General Application Command Line Interface (CLI)

Currently, the most common way to interact with an application is using the unified Command Line Interface (CLI). Although each application mode has a slightly different interface, they all share a number of common options and modes, which is described here.

Applications are launched from the command line by passing the input script to the python interpreter. The easiest way to achieve this, is using the oscar5 (or rapyds-cli) wrapper script, which has the following signature:

$oscar5 MY_REACTOR.package.my_module [app options] [mode [mode options]]

Here, we assume that you are running the script from the root MY_APPS directory. The number of sub-packages to get to your module can be of any length, separated by a ‘.’

Note

The ‘.py’ extension of the input module is omitted.

Although the oscar5 script simply wraps a python -m call, it also adds some basic bash <tab> and <tab><tab> auto completion features.

Note

Tab completion is currently only available on bash shells, and not in Windows cmd terminals. Extended tab completion is under development for PowerShell, which will then also make this feature available on the Windows operating system.

The available <app options> and modes are described in Setting or modifying parameters using command line arguments and Application modes respectively. They can also be viewed by passing the --help flag:

$oscar5 MY_REACTOR.package.my_module --help

Attention

If you are working in a terminal or Anaconda Prompt, remember to activate the correct environment first:

$ conda activate rapyds

Setting or modifying parameters using command line arguments

This section describes the available app options.

--log-level <str>

Determines the amount of log information printed to the log file. The following options are supported, listed from the most to least amount of log information:

Log level options.
DEBUG	Prints a lot of additional information, which typically only makes sense for the developers. Use this level if additional information is required in order to track down a problem.
INFO	Prints some additional runtime information to the log file.
WARN	Only print warnings and errors.
ERROR	Print only errors.

The default value is INFO.

Most of the general parameters can be customized on the command line using the following flags:

--config-file <str>: Targets app_param.config_file.

--target-mode <str>: Targets app_param.target_mode. This flag can be used to run the same module using multiple target codes.

--doppler-broadening: Targets app_param.doppler_broadening.

--source-iteration <int>: Targets app_param.source_iteration.

--max-iteration <int>: Targets app_param.max_iteration.

--particles <int>: Targets app_param.particles.

--convergence_criteria <float>: Targets app_param.convergence_criteria.

--error-tolerance <float>: Targets app_param.error_tolerance.

--cross-section-library <str>: Targets app_param.cross_section_library.

--decay-data-library <str>: Targets app_param.decay_data_library.

--fission-product-yields <str>: Targets app_param.fission_product_yields.

For instance, to set the configuration file :

$ oscar5 python -m MY_REACTOR.cases.my_app --config-file my_config.cfg

Note

Values specified on the command line are optional, and will override the parameter values set in the input module.

Attention

Since these parameters generally affect all sub modes, the are specified before any mode on the command line.

Application modes

All applications have numerous sub, or run, modes, each with its own set of command line flags. The following table summarizes the general modes:

Common application modes.
Run Mode	Description
archive	Compress the entire contents of `app_param.working_directory` into a single archive file.
clean	Clears files and directories from the `app_param.working_directory`.
visualization	Visualize the underlying model.
pre	Pre-processing and input creation.
execute	Execution using `app_param.target_mode`.
post	Post-process results from output file(s).
run	Create input, launch application and wait for results to be available.
doc	Generate and view attached document (if activated).

All the run modes have their own help flag, listing the available options for that particular mode. For instance,

$oscar5  MY_REACTOR.package.my_module execute --help

Archive mode

This mode is used to compress the entire app_param.working_directory into a single archive file. It accepts the following command line arguments:

--format <str>

Compression format. The available formats is determined by the shutil archive module, and depends on which compression libraries are available on your system:

‘zip’: ZIP file (if the zlib module or external zip executable is available).

‘tar’: uncompressed tar file.

‘gztar’: gzip’ed tar-file (if the zlib module is available).

‘bztar’: bzip2’ed tar-file (if the bz2 module is available).

The default value is ‘tar`.

--name <str>: Archive file name. Defaults to app_param.project_name. An extension will be automatically appended depending on archive --format.

For example, the following will create a zip archive app_param.project_name.zip:

$oscar5  MY_REACTOR.package.my_module archive --format zip

Clean mode

This mode clears all generated input and output from the app_param.working_directory. It accepts the following command line flags:

--keep_tree: Delete only files, that is, keep directory structure.

--remote_host: Also clear input and output files on the remote host.

Visualization mode

Three dimensional visualization of the underlying model. Accepts the following command line flags:

--interactive: Launch interactive VTK based viewer.

--parts: When combined with the interactive flag, displays a more sophisticated interactive viewer with a tree showing model components.

Note

This will become the default view mode in future releases, as the materials based viewer will be deprecated.

--freecad: Export model to FreeCAD.

If no flags are passed, a simple VTK view window is displayed.

For example, to view the model in an interactive frame:

$oscar5  MY_REACTOR.package.my_module visualization --interactive --parts

Note

The FreeCAD export requires that the FreeCAD python API is in the python path. This mode is also disabled for certain models.

Pre-processing mode

Process input data, and create input for the app_param.target_mode. Accepts the following command line flags:

--force: Overwrite any existing input file(s). If this flag is omitted, existing input files will be used.

Attention

Since input depends on the remote host, be sure to add this flag if app_param.config_file is changed!

Input file(s) are written to a app_param.target_mode sub directory under app_param.working_directory.

Note

Use the pre mode if you want to view or modify input files before program execution.

Execution mode

This mode is used to execute app_param.target_mode executables on the on the target host, and examine running applications. The following flags can be used to customize application parameters related to code execution:

--force: Overwrite any existing input file(s), and also ignore any existing input.

--executable <str>: Targets app_param.executable.

--arguments <str>: Targets app_param.arguments.

--use-rsync: Targets app_param.use_rsync.

--threads <int>: Targets app_param.threads.

--node <int>: Targets app_param.nodes.

--queue <str>: Targets app_param.queue.

--walltime <float>: Targets app_param.walltime.

Note

This mode will create input files if none exist, so there is no need to run in pre mode first. However, if you plan to modify input files, use pre mode, and don’t pass the --force flag to execute mode.

For example, the following will launch the application on the host defined in @a my_config using 20 threads:

$oscar5  MY_REACTOR.package.my_module --config-file my_config.cfg execute --threads 20

For running applications, the following flags can be used:

--status: Get the status of a running application.

--peek: Stream the output from a running application.

Attention

When running on a remote host, make sure that the spool parameter is set correctly.

--kill: Kill a running application.

For example,

$oscar5  MY_REACTOR.package.my_module --config-file my_config.cfg execute --status

Post-processing mode

Copy (sync) output files from the run host, parse results from output files and generate results summary. Accepts the following command line flags:

--force: Fore re-processing of output. Will generate a new result archive even if an existing is found.

--use-rsync: Use rsync to copy files from a remote host. Equivalent to setting the app_param.use_rsync parameter. Only relevant if a remote host is used.

--show: Initiate result viewer GUI (if available).

--compare <str>: Compare results with another target mode. Output for the target mode must already exist.

For example, the following will simply process output and generate a result archive:

$oscar5  MY_REACTOR.package.my_module post

Attention

If you passed a configuration file to the execute mode, be sure to use the same one in this mode, otherwise results will not be retrieved from the correct host:

$oscar5  MY_REACTOR.package.my_module --config-file my_config.cfg post

Run mode

This essentially combines the pre, execute and post modes. Supports all the execute mode flags. For example,

$oscar5  MY_REACTOR.package.my_module run --force

will, recreate the input, execute the application and post process the result.

Attention

When running on a remote host, for example,

$oscar5  MY_REACTOR.package.my_module --config-file my_config.cfg run --threads 24

the application will wait (pining the remote machine periodically) until execution on the remote host has finished, before copying output files back to the local machine. Thus, the terminal on the local machine must not be closed, and access to the remote machine must be maintained.

Document generation mode

Create and view the attached documentation.

Attention

This mode is only available if the docgen parameter set has been activated. See Activating documentation input.

Accepts the following command line flags:

--preview: Only create the document source tree (if it does not exist), and expand macros without generating targets.

Note

Is equivalent to running the standalone docgen application in pre mode.

--skip-html: Don’t generate HTML output.

--skip-pdf: Don’t generate LaTeX output.

--force: Force running the pre-processor, and rebinding of variables.

--show: View the generated output. On most platforms, it will be opened in a browser window.

Nested application modes

Many applications contain sub applications, which are then exposed in the CLI as additional modes.