4.5.1 pde.storage.base module

Base classes for storing data

class StorageBase(info=None, write_mode='truncate_once')[source]

Bases: object

base class for storing time series of discretized fields

These classes store time series of FieldBase, i.e., they store the values of the fields at particular time points. Iterating of the storage will return the fields in order and individual time points can also be accessed.

Parameters:
  • info (dict) – Supplies extra information that is stored in the storage

  • write_mode (str) – Determines how new data is added to already existing one. Possible values are: ‘append’ (data is always appended), ‘truncate’ (data is cleared every time this storage is used for writing), or ‘truncate_once’ (data is cleared for the first writing, but subsequent data using the same instances are appended). Alternatively, specifying ‘readonly’ will disable writing completely.

append(field, time=None)[source]

add field to the storage

Parameters:
  • field (FieldBase) – The field that is added to the storage

  • time (float, optional) – The time point

Return type:

None

apply(func, out=None, *, progress=False)[source]

applies function to each field in a storage

Parameters:
  • func (callable) – The function to apply to each stored field. The function must either take as a single argument the field or as two arguments the field and the associated time point. In both cases, it should return a field.

  • out (StorageBase) – Storage to which the output is written. If omitted, a new MemoryStorage is used and returned

  • progress (bool) – Flag indicating whether the progress is shown during the calculation

Returns:

The new storage that contains the data after the function func has been applied

Return type:

StorageBase

clear(clear_data_shape=False)[source]

truncate the storage by removing all stored data.

Parameters:

clear_data_shape (bool) – Flag determining whether the data shape is also deleted.

Return type:

None

copy(out=None, *, progress=False)[source]

copies all fields in a storage to a new one

Parameters:
  • out (StorageBase) – Storage to which the output is written. If omitted, a new MemoryStorage is used and returned

  • progress (bool) – Flag indicating whether the progress is shown during the calculation

Returns:

The new storage that contains the copied data

Return type:

StorageBase

data: Any
property data_shape: tuple[int, ...]

the current data shape.

Raises:

RuntimeError – if data_shape was not set

property dtype: dtype[Any] | None | type[Any] | _SupportsDType[dtype[Any]] | str | tuple[Any, int] | tuple[Any, SupportsIndex | Sequence[SupportsIndex]] | list[Any] | _DTypeDict | tuple[Any, Any]

the current data type.

Raises:

RuntimeError – if data_type was not set

end_writing()[source]

finalize the storage after writing

Return type:

None

extract_field(field_id, label=None)[source]

extract the time course of a single field from a collection

This method makes a copy of the underlying data.

Parameters:
  • field_id (int or str) – The index into the field collection. This determines which field of the collection is returned. Instead of a numerical index, the field label can also be supplied. If there are multiple fields with the same label, only the first field is returned.

  • label (str) – The label of the returned field. If omitted, the stored label is used.

Returns:

a storage instance that contains the data for the single field

Return type:

MemoryStorage

extract_time_range(t_range=None)[source]

extract a particular time interval

Note

This might return a view into the original data, so modifying the returned data can also change the underlying original data.

Parameters:

t_range (float or tuple) – Determines the range of time points included in the result. If only a single number is given, all data up to this time point are included.

Returns:

a storage instance that contains the extracted data.

Return type:

MemoryStorage

property grid: GridBase | None

the grid associated with this storage

This returns None if grid was not stored in self.info.

Type:

GridBase

property has_collection: bool

whether the storage is storing a collection

Type:

bool

items()[source]

iterate over all times and stored fields, returning pairs

Return type:

Iterator[tuple[float, FieldBase]]

property shape: tuple[int, ...] | None

the shape of the stored data

start_writing(field, info=None)[source]

initialize the storage for writing data

Parameters:
  • field (FieldBase) – An example of the data that will be written to extract the grid and the data_shape

  • info (dict) – Supplies extra information that is stored in the storage

Return type:

None

times: Sequence[float]
tracker(interrupts=1, *, transformation=None, interval=None)[source]

create object that can be used as a tracker to fill this storage

Parameters:
  • interrupts (InterruptsBase | float | str | Sequence[float] | ndarray) – Determines when the tracker interrupts the simulation. A single numbers determines an interval (measured in the simulation time unit) of regular interruption. A string is interpreted as a duration in real time assuming the format ‘hh:mm:ss’. A list of numbers is taken as explicit simulation time points. More fine- grained contol is possible by passing an instance of classes defined in interrupts.

  • transformation (callable, optional) – A function that transforms the current state into a new field or field collection, which is then stored. This allows to store derived quantities of the field during calculations. The argument needs to be a callable function taking 1 or 2 arguments. The first argument always is the current field, while the optional second argument is the associated time.

Returns:

The tracker that fills the current storage

Return type:

StorageTracker

Example

The transformation argument allows storing additional fields:

def add_to_state(state):
    transformed_field = state.smooth(1)
    return field.append(transformed_field)

storage = pde.MemoryStorage()
tracker = storage.tracker(1, transformation=add_to_state)
eq.solve(..., tracker=tracker)

In this example, storage will contain a trajectory of the fields of the simulation as well as the smoothed fields. Other transformations are possible by defining appropriate add_to_state()

view_field(field_id)[source]

returns a view into this storage focusing on a particular field

Note

Modifying data returned by the view will modify the underlying storage

Parameters:

field_id (int or str) – The index into the field collection. This determines which field of the collection is returned. Instead of a numerical index, the field label can also be supplied. If there are multiple fields with the same label, only the first field is returned.

Returns:

A view into the storage only returning a single field

Return type:

StorageView

write_mode: Literal['append', 'readonly', 'truncate', 'truncate_once']
class StorageTracker(storage, interrupts=1, *, transformation=None, interval=None)[source]

Bases: TrackerBase

Tracker that stores data in special storage classes

storage

The underlying storage class through which the data can be accessed

Type:

StorageBase

Parameters:
  • storage (StorageBase) – Storage instance to which the data is written

  • interrupts (InterruptData) – Determines when the tracker interrupts the simulation. A single numbers determines an interval (measured in the simulation time unit) of regular interruption. A string is interpreted as a duration in real time assuming the format ‘hh:mm:ss’. A list of numbers is taken as explicit simulation time points. More fine- grained contol is possible by passing an instance of classes defined in interrupts.

  • transformation (callable, optional) – A function that transforms the current state into a new field or field collection, which is then stored. This allows to store derived quantities of the field during calculations. The argument needs to be a callable function taking 1 or 2 arguments. The first argument always is the current field, while the optional second argument is the associated time.

finalize(info=None)[source]

finalize the tracker, supplying additional information

Parameters:

info (dict) – Extra information from the simulation

Return type:

None

handle(field, t)[source]

handle data supplied to this tracker

Parameters:
  • field (FieldBase) – The current state of the simulation

  • t (float) – The associated time

Return type:

None

initialize(field, info=None)[source]
Parameters:
  • field (FieldBase) – An example of the data that will be analyzed by the tracker

  • info (dict) – Extra information from the simulation

Returns:

The first time the tracker needs to handle data

Return type:

float

class StorageView(storage, *, field)[source]

Bases: object

represents a view into a storage that extracts a particular field

Parameters:
  • storage (StorageBase) – The storage providing the basic data

  • field (int or str) – The index into the field collection determining which field of the collection is returned. Instead of a numerical index, the field label can also be supplied. If there are multiple fields with the same label, only the first field is returned.

property grid: GridBase | None
has_collection: bool = False
items()[source]

iterate over all times and stored fields, returning pairs

Return type:

Iterator[tuple[float, DataFieldBase]]

property times: Sequence[float]