4. Command line options¶

This chapter describes the various command line options in more detail. ComFLOW simulations can be started by directly running the executables as described in Section 4.1 or by using the Python script runcomflow as described in Section 4.2.

4.1. The executables¶

Note

It is recommended to run ComFLOW by means of the included Python scripts, which provide several advantages with respect to directly calling the executables themselves. Most of the command line options of the executables translate one-on-one to the command line options of the Python scripts. See Section 4.2 for more information.

Several options can be specified when running any of the ComFLOW applications from the command line. If no options are specified, the application is started with default settings, which can be inspected by running the command comflow --help.

Please note that any settings provided at the command line take precedence over the settings as specified in the input file. For example, if the option --nthreads 4 is specified, the simulation is performed with 4 threads, irregardless of the parallelization settings in the input file.

It is strongly recommended to start each simulation in a new (clean) directory. Specifying non-standard output locations by means of the command line option --output ${OUTPUT} may be helpful for this purpose. Here, ${OUTPUT} has to replaced with the desired output directory, both relative and absolute paths are accepted. Relative paths at the command line are interpreted w.r.t. the initial working directory; relative paths in input files (etc.) are interpreted w.r.t. the chosen output directory of the program. Both forward and backward slashes are accepted and automatically converted to match those of the operating system.

The ComFLOW distribution includes a Python script runcomflow.py that may help streamlining the process of pre-processing and running a simulation (see Section 4.2).

4.2. Python wrapper and ComFLOW batch files¶

A Python-3 wrapper is provided that provides the following (and more) advantages over directly invoking the ComFLOW executables:

pre-process, run and post-process a simulation using a single command runcomflow
choose between different ComFLOW versions and releases
create a directory structure, apply clean-up
run lists of simulations specified in YAML files

4.2.1. Prerequisites¶

In order to use the Python scripts that are included in the ComFLOW distribution it is necessary to install Python 3. It is recommended (though not necessarily required) to use version 3.6 or later. Visit the Python download page for more information.

4.2.2. Basic options¶

The Python script runcomflow provides a wide range of options, of which the most important are:

`--run=${COMMANDS}`	list of ComFLOW commands `${COMMANDS}` for example `GC` for GEODEF followed by ComFLOW
`--input=${INPUT}`	specify a custom location `${INPUT}` for the input files of the simulation
`--output=${OUTPUT}`	specify a custom location `${OUTPUT}` for the output files of the simulation
`--nthreads=${NTHREADS}`	set the number of OpenMP threads `${NTHREADS}`
`--restart=${RESTARTFILE}`	restart a simulation from the restart file `${RESTARTFILE}`
`--help`	print help

If options are omitted, default values are used. In ComFLOW version 4.1.1 the following options are available (NB: check the output of the runcomflow script in your own ComFLOW distribution for up-to-date information):

runcomflow.py [-h] [--run [GLCMDWT]] [--save] [--test] [--mkdir]
                [--rmdat] [--versionlist] [--versioninfo] [-v V] [-c C]
                [--input INPUT] [--output OUTPUT] [--restart RESTART]
                [--prop-all] [-nt CPUS_PER_TASK] [-np NTASKS]
                [--ntasks_per_node NTASKS_PER_NODE]
                [--ntasks_per_socket NTASKS_PER_SOCKET] [--mpi MPI]
                [--memory_limit MEMORY_LIMIT] [--time_limit TIME_LIMIT]
                [--mpi_map_by MPI_MAP_BY]
                [--mpi_mpmd MPI_MPMD [MPI_MPMD ...]] [-id IDENTIFIER]
                [--compare_with COMPARE_WITH] [--reference REFERENCE]
                [--pause] [--sleep SLEEP] [--debug] [--valgrind]
                [--helgrind] [--drd] [--deterministic]
                [--verbosity VERBOSITY] [-j {peregrine,}]
                [--job_name JOB_NAME] [--slurm_stderr SLURM_STDERR]
                [--slurm_stdout SLURM_STDOUT]
                [simulation]
Run a ComFLOW simulation consisting of GEODEF, LIQDEF and ComFLOW

positional arguments:
  simulation            simulation directory, YAML file (multiple simulations)
                        or ".cfi" input file (default is current directory)

optional arguments:
  -h, --help            show this help message and exit
  --run [GLCMDWT]       list of commands (ordered), G=Geodef, L=Liqdef,
                        C=ComFLOW+merge, M=merge, D=Difference/compare,
                        W=Wave51, T=Work, for example: GWC to run Geodef-
                        Wave51-ComFLOW
  --save                save command line, but do not run (for reference and
                        comparison purposes)
  --test                test run (only print commands to be executed)
  --mkdir               make directory structure
  --rmdat               clean up old data
  --versionlist         show a list of available ComFLOW versions
  --versioninfo         show details of selected ComFLOW version and
                        configuration
  -v V, --version V     specify ComFLOW version "V" to be used
  -c C, --configuration C
                        specify ComFLOW configuration "C" to be used
  --input INPUT         input directory
  --output OUTPUT       output directory
  --restart RESTART     location of restart file
  --prop-all            list all program properties
  -nt CPUS_PER_TASK, --cpus_per_task CPUS_PER_TASK, --nthreads CPUS_PER_TASK
                        number of OpenMP threads
  -np NTASKS, --ntasks NTASKS, --nranks NTASKS
                        number of MPI ranks
  --ntasks_per_node NTASKS_PER_NODE, --tasks_per_node NTASKS_PER_NODE
                        number of tasks per node
  --ntasks_per_socket NTASKS_PER_SOCKET, --tasks_per_socket NTASKS_PER_SOCKET
                        number of tasks per socket
  --mpi MPI             run using MPI (e.g. mpirun*, mpiexec, srun)
  --memory_limit MEMORY_LIMIT
                        memory limit for job
  --time_limit TIME_LIMIT
                        time limit for job
  --mpi_map_by MPI_MAP_BY
                        custom setting for mpirun --map-by=
  --mpi_mpmd MPI_MPMD [MPI_MPMD ...]
                        specify list of simulations to run using one MPI
                        command
  -id IDENTIFIER, --identifier IDENTIFIER
                        simulation ID (for reference and comparison purposes)
  --compare_with COMPARE_WITH
                        compare with simulation ID (for reference and
                        comparison purposes)
  --reference REFERENCE
                        location of the reference directory (must be at the
                        same level as the output directory)
  --pause               initial pause for debugging purposes
  --sleep SLEEP         sleep interval at startup
  --debug               run using debugger (e.g. gdb)
  --valgrind            run using valgrind
  --helgrind            run using helgrind (a valgrind tool)
  --drd                 run using DRD (a valgrind tool)
  --deterministic       run in deterministic mode
  --verbosity VERBOSITY
                        verbosity
  -j {peregrine,}, --job_script {peregrine,}
                        make job scripts for the specified system
  --job_name JOB_NAME   job name
  --slurm_stderr SLURM_STDERR
                        file for stderr of slurm job
  --slurm_stdout SLURM_STDOUT
                        file for stdout of slurm job

4.2.3. Simulation batch files (YAML files)¶

The runcomflow script can read YAML files which contain settings for one or more ComFLOW simulations. For each simulation separate options can be specified in a similar fashion as on the command line. The option names are identical to those accepted by the runcomflow command line (to get an overview of the possible options, type runcomflow --help).

Running the contents of a YAML file is straightforward, just run: runcomflow ${YAMLFILE}, where ${YAMLFILE} has to replaced by the name of the YAML file. Additional settings can be provided on the command line, which overrule the settings specified in the YAML file.

The following basic example YAML file lists a number of ComFLOW input directories for different wave scenarios and asks for three ComFLOW simulations (one after the other) to be run on 16 processor cores:

defaults:
    nthreads: 16
    # use defaults for other settings
simulations:
    - {input: wave_on_deck/scenario1/input_files, output: wave_on_deck/scenario1/ }
    - {input: wave_on_deck/scenario2/input_files, output: wave_on_deck/scenario2/ }
    - {input: wave_on_deck/scenario3/input_files, output: wave_on_deck/scenario3/ }

4.2.4. Priority of simulation settings¶

The settings for a ComFLOW simulation are determined in the following order (ordered from lowest (1) to highest (4) priority):

settings provided in the simulation input files,
settings provided in the defaults section of the YAML file,
settings provided in the simulations section of the YAML file,
command line options for runcomflow, comflow or geodef.

4.3. Paths and file names¶

ComFLOW allows file locations to be specified in a cross-platform fashion. File delimiters / and \ are automatically converted to platform-compliant delimiters and paths are normalized where necessary.

File locations can be specified with respect to the simulation input and output directories by using ComFLOW-specific application environment variables ${INPUT} and ${OUTPUT}. For portability of the simulation input as well as for compatibility with future ComFLOW versions it is strongly recommended to avoid the use of absolute paths, where possible, and to always express paths relative to the locations ${INPUT} and ${OUTPUT}. For example, the location of the XML input file is ${INPUT}/comflow.cfi and the location of the ComFLOW screen output is ${OUTPUT}/omflow.out.

ComFLOW defines the following directories:

Directory Default location Contents

${INPUT} ./input_files input files

${OUTPUT} ./ simulation output

${INTERMEDIATE} ${OUTPUT}/intermediate intermediate files

4.3.1. XML-embedded files¶

ComFLOW is able to read XML-embedded files, which can be accessed in the namespace xml://. The embedded files are defined in the XML key comflow/files. As an example consider the following embedded INI file xml://movingobject1.ini:

<files>
    <file name="movingobject1.ini" trim="true" encoding="cdata">
<![CDATA[
[geometry]
identifier = 1
origin     = 11.76 0. 13.95

[motion]
type       = interactive
velocity   = 6.3931  0.0     -12.867     0. -13.4129  0. ;; m m m deg deg deg

[inertia]
reference  = 0. 0. 0.     0. 30. 0.  ;m,m,m,deg,deg,deg
mass       = 17701
j11        = 1.14
j22        = 2.88
j33        = 2.98

[transform]
destination = 11.76 0. 13.95    0. 0. 0.
]]>
    </file>
</files>

4.4. ComFLOW command Prompt (Windows only)¶

On the Windows operating system ComFLOW can be used out-of-the-box by means of the ComFLOW command prompt. The command prompt can be started by running comflowprompt.bat located in the sub-directory bin\win32 or bin\win64.

The command prompt provides the following commands:

COMFLOW $*: run ComFLOW with the specified options
GEODEF $*: run GEODEF with the specified options
PYTHON_RUNCOMFLOW $*, RUNCOMFLOW $*: invoke the Python script runcomflow with the specified options. Depending on your system configuration use either one of the two commands.
SETCOMFLOWVERSION: present a menu in which a version of the ComFLOW executables can be selected (obsolete)

For convenience a Visual Basic script createshortcuts.vbs is included in the same directory which can be used to create a shortcut, which can for example be placed on the Windows desktop or start menu.