= VAPOR =

VAPOR is the Visualization and Analysis Platform for Ocean, Atmosphere, and Solar Researchers. VAPOR provides an interactive 3D visualization environment that runs on most UNIX and Windows systems equipped with modern 3D graphics cards. It has been developed by [[http://ncar.ucar.edu|NCAR]] and is freely available at [http://www.vapor.ucar.edu].\\
\\
An official UI reference manual is available [[http://www.vapor.ucar.edu/docs/reference/UIRef/ReferenceManual.pdf|here]]. Please find also a small tutorial in german language attached to this page [[attachment:2010_5_vapor.pdf|here]].

== System requirements ==
The official VAPOR FAQ say:

* // We recommend a minimum of 512 MBs of main memory. VAPOR relies heavily on RAM for caching data in order to improve performance. So the more memory you have, the better the performance, in general.This is particularly true when animating through temporal data.//

* // A graphics card with 3D hardware texture support and an OpenGL driver that can take advantage of the card are a must. Note that standard Linux distributions come with a generic driver that will work on all systems, but this will usually not give adequate performance. For best performance a driver provided by the graphics card vendor is essential. If you plan to use Linux and have not yet purchased a graphics card, you should check that the card you are considering purchasing has a driver optimized for Linux.//


== Conversion of NetCDF to VDF data ==
VAPOR has its own mechanism for storing field data and its associated attributes (metadata). The components of a VAPOR Data Collection (VDC) are distributed across different disk files. All metadata for a VDC are stored in a single .vdf file. See [[http://www.vapor.ucar.edu/docs/vapor-data-preparation/vapor-data-preparation|here]] for more information.\\
\\
For the conversion of NetCDF data output from PALM to the VAPOR format, the tool nc2vdf has been developed at IMUK. It is based on NCL and available from r1046. In order to use the tool on any remote host, the PALM utility programs must be recompiled ({{{mbuild -u -h ...}}}).\\
\\
nc2vdf collects a list of parameters and uses the command line tools vdfcreate and ncdf2vdf, that come with VAPOR, to create the metadata file and populate the data collection automatically with all variables and time steps chosen by the user.\\
The tool can be used in two ways, an interactive command line prompt asking for all necessary information and a non interactive batch mode reading all input parameters from a configuration file. The batch mode may be preferred for converting large data sets and can be used as a batch job at HLRN (so far only hicegate2 and bicegate2 are allowed). For large batch jobs that would exceed the wallclock time limit of the shell, you might want to submit a batch job (currently only possible on the UV systems).\\ 
\\
=== Starting the conversion ===
The conversion can be started interactively, as local batch job at IMUK/HLRN or as batch job at UV. To use nc2vdf on your own workstation with VAPOR installed (Linux or Mac systems), you may edit the appropriate lines in the configuration file {{{nc2vdf.config}}}). The following instructions have to been executed in the directory where the data reside.

==== Interactive mode at IMUK/HLRN ====
Simply type\\\\
{{{nc2vdf}}}\\\\
and the script will guide you trough the conversion.

==== Batch mode at IMUK/HLRN ====
Provide a configuration file (usually {{{nc2vdf.config}}}). An example configuration file can be found in the folder {{{trunk/SCRIPTS/}}}. The configuration uses NCL syntax. Please see the instructions and comments in the example file for more information. Run the script as follows:\\\\
{{{nc2vdf ./anypath/nc2vdf.config}}}

==== Batch mode on other workstations ====
Since r1110, you can easily use nc2vdf on other systems than HLRN/IMUK. Therefore you need to adapt the appropriate block of the configuration file {{{nc2vdf.config}}} to your machine. Please see the instructions in the example file. Run the script as described above.

==== Batch mode on UV at HLRN ====
For submitting a batch job to the UV system, a job script is required. Please find a default job script in {{{trunk/SCRIPTS/batch_nc2vdfcat}}}. The script should be copied to the directory where your data resides. Change into this directory and submit the job as follows:\\\\
{{{msub batch_nc2vdfcat}}}

== Starting VAPOR at IMUK ==
VAPOR (version 2.2.0) is installed on the Linux server at IMUK and can be started from the terminal:

{{{. /muksoft/packages/vapor/2.2.0/bin/vapor-setup.sh; vaporgui&}}}.

The VAPOR window will appear. In case your graphics card (or your graphics card driver) is inappropriate, you might experience error message when rendering 3D data.

== Recommended User preferences & advices ==
* The user preferences can be opend from the "Edit" menu. We recommend to set the following settings:

  * '''Cache Size (Megabytes)''': depending on your RAM, allow VAPOR to block 70-80% of your total RAM.
  * '''Specify graphics texture size''': We suppose that the performance of VAPOR can be improved by setting a value for the texture size. However, currently we do not have no suggestions for an appropiate value.

* '''Save your work regularly! ''' Use the "Save Session" option to save your visualizer settings to file. Our experience is that VAPOR tends to crash from time to time and you will lose all your settings. Saving your settings allows you not only to restore your last session (you just need to load the data manually), but it also allows to visualize several datasets with the same visualizer settings.

* '''Play! ''' There are unlimited possibilies of presenting your data. Try out different approaches for visualizing interesting features of your simulated flow. Toy around with the lighting setup, transparency, viewing angles etc..

* '''Flow Renderer:''' Be careful when using "Field line advection". This type is used to show trajectories of your flow field, but it requires enormous computational time (which can make VAPOR crash). Make sure that "Auto-refresh flow" is disabled and you know what you are doing. It is also a good idea to save your session before using the flow renderer.