TIN — Tolerant Interlunar Network

Open-source DTN simulation and analysis engine for lunar and interplanetary relay architectures.

TIN models custody-aware bundle forwarding over sparse relay constellations using a five-state custody FSM, proactive fragment-group aggregation, and reliability-weighted contact graph routing (RW-CGR). The percolation engine (perc_engine) extends this with contact generation, feasibility sweeps, efficiency estimation, susceptibility analysis, and optimal routing across 11 planetary bodies — from Mercury to Titan — plus 4 CRAWDAD real-world traces.

Key result: The three-factor sparse law DR = S_T · exp(E[H]·λ) · Φ decomposes delivery ratio into temporal reachability, chain attenuation, and policy distortion. The classification theorem (γ order parameter) separates temporal contact graphs into trap (γ < 0) and cluster (γ > 0) universality classes with zero overlap. Validated across 154,000+ configurations with factorization error at machine epsilon (1.11×10⁻¹⁶).

Try the Sparse Law Calculator — interactive three-factor DR predictor for 8 solar system targets, runs in your browser.

Status: Research simulation, TRL 2-3. Baseline orbital propagation is 2-body Keplerian with secular J2; multi-fidelity propagators (Brouwer short-period J2, RK4 with SRP and third-body) confirm sparse-law robustness to < 1% across all levels. Coverage and latency figures are unvalidated against independent tools (GMAT, STK, Orekit). See the systems engineering study for the full gap register and resolution status.

Publications

A Classification Theorem for Temporal Contact Graphs: Morphology, Confinement, and the Routing Efficiency Frontier J. Councilman — preprint, submitted to IEEE Transactions on Network Science and Engineering, 2026

• arXiv: (pending endorsement — link will appear here)
• Code: github.com/toxic2040/TIN
• Supporting data: Zenodo 10.5281/zenodo.18765571

@article{councilman2026classification,
  author  = {Councilman, J.},
  title   = {A Classification Theorem for Temporal Contact Graphs:
             Morphology, Confinement, and the Routing Efficiency Frontier},
  journal = {arXiv preprint arXiv:XXXX.XXXXX},
  year    = {2026}
}

Quick Start

git clone https://github.com/toxic2040/TIN.git
cd TIN
pip install -e ".[dev]"
pytest tests/ -x -v

Expected output: 343 tests passed across both packages. The only core dependency is NumPy.

For visualization and SPICE ephemeris support:

pip install -e ".[dev,viz,spice]"

Architecture

TIN is a monorepo with two packages installed via a single editable install:

tin — DTN Simulation Engine

Planet-agnostic bundle forwarding with custody transfer, routing, and fragmentation.

• tin/core/dtn.py — 5-state custody FSM (Holding, Outstanding, Pending, Received, Expired/Lost) with fragment-group aggregation
• tin/core/routing.py — Stochastic RW-CGR: composite utility U = ∏P(p_i) × exp(−λT)
• tin/core/oracle.py — Earliest-arrival Dijkstra oracle with path extraction
• tin/core/base.py — Config dataclasses (body, satellite, halo, constellation)
• tin/core/optimal_router.py — Backward-induction DP on contact DAG (achievability bound)

perc_engine — Percolation Analysis Engine

Sweep infrastructure for sparse-law validation across planetary bodies.

• perc_engine/contact_gen.py — Contact plan generation with DSN link scheduling
• perc_engine/helio_contact_gen.py — Interplanetary (heliocentric) contact generation
• perc_engine/sweep.py — Feasibility sweep (S_T computation)
• perc_engine/efficiency.py — Efficiency estimation (η) with three simulation modes
• perc_engine/analytic_s.py — OPSP predictor + Lyapunov exponent
• perc_engine/bodies.py — 11 body configs (Moon through Titan) + 9 heliocentric configs
• perc_engine/trace_parser.py — CRAWDAD real-trace parser (Haggle, ONE, CSV)
• perc_engine/propagators.py — Multi-fidelity propagators (Kepler, secular J2, Brouwer J2, RK4 perturbed)
• perc_engine/susceptibility.py — Node vulnerability analysis (χ decomposition, hub-fragility, Braess detection)

Planetary Bodies

Body	Type	Orbiters	Notable
Moon	Inner	8 polar + ELFO + EM-L2 halo	Primary baseline
Mars	Inner	6 polar	Second baseline
Mercury	Inner	3 polar	Minimal constellation
Venus	Inner	4 polar	Dense atmosphere
Earth	Inner	—	DSN ground stations
Jupiter	Outer	4 polar	Giant, long OWLT
Europa	Outer	3 polar	Shares Jupiter helio orbit
Saturn	Outer	4 polar	Ring system
Titan	Outer	3 polar	Shares Saturn helio orbit
Ceres	Outer	3 polar	Dwarf planet

Project Structure

TIN/
├── tin/                    # DTN simulator
│   ├── core/               #   dtn, routing, oracle, base
│   ├── config/             #   lunar_default + body configs
│   └── scenarios/          #   scenario runners
├── perc_engine/            # Percolation engine (12 modules)
├── runs/                   # 112 experiment scripts
├── tests/                  # 343 tests (pytest)
├── theory/                 # Theory notes and derivations
├── data/kernels/           # SPICE kernels (.bsp from NAIF)
├── docs/                   # Study documents
├── figures/                # Generated figures (gitignored)
├── .github/workflows/      # CI: lint → test → build
├── pyproject.toml          # v0.9.2a, both packages
└── LICENSE                 # MIT

The Science

The three-factor sparse law provides an exact decomposition of delivery ratio:

DR = S_T · exp(E[H]·λ) · Φ

Factor	Meaning	Method
S_T	Temporal reachability (feasible fraction)	Oracle sweep (Dijkstra on contact DAG)
exp(E[H]·λ)	Chain attenuation (single-chain reference)	Lyapunov exponent from hop statistics
Φ	Policy distortion	Simulation or closed-form estimate

The classification theorem uses the order parameter γ = ∂ln(Φ)/∂E[H] / (−λ) to separate temporal contact graphs into two universality classes:

Class	γ	Φ	Behavior
Trap	< 0	≲ 1	Wrong turns lock in; each hop degrades retry budget
Cluster	> 0	≫ 1	Path multiplicity amplifies; each hop improves retry budget

Four independent confirmations: sign of γ, χ vulnerability distribution, achievability gap (φ_ratio), and forwarding ratio (fwd_ratio ≶ 1).

Closed-form delivery ratio (no simulation beyond oracle sweep):

DR = S_T · exp[ E[H] · λ · (1 − γ/(1 + α·p_eff)) ]

Five measurable quantities. R² = 0.935 (Lorentzian), 0.959 (shape-corrected).

Key numbers:

• Factorization exact to 1.11×10⁻¹⁶ across 154,000+ configurations (8 orbital + 4 CRAWDAD)
• Self-averaging: η_OPSP matches Monte Carlo to < 0.4%
• Classification gap: +0.75 in γ, zero overlap
• Forwarding ratio boundary: fwd_ratio = 1.0 (exact separation, 5 configs)
• Hub-fragility: H = 2.70 (Moon), Braess nodes emerge at p_eff ≥ 0.1
• Achievability gap: 22.6× (Moon trap) vs 1.7–2.6× (CRAWDAD cluster)

See the companion papers on Zenodo for full derivations.

Scope Boundaries

The simulator makes deliberate modeling choices to keep the sparse-law analysis tractable:

• Orbital propagation: Baseline is Keplerian with secular J2 drift (RAAN + AOP precession). Higher-fidelity propagators (Brouwer short-period J2, RK4 with SRP and third-body) are available in perc_engine/propagators.py; a sensitivity study confirms DR varies < 1% across all four fidelity levels.
• Surface occlusion: Hard-sphere geometric LOS. No terrain, mascon, or atmospheric scintillation models.
• Protocol fidelity: 5-state custody FSM with fragment groups (BPv7-inspired semantics). Does not implement BPSec, LTP, or wire-level encoding.
• Contact plans: Static snapshot topology per simulation window. The sweep framework compensates by sampling across many epochs and configurations.

Validation

• Keplerian propagator validated against JPL DE440s via SPICE (~0.3% position error over full synodic cycle)
• Sparse law confirmed on 4 CRAWDAD real-world contact traces (n = 9 to n = 98 nodes)
• Factorization exact to machine epsilon (1.11×10⁻¹⁶) across 154,000+ configurations (8 orbital + 4 CRAWDAD)
• Classification theorem separates trap-class and cluster-class temporal graphs with zero overlap across all tested domains
• Propagation fidelity sensitivity: DR robust to < 1% across four levels (Kepler → RK4 with J2 + SRP + third-body) on Moon and Mars
• Susceptibility analysis: hub-fragility index, χ decomposition, and Braess paradox detection validated on Moon and Mars
• Achievability: backward-induction DP confirms chain law as capacity bound for trap class (22.6× gap) and lower bound for cluster class

Citation

@software{councilman2026tin,
  author    = {Councilman, J.},
  title     = {{TIN}: Tolerant Interlunar Network},
  year      = {2026},
  doi       = {10.5281/zenodo.18765571},
  url       = {https://github.com/toxic2040/TIN}
}

Contributing

Contributions, reproductions, and independent validations are welcome. Run pytest tests/ -x -v and open an issue if results differ.

Areas where external input would be most valuable:

• Independent coverage analysis using Orekit, GMAT, or STK
• BPv7/ION/HDTN interoperability review of the custody model
• Link budget validation for the EM-L2 halo relay path
• Higher-fidelity propagation comparison — completed: runs/run_propagation_sensitivity.py (max |ΔDR| < 1% across four fidelity levels)

References

• RFC 9171 — Bundle Protocol Version 7 (BPv7)
• RFC 9172 — Bundle Protocol Security (BPSec)
• RFC 5326 — Licklider Transmission Protocol (LTP)
• Queqiao-1/2 — CNSA EM-L2 halo relay missions (2018+)
• HDTN — NASA Glenn High-rate Delay Tolerant Networking
• ION — JPL Interplanetary Overlay Network

License

MIT — see LICENSE.