Storage module

The AEIC.storage package provides the low-level building blocks used by trajectories, trajectory stores, and the rest of AEIC for:

Most user-facing code will reach these types indirectly, via Trajectory and TrajectoryStore. The public surface is re-exported at package level so that everything can be imported from AEIC.storage directly.

Note

track_file_accesses is a context manager wrapped around the entire aeic run invocation (see AEIC.commands.run_simulations). It captures the set of data files read during a run so that the resulting trajectory store can ship with a reproducibility snapshot. It is not intended for use inside a normal interactive session — open it once at the top of a CLI command, not per-trajectory.

API reference

class AEIC.storage.Container(npoints=None, fieldsets=None, fieldset=None)

Container class for 1-D trajectory and single point data with various data fields and metadata.

Parameters:

  • npoints (int | None)

  • fieldsets (list[str] | None)

  • fieldset (FieldSet | None)

CAPACITY_EXPANSION = 50

Number of points by which to expand the container’s capacity when adding points to an extensible container that has reached its current capacity.

STARTING_CAPACITY = 50

the initial number of points allocated for pointwise fields in a container without a specified number of points. The container will extend its capacity as needed when points are added.

Type:

Starting capacity for extensible containers

add_fields(fieldset)

Add fields from a FieldSet to the container.

Either just add fields with empty values, or, if the field set is attached to a value object using the HasFieldSet protocol, try to initialize data values too.

Parameters:

fieldset (FieldSet | HasFieldSets)

approx_eq(other)

Two containers are approximately equal if their data dictionaries are equal and all their field values are approximately equal.

Parameters:

other (object)

Return type:

bool

copy()

Create a deep copy of the container. A copy of an extensible container is not extensible.

Return type:

Self

fix()

Convert an extensible container to a fixed-size container.

Return type:

None

make_point(idx=None)

Make a new container representing a single point of the possible multiple points stored in this container. For example, for a trajectory, this produces a container representing a single point of the trajectory. If idx is specified, the field values for that point are copied to the new container. If idx is not specified, the field values in the new container are left uninitialized.

Parameters:

idx (int | None)

Return type:

Container

property species: list[Species]

Set of species included in any species-indexed fields in the container.

enum AEIC.storage.Dimension(value)

Standard dimension names for NetCDF serialization.

The sort order here is important: when serializing to NetCDF, dimensions should be written in the order defined here.

Member Type:

int

Valid values are as follows:

TRAJECTORY = <Dimension.TRAJECTORY: 1>
SPECIES = <Dimension.SPECIES: 2>
POINT = <Dimension.POINT: 3>
THRUST_MODE = <Dimension.THRUST_MODE: 4>

The Enum and its members also have the following methods:

property dim_name: str

Dimension name for use in NetCDF files.

classmethod from_dim_name(name)

Convert from names used in NetCDF files.

Parameters:

name (str)

Return type:

Dimension

class AEIC.storage.FieldMetadata(dimensions=<factory>, field_type=<class 'numpy.float64'>, description='', units='', required=True, default=None)

Metadata for a single field.

This is intended to describe the properties of a field in a dataset that may be serialized to NetCDF.

Fields can indexed by a range of different dimensions, represented by the dimensions field (in the “Type” rows, “scalar” means a Numpy floating point or integer type, or Python str):

  • Dimensions: trajectory

  • Use: per-trajectory individual values

  • Examples: total fuel burn for a trajectory, number of climb segments, etc.

  • Type: scalar

  • Dimensions: trajectory, point

  • Use: pointwise values along a trajectory

  • Examples: trajectory latitude, longitude, altitude

  • Type: np.ndarray

  • Dimensions: trajectory, species

  • Use: per-species values for a whole trajectory

  • Examples: APU emissions for a species on a trajectory

  • Type: SpeciesValues[scalar]

  • Dimensions: trajectory, species, point

  • Use: pointwise values for each species along a trajectory

  • Example: CO₂ emissions at each point along a trajectory

  • Type: SpeciesValues[np.ndarray]

  • Dimensions: trajectory, thrust_mode

  • Use: per-thrust-mode values for a whole trajectory

  • Examples: LTO fuel burn per thrust mode for a trajectory

  • Type: ThrustModeValues

  • Dimensions: trajectory, species, thrust_mode

  • Use: per-species values for each thrust mode for a whole trajectory.

  • Examples: NOₓ emissions per thrust mode for a trajectory

  • Type: SpeciesValues[ThrustModeValues]

Parameters:

  • dimensions (Dimensions)

  • field_type (type)

  • description (str)

  • units (str)

  • required (bool)

  • default (Any | None)

convert_in(v, name, npoints)

Convert an incoming value to the appropriate type for this field.

Parameters:

  • v (Any)

  • name (str)

  • npoints (int)

Return type:

Any

default: Any | None = None

Default value for the field if not present in the dataset.

description: str = ''

Human-readable description of the field (used for the NetCDF “description” attribute).

property digest_info: str

Generate a string representation of the field metadata for hashing.

dimensions: Dimensions

Dimensions for this field.

empty(npoints)

Create an empty value for this field based on its type and dimensions.

Parameters:

npoints (int)

Return type:

Any

field_type

alias of float64

nbytes(npoints)

Estimate the number of bytes used by this field per trajectory point.

This is a rough estimate used for memory usage calculations.

Parameters:

npoints (int)

Return type:

int

required: bool = True

Is this field required to be present in the dataset?

units: str = ''

Units of the field (used for the NetCDF “units” attribute).

class AEIC.storage.FieldSet(fieldset_name=None, registered=True, **fields)

A collection of field definitions.

Represented as a mapping from field name to metadata.

Parameters:

  • fieldset_name (str | None)

  • registered (bool)

  • fields (FieldMetadata)

REGISTRY: dict[str, FieldSet] = {'base': <FieldSet base: ['fuel_flow', 'aircraft_mass', 'fuel_mass', 'ground_distance', 'altitude', 'flight_level', 'rate_of_climb', 'flight_time', 'latitude', 'longitude', 'azimuth', 'heading', 'true_airspeed', 'ground_speed', 'starting_mass', 'total_fuel_mass', 'n_idle_origin', 'n_taxi_origin', 'n_takeoff', 'n_climb', 'n_cruise', 'n_descent', 'n_approach', 'n_taxi_destination', 'n_idle_destination', 'flight_id', 'name']>, 'emissions': <FieldSet emissions: ['trajectory_emissions', 'trajectory_indices', 'lto_emissions', 'lto_indices', 'apu_emissions', 'apu_indices', 'gse_emissions', 'total_emissions', 'fuel_burn_per_segment', 'total_fuel_burn', 'lifecycle_co2']>}

Registry of named field sets for reuse.

static calc_hash(name, fields)

Calculate a hash from a FieldSet name and field data.

Parameters:
Return type:

int

property digest

Generate persistent hash for FieldSet.

This MD5-based hash is used for identifying field sets within NetCDF files and is used to check the integrity of the link between associated NetCDF files and base trajectory NetCDF files in the TrajectoryStore class.

property dimensions: set[Dimension]

Combined dimensions of all fields in the field set.

property fields

Return an immutable view of the field definitions.

classmethod from_netcdf_group(group)

Construct a FieldSet from a NetCDF group.

Parameters:

group (Group)

Return type:

FieldSet

classmethod from_registry(name)

Retrieve a FieldSet from the registry by name.

Parameters:

name (str)

Return type:

FieldSet

classmethod known(name)

Check if a FieldSet with the given name exists in the registry.

Parameters:

name (str)

Return type:

bool

merge(other)

Combine field sets, ensuring unique field names.

single_point()

Return a new FieldSet containing only fields that have a point dimension, with the point dimension removed. This makes it possible to derive the equivalent “single point” field set for any field set containing whatever kinds of fields.

Return type:

FieldSet

enum AEIC.storage.FlightPhase(value)

Flight phases known to AEIC.

Member Type:

int

Valid values are as follows:

IDLE_ORIGIN = <FlightPhase.IDLE_ORIGIN: 1>
TAXI_ORIGIN = <FlightPhase.TAXI_ORIGIN: 2>
TAKEOFF = <FlightPhase.TAKEOFF: 3>
CLIMB = <FlightPhase.CLIMB: 4>
CRUISE = <FlightPhase.CRUISE: 5>
DESCENT = <FlightPhase.DESCENT: 6>
APPROACH = <FlightPhase.APPROACH: 7>
TAXI_DESTINATION = <FlightPhase.TAXI_DESTINATION: 8>
IDLE_DESTINATION = <FlightPhase.IDLE_DESTINATION: 9>

The Enum and its members also have the following methods:

property field_name

Trajectory point count field name for this flight phase.

property method_name

Method name used in trajectory builders for this flight phase.

property field_label

Human-readable label for this flight phase.

classmethod from_field_name(field_name)

Parse trajectory point count field name to get flight phase.

Parameters:

field_name (str)

class AEIC.storage.HasFieldSets(*args, **kwargs)

Protocol for objects that have associated field sets.

class AEIC.storage.ReproducibilityData(python_version, software_version, git_commit, git_branch, git_dirty, sample_fraction, sample_seed, config, files=<factory>)

Container for information about the software environment and accessed files during simulations, to enable reproduction of results and debugging.

Parameters:

  • python_version (str)

  • software_version (str)

  • git_commit (str | None)

  • git_branch (str | None)

  • git_dirty (bool)

  • sample_fraction (float | None)

  • sample_seed (int | None)

  • config (str)

  • files (list[Path])

config: str

String representation of the AEIC configuration used during simulations.

files: list[Path]

List of file paths accessed during simulations, captured by the AccessRecorder.

git_branch: str | None

Git branch name if available, or None if not in a Git repository.

git_commit: str | None

Git commit hash if available, or None if not in a Git repository.

git_dirty: bool

True if there are uncommitted changes in the Git repository, False if clean or not in a Git repository.

python_version: str

Python version string, e.g. ‘3.13.12’.

sample_fraction: float | None

Optional sample fraction used during simulations, if applicable.

sample_seed: int | None

Optional random seed used during simulations, if applicable.

software_version: str

Version string for the AEIC software, ideally including Git metadata if available, e.g. ‘v1.2.0’, ‘v1.2.3-4-gabcdef-dirty’ or ‘unknown’.

classmethod union(*data_list)

Combine a list of ReproducibilityData instances by merging their file lists and ensuring other fields match (or are compatible).

Parameters:

data_list (ReproducibilityData)

Return type:

ReproducibilityData

AEIC.storage.track_file_accesses()

Context manager to enable tracking of file accesses during simulations. Usage:

```python with track_file_accesses():

run_simulations()

```

After the block, accessed files can be retrieved from access_recorder.paths.