Source code documentation¶
parsim.core module¶
Main parsim classes and utility functions.
-
class
parsim.core.
Case
(name=None, path=None, **kwargs)¶ Bases:
parsim.core.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 thepath
to its storage on disk will then be constructed from thename
argument.The constructor extends the baseclass constructor.
- Parameters
-
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.- 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:
parsim.core.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, theStudy.collect()
method would like to process all cases of the study, even if the result file is missing for a particular case (raisingParsimCaseError
). 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:
parsim.core.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 thepath
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 thecreate
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 indata
dict attribute, if given.registry (list) – List of names of attributes to store on disk (by default, only the
data
andregistry
attributes are stored.
-
path
¶ Path to object directory.
- 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 attributedata
, 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. Theproject
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 itstype
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
-
class
parsim.core.
Project
(name=None, path=None, **kwargs)¶ Bases:
parsim.core.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. Theconfig
dict attribute is initialized with values fromDEFAULT_PROJECT_CONFIG
, and then modified by remaining keyword arguments (inconfig_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
orCase
. Returns reference toProject
, iftarget_arg
is empty.- Return type
-
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, returnNone
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.
-
class
parsim.core.
Study
(name=None, path=None, **kwargs)¶ Bases:
parsim.core.ParsimObject
Parsim Study class.
A
Study
instance holds information about a parameter study and contains one or more Cases. TheStudy
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 thepath
to its storage on disk will then be constructed from thename
argument.The constructor extends the baseclass constructor.
- Parameters
-
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 thedoe_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. Thedistr_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), orcase_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. Ifcsv
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. Ifget_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.
attempts to do the right thing anyway. (Otherwise) –
- 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:
parsim.doe.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:
parsim.doe.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:
parsim.doe.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:
parsim.doe.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:
parsim.doe.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:
parsim.doe.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,
number of levels will be used for all parameters. Defaults to two levels, same as ff2n. (this) –
Example – “levels=2,2,3,3”
-
class
parsim.doe.
gsd
(distr_dict, **kwargs)¶ Bases:
parsim.doe.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,
number of levels will be used for all parameters. Defaults to two levels, same as ff2n. (this) –
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:
parsim.doe.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:
parsim.doe.RandomSamplingScheme
Monte Carlo random sampling.
- Keyword Arguments
n (int) – Number of samples (default: 10)
-
class
parsim.doe.
pb
(distr_dict, **kwargs)¶ Bases:
parsim.doe.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)