Basilisk and Docker for Reproducible GN&C Simulation: A Workflow Reference

Source: arXiv:2605.12443 · Published 2026-05-12 · By Anubhav Gupta

TL;DR

This paper is not proposing a new GN&C algorithm; it is a workflow reference for making Basilisk simulations reproducible and portable across machines. The core problem it addresses is that Basilisk’s build and runtime environment can be fragile in practice: Python/package versions, compiler/toolchain dependencies, OS-specific quirks, visualization dependencies, and external data files can all make two developers’ “same” simulation behave differently or fail to build. The author’s answer is to freeze the environment in Docker, pin the Basilisk commit, and show a concrete project layout that keeps simulation scripts on the host while the Basilisk build and runtime live inside a container.

The paper then walks through progressively richer example simulations to show how the containerized environment is actually used: a minimal standalone spacecraft script, an Earth-orbit case with optional J2 perturbations, a Sun-Earth case using SPICE kernels, and then a BSKSim-based attitude-control workflow with Monte Carlo capability. The result is a practical implementation guide rather than a benchmark paper: the main claim is reproducibility and portability, supported by detailed code snippets, directory structure, message-passing architecture, task priorities, and visualization setup. It explicitly positions itself as an expanded reference built on a prior workshop presentation, not a novel simulation method.

Key findings

• The workflow pins Basilisk to commit 87cb4116e09694ddf6587f61a7f4196d2e720c43 and builds inside Ubuntu 22.04 with Python 3.10, making the environment insensitive to later upstream changes in the Basilisk develop branch.
• The Docker image installs Basilisk and its Python stack from source using pinned version ranges such as conan>=2.0.5,<=2.15.1, cmake>=3.26,<4.0, numpy>=1.24.4,<2.4.0, and scipy>=1.10.1,<2.0, which is intended to reduce build drift.
• The container runtime uses a bind mount from the host project directory to /app/workspace, so scenario scripts edited on the host are immediately visible inside the container without copying files.
• A minimal standalone Basilisk script can run successfully only if the spacecraft object is added to the task with AddModelToTask(); the paper notes that omitting this call does not raise an error but silently yields no dynamics propagation.
• For Earth-orbit simulation, the paper uses a 7000 km semi-major axis, e=0.0001, i=33.3 deg, RAAN=48.2 deg, argument of periapsis=347.8 deg, and true anomaly=85.3 deg, and notes that about 3 orbital periods (~18,000 s) are recommended to observe J2-driven nodal precession.
• The Sun-Earth scenario uses SPICE kernels de430.bsp, naif0012.tls, de-403-masses.tpc, and pck00010.tpc, with Earth as the zeroBase reference frame for Earth-centered state vectors.
• The BSKSim example separates dynamics and flight software into reusable model classes and uses module priorities (e.g., spacecraft 201, SPICE 200, ephemeris converter 199, force/torque effector 300) to enforce execution order within a task.

Threat model

The relevant failure mode is environmental non-determinism rather than a malicious attacker: developers may have different OS versions, compilers, Python stacks, package versions, or missing support files, leading to build failures or divergent simulation behavior. The workflow assumes a benign user with Docker access and access to Basilisk source/support data; it does not address adversarial tampering, sandbox escape, or malicious container images.

Methodology — deep read

Threat model and assumptions: the paper’s implicit “adversary” is not a malicious attacker but environment drift and configuration inconsistency across developer machines. The assumption is that users want the same Basilisk scenario to build and run identically on heterogeneous hosts (Windows/Linux/macOS-style workflows are discussed broadly, though the concrete setup shown is Ubuntu-based Docker). The paper assumes the user can run Docker and has access to the Basilisk source repository plus the external support data and SPICE kernels needed by the chosen scenario. It does not model hostile tampering, sandbox escapes, or supply-chain attacks; the focus is deterministic local execution and reproducibility.

Data and inputs: there is no labeled dataset in the ML sense. The “data” are simulation inputs and supporting files: the Basilisk repository at commit 87cb4116e09694ddf6587f61a7f4196d2e720c43; Basilisk support data pulled via git-lfs; the GGM03S J2-only gravity file for the Earth-orbit perturbation case; and SPICE kernels de430.bsp, naif0012.tls, de-403-masses.tpc, and pck00010.tpc for the Sun-Earth scenario. For the standalone and Earth-orbit examples, the paper specifies orbital initial conditions via classical elements (a, e, i, Ω, ω, f) and converts them to inertial state vectors with elem2rv(). For logging, recorder sampling is set using unitTestSupport.samplingTime(simulation_time, simulation_time_step, num_data_points), with a minimum 1 ns sampling period enforced by Basilisk. No train/validation/test split exists because this is a simulation workflow paper, not a predictive modeling paper.

Architecture and algorithm: the main technical artifact is the containerized Basilisk environment. The Dockerfile starts from ubuntu:22.04, sets DEBIAN_FRONTEND=noninteractive and TZ=America/Los_Angeles, installs build prerequisites (git, git-lfs, build-essential, Python dev/tooling, swig, GTK, ZeroMQ), clones Basilisk from GitHub, checks out the pinned commit, runs git lfs pull, installs a pinned Python dependency stack, and then invokes Basilisk’s conanfile.py with --buildProject False and --vizInterface True before compiling dist3 with make -j$(nproc). The docker-compose.yml then defines a single basilisk service, names the container basilisk_gnc, mounts the host workspace into /app/workspace, opens a TTY, and injects environment variables from .env so the Python path resolves compiled Basilisk modules. The paper’s concrete simulation architecture explanation is important: Basilisk is organized as simulation container -> process -> task -> module, and modules communicate only through typed messages. Modules have a lifecycle with SelfInit(), Reset(), and Update()/UpdateState(), and modules can be connected via subscribeTo() on output/input messages. Recorders are attached to messages to capture either every update or sampled updates. The BSKSim architecture adds an object-oriented layer on top: BSKSim owns process/model registration, while BSKScenario defines scenario-specific initialization, logging, and output handling. Dynamics and flight software are split into reusable class definitions (BSKDynamicModels and BSKFswModels), with gateway messages acting as a common interface for downstream modules.

Training / execution regime: there is no training regime in the machine-learning sense. The closest analog is simulation execution. The paper shows a minimal standalone run where a SimulationBaseClass.SimBaseClass() object is created, a process and task are defined, a Spacecraft module is instantiated, visualization is enabled through vizSupport.enableUnityVisualization(..., liveStream=False, saveFile=file), InitializeSimulation() is called, the stop time is configured, and ExecuteSimulation() runs the timeline. In the Earth-orbit case, the spacecraft hub is initialized with physical parameters (mass 750 kg and a 3x3 inertia matrix with diagonal 900/800/700 kg·m2 in the standalone YAML example; another BSKSim example uses 900/800/600), then gravity bodies and optional spherical harmonics are enabled. In the BSKSim attitude-control example, the dynamics model instantiates spacecraft, gravity factory, simple navigation, an external force/torque effector, and an ephemeris converter; the flight software model wires hill-point guidance, attitude reference, attitude tracking error, and MRP feedback control with gains K=3.5, Ki=-1.0, P=30.0, and an integral limit set to 0.1*2/Ki (notably negative because of Basilisk’s sign convention). The paper mentions Monte Carlo analysis at a high level in the abstract and section heading, but the truncated source here does not provide the iteration count, randomization scheme, or statistical summary details.

Evaluation protocol and reproducibility: evaluation is qualitative and demonstration-based. Success is shown by the ability to build the image once and execute several scenarios consistently, including visualization in Vizard and data logging to NumPy arrays/CSV. The paper emphasizes practical checks such as physically consistent inertia matrices (it warns that the sum of any two principal moments must exceed the third) and the non-obvious need to call AddModelToTask() to ensure dynamics are actually propagated. It compares no quantitative model metrics against baselines because there is no learned model or control-performance benchmark in the text provided. Reproducibility is strengthened by pinning the Basilisk commit, freezing package ranges, and using Docker Compose plus bind mounts. The paper says the full scripts are available at [8], and the Docker setup itself is explicitly shown in code, but the source excerpt does not mention released container images or frozen weights (none are relevant here). One concrete end-to-end example: in the Earth-orbit scenario, the user creates an Earth grav body, optionally enables J2 from GGM03S-J2-only.txt, converts the chosen Keplerian elements to inertial r and v with elem2rv(), assigns those to spacecraft_obj.hub.r_CN_NInit and v_CN_NInit, computes n = sqrt(mu/a^3) and T = 2*pi/n, logs scStateOutMsg with a chosen sampling period, initializes the simulation, and then executes it so Vizard can render the resulting orbit.

Technical innovations

• A Dockerized Basilisk build/runtime workflow that pins the upstream Basilisk commit and dependency stack for reproducible GN&C simulation execution.
• A concrete host/container directory layout with bind mounts and .env-based PYTHONPATH wiring that keeps scenario scripts editable on the host while using compiled Basilisk modules in-container.
• A stepwise reference implementation spanning standalone scripts, Earth-orbit dynamics with J2, SPICE-based multi-body scenarios, and BSKSim-based control/Monte Carlo structure.
• A reusable BSKSim class split between dynamics and flight software models, with gateway messages and module priorities used to make execution ordering explicit.

Datasets

• None — n/a — no empirical dataset; the paper uses simulation scripts, Basilisk support files, GGM03S-J2-only.txt, and SPICE kernels (de430.bsp, naif0012.tls, de-403-masses.tpc, pck00010.tpc).

Figures from the paper

Figures are reproduced from the source paper for academic discussion. Original copyright: the paper authors. See arXiv:2605.12443.

Fig 2: Example spacecraft visualization rendered using Vizard during an Earth-orbit Basilisk simulation.

Fig 7: Spacecraft in low-Earth orbit rendered in Vizard from the Earth-orbit scenario.

Fig 8: Sun-Earth-spacecraft simulation rendered in Vizard using SPICE ephemerides.

Limitations

• No quantitative comparison against a non-containerized Basilisk setup is reported; the benefit is asserted as reproducibility/portability, not measured with timing or failure rates.
• The paper is a workflow reference, so the simulations are illustrative rather than exhaustive; it does not report numerical control-performance results, Monte Carlo statistics, or sensitivity analyses in the excerpt provided.
• The container is pinned to a specific Basilisk commit and package ranges, which improves reproducibility but may age quickly as upstream dependencies change.
• Some important behaviors are noted but not deeply validated empirically here, e.g., the claim that omitting AddModelToTask() silently yields no propagation.
• The Monte Carlo workflow is mentioned, but the excerpt does not include the randomization design, number of runs, or any statistical robustness analysis.
• Reproducibility depends on external assets (Git LFS content, gravity files, SPICE kernels) remaining accessible and unchanged.

Open questions / follow-ons

• How portable is the exact container recipe across GPU-enabled, real-time, or HIL-style Basilisk deployments where Dockerization can introduce device and latency constraints?
• What is the minimal set of pinned dependencies needed for long-term reproducibility without over-constraining the environment as Basilisk evolves?
• Can the same containerized workflow be extended to automated regression testing that catches silent simulation errors like omitted task registration?
• How robust is the BSKSim architecture under more complex mission scenarios with many interacting modules, multiple spacecraft, or large Monte Carlo ensembles?

Why it matters for bot defense

For a bot-defense or CAPTCHA practitioner, the main takeaway is procedural rather than algorithmic: if your simulation or evaluation environment is hard to reproduce, you will struggle to trust benchmark results, compare defenses, or debug regressions. The paper’s Docker-plus-pinned-commit pattern is directly applicable to adversarial evaluation pipelines, synthetic attacker simulation, and controlled testbeds where you want the same scripts, dependencies, and data files to behave identically across analysts and CI runners.

The architecture advice also transfers well: keep scenario parameters in config files, separate reusable model code from per-experiment orchestration, and make execution order explicit rather than implicit. In bot-defense work, that helps prevent subtle evaluation bugs—wrong task ordering, missing model registration, hidden environment drift, or inconsistent logging—that can otherwise make a defense look stronger or weaker than it really is.

Cite

@article{arxiv2605_12443,
  title={ Basilisk and Docker for Reproducible GN&C Simulation: A Workflow Reference },
  author={ Anubhav Gupta },
  journal={arXiv preprint arXiv:2605.12443},
  year={ 2026 },
  url={https://arxiv.org/abs/2605.12443}
}

Read the full paper

• arXiv:2605.12443 (abstract)
• arXiv:2605.12443 (PDF)