PyCG-DTN

Build DTN contact graphs for deep-space networks from real ephemerides.

Give it a set of bodies and a number of days. It works out which SPICE kernels it needs, downloads them from NASA/NAIF, computes when every pair of nodes can actually see each other, and writes a contact plan.

from pycg_dtn import ContactGraph

cg = ContactGraph()
cg.AddCelestial("Earth")
cg.AddCelestial("Mars")
cg.AddCelestial("Phobos")

plan = cg.GenerateContactGraph(days=780)
plan.Write("out/")

out/contactGraph.csv     ION contact plan
out/contactGraph.json    full plan with metadata
out/summary.json         per-link statistics

Install

pip install pycg-dtn

Requires Python 3.10+.

What it computes

A contact is an interval during which two nodes can exchange data. Two things take a deep-space link away even when both endpoints are nominally in view:

Occultation — a third body sits in the line of sight. Mars hides Phobos; Jupiter hides Io.

Solar conjunction — the signal path passes close to the Sun, whose corona scatters and delays the signal badly enough that operators stand the link down. The threshold is the Sun–Earth–probe angle; below about 3° the link is treated as unusable, following DSN practice (DSN handbook 810-005).

Contact time is the analysed span minus the union of everything that blocks it. Each surviving interval is then cut into sub-contacts wherever the achievable data rate has drifted more than 10%, so no single contact misrepresents how much data fits through it.

Rates come from a Friis free-space path loss → SNR → Shannon capacity chain, with defaults modelling an X-band spacecraft high-gain dish talking to a DSN 70 m antenna (74.18 dBi, Rodemich 1989).

Bodies

AddCelestial accepts anything NAIF names, case-insensitively — or a NAIF integer ID code.

cg.AddCelestial("Titan")
cg.AddCelestial("Europa", eid="ipn:5.2")   # custom ION endpoint identifier
cg.AddCelestial("401")                      # Phobos, by ID

An unrecognised name raises UnknownCelestialBodyError.

Kernels

A kernel is NAIF's term for a SPICE data file. Only the ones your bodies need are downloaded, which matters — the Jovian satellite ephemeris alone is over a gigabyte, and an Earth–Mars scenario should never pay for it.

Check the cost before committing:

pycg kernels --bodies Earth Mars Phobos

kernel directory: /home/you/kernels
4 kernels, about 96 MB total

  [need] naif0012.tls          0.0 MB   leap seconds, for UTC <-> ET conversion
  [need] pck00011.tpc          0.1 MB   body radii and IAU body-fixed orientation
  [need] de440s.bsp           31.2 MB   planetary ephemeris DE440 (short), 1849-2150
  [need] mar099s.bsp          64.5 MB   Phobos and Deimos

All files come from NAIF's public generic-kernel archive.

Configuring the link budget

Every radio parameter has a getter and a setter. Setters chain and validate.

lb = cg.GetLinkBudget()
lb.SetFrequency(32.0e9)     # Ka-band instead of X-band
lb.SetRxGain(79.0)          # a larger ground antenna
lb.SetBandwidth(5.0e6)
lb.SetMinRate(1000.0)       # drop contacts below 1 kbps

print(lb.GetWavelength(), lb.GetNoisePower())

Configuring the geometry search

Same pattern on cg.GetGeometry():

geo = cg.GetGeometry()
geo.SetSepExclusion(2.0)     # tighter solar exclusion, degrees
geo.SetOccultStep(300.0)     # finer occultation search, seconds
geo.SetRateTolerance(0.05)   # split contacts on 5% rate drift

Choosing a span

Contact plans repeat on the synodic period — the time for two bodies to return to the same relative arrangement, which for planets with orbital periods Pa and Pb is 1 / |1/Pa − 1/Pb|.

Reading the results

plan = cg.GenerateContactGraph(days=780)

len(plan)                          # number of contacts
plan.ForLink("EARTH", "MARS")      # contacts on one link, time-ordered

for s in plan.LongestOutages(5):
    print(s.a, s.b, s.t_maxgap_days)

The CSV is the contact plan format ingested by ION, NASA JPL's reference DTN implementation. Each contact becomes four rows — a contact and a range line in each direction.

Command line

pycg kernels --bodies Earth Mars Phobos
pycg fetch   --bodies Earth Mars Phobos
pycg build   --bodies Earth Mars --days 780 --out out/
pycg build   --bodies Earth Mars --days 780 --frequency 32e9 --rx-gain 79

Roadmap

AddSatellite, for artificial spacecraft supplied as Keplerian orbital elements and propagated into the same geometry pipeline, is not implemented yet. It currently raises NotImplementedError.

License

GNU General Public License v3.0 or later. See LICENSE.