Metadata-Version: 2.4
Name: mechanicsdsl-core
Version: 2.0.1
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

<p align="center">
  <img src="docs/images/logo.png" alt="MechanicsDSL Logo" width="400">
</p>

<h1 align="center">MechanicsDSL</h1>

<p align="center">
  <a href="https://github.com/MechanicsDSL/mechanicsdsl/actions/workflows/python-app.yml"><img src="https://github.com/MechanicsDSL/mechanicsdsl/actions/workflows/python-app.yml/badge.svg" alt="Python CI"></a>
  <a href="https://www.python.org/downloads/"><img src="https://img.shields.io/badge/python-3.8+-blue.svg" alt="Python 3.8+"></a>
  <a href="https://opensource.org/licenses/MIT"><img src="https://img.shields.io/badge/License-MIT-yellow.svg" alt="License: MIT"></a>
  <a href="https://doi.org/10.5281/zenodo.17771040"><img src="https://zenodo.org/badge/DOI/10.5281/zenodo.17771040.svg" alt="DOI"></a>
  <a href="https://mechanicsdsl.readthedocs.io/en/latest/?badge=latest"><img src="https://readthedocs.org/projects/mechanicsdsl/badge/?version=latest" alt="Documentation Status"></a>
  <img alt="PyPI - Downloads" src="https://img.shields.io/pypi/dm/mechanicsdsl-core">
<a href="https://codecov.io/github/MechanicsDSL/mechanicsdsl" > 
 <img src="https://codecov.io/github/MechanicsDSL/mechanicsdsl/graph/badge.svg"/> 
</a>
<a href="https://github.com/MechanicsDSL/mechanicsdsl/actions/workflows/codeql.yml"> 
 <img src="https://github.com/MechanicsDSL/mechanicsdsl/actions/workflows/codeql.yml/badge.svg" alt="CodeQL Advanced"> 
</a>
<a href="https://mybinder.org/v2/gh/MechanicsDSL/mechanicsdsl/main?filepath=tutorials">
 <img src="https://mybinder.org/badge_logo.svg" alt="Launch Binder">
</a>

</p>

---

**MechanicsDSL** is a computational physics framework that lets you define physical systems in a natural, LaTeX-inspired syntax and automatically generates high-performance simulations. From pendulums to planetary orbits, from Lagrangian mechanics to fluid dynamics—describe it once, simulate it anywhere.

## ✨ Why MechanicsDSL?

| Feature | Description |
|---------|-------------|
| **Symbolic Engine** | Automatically derives equations of motion from Lagrangians or Hamiltonians |
| **12+ Code Generators** | C++, Rust, Julia, CUDA, WebAssembly, Unity, Unreal, Modelica, and more |
| **GPU Acceleration** | JAX backend with JIT compilation and automatic differentiation |
| **Inverse Problems** | Parameter estimation, sensitivity analysis, MCMC uncertainty |
| **Jupyter Native** | `%%mechanicsdsl` magic commands for notebooks |
| **Real-time API** | FastAPI server with WebSocket streaming |
| **IDE Support** | LSP server for VS Code with autocomplete and diagnostics |
| **Plugin Architecture** | Extensible with custom physics domains and solvers |

---

## 📦 Installation

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

**With optional features:**

```bash
pip install mechanicsdsl-core[jax]      # GPU acceleration + autodiff
pip install mechanicsdsl-core[server]   # FastAPI real-time server
pip install mechanicsdsl-core[jupyter]  # Notebook magic commands
pip install mechanicsdsl-core[lsp]      # VS Code language server
pip install mechanicsdsl-core[embedded] # Raspberry Pi / ARM support
pip install mechanicsdsl-core[all]      # Everything
```

**Docker deployment:**

```bash
# CPU version
docker pull ghcr.io/mechanicsdsl/mechanicsdsl:latest
docker run -it ghcr.io/mechanicsdsl/mechanicsdsl:latest

# GPU version (requires nvidia-docker)
docker pull ghcr.io/mechanicsdsl/mechanicsdsl:gpu
docker run --gpus all -it ghcr.io/mechanicsdsl/mechanicsdsl:gpu
```

**Requirements:** Python 3.9+ with NumPy, SciPy, SymPy, and Matplotlib (installed automatically).

---

## 🚀 What's New in v2.0.0

**Released January 17, 2026** — Now deployed in **19 countries** across enterprise, research, and embedded platforms.

### Enterprise Deployment
- **Docker Support** — Production-ready multi-stage containers for CPU and GPU
- **docker-compose** — API server, Jupyter, and worker service orchestration
- **Kubernetes Ready** — Enterprise deployment guide with security best practices

### ARM & Embedded Platforms
- **Raspberry Pi Examples** — Real-time pendulum simulation with C++ export
- **IMU Integration** — MPU6050 sensor fusion examples
- **ARM Optimization** — NEON detection and cross-compilation support

### Enhanced Code Generation
- **C++ CMake Projects** — `generate_cmake()` and `generate_project()` methods
- **Rust Cargo Projects** — Full project scaffolding with `no_std` embedded option
- **11 Target Platforms** — C++, CUDA, Rust, Julia, Fortran, MATLAB, JavaScript, WebAssembly, Python, Arduino, OpenMP

📖 See [RELEASE_NOTES_v2.0.0.md](RELEASE_NOTES_v2.0.0.md) for full details.

---

## Quick Start

### The Famous Figure-8 Three-Body Orbit

Define a gravitational three-body system and watch it trace the celebrated Figure-8 periodic orbit:

```python
from mechanics_dsl import PhysicsCompiler

# Define the system using LaTeX-inspired DSL
figure8_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}
}
"""

# Compile and simulate
compiler = PhysicsCompiler()
compiler.compile_dsl(figure8_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)
```

### Dam Break Fluid Simulation

Simulate fluid dynamics with the integrated SPH solver:

```python
from mechanics_dsl import PhysicsCompiler

fluid_code = r"""
\system{dam_break}

\parameter{h}{0.04}{m}
\parameter{g}{9.81}{m/s^2}

\fluid{water}
\region{rectangle}{x=0.0 .. 0.4, y=0.0 .. 0.8}
\particle_mass{0.02}
\equation_of_state{tait}

\boundary{walls}
\region{line}{x=-0.05, y=0.0 .. 1.5}
\region{line}{x=1.5, y=0.0 .. 1.5}
\region{line}{x=-0.05 .. 1.5, y=-0.05}
"""

compiler = PhysicsCompiler()
compiler.compile_dsl(fluid_code)
compiler.compile_to_cpp("dam_break.cpp", target="standard", compile_binary=True)
```

---

## 🆕 New in v1.6.0

### Jupyter Magic Commands

```python
%load_ext mechanics_dsl.jupyter

%%mechanicsdsl --animate --t_span=0,20
\system{pendulum}
\defvar{theta}{Angle}{rad}
\parameter{m}{1.0}{kg}
\lagrangian{\frac{1}{2}*m*l^2*\dot{theta}^2 - m*g*l*(1-\cos{theta})}
\initial{theta=2.5, theta_dot=0.0}
```

### Parameter Estimation

```python
from mechanics_dsl.inverse import ParameterEstimator

estimator = ParameterEstimator(compiler)
result = estimator.fit(observations, t_obs, ['m', 'k'])
print(f"Fitted: m={result.parameters['m']:.3f}, k={result.parameters['k']:.3f}")
```

### Real-time API Server

```bash
python -m mechanics_dsl.server
# -> http://localhost:8000/docs
```

### External Integrations

| Platform | Module | Purpose |
|----------|--------|---------|
| **OpenMDAO** | `integrations.openmao` | Multidisciplinary optimization |
| **ROS2** | `integrations.ros2` | Robotics simulation |
| **Unity** | `integrations.unity` | Game engine (C#) |
| **Unreal** | `integrations.unreal` | Game engine (C++) |
| **Modelica** | `integrations.modelica` | Standards-based simulation |

---

## Core Capabilities

### Classical Mechanics (17 Modules)
- **Lagrangian & Hamiltonian** formulations with automatic EOM derivation
- **Constraints**: Holonomic, non-holonomic, rolling, knife-edge (Baumgarte stabilization)
- **Dissipation**: Rayleigh function, viscous/Coulomb/Stribeck friction
- **Stability Analysis**: Equilibrium points, linearization, eigenvalue analysis
- **Noether's Theorem**: Symmetry detection, conservation laws, cyclic coordinates
- **Central Forces**: Effective potential, Kepler problem, orbital mechanics
- **Canonical Transformations**: Generating functions, action-angle, Hamilton-Jacobi
- **Normal Modes**: Mass/stiffness matrices, coupled oscillators, modal decomposition
- **Rigid Body**: Euler angles, quaternions, gyroscopes, symmetric top
- **Perturbation Theory**: Lindstedt-Poincaré, averaging, multi-scale analysis
- **Collisions**: Elastic/inelastic, impulse, center of mass frame
- **Scattering**: Rutherford, cross-sections, impact parameter
- **Variable Mass**: Tsiolkovsky rocket equation, conveyor belts
- **Continuous Systems**: Vibrating strings, membranes, field equations

### Quantum Mechanics
- **Bound States**: Infinite well, finite square well, hydrogen atom
- **Scattering**: Step potential, delta barriers, transmission/reflection coefficients
- **Quantum Tunneling**: Rectangular barriers, WKB approximation, Gamow factor
- **Semiclassical**: WKB wavefunctions, Bohr-Sommerfeld quantization
- **Hydrogen Atom**: Energy levels, Bohr radius, spectral series (Lyman, Balmer, etc.)
- **Ehrenfest Theorem**: Quantum-classical correspondence

### Electromagnetism
- **Charged Particles**: Lorentz force, cyclotron motion, Larmor radius
- **Waves**: Plane waves, Poynting vector, radiation pressure
- **Antennas**: Hertzian dipole, λ/2 dipole, radiation resistance
- **Waveguides**: TE/TM modes, cutoff frequencies, group velocity
- **Traps**: Penning trap, magnetic dipole traps, gradient/curvature drift

### Special Relativity
- **Kinematics**: Lorentz boosts, velocity addition, time dilation, length contraction
- **Four-Vectors**: Spacetime intervals, invariants, metric signature (+,-,-,-)
- **Doppler Effect**: Longitudinal, transverse, cosmological redshift
- **Radiation**: Synchrotron radiation, Thomas precession, twin paradox

### General Relativity
- **Black Holes**: Schwarzschild metric, Kerr (rotating), ergosphere
- **Geodesics**: Light bending, ISCO, photon sphere
- **Lensing**: Deflection angle, Einstein radius, magnification
- **Cosmology**: FLRW metric, Hubble law, comoving distance

### Statistical Mechanics
- **Ensembles**: Microcanonical, canonical, grand canonical
- **Distributions**: Boltzmann, Fermi-Dirac, Bose-Einstein
- **Models**: Ising model, ideal gas, quantum harmonic oscillator
- **Thermodynamic Quantities**: Partition functions, entropy, free energy

### Thermodynamics
- **Heat Engines**: Carnot, Otto, Diesel cycles
- **Equations of State**: Ideal gas, van der Waals
- **Phase Transitions**: Clausius-Clapeyron, latent heat
- **Heat Capacity**: Debye, Einstein models

### Fluid Dynamics
- **SPH Solver**: Smoothed Particle Hydrodynamics for incompressible fluids
- **Kernels**: Poly6, Spiky, Viscosity with Tait equation of state
- **Boundaries**: No-slip, periodic, reflective conditions


---

## 📚 Examples & Tutorials

### Interactive Tutorials (Jupyter)

| # | Tutorial | Topics |
|---|----------|--------|
| 1 | [Getting Started](tutorials/01_getting_started.ipynb) | DSL basics, simple pendulum, export |
| 2 | [Double Pendulum](tutorials/02_double_pendulum.ipynb) | Chaos, sensitivity, phase space |
| 3 | [Parameter Estimation](tutorials/03_parameter_estimation.ipynb) | Inverse problems, Sobol analysis |

[![Launch Binder](https://mybinder.org/badge_logo.svg)](https://mybinder.org/v2/gh/MechanicsDSL/mechanicsdsl/main?labpath=tutorials)

### Example Scripts

The [`examples/`](examples/) directory contains 30+ progressive examples:

| Level | Examples |
|-------|----------|
| **Beginner** | Harmonic oscillator, Simple pendulum, Plotting basics |
| **Intermediate** | Double pendulum, Coupled oscillators, 2D motion, Damping |
| **Advanced** | 3D gyroscope, Hamiltonian formulation, Phase space, Energy analysis |
| **Expert** | C++ export, WebAssembly targets, SPH fluid dynamics |

---

## Documentation

Full documentation with tutorials, API reference, and DSL syntax guide:

**[Read the Docs](https://mechanicsdsl.readthedocs.io/en/latest/index.html)**

---

## Contributing

We welcome contributions! See [CONTRIBUTING.md](CONTRIBUTING.md) for guidelines.

---

## License

MIT License — see [LICENSE](LICENSE) for details.

---

<p align="center">
  <em>Built with ❤️ for physicists, engineers, and curious minds.</em>
</p>
