gemseo / utils

# data_conversion module¶

Conversion from a NumPy array to a dictionary of NumPy arrays and vice versa.

Classes:

 Methods to juggle NumPy arrays and dictionaries of Numpy arrays.

Functions:

 flatten_mapping(mapping[, parent_key, sep]) Flatten a nested mapping.
class gemseo.utils.data_conversion.DataConversion[source]

Bases: object

Methods to juggle NumPy arrays and dictionaries of Numpy arrays.

Attributes:

Methods:

 array_to_dict(data_array, data_names, data_sizes) Convert an NumPy array into a dictionary of NumPy arrays indexed by names. deepcopy_datadict(data_dict[, keys]) Perform a deep copy of a data mapping. dict_jac_to_2dmat(jac_dict, outputs, inputs, ...) Convert elementary Jacobian matrices into a full Jacobian matrix. dict_jac_to_dict(jac_dict) Reindex a mapping of elementary Jacobian matrices by Jacobian names. dict_to_array(data_dict, data_names) Concatenate some values of a mapping associating values to names. dict_to_jac_dict(flat_jac_dict) Reindex a mapping of elementary Jacobian matrices by input and output names. flat_jac_name(out_name, inpt_name) Concatenate the name of the output and input, with a separator. get_all_inputs(disciplines[, recursive]) Return all the input names of the disciplines. get_all_outputs(disciplines[, recursive]) Return all the output names of the disciplines. jac_2dmat_to_dict(flat_jac, outputs, inputs, ...) Convert a full Jacobian matrix into elementary Jacobian matrices. jac_3dmat_to_dict(jac, outputs, inputs, ...) Convert several full Jacobian matrices into elementary Jacobian matrices. list_of_dict_to_array(data_list, data_names) Concatenate some values of mappings associating values to names. update_dict_from_array(reference_input_data, ...) Update a data mapping from data array and names.
FLAT_JAC_SEP = '!d$_$d!'
static array_to_dict(data_array, data_names, data_sizes)[source]

Convert an NumPy array into a dictionary of NumPy arrays indexed by names.

This allows to convert:

array([1., 2., 3.])


to:

{'x': array([1.])}, 'y': array([2., 3.])}

Parameters
• data_array (numpy.ndarray) – The data array to be converted.

• data_names (Iterable[str]) – The names to be used as keys of the dictionary. The data array must contain the values of these names in the same order, e.g. data_array=array([1.,2.]) and data_names=["x","y"] implies that x=array([1.]) and x=array([2.]).

• data_sizes (Mapping[str, int]) – The sizes of the variables e.g. data_array=array([1.,2.,3.]), data_names=["x","y"] and data_sizes={"x":2,"y":1} implies that x=array([1.,2.]) and x=array([3.]).

Returns

The data mapped to the names.

Raises

ValueError – If the number of dimensions of the data array is greater than 2.

Return type

Dict[str, numpy.ndarray]

Perform a deep copy of a data mapping.

This treats the NumPy arrays specially using array.copy() instead of deepcopy.

Parameters
• data_dict – The data mapping to be copied.

• keys

The keys of the mapping to be considered. If None, consider all the mapping keys.

By default it is set to None.

Returns

A deep copy of the data mapping.

static dict_jac_to_2dmat(jac_dict, outputs, inputs, data_sizes)[source]

Convert elementary Jacobian matrices into a full Jacobian matrix.

Parameters
• jac_dict (Mapping[str, Mapping[str, numpy.ndarray]]) – The elementary Jacobian matrices indexed by the names of the inputs and outputs.

• inputs (Iterable[str]) – The names of the inputs.

• outputs (Iterable[str]) – The names of the outputs.

• data_sizes (Mapping[str, int]) – The sizes of the inputs and outputs.

Returns

The full Jacobian matrix whose first dimension represents the outputs and the second one represents the inputs, both preserving the order of variables passed as arguments.

Return type

numpy.ndarray

static dict_jac_to_dict(jac_dict)[source]

Reindex a mapping of elementary Jacobian matrices by Jacobian names.

A Jacobian name is built with the method flat_jac_name() from the input and output names.

Parameters

jac_dict (Mapping[str, Mapping[str, numpy.ndarray]]) – The elementary Jacobian matrices indexed by input and output names.

Returns

The elementary Jacobian matrices index by Jacobian names.

Return type

Dict[str, numpy.ndarray]

static dict_to_array(data_dict, data_names)[source]

Concatenate some values of a mapping associating values to names.

This allows to convert:

{'x': array([1.])}, 'y': array([2., 3.])}


to:

array([1., 2., 3.])

Parameters
• data_dict (Mapping[str, numpy.ndarray]) – The mapping to be converted; it associates values to names.

• data_names (Iterable[str]) – The names to be used for the concatenation.

Returns

The concatenation of the values for the provided names.

Return type

numpy.ndarray

static dict_to_jac_dict(flat_jac_dict)[source]

Reindex a mapping of elementary Jacobian matrices by input and output names.

Parameters

flat_jac_dict (Mapping[str, numpy.ndarray]) – The elementary Jacobian matrices index by Jacobian names. A Jacobian name is built with the method flat_jac_name() from the input and output names.

Returns

The elementary Jacobian matrices index by input and output names.

Return type

Mapping[str, Mapping[str, numpy.ndarray]]

static flat_jac_name(out_name, inpt_name)[source]

Concatenate the name of the output and input, with a separator.

Parameters
• out_name (str) – The name of the output.

• inpt_name (str) – The name of the input.

Returns

The name of the output concatenated with the name of the input.

Return type

str

static get_all_inputs(disciplines, recursive=False)[source]

Return all the input names of the disciplines.

Parameters
• disciplines (Iterable[MDODiscipline]) – The disciplines.

• recursive (bool) –

If True, search for the inputs of the sub-disciplines, when some disciplines are scenarios.

By default it is set to False.

Returns

The names of the inputs.

Return type

List[str]

static get_all_outputs(disciplines, recursive=False)[source]

Return all the output names of the disciplines.

Parameters
• disciplines (Iterable[MDODiscipline]) – The disciplines.

• recursive (bool) –

If True, search for the outputs of the sub-disciplines, when some disciplines are scenarios.

By default it is set to False.

Returns

The names of the outputs.

Return type

List[str]

static jac_2dmat_to_dict(flat_jac, outputs, inputs, data_sizes)[source]

Convert a full Jacobian matrix into elementary Jacobian matrices.

The full Jacobian matrix is passed as a two-dimensional NumPy array. Its first dimension represents the outputs and its second one represents the inputs.

Parameters
• flat_jac (numpy.ndarray) – The full Jacobian matrix.

• inputs (Iterable[str]) – The names of the inputs.

• outputs (Iterable[str]) – The names of the outputs.

• data_sizes (Mapping[str, int]) – The sizes of the inputs and outputs.

Returns

The Jacobian matrices indexed by the names of the inputs and outputs. Precisely, jac[output][input] is a two-dimensional NumPy array representing the Jacobian matrix for the input input and output output, with the output components in the first dimension and the output components in the second one.

Return type

Dict[str, Dict[str, numpy.ndarray]]

static jac_3dmat_to_dict(jac, outputs, inputs, data_sizes)[source]

Convert several full Jacobian matrices into elementary Jacobian matrices.

The full Jacobian matrices are passed as a three-dimensional NumPy array. Its first dimension represents the different full Jacobian matrices, its second dimension represents the outputs and its third one represents the inputs.

Parameters
• jac (numpy.ndarray) – The full Jacobian matrices.

• inputs (Iterable[str]) – The names of the inputs.

• outputs (Iterable[str]) – The names of the outputs.

• data_sizes (Mapping[str, int]) – The sizes of the inputs and outputs.

Returns

The Jacobian matrices indexed by the names of the inputs and outputs. Precisely, jac[output][input] is a three-dimensional NumPy array where jac[output][input][i] represents the i-th Jacobian matrix for the input input and output output, with the output components in the first dimension and the output components in the second one.

Return type

Dict[str, Dict[str, numpy.ndarray]]

static list_of_dict_to_array(data_list, data_names, group=None)[source]

Concatenate some values of mappings associating values to names.

The names can be either grouped:

[
{'group1':
{'x': array([3.])},
'group2':
{'y': array([1., 1.])}
},
{'group1':
{'x': array([6.])},
'group2':
{'y': array([2., 2.])}
}
]


or ungrouped:

[
{'x': array([3.]), 'y': array([1., 1.])},
{'x': array([6.]), 'y': array([2., 2.])}
]


For both cases, if data_names=["y", "x"], the returned object will be

array([[1., 1., 3.],
[2., 2., 6.]])

Parameters
• data_list (Iterable[Mapping[str, Union[numpy.ndarray, Mapping[str, numpy.ndarray]]]]) – The mappings to be converted; it associates values to names, possibly classified by groups.

• data_names (Iterable[str]) – The names to be used for the concatenation.

• group (Optional[str]) –

The name of the group to be considered. If None, the data is assumed to have no group.

By default it is set to None.

Returns

The concatenation of the values of the passed names.

Return type

numpy.ndarray

static update_dict_from_array(reference_input_data, data_names, values_array)[source]

Update a data mapping from data array and names.

The order of the data in the array follows the order of the data names.

Parameters
• reference_input_data (Mapping[str, numpy.ndarray]) – The reference data to be updated.

• data_names (Iterable[str]) – The names for which to update the data.

• values_array (numpy.ndarray) – The data with which to update the reference one.

Returns

The updated data mapping.

Raises
• TypeError – If the data with which to update the reference one is not a NumPy array.

• ValueError

• If a name for which to update the data is missing from the reference data. * If the size of the data with which to update the reference one is inconsistent with the reference data.

Return type

Dict[str, numpy.ndarray]

gemseo.utils.data_conversion.flatten_mapping(mapping, parent_key='', sep='_')[source]

Flatten a nested mapping.

Parameters
• mapping (Mapping) – The mapping to be flattened.

• parent_key (str) –

The key for which mapping is the value.

By default it is set to .

• sep (str) –

The keys separator, to be used as {parent_key}{sep}{child_key}.

By default it is set to _.

Return type

Dict