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.

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.