LunarTrace

Reproducible event-conditioned lunar observation studies.

LunarTrace is research software for constructing, inspecting, and reproducing event-conditioned lunar observation studies. The Python package is the canonical scientific-computation surface; the interactive web Lab provides spatial discovery, source-backed observation inspection, exploratory comparison analysis, and a path back to reproducible Python workflows.

• Research Lab: https://lunartrace-webspine-r1.araveal.workers.dev/
• Scientific manual: https://lunartrace-webspine-r1.araveal.workers.dev/manual/

Install

When the 0.1.0 release is published, install it with:

python -m pip install lunartrace==0.1.0

For source development, use the repository's locked environment:

uv sync --frozen

The Python distribution contains the scientific package and CLI. The React/Cesium web Lab and deployed Cloudflare Worker are separate product surfaces and are not bundled into the wheel.

Python surface

The public package root exposes the scientific entry points used to define and verify studies:

from lunartrace import StudyProtocol

protocol = StudyProtocol()
print(protocol.protocol_id)
print([frontier.frontier_id for frontier in protocol.frontiers])

This prints the protocol identity and its four declared screening frontiers. The package API also exposes the compiler, event and evidence models, verification, and the retained historical benchmark helpers.

Python owns canonical scientific semantics. Browser-side exploration is deliberately provisional and must not silently become an admitted scientific Study.

CLI

lunartrace --help
lunartrace inspect <artifact>
lunartrace verify <study-dir>
lunartrace reproduce <study-dir>
lunartrace benchmark --repository-root <source-repository>

The benchmark command requires the source repository's retained research basis; those research files are not bundled into the wheel. See the scientific manual for exact command semantics, artifacts, and proof boundaries.

Scientific model

LunarTrace treats an event-conditioned study as a traceable sequence:

event / reference
→ bounded source query
→ normalized observations
→ strict PRE / POST partition
→ candidate comparisons
→ explicit multi-objective screening
→ evidence + provenance
→ scientific standing

The package distinguishes source custody, integrity, scientific computation, and scientific standing. In particular:

ContextBasis != StudyBasis
Selected != Included
Exploration != Admission
Integrity != Scientific truth
Archive miss != physical absence

Qualified Chang'e 6 historical exemplar

The retained historical exemplar preserves these aggregate facts:

PRE observations          14
POST observations         39
evaluable temporal pairs 546
V1 / V2 / V3 / V4         7 / 26 / 71 / 102

The historical observation and pair rows are unavailable. Retained browse imagery remains REFERENCE_ONLY and UNALIGNED.

LunarTrace does not claim image registration, photometric comparability, change detection, causal attribution, or physical absence from an archive miss.

Reproducibility

The package supports content-addressed artifacts, source receipts, explicit query closure, verification, replay-oriented workflows, and bounded live Lunar ODE acquisition. The web Lab can export exploratory intent and captured source receipts for offline audit and deliberate continuation in Python without promoting browser exploration to canonical admission.

Status

0.1.0 is the first public Python release candidate. It is alpha research software: interfaces are intentionally conservative, but compatibility is not yet promised across all future minor releases.

Before relying on a result, read the methodology, limitations, evidence-standing, and reproducibility sections of the scientific manual.

Citation

Krit Promsanuwong. LunarTrace 0.1.0. Software release. See CITATION.cff for machine-readable citation metadata.