Skip to content

Getting Started

This guide walks through installing ACONS, running the bundled lunar scenario, and adapting the configuration to other celestial bodies.

Prerequisites

  • Python 3.11 (matching the pyproject.toml requirement)
  • Poetry for dependency management

Install Poetry via pipx (recommended):

pip install --user pipx
pipx ensurepath
pipx install poetry

or through the official installer:

curl -sSL https://install.python-poetry.org | python3 -

Verify the installation:

poetry --version

Installation

git clone https://github.com/<your-org>/acons.git
cd acons
poetry install          # create the virtual environment and install dependencies

(Optional) spawn a Poetry-managed shell:

poetry shell

Running the lunar example

The repository ships with a fully configured lunar navigation scenario. Execute the full pipeline from ingest to estimation with:

poetry run acons all --config configs/scenarios/lunar_static_rover.yaml --run-dir outputs/lunar_static

This performs the three stages sequentially:

  1. Ingest – resample the satellite ephemerides onto the scenario grid and render quick-look plots.
  2. Simulate – synthesise one-way range and Doppler measurements, including Friis-based C/N₀, and write the complete measurement catalogue to measurements.json.
  3. Estimate – run the eight-state EKF (position, velocity, clock bias/drift), produce state and covariance histories, and generate residual/error plots. Reporting automatically drops robust outliers before computing statistics.

You can drive individual stages if you only need a subset:

poetry run acons ingest  --config configs/scenarios/lunar_static_rover.yaml --run-dir outputs/lunar_static
poetry run acons simulate --config configs/scenarios/lunar_static_rover.yaml --run-dir outputs/lunar_static
poetry run acons estimate --config configs/scenarios/lunar_static_rover.yaml --run-dir outputs/lunar_static

Re-running a stage overwrites only that stage’s outputs, letting you quickly iterate on scenarios.

Running the Mars example

configs/scenarios/mars_static_rover.yaml reproduces a surface receiver that ingests the MARCONI constellation ephemerides from ephemeris/MARS/. These tracks are provided in the JCRF inertial frame and the scenario’s frames block requests a JCRF → MARS-IAU conversion, so make sure the referenced SPICE kernels include the NAIF leapseconds file plus Mars frame/orientation kernels (e.g., data/SPICE/mars_iau2000.tf and data/SPICE/mars_pa_de440_2000-2050.bpc).

Run the full pipeline with:

poetry run acons all --config configs/scenarios/mars_static_rover.yaml --run-dir outputs/mars_static

Swap in ingest, simulate, or estimate if you only need a subset of the flow just like the lunar example.

Adapting to another body

Scenario configuration is consolidated into a single YAML/JSON file. The key sections are:

  1. time – start/end timestamps and sampling cadence.
  2. frames – source and body-fixed frames (e.g., J2000 → MOON_PA).
  3. spice.kernels – list of SPICE kernels furnished before ingest.
  4. receiver – geodetic location, elevation mask, and user type (surface, orbiter, or edl).
  5. measurement – carrier frequency, DLL/FLL parameters, transmitter/receiver gain patterns, RNG seed, observable list (currently range and range_rate), an oscillator entry with at least two Allan deviation samples (any averaging times are accepted), and a sise block describing ODTS one-sigma errors for satellite position, velocity, clock bias, and clock drift.
  6. orbits – satellite identifiers with ephemeris file paths (CSV/SP3/OEM).
  7. estimation – initial position/velocity/clock bias/drift, process-noise settings (process_noise for orbiters/EDL, process_noise_diag for surface users), and 1‑σ initial covariance.

Bundled scenario YAMLs now include short comment banners ahead of each section so you can glance at configs/scenarios/*.yaml to understand what knobs a block controls before editing it.

When initial_state.use_receiver_as_truth is true you can specify random_position_error_m (e.g., 1000 m) to inject a random offset with that magnitude, optionally fixing the direction via position_error_seed for reproducibility.

Update those sections to reflect the new body or constellation, then rerun the same acons commands. No code changes are required as long as ephemerides and SPICE kernels are supplied.

Project layout

acon/
├── configs/
│   └── scenarios/               # Ready-to-run scenario files
├── data/SPICE/                  # Furnished kernels (LSK, frame, SPK…)
├── docs/                        # MkDocs documentation set
├── ephemeris/                   # Tabulated orbit samples (CSV)
├── outputs/                     # Generated artefacts (gitignored)
├── src/
│   ├── constants.py             # Shared physical/logging constants
│   ├── cli.py                   # CLI entry point (`poetry run acons …`)
│   ├── measurement_simulator.py # Measurement synthesis & JSON exporter
│   ├── filtering.py             # Eight-state EKF
│   └── reporting.py             # Plots and CSV summaries with outlier removal
└── README.md

Refer to the Outputs & Reporting page for a breakdown of stage artefacts.