MDFactoryMDFactory
Developer Guide

Contributing

How to contribute to MDFactory

Contributions to MDFactory are welcome. Here's how to get started.

Development setup

Clone and install in development mode:

With pixi (recommended):

git clone https://github.com/emdgroup/mdfactory.git
cd mdfactory
pixi install

The dev environment includes testing and linting tools. Run tests with:

pixi run -e dev test

Without pixi:

git clone https://github.com/emdgroup/mdfactory.git
cd mdfactory
conda create -n mdfactory -c conda-forge python rdkit \
    openff-toolkit openff-interchange openff-nagl openff-units openmm
conda activate mdfactory
pip install -e .[dev]

Code style

MDFactory uses Ruff for linting and formatting:

ruff format .
ruff check .

Fix auto-fixable lint issues:

ruff check --fix .

Docstrings

All functions must have numpydoc-compliant docstrings:

def build_system(config, molecules):
    """
    Build a simulation system from configuration and molecules.

    Parameters
    ----------
    config : dict
        System configuration with box_size, engine, etc.
    molecules : list of dict
        Molecule specifications with SMILES and counts.

    Returns
    -------
    positions : ndarray
        Molecule positions in the simulation box.

    Raises
    ------
    ValueError
        If box_size is negative or molecules list is empty.

    Examples
    --------
    >>> config = {"box_size": [3.0, 3.0, 3.0]}
    >>> molecules = [{"smiles": "O", "count": 100}]
    >>> positions = build_system(config, molecules)
    """
    pass

Testing

Write tests for all new code:

pytest mdfactory/tests/

Check coverage:

pytest --cov=mdfactory --cov-report=html

See Testing for details.

Workflow

Fork the repository

Create a feature branch:

git checkout -b feature/my-feature

Make changes and write tests

Format and lint code:

ruff format .
ruff check .

Run tests:

pixi run -e dev test

Or without pixi:

pytest

Commit with clear message:

git commit -m "Add support for NAMD engine"

Push to your fork:

git push origin feature/my-feature

Open a pull request

Pull request guidelines

Title format

Use clear, descriptive titles:

  • Add NAMD engine support
  • Fix bilayer builder box size calculation
  • Update GROMACS input file generation

Description

Include:

  • What the PR changes
  • Why the change is needed
  • How to test the changes
  • Related issues (if any)

Example:

## Changes
- Implements NAMDEngine class
- Adds PSF topology generation
- Updates engine registry

## Testing
- Added test_namd_engine.py
- All existing tests pass
- Tested with sample protein system

Closes #123

Checklist

Before submitting:

  • Tests pass locally
  • Code is formatted with Ruff
  • Docstrings added for new functions
  • Documentation updated if needed
  • No secrets or credentials in code

Code review

Maintainers will review your PR. Address feedback by:

# Make changes
git add .
git commit -m "Address review feedback"
git push origin feature/my-feature

Adding documentation

Update docs for new features:

cd docs
bun run dev

Add MDX files in docs/content/docs/:

---
title: New Feature
description: Description of the feature
---

## Usage

Explain how to use the feature...

Project structure

README.md
pyproject.toml

Common tasks

Add a new engine

Create mdfactory/simulation/my_engine.py

Implement MDEngineInterface

Register in mdfactory/simulation/__init__.py

Add tests in mdfactory/tests/test_engines.py

Update docs in docs/content/docs/developer-guide/extending-engines.mdx

Add a new builder

Create mdfactory/setup/my_builder.py

Implement SystemBuilderInterface

Register in mdfactory/setup/__init__.py

Add tests in mdfactory/tests/test_builders.py

Update docs in docs/content/docs/developer-guide/custom-builders.mdx

Fix a bug

Write a failing test that reproduces the bug

Fix the bug

Verify test now passes

Submit PR with test and fix

License

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

Getting help

Questions about contributing:

  • Open an issue on GitHub
  • Contact the development team
  • Check existing issues and PRs

Recognition

Contributors are acknowledged in:

  • Release notes
  • Contributors list
  • Documentation credits

Next steps

On this page