Family Module

The family module provides light-weight container that groups a family of periodic orbits obtained via a continuation engine.

It offers convenience helpers for iteration, random access, conversion to a pandas.DataFrame, and basic serialisation to an HDF5 file leveraging the existing utilities in io.

OrbitFamily()

Container for an ordered family of periodic orbits.

class hiten.system.family.OrbitFamily[source]

Bases: _HitenBase

Container for an ordered family of periodic orbits.

Parameters:

  • orbits (List[PeriodicOrbit]) – The orbits in the family.

  • parameter_name (str) – The name of the parameter that is varied.

  • parameter_values (np.ndarray) – The values of the parameter that is varied.

property periods: ndarray

Array of orbit periods.

Returns:

Array of orbit periods in nondimensional units (NaN if not available).

Return type:

numpy.ndarray

property jacobis: ndarray

Array of Jacobi constants for all orbits.

Returns:

Array of Jacobi constants (dimensionless).

Return type:

numpy.ndarray

propagate(**kwargs)[source]

Propagate all orbits in the family.

Parameters:

**kwargs – Additional keyword arguments passed to each orbit’s propagate method.

Return type:

None

to_csv(filepath, **kwargs)[source]

Export the contents of the orbit family to a CSV file.

Parameters:

  • filepath (str or Path) – Destination CSV file path.

  • **kwargs – Extra keyword arguments passed to propagate().

Raises:

ValueError – If no trajectory data is available to export.

Return type:

None

to_df(**kwargs)[source]

Return a DataFrame summarising the family.

Parameters:

**kwargs – Additional keyword arguments passed to propagate().

Return type:

DataFrame

classmethod from_result(result, parameter_name=None)[source]

Build an OrbitFamily from a ContinuationResult.

Parameters:

  • result (ContinuationResult) – Result object returned by the new continuation engine/facade.

  • parameter_name (str or None, optional) – Name for the continuation parameter. If None, defaults to “param”.

Returns:

A new OrbitFamily instance containing the orbits from the result.

Return type:

OrbitFamily

save(filepath, *, compression='gzip', level=4)[source]

Save the family to an pickle file.

Parameters:

  • filepath (str or Path) – The path to the file to save the family to.

  • compression (str, default "gzip") – The compression algorithm to use.

  • level (int, default 4) – The compression level to use.

Return type:

None

classmethod load(filepath, **kwargs)[source]

Load a OrbitFamily from a file (new instance).

Parameters:

  • filepath (str or Path) – The path to the file to load the family from.

  • **kwargs – Additional keyword arguments for the load operation.

Return type:

OrbitFamily

plot(*, dark_mode=True, save=False, filepath='orbit_family.svg', **kwargs)[source]

Visualise the family trajectories in rotating frame.

Parameters:

  • dark_mode (bool, default True) – Whether to use dark mode for the plot.

  • save (bool, default False) – Whether to save the plot to a file.

  • filepath (str, default "orbit_family.svg") – Path where to save the plot if save=True.

  • **kwargs – Additional keyword arguments passed to the plotting function.

Returns:

The generated plot figure.

Return type:

matplotlib.figure.Figure

Raises:

ValueError – If orbits have no trajectory data available.