Input/Output Module

The io module provides comprehensive serialization and file I/O utilities for the hiten package.

This module provides a complete set of utilities for serializing and deserializing various hiten objects to/from HDF5 files. It includes specialized I/O functions for center manifolds, Hamiltonians, manifolds, Poincare maps, and periodic orbits. All data is stored in HDF5 format with version tracking and supports compression for efficient storage.

Common I/O Utilities

The common module provides shared utilities for file and directory operations.

hiten.utils.io.common._ensure_dir(path)[source]

Create directory and any parent directories if they do not exist.

Parameters:: path (str or os.PathLike) – Directory path that should exist after this call. Accepts any object supported by pathlib.Path.
Return type:: None

Notes

This function is safe to call multiple times - it will not raise an error if the directory already exists. Parent directories are created recursively as needed.

Examples

>>> _ensure_dir("path/to/directory")
>>> _ensure_dir(Path("another/path"))

hiten.utils.io.common._write_dataset(group, name, data, *, compression='gzip', level=4)[source]

Write data into HDF5 group under dataset name if data is not None.

Parameters:

group (h5py.Group) – Open h5py group or file handle.
name (str) – Name of the dataset to create.
data (numpy.ndarray or None) – Array to store. If None, the function is a no-op.
compression (str, default "gzip") – Compression backend passed to h5py.Group.create_dataset.
level (int, default 4) – Compression level (0-9, higher means better compression).

Return type:

None

Notes

This function safely handles None data by performing no operation. Only numpy arrays are written to the HDF5 group.

Examples

>>> import h5py
>>> import numpy as np
>>> with h5py.File("test.h5", "w") as f:
...     _write_dataset(f, "my_data", np.array([1, 2, 3]))
>>> with h5py.File("test.h5", "w") as f:
...     _write_dataset(f, "empty", None)  # No-op

Center Manifold I/O

The center module provides I/O utilities for center manifold data.

hiten.utils.io.center.save_center_manifold(cm, path, **kwargs)[source]

Serialize center manifold to a pickle file.

Parameters:

cm (CenterManifold) – The center manifold object to serialize.
path (str or pathlib.Path) – File path where to save the center manifold data.
**kwargs – Additional arguments (ignored for pickle serialization).

Return type:

None

Examples

>>> from hiten.system import System
>>> from hiten.system.center import CenterManifold
>>> system = System.from_bodies("earth", "moon")
>>> L2 = system.get_libration_point(2)
>>> cm = CenterManifold(L2, degree=10)
>>> save_center_manifold(cm, "my_center_manifold.pkl")

hiten.utils.io.center.load_center_manifold(path)[source]

Load a center manifold from a pickle file.

Parameters:: path (str or pathlib.Path) – File path containing the center manifold data.
Returns:: The reconstructed center manifold object.
Return type:: CenterManifold
Raises:: FileNotFoundError – If the specified file does not exist.

Examples

>>> cm = load_center_manifold("my_center_manifold.pkl")
>>> print(f"Loaded center manifold with degree {cm.degree}")

hiten.utils.io.center.load_center_manifold_inplace(obj, path)[source]

Populate an existing center manifold object from a pickle file.

Parameters:

obj (CenterManifold) – The center manifold object to populate.
path (str or pathlib.Path) – File path containing the center manifold data.

Return type:

None

Hamiltonian I/O

The hamiltonian module provides I/O utilities for Hamiltonian data.

hiten.utils.io.hamiltonian.save_hamiltonian(ham, path, **kwargs)[source]

Serialize a Hamiltonian object to a pickle file.

Parameters:

ham (Hamiltonian) – The Hamiltonian object to serialize.
path (str or pathlib.Path) – File path where to save the Hamiltonian data.
**kwargs – Additional arguments (ignored for pickle serialization).

Return type:

None

Examples

>>> from hiten.system.hamiltonian import Hamiltonian
>>> import numpy as np
>>> ham = Hamiltonian([np.array([1.0, 2.0])], degree=2, ndof=3, name="test")
>>> save_hamiltonian(ham, "my_hamiltonian.pkl")

hiten.utils.io.hamiltonian.load_hamiltonian(path, **kwargs)[source]

Load a Hamiltonian object from a pickle file.

Parameters:

path (str or pathlib.Path) – File path containing the Hamiltonian data.
**kwargs – Additional keyword arguments (currently unused).

Returns:

The reconstructed Hamiltonian object.

Return type:

Hamiltonian

Raises:

FileNotFoundError – If the specified file does not exist.

Examples

>>> ham = load_hamiltonian("my_hamiltonian.pkl")
>>> print(f"Loaded Hamiltonian: {ham.name}")

hiten.utils.io.hamiltonian.save_lie_generating_function(lgf, path, **kwargs)[source]

Serialize a LieGeneratingFunction object to a pickle file.

Parameters:

lgf (LieGeneratingFunction) – The LieGeneratingFunction object to serialize.
path (str or pathlib.Path) – File path where to save the LieGeneratingFunction data.
**kwargs – Additional arguments (ignored for pickle serialization).

Return type:

None

Examples

>>> from hiten.system.hamiltonian import LieGeneratingFunction
>>> import numpy as np
>>> lgf = LieGeneratingFunction([np.array([1.0, 2.0])], [np.array([0.5])], degree=2, ndof=3, name="test")
>>> save_lie_generating_function(lgf, "my_lgf.pkl")

hiten.utils.io.hamiltonian.load_lie_generating_function(path, **kwargs)[source]

Load a LieGeneratingFunction object from a pickle file.

Parameters:

path (str or pathlib.Path) – File path containing the LieGeneratingFunction data.
**kwargs – Additional keyword arguments (currently unused).

Returns:

The reconstructed LieGeneratingFunction object.

Return type:

LieGeneratingFunction

Raises:

FileNotFoundError – If the specified file does not exist.

Examples

>>> lgf = load_lie_generating_function("my_lgf.pkl")
>>> print(f"Loaded LieGeneratingFunction: {lgf.name}")

hiten.utils.io.hamiltonian.load_hamiltonian_inplace(obj, path)[source]

Populate an existing Hamiltonian object from a pickle file.

Parameters:

obj (Hamiltonian) – The Hamiltonian object to populate.
path (str or pathlib.Path) – File path containing the Hamiltonian data.

Return type:

None

hiten.utils.io.hamiltonian.load_lie_generating_function_inplace(obj, path)[source]

Populate an existing LieGeneratingFunction object from a pickle file.

Parameters:

obj (LieGeneratingFunction) – The LieGeneratingFunction object to populate.
path (str or pathlib.Path) – File path containing the LieGeneratingFunction data.

Return type:

None

Manifold I/O

The manifold module provides I/O utilities for manifold data.

hiten.utils.io.manifold.save_manifold(manifold, path, **kwargs)[source]

Serialize manifold to a pickle file.

Parameters:

manifold (Manifold) – The manifold object to serialize.
path (str or pathlib.Path) – File path where to save the manifold data.
**kwargs – Additional arguments (ignored for pickle serialization).

Return type:

None

hiten.utils.io.manifold.load_manifold(path)[source]

Load a manifold from a pickle file.

Parameters:: path (str or pathlib.Path) – File path containing the manifold data.
Returns:: The reconstructed manifold object.
Return type:: Manifold
Raises:: FileNotFoundError – If the specified file does not exist.

Poincare Map I/O

The map module provides I/O utilities for Poincare map data.

hiten.utils.io.map.save_poincare_map(pmap, path, **kwargs)[source]

Serialize Poincare map to a pickle file.

Parameters:

pmap (CenterManifoldMap) – The Poincare map object to serialize.
path (str or pathlib.Path) – File path where to save the Poincare map data.
**kwargs – Additional arguments (ignored for pickle serialization).

Return type:

None

Examples

>>> from hiten.system import System
>>> from hiten.system.maps.center import CenterManifoldMap
>>> system = System.from_bodies("earth", "moon")
>>> L2 = system.get_libration_point(2)
>>> cm = CenterManifoldMap(L2, degree=10)
>>> pmap = cm.poincare_map(energy=0.1)
>>> save_poincare_map(pmap, "my_poincare_map.pkl")

hiten.utils.io.map.load_poincare_map_inplace(obj, path)[source]

Populate an existing Poincare map object from a pickle file.

Parameters:

obj (CenterManifoldMap) – The Poincare map object to populate with data.
path (str or pathlib.Path) – File path containing the Poincare map data.

Raises:

FileNotFoundError – If the specified file does not exist.

Return type:

None

Examples

>>> from hiten.system.maps.center import CenterManifoldMap
>>> pmap = CenterManifoldMap(cm, energy=0.1)
>>> load_poincare_map_inplace(pmap, "my_poincare_map.pkl")

hiten.utils.io.map.load_poincare_map(path)[source]

Load a Poincare map from a pickle file.

Parameters:

path (str or pathlib.Path) – File path containing the Poincare map data.
cm (CenterManifoldMap) – The center manifold object to associate with the map.

Returns:

The reconstructed Poincare map object.

Return type:

CenterManifoldMap

Raises:

FileNotFoundError – If the specified file does not exist.

Examples

>>> from hiten.system import System
>>> from hiten.system.center import CenterManifold
>>> system = System.from_bodies("earth", "moon")
>>> L2 = system.get_libration_point(2)
>>> cm = CenterManifold(L2, degree=10)
>>> pmap = load_poincare_map("my_poincare_map.pkl", cm)
>>> print(f"Loaded map with energy {pmap.energy}")

Periodic Orbit I/O

The orbits module provides I/O utilities for periodic orbit data.

hiten.utils.io.orbits.save_periodic_orbit(orbit, path, **kwargs)[source]

Serialize periodic orbit to a pickle file.

Parameters:

orbit (PeriodicOrbit) – The periodic orbit object to serialize.
path (str or pathlib.Path) – File path where to save the orbit data.
**kwargs – Additional arguments (ignored for pickle serialization).

Return type:

None

hiten.utils.io.orbits.load_periodic_orbit_inplace(obj, path)[source]

Load periodic orbit data into existing object.

Parameters:

obj (PeriodicOrbit) – The periodic orbit object to populate with data.
path (str or pathlib.Path) – File path containing the orbit data.

Return type:

None

hiten.utils.io.orbits.load_periodic_orbit(path)[source]

Load a periodic orbit from a pickle file.

Parameters:: path (str or pathlib.Path) – File path containing the orbit data.
Returns:: The reconstructed periodic orbit object.
Return type:: PeriodicOrbit
Raises:: FileNotFoundError – If the specified file does not exist.

Body I/O

The body module provides I/O utilities for body data.

hiten.utils.io.body.save_body(body, path)[source]

Serialize a Body to a pickle file.

Parameters:

body (Body) – Body instance to serialize.
path (str or pathlib.Path) – File path where to save the body.

Return type:

None

hiten.utils.io.body.load_body(path)[source]

Load a Body from a pickle file.

Parameters:: path (str or pathlib.Path) – File path containing the body description.
Returns:: The reconstructed Body instance.
Return type:: Body

hiten.utils.io.body.load_body_inplace(obj, path)[source]

Populate an existing Body object from a pickle file.

Parameters:

obj (Body) – Body instance to populate.
path (str or pathlib.Path) – File path with serialized body.

Return type:

None

Family I/O

The family module provides I/O utilities for orbit family data.

hiten.utils.io.family.save_family(family, filepath, **kwargs)[source]

Serialize an orbit family to a pickle file.

Parameters:

family (OrbitFamily)
filepath (str | Path)

Return type:

None

hiten.utils.io.family.load_family(filepath, **kwargs)[source]

Load an orbit family from a pickle file.

Parameters:: filepath (str | Path)
Return type:: OrbitFamily

hiten.utils.io.family.load_family_inplace(family, filepath, **kwargs)[source]

Load an orbit family into an existing object from a pickle file.

Parameters:

family (OrbitFamily)
filepath (str | Path)

Return type:

None

Libration Point I/O

The libration module provides I/O utilities for libration point data.

hiten.utils.io.libration.save_libration_point(lp, path, **kwargs)[source]

Serialize a LibrationPoint to a pickle file.

Parameters:

lp (LibrationPoint) – Libration point instance to serialize.
path (str or pathlib.Path) – File path where to save the libration point.
**kwargs – Additional arguments (ignored for pickle serialization).

Return type:

None

hiten.utils.io.libration.load_libration_point(path, **kwargs)[source]

Load a LibrationPoint from a pickle file.

Parameters:

path (str or pathlib.Path) – File path containing the libration point data.
**kwargs – Additional arguments (ignored for pickle deserialization).

Returns:

The reconstructed libration point instance.

Return type:

LibrationPoint

hiten.utils.io.libration.load_libration_point_inplace(obj, path)[source]

Populate an existing LibrationPoint object from a pickle file.

Parameters:

obj (LibrationPoint) – The libration point instance to populate.
path (str or pathlib.Path) – File path containing the libration point data.

Return type:

None

System I/O

The system module provides I/O utilities for system data.

hiten.utils.io.system.save_system(system, path)[source]

Serialize a System to a pickle file.

Parameters:

system (System) – The CR3BP system instance to serialize.
path (str or pathlib.Path) – File path where to save the system description.

Return type:

None

hiten.utils.io.system.load_system(path)[source]

Load a System from a pickle file.

Parameters:: path (str or pathlib.Path) – File path containing the system description.
Returns:: The reconstructed system instance.
Return type:: System

hiten.utils.io.system.load_system_inplace(obj, path)[source]

Populate an existing System object from a pickle file.

Parameters:

obj (System) – The System instance to populate.
path (str or pathlib.Path) – File path containing the serialized system description.

Return type:

None

Torus I/O

The torus module provides I/O utilities for invariant torus data.

hiten.utils.io.torus.save_torus(torus, path, **kwargs)[source]

Serialize an invariant torus to a pickle file.

Parameters:

torus (InvariantTori)
path (str | Path)

Return type:

None

hiten.utils.io.torus.load_torus(path)[source]

Load an invariant torus from a pickle file.

Parameters:: path (str | Path)
Return type:: InvariantTori

hiten.utils.io.torus.load_torus_inplace(obj, path)[source]

Populate an existing invariant torus from a pickle file.

Parameters:

obj (InvariantTori)
path (str | Path)

Return type:

None