hyvr.input package

Submodules

hyvr.input.option_parsing module

This module contains the classes hyvr.input.option_parsing.Section and hyvr.input.option_parsing.Option to simplify parsing and validating input-files (*.ini).

Every HyVR option should have a corresponding instance of an Option, which is defined in hyvr.input.options in the options lists. These option lists are then assigned to Section instances in hyvr.input.parameters.parse_inifile().

If you add functionality to HyVR, you most likely only have to add an option to the option lists, normally you don’t have to change anything in here (at least if you’re lucky, since this is a very recursive mess).

Author

Samuel Scherrer

class hyvr.input.option_parsing.Section(name, options)

Bases: object

A Section instance corresponds to a section in an ini-file.

A section is mainly a wrapper for a list of options, and therefore only has a name and a list of options. Upon parsing a section, it checks whether all given options in the inifile are actually expected, and then delegates the parsing of single options to the Option class.

parse(section_dict)

Parses and validates options of the section given a dictionary containing key-value pairs of the options. If options are not present, default values might be set.

Parameters

section_dict (dictionary) –

Dictionary of section values. This can for example be obtained using configparser:

p = configparser.ConfigParser()
p.read(filename)
section_dict = dict(p[section_name])

Returns

section_dict – The same dictionary with parsed and validated values

Return type

dictionary

class hyvr.input.option_parsing.Option(name, dtype, optional=False, default=None, shape=-1, datatype=None, validation_func=<function Option.<lambda>>, alternatives=[])

Bases: object

An Option instance is basically a parser for a specific option in a ini-file.

An Option is typically part of a Section, and normally parse() is called by the Section it belongs to. The main tasks of an Option instance is to parse an option and make sure it has the right type, and in the case of lists, the right shape. Below is a description of its capabilities, note especially the shape parameter.

Parameters

• name (string) – name of the option

• dtype (type) – type of the value of the option, e.g. float, str, int, or list. If dtype is list, every entry of the list must have the same type.

• optional (bool, optional (default: False)) – whether the option is optional or not

• default (optional, (default: None)) – if optional=True, this default value will be used if this option is not given.

• shape (int or string or list/tuple of ints and/or strings, optional (only) –

  required for lists, default: None) If dtype is list, this is the shape of the list. There are several possibilities how to use this option:

  • if shape=n where n is a nonnegative integer, the value must be a list with length n.

  • if shape=-1 the value can have an arbitrary shape.

  • if shape="option1", the value of this option must have the same shape as “option1”. This is especially useful if the shape of “option1” is set to -1.

  • if shape=[2, 3], the value must be a list of lists, where the outermost list has length 2 and the inner lists all have length 3. This also works for more than 2 dimensions.

  • if shape=[2, -1, 3], the value must be a list of lists of lists. The outermost list must again have length 2, the innermost lists must have length 3, and the lists at the intermediate level can have any length (even different lengths).

  • if shape=[2, "option1", 3], the values must again be a list of lists similar to above, but now the lists at the intermediate level must have the same length as “option1”.

  • if shape=[2, [1, 2], [[3], [3, 3]]], the value must be a list of lists of lists. The outermost list must again have length 2. The two lists it contains have length 1 and length 2. The innermost lists all must have length 3.

  It’s also possible to only give the innermost value(s), e.g. for a list with shape=[2, 3] only the value 18. This will then be expanded to [[18, 18, 18], [18, 18, 18]]. Similarly, [18, 19, 20] would be expanded to [[18, 19, 20], [18, 19, 20]]. This expansion obviously doesn’t work if shape=-1. If shape=[2, -1, 3], expansion is possible if the given value is e.g. [[1, 2, 3], [1, 2, 3], [1, 2, 3]], but not if only [1, 2, 3] is given, since the length of the second dimension must be determined from the given value.

• datatype (int, float or string, optional (only required for lists, default: None)) – Type of the innermost elements of the option in case the option is a list.

• validation_func (function of one argument that returns a boolean, optional.) – Returns true if the value (for lists or lists of lists this applies to all values) is valid.

• alternatives (list of strings) – List of alternative names for this option. If the option is not found in the given dictionary while parsing, these alternatives are used if they exist. If an alternative is found (searching happens in the supplied order), the option is stored under it’s standard name.

parse(section)

Parses the option based on it’s attributes.

Parameters

section (Section instance) – The section it belongs to.

Returns

value – The parsed value.

Return type

self.type

Raises

• ShapeError – If the parsed list does not have the right shape.

• ValueError – Other errors, description in text.

exception hyvr.input.option_parsing.MissingSectionError(sectionname)

Bases: Exception

exception hyvr.input.option_parsing.MissingOptionError(optionname, sectionname)

Bases: Exception

exception hyvr.input.option_parsing.ShapeError(optionname, sectionname)

Bases: Exception

hyvr.input.option_parsing.assert_exists(option, dictionary, section_name)

hyvr.input.options module

This module contains all options for the ini-files. If you want to add an option, add it here.

The options are instances of hyvr.input.option_parsing.Option, where you will find more documentation on how to create an option. They should be added to one of the lists in here, if you want to add them to an existing section. For creating a new section, create a new list, and also make sure this section is added in hyvr.input.parameters.parse_inifile().

The element options are currently spread out over multiple lists. element_options contains general options that all architectural elements have. erosive_element_options contains options that all erosive architectural elements (trough, channel) have, and the options['<element_name>'] lists are specific for a single architectural element type.

Authors

Samuel Scherrer, Jeremy P. Bennett

hyvr.input.options_deprecated module

This module contains all options for the ini-files.

This module is only for parsing deprecated ini files, it might be removed in the future.

Authors

Samuel Scherrer, Jeremy P. Bennett

hyvr.input.parameters module

This is the main module for parsing the parameter file. There are two other modules strongly linked ot this one:

• options: contains definitions of the possible options of a parameter file

• option_parsing: provides the classes Section and Option for simpler parsing and validation.

Authors

Jeremy P. Bennett, Samuel Scherrer

hyvr.input.parameters.get_new_facies_list(facies_list, hydrofacies)

hyvr.input.parameters.get_new_parameters_from_deprecated(run, model, strata, hydraulics, flowtrans, elements)

This applies the necessary changes to parsed sections of an old-format inifile.

hyvr.input.parameters.parameters(inifile)

Parses the inifile and returns all sections as dictionaries. Furthermore it sets to correct directory names for the run settings.

Parameters

inifile (path) – Path to inifile. If inifile is set to 0, the ini-file for the MADE test case is used.

Returns

• run (dict) – HyVR run settings (number of simulations, where to store results)

• model_dict (dict) – model setup parameters

• strata_dict (dict) – strata setup parameters

• hydraulics (dict) – Parsed hydraulics section of the ini-file

• flowtrans (dict) – Flow and transport settings for output

• elements (list of dicts) – List of dictionaries of settings for hyvr.model.ae_types.AEType.

hyvr.input.parameters.parse_deprecated_inifile(p)

hyvr.input.parameters.parse_facies(facies_list, hydrofacies)

Reads a list of facies strings (facies_list) and returns the corresponding indices in the hydrofacies list.

hyvr.input.parameters.parse_inifile(p)

This function does the main work of parsing the input file.

Parameters

p (ConfigParser) – A config parser that already read in the inifile.

Returns

• run (dict) – HyVR run parameters (number of simulations, where to store results)

• model_dict (dict) – model setup parameters

• strata_dict (dict) – strata setup parameters

• hydraulics (dict) – Parsed hydraulics section of the ini-file

• flowtrans (dict) – Flow and transport settings for output

• elements (list of dicts) – List of dictionaries of settings for hyvr.model.ae_types.AEType.

hyvr.input.parameters.parse_old_elem_contact_model(elem)

hyvr.input.parameters.parse_old_strata_contact_model(strata, i)

hyvr.input.parameters.set_up_directories(run, inifile, overwrite_old_output=None)

This functions creates the necessary directories (modeldir, rundir). It also stores the used ini-file in the rundir.

Parameters

• run (dict) – parsed run-section of the config file

• inifile (str) – path to config file

• overwrite_old_output (bool) – Whether to overwrite the old run directory. If it is None, the option from the config file will be chosen instead (default in inifile: False)

hyvr.input.parameters.setup_from_inifile(inifile, flag_ow)

Parses the input file and sets up the directory structure for a HyVR run.

Parameters

• inifile (path) – Path to inifile. If inifile is set to 0, the ini-file for the MADE test case is used.

• flag_ow (bool) – Whether to overwrite existing run directories.

Returns

• run (dict) – HyVR run parameters (number of simulations, where to store results)

• model (Model object) – A HyVR model object created from the ini-file.

• hydraulics (dict) – Parsed hydraulics section of the ini-file