Contributing to MechanicsDSL

Thank you for your interest in contributing to MechanicsDSL! This document provides guidelines for contributing to the project.

Getting Started 

Development Setup 

Fork the repository on GitHub

Clone your fork:

git clone https://github.com/YOUR_USERNAME/mechanicsdsl.git
cd mechanicsdsl

Create a virtual environment:

python -m venv venv
source venv/bin/activate  # Linux/Mac
venv\Scripts\activate     # Windows

Install in development mode:
```
pip install -e ".[dev]"
```
Verify tests pass:
```
pytest tests/
```

Code Style 

Python Style 

Follow PEP 8 guidelines
Use type hints for public APIs
Maximum line length: 100 characters
Use docstrings for all public functions/classes

def compute_energy(solution: dict, parameters: dict) -> np.ndarray:
    """
    Compute total energy from simulation solution.

    Args:
        solution: Simulation result dictionary containing 't' and 'y'
        parameters: Physical parameters dictionary

    Returns:
        Array of total energy values at each time point

    Raises:
        ValueError: If solution format is invalid
    """
    ...

Docstrings 

Use Google-style docstrings:

def function(arg1: str, arg2: int = 0) -> bool:
    """Short description.

    Longer description if needed, explaining the purpose
    and any important details.

    Args:
        arg1: Description of first argument.
        arg2: Description of second argument with default.

    Returns:
        Description of return value.

    Raises:
        ValueError: When arg1 is empty.
        TypeError: When arg2 is not an integer.

    Example:
        >>> function("test", 42)
        True
    """

Making Changes 

Workflow 

Create a feature branch:

git checkout -b feature/your-feature-name

Make your changes
Add tests for new functionality
Ensure all tests pass
Update documentation if needed

Commit with descriptive messages:

git commit -m "Add: New constraint handling for rolling contacts"

Push and create a Pull Request

Commit Messages 

Use descriptive commit messages with a prefix:

Add: New features
Fix: Bug fixes
Update: Updates to existing features
Docs: Documentation changes
Test: Test additions/changes
Refactor: Code refactoring
Perf: Performance improvements

Testing 

Running Tests 

# Run all tests
pytest tests/

# Run with coverage
pytest tests/ --cov=mechanics_dsl

# Run specific test file
pytest tests/test_parser.py

# Run with verbose output
pytest tests/ -v

Writing Tests 

Place tests in the tests/ directory:

# tests/test_my_feature.py
import pytest
from mechanics_dsl import PhysicsCompiler

class TestMyFeature:
    def test_basic_functionality(self):
        compiler = PhysicsCompiler()
        result = compiler.compile_dsl(source)
        assert result['success']

    def test_error_handling(self):
        with pytest.raises(ValueError):
            compiler.compile_dsl("invalid source")

Documentation 

Building Docs 

cd docs
make html

# Open in browser
open _build/html/index.html  # Mac
start _build/html/index.html  # Windows

Documentation Style 

Use reStructuredText format
Include code examples
Add cross-references to related sections
Keep explanations clear and concise

Adding New Features 

Physics Domains 

To add a new physics domain:

Create module in mechanics_dsl/domains/
Inherit from PhysicsDomain
Implement required abstract methods
Add tests
Add documentation

# mechanics_dsl/domains/quantum/schrodinger.py
from ..base import PhysicsDomain

class SchrodingerDomain(PhysicsDomain):
    """Quantum mechanics using Schrödinger equation."""

    def define_lagrangian(self):
        raise NotImplementedError("Quantum uses Hamiltonian")

    def define_hamiltonian(self):
        # H = -ℏ²/2m ∇² + V
        ...

Code Generation Backends 

To add a new code generation target:

Create module in mechanics_dsl/codegen/
Inherit from CodeGenerator
Implement required methods
Add template files if needed

Reporting Issues 

Bug Reports 

Include:

MechanicsDSL version (python -c "import mechanics_dsl; print(mechanics_dsl.__version__)"
Python version
Operating system
Minimal reproducible example
Full error traceback

Feature Requests 

Include:

Clear description of the feature
Use case / motivation
Any relevant references (papers, algorithms)

Code of Conduct 

Be respectful and inclusive
Focus on constructive feedback
Welcome newcomers
Report inappropriate behavior to maintainers

License 

By contributing, you agree that your contributions will be licensed under the MIT License.

Thank you for contributing to MechanicsDSL!