Metadata-Version: 2.4
Name: mechanicsdsl-core
Version: 2.1.0
Summary: A Domain-Specific Language and Transpiler for Classical Mechanics
Author-email: Noah Parsons <nomapa223@gmail.com>
License: MIT License
        
        Copyright (©) 2025 Mechanics_DSL
        
        Permission is hereby granted, free of charge, to any person obtaining a copy
        of this software and associated documentation files (the "Software"), to deal
        in the Software without restriction, including without limitation the rights
        to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
        copies of the Software, and to permit persons to whom the Software is
        furnished to do so, subject to the following conditions:
        
        The above copyright notice and this permission notice shall be included in all
        copies or substantial portions of the Software.
        
        THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
        IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
        FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
        AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
        LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
        OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
        SOFTWARE.
        
Project-URL: Repository, https://github.com/MechanicsDSL/mechanicsdsl
Project-URL: Documentation, https://mechanicsdsl.readthedocs.io
Project-URL: Bug Tracker, https://github.com/MechanicsDSL/mechanicsdsl/issues
Keywords: physics,simulation,mechanics,dsl,lagrangian,hamiltonian,code-generation,scientific-computing,embedded,raspberry-pi,arm,gpu,cuda
Classifier: Development Status :: 5 - Production/Stable
Classifier: Intended Audience :: Science/Research
Classifier: Intended Audience :: Education
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: OS Independent
Classifier: Operating System :: POSIX :: Linux
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.9
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Programming Language :: Python :: 3.14
Classifier: Programming Language :: C++
Classifier: Programming Language :: Rust
Classifier: Topic :: Scientific/Engineering :: Physics
Classifier: Topic :: Scientific/Engineering :: Mathematics
Classifier: Topic :: Software Development :: Code Generators
Classifier: Topic :: Software Development :: Compilers
Classifier: Topic :: System :: Emulators
Classifier: Topic :: System :: Hardware
Requires-Python: >=3.9
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: numpy>=1.20.0
Requires-Dist: scipy>=1.7.0
Requires-Dist: sympy>=1.8
Requires-Dist: matplotlib>=3.4.0
Requires-Dist: tqdm>=4.60.0
Provides-Extra: test
Requires-Dist: pytest; extra == "test"
Requires-Dist: pytest-cov; extra == "test"
Requires-Dist: hypothesis>=6.0; extra == "test"
Provides-Extra: codegen
Requires-Dist: pybind11; extra == "codegen"
Provides-Extra: jit
Requires-Dist: numba>=0.56.0; extra == "jit"
Provides-Extra: typing
Requires-Dist: mypy; extra == "typing"
Requires-Dist: types-setuptools; extra == "typing"
Provides-Extra: jax
Requires-Dist: jax>=0.4.0; extra == "jax"
Requires-Dist: jaxlib>=0.4.0; extra == "jax"
Requires-Dist: diffrax>=0.4.0; extra == "jax"
Provides-Extra: jax-gpu
Requires-Dist: jax[cuda12]>=0.4.0; extra == "jax-gpu"
Requires-Dist: diffrax>=0.4.0; extra == "jax-gpu"
Provides-Extra: server
Requires-Dist: fastapi>=0.100.0; extra == "server"
Requires-Dist: uvicorn>=0.22.0; extra == "server"
Requires-Dist: websockets>=11.0; extra == "server"
Provides-Extra: jupyter
Requires-Dist: ipywidgets>=8.0.0; extra == "jupyter"
Requires-Dist: ipython>=8.0.0; extra == "jupyter"
Provides-Extra: lsp
Requires-Dist: pygls>=1.0.0; extra == "lsp"
Requires-Dist: lsprotocol>=2023.0.0; extra == "lsp"
Provides-Extra: openmao
Requires-Dist: openmdao>=3.25.0; extra == "openmao"
Provides-Extra: embedded
Requires-Dist: RPi.GPIO>=0.7.0; (platform_machine == "aarch64" or platform_machine == "armv7l") and extra == "embedded"
Provides-Extra: arm
Requires-Dist: numpy>=1.20.0; extra == "arm"
Provides-Extra: dev
Requires-Dist: pytest; extra == "dev"
Requires-Dist: pytest-cov; extra == "dev"
Requires-Dist: hypothesis>=6.0; extra == "dev"
Requires-Dist: mypy; extra == "dev"
Requires-Dist: types-setuptools; extra == "dev"
Requires-Dist: black; extra == "dev"
Requires-Dist: flake8; extra == "dev"
Requires-Dist: isort; extra == "dev"
Requires-Dist: bandit; extra == "dev"
Provides-Extra: all
Requires-Dist: numba>=0.56.0; extra == "all"
Requires-Dist: pybind11; extra == "all"
Requires-Dist: hypothesis>=6.0; extra == "all"
Requires-Dist: mypy; extra == "all"
Requires-Dist: fastapi>=0.100.0; extra == "all"
Requires-Dist: uvicorn>=0.22.0; extra == "all"
Requires-Dist: ipywidgets>=8.0.0; extra == "all"
Requires-Dist: pygls>=1.0.0; extra == "all"
Dynamic: license-file

![MechanicsDSL Logo](docs/images/logo.png)

# MechanicsDSL

[![Python CI](https://github.com/MechanicsDSL/mechanicsdsl/actions/workflows/python-app.yml/badge.svg)](https://github.com/MechanicsDSL/mechanicsdsl/actions/workflows/python-app.yml)
[![PyPI Downloads](https://static.pepy.tech/personalized-badge/mechanicsdsl-core?period=total&units=INTERNATIONAL_SYSTEM&left_color=GRAY&right_color=BLUE&left_text=Downloads)](https://pepy.tech/projects/mechanicsdsl-core)
![Python 3.9+](https://img.shields.io/badge/python-3.9%2B-blue)
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
[![DOI](https://zenodo.org/badge/DOI/10.5281/zenodo.17771040.svg)](https://doi.org/10.5281/zenodo.17771040)
[![Documentation Status](https://readthedocs.org/projects/mechanicsdsl/badge/?version=latest)](https://mechanicsdsl.readthedocs.io/en/latest/?badge=latest)

*Write a Lagrangian. Get a simulation.*

---

MechanicsDSL is a domain-specific language and compiler for physical systems. You write a Lagrangian or Hamiltonian in a LaTeX-inspired syntax; the symbolic engine (built on SymPy) derives the equations of motion automatically, and the compiler generates simulation code in your choice of thirteen target languages — from Python and C++ to CUDA, Rust, WebAssembly, and Arduino.

The goal is to collapse the distance between textbook physics and a running simulation, while keeping the path to lower-level, performance-tuned code open through code generation.

```python
from mechanics_dsl import PhysicsCompiler

compiler = PhysicsCompiler()
compiler.compile_dsl(r"""
\system{pendulum}
\defvar{theta}{Angle}{rad}
\parameter{m}{1.0}{kg}
\parameter{l}{1.0}{m}
\parameter{g}{9.81}{m/s^2}

\lagrangian{\frac{1}{2} * m * l^2 * \dot{theta}^2 - m * g * l * (1 - \cos{theta})}
\initial{theta=0.5, theta_dot=0.0}
""")

solution = compiler.simulate(t_span=(0, 10), num_points=1000)
compiler.plot(solution)
```

## What's in the box

| Component | Description |
|-----------|-------------|
| **Symbolic engine** | Derives equations of motion from Lagrangians or Hamiltonians, built on SymPy |
| **Code generation** | Thirteen targets: C++, Python, Rust, Julia, CUDA, Fortran, MATLAB, JavaScript, OpenMP, WebAssembly, Arduino, ARM, Modelica |
| **JAX backend** | GPU acceleration with JIT compilation and automatic differentiation |
| **Inverse problems** | Parameter estimation, sensitivity analysis, MCMC uncertainty quantification |
| **Jupyter integration** | `%%mechanicsdsl` magic commands for interactive notebooks |
| **Plugin architecture** | Custom physics domains and solvers without modifying the core |

> **Note on generated code.** The code generators produce working reference implementations, not production-tuned binaries. For high-performance or mission-critical work, treat the generated code as a starting point rather than a finished product.

## Installation

```bash
pip install mechanicsdsl-core
```

Optional extras:

```bash
pip install mechanicsdsl-core[jax]      # GPU + autodiff
pip install mechanicsdsl-core[jupyter]  # Notebook magic
pip install mechanicsdsl-core[all]      # Everything
```

Requires Python 3.9+. NumPy, SciPy, SymPy, and Matplotlib are installed automatically.

## Example: Figure-8 three-body orbit

```python
from mechanics_dsl import PhysicsCompiler

code = r"""
\system{figure8_orbit}
\defvar{x1}{Position}{m} \defvar{y1}{Position}{m}
\defvar{x2}{Position}{m} \defvar{y2}{Position}{m}
\defvar{x3}{Position}{m} \defvar{y3}{Position}{m}
\defvar{m}{Mass}{kg} \defvar{G}{Grav}{1}

\parameter{m}{1.0}{kg} \parameter{G}{1.0}{1}

\lagrangian{
    0.5 * m * (\dot{x1}^2 + \dot{y1}^2 + \dot{x2}^2 + \dot{y2}^2 + \dot{x3}^2 + \dot{y3}^2)
    + G*m^2/\sqrt{(x1-x2)^2 + (y1-y2)^2}
    + G*m^2/\sqrt{(x2-x3)^2 + (y2-y3)^2}
    + G*m^2/\sqrt{(x1-x3)^2 + (y1-y3)^2}
}
"""

compiler = PhysicsCompiler()
compiler.compile_dsl(code)
compiler.simulator.set_initial_conditions({
    'x1': 0.97000436,  'y1': -0.24308753, 'x1_dot': 0.466203685, 'y1_dot': 0.43236573,
    'x2': -0.97000436, 'y2': 0.24308753,  'x2_dot': 0.466203685, 'y2_dot': 0.43236573,
    'x3': 0.0,         'y3': 0.0,         'x3_dot': -0.93240737, 'y3_dot': -0.86473146
})
solution = compiler.simulate(t_span=(0, 6.326), num_points=2000)
```

The `examples/` directory contains 30+ progressive examples, from harmonic oscillators to SPH fluid dynamics.

## Code generation

Any compiled system can be exported as standalone code in any of the supported targets:

| Target | Output |
|--------|--------|
| C++ | CMake project with solver |
| Python | NumPy/SciPy standalone script |
| Rust | Cargo project, `no_std` option |
| Julia | DifferentialEquations.jl |
| CUDA | GPU-parallel solver |
| Fortran | F90 with LAPACK |
| MATLAB | `.m` script with `ode45` |
| JavaScript | Browser or Node.js |
| OpenMP | Multi-threaded C++ |
| WebAssembly | Emscripten WASM |
| Arduino | `.ino` embedded sketch |
| ARM | Raspberry Pi / NEON |
| Modelica | Standards-based FMU |

```python
from mechanics_dsl.codegen.rust import RustGenerator

gen = RustGenerator(
    system_name="pendulum",
    coordinates=compiler.get_coordinates(),
    parameters=compiler.simulator.parameters,
    initial_conditions=compiler.initial_conditions,
    equations=compiler.equations,
)
gen.generate("pendulum.rs")
```

## Physics coverage

- **Classical mechanics** — Lagrangian and Hamiltonian formulations; holonomic, non-holonomic, and rolling constraints; Rayleigh dissipation; stability analysis; Noether's theorem; central forces; canonical transformations; normal modes; rigid body dynamics; perturbation theory; collisions; scattering; variable-mass systems; continuous media.
- **Quantum mechanics** — Bound states, scattering, tunneling, WKB approximation, hydrogen atom, Ehrenfest theorem.
- **Electromagnetism** — Lorentz force, cyclotron motion, plane waves, antennas, waveguides, Penning traps.
- **Relativity** — Special: Lorentz boosts, four-vectors, Doppler effect. General: Schwarzschild and Kerr metrics, geodesics, gravitational lensing, FLRW cosmology.
- **Statistical mechanics and thermodynamics** — Microcanonical, canonical, and grand canonical ensembles; Boltzmann, Fermi-Dirac, and Bose-Einstein distributions; Ising model; heat engines; phase transitions.
- **Fluid dynamics** — SPH solver with Poly6, Spiky, and viscosity kernels; Tait equation of state; boundary conditions.

## Project status

MechanicsDSL is under active development. The v2.0.x line is stable; new features, additional backends, and broader validation are ongoing. Issues, pull requests, and use-case reports are all welcome — what the project becomes next depends in part on how people are using it.

## Documentation

Full documentation, tutorials, and DSL reference at **[mechanicsdsl.readthedocs.io](https://mechanicsdsl.readthedocs.io/)**.

## Contributing

Contributions are welcome. See [CONTRIBUTING.md](CONTRIBUTING.md) for guidelines.

## License

MIT — see [LICENSE](LICENSE).
