distlink-python

An unofficial, source-level Python port of the DISTLINK C++ library for computing the minimum orbit intersection distance (MOID) and orbital linking coefficients. The public API retains the C++ names to make examples and results straightforward to compare.

This port is maintained independently and is not represented as an official release by the original DISTLINK authors.

Installation

After the first PyPI release:

python -m pip install distlink-python

The distribution is named distlink-python; the import name is distlink. To install the current development version directly from GitHub:

python -m pip install git+https://github.com/troyrock/distlink-python.git

The implementation uses only the Python standard library and supports Python 3.10 and later.

Quick start

from distlink import COrbitData, MOID_fast, detect_suitable_options

earth = COrbitData(1.00000011, 0.01671022, 0.0, 1.796767, -0.196535)
asteroid = COrbitData(1.4583, 0.2226, 0.05814, 2.20611, 3.56154)
max_root_error, min_root_error, _ = detect_suitable_options()
result = MOID_fast(earth, asteroid, max_root_error, min_root_error)
print(result.distance, result.good)

Angles are in radians. Distance results use the same unit as the supplied semimajor axes. Python float corresponds to the C++ double instantiation.

Input and numerical behavior

Orbital elements and numerical options must be finite. Eccentricity must be nonnegative, and exactly parabolic orbits (e == 1) are rejected. A nonzero semimajor axis is canonicalized to positive for an ellipse and negative for a hyperbola. Invalid inputs raise ValueError.

MOID_fast is deterministic and supports circular first orbits directly. It automatically exchanges the pair when only the first orbit is circular and uses the exact two-circle solution when both are circular. For other results marked unreliable, retrying in the opposite order remains reasonable before using MOID_direct_search as the fallback.

The direct scanner uses a full anomaly range for coplanar elliptic orbits. It rejects a coplanar hyperbolic pair because no finite scan interval can in general bound both unbounded branches; use MOID_fast for that case.

Verification against C++

The standard-library test suite compiles a fresh C++20 command-line oracle and compares Python results with it:

python -m unittest discover -s tests -v

The release CI pins the oracle to troyrock/distlink-cpp@58c1c29. For a local checkout, place distlink-python and distlink-cpp beside one another, as they are in the development workspace.

Provenance and references

This code is a direct Python translation of DISTLINK by Roman V. Baluev and Denis V. Mikryukov. The original project is distributed at SourceForge; the maintained C++20 oracle used for this port is available at troyrock/distlink-cpp.

The underlying algorithms are described in:

• R. V. Baluev and D. V. Mikryukov, “Fast error-controlling MOID computation for confocal elliptic orbits,” Astronomy and Computing 27 (2019), 11–22, doi:10.1016/j.ascom.2019.02.005.
• R. V. Baluev, “Fast error-safe MOID computation involving hyperbolic orbits,” Astronomy and Computing 34 (2021), 100440, doi:10.1016/j.ascom.2020.100440.

License

The original C++ work and this Python translation are distributed under the MIT License. The original authors' copyright and permission notice are preserved in LICENSE and in the translated source.