Backends

Note

This section characterizes protocols for backends. The purpose of a protocol is to provide support for nominal and structural subtyping.

Backend provide access to stored data. In general, each backend is of type BackendType.

class nata.types.BackendType(*args, **kwds)

Bases: typing_extensions.Protocol

General type for retreiving data.

The BackendType characterizes a general behavior of a backend. It is a Protocol which characterizes available attributes and their corresponding type annotation.

name: str

Name of the backend. The name can be chosen individually and is used for providing users with information about the underlaying data storage. It should follow the convention "CODENAME_VERSION_DATATYPE_STORAGE", e.g. "osiris_4.4.4_grid_hdf5"

location: Optional[Union[str, pathlib.Path]]

Location of the data. This attribute can be used inside a backend to point to data, either to open a file or to retrieve it.

To avoid validity checks at initialization level, each backend has a simple static-method of receiving a location and deducing if the backend is a valid backend, given a location.

static BackendType.is_valid_backend(location: Union[pathlib.Path, str]) → bool

Determine if a backend is a valid backend.

Parameters

location (str or pathlib.Path) – Checks if a location can be passed to backend to initiate it.

Returns

out (bool) – Returns True if location is valid input parameter for instantiation and False otherwise.

Backends for grids

For retrieving grid based data, the GridBackendType extends the base backend type.

class nata.types.GridBackendType(*args, **kwds)

Bases: nata.types.BackendType, typing_extensions.Protocol

Backend representing a grid.

GridBackendType is a protocol with the purpose of characterizing attributes being available for object to be recognized as a GridBackendType. Reading data is not part of this protocol but is characterized by GridDataReader which extends this protocol.

dataset_name: str

Name of the dataset. It has to be identifiable, e.g. "some_dataset_name".

dataset_label: str

Descriptive label of the dataset. Can be an arbitrary string, e.g. "some long label with space".

dataset_unit: str

Unit of the correspinding grid. Can be an string including some latex symbols, e.g. "m_e c \\omega_p e^{-1}".

axes_names: Sequence[str]

A sequence of strings for each grid axis. Each string of the sequence has to be identifiable, e.g. ["axis0", "axis1", "axis2"].

axes_labels: Sequence[str]

A sequence of strings for each grid axis. Each string of the sequence is a descriptive label for each axis, e.g. ["some axis 0", "some axis 1", "some axis 2"].

axes_units: Sequence[str]

A sequence of strings for each grid axis. Each string of the sequence is the unit for each axis including some latex symbols, e.g. ["c / \\omega_p", "mm", "\\omega_p^{-1}"].

axes_min: numpy.ndarray

An array representing the lower limits of each grid axis.

axes_max: numpy.ndarray

An array representing the upper limits of each grid axis.

iteration: int

Associated iteration step of the underlaying data.

time_step: float

::Associated time step of the underlaying data in code units.

time_unit: str

Unit for time. Can be an arbitrary string, e.g. "1 / \\omega_p".

shape: Tuple[int, …]

Tuple of grid array dimensions. Corresponds to numpy.ndarray.shape.

dtype: numpy.dtype

Data type object of the grid array. Corresponds to numpy.dtype.

ndim: int

Dimensionality of the grid. Corresponds to numpy.ndarray.ndim

class nata.types.GridDataReader(*args, **kwds)

Bases: nata.types.GridBackendType, typing_extensions.Protocol

Extended backend which handles grid data reading

get_data(indexing: Optional[Union[int, slice, Tuple[Union[int, slice], …]]] = None) → numpy.ndarray

Routine for reading underlaying grid data.

Parameters

indexing (int, slice, typing.Tuple[Union[slice, int], ...]], optional) – Optional indexing for reading a section of the grid. Any basic slicing and indexing can be passed here.

Returns

out (numpy.ndarray) – Data array of the underlaying grid.

Backends for particles

For retrieving particle based data, the ParticleBackendType extends the base backend type.

class nata.types.ParticleBackendType(*args, **kwds)

Bases: nata.types.BackendType, typing_extensions.Protocol

Backend representing a particles.

ParticleBackendType is a protocol with the purpose of characterizing attributes being available for object to be recognized as a ParticleBackendType. Reading data is not part of this protocol but is characterized by ParticleDataReader which extends this protocol.

dataset_name: str

Name of the dataset. It has to be identifiable, e.g. "some_dataset_name".

num_particles: int

Number of particles for a given backend.

quantity_names: Sequence[str]

A sequence of strings for each quantity stored in a backend. Each string of the sequence has to be identifiable, e.g. ["quant0", "quant1", "quant2"].

quantity_labels: Sequence[str]

A sequence of strings for each quantity stored in a backend. Each string of the sequence is a descriptive label for each quantity, e.g. ["some quantity 0", "some quantity 1", "some quantity 2"].

quantity_units: Sequence[str]

A sequence of strings for the unit of each quantity. Each string of the sequence is the unit for each quantity including some latex symbols, e.g. ["m_e", "c / \\omega_p"].

iteration: int

Associated iteration step of the underlaying data.

time_step: float

Associated time step of the underlaying data in code units.

time_unit: str

Unit for time. Can be an arbitrary string, e.g. "1 / \\omega_p".

dtype: numpy.dtype

Structured type of the underlaying particle backend. Field names correspond to quantity names, and the type corresponds to the array type.

In addition, for reading the underlying particle array the ParticleDataReader extends the ParticleBackendType.

class nata.types.ParticleDataReader(*args, **kwds)

Bases: nata.types.ParticleBackendType, typing_extensions.Protocol

Extended backend which handles particle data reading

get_data(indexing: Optional[Union[int, slice]] = None, fields: Optional[Union[str, Sequence[str]]] = None) → numpy.ndarray

Routine for reading underlaying grid data.

Parameters

• indexing (int, slice, typing.Tuple[Union[slice, int], ...]], optional) –

  Optional indexing for reading a section of the grid. Any basic slicing and indexing can be passed here.

• fields (str, typing.Sequence[str], optional) – Optional field or Sequence of fields to read out. Each field correspond to a quantity stored in the backend.

Returns

out (numpy.ndarray) – Data array of the underlaying particle array.