.. _commandline: 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 :numref:`commandline/executables` or by using the Python script ``runcomflow`` as described in :numref:`commandline/python`. .. _commandline/executables: 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 :numref:`commandline/python` 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 :numref:`commandline/python`). .. _commandline/python: 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 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. Basic options ...................... The Python script ``runcomflow`` provides a wide range of options, of which the most important are: .. list-table:: :widths: 30 70 * - ``--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 |COMFLOW_CURRENT_VERSION| the following options are available (NB: check the output of the ``runcomflow`` script in your own ComFLOW distribution for up-to-date information): .. code-block:: none 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 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: .. code-block:: none 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/ } Priority of simulation settings ................................ The settings for a ComFLOW simulation are determined in the following order (ordered from lowest (1) to highest (4) priority): 1) settings provided in the simulation input files, 2) settings provided in the **defaults** section of the YAML file, 3) settings provided in the **simulations** section of the YAML file, 4) command line options for ``runcomflow``, ``comflow`` or ``geodef``. .. _commandline/directories: 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 =================== ========================== =================== 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``: .. code-block:: xml 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. .. .. rubric:: Footnotes .. .. rubric:: References .. .. bibliography:: references.bib