Physics Simulator

Physics Simulator is an interactive Manim-based collision and scattering playground for building, rendering, and profiling physics scenes.

Current development version: 0.4.0

Quick Start

1. Run pwsh -ExecutionPolicy Bypass -File scripts/setup.ps1 from the repository root.
2. Check the available simulator surfaces with uv run python simulation --list.
3. Launch the supported authoring surface with uv run python simulation scattering_playground.
4. Run the full validation suite with uv run pytest -q.

No manual virtual environment activation is required. The repository is set up to use uv run for both local development and CI.

Product Scope

• Primary surface: scattering_playground is the only listed simulator and the only supported authoring surface.
• Engineering tooling: benchmark and diagnostic commands remain available for profiling and regression tracking, but they are intentionally secondary to the playground workflow.
• Sample Manim scene: uv run python "my first video code.py" stays in the repository as a simple baseline script example.
• Release default: the tracked playground default now ships as an empty scene with committed shared example configs alongside it.

Common Commands

Launch and render

• uv run python simulation scattering_playground
• 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

Benchmark and diagnostics

• 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

Validation

• uv run pytest -q
• uv run pytest tests/simulations -q
• uv run pytest tests/simulations/scattering_playground -q
• uv run python simulation --list
• pwsh -ExecutionPolicy Bypass -File scripts/clean-local-env.ps1 -Preview

Simulation renders default to concise terminal output. Add --verbose when you want full Manim logs.

Cleanup script options:

• Default run: pwsh -ExecutionPolicy Bypass -File scripts/clean-local-env.ps1 Deletes repo-local .venv/, __pycache__/, .pytest_cache/, and root media/.
• -Preview Shows what would be removed without deleting anything.
• -IncludeUnignored Expands cleanup from the safe default scope to all untracked files in the checkout, including non-ignored files. Use -Preview first when using this mode.
• -WhatIf Uses PowerShell's built-in should-process preview in addition to the script's own reporting.

Recommended maintenance flow:

• pwsh -ExecutionPolicy Bypass -File scripts/clean-local-env.ps1 -Preview
• pwsh -ExecutionPolicy Bypass -File scripts/clean-local-env.ps1
• pwsh -ExecutionPolicy Bypass -File scripts/clean-local-env.ps1 -Preview -IncludeUnignored

Documentation Map

• CHANGELOG.md: version history and release-shaping milestones.
• docs/setup.md: onboarding, toolchain assumptions, and verification commands.
• docs/user-guide.md: day-to-day playground workflow, UI layout, rendering, and export.
• docs/cli.md: launcher commands, render flags, benchmark flags, and environment overrides.
• docs/physics.md: material preset catalog, collision behavior, and deformation model.
• docs/architecture.md: repository structure and subsystem boundaries.
• docs/testing.md: test layout, CI expectations, and shared harnesses.

Branch and Release Workflow

• Daily development happens on dev/* branches.
• A push to dev/* runs validation and attempts to open or update a PR into main.
• If GitHub Actions is not allowed to create PRs in the repository, the workflow exits with a warning and the PR is opened manually.
• main remains the release-ready branch and is merged manually after checks pass.
• Merge only when docs, version metadata, and tracked default-config behavior match the intended release state.

The validation and PR automation live under .github/workflows/ and are intentionally lightweight: one validation workflow and one dev-branch PR workflow.

Ownership And License

The first-party source, documentation, configurations, and committed assets in this repository are owned by Daniel Lomazov and covered by the proprietary terms in LICENSE.

Where It All Started

This simulator traces back to the early work of Dr. Meny Menashes PhD in AtomicA-vids. His friendship, creative partnership, and steady collaboration helped turn that first spark into something worth continuing, and this repository carries that shared beginning forward with gratitude. With ongoing collaboration and perspective, that shared start still helps shape what comes next.