Quick Reference

Goal Command / Path Notes
Format everything conda run -n orbitron-dev cargo fmt --all Run before sending PRs; CI enforces formatting.
Run focused viewer tests conda run -n orbitron-dev cargo nextest run -p orbitron-ui-shell start_new_session_uses_truly_empty_scene A filter that matches nothing exits 0 having run nothing, so check the reported test count.
Launch desktop viewer from workspace root conda run -n orbitron-dev cargo run --release -p orbitron-ui-shell --bin orbitron-viewer -- fixtures/benzene.xyz Mirrors the user workflow in the User Guide (§3 Graphical Viewer). orbitron-cli does not link the desktop; there is no gui feature.
GUI smoke test conda run -n orbitron-dev cargo nextest run -p orbitron-ui-shell a_blank_session_opens_and_presents_a_frame Launches orbitron-viewer in a blank session (ORBITRON_AUTOCLOSE_MS=200 set internally by the test) and asserts it presents a frame before exiting.
TUI smoke test ORBITRON_TUI_AUTOCLOSE=1 conda run -n orbitron-dev cargo nextest run -p orbitron-cli --features tui --test view Loads the terminal UI with an empty scene and exits immediately.
TUI render benchmark conda run -n orbitron-dev cargo bench -p orbitron-tui --bench render --features bench-stats Profiles ASCII glyph/bond rendering via Criterion.
Build Python bridge conda run --no-capture-output -n orbitron-dev python -m pip install -e extensions/python-bridge Uses the PEP 517 wrapper, which builds and stages the widget and WASM assets. maturin develop skips those steps.
Inspect selection engine conda run -n orbitron-dev cargo run --release -p orbitron-cli -- select "element C and within_atom(1, 3.0)" fixtures/benzene.xyz Uses the query stack described in §5.2.
Generate release bundle (macOS) bash scripts/build-macos-release.sh (or see scripts/BUILD_RELEASE.md) Wraps the steps in Packaging & Distribution.

Environment Variables

Variable Applies to Effect
RUST_LOG desktop viewer Tracing filter for stderr (default warn; e.g. RUST_LOG=debug). The CLI ignores it; use --log-level there.
WGPU_BACKEND desktop, CLI render Force a wgpu backend (gl, vulkan, metal) when the default is unavailable. See the Debugging Playbook.
RAYON_NUM_THREADS all native crates Cap Rayon’s global thread pool. =1 pins parallel paths (e.g. orbital grid evaluation) to one worker for approximate serial-vs-parallel comparisons.
ORBITRON_CONFIG CLI, desktop Path of the config.toml that OrbitronConfig::default_path resolves to, instead of the user’s configuration directory (an empty value counts as unset). The CLI test harness (common::orbitron()) points it at a path nothing creates, so tests get built-in defaults rather than the developer’s saved preferences.
ORBITRON_CANONICAL_CACHE CLI, desktop Override the canonical-bundle cache directory.
ORBITRON_CLI_PROGRESS CLI =0 disables progress bars (set automatically by --no-progress and --quiet).
ORBITRON_CLI_QUIET CLI =1 suppresses the startup banner (set automatically by --quiet).
ORBITRON_VASP_SKIP_VOLUMETRIC parsers Skip volumetric payloads in VASP output; faster loads when densities are not needed.
ORBITRON_MSAA_SAMPLES desktop renderer Request an MSAA sample count (1, 2, 4, 8, or 16; clamped to a power of two and to what the adapter supports).
ORBITRON_LIGHTING_PRESET desktop Apply a named lighting preset at startup (case-insensitive).
ORBITRON_NO_SPECULAR desktop Zero both specular intensities for a matte look.
ORBITRON_SYNC_LOAD desktop Load the startup file synchronously before first paint.
ORBITRON_AUTOCLOSE_MS GUI smoke tests Auto-close the viewer after N milliseconds (CI-friendly).
ORBITRON_TUI_AUTOCLOSE TUI smoke tests Exit immediately after load (CI-friendly).
ORBITRON_TUI_NO_SPLASH TUI Skip the splash screen.
ORBITRON_TUI_FPS TUI Show the frame rate in the molecule panel title.
ORBITRON_REGEN_BASELINES render-parity tests Regenerate golden images instead of diffing against them.
ORBITRON_RENDER_PARITY_REQUIRE_GPU render-parity tests =1 turns “no usable GPU adapter” into a failure instead of a skip. CI’s lavapipe job sets it.
ORBITRON_SKIP_VIEWER_BUILD stage_viewer_assets.sh =1 stages the existing viewer/wasm artifacts without re-running trunk + esbuild.
ORBITRON_SKIP_VIEWER_ASSETS wheel build backend =1 builds the wheel without the staged viewer bundle.
ORBITRON_SKIP_WIDGET_BUILD wheel build backend =1 skips the Jupyter widget frontend build.
ORBITRON_NO_MMAP parsers Any non-empty value disables memory-mapped reads and falls back to buffered I/O.
ORBITRON_INCHI_BINARY orbitron-inchi oracle tests Path to a reference inchi-1 executable; the #[ignore]d oracle tests need it.
ORBITRON_TRAJECTORY_NOTEBOOK_PATH Python bridge tests Path to a real optimisation log. Un-skips the trajectory notebook test, which otherwise skips in silence.
ORBITRON_REQUIRE_OFFSCREEN_GPU_TESTS core/render offscreen tests Any value turns a missing GPU adapter into a failure instead of a skip. CI’s Windows dx12 leg sets it.
ORBITRON_RAW_SOURCE_INLINE_MAX core/orbpack Byte threshold (default 64 MiB) below which a raw_source payload is copied into memory. At or above it the attachment carries empty data and export re-reads from source_path, keeping a several-hundred-MB verbatim echo off the heap. Set it to 1 to force the re-read path in a test.
ORBITRON_SKIP_GUI_TESTS / ORBITRON_FORCE_GUI_TESTS GUI smoke tests Force the display guard off / on regardless of the detected environment.
CARGO_BUILD_JOBS all builds Cap rustc parallelism (16, for example, on a 24-core machine). Does nothing once nextest starts running tests — see .config/nextest.toml.

Smoke Test Checklist (Pre-release)

  • conda run -n orbitron-dev cargo run --release -p orbitron-cli --bin orbitron -- info io/pipelines/tests/fixtures/xyz/water.xyz --json
  • conda run -n orbitron-dev cargo run --release -p orbitron-cli --bin orbitron -- analyze geometry fixtures/benzene.xyz --json
  • conda run -n orbitron-dev cargo run --release -p orbitron-ui-shell --bin orbitron-viewer
  • conda run -n orbitron-dev cargo run --release -p orbitron-ui-shell --bin orbitron-viewer -- io/pipelines/tests/fixtures/xyz/water.xyz
  • mkdir -p ~/scratch/orbitron-smoke && conda run -n orbitron-dev cargo run --release -p orbitron-cli --bin orbitron -- render --output ~/scratch/orbitron-smoke/water.png io/pipelines/tests/fixtures/xyz/water.xyz
  • TUI (manual): conda run -n orbitron-dev cargo run --release -p orbitron-cli --bin orbitron -- view io/pipelines/tests/fixtures/xyz/water.xyz --tui