.. _preview_setup:

Preview
=======

In the distribution a source file named ``import_preview.sh`` exists to
provide a hook to call preview.

Add preview to run script
~~~~~~~~~~~~~~~~~~~~~~~~~

The default import_preview can be called as follows::

  $ import_preview.sh $USERNAME $APPLICATION_NAME $LOG_FILE_NAME &

``USERNAME`` - the d3VIEW username that is running the simulation
``APPLICATION_NAME`` - the name of the simulation application, e.g. starccm
``LOG_FILE_NAME`` - the output file which preview data will be gathered, in
the example of starccm, this would be the name of the
output file, in lsdyna this is the name of the d3hsp

To add preview to an existing run script, simply call preview using the
3 parameters prior to starting the simulation.

  Example run script would look as follows:

  Before adding preview ::

    lsdyna -inf $SOLVER_INPUT_FILE -o $SOLVER_ARGS

  After adding preview ::

    import_preview.sh $USERNAME lsdyna

    lsdyna -inf $SOLVER_INPUT_FILE -o $SOLVER_ARGS

Configure preview
~~~~~~~~~~~~~~~~~

Preview is configured by managing two files in the
``${D3VIEW_HOME}/etc/config`` directory.

1) The ``d3view.json`` file can be modified to change which files will be
   uploaded to d3VIEW from the compute node. To change this modify the section
   titled ``"preview":``. By default the section looks similar to the
   following::

     "preview": {
       "short_interval": 30,
       "long_interval": 600,
       "short_files": {
         "global": {
           "types": [
             "image",
             "curve"
           ],
           "extensions": [
             "txt",
             "tsv",
             "log"
           ]
         },
         "lsdyna": {
           "types": [
             "*d3hsp",
             "status.out",
             "glstat"
           ],
           "extensions": [
             "d3hsp",
             "status.out",
             "glstat"
           ]
         }
       },
       "long_files": {
         "global": {
           "types": [
             "image",
             "curve"
           ],
           "extensions": [
             "txt",
             "log",
             "tsv"
           ]
         },
         "lsdyna": {
           "post_script": "",
           "types": [
             "*lsppdb",
             "dyna_binout",
           ],
           "extensions": [
             "lsppdb",
             "dyna_binout"
           ]
         }
       },
       "post_script": ""
     }


   The included files section lists all included files by type or by
   extension. To add a solver type, add a new tag under ``included_files``.
   This tag should match the name of the solver.

   The ``global`` tag affects all solvers.

   ``types`` are specified as mimetypes, which are also defined in the
   ``d3view.json`` file.

   ``extensions`` are specified as file extensions, the part of the filename
   that comes after the last '.' for example 'txt' in 'solver_1.txt'

2) The ``user_api_keys.json`` is a site specific json file that must be created
   after installation. This stores which users (by name) are allowed to use
   `preview`_ and `publishing`_. An example file is included in the
   installation named ``user_api_keys.json.in``. The file can be renamed and
   edited using an editor such as ``vim`` and must have the following format::

     {
       "example_user": "e4d0b71d5a0a80c11ce890919edcb1ef972c06b1",
       "<user_id>": "<user_api_key>",
       "<user_id_2>": "<user_api_key_2>"
     }

   Each user's api key can be found by logging into d3VIEW, and clicking on the
   name button found in the top right of the screen, just to the left of
   logout.

   Copy the ``User Name`` and ``API Key`` directly from d3VIEW into the
   ``user_api_keys.json`` file.

   .. note::
     Please assure that the file is in `proper json format <http://www.json.org/>`_.