chandrapin 1.0.0

Modular ChandraPIN spatial addressing & pathfinding framework for lunar operations

ChandraPIN: Geodesic Hierarchical Hexagonal Geocoding & Telemetry Serialization

ChandraPIN is a scientific-grade geocoding and delay-tolerant networking (DTN) serialization library designed for lunar surface exploration, extravehicular activities (EVAs), and autonomous rover pathfinding.

The engine implements a 2D Polar Stereographic Hierarchical Hexagonal Geocoding schema centered at the Moon's South Pole, dividing coordinates into pointy-topped hexagonal tiles down to sub-meter tactical precision. It integrates spatial indexing with heading-dependent kinematic difficulty weights and high-reliability, space-grade CBOR binary packaging.

---

1. Architectural Overview

ChandraPIN/
├── pyproject.toml             # PEP 517 build configuration & metadata
├── LICENSE                    # MIT license
├── README.md                  # Comprehensive technical specification
├── chandrapin/                # Production Library
│   ├── __init__.py            # Explicit API exposition & versioning
│   ├── datums.py              # Geodetic datums (IAU Moon-2000) & constraints
│   ├── core_hex.py            # Level-12 recursive bisection tiling engine
│   ├── weights.py             # Directional traversability cost models
│   ├── dtn.py                 # Space-grade CBOR serialization & CRC-8 engine
│   ├── central.py             # Prefix-indexed central registry & state sync
│   └── interfaces.py          # Astronaut HUD presentation pipelines
└── tests/
    ├── __init__.py            # Test package marker
    └── test_flight_bounds.py  # 28-test automated assertions suite

---

2. Technical & Mathematical Specifications

2.1 Geodetic Datum & South Polar Projection

• Coordinate Reference System (CRS): IAU/IAG Moon-2000 ellipsoid model ($R_{eq} = 1,737,400\text{ m}$, flattening $f = 0.0$).
• Latitude Constraints: Strictly bounded to the Southern Hemisphere ($\phi \in [-90.0, 0.0]$) to eliminate hemisphere-fold collision vulnerabilities.
• Projection Plane: South Polar Stereographic projection maps geodetic coordinates to 2D Cartesian coordinates $(x_p, y_p)$ via: $$R_p = 2 R_{eq} \tan\left(\frac{\pi}{4} + \frac{\phi_{\text{rad}}}{2}\right)$$ $$x_p = R_p \sin(\lambda_{\text{rad}}), \quad y_p = -R_p \cos(\lambda_{\text{rad}})$$

2.2 Pointy-Topped Hex Axial Tiling

• Orientation: Pointy-topped hexagons mapped via axial coordinates $(q, r)$.
• Decomposition Resolution: 12 levels of recursive bisection.
• Tactical Precision: Flat-to-flat width at Level 12 is fixed at $0.92\text{ meters}$, yielding sub-meter accuracy.
• Hierarchical Formatting: Geocodes format to a 12-character token split into four 3-character chunks: XXX-XXX-XXX-XXX.
• Phonetic Alphabet: Built using 16 acoustically distinct characters (2C3J4K5L6M7P8F9T) to prevent vocal confusion over noisy VHF radio links.
• State Mapping: At each bisection level, the 9 possible child-offset configurations $(dq, dr) \in {-1, 0, 1}^2$ map strictly to the first 9 alphabet characters (2C3J4K5L6), leaving the remaining 7 characters reserved for future telemetry flags.

2.3 Asymmetric Kinematic Weights

ChandraPIN cells are not static coordinates; they act as nodes in a dynamic traversability graph:

• Permanent Solar Constancy: Probability score $[0.0, 1.0]$ representing solar illumination (energy harvesting potential).
• Dynamic Traversability: 6 heading-dependent path cost multipliers $[0.0, 15.0]$ representing terrain slopes, crater hazards, or slip risks.
• 8-bit Compression: Compresses weights into a single telemetry byte:
  • Bits [7:4]: Variable Traversability Cost (0–15 scale)
  • Bits [3:0]: Permanent Solar Reach Score (0–15 scale)

2.4 Delay-Tolerant Serialization (DTN)

For transmission over satellite-relay links, data is serialized into a highly optimized 19-byte packet:

• 6-byte binary payload: The 12-char geocode compressed using 4 bits per character.
• 1-byte telemetry bitmask: Compressed solar reach and heading friction nibbles.
• 11-byte state string: Relative tracking anchor ID (alphanumeric, max 16 characters) or lost-tracking state.
• 1-byte CRC-8 Checksum: Polynomial $x^8 + x^5 + x^4 + 1$ (CRC-8-ATM, 0x07) protecting the payload against cosmic-ray bit-flips.

---

3. Installation

Install the library locally in editable mode:

pip install -e .

---

4. Usage Reference

4.1 Geocoding & Decoding

from chandrapin.core_hex import GeodesicHexEngine

# 1. Forward Geocoding: Coordinate -> Geocode
geocode = GeodesicHexEngine.ForwardProjection(latitude=-86.9, longitude=70.0)
print(geocode)  # "4CJ-4KL-4K4-C46"

# 2. Reverse Geocoding: Geocode -> Central Coordinates
lat, lon = GeodesicHexEngine.ReverseProjection(geocode, lat_ref=-86.9, lon_ref=70.0)
print(f"Decoded: {lat:.6f}, {lon:.6f}")

4.2 Spatial Pathfinding Utilities

# 1. Resolve adjacent neighbor cells (Returns geocodes of the 6 surrounding tiles)
neighbors = GeodesicHexEngine.GetNeighbors(geocode)
for n in neighbors:
    print(n)

# 2. Calculate great-circle distance between two cells in meters
distance_m = GeodesicHexEngine.GetDistance("4CJ-4KL-4K4-C46", "4CJ-4KL-4K4-C4C")
print(f"Distance: {distance_m:.2f} meters")

4.3 Telemetry Weight Compilation

from chandrapin.weights import AsymmetricTelemetryFrame

# Initialize a weight frame with 80% permanent solar reach
frame = AsymmetricTelemetryFrame(geocode, permanent_solar_score=0.8)

# Update traversability costs for heading directions (0 to 5)
frame.update_heading_cost(ingress_direction=0, friction_multiplier=4.2)
frame.update_heading_cost(ingress_direction=3, friction_multiplier=12.0)

# Compile telemetry byte for active heading direction 0
telemetry_byte = frame.compile_telemetry_byte(current_heading=0)
print(f"Telemetry Byte: {bin(telemetry_byte)}")

4.4 Space-Grade Serialization

from chandrapin.dtn import DtnSerializer

# Serialize frame states into a robust 19-byte packet
packet = DtnSerializer.SerializeFrame(
    geocode, frame, current_heading=0, tracking_mode="RELATIVE", anchor_id="LANDER1"
)
print(f"Packet size: {len(packet)} bytes (Hex: {packet.hex()})")

# Verify and deserialize incoming packet
payload, is_valid = DtnSerializer.VerifyAndDeserializeFrame(packet)
if is_valid:
    coord_bytes, telemetry_bytes, tracking_mode = payload
    print("Verification Successful!")

4.5 Central Control Sync Broadcasts

from chandrapin.central import ChandraCentralRegistry

registry = ChandraCentralRegistry()
registry.seed_permanent_solar_reach("4CJ-4KL-4K4-C46", 0.95)

# O(log n) Prefix-based broadcast compilation
sync_broadcast = registry.generate_regional_broadcast("4CJ-4KL")
print(sync_broadcast)

---

5. Testing & Verification

Run the comprehensive 28-assertion automated test suite:

python -m unittest tests/test_flight_bounds.py -v

All assertions verify boundary bounds validation, deserialization type schema checking, arithmetic precision, and geodetic coordinate transformations.