Metadata-Version: 2.4
Name: mechanicsdsl-core
Version: 1.5.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
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: C++
Classifier: License :: OSI Approved :: MIT License
Classifier: Topic :: Scientific/Engineering :: Physics
Classifier: Topic :: Software Development :: Compilers
Requires-Python: >=3.8
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
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: 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"
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=examples/notebooks">
 <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 |
| **Fluid Dynamics** | Built-in SPH solver for dam breaks, waves, and liquid physics |
| **High Performance** | Generates optimized C++, OpenMP, and WebAssembly code |
| **Rich Visualization** | Phase space plots, energy analysis, and smooth animations |
| **Research Ready** | Validated against analytical solutions and conservation laws |

---

## Installation

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

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

---

## 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)
```

## 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

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

| 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>
