# Trajectory stores

Trajectories generated by simulation using trajectory builders can be
persisted to NetCDF files using the `TrajectoryStore` class. This provides a
general facility for storing trajectory and associated data that covers not
only the base case of saving simple trajectory data, but also storing
associated data like emissions values alongside trajectory data.

This system works in conjunction with the `Trajectory` and `FieldSet` classes.
Each field set for a trajectory is stored in a separate NetCDF group within a
NetCDF file (or files: see below). Associated data can be stored in separate
associated NetCDF files to allow for cases where emissions data is created by
a separate process from the base trajectory simulation.

When working in conjunction with the missions database, a `TrajectoryStore`
can create an index based on the mission database flight ID. This makes
referencing simulated trajectories based on mission database queries
straightforward.

More detailed information can be found in the documentation string for the
`TrajectoryStore` class. Example usage of the `TrajectoryStore` class can be
found in the `test/test_trajectory_stores.py` test file, and a more extended
example, including parallel generation and merging of trajectory stores can be
seen in the `notebooks/end-to-end-simulation.ipynb` notebook in the AEIC
repository.

```{eval-rst}
.. WARNING::
   The `TrajectoryStore` class is not thread-safe. Even opening a trajectory
   store read-only in multiple threads is unsafe. This is a limitation of the
   underlying HDF5 and netcdf-c libraries on which the Python netCDF4 package
   relies.

   Parallelism for trajectory stores should always be done at the process
   level. Multiple processes can open a trajectory store for reading without
   causing problems. For creating trajectory stores in parallel, there is a
   facility to merge multiple stores into a single "merged store": split the
   simulation work to be done, run simulations in separate processes and
   create multiple trajectory stores, one per process, then merge them. The
   merged store can then be opened in parallel by multiple processes for
   further processing. This approach avoids all problems with the lack of
   thread safety in the underlying libraries.
```

```{eval-rst}
.. autoclass:: AEIC.trajectories.store.TrajectoryStore
   :members:
```