Command Line API Reference

The main function for parsing global arguments

usage: model [-h] [-id str] [-l] [-n] [-v] [-vl str or int] [-nm] [-E]
             {setup,init,set-value,get-value,del-value,info,unarchive,configure,archive,remove}
             ...

Named Arguments

-id, --experiment
experiment: str

The id of the experiment to use. If the init argument is called, the new argument is automatically set. Otherwise, if not specified differently, the last created experiment is used.

-l, --last

If True, the last experiment is used

Default: False

-n, --new

If True, a new experiment is created

Default: False

-v, --verbose

Increase the verbosity level to DEBUG. See also verbosity_level for a more specific determination of the verbosity

Default: False

-vl, --verbosity-level

The verbosity level to use. Either one of 'DEBUG', 'INFO', 'WARNING', 'ERROR' or the corresponding integer (see pythons logging module)

-nm, --no-modification

If True/set, no modifications in the configuration files will be done

Default: False

-E, --match

If True/set, interprete experiment as a regular expression (regex) und use the matching experiment

Default: False

Sub-commands:

setup

Perform the initial setup for the project

model setup [-h] [-p str] [-link] str

Positional Arguments

str

The path to the root directory where the experiments, etc. will be stored

Named Arguments

-p, --projectname

The name of the project that shall be initialized at root_dir. A new directory will be created namely root_dir + '/' + projectname

-link

If set, the source files are linked to the original ones instead of copied

Default: False

init

Initialize a new experiment

model init [-h] [-p str] [-d str]

Named Arguments

-p, --projectname

The name of the project that shall be used. If None, the last one created will be used

-d, --description

A short summary of the experiment

Notes

If the experiment is None, a new experiment will be created

Notes

If the experiment is None, a new experiment will be created

set-value

Set a value in the configuration

model set-value [-h] [-a] [-P] [-g] [-p str] [-b str] [-dt str]
                level0.level1.level...=value
                [level0.level1.level...=value ...]

Positional Arguments

level0.level1.level...=value

The key-value pairs to set. If the configuration goes some levels deeper, keys may be separated by a '.' (e.g. 'namelists.weathergen'). Hence, to insert a ',', it must be escaped by a preceeding ''.

Named Arguments

-a, --all

If True/set, the information on all experiments are printed

Default: False

-P, --on-projects

If set, show information on the projects rather than the experiment

Default: False

-g, --globally

If set, show the global configuration settings

Default: False

-p, --projectname

The name of the project that shall be used. If provided and on_projects is not True, the information on all experiments for this project will be shown

-b, --base

A base string that shall be put in front of each key in values to avoid typing it all the time

Default: “”

-dt, --dtype

Possible choices: ArithmeticError, AssertionError, AttributeError, BaseException, BlockingIOError, BrokenPipeError, BufferError, BytesWarning, ChildProcessError, ConnectionAbortedError, ConnectionError, ConnectionRefusedError, ConnectionResetError, DeprecationWarning, EOFError, Ellipsis, EnvironmentError, Exception, False, FileExistsError, FileNotFoundError, FloatingPointError, FutureWarning, GeneratorExit, IOError, ImportError, ImportWarning, IndentationError, IndexError, InterruptedError, IsADirectoryError, KeyError, KeyboardInterrupt, LookupError, MemoryError, ModuleNotFoundError, NameError, None, NotADirectoryError, NotImplemented, NotImplementedError, OSError, OverflowError, PendingDeprecationWarning, PermissionError, ProcessLookupError, RecursionError, ReferenceError, ResourceWarning, RuntimeError, RuntimeWarning, StopAsyncIteration, StopIteration, SyntaxError, SyntaxWarning, SystemError, SystemExit, TabError, TimeoutError, True, TypeError, UnboundLocalError, UnicodeDecodeError, UnicodeEncodeError, UnicodeError, UnicodeTranslateError, UnicodeWarning, UserWarning, ValueError, Warning, ZeroDivisionError, __build_class__, __debug__, __doc__, __import__, __loader__, __name__, __package__, __spec__, abs, all, any, ascii, bin, bool, bytearray, bytes, callable, chr, classmethod, compile, complex, copyright, credits, delattr, dict, dir, divmod, enumerate, eval, exec, exit, filter, float, format, frozenset, getattr, globals, hasattr, hash, help, hex, id, input, int, isinstance, issubclass, iter, len, license, list, locals, map, max, memoryview, min, next, object, oct, open, ord, pow, print, property, quit, range, repr, reversed, round, set, setattr, slice, sorted, staticmethod, str, sum, super, tuple, type, vars, zip

The name of the data type or a data type to cast the value to

get-value

Get one or more values in the configuration

model get-value [-h] [-ep] [-pp] [-a] [-P] [-g] [-p str] [-nf] [-k] [-b str]
                [-arc]
                level0.level1.level... [level0.level1.level... ...]

Positional Arguments

level0.level1.level...

A list of keys to get the values of. If the key goes some levels deeper, keys may be separated by a '.' (e.g. 'namelists.weathergen'). Hence, to insert a ',', it must be escaped by a preceeding ''.

Named Arguments

-ep, --exp-path

If True/set, print the filename of the experiment configuration

Default: False

-pp, --project-path

If True/set, print the filename on the project configuration

Default: False

-a, --all

If True/set, the information on all experiments are printed

Default: False

-P, --on-projects

If set, show information on the projects rather than the experiment

Default: False

-g, --globally

If set, show the global configuration settings

Default: False

-p, --projectname

The name of the project that shall be used. If provided and on_projects is not True, the information on all experiments for this project will be shown

-nf, --no-fix

If set, paths are given relative to the root directory of the project

Default: False

-k, --only-keys

If True, only the keys of the given dictionary are printed

Default: False

-b, --base

A base string that shall be put in front of each key in values to avoid typing it all the time

Default: “”

-arc, --archives

If True, print the archives and the corresponding experiments for the specified project

Default: False

del-value

Delete a value in the configuration

model del-value [-h] [-a] [-P] [-g] [-p str] [-b str] [-dtype DTYPE]
                level0.level1.level... [level0.level1.level... ...]

Positional Arguments

level0.level1.level...

A list of keys to be deleted. If the key goes some levels deeper, keys may be separated by a '.' (e.g. 'namelists.weathergen'). Hence, to insert a ',', it must be escaped by a preceeding ''.

Named Arguments

-a, --all

If True/set, the information on all experiments are printed

Default: False

-P, --on-projects

If set, show information on the projects rather than the experiment

Default: False

-g, --globally

If set, show the global configuration settings

Default: False

-p, --projectname

The name of the project that shall be used. If provided and on_projects is not True, the information on all experiments for this project will be shown

-b, --base

A base string that shall be put in front of each key in values to avoid typing it all the time

Default: “”

-dtype

info

Print information on the experiments

model info [-h] [-ep] [-pp] [-gp] [-cp] [-a] [-nf] [-P] [-g] [-p str] [-k]
           [-arc]

Named Arguments

-ep, --exp-path

If True/set, print the filename of the experiment configuration

Default: False

-pp, --project-path

If True/set, print the filename on the project configuration

Default: False

-gp, --global-path

If True/set, print the filename on the global configuration

Default: False

-cp, --config-path

If True/set, print the path to the configuration directory

Default: False

-a, --all

If True/set, the information on all experiments are printed

Default: False

-nf, --no-fix

If set, paths are given relative to the root directory of the project

Default: False

-P, --on-projects

If set, show information on the projects rather than the experiment

Default: False

-g, --globally

If set, show the global configuration settings

Default: False

-p, --projectname

The name of the project that shall be used. If provided and on_projects is not True, the information on all experiments for this project will be shown

-k, --only-keys

If True, only the keys of the given dictionary are printed

Default: False

-arc, --archives

If True, print the archives and the corresponding experiments for the specified project

Default: False

unarchive

Extract archived experiments

model unarchive [-h] [-ids exp1,[exp2[,...]]] [exp1,[exp2[,...]]] ...]]
                [-f str] [-a] [-pd] [-P] [-d str] [-p str]
                [-fmt { 'gztar' | 'bztar' | 'tar' | 'zip' }] [--force]

Named Arguments

-ids, --experiments

The experiments to extract. If None the current experiment is used

-f, --file

The path to an archive to extract the experiments from. If None, we assume that the path to the archive has been stored in the configuration when using the archive() command

-a, --all

If True, archives are extracted completely, not only the experiment (implies project_data = True)

Default: False

-pd, --project-data

If True, the data for the project is extracted as well

Default: False

-P, --replace-project-config

If True and the project does already exist in the configuration, it is updated with what is stored in the archive

Default: False

-d, --root

An alternative root directory to use. Otherwise the experiment will be exctracted to

  1. the root directory specified in the configuration files (if the project exists in it) and replace_project_config is False

  2. the root directory as stored in the archive

-p, --projectname

The projectname to use. If None, use the one specified in the archive

-fmt

The format of the archive. If None, it is inferred

--force

If True, force to overwrite the configuration of all experiments from what is stored in archive. Otherwise, the configuration of the experiments in archive are only used if missing in the current configuration

Default: False

configure

Configure the project and experiments

model configure [-h] [-g] [-p] [-i str] [-f str] [-s] [-n int or 'all']
                [-update-from str]

Named Arguments

-g, --globally

If True/set, the configuration are applied globally (already existing and configured experiments are not impacted)

Default: False

-p, --project

Apply the configuration on the entire project instance instead of only the single experiment (already existing and configured experiments are not impacted)

Default: False

-i, --ifile

The input file for the project. Must be a netCDF file with population data

-f, --forcing

The input file for the project containing variables with population evolution information. Possible variables in the netCDF file are movement containing the number of people to move and change containing the population change (positive or negative)

-s, --serial

Do the parameterization always serial (i.e. not in parallel on multiple processors). Does automatically impact global settings

Default: False

-n, --nprocs

Maximum number of processes to when making the parameterization in parallel. Does automatically impact global settings and disables serial

-update-from

Path to a yaml configuration file to update the specified configuration with it

archive

Archive one or more experiments or a project instance

This method may be used to archive experiments in order to minimize the amount of necessary configuration files

model archive [-h] [-d str] [-f str]
              [-fmt { 'gztar' | 'bztar' | 'tar' | 'zip' }] [-p str]
              [-ids exp1,[exp2[,...]]]] [-P] [-na] [-np] [-e str [str ...]]
              [-k] [-rm] [-n] [-L]

Named Arguments

-d, --odir

The path where to store the archive

-f, --aname

The name of the archive (minus any format-specific extension). If None, defaults to the projectname

-fmt

Possible choices: bztar, gztar, tar, zip

The format of the archive. If None, it is tested whether an archived with the name specified by aname already exists and if yes, the format is inferred, otherwise 'tar' is used

-p, --projectname

If provided, the entire project is archived

-ids, --experiments

If provided, the given experiments are archived. Note that an error is raised if they belong to multiple project instances

-P, --current-project

If True, projectname is set to the current project

Default: False

-na, --no-append

It True and the archive already exists, it is deleted

Default: False

-np, --no-project-paths

If True, paths outside the experiment directories are neglected

Default: False

-e, --exclude

Filename patterns to ignore (see glob.fnmatch.fnmatch())

-k, --keep

If True, the experiment directories are not removed and no modification is made in the configuration

Default: False

-rm, --rm-project

If True, remove all the project files

Default: False

-n, --dry-run

If True, set, do not actually make anything

Default: False

-L, --dereference

If set, dereference symbolic links. Note: This is automatically set for fmt=='zip'

Default: False

remove

Delete an existing experiment and/or projectname

model remove [-h] [-p [str]] [-a] [-y] [-ap]

Named Arguments

-p, --projectname

The name for which the data shall be removed. If set without, argument, the project will be determined by the experiment. If specified, all experiments for the given project will be removed.

-a, --all

If set, delete not only the experiments and config files, but also all the project files

Default: False

-y, --yes

If True/set, do not ask for confirmation

Default: False

-ap, --all-projects

If True/set, all projects are removed

Default: False