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
the root directory specified in the configuration files (if the project exists in it) and replace_project_config is False
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