Python API reference#
The package root exposes the current public scientific entry points. Lower-level modules remain available for research workflows; the experimental Lab bridge is labelled separately below.
Compiler#
Compiler is the canonical scientific computation boundary. It consumes explicit event, protocol, source snapshot, and normalized observation inputs. It does not perform network access or manage a browser.
.. py:class:: Compiler(screener=None, pair_builder=None) :module: lunartrace :canonical: lunartrace.compiler.Compiler
Compile a captured snapshot, preserving its source scope and proof ceiling.
Execution is deterministic for identical inputs and software identity. Wall-clock execution receipts belong outside the semantic artifact, so replay is byte-stable. A custom screener must identify itself in the supplied protocol.
A compiled result is a candidate with explicit evidence and limitations. It is not automatic scientific admission. For a complete workflow, read From exploration to reproducible computation.
Protocol and screening#
.. py:class:: StudyProtocol(*, protocol_id=’lunartrace-point-pareto’, version=’1’, archive=’NASA_LUNAR_ODE’, mission=’LRO’, instrument=’LROC’, product_type=’CDRNAC4’, epsilon_degrees=1e-06, location_mode=’i’, partition_rule=’STRICT_OUTSIDE_EVENT_UNCERTAINTY’, temporal_metric=’SECONDS_FROM_NOMINAL_EVENT’, missing_metadata=’EXCLUDE_PAIR’, screener_id=’pareto-v1’, frontiers=(FrontierDefinition(frontier_id=’V1_ANGLES’, name=’Angles’, objectives=(<Objective.DELTA_INCIDENCE: ‘DELTA_INCIDENCE’>, <Objective.DELTA_EMISSION: ‘DELTA_EMISSION’>, <Objective.DELTA_PHASE: ‘DELTA_PHASE’>), direction=’MINIMIZE’), FrontierDefinition(frontier_id=’V2_ANGLES_RESOLUTION’, name=’Angles + resolution’, objectives=(<Objective.DELTA_INCIDENCE: ‘DELTA_INCIDENCE’>, <Objective.DELTA_EMISSION: ‘DELTA_EMISSION’>, <Objective.DELTA_PHASE: ‘DELTA_PHASE’>, <Objective.WORST_RESOLUTION: ‘WORST_RESOLUTION’>), direction=’MINIMIZE’), FrontierDefinition(frontier_id=’V3_ANGLES_TIME’, name=’Angles + time’, objectives=(<Objective.DELTA_INCIDENCE: ‘DELTA_INCIDENCE’>, <Objective.DELTA_EMISSION: ‘DELTA_EMISSION’>, <Objective.DELTA_PHASE: ‘DELTA_PHASE’>, <Objective.PRE_TEMPORAL_DISTANCE: ‘PRE_TEMPORAL_DISTANCE’>, <Objective.POST_TEMPORAL_DISTANCE: ‘POST_TEMPORAL_DISTANCE’>), direction=’MINIMIZE’), FrontierDefinition(frontier_id=’V4_FULL_AVAILABLE’, name=’Full available’, objectives=(<Objective.DELTA_INCIDENCE: ‘DELTA_INCIDENCE’>, <Objective.DELTA_EMISSION: ‘DELTA_EMISSION’>, <Objective.DELTA_PHASE: ‘DELTA_PHASE’>, <Objective.WORST_RESOLUTION: ‘WORST_RESOLUTION’>, <Objective.PRE_TEMPORAL_DISTANCE: ‘PRE_TEMPORAL_DISTANCE’>, <Objective.POST_TEMPORAL_DISTANCE: ‘POST_TEMPORAL_DISTANCE’>), direction=’MINIMIZE’)), window_start=None, window_end=None, max_pairs=100000) :module: lunartrace :canonical: lunartrace.protocols.StudyProtocol
.. py:class:: FrontierDefinition(*, frontier_id, name, objectives, direction=’MINIMIZE’) :module: lunartrace :canonical: lunartrace.protocols.FrontierDefinition
.. py:class:: ParetoScreener(max_comparisons: int = 10000000) :module: lunartrace :canonical: lunartrace.screening.ParetoScreener
The protocol declares objective sets and scientific rules. The current FRONTIERS constant contains the four retained angle/resolution/time definitions. See Event-conditioned comparison methodology for units, missing-metadata behavior, and the exact dominance relation.
Event and archive models#
.. py:class:: LunarEvent(*, event_id, name, event_class, geometry, occurred_at, temporal_uncertainty=
.. py:class:: ArchiveSnapshot(*, snapshot_id, archive=’NASA_LUNAR_ODE’, product_type=’CDRNAC4’, capture, query_description, query_scope=None, request_identity=None, queried_at=None, indexed_through=None, raw_response_hashes=(), normalized_data_hash=None, expected_count=None, retrieved_count=None, closure=’UNKNOWN’, limitations=()) :module: lunartrace :canonical: lunartrace.archive.ArchiveSnapshot
.. py:class:: ArchiveCurrentness(*, state, indexed_through, observed_at, event_latest, source_mode, query_closure, absence_claim_permitted=False, explanation) :module: lunartrace :canonical: lunartrace.archive.ArchiveCurrentness
Coordinate conventions are explicit in lunartrace.events. Longitude normalization does not transform latitude convention or invent a reference frame. Captured snapshot validation binds query scope, response identities, normalized rows, counts, and closure.
Scientific result and evidence models#
.. py:class:: HistoricalStudyRecord(*, kind=’HISTORICAL_AGGREGATE’, study_id, historical_basis_id, software, event, protocol, archive_snapshot, currentness, source_mode=’SNAPSHOT’, observation_rows=’UNAVAILABLE’, pair_rows=’UNAVAILABLE’, aggregate, reference_products, evidence) :module: lunartrace :canonical: lunartrace.studies.HistoricalStudyRecord
.. py:class:: CompiledStudy(*, kind=’COMPILED’, study_id, software, event, protocol, archive_snapshot, currentness, source_mode, data_standing, observations, pre_keys, post_keys, excluded_observations, pairs, screenings, evidence) :module: lunartrace :canonical: lunartrace.studies.CompiledStudy
.. py:class:: EvidenceManifest(*, manifest_version=’1’, serialization=’lunartrace-json-v1’, software, study_id, study_kind, event, protocol, archive_snapshot, currentness, available_observation_keys, observation_rows, study_artifact, artifacts, evidence) :module: lunartrace :canonical: lunartrace.studies.EvidenceManifest
.. py:class:: EvidenceCompilation(*, study, manifest, manifest_hash) :module: lunartrace :canonical: lunartrace.studies.EvidenceCompilation
Historical and compiled Study kinds have different row/replay capabilities. Do not treat one as a presentation alias for the other.
Verification and historical entry points#
.. py:function:: verify_study(directory, *, replay=True) :module: lunartrace
.. py:class:: VerificationReport(*, kind=’VERIFICATION_REPORT’, ok, manifest_hash=None, study_kind=None, checked_artifacts=0, contract_validation, artifact_integrity, manifest_consistency, compiler_replay, errors=(), proof_ceiling=’Verification establishes byte identity and internal consistency, not source authenticity, image alignment, or scientific discovery.’) :module: lunartrace :canonical: lunartrace.verification.VerificationReport
.. py:function:: historical_change6(repository_root, *, software=None) :module: lunartrace
.. py:function:: historical_benchmark(study) :module: lunartrace
historical_change6 returns the Study and its dependency payloads. verify_study returns structured evidence about verification rather than silently weakening a failing contract.
Acquisition and bundle composition#
These lower-level interfaces are useful when assembling a complete workflow:
.. py:class:: ODEClient(*, limits=None, normalization=None, transport=None, sleep=
Single-acquisition client; injected HTTP transports support deterministic tests.
The endpoint, body, mission, instrument and product type are not caller-provided proxy parameters. Response URLs are recorded, never followed for image downloads. No credentials, implicit environment proxy, or redirects are accepted.
.. py:class:: ODEAcquisition(capture: lunartrace.sources.capture.CapturedArchive, raw_responses: dict[str, bytes]) :module: lunartrace.sources.capture
.. py:function:: load_capture(directory) :module: lunartrace.sources.capture
.. py:function:: export_study(study, directory, dependencies=(), *, replace=False) :module: lunartrace.bundles
Export without inventing unavailable dependencies; no network access.
Immutable objects are written first. The manifest hash pointer is written last. An interrupted multi-file export fails verification rather than claiming settlement.
The ODE client is a bounded external acquisition surface. Bundle export is a local artifact operation. Neither should be confused with scholarly publication.
Experimental Lab exchange#
These R2 module-level helpers are not added to the stable package-root API:
.. py:function:: load_lab_export(path) :module: lunartrace.lab_exchange
Bounded, offline audit of raw metadata-response byte identities.
This verifies self-consistency of supplied bytes, not the archive’s authenticity, completeness, normalized rows, imagery, or scientific truth.
.. py:function:: point_definition(export) :module: lunartrace.lab_exchange
Translate user intent into a NEW point query; never reinterpret box capture.
They audit an exploratory transport envelope and translate user-defined point intent into a new Python query definition. They do not deserialize browser results as canonical scientific truth.