Command-Line Usage

Command-Line Options

All MOOSE-based applications come with quite a few command-line options. These can be customized by each application by adding "Command Line Parameters" to their MooseApp derived object.

Command-line options can be set using either short syntax such as -i inputfile.i or longer syntax with either --long-option value or --long-option=value. If spaces are needed for the value then you need to quote them like --long-option='value1 value2'. If using the = it's important not to put any space around it.

To print out the available command-line options use --help. An example from MooseTest looks like this:

> ./moose_test-opt --help

Usage: ./moose_test-opt [<options>]

Options:
  --check-input                                     Check the input file (i.e. requires -i <filename>) and quit.
  --color [auto,on,off]                             Whether to use color in console output (default 'on').
  --definition                                      Shows a SON style input definition dump for input validation
  --disallow-test-objects                           Don't register test objects and syntax
  -v --version                                      Print application version
  --distributed-mesh                                The libMesh Mesh underlying MooseMesh should always be a DistributedMesh
  --dump [search_string]                            Shows a dump of available input file syntax.
  --error                                           Turn all warnings into errors
  --error-deprecated                                Turn deprecated code messages into Errors
  -o --error-override                               Error when encountering overridden or parameters supplied multiple times
  -e --error-unused                                 Error when encountering unused input file options
  --half-transient                                  When true the simulation will only run half of its specified transient (ie half the timesteps).  This is useful for testing recovery and restart
  -h --help                                         Displays CLI usage statement.
  -i <input_files>                                  Specify one or multiple input files. Multiple files get merged into a single simulation input.
  --json                                            Dumps input file syntax in JSON format.
  --keep-cout                                       Keep standard output from all processors when running in parallel
  --list-constructed-objects                        List all moose object type names constructed by the master app factory.
  --mesh-only [mesh_file_name]                      Setup and Output the input mesh only (Default: "<input_file_name>_in.e")
  --minimal                                         Ignore input file and build a minimal application with Transient executioner.
  --n-threads=<n>                                   Runs the specified number of threads per process
  --no-color                                        Disable coloring of all Console outputs.
  --no-timing                                       Disabled performance logging. Overrides -t or --timing if passed in conjunction with this flag
  --no-trap-fpe                                     Disable Floating Point Exception handling in critical sections of code when using DEBUG mode.
  --recover [file_base]                             Continue the calculation.  If file_base is omitted then the most recent recovery file will be utilized
  --recoversuffix [suffix]                          Use a different file extension, other than cpr, for a recovery file
  --redirect-stdout                                 Keep standard output from all processors when running in parallel
  -r <n>                                            Specify additional initial uniform refinements for automatic scaling
  --registry                                        Lists all known objects and actions.
  --registry-hit                                    Lists all known objects and actions in hit format.
  --show-controls                                   Shows the Control logic available and executed.
  --show-input                                      Shows the parsed input file before running the simulation.
  --show-outputs                                    Shows the output execution time information.
  --split-file [filename]                           optional name of split mesh file(s) to write/read
  --split-mesh [splits]                             comma-separated list of numbers of chunks to split the mesh into
  --syntax                                          Dumps the associated Action syntax paths ONLY
  -t --timing                                       Enable all performance logging for timing purposes. This will disable all screen output of performance logs for all Console objects.
  --trap-fpe                                        Enable Floating Point Exception handling in critical sections of code.  This is enabled automatically in DEBUG mode
  --use-split                                       use split distributed mesh files
  -w --allow_unused                                 Warn about unused input file options
  --yaml                                            Dumps input file syntax in YAML format.

Solver Options:
  See solver manual for details (Petsc or Trilinos)

Important Options

Below are a few important command-line options you should be aware of:

-i

The most important option is -i this is how you specify an input file to read like so:

./yourapp-opt -i input.i

It's always important to cd to the directory where your input file is so that relative paths within the input file are treated properly.

It's also possible to specify multiple input files like the following:

./yourapp-opt -i base.i input.i

The input files are processed from left to right, so in this example, base.i is processed before input.i. This feature is useful when you have multiple input files that share input: you can factor out the common input into another file (e.g., base.i) so that you do not duplicate it (and thus risk changing it in one input file but not another).

--dump

--dump will show you all of the available input file syntax for your application. This can be quite overwhelming so --dump can optionally take an argument for a piece of syntax to search for like so:

./yourapp-opt --dump SomeKernel

Would show you documentation for objects matching SomeKernel.

--recover

If you output checkpoint files (using checkpoint = true in your Outputs block in your input file) then --recover will allow you to continue a solve that died in the middle of the solve. This can allow you to recover a job that was killed because the power went out or your job ran out of time on the cluster you were using.

Again: you MUST turn on checkpoint = true in the Outputs block of your input file for this to work! We now recommend that all input files contain checkpoint = true.

--n-threads

--n-threads controls the number of threads per MPI process MOOSE will use for the computation. This is how you turn on shared-memory parallelism.

Mesh Splitting Options

For more information see the Splitting documentation under the Mesh System

Command-Line Input File Overrides

Any input file parameters can be overridden/set from the command-line. This is incredibly handy for scripting and parameter studies. The way it works is that you use a "directory" type of syntax. Let's say that you have this [Kernels] block in your input file:

[Kernels]
  [./akernel]
    type = MyKernel
    variable = somevar
    coefficient = 0.2
  [../]
[]

To set the value of coefficient from the command-line you would run your application like so:

./yourapp-opt -i theinput.i Kernels/akernel/coefficient=0.7

It's important to remember not to use any spaces when doing command-line overrides like this.