Connections Base

The base module provides the core connections framework and user-facing interface for connection discovery.

Main Classes

class hiten.algorithms.connections.base.ConnectionPipeline[source]

Bases: _HitenBasePipeline, Generic[DomainT, InterfaceT, ConfigT, ResultT]

Provide a user-facing facade for connection discovery and plotting in CR3BP.

This class provides a high-level interface for discovering ballistic and impulsive transfers between manifolds in the Circular Restricted Three-Body Problem. It wraps the lower-level connection engine and provides convenient methods for solving connection problems and visualizing results.

Parameters:

config (ConnectionConfig) – Configuration object containing section, direction, and search parameters.
interface (_ManifoldConnectionInterface) – Interface for translating between domain objects and backend inputs.
engine (_ConnectionEngine, optional) – Engine instance to use for connection discovery. If None, must be set later or use with_default_engine() factory method.
backend (_ConnectionsBackend)

Examples

>>> from hiten.algorithms.connections import ConnectionPipeline, SearchConfig
>>> from hiten.algorithms.poincare import SynodicMapConfig
>>> from hiten.system import System
>>>
>>> system = System.from_bodies("earth", "moon")
>>> mu = system.mu

>>> l1 = system.get_libration_point(1)
>>> l2 = system.get_libration_point(2)
>>>
>>> halo_l1 = l1.create_orbit('halo', amplitude_z=0.5, zenith='southern')
>>> halo_l1.correct()
>>> halo_l1.propagate()
>>>
>>> halo_l2 = l2.create_orbit('halo', amplitude_z=0.3663368, zenith='northern')
>>> halo_l2.correct()
>>> halo_l2.propagate()
>>>
>>> manifold_l1 = halo_l1.manifold(stable=True, direction='positive')
>>> manifold_l1.compute(integration_fraction=0.9, step=0.005)
>>>
>>> manifold_l2 = halo_l2.manifold(stable=False, direction='negative')
>>> manifold_l2.compute(integration_fraction=1.0, step=0.005)
>>>
>>> section_cfg = SynodicMapConfig(
>>>     section_axis="x",
>>>     section_offset=1 - mu,
>>>     plane_coords=("y", "z"),
>>>     interp_kind="cubic",
>>>     segment_refine=30,
>>>     tol_on_surface=1e-9,
>>>     dedup_time_tol=1e-9,
>>>     dedup_point_tol=1e-9,
>>>     max_hits_per_traj=None,
>>>     n_workers=None,
>>> )
>>>
>>> conn = ConnectionPipeline.with_default_engine(
>>>     config=ConnectionConfig(
>>>         section=section_cfg,
>>>         direction=None,
>>>         delta_v_tol=1,
>>>         ballistic_tol=1e-8,
>>>         eps2d=1e-3,
>>>     )
>>> )
>>>
>>> conn.solve(manifold_l1, manifold_l2)
>>> print(conn)
>>> conn.plot(dark_mode=True)

Notes

The connection algorithm works by: 1. Intersecting both manifolds with the specified synodic section 2. Finding geometrically close points between the two intersection sets 3. Refining matches using local segment geometry 4. Computing Delta-V requirements and classifying transfers

See also

_ConnectionEngine: Lower-level engine that performs the actual computation.
Connections: Container for connection results with convenient access methods.

classmethod with_default_engine(*, config, interface=None, backend=None)[source]

Create a facade instance with a default engine (factory).

The default engine uses _ConnectionsBackend.

Parameters:

config (ConnectionConfig) – Configuration object containing section, direction, and search parameters.
interface (_ManifoldConnectionInterface, optional) – Interface for translating between domain objects and backend inputs. If None, uses the default _ManifoldConnectionInterface.
backend (_ConnectionsBackend, optional) – Backend instance for the connection algorithm. If None, uses the default _ConnectionsBackend.

Returns:

A connection facade instance with a default engine injected.

Return type:

ConnectionPipeline

solve(source, target, options)[source]

Discover connections between two manifolds.

This method finds ballistic and impulsive transfers between the source and target manifolds by intersecting them with the configured synodic section and analyzing potential connection points.

Parameters:

source (Manifold) – Source manifold (e.g., unstable manifold of a periodic orbit).
target (Manifold) – Target manifold (e.g., stable manifold of another periodic orbit).
options (ConnectionOptions) – Runtime options for the connection search.

Returns:

ConnectionPipeline results sorted by increasing Delta-V requirement. Each result contains transfer type, Delta-V, intersection points, and 6D states at the connection.

Return type:

Connections

Notes

Results are cached internally for convenient access via the results property and for plotting with the plot() method.

The algorithm performs these steps: 1. Convert manifolds to section interfaces 2. Create connection problem specification 3. Delegate to _ConnectionEngine 4. Cache results for later use

Examples

>>> from hiten.algorithms.connections.options import ConnectionOptions
>>> options = ConnectionOptions()
>>> results = connection.solve(unstable_manifold, stable_manifold, options)
>>> print(results)

property results: Connections

Access the latest connection results with convenient formatting.

Returns:: A view over the latest results with friendly printing and convenient access methods. Returns an empty view if solve() has not been called yet.
Return type:: Connections

Notes

This property provides access to cached results from the most recent call to solve(). The Connections wrapper provides enhanced formatting and filtering capabilities.

Examples

>>> connection.solve(source, target)
>>> print(connection.results)  # Pretty-printed summary
>>> ballistic = connection.results.ballistic  # Filter by type

plot(**kwargs)[source]

Create a visualization of the connection results on the synodic section.

This method generates a Poincare map showing the intersection points of both manifolds with the synodic section, highlighting discovered connections with color-coded Delta-V values.

Parameters:: **kwargs – Additional keyword arguments passed to plot_poincare_connections_map(). Common options include figure size, color maps, and styling parameters.
Returns:: The plot object, which can be further customized or saved.
Return type:: matplotlib figure or axes
Raises:: ValueError – If solve() has not been called yet (no cached data to plot).

Notes

The plot shows: - Source manifold intersection points (typically unstable manifold) - Target manifold intersection points (typically stable manifold) - ConnectionPipeline points with color-coded Delta-V requirements - Section coordinate labels and axes

Examples

>>> connection.solve(source, target)
>>> fig = connection.plot(figsize=(10, 8), cmap='viridis')
>>> fig.savefig('connections.png')

See also

plot_poincare_connections_map(): Underlying plotting function with detailed parameter documentation.

plot_connection(index=0, **kwargs)[source]

Plot a specific heteroclinic connection showing the connecting trajectories.

This method visualizes a single connection by plotting the portions of trajectories from both manifolds that lead to the connection point, including flow direction arrows and a Delta-V arrow at the connection.

Parameters:

index (int, default=0) – Index of the connection to plot (0 = best/lowest Delta-V connection).
**kwargs –
Additional keyword arguments passed to plot_heteroclinic_connection(). Common options include:
- figsize : tuple, default (10, 8)
- save : bool, default False
- dark_mode : bool, default True
- filepath : str, default ‘heteroclinic_connection.svg’
- src_color : str, default ‘red’
- tgt_color : str, default ‘blue’
- dv_arrow_scale : float, default 0.05
- flow_arrow_spacing : int, default 10

Returns:

(fig, ax) containing the matplotlib figure and axis objects.

Return type:

tuple

Raises:

EngineError – If solve() has not been called yet.
IndexError – If the specified index is out of range for the available connections.

Notes

The plot shows:

Trajectory portions from source manifold (unstable) in red
Trajectory portions from target manifold (stable) in blue
Flow direction arrows along both trajectories
Connection point marked with a yellow circle
Delta-V vector as a magenta arrow (if non-negligible)
Text annotation with connection type and Delta-V magnitude
Parent periodic orbits (naturally included in manifold trajectories)

Examples

>>> # Plot the best connection (index 0)
>>> connection.solve(source, target)
>>> connection.plot_connection()
>>>
>>> # Plot a specific connection with custom styling
>>> connection.plot_connection(
...     index=5,
...     figsize=(12, 10),
...     dark_mode=True,
...     src_color='cyan',
...     tgt_color='magenta'
... )