Connections Backends

The backends module provides backend routines for discovering connections between synodic sections in CR3BP.

Backend Classes

class hiten.algorithms.connections.backends._ConnectionsBackend

Bases: _HitenBaseBackend

Encapsulate matching/refinement and Delta-V computation for connections.

This backend orchestrates the end-to-end process for discovering ballistic/impulsive transfers between two synodic sections within the CR3BP. It builds coarse hits, applies radius-based pairing and mutual-nearest filtering, refines matched pairs using local segment geometry, and finally computes the Delta-V required for each candidate transfer.

See also

_ConnectionResult

Result objects returned by the solve method.

run(request)

Compute possible connections from precomputed section data.

Parameters:

• pu (np.ndarray, shape (N, 2)) – 2D points on the unstable/source section.

• ps (np.ndarray, shape (M, 2)) – 2D points on the stable/target section.

• Xu (np.ndarray, shape (N, 6)) – 6D states corresponding to pu.

• Xs (ndarray, shape (M, 6)) – 6D states corresponding to ps.

• traj_indices_u (np.ndarray or None, shape (N,)) – Trajectory indices for source manifold intersections.

• traj_indices_s (ndarray or None, shape (M,)) – Trajectory indices for target manifold intersections.

• eps (float) – Pairing radius on the 2D section plane.

• dv_tol (float) – Maximum allowed Delta-V for accepting a connection.

• bal_tol (float) – Threshold for classifying a connection as ballistic.

• request (ConnectionsBackendRequest)

Returns:

ConnectionPipeline results sorted by increasing delta_v (velocity change).

Return type:

list of _ConnectionResult

Notes

Steps: 1. Coarse 2D radius pairing 2. Mutual-nearest filtering 3. Segment-based refinement 4. Delta-V computation and classification

on_start(problem)

Called by the engine before solving.

Return type:

None

on_success(results)

Called by the engine after successful solve.

Parameters:

results (list[_ConnectionResult])

Return type:

None

on_failure(error)

Called by the engine on failure.

Parameters:

error (Exception)

Return type:

None

Functions

hiten.algorithms.connections.backends._pair_counts()

Return for each query point the number of reference points within radius^2.

Parameters:

• query (np.ndarray, shape (N, 2)) – 2D coordinates of query points.

• ref (np.ndarray, shape (M, 2)) – 2D coordinates of reference points.

• r2 (float) – Radius squared for distance comparison.

Returns:

For each query point, the count of reference points with distance^2 <= r2.

Return type:

np.ndarray, shape (N,)

Notes

Used by _radpair2d() to efficiently allocate storage for pairs.

hiten.algorithms.connections.backends._exclusive_prefix_sum()

Compute exclusive prefix sum of an integer array.

Parameters:

a (np.ndarray) – Input integer array of length N.

Returns:

Exclusive prefix sums where out[0] = 0 and out[i+1] = sum_{k=0}^{i} a[k].

Return type:

np.ndarray, shape (N+1,)

Notes

Used by _radpair2d() to determine memory offsets for storing pairs.

hiten.algorithms.connections.backends._radpair2d()

Find all pairs (i,j) where distance(query[i], ref[j]) <= radius in 2D.

Parameters:

• query (np.ndarray, shape (N, 2)) – Query points in 2D.

• ref (np.ndarray, shape (M, 2)) – Reference points in 2D.

• radius (float) – Matching radius in the same units as query/ref coordinates.

Returns:

Each row is a pair (i, j) indicating a match between query[i] and ref[j].

Return type:

np.ndarray, shape (total, 2)

Notes

Uses _pair_counts() and _exclusive_prefix_sum() to efficiently allocate and populate the output array.

hiten.algorithms.connections.backends._radius_pairs_2d()

Return pairs (i,j) where ||query[i]-ref[j]|| <= radius on a 2D plane.

Parameters:

• query (ndarray, shape (N, 2)) – 2D plane coordinates of query points.

• ref (ndarray, shape (M, 2)) – 2D plane coordinates of reference points.

• radius (float) – Match radius in nondimensional CR3BP units.

Returns:

Each row is a pair (i, j) indicating a match between query[i] and ref[j].

Return type:

ndarray, shape (total, 2)

Notes

This is the main entry point for 2D radius-based pairing. It prepares contiguous arrays and delegates to the numba-accelerated _radpair2d().

hiten.algorithms.connections.backends._nearest_neighbor_2d_numba()

Find the nearest neighbor for each point in a 2D array (numba-accelerated).

Parameters:

points (np.ndarray, shape (N, 2)) – 2D coordinates of points.

Returns:

For each point i, the index j of its nearest neighbor (j != i). Returns -1 if no valid neighbor exists.

Return type:

np.ndarray, shape (N,)

Notes

This is the numba-accelerated implementation used by _nearest_neighbor_2d().

hiten.algorithms.connections.backends._nearest_neighbor_2d()

Find the nearest neighbor for each point in a 2D array.

Parameters:

points (np.ndarray, shape (N, 2)) – 2D coordinates of points.

Returns:

For each point i, the index j of its nearest neighbor (j != i). Returns -1 if no valid neighbor exists.

Return type:

np.ndarray, shape (N,)

Notes

This function prepares data and delegates to the numba-accelerated _nearest_neighbor_2d_numba().

hiten.algorithms.connections.backends._closest_points_on_segments_2d()

Find the closest points between two 2D line segments.

Parameters:

• a0x (float) – Start point of first segment.

• a0y (float) – Start point of first segment.

• a1x (float) – End point of first segment.

• a1y (float) – End point of first segment.

• b0x (float) – Start point of second segment.

• b0y (float) – Start point of second segment.

• b1x (float) – End point of second segment.

• b1y (float) – End point of second segment.

Returns:

• s (float) – Parameter along first segment (0 <= s <= 1).

• t (float) – Parameter along second segment (0 <= t <= 1).

• px, py (float) – Closest point on first segment.

• qx, qy (float) – Closest point on second segment.

Return type:

Tuple[float, float, float, float, float, float]

Notes

Used by _refine_pairs_on_section() for geometric refinement of matched pairs between synodic sections.

hiten.algorithms.connections.backends._refine_pairs_on_section()

Refine matched pairs using closest points between local segments.

Parameters:

• pu (np.ndarray, shape (N, 2)) – 2D points on the unstable (source) section.

• ps (np.ndarray, shape (M, 2)) – 2D points on the stable (target) section.

• pairs (np.ndarray, shape (k, 2)) – Initial matched pairs as (i, j) indices.

• nn_u (np.ndarray, shape (N,)) – Nearest neighbor indices for unstable section points.

• nn_s (np.ndarray, shape (M,)) – Nearest neighbor indices for stable section points.

• max_seg_len (float, optional) – Maximum allowed segment length for refinement (default: 1e9).

Returns:

• rstar (np.ndarray, shape (k, 2)) – Refined common points (midpoint of segment closest points).

• u_idx0, u_idx1 (np.ndarray, shape (k,)) – Endpoint indices used on the unstable section.

• s_idx0, s_idx1 (np.ndarray, shape (k,)) – Endpoint indices used on the stable section.

• sval, tval (ndarray, shape (k,)) – Interpolation parameters on U and S segments.

• valid (ndarray, shape (k,)) – Boolean mask indicating pairs where refinement was performed.

Return type:

Tuple[ndarray, ndarray, ndarray, ndarray, ndarray, ndarray, ndarray]

Notes

Uses _closest_points_on_segments_2d() to find optimal intersection points between local segments formed by nearest neighbors.