Plotting Module

The plots module provides a wide range of visualization functions for orbits, manifolds, Poincare maps, and other dynamical system visualizations in the Circular Restricted Three-Body Problem (CR3BP).

This module provides a comprehensive set of plotting utilities for visualizing dynamical systems, including orbit trajectories, invariant manifolds, Poincare maps, and invariant tori. All plotting functions support both light and dark modes, and most functions include options for saving plots to files. Coordinate systems are clearly labeled with appropriate units.

Animation Functions

Functions for creating animated visualizations.

hiten.utils.plots.animate_trajectories(states, times, bodies, system_distance, interval=10, figsize=(14, 6), save=False, dark_mode=True, filepath='trajectory.mp4')

Create an animated comparison of trajectories in rotating and inertial frames.

Parameters:

• states (numpy.ndarray, shape (n, 6)) – State vectors [x, y, z, vx, vy, vz] in nondimensional units.

• times (numpy.ndarray, shape (n,)) – Time array in nondimensional units.

• bodies (list of Body) – List of celestial body objects with properties like mass, radius, and name.

• system_distance (float) – Characteristic distance of the system in meters.

• interval (int, default 10) – Time interval between animation frames in milliseconds.

• figsize (tuple, default (14, 6)) – Figure size in inches (width, height).

• save (bool, default False) – Whether to save the animation as an MP4 file.

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

• filepath (str, default 'trajectory.mp4') – Path where to save the animation if save=True.

Returns:

The animation object.

Return type:

matplotlib.animation.FuncAnimation

Notes

This function creates a side-by-side animation showing the trajectory in both rotating and inertial frames, with consistent axis scaling to maintain proper proportions. The animation shows the motion of celestial bodies and the particle over time, with time displayed in days.

Orbit Plotting Functions

Functions for plotting orbit trajectories.

hiten.utils.plots.plot_rotating_frame(states, times, bodies, system_distance, figsize=(10, 8), save=False, dark_mode=True, filepath='rotating_frame.svg', *, block=True, close_after=True, **kwargs)

Plot the orbit trajectory in the rotating reference frame.

Parameters:

• states (numpy.ndarray, shape (n, 6)) – State vectors [x, y, z, vx, vy, vz] in nondimensional units.

• times (numpy.ndarray, shape (n,)) – Time array in nondimensional units.

• bodies (list of Body) – The celestial bodies to plot.

• system_distance (float) – The distance between the bodies in meters.

• figsize (tuple, default (10, 8)) – Figure size in inches (width, height).

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

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

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

• block (bool, default True) – Whether to block execution while displaying the plot.

• close_after (bool, default True) – Whether to close the figure after displaying.

• **kwargs – Additional keyword arguments for plot customization.

Returns:

(fig, ax) containing the figure and axis objects for further customization

Return type:

tuple

hiten.utils.plots.plot_inertial_frame(states, times, bodies, system_distance, figsize=(10, 8), save=False, dark_mode=True, filepath='inertial_frame.svg', *, block=True, close_after=True, **kwargs)

Plot the orbit trajectory in the primary-centered inertial reference frame.

Parameters:

• states (numpy.ndarray, shape (n, 6)) – State vectors [x, y, z, vx, vy, vz] in nondimensional units.

• times (numpy.ndarray, shape (n,)) – Time array in nondimensional units.

• bodies (list of Body) – The celestial bodies to plot.

• system_distance (float) – The distance between the bodies in meters.

• figsize (tuple, default (10, 8)) – Figure size in inches (width, height).

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

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

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

• block (bool, default True) – Whether to block execution while displaying the plot.

• close_after (bool, default True) – Whether to close the figure after displaying.

• **kwargs – Additional keyword arguments for plot customization.

Returns:

(fig, ax) containing the figure and axis objects for further customization

Return type:

tuple

hiten.utils.plots.plot_orbit_family(states_list, times_list, parameter_values, bodies, system_distance, *, figsize=(10, 8), save=False, dark_mode=True, filepath='orbit_family.svg', **kwargs)

Visualise a family of periodic orbits (rotating-frame trajectories).

Parameters:

• states_list (list of numpy.ndarray) – Trajectory arrays for each family member in nondimensional units.

• times_list (list of numpy.ndarray) – Time arrays for each family member in nondimensional units.

• parameter_values (numpy.ndarray) – Scalar parameter associated with each orbit (used for colour-coding).

• bodies (list of Body) – Primary and secondary bodies of the system.

• system_distance (float) – Characteristic distance in meters - needed to scale body radii.

• figsize (tuple, default (10, 8)) – Figure size in inches (width, height).

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

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

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

• **kwargs –

  Additional keyword arguments:

  cmapstr, default “plasma”

  Colormap for parameter color-coding.

  elevfloat, optional

  Elevation angle for 3D view.

  azimfloat, optional

  Azimuth angle for 3D view.

  equal_axesbool, default True

  Whether to use equal scaling for all axes.

  param_indexint, optional

  Index of parameter to use for color-coding when parameter_values is 2D.

Returns:

(fig, ax) containing the figure and axis objects for further customization

Return type:

tuple

Manifold Plotting Functions

Functions for plotting invariant manifolds.

hiten.utils.plots.plot_manifold(states_list, times_list, bodies, system_distance, figsize=(10, 8), save=False, dark_mode=True, filepath='manifold.svg', **kwargs)

Plot the manifold trajectories.

Parameters:

• states_list (list of numpy.ndarray) – List of state arrays for each manifold trajectory in nondimensional units.

• times_list (list of numpy.ndarray) – List of time arrays for each manifold trajectory in nondimensional units.

• bodies (list of Body) – The celestial bodies to plot.

• system_distance (float) – The distance between the bodies in meters.

• figsize (tuple, default (10, 8)) – Figure size in inches (width, height).

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

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

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

• **kwargs – Additional keyword arguments for plot customization.

Returns:

(fig, ax) containing the figure and axis objects for further customization

Return type:

tuple

hiten.utils.plots.plot_manifolds(manifolds, *, figsize=(10, 8), save=False, dark_mode=True, filepath='manifolds.svg', labels=None, colors=None, cmap='tab10', alpha=0.6, equal_axes=True, **kwargs)

Plot several invariant manifolds on the same 3-D axes.

Parameters:

• manifolds (list of Manifold) – Collection of previously-computed Manifold objects. Each item must have been computed (trajectories property is not None).

• figsize (tuple, default (10, 8)) – Size of the matplotlib figure in inches.

• save (bool, default False) – Save the figure to filepath.

• dark_mode (bool, default True) – Apply the dark colour scheme.

• filepath (str, default "manifolds.svg") – Output path used if save is True.

• labels (list of str or None, optional) – Custom legend labels. Must match len(manifolds) when supplied.

• colors (list of str or None, optional) – Override the automatically-generated colours (one per manifold).

• cmap (str, default "tab10") – Matplotlib colormap used when colors is None.

• alpha (float, default 0.6) – Line opacity for manifold trajectories (0 < alpha <= 1).

• equal_axes (bool, default True) – Enforce identical scaling on all axes.

• **kwargs – Reserved for future extensions.

Returns:

(fig, ax) containing the figure and axis objects for further customization

Return type:

tuple

Raises:

ValueError – If manifolds list is empty, labels/colors length mismatch, or alpha out of range.

Poincare Map Functions

Functions for plotting Poincare maps.

hiten.utils.plots.plot_poincare_map(points, labels, figsize=(10, 8), save=False, dark_mode=True, filepath='poincare_map.svg', **kwargs)

Plot a Poincare map.

Parameters:

• points (numpy.ndarray, shape (n, 2)) – Poincare section points in nondimensional units.

• labels (list of str) – Axis labels for the plot.

• figsize (tuple, default (10, 8)) – Figure size in inches (width, height).

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

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

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

• **kwargs – Additional keyword arguments for plot customization.

Returns:

(fig, ax) containing the figure and axis objects for further customization

Return type:

tuple

hiten.utils.plots.plot_poincare_connections_map(points_src, points_tgt, labels, *, match_points=None, match_values=None, figsize=(8, 7), save=False, dark_mode=True, filepath='connections_poincare.svg', src_color='C0', tgt_color='C1', cmap='viridis')

Plot source/target section sets and candidate matches.

Parameters:

• points_src (numpy.ndarray, shape (N, 2)) – 2D section points for source in nondimensional units.

• points_tgt (numpy.ndarray, shape (N, 2)) – 2D section points for target in nondimensional units.

• labels (list or tuple of str) – Axes labels for the section projection.

• match_points (numpy.ndarray, shape (M, 2), optional) – 2D coordinates of candidate meet points in nondimensional units.

• match_values (numpy.ndarray, shape (M,), optional) – Quality metric at each meet point.

• figsize (tuple, default (8, 7)) – Figure size in inches (width, height).

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

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

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

• src_color (str, default 'C0') – Color for source points.

• tgt_color (str, default 'C1') – Color for target points.

• cmap (str, default 'viridis') – Colormap for match values.

Returns:

(fig, ax) containing the figure and axis objects for further customization

Return type:

tuple

hiten.utils.plots.plot_poincare_map_interactive(points, labels, on_select=None, figsize=(10, 8), dark_mode=True, **kwargs)

Interactive Poincare-map viewer.

Parameters:

• points (numpy.ndarray, shape (n, 2)) – Collection of Poincare-section points to visualise in nondimensional units.

• labels (list of str) – Axis labels corresponding to points (e.g. [“q2”, “p2”]).

• on_select (callable, optional) – Callback executed when a point is selected with the left mouse button. It receives the coordinates of the selected point (2,) and may return an arbitrary object (e.g. a GenericOrbit). The last returned value is also the return value of this function.

• figsize (tuple, default (10, 8)) – Figure size in inches.

• dark_mode (bool, default True) – Use a dark colour scheme.

• **kwargs – Currently ignored. Reserved for future extensions.

Returns:

The return value from the last on_select callback, or None if no callback.

Return type:

Any

Invariant Torus Functions

Functions for plotting invariant tori.

hiten.utils.plots.plot_invariant_torus(u_grid, bodies, system_distance, *, figsize=(10, 8), save=False, dark_mode=True, filepath='invariant_torus.svg', cmap='plasma', elev=None, azim=None, equal_axes=True, **kwargs)

Visualise an invariant torus in the rotating frame.

Parameters:

• u_grid (numpy.ndarray, shape (n_theta1, n_theta2, 6)) – Grid of state vectors returned by InvariantTori.sample_grid in nondimensional units.

• bodies (list of Body) – Primary and secondary bodies of the CR3BP.

• system_distance (float) – Characteristic distance in meters - required to scale the body radii.

• figsize (tuple, default (10, 8)) – Figure size in inches (width, height).

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

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

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

• cmap (str, default "plasma") – Colormap name used to colour-code the major-angle theta_1.

• elev (float, optional) – Elevation view angle passed to Axes3D.view_init.

• azim (float, optional) – Azimuth view angle passed to Axes3D.view_init.

• equal_axes (bool, default True) – If True, enforce identical scaling on all axes.

• **kwargs – Additional keyword arguments reserved for future extensions.

Returns:

(fig, ax) containing the figure and axis objects for further customization

Return type:

tuple

Helper Functions

Internal helper functions for plotting.

hiten.utils.plots._get_body_color(body, default_color)

Determine the color for a celestial body in a plot.

It returns the color specified in the Body object, unless the color is the default black (“#000000”), in which case it returns a specified default color. This ensures visibility in both light and dark modes.

Parameters:

• body (Body) – The celestial body object.

• default_color (str) – The color to use if the body’s color is the default black.

Returns:

The determined color string.

Return type:

str

hiten.utils.plots._plot_body(ax, center, radius, color, name, u_res=40, v_res=15, *, label=True)

Helper method to plot a celestial body as a sphere.

Parameters:

• ax (matplotlib.axes.Axes) – The 3D axes to plot on.

• center (numpy.ndarray, shape (3,)) – The (x, y, z) coordinates of the body center in nondimensional units.

• radius (float) – The radius of the body in nondimensional units.

• color (str) – The color to use for the body.

• name (str) – The name of the body to use in the label.

• u_res (int, default 40) – Resolution around the circumference (longitude).

• v_res (int, default 15) – Resolution from pole to pole (latitude).

• label (bool, default True) – Whether to add a text label for the body.

Return type:

None

hiten.utils.plots._set_axes_equal(ax)

Set 3D plot axes to equal scale.

Parameters:

ax (matplotlib.axes.Axes) – The 3D axes to adjust.

Return type:

None

hiten.utils.plots._set_dark_mode(fig, ax, title=None)

Apply dark mode styling to the figure and axes.

Handles both 2D and 3D axes with appropriate styling for each type.

Parameters:

• fig (matplotlib.figure.Figure) – The figure to apply dark mode styling to.

• ax (matplotlib.axes.Axes) – The 2D or 3D axes to apply dark mode styling to.

• title (str, optional) – The title to set with appropriate dark mode styling.

Return type:

None