fastoad.openmdao.variables package

Submodules

Module contents

Package for managing OpenMDAO variables

class fastoad.openmdao.variables.Variable(name: str, *, init_metadata: bool = True, **kwargs)[source]

Bases: Hashable

A class for storing data of OpenMDAO variables.

Instantiation is expected to be done through keyword arguments only.

Beside the mandatory parameter ‘name, kwargs is expected to have keys ‘value’, ‘units’ and ‘desc’, that are accessible respectively through properties name(), value(), units() and description().

Other keys are possible. They match the definition of OpenMDAO’s method Component.add_output() described here.

These keys can be listed with class method get_openmdao_keys(). Any other key in kwargs will be silently ignored.

Special behaviour: description() will return the content of kwargs[‘desc’] unless these 2 conditions are met:

  • kwargs[‘desc’] is None or ‘desc’ key is missing

  • a description exists in FAST-OAD internal data for the variable name

Then, the internal description will be returned by description()

Parameters:

  • name – the name of the variable

  • init_metadata – if True, applies default values for metadata keys not provided in kwargs

  • kwargs – the OpenMDAO metadata of the variable, as keyword arguments

name

Name of the variable

metadata: dict

Dictionary for metadata of the variable

get_val(new_units: str | None = None) → float | ndarray[source]

Returns the variable value converted in the new_units. One dimensional lists and np.array are scalarized.

Note that this method should not be confused with OpenMDAO’s problem.get_val(). While they have similar behavior, this method applies to a Variable instance rather than to a Problem instance.

Parameters:

new_units – units to convert the value to. If None, the value will be returned with its original units.

Returns:

the variable value, converted to new_units if specified.

update_missing_metadata(source_variable: Variable)[source]

Add metadata from source_variable to this variable, but only for keys that don’t already exist.

This is used to fill in missing metadata while preserving existing values.

Parameters:

source_variable – Source for additional metadata

classmethod read_variable_descriptions(file_parent: str | PathLike, *, update_existing: bool = True)[source]

Reads variable descriptions in indicated folder or package, if it contains some.

The file variable_descriptions.txt is looked for. Nothing is done if it is not found (no error raised also).

Each line of the file should be formatted like:

my:variable||The description of my:variable, as long as needed, but on one line.
Parameters:

  • file_parent – the folder path or the package name that should contain the file

  • update_existing – if True, previous descriptions will be updated. if False, previous descriptions will be erased.

classmethod update_variable_descriptions(variable_descriptions: Mapping[str, str] | Iterable[tuple[str, str]])[source]

Updates description of variables.

Parameters:

variable_descriptions – dict-like object with variable names as keys and descriptions as values

classmethod get_openmdao_keys()[source]
Returns:

the keys that are used in OpenMDAO variables

property value

value of the variable

property val

value of the variable (alias of property “value”)

property units

units associated to value (or None if not found)

property description

description of the variable (or None if not found)

property desc

description of the variable (or None if not found) (alias of property “description”)

property is_input

I/O status of the variable.

  • True if variable is a problem input

  • False if it is an output

  • None if information not found

get_openmdao_kwargs(keys: Iterable | None = None) → dict[source]

Provides a dict usable as keyword args by OpenMDAO add_input()/add_output().

The dict keys will be the ones provided, or a default set if no keys are provided.

Parameters:

keys

Returns:

the kwargs dict

class fastoad.openmdao.variables.VariableList(iterable=(), /)[source]

Bases: list

Class for storing OpenMDAO variables.

A list of Variable instances, but items can also be accessed through variable names. It also has utilities to be converted from/to some other data structures (python dict, OpenMDAO IndepVarComp, pandas DataFrame)

See documentation of Variable to see how to manipulate each element.

There are several ways for adding variables:

# Assuming these Python variables are ready...
var_1 = Variable('var/1', value=0.)
metadata_2 = {'value': 1., 'units': 'm'}

# ... a VariableList instance can be populated like this:
vars_A = VariableList()
vars_A.append(var_1)              # Adds directly a Variable instance
vars_A['var/2'] = metadata_2      # Adds the variable with given name and given metadata

Note

Adding a Variable instance with a name that is already in the VariableList instance will replace the previous Variable instance instead of adding a new one.

# It is also possible to instantiate a VariableList instance from another VariableList
# instance or a simple list of Variable instances
vars_B = VariableList(vars_A)
vars_C = VariableList([var_1])

# An existing VariableList instance can also receive the content of another VariableList
# instance.
vars_C.update(vars_A)             # variables in vars_A will overwrite variables with same
                                  # name in vars_C

After that, following equalities are True:

print( var_1 in vars_A )
print( 'var/1' in vars_A.names() )
print( 'var/2' in vars_A.names() )
names() → list[str][source]
Returns:

names of variables

metadata_keys() → list[str][source]
Returns:

the metadata keys that are common to all variables in the list

append(var: Variable) → None[source]

Appends var to the end of the list, unless its name is already used. In that case, var will replace the previous Variable instance with the same name.

add_var(name, **kwargs)[source]

Adds, or replace, the named variable with given attributes

Parameters:

  • name

  • kwargs

update(other_var_list: list, *, add_variables: bool = True, merge_metadata: bool = False)[source]

Uses variables in other_var_list to update the current VariableList instance.

For each Variable instance in other_var_list:

  • if a Variable instance with same name exists, it is replaced by the one in other_var_list (special case: if one in other_var_list has an empty description, the original description is kept)

  • if not, Variable instance from other_var_list will be added only if add_variables==True

The merge_metadata parameter controls how metadata is handled when replacing variables:

  • if merge_metadata=False (default): The original variable is completely overwritten

with the new one, and all previous metadata is lost (except for the description as noted above). - if merge_metadata=True: The metadata present in the original variable and absent from the new variable will be conserved. All other metadata will be overwritten by the ones in the new variable.

Parameters:

  • other_var_list – source for new Variable data

  • add_variables – if True, unknown variables are also added

  • merge_metadata – if True, preserves existing metadata for keys not present in the new variable

to_ivc() → IndepVarComp[source]
Returns:

an OpenMDAO IndepVarComp instance with all variables from current list

to_dataframe() → DataFrame[source]

Creates a DataFrame instance from a VariableList instance.

Column names are “name” + the keys returned by Variable.get_openmdao_keys(). Values in Series “value” are floats or lists (numpy arrays are converted).

Returns:

a pandas DataFrame instance with all variables from current list

classmethod from_dict(var_dict: Mapping[str, dict] | Iterable[tuple[str, dict]]) → VariableList[source]

Creates a VariableList instance from a dict-like object.

Parameters:

var_dict

Returns:

a VariableList instance

classmethod from_ivc(ivc: IndepVarComp) → VariableList[source]

Creates a VariableList instance from an OpenMDAO IndepVarComp instance

Parameters:

ivc – an IndepVarComp instance

Returns:

a VariableList instance

classmethod from_dataframe(df: DataFrame) → VariableList[source]

Creates a VariableList instance from a pandas DataFrame instance.

The DataFrame instance is expected to have column names “name” + some keys among the ones given by Variable.get_openmdao_keys().

Parameters:

df – a DataFrame instance

Returns:

a VariableList instance

classmethod from_problem(problem: Problem, io_status: str = 'all', *, use_initial_values: bool = False, get_promoted_names: bool = True, promoted_only: bool = True) → VariableList[source]

Creates a VariableList instance containing inputs and outputs of an OpenMDAO Problem.

The inputs (is_input=True) correspond to the variables of IndepVarComp components and all the unconnected input variables.

Note

Variables from _auto_ivc are ignored.

Parameters:

  • problem – OpenMDAO Problem instance to inspect

  • io_status – to choose with type of variable we return (“all”, “inputs, “outputs”)

  • use_initial_values – if True, or if problem has not been run, returned instance will contain values before computation

  • get_promoted_names – if True, promoted names will be returned instead of absolute ones (if no promotion, absolute name will be returned)

  • promoted_only – if True, only promoted variable names will be returned

Returns:

VariableList instance

classmethod from_unconnected_inputs(problem: Problem, *, with_optional_inputs: bool = False) → VariableList[source]

Creates a VariableList instance containing unconnected inputs of an OpenMDAO Problem.

Warning

problem.setup() must have been run.

If optional_inputs is False, only inputs that have numpy.nan as default value (hence considered as mandatory) will be in returned instance. Otherwise, all unconnected inputs will be in returned instance.

Parameters:

  • problem – OpenMDAO Problem instance to inspect

  • with_optional_inputs – If True, returned instance will contain all unconnected inputs. Otherwise, it will contain only mandatory ones.

Returns:

VariableList instance