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

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

--timeout <timeout>#

Timeout of the whole simulation run (in seconds). Sets the meta-config entry run_kwargs.timeout. Once the timeout is exceeded, workers will be stopped, which may lead to corrupted or incomplete individual universe outputs. Set to negative values to deactivate.

--skippable, --not-skippable#

If given, will overwrite the default value for skipping.enabled in the meta-configuration. Skippable universes allow that a run can be joined from another machine using utopya join-run, with the disadvantage that the run is now distributed across machines…

--skip-after-setup, --no-work#

By setting –no-work, the universe setup will be run, creating a universe output directory, but no universe process will be spawned. Use this as a first stage of distributedly working on a Multiverse run using multiple machines.

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

--no-wait#

If set, will not check whether there are distributed Multiverse runs that have not finished yet and directly proceed to loading.

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


utopya join-run#

utopya join-run#

EXPERIMENTAL Join a currently-running simulation.

Initializes MODEL_NAME from RUN_DIR and joins in working on the remaining simulation tasks, thus speeding up the progress.

Only runs that were started with the --skippable option can be joined, otherwise the main simulation would fail.

Note that this feature is currently experimental, meaning that the interface may still change a lot. If you encounter any issues, please let us know.

utopya join-run [OPTIONS] MODEL_NAME [RUN_DIR]

Options

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

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

--timeout <timeout>#

Timeout of the whole simulation run (in seconds). Sets the meta-config entry run_kwargs.timeout. Once the timeout is exceeded, workers will be stopped, which may lead to corrupted or incomplete individual universe outputs. Set to negative values to deactivate.

Arguments

MODEL_NAME#

Required argument

RUN_DIR#

Optional argument


utopya run-existing#

utopya run-existing#

EXPERIMENTAL (Re-)Run universes of an existing simulation run.

Restores a run of MODEL_NAME from the given RUN_DIR and allows to either continue working on it (e.g. if it was incomplete) or re-running universes (e.g. because they failed or were stopped).

Note that this feature is currently experimental, meaning that the interface may still change a lot. If you encounter any issues, please let us know.

utopya run-existing [OPTIONS] MODEL_NAME [RUN_DIR]

Options

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

-u, --uni, --universe <universes>#

If given, will only run a selection of these universes, identified by their state number, e.g. --uni 0423.

Note that leading zeros and the uni prefix are optional. To supply multiple, use the -u option multiple times (-u uni123 -u uni234 -u uni345) or provide a comma-separated list without spaces (-u 154,167,180).

If no universes are specified, a run on all universes is performed.

-c, --clear-existing#

Whether to clear existing output files from universes. Set this option to re-run universes that were previously run. Cannot be used together with –skip-existing.

-s, --skip-existing#

Whether to skip universes with existing output. Set this option to complete universes from a previous run. Cannot be used together –clear-existing.

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

--timeout <timeout>#

Timeout of the whole simulation run (in seconds). Sets the meta-config entry run_kwargs.timeout. Once the timeout is exceeded, workers will be stopped, which may lead to corrupted or incomplete individual universe outputs. Set to negative values to deactivate.

--no-reports#

If set, will not write report files. Set this flag if invoking this command with many individual universes to avoid creating as many report files.

Arguments

MODEL_NAME#

Required argument

RUN_DIR#

Optional argument