Documentation: Command Line Interface

MolflowCLI Documentation

  __  __     _  __ _
 |  \/  |___| |/ _| |_____ __ __
 | |\/| / _ \ |  _| / _ \ V  V /
 |_|  |_\___/_|_| |_\___/\_/\_/

Abstract

The MolflowCLI gives Molflow users another useful tool that lets them run simulations without the graphical user interface. Simulations can thus be run on headless servers, such as computing clusters. CLI arguments give users the flexibility to change simulation parameters on demand, e.g. when using scripts.

Changelog

2023/01/10: Updated example scripts, added batch file
2022/04/14: Added "auto" command
2021/11/09: Added "Additional output" section for new 2.9.1 arguments
2021/09/29: Initial publication

MolflowCLI Documentation

Commands

A list of commands can be fetched by starting the application with the -h or --help argument:

  -h,--help                   Print this help message and exit
  -j,--threads UINT           # Threads to be deployed
  -t,--time UINT              Simulation duration in seconds
  -d,--ndes FLOAT ...         Desorption limit for simulation end
  -f,--file TEXT:FILE REQUIRED
                              Required input file (XML only)
  -o,--output TEXT Excludes: --overwrite
                              Output file name (e.g. 'outfile.xml', defaults to 'out_{inputFileName}'
  --outputPath TEXT Excludes: --overwrite
                              Output path, defaults to 'Results_{date}'
  -s,--outputDuration UINT    Seconds between each stat output if not zero
  -a,--autosaveDuration UINT  Seconds for autoSave if not zero
  --setParamsByFile TEXT:FILE Parameter file for ad hoc change of the given geometry parameters
  --setParams TEXT ...        Direct parameter input for ad hoc change of the given geometry parameters
  --verbosity INT             Restrict console output to different levels
  --loadAutosave              Whether autoSave_ file should be used if exists
  -r,--reset                  Resets simulation status loaded from file
  --verbose                   Verbose console output (all levels)
  --overwrite Excludes: --output --outputPath
                              Overwrite input file with new results
  --writeFacetDetails         Will write a CSV file containing all facet details including physical quantities
  --writeFacetQuantities      Will write a CSV file containing all physical quantities for each facet
  --config                    Read an ini file

  --auto                      Use auto generated test case

Examples

MolflowCLI has been developed for Linux, MacOS and Windows operating systems. The provided examples should work for most Unix shells and for Powershell on Windows. If the path to the molflowCLI binary is not set with an environment variable, the application usually has to be appended with ./ to note, which is the relative path to the current directory (assuming the binary directory and the working directory are equal).

Note: As a minimal starting configuration molflowCLI needs the following arguments:

input file --file {file_name} (see Input / Output)

end condition -t or -d (see Simulation settings)

To give working examples, by default the configuration --file inputFile.xml -t 1000 will be used.

Input / Output

The MolflowCLI's main purpose is the launch of simulations with geometries that have been prepared with the Molflow GUI. The CLI application can start simulations from either .xml or .zip files. The file can be given with the argument --file {file_name}, where file_name can also be a relative or an absolute path to a file.

Input file from working directory

./molflowCLI --file inputFile.xml -t 1000

Input file from relative path

./molflowCLI --file geometries/inputFile.xml -t 1000

Input file from absolute path

./molflowCLI --file /usr/molflow/inputFile.xml -t 1000

By default the input file will not be overwritten with the results. Instead another output file will be generated in a directory inside the binary path labeled as Results_{date_time}.

./molflowCLI --file inputFile.xml --overwrite -t 1000

will instead write the simulation results to the given input file.

./molflowCLI --file inputFile.xml -o outputFile.xml  --outputPath . -t 1000

will generate an output file directly in the binary path. The path can also be deduced by giving a path with the output file name:

./molflowCLI --file inputFile.xml -o ./outputFile.xml -t 1000

is redudant with the previous example.

[From 2.9.4]

An automatically generated test case can be used as a test case with --auto:

./molflowCLI --auto -o ./auto_prism.xml -t 1000

In 2.9.4 the auto generated test case is always a pipe tilted by an angle (an oblique prism) of 10 degrees with a L/R ratio of 10.

Additional output

[From 2.9.1]

To export a list of various details and converted physical quantities for each facet, the CLI provides the following possibilities:

./molflowCLI --file inputFile.xml -t 1000 --writeFacetDetails

This will create a list and write them to a CSV file facet_details.csv covering all possible values, which are the following:

* Facet ID [\#]
* Sticking
* Opacity
* Structure
* Link
* Desorption
* Reflection
* 2 Sided
* Vertex
* Area
* Temperature (K)
* Facet 2D Box
* Texture (u,v)
* Mesh sample/cm
* Count
* Memory
* Planarity
* Profile
* Imping.rate
* Density [1/m3]
* Density [kg/m3]
* Pressure [mbar]
* Av.mol.speed[m/s]
* MC Hits
* Equiv.hits
* Des.
* Equiv.abs.

With

./molflowCLI --file inputFile.xml -t 1000 --writeFacetQuantities

only converted physical quantities are written to a CSV file facet_physics.csv:

* Facet ID [\#]
* Imping.rate
* Density [1/m3]
* Density [kg/m3]
* Pressure [mbar]
* Av.mol.speed[m/s]

Autosave

Since CLI simulations are usually setup for longer durations, an autosave should be created frequently. By default an autosave file will be created every 10 minutes. This duration can be changed, e.g. to every 5 minutes (given as 300 seconds):

--autosaveDuration 300 -t 1000

If an autosave file exists, it will be loaded when --loadAutosave is given as an argument. The application will check for a file with the prefix autosave_ in the working directory.

Simulation settings

For simulations with the CLI an end condition needs to be set. Currently this can be time specific, e.g. to launch a simulation for 60 seconds:

./molflowCLI --file inputFile.xml -t 60

or a maximal number of traced particles (number of desorptions) can be used, e.g. to launch a simulation with 100,000 particles:

./molflowCLI --file inputFile.xml -d 1e5

A list of desorption limits can be given, which will create intermediary output files for each reached limit, e.g. to launch a simulation with 1E5, 1E6 and then 1E7 particles:

./molflowCLI --file inputFile.xml -d 1e5 1e6 1e7

If a file already has results from a previous simulation saved, these results can be reset with --reset , e.g.:

./molflowCLI --file inputFile.xml --reset -t 1000

the reset will not automatically apply to the input file.

If necessary, the amount of CPU cores/threads that shall be deployed can be regulated with --threads , e.g. for a limit of 8 CPU cores:

./molflowCLI --file inputFile.xml --threads 8 -t 1000

The CLI application allows the user to change several geometry and simulation parameters either with argument(s) or by reading a file where each line is a parameter change.

The following facet parameters can be changed:

outgassing: Facet outgassing in (mbar*l/s)
specificOutgassing: Facet area-wise outgassing in (mbar*l/s/cm2) - from Molflow 2.9.19+
sticking: Sticking coefficient [0..1]
opacity: Facet opacity [0..1]
temperature: Facet temperature in (K)

The following simulation parameters can be changed:

mass: particle mass in (g/mol)
enableDecay: particle decay 0=off,1=on
halfLife: half life in (s)

Individual parameter changes are given in the form

facet.{facet_index|range_of_indices|"selection_group"}.{parameter} = {value}

simulation.{parameter} = {value}

See examples just a bit further on.

Change(s) can also given directly as a CLI argument:

./molflowCLI --file inputFile.xml --setParams facet.2.outgassing=10.0 facet.42.sticking=1.0 -t 1000

To avoid passing very long lists as arguments, parameter changes can be saved inside a file (here paramsweep.txt):

./molflowCLI --file inputFile.xml --setParamsByFile 'paramsweep.cfg' -t 1000

For example the following paramsweep.cfg file:

facet.2.outgassing = 10.0
facet.42.sticking = 1.0
facet.10-15.opacity = 0.5
facet."wall".temperature=290.92
simulation.mass = 2.0
simulation.enableDecay = 1
simulation.halfLife = 42.42

would change...

the outgassing on facet #2
the sticking on facet #42
the opacity on facets #10 to #15
the temperature for the selection group called "wall"

For the simulation...

the general particle mass will be modified
particle decay will be activated with the given particle half life.

See example scripts for automatic sweeps through a range of values.

Terminal log

To keep track of the simulation state in certain frequencies, an output about various statistics can be printed to the terminal every few seconds, e.g.

./molflowCLI --file inputFile.xml -s 10 -t 1000

will give an output every 10 seconds in the form

Node#  Time           #Hits (run)          #Hits (total)        Hit/sec              #Des (run)           #Des (total)         Des/sec             
--------------------------------------------------------------------------------------------------------------------------------------------
0      10.02          40757977             2034302298           4067226.30           1990655              3990655              198646.87           
0      20.05          97010273             2090554594           4838832.30           4737142              6737142              236286.68           
0      30.08          160969458            2154513779           5351621.66           7849474              9849474              260965.13           
0      40.11          222523417            2216067738           5547208.36           10854042             12854042             270576.61

Various details are printed when running the application, the verbosity of these outputs can be restricted with --verbosity {level}, where level=0 means minimal output. Maximal output can be activated with the argument --verbose. The default is level=2. Some examples of what is printed with certain verbosity levels:

Level
0	Error messages
1	Initialisation log	Simulation stats
2	Write/load progress	Higher load verbosity	Autosave notifaction
3	Parameter change details	Higher load verbosity
4	Simulation settings	Acceleration Data Structure statistics	(Dev) MPI log
5	(Dev) More verbose MPI log

Config file

To reduce the argument list or e.g. to create a default set of arguments that saves you typing, a configuration file containing the arguments can be loaded with --config [config_file], e.g. a simulation can be started with

./molflowCLI --config default.ini

The extension can be anything, not just '.ini'. Please note that the config file doesn't persistently change molflowCLI - all it does is it adds the arguments it finds in the file, saving you typing. For beginners, it is not recommended to use config files.

An example config file is given as follows:

; Molflow+/Synrad+ Simulation Management
; Lines starting with semicolons are comments

; Simulation duration in seconds
time=900

; Desorption limit for simulation end
ndes=1e6 1e7

; Input file (XML/ZIP only)
file="inputFile.xml"

; Output file name (e.g. 'outfile.xml', defaults to 'out_{inputFileName}'
output="output.xml"

; Output path, defaults to 'Results_{date}'
outputPath="tmp"

; Seconds between each stat output if not zero
outputDuration=10

; Seconds for autoSave if not zero
autosaveDuration=60

; Parameter file for ad hoc change of the given geometry parameters
setParamsByFile="sweep.cfg"

; Direct parameter input for ad hoc change of the given geometry parameters
setParams="facet.10.opacity=0"

; Restrict console output to different levels
verbosity=4

; Whether autosave_ file should be used if exists
loadAutosave=true

; Resets simulation status loaded from file
reset=false

; Verbose console output (all levels)
verbose=true

; Overwrite input file with new results
overwrite=false

Example scripts

A major advantage with the CLI is the simple modification of simulation parameters. With scripts multiple runs can easily be run with an loop, e.g. to launch simulations for different geometries or to launch simulations with incrental modifications to facet properties.

As a brief example, we give a bash script (Linux/Mac) and a powershell script (Windows).

Bash:

# loop over a sequence [0.1,0.2 .. 1.0]
for val in $(seq 0.1 0.1 1.0)
do
   fileName=result_$val.zip
   echo "Launch simulation for opacity $val..."
   ./molflow_mac_2.9.8_beta/molflowCLI -f inputFile.zip -o $fileName --outputPath opacityResults -t 10 --setParams facet.2.opacity=$val --reset
   echo "Written result to $fileName"
done

Powershell:

# Loop over a sequence [0.1,0.2 .. 1.0]
for ($val=0.1; $val -le 1.0; $val=$val+0.1) {
  $fileName = "result_$val.zip"
  Write-Host "Launch simulation for opacity $val..."
  & .\molflow_win_2.9.8_beta\molflowCLI.exe "-f inputFile.zip -o $fileName --outputPath opacityResults -t 10 --setParams facet.2.opacity=$val --reset".Split(" ") #Converting parameters to a list
  Write-Host "Written result to $fileName"
}

Batch file:

@echo OFF
FOR %%G IN (0.1 0.2 0.3 0.4 0.5 0.6 0.7 0.8 0.9 1.0) DO (
  echo "Launch simulation for opacity %%G..."
  molflow_win_2.9.8_beta\molflowCLI.exe -f inputFile.zip -o result_%%G.zip --outputPath opacityResults -t 10 --setParams facet.2.opacity=%%G --reset
  echo "Written result to result_%%G.zip"  )

Documentation: Command Line Interface

MolflowCLI Documentation

Abstract

Changelog

Contents

Commands

Examples

Input / Output

[From 2.9.4]

Additional output

[From 2.9.1]

Autosave

Simulation settings

Facet parameter changes

Terminal log

Config file

Example scripts

CERN Accelerating science

Documentation: Command Line Interface

MolflowCLI Documentation

Abstract

Changelog

Contents

Commands

Examples

Input / Output

[From 2.9.4]

Additional output

[From 2.9.1]

Autosave

Simulation settings

Facet parameter changes

Terminal log

Config file

Example scripts