utopya run

utopya run

Perform a simulation run and evaluate its outputs.

Starts a simulation of the MODEL_NAME model, allowing to pass a custom RUN_CFG and otherwise manipulating the meta configuration. Subsequently, the simulation output is fed into the evaluation pipeline.

utopya run [OPTIONS] MODEL_NAME [RUN_CFG]

Options

--cfg-set, --cs <cfg_set>

If the chosen model provides configuration sets, use the config files from the chosen set for the run and plots config. Note that the specific arguments still take precedence over the values from the config sets; to use default paths, specify empty strings ('') for those arguments.

--label <label>

For model names that have multiple info bundles registered, a label is needed to unambiguously select the desired one. Alternatively, use the utopya models set-default CLI command to set a default label for a model.

--validate, --no-validate

If given, sets whether there will be parameter validation. If not given, will use the default specified in the meta config.

--run-mode <run_mode>

Forces a single simulation or a sweep. If not given, will use the value specified in the meta configuration.

Options:

single | sweep

--no-work

Whether to call WorkerTask or NoWorkTask. NoWorkerTask only creates configurations, but does not spawn a worker. No-work implies no-eval.

--note <note>

A suffix that is appended to the name of the run output directory; this can be useful to give a name to a certain simulation run.

-N, --num-steps <num_steps>

Sets the number of simulation steps. Needs to be an integer. Metric suffixes (k, M, G, T) can be used to denote large numbers, e.g 1.23M translating to 1230000, and scientific notation is also supported (applying integer rounding).

--write-every, --we <write_every>

Sets the write_every parameter, controlling how frequently model data is written. Can be given in the same formats as --num-steps.

--write-start, --ws <write_start>

Sets the write_start parameter, specifying the first time step at which data is written. After that step, data is written every write_every th step.Can be given in the same formats as --num-steps.

--num-seeds <num_seeds>

Creates a parameter dimension for the seeds with the given number of seed values. This also sets the perform_sweep parameter to True, such that a sweep is invoked.

-W, --num-workers <num_workers>

Shortcut for meta-config entry worker_manager.num_workers, which sets the number of worker processes. Can be an integer; if negative, will deduce the number from the number of available CPUs.

--set-model-params, --mp <set_model_params>

Sets entries in the model configuration, i.e. inside of the parameter_space.<model_name> entry of the meta configuration. Example: --mp some.param=42 sets the param entry in some to 42. Specify DELETE as value to remove an entry. Repeat the --mp option to set multiple values.

--set-pspace-params, --pp <set_pspace_params>

Like --set-model-params but attaching to the parameter_space entry of the meta configuration. Repeat the --pp option to set multiple values.These arguments are parsed after --set-pspace-params and --set-model-params such that they can overwrite any of the previously defined arguments.

-p, --set-params <set_params>

Like --set-model-params but attaching to the root level of the meta configuration. These arguments are parsed after --set-pspace-params and --set-model-params such that they can overwrite any of the previously defined arguments.

--eval, --no-eval

If given, overwrites the default behavior of whether the simulation run should be followed by the evaluation routine (data loading and plotting) or not. The default can also be set in the model info file. If no default is given there, will attempt evaluation.

-P, --load-parallel

If given, will force loading data in parallel.

--use-data-tree-cache, --tc

If set, uses tree file caching: If no cache file exists, creates one after loading all data; if a tree file already exists, uses that to restore the data tree. This may bring a speed-up if the creation of the data tree takes a long time.

--show-data-tree <show_data_tree>

Controls which kind of data tree should be shown after loading.

Default:

condensed

Options:

full | condensed | none

--plots-cfg <plots_cfg>

If given, uses the plots configuration file found at this path instead of the defaults for the model.

-u, --update-plots-cfg <update_plots_cfg>

Sets entries in the selected plots config. Example: -u my_plot.some_param=42 sets the some_param entry in the plot configuration named my_plot. Repeat the -u option to set multiple values.

--plot-only, --po <plot_only>

If given, will plot only those entries of the plot configuration that match the names given here. This can also be used to activate plots that are disabled in the specified plot configuration. Note that simple name globbing is supported, but the argument needs to be put into quotes to not conflict with the globbing done by the shell. Repeat the --po option to denote multiple plot_only arguments.

-i, --interactive

If set, the CLI will not exit after plotting finished, but allow to continue plotting in an interactive session. This option is useful for creating multiple plots in an iterative fashion, especially if data loading time is large. Note that all Multiverse-related configuration options can not be changed during the session and have to be set beforehand.

-R, --reveal-output

If set, opens the output directory after plotting finished.

-d, --debug

The debug level.

--cluster-mode

Enables cluster mode.

Arguments

MODEL_NAME

Required argument

RUN_CFG

Optional argument