How can I contribute to MatCraft?

We welcome contributions to the MatCraft open-source core. Whether you are fixing a bug, adding a domain plugin, improving documentation, or implementing a new feature, here is how to get started.

Getting Set Up

# Fork and clone the repository
git clone https://github.com/YOUR_USERNAME/matcraft.git
cd matcraft

# Create a virtual environment
python -m venv .venv
source .venv/bin/activate

# Install in development mode with all extras
pip install -e ".[dev,test,docs]"

# Install pre-commit hooks
pre-commit install

# Verify everything works
pytest

Development Workflow

1. Create a branch from main:

``bash git checkout -b feature/my-new-feature ``

1. Make your changes with tests. We maintain >90% test coverage.

1. Run the test suite:

```bash # Run all tests pytest

# Run specific test file pytest tests/test_surrogate_mlp.py

# Run with coverage pytest —cov=materia —cov-report=html ```

1. Run linting and formatting:

``bash # These run automatically via pre-commit hooks ruff check src/ tests/ ruff format src/ tests/ mypy src/materia/ ``

1. Submit a pull request against main with a clear description of your changes.

Contribution Areas

Domain Plugins (Most Welcome)

Adding new material domain plugins is one of the most impactful contributions. A domain plugin consists of:

• A components.yaml file defining the parameter schema
• A physics.py file with approximate evaluation models
• Tests in tests/test_plugin_<domain>.py
• Documentation in docs/domains/<domain>.md

See src/materia/plugins/water/ for a complete example.

Surrogate Models

We are interested in alternative surrogate architectures:

• Gaussian Process surrogates
• Graph Neural Network surrogates (for crystal structures)
• Ensemble methods
• Transfer learning across domains

Optimization Algorithms

Beyond CMA-ES, we would welcome implementations of:

• Differential Evolution
• Particle Swarm Optimization
• Multi-objective evolutionary algorithms (NSGA-II, MOEA/D)

Bug Fixes and Improvements

Check the GitHub Issues page for open bugs and feature requests labeled good-first-issue or help-wanted.

Code Style

• Python code follows PEP 8, enforced by Ruff.
• Type hints are required for all public APIs.
• Docstrings follow the NumPy style.
• Tests use pytest with fixtures defined in conftest.py.

Contributor License Agreement

All contributors must sign a CLA before their first pull request can be merged. The CLA bot will automatically comment on your PR with instructions. The CLA allows us to distribute your contributions under the Apache 2.0 license.

Recognition

All contributors are listed in the CONTRIBUTORS.md file and acknowledged in release notes. Significant contributors may be invited to join the core maintainer team.