Source code documentation

parsim.core module

Main parsim classes and utility functions.

class parsim.core.Case(name=None, path=None, **kwargs)

Bases: ParsimObject

Parsim Case class.

A Case instance holds information about a case, created from a model template.

A Case is usually identified by its name, and the path to its storage on disk will then be constructed from the name argument.

The constructor extends the baseclass constructor.

Parameters:

project (Project) – Reference to parent Project instance.
name (str) – Name of the case.
study (Study) – Reference to parent Study instance, if any (otherwise None).

project

Reference to parent Project instance.

Type:: Project

study

Reference to parent Study instance (if any).

Type:: Study

collect(input=None, parameters=None)

Collect results from the case.

Parameters:

input (list) – List of names of results files to process (could also be string of single file name).
parameters (list) – List of input parameter columns to include in output table.

Returns:

Tuple containing dict of name and value of result variables (output_dict) and dict of name and value of input parameters to include in output table (param_dict).

Return type:

(dict, dict)

create(description=None, template=None, user_parameters=None, caselist_parameters=None, default_parameters=None)

Create a new Case object.

Parameters:

description (str) – Optional description of case.
template (str) – Name of (or path to) model template used for Cases of the Study.
user_parameters (dict) – Dict of parameters common to all cases.
caselist_parameters (dict) – Dict of parameters read from Study caselist.
default_parameters (dict) – Dict of default parameters (constructed here, if not provided by parent Study).

get_env()

Create and return dict with parsim-related information about the case.

These key-value pairs can be sent along as extra parameters on case creation, or injected into “run” subprocess as environment variables.

Returns:: parsim-related case information
Return type:: dict

info(create_log=False): Show some basic information about the case.

load()

Loads object data from an object data file on disk.

The object must, of course, already exist on disk.

property parameters: Getter returning pandas DataFrame containing value and source of all parameters.

property results: Getter returning pandas Series containing all results collected for the case

run(executable, args='', sub_dir=None, out=None, err=None, shell=False)

Run executable on the case.

If executable is an absolute path to an existing file, this file is called. Otherwise an excutable is looked for in the following locations (in order): Current working directory (where psm run is called), case directory, case bin directory, case subdirectory (if sub_dir is specified), project bin directory. Note that the case directory is searched before the project bin directory, so that case-specific executables will be found before project-level ones. The executable will always be called with its absolute path; parsim will not find an executable in the search path of the the current OS shell.

Parameters:

executable (str) – Name or path of executable to run.
args (list) – List of string arguments to executable.
sub_dir (str) – Relative path to Case subdirectory in which to run the executable (default is to run the in the root of the Case directory).
out (str) – Optional custom name of output file.
err (str) – Optional custom name of error file.
shell (bool) – Flag used by the subprocess call (whether to run executable in OS shell, or directly).

parsim.core.DEFAULT_PROJECT_CONFIG = {'case_prefix': 'case_', 'dakota_exe': 'dakota', 'default_executable': None, 'default_parameter_file': 'default.parameters', 'default_results_file': 'results.json', 'default_template': 'default', 'log_level': 'info', 'psm_ignore_file': '.psmignore', 'psm_ignore_patterns': ['default.parameters', '.psm*', '.git*', '.svn*', '*~'], 'python_exe': 'python', 'study_prefix': 'study_', 'template_root': 'modelTemplates'}: Default config settings for Parsim projects.

exception parsim.core.ParsimCaseError(*args, **kwargs)

Bases: ParsimError

Error in operation on case, which may affect only this particular case.

Raising this exception, rather than ParsimError, would allow an outer exception handler to continue. For example, the Study.collect() method would like to process all cases of the study, even if the result file is missing for a particular case (raising ParsimCaseError). Other cases may still be ok!

exception parsim.core.ParsimError(*args, **kwargs)

Bases: Exception

Baseclass for Parsim exceptions.

The keyword argument handled may be set, if the the error has already been handled, in the sense that information has been given to the user. This is to avoid duplicate output if the exception is captured and handled by outer handler.

Parameters:: handled (bool) – Set to true if exception already reported to user. Defaults to False.

handled

Flag to show if exception already reported to user.

Type:: bool

exception parsim.core.ParsimExpanderError(*args, **kwargs)

Bases: ParsimError

Exception raised inside pyExpander library.

class parsim.core.ParsimObject(name=None, path=None, **kwargs)

Bases: object

Baseclass for all Parsim objects (projects, cases and studies).

A ParsimObject is uniquely identified by its path on disk. Unless the path is given with the path argument, a path can be constructed from an object name.

If the object exists on disk, its data will be automatically loaded from the object data file (with the load method). Otherwise an empty object is created by the constructor, but its data will have to be initialized by a separate call to the create method.

Parameters:

path (str) – Path to object directory. Mandatory, unless the path attribute has already been set by the subclass constructor before calling the baseclass constructor.
name (str) – Name of object. Used for name value in data dict attribute, if given.
registry (list) – List of names of attributes to store on disk (by default, only the data and registry attributes are stored.

path

Path to object directory.

Type:: str

_parent_object_path

Path to parent object (Study or Project).

Type:: str

_parent_object_type

Type of parent object

Type:: str

_psm_path

Path to object storage subdirectory (inside object directory).

Type:: str

_data_file

Name of data file for object data storage.

Type:: str

_logger

Logger instance of this object.

Type:: logging.Logger

_logger_name

Name of object logger instance.

Type:: str

_logger_file

File used by logger file handler.

Type:: str

exists

Flag is True is object exists on disk.

Type:: bool

open

Flag is True if logger file is open and/or (?) object data not saved.

Type:: bool

registry

List of object attributes to save to and load from disk storage.

Type:: list

data

Dict for storage of object data.

Type:: dict

add_comment(msg)

Add user comment to object event log.

Parameters:: msg (str) – Comment text string for event log.

close()

Closes the object.

Closing the object means its data is written to the object data file on disk and the object logger is closed.

create(name=None, description=None, noSave=False, onlySave=False)

Create new object.

ParsimObject creation is made separate from the object instantiation. The object is complete only when this creation step is done, and this is when the object is written to disk.

Parameters:

name (str) – Sets name value in dict attribute data, if provided.
description (str) – Optional description of the object.

delete(force=False, logging=True)

Delete the object’s directory from disk, including all its contents.

Parameters:

force (bool) – Forces deletion without interactive query, also if the object actually exists and seems to correctly created. Default is to ask for confirmation if the the object’s exist attribute is True.
logging (bool) – Argument currently not used…

Returns:

Returns True if delete is successful. Returns False if the object’s directory path does not exist, or if an error occurred.

Return type:

bool

find_parent_object_path(p=None, project=False)

Find path to an object’s parent object, if any.

Most ParsimObjects live in the directory of a parent object. For example, a Study lives in a Project directory, and a Case lives either in a Project directory, or it is part of a Study.

This function will move back up through the directory tree, until a parent ParsimObject is found. The project argument can be set if we want to find the Parsim Project.

Parameters:

p (str) – Optional path to the child object, whose parent we seek. By default, the present object is the child.
project – If True, the function will look for the Project to which the object belongs.

Returns:

If a parent is found, returns tuple of path of parent object and its type attribute. If not no parent is found, returns (None, None).

Return type:

(str, str)

get(key)

Get a value from the object data attribute dictionary.

Parameters:: key (str) – Dictionary key.
Returns:: Dictionary value.

info()

Create text with basic object information.

Returns:: Line-wrapped text with object information.
Return type:: str

load()

Loads object data from an object data file on disk.

The object must, of course, already exist on disk.

log()

Return contents of event log.

Returns:: Contents of logger file.
Return type:: str

save(silent=False)

Save the object to its object data file on disk.

The object attributes to save are those named in the object’s registry attribute.

set(key, value)

Set a key-value pair in the object data attribute dictionary.

Parameters:

key (str) – Dictionary key.
value – Dictionary value.

class parsim.core.Project(name=None, path=None, **kwargs)

Bases: ParsimObject

Parsim Project class.

A Project instance holds information about the Project and the project directory. The project directory is the root directory for all cases and studies of the project.

The constructor extends the baseclass constructor.

Parameters:: path (str) – Path to project directory. If not provided, the current directory is used.

config

Dictionary containing configuration settings for the project.

Type:: dict

create(name=None, description=None, **config_dict)

Create new Project object.

Extends baseclass ParsimObject method. Sets description, if given as keyword argument. The config dict attribute is initialized with values from DEFAULT_PROJECT_CONFIG, and then modified by remaining keyword arguments (in config_dict). Creates directories for template root and default template, if missing.

Parameters:

name (str) – Mandatory name of project.
description (str) – Description of project
**config_dict – Dict of keyword arguments.

delete(force=False, logging=True)

Delete the object’s directory from disk, including all its contents.

Projects can only be deleted manually – ABORT…

Parameters:

force (bool) – Forces deletion without interactive query, also if the object actually exists and seems to correctly created. Default is to ask for confirmation if the the object’s exist attribute is True.
logging (bool) – Argument currently not used…

Returns:

Returns True if delete is successful. Returns False if the object’s directory path does not exist, if the object is a ParsimProject, or if an error occurred.

Return type:

bool

find_target(target_arg)

Process a command-line target argument and generate ParsimError if invalid.

Parameters:: target_arg (str) – A string identifying a “target”. This could be a single case or a study. It could also be a single case within a study; if so, both study and case names are provided, separated by a colon “:”. For example, s2:c1 identifies the case “c1” of study “s2”.
Returns:: Reference to target Study or Case. Returns reference to Project, if target_arg is empty.
Return type:: ParsimObject

find_target_path_and_type(name)

Find an existing case or study directory path, based on given name.

The target could be either a case, or a study. Returns both path and type, if it finds a unique target.

Parameters:: name (str) – Name of target to look for, which could be a case or a study.
Returns:: If a unique target (case or study) is found, returns tuple (path, type) with both path and object type string (‘case’ or ‘study’). If both a case and study exists with the given name, return None path and type ‘both’. Returns (None, None) if no target is found.
Return type:: (str, str)

get_case_path(case_id, study=None, only_existing=False)

Construct path to case directory, based on a case_id (the name of the case).

Parameters:

case_id (str) – Case ID, i.e. the name of the case.
study (ParsimStudy) – Reference to parent Study instance.
only_existing (bool) – If set, return path only if the case exists.

Returns:

Path to case directory. Return None if only_existing argument is set and the case does not exist.

Return type:

str

get_study_path(name, only_existing=False)

Construct path to study directory, based on name of study.

Parameters:

name (str) – Name of the study.
only_existing (bool) – If set, return path only if the study exists.

Returns:

Path to study directory. Return None if only_existing argument is set and the study does not exist.

Return type:

str

get_template_path(template)

Search several locations for a valid model template.

Several locations are searched, in the following order:

Current directory (only if template name is provided)

Project template directory

Default template, inside project template directory

Parameters:: template (str) – Name of model template
Returns:: Path to model template directory.
Return type:: str

info(): Show some basic information about the project.

load()

Loads object data from object data file on disk.

Extends baseclass ParsimObject method by setting a log level according to Project config settings.

modify(**config_dict)

Modify project config settings.

Keyword arguments will update project config attribute.

Parameters:: **config_dict – Dict of keyword arguments.

class parsim.core.Study(name=None, path=None, **kwargs)

Bases: ParsimObject

Parsim Study class.

A Study instance holds information about a parameter study and contains one or more Cases. The Study has a dict of parameters common to all cases (can be represented as a Parsim parameter file). It will also have a caselist defining the parameter values that vary between cases of the Study.

A Study is usually identified by its name, and the path to its storage on disk will then be constructed from the name argument.

The constructor extends the baseclass constructor.

Parameters:

project (Project) – Reference to parent Project instance.
name (str) – Name of the parameter study.
path (str) – Path to the Study on disk. If absent (common), the path is constructed from the name argument.

project

Reference to parent Project instance.

Type:: Project

property caselist: Getter returning pandas DataFrame with the Study caselist (all varying parameters).

collect(**kwargs)

Collect results from all cases of the study.

Iterates over all cases of the study and calls the Case.collect method of each.

Parameters:: **kwargs (dict) – Dict of keyword arguments to forward.

create(description=None, template=None, user_parameters=None, caselist_file=None, doe_scheme=None, doe_args=None, distr_dict=None)

Create a new Study object.

Extends the baseclass method. This method provides two ways to generate Cases for Study; either the path of a caselist file is provided with the caselist_file option, or a DOE scheme is defined with the doe_scheme option. These two options are mutually exclusive. If none of them are provided, an empty Study (without cases) will be created, and the information about model template and user parameters is stored. (An empty Study is used when Parsim is run as an interface to Dakota.)

If a DOE scheme is given, a dict with additional DOE options can be provided with the doe_args argument. The distr_dict argument should then be a dict defining statistical distributions for all uncertain parameters.

Parameters:

description (str) – Optional description of parameter study.
template (str) – Name of (or path to) model template used for Cases of the Study.
user_parameters (dict) – Dict of parameters common to all cases.
caselist_file (str) – Path to caselist file with case and parameter definitions.
doe_scheme (str) – Name of DOE scheme to use for case creation.
doe_args (dict) – Dict of arguments to the DOE scheme.
distr_dict (dict) – Dict of distributions for uncertain parameters.

info(create_log=False): Show some basic information about the study.

next(): Iterator function (proxy for __next__, for Python 3 compatibility).

property parameters: Getter returning pandas DataFrame containing value and source of all parameters.

property results: Getter returning pandas DataFrame with the last collected results of the Study.

run(executable, **kwargs)

Run executable on all cases of the study.

Iterates over all cases of the study and calls the Case.run method of each.

Parameters:

executable (str) – Name or path of executable to run.
**kwargs (dict) – Dict of keyword arguments to forward.

run_dakota(dakota_file=None, executable=None, pre_run=False, restart=False, restart_index=-1, stop_restart=0, shell=False)

Run Dakota in this Study.

Runs Dakota inside the study (already created with the create method). The Dakota input file…

Parameters:

dakota_file (str)
executable (str)
pre_run (bool)
restart
restart_index (int)
stop_restart (int)
shell (bool)

parsim.core.create_caselist_file(output_path, case_names, column_dict=None, case_dicts=None, parameter_names=None, csv=None)

Create and write a case list to a specified file (output_path).

Case names are supplied in a separate list (case_names). Parameter names may optionally be supplied in a list (parameter_names), to control the order of the parameter columns, or to output only a subset of the available parameters; default is to output all available parameters, in arbitrary order.

Case parameter data are specified in one of two ways: Either column_dict is a dict from parameter name to list (vector) of values (one value per case), or case_dicts is a list of dicts from parameter name to value (one dict per case).

Parameters:

output_path (str) – Path to output file.
case_names (list) – List of case names (output in first column, “CASENAME”)
column_dict (dict) – Dict from parameter name to list of values (one value per case).
case_dicts (list) – List of dicts from parameter name to value (one dict per case). Arguments column_dict and case_dicts are mutually exclusive.
parameter_names (list, optional) – List of parameter names to output.
csv (bool, optional) –
Flag to request output in CSV format.

Default (False) is to output in fixed-width whitespace-separated columns. If csv is one of the characters “,;%|#”, this will be used as separator. If csv is any other boolean “True” value, “;” is used as separator.

parsim.core.create_parameter_file(output_path, parameters, parameter_names=None)

Create and write a parameter file to a specified file (output_path).

Parameter definitions are specified as dictionary (parameters).

Parameter names may optionally be supplied in a list (parameter_names), to control the order of the parameters in the output, or to output only a subset of the available parameters; default is to output all available parameters, in arbitrary order.

Parameters:

output_path (str) – Path to output file.
parameters (dict) – Dictionary with parameter/value pairs.
parameter_names (list) – List of parameter names, to control order of parameters in output.

parsim.core.find_file_path(filename, *places)

Search for filename in list of possible paths and return full path to the file.

Parameters:

filename (str) – Name of file to search for.
*places (str) – Variable length argument list of paths to search.

Returns:

Full path to file.

Return type:

str

parsim.core.parse_caselist_file(file_name)

Parse a caselist file (or Dakota annotated file) and return case definitions.

Returns case definitions as a list of tuples. The first tuple element is the case name, and the second is a dictionary of parameters.

Parameters:: file_name (str) – Path to input file.
Returns:: Case definitions as a list of tuples. First tuple element is case name and the second a dict of parameters.
Return type:: list((str, dict))

parsim.core.parse_parameter_file(file_path, get_comments=False, doe=False)

Parse parameter file and return dict with parameters (and perhaps comments).

If called with the doe flag set, tries to interpret un-resolved parameter definitions as distributions.

Parameters:

file_path (str) – Path to parameter file.
get_comments (bool) – If True, return also comments at end of lines.
doe (bool) – If True, try to interpret un-resolved parameter definitions as distributions of uncertain parameters.

Returns: Returns dict of parameter values. If doe is True, return tuple with dict of parameter distributions as second item. If get_comments is True, returns tuple with dict of comments as last item.

parsim.dakota module

class parsim.dakota.DakotaVariables(filepath)

Bases: object

Class of Dakota variables file.

Parameters:: filepath (str) – Path to input file to read.

parsim.dakota.key_value(line, type=None)

Parse key-value pair from line read from Dakota input file.

Parameters:

line (str) – Text line to parse.
type (str) – Optional string {‘int’, ‘float’, ‘str’} to indicate expected value type.
anyway. (Otherwise attempts to do the right thing)

Returns:

Tuple of key and value (key is string, but value could be int, float or str).

Return type:

(str, value)

parsim.dakota.psm_dakota_driver(): Analysis driver for Dakota fork interface under parsim.

parsim.doe module

class parsim.doe.FactorLevelScheme(distr_dict, **kwargs)

Bases: SamplingScheme

Subclass for sampling factors at certain levels.

log_message(): Return log message for the sampling operation.

sampling_method = 'levels'

class parsim.doe.RandomSamplingScheme(distr_dict, **kwargs)

Bases: SamplingScheme

Subclass for random sampling of distributions through their Cumulative Distribution Function (CDF).

log_message(): Return log message for the sampling operation.

sampling_method = 'cdf'

class parsim.doe.SamplingScheme(distr_dict, **kwargs)

Bases: object

Baseclass for sampling schemes, used for creating parsim Study cbjects.

Parameters:

distr_dict (dict) – Dict of distribution definitions for varying parameters.
kwargs (dict) – Dict of keyword arguments for sampling schemes.

add_required_args(args)

Add variable name to list of required arguments for the scheme.

Parameters:: args (str) – Name of argument.

add_valid_args(args)

Add variable name to list of valid arguments for the scheme.

Parameters:: args (str) – Name of argument.

get(*key)

Get value from object dictionary.

Parameters:: *key (list) – List of arguments; first argument is key name, second holds optional default value.
Returns:: Value of dictionary value.
Return type:: value

get_case_definitions(): Output list of tuples (case_id, case_dict)

classmethod help_message()

Return help message for this sampler class, based on subclass docstring.

Docstring should describe sampling method and all options.

log_message(): Return log message for the sampling operation.

sampling_method = None

set(key, value)

Sets value in object dictionary.

Parameters:

key (str) – Name of variable.
value – Value of variable.

write_caselist(filename)

Construct and write caselist to file. Not yet implemented.

Parameters:: filename (str) – Name of caselist to write.

write_norm_matrix(filename)

Write norm_matrix to file.

Parameters:: filename (str) – Name of output file.

write_value_matrix(filename)

Write value_matrix to file.

Parameters:: filename (str) – Name of output file.

class parsim.doe.ccdesign(distr_dict, **kwargs)

Bases: FactorLevelScheme

Central Composite Design (CCD).

The “face” keyword can be used to select one of three combinations of facial and corner points: ‘ccc’ for circumscribed (corner points are at nominal high/low levels, while facial points are outside (!) of these); ‘cci’ for inscribed (facial points are at nominal high/low levels, while corner points are inside of these); ‘ccf’ for faced (both corner and facial points are at nominal high/low levels). Contrary to pyDOE standard behavior, the parsim default is inscribed, ‘cci’, such that parameter values are guaranteed not to exceed the nominal high/low levels. If a circumscribed (‘ccc’) is defined, then beware that the facial points may lie far outside of the nominal high/low levels – make sure these extreme values are realistic and physically meaningful! This effect can be controlled to some extend by choosing a smaller value of the beta parameter, so that the nominal high/low levels are taken away from the tails/bounds of the parameter distributions.

The “alpha” keyword is used to define designs that are either orthogonal (value ‘o’), or rotatable (value ‘r’). Default is orthogonal, ‘o’. Note that both circumscribed and inscribed designs may be rotatable, but the faced design (‘ccf’) cannot.

The CCD method generates only one center point, since simulations are deterministic in nature. For regression analysis of the results, however, the center point should usually be replicated or weighted higher than the other points.

Keyword Arguments:

mapping (str) –
Selection of method for mapping high/low factor levels to actual values in the distribution.

’int’: (default) Use confidence interval with equal areas around the mean. Width of interval is given by parameter ‘beta’ (default: 0.9545)
beta (float) – Width of confidence interval for ‘int’ method (see above). Default: 0.9545 (+/- 2*sigma)
face (str) – Specifies combination of corner and facial points: ‘cci’ for inscribed (default), ‘ccc’ for circumscribed or ‘ccf’ for faced design.
alpha (str) – Selects whether design should be orthogonal (‘o’) or rotatable (‘r’). Default is orthogonal.

parsim.doe.docstring_first_line(obj)

Extract text from first line of object’s docstring.

Parameters:: obj (object) – Reference to object.
Returns:: Docstring text (first line).
Return type:: str

class parsim.doe.ff2n(distr_dict, **kwargs)

Bases: FactorLevelScheme

Two-level full factorial sampling.

Keyword Arguments:

mapping (str) –
Selection of method for mapping factor levels to actual values in the distribution.

’int’: (default) Use confidence interval with equal areas around the mean. Width of interval is given by parameter ‘beta’ (default: 0.9545)
beta (float) – Width of confidence interval for ‘int’ method (see above). Default: 0.9545 (+/- 2*sigma)

class parsim.doe.fracfact(distr_dict, **kwargs)

Bases: FactorLevelScheme

Two-level fractional factorial sampling.

A fractional factorial design reduces the number of runs, compared to a full factorial design, by confounding certain main factor effects with interaction effects. The confounding must be explicitly defined by the user, either by supplying a so-called generator expression with the “gen” keyword, or defining the resolution of the design with the “res” keyword (only one of these keywords should be used).

In addition, the resulting design may be folded (replicated with levels switched). The keyword “fold” specifies if folding should be applied, either an all columns (value “all”), or by listing which parameters to fold (comma-delimited list of parameter4 columns; first parameter is “1”). For example, “fold=1,3” to fold parameters one and three, or “fold=all” to fold the whole design.

Keyword Arguments:

mapping (str) –
Selection of method for mapping high/low factor levels to actual values in the distribution.

’int’: (default) Use confidence interval with equal areas around the mean. Width of interval is given by parameter ‘beta’ (default: 0.9545)
beta (float) – Width of confidence interval for ‘int’ method (see above). Default: 0.9545 (+/- 2*sigma)
gen (str) – Generator pattern, for example gen=’a,b,ab’ for three parameters. Note that the generator expression must be given as a quoted string, with columns delimited by commas rather than white-space.
res (int) – Resolution of the design, defined as an integer. Common values are 3, 4 or 5, depending on the number of parameters in the design.
fold (str) – Specify optional folding of design. “all” to fold all columns, or a comma-delimited list of columns to fold (starting with 1 for first column). For example, fold=’all’, or fold=1,3,5.

class parsim.doe.fullfact(distr_dict, **kwargs)

Bases: FactorLevelScheme

General full factorial sampling (for more than two levels).

The number of levels can be given individually for each parameters using the “levels” keyword argument. If a single integer is given, this is the number of levels used for all parameters.

Keyword Arguments:

mapping (str) –
Selection of method for mapping high/low factor levels to actual values in the distribution.

’int’: (default) Use confidence interval with equal areas around the mean. Width of interval is given by parameter ‘beta’ (default: 0.9545)
beta (float) – Width of confidence interval for ‘int’ method (see above). Default: 0.9545 (+/- 2*sigma)
levels (str) – Comma-delimited list of number of levels for each parameter. If only one integer is given,
ff2n. (this number of levels will be used for all parameters. Defaults to two levels, same as)
Example – “levels=2,2,3,3”

class parsim.doe.gsd(distr_dict, **kwargs)

Bases: fullfact

Generalized Subset Design (GSD)

GSD is a generalization of traditional fractional factorial designs to problems, where factors can have more than two levels.

In many application problems, factors can have categorical or quantitative factors on more than two levels. Conventional reduced designs have not been able to deal with such types of problems. Full multi-level factorial designs can handle such problems, but the number of samples quickly grows too large to be useful.

The GSD method provides balanced designs in multi-level experiments, with the number of experiments reduced by a user-specified reduction factor. Complementary reduced designs are also provided, analogous to fold-over in traditional fractional factorial designs.

The number of levels can be given individually for each parameter using the “levels” keyword argument. If a single integer is given, this is the number of levels used for all parameters. The “reduction” keyword is used to specify the reduction factor of the design; the reduction factor must be an integer larger than one (default is 2). The number of complementary designs is controlled by the “ncomp” keyword (default is 1, meaning only the original reduced design is used).

Keyword Arguments:

mapping (str) –
Selection of method for mapping high/low factor levels to actual values in the distribution.

’int’: (default) Use confidence interval with equal areas around the mean. Width of interval is given by parameter ‘beta’ (default: 0.9545)
beta (float) – Width of confidence interval for ‘int’ method (see above). Default: 0.9545 (+/- 2*sigma)
levels (str) – Comma-delimited list of number of levels for each parameter. If only one integer is given,
ff2n. (this number of levels will be used for all parameters. Defaults to two levels, same as)
Example – “levels=2,2,3,3”
reduction (int) – Size reduction factor, which must be an integer larger than one (default: 2)
ncomp (int) – Number of complementary designs (default: 1)

parsim.doe.help_message(sphinx=False)

Create help message for DOE sampling, listing all available samplers in this module.

Documentation is available from sampler classes docstrings.

Parameters:: sphinx (bool) – Set to True if called from Sphinx run.
Returns:: Help message description created from docstring.
Return type:: str

class parsim.doe.lhs(distr_dict, **kwargs)

Bases: RandomSamplingScheme

Latin Hypercube sampling.

Keyword Arguments:

n (int) – Number of sample points (default: one per parameter)
mode (str) –
String that tells lhs how to sample the points,

’rand’: Random within sampling interval (default),

’center’, ‘c’: Center within interval,

’maximin’, ‘m’: Maximize the minimum distance between points, but place the point in a randomized location within its interval,

’centermaximin’, ‘cm’: Same as ‘maximin’, but centered within the intervals,

’correlation’, ‘corr’: Minimize the maximum correlation coefficient.
iter (int) – Number of iterations (used by some modes; see pyDOE docs and code).

valid_modes = ['rand', 'center', 'c', 'maximin', 'm', 'centermaximin', 'cm', 'correlation', 'corr']

class parsim.doe.mc(distr_dict, **kwargs)

Bases: RandomSamplingScheme

Monte Carlo random sampling.

Keyword Arguments:: n (int) – Number of samples (default: 10)

class parsim.doe.pb(distr_dict, **kwargs)

Bases: FactorLevelScheme

Plackett-Burman (pbdesign).

Another way to generate fractional-factorial designs is through the use of Plackett-Burman designs. These designs are unique in that the number of trial conditions (rows) expands by multiples of four (e.g. 4, 8, 12, etc.). The max number of factors allowed before a design increases the number of rows is always one less than the next higher multiple of four.

Keyword Arguments:

mapping (str) –
Selection of method for mapping factor levels to actual values in the distribution.

’int’: (default) Use confidence interval with equal areas around the mean. Width of interval is given by parameter ‘beta’ (default: 0.9545)
beta (float) – Width of confidence interval for ‘int’ method (see above). Default: 0.9545 (+/- 2*sigma)