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 installThe dev environment includes testing and linting tools. Run tests with:
pixi run -e dev testWithout 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)
"""
passTesting
Write tests for all new code:
pytest mdfactory/tests/Check coverage:
pytest --cov=mdfactory --cov-report=htmlSee Testing for details.
Workflow
Fork the repository
Create a feature branch:
git checkout -b feature/my-featureMake changes and write tests
Format and lint code:
ruff format .
ruff check .Run tests:
pixi run -e dev testOr without pixi:
pytestCommit with clear message:
git commit -m "Add support for NAMD engine"Push to your fork:
git push origin feature/my-featureOpen a pull request
Pull request guidelines
Title format
Use clear, descriptive titles:
Add NAMD engine supportFix bilayer builder box size calculationUpdate 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 #123Checklist
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-featureAdding documentation
Update docs for new features:
cd docs
bun run devAdd MDX files in docs/content/docs/:
---
title: New Feature
description: Description of the feature
---
## Usage
Explain how to use the feature...Project structure
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
