MolflowCLI

MolflowCLI allows users to 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.

Contents

Use the right-side navigation bar for sections of this document

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           Number of parallel threads to be used for calculation
  -t,--time UINT              Finish simulation after this time (in seconds)
  -d,--ndes FLOAT ...         Finish simulation after this number of desorbed particles
  -f,--file TEXT:FILE REQUIRED
                              Input file to load (XML/ZIP only)
  -o,--output TEXT            Excludes: --overwrite
                              Output file name. Example: 'result.zip', default: 'out_{inputFileName}'
  --outputPath TEXT           Excludes: --overwrite
                              Output path, default: 'Results_{timestamp}'
  -s,--statprintInterval UINT Statistics print interval in seconds, 0=disabled, default:60
  -a,--autosaveInterval UINT  Autosave interval in seconds, 0=disabled, default:600
  --writeFacetDetails         When ready, write a CSV file containing all facet details (incl. physical quantities)
  --writeFacetQuantities      When ready, write a CSV file containing all physical quantities for each facet
  --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             Console output verbosity. Levels: 0-4. Default:2
  --noProgress                No percentage updates of progress (useful when output is saved to a log file)
  --loadAutosave              Load and continue autosave_ file if exists
  -r,--reset                  Reset input file simulation (to 0 des.) before starting
  --verbose                   Verbose console output (equivalent to --verbosity 4)
  --overwrite                 (Excludes: --output --outputPath)
                              Overwrite input file with results
  --config                    Read an ini file

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.

1. Input file from working directory

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

2. Input file from relative path

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

3. 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.

Additional output

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

Parameter changes

The CLI application allows the user to change several geometry and simulation parameters.

Using as argument

Use the --setParams argument followed by one or more change command(s)

Example

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

• First sets Facet #2 outgassing to 10 mbar.l/s
• Then sets Facet #42 sticking to 1
• Then continues the simulation for 1000 seconds and saves the result
• Parameter changes are saved with the geometry in the result file

Using a parameter file

You can create an external file, where each command is one line, and refer to it with
--setParamsByFile {fileName}

Example

The equialent of the previous example would be to create the file paramChanges.txt with two lines:

facet.2.outgassing=10.0
facet.42.sticking=1.0

Then call it as:

./molflowCLI --file inputFile.xml --setParamsByFile paramChanges.txt -t 1000

Changing facet parameters

The command(s) can be in the format:

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

Where...

• facet_index is the facet number, for example 30 for Facet #30
• range_of_indices refers to multiple indices, for example 30-50 to facets 30,31,...,50
• "selection_group" is a named selection already defined in the geometry. See the comment at the end about the need to escape the " character.

The following facet parameters can be changed:

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

Changing simulation parameters

simulation.{parameter} = {value}

The following simulation parameters can be changed:

• mass: particle mass [g/mol]
• enableDecay: particle decay 0=off,1=on
• halfLife: half life [s]

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.

About named selections as arguments

When using commands referring to named selections, such as...

facet."wall".temperature=273

Be aware that most command line(s) parse the " quotation mark locally, so molflowCLI would receive the argument incorrectly as

facet.wall.temperature=273

One solution is to use a parameter file with the --setParamsByFile argument.

Otherwise, you have to escape the quotation mark as follows:

• Windows Powershell 7, Linux/Mac terminals:
  Use the command with ' simple quotation, such as:
  

  ./molflowCLI -f input.zip -t 100 --setParams 'facet."wall".temperature=300'
  

• Windows Command Prompt:
  Escape with \":
  

  molflowCLI.exe -f input.zip -t 100 --setParams facet.\"wall\".temperature=300
  

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 (level2 from Molflow 2.9.19)	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 (Linux/Mac)

# 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"  )

---

Last update: January 22, 2024