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.

Available 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