gemseo.caches.base_cache module#

Caching module to avoid multiple evaluations of a discipline.

class BaseCache(tolerance=0.0, name='')[source]#

Bases: Mapping[Mapping[str, Any], CacheEntry]

A base class for caches with a dictionary-like interface.

Caches are mainly used to store the Discipline evaluations.

A cache entry is defined by:

  • an input data in the form of a dictionary of objects associated with input names, i.e. {"input_name": object},

  • an output data in the form of a dictionary of NumPy arrays associated with output names, i.e. {"output_name": array}.

  • an optional Jacobian data, in the form of a nested dictionary of NumPy arrays associating output and input names, i.e. {"output_name": {"input_name": array}}.

Examples

The evaluation of the function \(y=f(x)=(x^2, 2x^3\))` and its derivative at \(x=1\) leads to cache the entry defined by:

  • the input data: \(1.\),

  • the output data: \((1., 2.)\),

  • the Jacobian data: \((2., 6.)^T\).

>>> input_data = {"x": array([1.0])}
>>> output_data = {"y": array([1.0, 2.0])}
>>> jacobian_data = {"y": {"x": array([[2.0], [6.0]])}}

For this input_data, one can cache the output data:

>>> cache.cache_outputs(input_data, output_data)

as well as the Jacobian data:

>>> cache.cache_jacobian(input_data, jacobian_data)

Caches have a abc.Mapping interface making them easy to set (cache[input_data] = (output_data, jacobian_data)), access (cache_entry = cache[input_data]) and update (cache.update(other_cache)).

Notes

cache_entry is a CacheEntry with the ordered fields input, output and jacobian accessible either by index, e.g. input_data = cache_entry[0], or by name, e.g. input_data = cache_entry.inputs.

Notes

If an output name is also an input name, the output name is suffixed with [out].

One can also get the number of cache entries with size = len(cache) and iterate over the cache, e.g. for input_data, output_data, _ in cache for index, (input_data, _, jacobian_data) in enumerate(cache) or [entry.outputs for entry in cache].

See also

SimpleCache to store the last discipline evaluation. MemoryFullCache to store all the discipline evaluations in memory. HDF5Cache to store all the discipline evaluations in a HDF5 file.

Parameters:

  • tolerance (float) --

    The tolerance below which two input arrays are considered equal: norm(new_array-cached_array)/(1+norm(cached_array)) <= tolerance. If this is the case for all the input names, then the cached output data shall be returned rather than re-evaluating the discipline. This tolerance could be useful to optimize CPU time. It could be something like 2 * numpy.finfo(float).eps.

    By default it is set to 0.0.

  • name (str) --

    A name for the cache. If empty, use the class name.

    By default it is set to "".

class Group(value)[source]#

Bases: StrEnum

A data group.

INPUTS = 'inputs'#

The label for the input variables.

JACOBIAN = 'jacobian'#

The label for the Jacobian.

OUTPUTS = 'outputs'#

The label for the output variables.

abstract cache_jacobian(input_data, jacobian_data)[source]#

Cache the input and Jacobian data.

Parameters:

  • input_data (StrKeyMapping) -- The data containing the input data to cache.

  • jacobian_data (JacobianData) -- The Jacobian data to cache.

Return type:

None

abstract cache_outputs(input_data, output_data)[source]#

Cache input and output data.

Parameters:

  • input_data (Mapping[str, Any]) -- The data containing the input data to cache.

  • output_data (Mapping[str, Any]) -- The data containing the output data to cache.

Return type:

None

clear()[source]#

Clear the cache.

Return type:

None

abstract get_all_entries()[source]#

Return an iterator over all the entries.

The tolerance is ignored.

Yields:

The entries.

Return type:

Iterator[CacheEntry]

to_dataset(name: str = '', categorize: Literal[True] = True, input_names: Iterable[str] = (), output_names: Iterable[str] = ()) → IODataset[source]#
to_dataset(name: str = '', categorize: Literal[False] = True, input_names: Iterable[str] = (), output_names: Iterable[str] = ()) → Dataset

Build a Dataset from the cache.

Parameters:

  • name -- A name for the dataset. If empty, use the name of the cache.

  • categorize -- Whether to distinguish between the different groups of variables. Otherwise, group all the variables in Dataset.PARAMETER_GROUP`.

  • input_names -- The names of the inputs to be exported. If empty, use all the inputs.

  • output_names -- The names of the outputs to be exported. If empty, use all the outputs. If an output name is also an input name, the output name is suffixed with [out].

Returns:

A dataset version of the cache.

property input_names: list[str]#

The names of the inputs of the last entry.

abstract property last_entry: CacheEntry#

The last cache entry.

name: str#

The name of the cache.

property names_to_sizes: dict[str, int]#

The sizes of the variables of the last entry.

For a Numpy array, its size is used. For a container, its length is used. Otherwise, a size of 1 is used.

property output_names: list[str]#

The names of the outputs of the last entry.

property tolerance: float#

The tolerance below which two input arrays are considered equal.

Raises:

ValueError -- If the tolerance is not positive.

DATA_COMPARATOR(dict_of_arrays, other_dict_of_arrays, tolerance=0.0)#

The comparator of input data structures.

It is used to check whether an input data has been cached in.

Parameters:
Return type:

bool