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_file>                                   Specify an input file
--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.
--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 --warn-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.

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

Command-Line Input File Overrides

Any input file parameters can be overriden/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.