Documentation

Simulation workflow scripts tell the simulator how to process the simulation. The scripting language is TCL (here's a quick tutorial.) Here is an example workflow script that imports all the input entities from a list, performs the simulation - outputing intermediate results - then outputs the final results and writes the final state of the simulation space to a file.

  foreach inputEntity $inputEntityList {
    NH_Import $inputEntity
  }

  set maxIterations [expr $startIteration + $iterations]
  for {set iteration $startIteration} {$iteration < $maxIterations} {incr iteration} {
    NH_Intermediate $iteration $simResult
	
    NH_Prepare $iteration $traverser
    NH_Calculate $iteration $physicalInteraction $traverser
  }

  NH_Final $simResult
  NH_Export $outputEntity

The functions NH_Import, NH_Intermediate, NH_Prepare, NH_Calculate, NH_Final, and NH_Export control the simulator. They are described below.

The symbols inputEntityList, startIteration, iterations, maxIterations, simResult, traverser, physicalInteraction, and outputEntity are all defined in a Simulation Specification (sim-spec) file, discussed in the next section.

The workflow functions that control the simulator are summarized in the following table.

  set maxIterations [expr $startIteration + $iterations]
  for {set iteration $startIteration} {$iteration < $maxIterations} {incr iteration} {
    NH_Prepare $iteration $traverser
    NH_Calculate $iteration $physicalInteraction $traverser
    set filename [format "out.%04d.xyz" $iteration]
    NH_Export $outputEntity $filename
  }

All the parameters to the functions, except for the <iteration>, are passed into the script variable space from the Simulation Specification (sim-spec.)

The Simulation Specification (sim-spec) determines all the particulars of a simulation such as the input files, traverser plugins, calculator plugins, result plugins, and output files. The sim-spec is expressed in XML, and its entities can be passed into the simulation workflow functions described in the previous section.

This schema shows the list of entities in the sim-spec - all of the parameters for the simulation workflow functions listed above are described there. The top-level entity is the <simulation> entity.

The schema .xsd file is in the appendix (see Appendix for Simulation Specifications Schema) and also available here: simulation-1.0.1.xsd.

Here is an example sim-spec followed by an explanation:

  <simulation>
    <description>Carbon nanotube simulation.</description>

    <parameter name="timeQuantumLength" value="5e-16" />
    <parameter name="environmentTemperature" value="300" />
    <parameter name="startIteration" value="0" />
    <parameter name="iterations" value="1000" />

    <simulationFlow file="simflow.tcl">
      <list name="inputEntityList">
        <input type="nanoML" file="cnt55.nml" />
      </list>

      <output name="outputEntity" type="nanoML" file="cnt55-out.nml" />

      <traverser name="traverser" plugin="RC_Traverser" />
 
      <calculator name="physicalInteraction" plugin="AIREBO">
        <parameter name="deltaTbyTau" value="1.0" />
      </calculator>

      <result name="simResult1" plugin="MeasurementSetToFile">
        <parameter name="outputInterval" value="20" />
        <parameter name="outputFile" value="results.txt" />
        <parameter name="datumSeparator" value="\t" />
      </result>
    </simulationFlow>
  </simulation>

The <description> is simply a description of the simulation. The plugins have access to this description and, for example, the MeasurementSetToFile plugin can be configured to output it along with the results.

The <parameter> key/value pairs are simulation parameters; they are passed into the workflow script variable space. The following table describes the standard top-level simulation parameters, but you can add additional parameters as necessary for your workflow script.

The <simulationFlow> block enumerates additional symbols available to the simulation's workflow script; especially for passing to the workflow functions. See a description of the <simulationFlow> entity in the specification schema.