Command-line reference¶
Parsim is a command-line tool. The command-line client program is called psm.
The general syntax is
psm [-h] SUBCOMMAND [<arguments>]
The available subcommands are described in the following sections.
Use option -h
to get information about available subcommands.
You get detailed information about each subcommand using the command psm help <subcommand>,
or psm <subcommand> -h.
-
-h
,
--help
¶
Show help message, including available subcommands, and exit.
-
SUBCOMMAND
[<arguments>]
¶ Parsim subcommand (see below), with arguments.
Project initialization and configuration¶
Before Parsim can be used with your project, your project directory must be initialized using the psm init command. Most of the configurations settings may be changed later using the psm config command.
psm init¶
Create a new project called NAME in the current directory. This stores some metadata and configuration settings for the project. There are sensible defaults for all settings, and most of them can be changed later using the psm config command.
usage: psm init [-h] [--description DESCRIPTION]
[--default_executable EXECUTABLE] [--template_root DIRECTORY]
[--default_template DIRECTORY]
[--default_parameter_file FILENAME]
[--log_level {debug,info,warning,error}]
[--config PARAMETER=VALUE]
NAME
Positional Arguments¶
- NAME
a short name for the project; should not contain spaces.
Named Arguments¶
- --description, -m
Project description (text in quotes)
- --default_executable
Name/path of default executable for the “run” command
- --template_root
Path to directory where model templates are stored
- --default_template
Name of default model template to replicate (a directory). A relative path is searched for in the current and in the template root directory. Could also be an absolute path.
- --default_parameter_file
Name of parameter file holding default parameter definitions. The default name is “default.parameters”, located in the model template directory.
- --log_level
Possible choices: debug, info, warning, error
Set log-level for logging. The default is “info”. This value is stored in the project settings.
- --config, -c
Definition of project configuration name=value pairs. Could be a comma-separated list of name/value pairs. (Explicit config options (above) have precedence.)
Note
When configuration settings containing strings are defined using the --config
option,
the whole option argument string must be enclosed in quotes. The string value itself must also
be quoted. For example, the following option will correctly set the value of the default_executable
setting:
psm init --config 'default_executable="myScript.sh"' myProject
psm config¶
Modify the settings for the current project.
usage: psm config [-h] [--description DESCRIPTION]
[--default_executable EXECUTABLE]
[--template_root DIRECTORY] [--default_template DIRECTORY]
[--default_parameter_file FILENAME]
[--log_level {debug,info,warning,error}]
[--config PARAMETER=VALUE]
Named Arguments¶
- --description, -m
Project description (text in quotes)
- --default_executable
Name/path of default executable for the “run” command
- --template_root
Path to directory where model templates are stored
- --default_template
Name of default model template to replicate (a directory). A relative path is searched for in the current and in the template root directory. Could also be an absolute path.
- --default_parameter_file
Name of parameter file holding default parameter definitions. The default name is “default.parameters”, located in the model template directory.
- --log_level
Possible choices: debug, info, warning, error
Set log-level for logging. The default is “info”. This value is stored in the project settings.
- --config, -c
Definition of project configuration name=value pairs. Could be a comma-separated list of name/value pairs. (Explicit config options (above) have precedence.)
Creation of cases and studies¶
Individual cases can be created using the psm case command, while entire case studies are created using the psm study command.
Case studies can also be created with the psm doe command. The DOE (Design Of Experiments) functionality uses built-in sampling algorithms to generate the parameter matrix, rather than reading it from a caselist.
psm case¶
Create a new case, named from CASE_ID.
A case is created from a model template. A template is a directory, whose content will be replicated recursively to form a new case. During replication, all files with extension “.macro” are assumed to be parameterized. These files are processed for macro expansion, in which parameter names are replaced by actual values. The processed files have the same name, but without the “.macro” extension. Parameter values can be specified on the command line directly (with the –define option), or in a PARAMETER_FILE. A model template usually defines default variables for all its parameters.
usage: psm case [-h] [--description DESCRIPTION] [--template TEMPLATE]
[--parameters PARAMETER_FILE] [--define PARAMETER=VALUE]
CASE_ID
Positional Arguments¶
- CASE_ID
Name used to form the case directory name.
Named Arguments¶
- --description, -m
Description of case or study (text in quotes)
- --template, -t
Name of the model template. This is either an absolute directory path, a path relative to the current directory, or a directory inside the template root directory of the parsim project.
- --parameters, -p
Name of a parameter file (absolute path, or relative to the current directory)
- --define, -D
Definition of parameter name=value pairs. Could be a comma-separated list of name/value pairs. Overrides values in a parameter file.
Note
When string values are defined for parameters using the --define
option,
the whole option argument string must be enclosed in quotes. The string value itself must also
be quoted. For example, when creating a case A13
, the following option will correctly set
the value of the output_file
parameter to out.txt
:
psm case --template box --define 'output_file="out.txt"' A13
psm study¶
Create cases in a case study, as defined by the records in the CASELIST file.
A case is created from a model template. A template is a directory, whose content will be replicated recursively to form a new case. During replication, all files with extension “.macro” are assumed to be parameterized. These files are processed for macro expansion, in which parameter names are replaced by actual values. The processed files have the same name, but without the “.macro” extension. Parameter values can be specified on the command line directly (with the –define option), or in a PARAMETER_FILE. A model template usually defines default variables for all its parameters.
When a case study is created, case-specific values for the parameters are given in a CASELIST_FILE. Values in the caselist override values given on the command line.
usage: psm study [-h] [--description DESCRIPTION] [--template TEMPLATE]
[--parameters PARAMETER_FILE] [--define PARAMETER=VALUE]
[--name STUDY_NAME]
CASELIST
Positional Arguments¶
- CASELIST
Name of the caselist file, which defines case-specific parameter values.
Named Arguments¶
- --description, -m
Description of case or study (text in quotes)
- --template, -t
Name of the model template. This is either an absolute directory path, a path relative to the current directory, or a directory inside the template root directory of the parsim project.
- --parameters, -p
Name of a parameter file (absolute path, or relative to the current directory)
- --define, -D
Definition of parameter name=value pairs. Could be a comma-separated list of name/value pairs. Overrides values in a parameter file.
- --name, -n
Name used to form the study directory name. By default, the study directory is named from the CASELIST file name.
psm doe¶
Create cases in a case study, based on a sampling scheme and parameter definitions.
A case is created from a model template. A template is a directory, whose content will be replicated recursively to form a new case. During replication, all files with extension “.macro” are assumed to be parameterized. These files are processed for macro expansion, in which parameter names are replaced by actual values. The processed files have the same name, but without the “.macro” extension. Parameter values can be specified on the command line directly (with the –define option), or in a PARAMETER_FILE. A model template usually defines default variables for all its parameters.
When a DOE (Design Of Experiments) study is created, a sampling scheme is used to generate the caselist for the study. Parameters are defined in a parameter file, where statistical distributions are specified for the uncertain variables. Other parameters are given constant values.
usage: psm doe [-h] [--description DESCRIPTION] [--template TEMPLATE]
[--define PARAMETER=VALUE] [--name STUDY_NAME]
PARAMETER_FILE DOE_SCHEME [DOE_ARGS [DOE_ARGS ...]]
Positional Arguments¶
- PARAMETER_FILE
Name of the parameter file (absolute path, or relative to the current directory) defining constant parameter values, as well as statistical distributions for uncertain parameters.
- DOE_SCHEME
Valid DOE sampling scheme, for example “mc” (Monte Carlo) or “lhs” (Latin Hypercube Sampling.
- DOE_ARGS
Valid arguments for the chosen DOE sampling scheme
Named Arguments¶
- --description, -m
Description of case or study (text in quotes)
- --template, -t
Name of the model template. This is either an absolute directory path, a path relative to the current directory, or a directory inside the template root directory of the parsim project.
- --define, -D
Definition of parameter name=value pairs. Could be a comma-separated list of name/value pairs. Overrides values in a parameter file.
- --name, -n
Name used to form the study directory name. By default, the study directory is named from the PARAMETER_FILE file name.
To get help on an individual sampling scheme, search help for the doe command and add name of scheme. For example:
psm help doe <scheme>
or
psm doe -h <scheme>
The following table shows the currently implemented DOE schemes.
mc |
Monte Carlo random sampling. |
ff2n |
Two-level full factorial sampling. |
fullfact |
General full factorial sampling (for more than two levels). |
fracfact |
Two-level fractional factorial sampling. |
ccdesign |
Central Composite Design (CCD). |
lhs |
Latin Hypercube sampling. |
pb |
Plackett-Burman (pbdesign). |
gsd |
Generalized Subset Design (GSD) |
psm dakota¶
Create a study and start a Dakota process in it.
A case is created from a model template. A template is a directory, whose content will be replicated recursively to form a new case. During replication, all files with extension “.macro” are assumed to be parameterized. These files are processed for macro expansion, in which parameter names are replaced by actual values. The processed files have the same name, but without the “.macro” extension. Parameter values can be specified on the command line directly (with the –define option), or in a PARAMETER_FILE. A model template usually defines default variables for all its parameters.
When a Dakota study is created, an empty study is created and control is then handed over to Dakota. Dakota uses a built-in Parsim analysis driver interface to create, run and evaluate successive cases needed for the Dakota simulation task. The Dakota simulation task is configured in the Dakota input file supplied on the command line.
usage: psm dakota [-h] [--description DESCRIPTION] [--template TEMPLATE]
[--parameters PARAMETER_FILE] [--define PARAMETER=VALUE]
[--name STUDY_NAME] [--restart [INDEX]] [--stop_restart N]
[--pre_run]
DAKOTA_INPUT EXECUTABLE
Positional Arguments¶
- DAKOTA_INPUT
Path to Dakota input file.
- EXECUTABLE
Name of executable, or path to it (named executable will be searched for)
Named Arguments¶
- --description, -m
Description of case or study (text in quotes)
- --template, -t
Name of the model template. This is either an absolute directory path, a path relative to the current directory, or a directory inside the template root directory of the parsim project.
- --parameters, -p
Name of a parameter file (absolute path, or relative to the current directory)
- --define, -D
Definition of parameter name=value pairs. Could be a comma-separated list of name/value pairs. Overrides values in a parameter file.
- --name, -n
Name used to form the study directory name. By default, the study directory is named from the DAKOTA_INPUT file name.
- --restart
Perform a restart of failed Dakota run. An extra integer index argument specifies which of successive restart files to use. “0” selects the orginal run; the default is to use the latest restart file created.
- --stop_restart
Integer -stop_restart option sent to Dakota if restart requested.
Default: 0
- --pre_run
Only create study with cases according to Dakota method, using the Dakota -pre_run option. No script execution.
Default: False
Operations on cases and studies¶
The following subcommands perform specific operations on a specified target, which may be a either a case or a study. In particular, the psm run command is used to execute scripts (or other executables) on a specific case, or on all cases of a study.
The target can be either a case or a study. Based on the name provided, the current directory is searched
for a matching case or study directory.
In case both a case and study is found, an error is issued. If this happens, please specify the full name of
the directory instead (starting with either case_
or study_
).
It is possible to specify an individual case belonging to a study, by specifying both study and case names,
separated by a colon. For example, the following will print detailed information about the case A1
, which
is part of the study test_matrix
:
psm info test_matrix:A1
Some commands, like psm info and psm comment, can operate also on the project as a whole.
If no TARGET
argument is specified, the current project is used as the target.
psm run¶
Execute script or executable in specified case, or in each case of a study.
usage: psm run [-h] [--sub_dir SUBDIR] [-o OUTFILE] [-e ERRFILE] [--shell]
TARGET EXECUTABLE ...
Positional Arguments¶
- TARGET
Name of target (case or a study)
- EXECUTABLE
Name of executable, or path to it (named executable will be searched for)
- ...
Additional arguments forwarded to the executable command-line
Named Arguments¶
- --sub_dir, -d
Case subdirectory to run in (otherwise the case root)
- -o
Name of file for redirection of stdout
- -e
Name of file for redirection of stderr
- --shell
Run executable through a shell (see Python subprocess module)
Default: False
psm collect¶
Collect results (json format) from all cases of a study and create text table.
usage: psm collect [-h] [--input INFILE] [--output OUTFILE] [--delim CHAR]
STUDY
Positional Arguments¶
- STUDY
Name of study
Named Arguments¶
- --input, -i
Name of case file(s) containing results in json format. Multiple comma-delimited file names allowed. (Default: “results.json”)
- --output, -o
Name of output file (default derived from name of input file)
- --delim
Field delimeter (default is white-space with fixed column width)
psm info¶
Print information about the specified target (case or study), or current project (no target).
usage: psm info [-h] [TARGET]
Positional Arguments¶
- TARGET
Name of target (case or a study). If missing, the current project is assumed.
psm log¶
Print event log of specified target (case or study), or current project (no target).
usage: psm log [-h] [TARGET]
Positional Arguments¶
- TARGET
Name of target (case or a study). If missing, the current project is assumed.
psm comment¶
Write user comment to the event log of the specified target (case or study), or current project (no target).
usage: psm comment [-h] [TARGET] comment
Positional Arguments¶
- TARGET
Name of target (case or a study). If missing, the current project is assumed.
- comment
user comment to add to the event log