mechanicsdsl-notebooks

Curated Jupyter notebooks spanning all eight MechanicsDSL physics domains.

Available Notebooks

More notebooks in development — see docs/index.md for the full planned curriculum.

Launch

Binder (no install required):

Local:

pip install mechanicsdsl-core[jupyter]
git clone https://github.com/MechanicsDSL/mechanicsdsl-notebooks
cd mechanicsdsl-notebooks
jupyter lab

Repository Structure

mechanicsdsl-notebooks/
├── notebooks/              # Jupyter notebooks (numbered sequentially)
│   ├── 01_double_pendulum.ipynb
│   ├── 02_coupled_oscillators.ipynb
│   ├── 03_constraints.ipynb
│   ├── 04_central_forces.ipynb
│   └── 05_hamiltonian.ipynb
├── binder/                 # Binder environment configuration
│   ├── environment.yml
│   └── postBuild
├── docs/                   # Documentation
│   ├── index.md            # Full curriculum index
│   └── notation.md         # DSL notation reference
├── scripts/
│   ├── check_notebooks.py  # Execute and validate all notebooks
│   └── generate_index.py   # Auto-regenerate docs/index.md
└── tests/
    └── test_notebooks_run.py

What MechanicsDSL Does in Each Notebook

Every notebook includes the DSL specification that the MechanicsDSL compiler uses to automatically:

• Derive equations of motion via the Euler-Lagrange equations symbolically
• Identify conserved quantities via Noether's theorem
• Generate NumPy, JAX, or other backend simulation code

Example from Notebook 05:

\system{pendulum_hamiltonian}
\parameter{m}{1.0}{kg}
\parameter{l}{1.0}{m}
\lagrangian{0.5*m*l^2*\dot{theta}^2 - m*g*l*(1-cos(theta))}
\target{python_numpy}

MechanicsDSL derives: $H = p_\theta^2/(2ml^2) + mgl(1-\cos\theta)$ and generates Hamilton's equations automatically.

For Instructors

Notebooks are designed for direct classroom use — no prior DSL knowledge assumed. Each opens with physics motivation, introduces DSL syntax progressively, and includes interactive parameter exploration. If you use these notebooks in a course, open an issue to be acknowledged in the documentation.

Testing

pip install pytest nbconvert
python scripts/check_notebooks.py       # execute all notebooks
pytest tests/ -v                        # validate structure

Contributing

See CONTRIBUTING.md. Domain coverage especially needed: rigid body, perturbation theory, quantum tunneling, electromagnetism, general relativity.

Citation

@software{mechanicsdsl2026,
  author = {Parsons, Noah},
  title  = {{MechanicsDSL Notebooks}},
  year   = {2026},
  doi    = {10.5281/zenodo.17771040},
  url    = {https://github.com/MechanicsDSL/mechanicsdsl-notebooks}
}

License

MIT License — see LICENSE.