Metadata-Version: 2.4
Name: distlink-python
Version: 0.2.0
Summary: Pure-Python port of the distlink MOID and linking-coefficient library
Author: Roman V. Baluev, Denis V. Mikryukov
Maintainer: Troy D. Rockwood
License-Expression: MIT
Project-URL: Repository, https://github.com/troyrock/distlink-python
Project-URL: Issues, https://github.com/troyrock/distlink-python/issues
Project-URL: Original C++ project, https://sourceforge.net/projects/distlink/
Project-URL: C++ parity oracle, https://github.com/troyrock/distlink-cpp
Keywords: astronomy,astrodynamics,MOID,orbital mechanics
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Science/Research
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3 :: Only
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Programming Language :: Python :: 3.14
Classifier: Topic :: Scientific/Engineering :: Astronomy
Requires-Python: >=3.10
Description-Content-Type: text/markdown
License-File: LICENSE
Dynamic: license-file

# 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:

```text
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:

```text
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

```python
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:

```text
python -m unittest discover -s tests -v
```

The release CI pins the oracle to
[`troyrock/distlink-cpp@58c1c29`](https://github.com/troyrock/distlink-cpp/commit/58c1c29ad1555920e004ff6fc8b932e954751147).
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](https://sourceforge.net/projects/distlink/); the maintained
C++20 oracle used for this port is available at
[`troyrock/distlink-cpp`](https://github.com/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](https://doi.org/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](https://doi.org/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`](LICENSE) and in the translated source.
