5. Simulaton Results Plugins

5. Simulaton Results Plugins
	Chapter 5. Plugin Reference

Simulation Results plugins handle the management and presentation of simulation results - both realtime and post-simulation.

5.1. MeasurementSetToFile

This plugin periodically outputs the MeasurementSet contents to a file. That file can then be used to generate graphs, or as data to perform other calculations. The first line in the file comprises column titles, the subsequent lines comprise the data.

5.1.1. Configuration

The following is an example of how to configure the MeasurementSetToFile plugin in the simulation specification file.

  ...
  <parameter name="baseDirectory" value="c:/NanoHive-1" />
  ...
  <simulationFlow ...
    ...
    <result name="MeasurementSetToFile" plugin="MeasurementSetToFile">
      <parameter name="outputInterval" value="20" />
      <parameter name="outputFile"
                 value="examples/nanotube-5x5/results/data.txt" />
      <parameter name="datumSeparator" value="\t" />
    </result>

Table 5.9. MeasurementSetToFile Configuration Parameters

Parameter	Description
`outputInterval`	How often to output the MeasurementSet contents. Output occurs when the iteration number modulus `outputInterval` is zero. Set it to 1 to output at every iteration and set it to 5 to output at every fifth iteration, for example.
`outputFile`	The file to write to.
`datumSeparator`	What to separate each number with. This is usually either a comma (,), or the tab character (\t).

5.2. NetCDF_DataSet

NetCDF (network Common Data Form) is a file format for array-oriented data access. See Unidata NetCDF for more information. This plugin generates a netCDF dataset file during simulation. The dataset file is opened in "share" mode, so it can be read while it is being written to.

5.2.1. Configuration

The following is an example of how to configure the MeasurementSetToFile plugin in the simulation specification file.

  ...
  <parameter name="baseDirectory" value="c:/NanoHive-1" />
  ...
  <simulationFlow ...
    ...
    <result name="NetCDF_DataSet" plugin="NetCDF_DataSet">
      <parameter name="outputInterval" value="1" />
      <parameter name="outputDirectory" value="c:/results/benzene" />
      <parameter name="maxDataSets" value="3" />
    </result>

Table 5.10. NetCDF_DataSet Configuration Parameters

Parameter	Description
`outputInterval`	The netCDF dataset is appended with the simulation space state every `outputInterval` iteration(s). For example, if outputInterval is set to 5, the dataset is appended every 5 iterations.
`outputDirectory`	This specifies the directory in which to place the dataset file. Every NanoHive-1 simulation run has a serial number which is stored in the simulation's lastRunSerial property. The full path/filename of a dataset file is: <plugin.outputDirectory>/<simulation.lastRunSerial>.nc
`maxDataSets`	This specifies how many dataset files to keep in the directory. For example, if maxDataSets is set to 3, when the 4th dataset is opened, the 1st one is deleted. The default is -1, which means no datasets will be culled.

The following is the Common Definition Language (CDL) description of the dataset schema.

netcdf simulationResults {
dimensions:
  atomId = 10,
  bondId = 10,
  espCell = 100,
  time = unlimited;

variables:
  int atomId(atomId);
  float x(time, atomId);
    x:long_name             = "x-axis position";
    x:units                 = "A";
  float y(time, atomId);
    y:long_name             = "y-axis position";
    y:units                 = "A";
  float z(time, atomId);
    z:long_name             = "z-axis position";
    z:units                 = "A";
  int type(time, atomId);
    type:units              = "atomic number";
  int a(time, bondId);
    a:units                 = "from atomId";
  int b(time, bondId);
    b:units                 = "to atomId";
  float time(time);
    time:long_name          = "elapsed time";
    time:units              = "s";
  float temperature(time);
    temperature:long_name   = "ideal temperature";
    temperature:units       = "K";
    temperature:thermostat  = 300.0;
  float totalEnergy(time);
    totalEnergy:units       = "J";
  float rectangularESP(time, espCell);
    rectangularESP:long_name= "electrostatic potential";
    rectangularESP:units    = "kJ/mol";
    rectangularESP:sizeX    = 10;
    rectangularESP:sizeY    = 10;
    rectangularESP:sizeZ    = 1;
    rectangularESP:centerX  = 0.0;
    rectangularESP:centerY  = 0.0;
    rectangularESP:centerZ  = 0.0;
    rectangularESP:normalX  = 0.0;
    rectangularESP:normalY  = 1.0;
    rectangularESP:normalZ  = 0.0;
    rectangularESP:lengthX  = 1.0e-9;
    rectangularESP:lengthY  = 1.0e-9;
    rectangularESP:lengthZ  = 0.0;
}

5.3. POVRayVideo

This plugin outputs POV-Ray scene description files which can be rendered, then encoded as frames in an MPEG video. The following tools are used to create the video from the scene description files:

POV-Ray is a high-quality, totally free tool for creating high resolution 3D graphics. Download this from http://www.povray.org/
POVRayDataLayer is included with the plugin. It augments each frame with a title, MeasurementSet information, and a logo.
mpeg_encode encodes the POV-Ray output (images) into the final video. BuckoSoft's version with PNG support is included with the plugin for Windows distributions, and the original Berkeley version is included for Unix distributions.

The POVRayVideo plugin uses the following 3rd party libraries and code.

Table 5.11. 3rd Party Libraries and Code Used by POVRayVideo

Library/Code	License
GD Graphics Library (POVRayVideo plugin system)	Permission granted to copy, distribute and modify in any context. See Appendix for the GD License.
The Berkeley MPEG Encoder and BuckoSoft's version with PNG support (POVRayVideo plugin system)	Permission granted to use, copy, modify, and distribute. See Appendix for the MPEG_ENCODE License.

5.3.1. Configuration

The following is an example of how to configure the POVRayVideo plugin in the simulation specification file.

  ...
  <parameter name="baseDirectory" value="c:/NanoHive-1" />
  ...
  <simulationFlow ...
    ...
    <result name="POVRayVideo" plugin="POVRayVideo">
      <parameter name="outputInterval" value="20" />
      <parameter name="lengthMultiplier" value="1e10" />
      <parameter name="outputDirectory"
	             value="examples/nanotube-5x5/results" />
      <parameter name="outputIdentifier" value="cnt55" />
      <parameter name="povTemplateFilename"
                 value="examples-beta/nanotube-5x5/cnt55-pov.tmplt" />
      <parameter name="mpegTemplateFilename"
                 value="data/mpeg_encode.param.tmplt" />
    </result>

Table 5.12. POVRayVideo Configuration Parameters

Parameter	Description
`outputInterval`	How often to output scene descriptions. Output occurs when the iteration number modulus `outputInterval` is zero. Set it to 1 to output at every iteration and set it to 5 to output at every fifth iteration, for example.
`lengthMultiplier`	What to multiply coordinate values by. Molecular coordinate vectors are near the order of 10^-10 (m); this parameter is used to scale those coordinates so that they are visible. For small molecular systems of less than 10,000 atoms, a value of 1e10 (10¹⁰) should be ok.
`outputDirectory`	Where to write the scene description files.
`outputIdentifier`	This is a short string that will be used as the root of scene description filenames.
`povTemplateFilename`	The template to use for scene description files. The supplied template (in the `data` directory) can usually be used without modification.
`mpegTemplateFilename`	The template to use for the MPEG encoding encoding tool (mpeg_encode). The supplied template (in the `data` directory) can usually be used without modification.

5.3.2. Include and Macro Files

The povTemplateFilename parameter points to a template file used to create every scene file. The one included with NanoHive-1 looks like the following:

  #include "NH-POV-Ray-general.inc"
  #include "../POV-Ray.inc"

  Setup()

  !!moleculeData!!

The first file it includes is a general utility file, NH-POV-Ray-general.inc, which contains atom representation data (radius, van der Waals radius, color), and the DrawAtom, DrawBond, and DrawDF3_Plane macros.

The second file, ../POV-Ray.inc, is a per simulation customization file where you can specify scene translation, rotation, model representation, lighting, cameras, ESP plane color maps, and over-ride the DrawBall (used by the DrawAtom macro) and DrawBond macros. A template for this file (NH-POV-Ray-custom.inc) is in the include directory.

After the includes, it calls the Setup macro (defined in ../POV-Ray.inc). The !!moleculeData!! item will be populated with calls to the DrawAtom, DrawBond, and DrawDF3_Plane macros.

5.3.3. Example Usage: Hydrogen Abstraction Video

In the following example, we walk-through the steps involved in creating a video of a hydrogen abstraction from a diamond molecule. Here is the final result [MPEG] 1.63 Mb

In general, the steps involved comprise:

Configuration of the POVRayVideo plugin
Simulation of the hydrogen abstraction
Creation of the video

Note

This tutorial assumes:

a basic knowledge of how to run NanoHive-1
that you have the POVRayVideo plugin installed
that you have POV-Ray installed and know basically how to render .pov scene description files
(for Unix only) that you have mpeg_encode installed
(for Unix only) that you have a .png to .pnm file conversion utility installed such as pngtopnm

1. Plugin Configuration

All the necessary files are in the examples/hydrogen-abstraction directory. Edit the hydrogen-abstraction-sim.xml simulation specification file. Note the POVRayVideo.outputInterval parameter. A setting of 25 for 6600 iterations will yield 264 frames of video - about 10 seconds worth.
Open the pov-file.tmplt file - the template scene description file. The !!moleculeData!! item will be populated with the atom and bond data and the result copied to the results directory. Leave this file as it is.
Open the POV-Ray.inc file. (This file is #included by the pov-file.tmplt file.) This file is used to configure various aspects of the output images such as colors and size for atoms. Leave this file as it is - we'll return to it later.
When creating new simulation videos, you can either re-use this file, or make a copy of the include/NH-POV-Ray-custom.inc.tmplt file and edit that to your needs.

2. Simulation

Start NanoHive-1 and run the simulation with the following commands (or use HiveKeeper):

Windows

  > load simulation -f "C:\Program Files\NanoHive-1\examples\hydrogen-abstraction\hydrogen-abstraction-sim.xml" -n ha
  > run ha

Unix - assuming you're in the directory where you ran the install-examples script:

  > load simulation -f NanoHive-1/examples/hydrogen-abstraction/hydrogen-abstraction-sim.xml -n ha
  > run ha

You can check the progress of the simulation with: status ha

3. Video Creation

Once the simulation is finished, the hydrogen-abstraction/results directory will have 264 hyd-abs.0NNN.pov files. We'll first render one of them to validate and fine tune our POV-Ray settings.
Note
POV-Ray needs to have the NH-POV-Ray-general.inc file in its include path.
- Windows - add the following entry to the end of POV-Ray's POVRAY.INI file. (Tools | Edit master POVRAY.INI): Library_Path=C:\Program Files\NanoHive-1\include
- Unix - add +L/usr/local/share/NanoHive-1/include to any povray commands
Pick one of the files, hyd-abs.0010.pov, for example, and render it. You'll get something like the following:

Move the molecules over so that they're more centered by changing the Translate value in the POV-Ray.inc file to <5, 0, 0> from <0, 0, 0>, save, and re-render the file. It should look something like the following:
Now that we like the layout of the images we can render all the images.
1. Use the following POV-Ray options: -D -GA +W640 +H480 +A +FN
2. Windows - use the render queue (Render | File Queue...) to queue up all 264 files and let 'er rip. On an 800 MHz Pentium machine with 512 Mb RAM it took about 12 minutes to render all the files.
3. Unix - run the following command in the results directory: for file in *.pov; do povray +L/usr/local/share/NanoHive-1/include +I$file -D -GA +W640 +H480 +A +FN; done
This next step augments each image with a title, MeasurementSet information, and a logo, then creates the final results/hyd-abs.mpg video.
- Windows - open a command line, go to the C:\Program Files\NanoHive-1\bin\win32-x86 directory, and run
```
  pv ..\..\examples\hydrogen-abstraction\results\hyd-abs "HYDROGEN ABSTRACTION"
```
- Unix
  1. Edit the results/hyd-abs.mpeg.param file. Change the BASE_FILE_FORMAT to PNM, and add the pngtopnm program (or some other .png to .pnm conversion program) to the INPUT_CONVERT directive to convert the .png images to .pnm images. This is required by the mpeg_encode program. For example:
    ... BASE_FILE_FORMAT PNM INPUT_CONVERT /usr/bin/pngtopnm * ...
  2. From the /results directory run:
    /usr/local/share/NanoHive-1/scripts/pv hyd-abs "HYDROGEN ABSTRACTION"
Data augmentation took about two minutes on the same machine, and encoding the MPEG video took about one minute.
Here is an example of one of the data augmented files (slightly shrunken)

The final result will be hydrogen-abstraction/results/hyd-abs.mpg and look something like this one: [MPEG] 1.63 Mb.
It's possible that your hydrogen didn't get abstracted - don't take it personally, try dropping the tool down lower. The simulation is non-deterministic and the tool design doesn't account for much reactive margin. Here's a <path> for the tool to replace the one in the hydrogen-abstraction-sim.xml file that drops the tool down lower:
```
  <path name="toolPath">
    <interval start="0" end="180e-15">
      <velocity fixed="true" />
    </interval>
    <interval start="180e-15" end="2645e-15">
      <velocity componentsXYZ="0 -0.02e4 0" />
    </interval>
    <interval start="2645e-15" end="2880e-15">
      <velocity fixed="true" />
    </interval>
    <interval start="2880e-15" end="3300e-15">
      <velocity componentsXYZ="0 0.02e4 0" />
    </interval>
  </path>
```
Note
You can change the logo in the image by changing the -l ..displayDataLogo.png option in the POVRayDataLayer command in the pv script to point to your logo.

5.3.4. Frequently Asked Questions (FAQ)

5.3.4.1. (Unix) When I add the +L/usr/local/share/NanoHive-1/include to my povray commands, it says, #include "NH-POV-Ray-general.inc" Parse Error: Reading from '/usr/local/share/NanoHive-1/include/NH-POV-Ray-general.inc' is not permitted. Check the configuration in '/usr/local/etc/povray/3.6/povray.conf'.

5.3.4.1.

(Unix) When I add the +L/usr/local/share/NanoHive-1/include to my povray commands, it says,

  #include "NH-POV-Ray-general.inc"
  Parse Error: Reading from
  '/usr/local/share/NanoHive-1/include/NH-POV-Ray-general.inc'
  is not permitted.  Check the configuration in
  '/usr/local/etc/povray/3.6/povray.conf'.

If you can edit the povray.conf file mentioned in the error, add

  read* = /usr/local/share/NanoHive-1/include

to the end of it. This will allow you to include the NH-POV-Ray-general.inc file from any directory. Alternatively, you can simply copy the NH-POV-Ray-general.inc file to the directory from which you are issuing the povray commands, and it should work fine as well.


4. Entity Management Plugins		6. Data Import/Export Plugins

Documentation