Skip to content

cli.md

Latest commit

 

History

History
141 lines (95 loc) · 4.18 KB

cli.md

File metadata and controls

141 lines (95 loc) · 4.18 KB
Raw

Command-Line Guide

This repository exposes one canonical command surface through the shared launcher.

Preferred Launcher

The preferred entrypoint is the shared launcher:

uv run python simulation <command>

List available simulators:

uv run python simulation --list

Launch the playground UI:

uv run python simulation scattering_playground

The launcher also accepts the simulator flags generated from the manifest:

  • --scattering-playground
  • --scattering_playground.py

The positional form simulation scattering_playground is the preferred documented form.

Passing Through Simulator-Specific Args

The shared launcher forwards simulator-specific arguments after --.

Examples:

uv run python simulation scattering_playground -- --render
uv run python simulation scattering_playground -- --render --playback-rate 0.5
uv run python simulation scattering_playground -- --config path\to\scene.json
uv run python simulation scattering_playground -- --render --config path\to\scene.json

Committed shared example configs live under simulations/scattering_playground/shared_configs/. Those files are ordinary JSON configs and can be passed to --config directly.

Render Behavior

The simulator-specific entrypoint supports:

  • --ui to open the interactive UI,
  • --render to render the selected config,
  • --config to point at a JSON config file,
  • --playback-rate to override rendered playback speed when used with --render.

--playback-rate requires --render.

Benchmark Commands

Benchmark commands are intentionally documented as engineering tooling rather than the primary product surface.

You can run them from the shared launcher:

uv run python simulation --benchmark-render-speed
uv run python simulation --benchmark-diagnostic-profile
uv run python simulation --refresh-benchmark-graphs
uv run python simulation --reset-benchmark-data

With the current registry, shared-launcher benchmark commands default to scattering_playground; --benchmark-simulation only matters if additional benchmarkable simulator surfaces are added later.

Useful benchmark flags:

  • --benchmark-durations 1,2,3
  • --benchmark-extended-durations
  • --benchmark-subsecond-durations
  • --benchmark-quality 1080p60
  • --benchmark-seed 12345
  • --benchmark-max-substep 0.0005
  • --avg-over-rand-sample 3

Output And Verbosity

Render commands keep terminal output concise by default.

  • --verbose forces MANIM_QUIET_RENDER=0.
  • Without --verbose, the launcher defaults to concise render output.

Benchmark commands also keep the output concise and are designed for repeatable profiling runs.

Common Recipes

Render a saved scene in slow motion:

uv run python simulation scattering_playground -- --render --config path\to\scene.json --playback-rate 0.5

Render a committed shared example:

uv run python simulation scattering_playground -- --render --config simulations\scattering_playground\shared_configs\six-ball-showcase.json --playback-rate 0.5

Compare repeated benchmark runs:

uv run python simulation --reset-benchmark-data
uv run python simulation --benchmark-render-speed
uv run python simulation --benchmark-render-speed

Collect a diagnostic profile:

uv run python simulation --benchmark-diagnostic-profile --avg-over-rand-sample 3

Environment Overrides

The shared render support layer recognizes a few environment overrides:

  • MANIM_SAVE_VIDEO: defaults to 1; set it to 0 to skip writing the output movie.
  • MANIM_MEDIA_DIR: overrides the media output root.
  • MANIM_RENDER_QUALITY: overrides the Manim quality profile.
  • MANIM_QUIET_RENDER: controls quiet render output when the CLI does not force --verbose.
  • MANIM_EMIT_RENDER_PROGRESS: controls structured progress messages used by the interactive player.

Validation Commands

Common validation commands:

uv run pytest -q
uv run pytest tests/simulations -q
uv run pytest tests/simulations/scattering_playground -q
uv run pytest tests/simulations/test_cli.py -q
uv run pytest tests/simulations/test_benchmarking.py -q
uv run python "my first video code.py"