.. _preview:

Preview
=======

What is preview?
----------------
The ``Preview`` process is a tool to help monitor from a **locally
running** job. There are two directives for ``Preview``

1) `Preview Import`_ -
   Import attaches files to a d3view simulation at a regular interval

2) `Preview Generate`_
   Generates a tsv file to look at the changing variable of the running
   job in a easily viewed format.

Requirements
------------

• Python 2.7 (Latest release of Python 2.7 can be found
  `here <https://www.python.org/downloads/>`_)
• Lucy
• Connection to d3VIEW

Configure preview
-----------------

Preview is configured by managing the d3view.json file in the
``${LUCY_HOME}/etc/config`` directory.

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 as follows::

 "preview": {
   "included_files": {
     "global": {
       "types": [
         "image",
         "curve"
       ],
       "extensions": [
         "txt",
         "log",
         "tsv"
       ]
     },
     "lsdyna": {
       "types": "dyna_d3plot"
     }
   }
 }

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'


Preview Import
**************

How to run
----------

The ``Preview`` tool is used by invoking ``Lucy``, and specifying the
arguments needed to monitor a job. The most basic command is as follows::

  $ lucy preview import ``<<USERNAME>>`` ``<<APPLICATION_NAME>>`` ``<<SOLVER_LOG_FILE>>`` -d3view-url http://d3VIEW-internal.com -a ``<<API_KEY>>``


:program:`lucy` :program:`preview` :program:`import`
:option:`import USERNAME`
:option:`import APPLICATION_NAME`
:option:`import SOLVER_LOG_FILE`
:option:`import -d3view-url` ``http://d3VIEW-internal.com``
:option:`import -a` ``<<API_KEY>>``

If you don't have a job.json file prepared, one will automatically be created
after running the command with the keyword arguments outlined below.

Import Arguments
----------------

``Preview`` comes with a number of arguments to allow flexibility when
sending data from different kinds of jobs.

All arguments are shown directly below, with links to their sections.

+----------------------------------------+----------------------------------+
| Parameter name                         | When required                    |
+========================================+==================================+
+----------------------------------------+----------------------------------+
| `Preview Import Positional arguments`_ |                                  |
+----------------------------------------+----------------------------------+
|:option:`import USERNAME`               | **Always required**              |
+----------------------------------------+----------------------------------+
|:option:`import APPLICATION_NAME`       | **Always required**              |
+----------------------------------------+----------------------------------+
|:option:`import SOLVER_LOG_FILE`        | **Always required**              |
+----------------------------------------+----------------------------------+
+----------------------------------------+----------------------------------+
| `Preview Import Connection arguments`_ |                                  |
+----------------------------------------+----------------------------------+
|:option:`import -d3view-url`            | **Always required**              |
+----------------------------------------+----------------------------------+
|:option:`import -d3view-port`           | **Always required**              |
+----------------------------------------+----------------------------------+
|:option:`import -a`,                    | **Always required**              |
|:option:`import -api-key`               |                                  |
+----------------------------------------+----------------------------------+
+----------------------------------------+----------------------------------+
| `Preview Import Simulation arguments`_ |                                  |
+----------------------------------------+----------------------------------+
|:option:`import -s`,                    |                                  |
|:option:`import -hpcserver-name`        |                                  |
+----------------------------------------+----------------------------------+
|:option:`import -project-id`            |                                  |
+----------------------------------------+----------------------------------+
|:option:`import -loadcase-name`         |                                  |
+----------------------------------------+----------------------------------+
|:option:`import -loadcase-id`           |                                  |
+----------------------------------------+----------------------------------+
|:option:`import -r`,                    |                                  |
|:option:`import -response-template`     |                                  |
+----------------------------------------+----------------------------------+
|:option:`import -n`,                    |                                  |
|:option:`import -name`,                 |                                  |
|:option:`import -job-name`              |                                  |
+----------------------------------------+----------------------------------+
|:option:`import -d`,                    |                                  |
|:option:`import -description`,          |                                  |
|:option:`import -job-desc`              |                                  |
+----------------------------------------+----------------------------------+
|:option:`import -vd`,                   |                                  |
|:option:`import -variable-definition`,  |                                  |
+----------------------------------------+----------------------------------+
+----------------------------------------+----------------------------------+
| `Preview Import Additional arguments`_ |                                  |
+----------------------------------------+----------------------------------+
|:option:`import -job-json`              |                                  |
+----------------------------------------+----------------------------------+
|:option:`import -job-id`                |                                  |
+----------------------------------------+----------------------------------+
|:option:`import -simulation-id`         |                                  |
+----------------------------------------+----------------------------------+

Preview Import Positional arguments
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

These arguments are required for the application to be able to run, and should
be specified in order.

.. program:: import

.. option:: USERNAME

   d3VIEW user name.

.. option:: APPLICATION_NAME

   Name of application/solver

.. option:: SOLVER_LOG_FILE

   Name of the log file the solver will write to. Used in
   generating preview.tsv.


Preview Import Connection arguments
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

These Arguments are required for the application to be able to log into d3VIEW.

.. option:: -d3view-url

   The url to d3VIEW. Such as ``http://d3VIEW-internal.com``
   (Note: do not include port number if shown, that is the next parameter.)

.. option:: -d3view-port

   The port to d3VIEW, if it is not 80, this should be set.

.. option:: -a, -api-key

   The `API Key`_ found in d3VIEW.

Preview Import Simulation arguments
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

.. option:: -s,  -hpcserver-name

   The name of the `HPC server`_ (in d3VIEW) that
   the simulation is going to be created on.

.. option:: -project-id

   The name of the d3VIEW project that the simulation should be part of.

.. option:: -loadcase-name

   The name of the d3VIEW loadcase that will be attached to the simulation.

.. option:: -loadcase-id

   The id of the loadcase in d3VIEW.

.. option:: -r,  -response-template

   The name of the response template to
   apply

.. option:: -n,  -name,  -job-name

   The name of the simulation. If set to ``'auto'``, ``Preview Import`` will
   name the simulation as a combination of the working directory and the
   parent directory.

   If the folder structure is::

     root
      ├ stage1
      │  ├ 1.1 (working directory)
      │  │  ├ main_input_file.k
      │  │  └ additional_input_file.key

   The simulation will be named stage1_1.1. This is especially useful for
   LS-OPT where multiple simulations will be submitted from the same LS-OPT
   job.

.. option:: -d,  -description,  -job-desc

   The description of the simulation

.. option:: -vd, -variable-definition

   Path to the variable definition file.

Preview Import Additional arguments
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

.. option:: -job-json

   This option allows loading all parameters from a job.json file
   instead of having a large command.

   The contents of the job.json file should look like::

     {
       "api_url": "<URL>",
       "api_port": "<PORT>",
       "username": "<USER_NAME>",
       "api_key": "<API_KEY>",
       "hpcserver_name": "<SERVER_NAME>",
       "solver_type": "<SOLVER_TYPE>",
       "response_template": "<RESPONSE_TEMPLATE>",
       "job_name": "<JOB_NAME>",
       "job_description": "<DESCRIPTION>",
     }

.. option:: -job-id

   The job id used to connect to an existing simulation.

.. option:: -simulation-id

   The simulation id used to connect to an existing
   simulation.

Preview Generate
****************


How to run
----------

The ``Generate`` directive is used by invoking ``Lucy``, and specifying the
arguments needed to generate a tsv. The most basic command is as follows::

  $ lucy preview generate ``<<APPLICATION_NAME>>``


:program:`lucy` :program:`preview` :program:`generate`
:option:`generate APPLICATION_NAME`

Generate Arguments
------------------

All arguments are shown directly below, with links to their sections.

+------------------------------------------+----------------------------------+
| Parameter name                           | When required                    |
+==========================================+==================================+
+------------------------------------------+----------------------------------+
| `Preview Generate Positional arguments`_ |                                  |
+------------------------------------------+----------------------------------+
|:option:`generate APPLICATION_NAME`       | **Always required**              |
+------------------------------------------+----------------------------------+
+------------------------------------------+----------------------------------+
| `Preview Generate Additional arguments`_ |                                  |
+------------------------------------------+----------------------------------+
|:option:`generate -solver-log-file`       |                                  |
+------------------------------------------+----------------------------------+

Preview Generate Positional arguments
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

These arguments are required for the application to be able to run, and should
be specified in order.

.. program:: generate

.. option:: APPLICATION_NAME

   Name of application/solver


Preview Generate Additional arguments
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

These Arguments are required for the application to be able to log into d3VIEW.

.. option:: -solver-log-file

   Name of the log file the solver will write to. Used in
   generating preview.tsv.