Parameters

class pvade.Parameters.SimParams(input_file_path=None)

Manages and validates all simulation parameters

SimParams provides a set of methods to obtain user-input values from both input files and the command line. It also provides input validation via a yaml schema file. All parameters can later be access from PVade objects like params.parent_group.option for example, params.solver.dt.

comm

An MPI communicator that will be shared by all PVade objects.

Type:: MPI Communicator

flat_schema_dict

A flattened dictionary version of the yaml schema file used to set default values and provide valid command-line options.

Type:: dict

input_dict

The aggregated input dictionary containing all command-line updated values and input-file values.

Type:: dict

input_file_dict

The dictionary representing the input file.

Type:: dict

num_procs

The total number of processors being used to solve the problem

Type:: int

rank

A unique ID for each process in the range [0, 1, …, num_procs-1]

Type:: int

schema_dict

The unflattened (nested) representation of the yaml schema dictionary.

Type:: dict

Create a SimParams object

This method begins by reading both the schema file and the user-specified file into dictionaries. It overrides entries in the user-specified dictionary with command-line inputs and finally validates the complete dictionary against the schema file.

Parameters:: input_file_path (str, optional) – The complete path to the input yaml file defining the problem.

_add_derived_quantities()

Add derived quantities for convenience

For convenience, it is helpful to store certain derived quantities in the SimParams object that are not explicitly provided by the user. For example, params.solver.t_steps is the integer number of steps implied by the user-provided entries for t_final and dt. Such derived and/or convenience quantities are accumulated here. Note that no error checking is performed on these values since they do not appear in the yaml schema file, the expectation being that valid quantities up till this point will result in valid derived values.

Parameters:: None

_flatten_schema_dict()

Flatten the schema dictionary

This method returns a flattened version of the schema dictionary where nested dictionary key:val pairs are separated with dots (.). For example:

general:
    name: test_sim
    size:
        x: 10
        y: 20

will be converted to:

general.name: test_sim
general.size.x: 10
general.size.y: 20

Parameters:: None

_initialize_params_to_default(override_existing=True)

Initialize values to default

This method uses the default entry associated with each parameter in the yaml schema to provide a sane value where none is supplied by the input yaml file.

Parameters:: None

_pprint_dict(d, indent=0)

Pretty print a dictionary

Print a dictionary where nesting is visualized with indentation. Useful for validation and debugging.

Parameters:

d (dict) – The dictionary to print
indent (int, optional) – The amount of indentation to use for this level, default=0

_rec_settattr(parent_obj, path_to_input, value, error_on_missing_key=True)

Convert nested dictionary to object.attribute format

This method recursively creates nested objects to hold attributes in the same manner as the nested dictionary.

Parameters:

parent_obj (object) – The parent object that will contain this value (self when first called)
path_to_input (list, str) – A list of strings containing the attribute names to be used at each level
value (int, float, object) – The value to store at the final level of nesting
error_on_missing_key (bool, optional) – A flag to raise an error if any of the keys or sub-keys is not already present

_set_nested_dict_value(parent_obj, path_to_input, value, error_on_missing_key=False, override_existing=True)

Set a nested value in a dictionary

This method uses the flattened path to a dictionary value to create the nested structure/path and then store the value.

Parameters:

parent_obj (dict) – The dictionary containing the value to be set
path_to_input (list, str) – A list of strings containing the key names to be used at each level
value (int, float, object) – The value to store at the final level of nesting
error_on_missing_key (bool, optional) – A flag to raise an error if any of the keys or sub-keys is not already present

_set_user_params_from_cli()

Store values from command line

This method uses the flattened schema dictionary, where nested options are stored as a one-layer dictionary with keys separated by dots (.), to generate a set of valid command line inputs that can be used to override options that would otherwise be set by the input yaml file or defaults. For example:

python main.py --solver.dt 0.01

will override whatever value of dt is present in the yaml file with the value 0.01. Note the double hyphen to set off an argument name, either with or without the assignment operator is allowed (e.g., both --solver.dt 0.01 and --solver.dt=0.01 are valid)

Parameters:: None

_set_user_params_from_file()

Store the input-file supplied values

This method stores the parameters supplied via input yaml file in the aggregated input dictionary.

Parameters:: None

_store_dict_as_attrs()

Converts dictionary notation to nested object attributes

This method re-structures the parameters dictionary into the slightly easier-to-navigate object.attribute format. For example, rather than having a parameters dictionary and accessing entries like params['general']['name'], we create a parameters object with attributes accessed like params.general.name.

Parameters:: None

_validate_inputs()

Validate the input dictionary

This method uses the validate function from the jsonschema package to validate the complete user-supplied parameter set. This checks that variables are the expected type, fall within prescribed ranges, and also ensure that dependencies between variables are satisfied (e.g., if variable a is specified, then variable b must also be specified.)

Parameters:: None