Utilities

Utilities#

Provides all the attrs-based utilities for the CSM base model and its subclasses.

csm.models.utils.convert_if_allowable_type(value, target, allowable)#

Converts the type of value to the target type if it is one of an allowable type. If value is already the correct type, or is not of an allowable type for conversion, the value will be returned unmodified.

Parameters:

  • value (Any) -- User input field value.

  • target (type) -- The type the value should be converted to if it is not already of that type.

  • allowable (type | tuple[type]) -- The allowable type(s) for conversion, i.e., (str, int) for a target type of float.

Returns:

Any -- The original value or a converted value of type target.

Return type:

Any

csm.models.utils.convert_float(value, *, target=<class 'float'>, allowable=(<class 'int'>, <class 'str'>))#

Converts the type of value to the target type if it is one of an allowable type. If value is already the correct type, or is not of an allowable type for conversion, the value will be returned unmodified.

Parameters:

  • value (Any) -- User input field value.

  • target (type) -- The type the value should be converted to if it is not already of that type.

  • allowable (type | tuple[type]) -- The allowable type(s) for conversion, i.e., (str, int) for a target type of float.

Returns:

Any -- The original value or a converted value of type target.

Return type:

Any

csm.models.utils.create_field(obj, units='unitless', io_type='input', *, default=None, additional_validators=None, additional_converters=None, **kwargs)#

Creates an obj-based field with pre-loaded defaults, conversions, validations, and metadata.

Parameters:

  • obj (type) -- A type. Currently only accepts int, float, or bool.

  • units (str, optional) -- OpenMDAO-compatible units. See <https://openmdao.org/newdocs/versions/latest/features/units.html> for more details. Defaults to "unitless".

  • io_type (str, optional) -- One of "input", "output", or "both" for how the attribute should be initialized within a WISDEM model. Typically xx_mass` and ``xx_cost attributes are both inputs and outputs. Defaults to "input".

  • default (int | float | bool, optional) -- Value of the default, if not None.

  • additional_validators (list[callable], optional) -- A list of additional validator functions to attach to the attrs.field initialization. Defaults to None

  • additional_converters (list[callable], optional) -- A list of additional converter functions to attach to the attrs.field initialization. Defaults to None

  • kwargs (dict[str, Any], optional) -- Additional parameterizations to pass to attrs.field.

Returns:

attrs.field -- Creates an attrs.field object for the attribute.

Raises:

NotImplementedError -- Raised if an unsupported type object is passed. Only int, float, and bool are accepted at this time.

Return type:

field

csm.models.utils.reuse(attribute, *, default=None, metadata=None, init=None)#

Reuses an existing attrs.Attribute object with an updated default value.

Borrowed idea from python-attrs/attrs#1429 until the functionality is fully integrated.

Parameters:

  • attribute (attrs.Attribute) -- The attribute to modify.

  • default (Any, optional) -- The new default value.

  • metadata (None, optional) -- Updated metadata dictionary to change attributes such as "units" or "io". Defaults to None.

  • init (bool | None) -- Custom value for the init attribute, if modification is desired. If None, then the existing value for the attribute will be used. Defaults to False.

Returns:

attrib -- The new attribute object used in class initialization.

Return type:

attrib

csm.models.utils.generate_parameterization(parameterized_kwargs)#

Validates the kwargs to be parameterized and creates the full set of values to be used for each argument.

Parameters:

parameterized_kwargs (dict[str, int | float | bool]) --

Dictionary of independent variables with an iterable value consisting of an explicit set of values or range of values generated by np.linspace. For both cases, the first value must be one of "inputs" or "range". Subsequent values should specified according to the case:

  • "inputs": all subsequent values will be used as inputs, e.g.,

    {"tower_length": ("inputs", 90, 100)} will run 2 iterations, one with a 90m tower length and one with a 100 meter tower length.

  • "range": subsequent values must be start, stop, num where stop is inclusive,

    e.g., {"efficiency_max": ("range", 0.8, 1.0, 5)} will run 5 iterations of the model varying efficiency_max with values 0.8, 0.85, 0.9, 0.95, and 1.0.

Raises:

  • ValueError -- Raised if any of the keys of parameterized_kwargs are not defined as a "range" or "inputs" style variable.

  • ValueError -- Raised if fewer than 2 inputs are able to be generated by the parameterization type.

Returns:

dict[str, list]] --

Dictionary of each argument and the full set of values to parameterize

a model.

Return type:

dict[str, list]

csm.models.utils.get_dependent_attributes(parameter_graph, name)#

Returns a set of model attributes that depend on the value of name.

Parameters:

  • parameter_graph (nx.DiGraph) -- The CSMBase.parameter_graph.

  • name (str) -- The name of a model attribute that a user inputs or can be calculated.

Returns:

set[str] -- Set of model attribute names that rely on the value of name.

Return type:

set[str]

csm.models.utils.get_descendant_attributes(parameter_graph, name)#

Returns a set of model attributes name requires.

Parameters:

  • parameter_graph (nx.DiGraph) -- The CSMBase.parameter_graph.

  • name (str) -- The name of a model attribute that a user inputs or can be calculated.

Returns:

set[str] -- Set of model attribute names that name relies on.

Return type:

set[str]