Thank you for your interest in contributing to MICOM! We welcome contributions ranging from bug fixes and documentation improvements to new simulation algorithms and visualization features.
To maintain a high standard of code quality, numerical stability, and maintainability, please review the guidelines below before submitting issues or pull requests.
For an overview of the system architecture, mathematical principles, and component design, refer to DESIGN.md.
We are committed to providing a friendly, safe, and welcoming environment for all contributors. Please treat others with respect and constructive feedback throughout all discussions, issues, and code reviews.
- Supported Python Versions: MICOM supports CPython 3.11 through 3.14. CI tests all four versions across Linux, macOS, and Windows.
- Linear/Quadratic Programming Solvers:
- MICOM relies on LP and QP solvers via
optlang. - CPLEX is not a runtime dependency. It is installed by the test dependency group; its PyPI community edition is sufficient for the test suite. Users working with larger models can configure a separately licensed CPLEX or Gurobi installation.
- MICOM relies on LP and QP solvers via
-
Fork and clone the repository:
git clone https://github.com/<your-username>/micom.git cd micom git checkout -b feature/my-new-feature
-
Install uv using the official installation instructions.
-
Create the project environment and install development dependencies:
uv sync --all-groups
This installs MICOM in editable mode along with CPLEX and the test, lint, and documentation tools.
---
## 3. Code Standards and Conventions
To preserve codebase consistency across all modules, all contributions must adhere to the following standards:
### 3.1 Code Style and Formatting
- **Formatting Tool**: Ruff formats code with a maximum line length of **88 characters**:
```bash
uv run ruff format micom tests
- Linter: Ruff checks for Python errors and undefined names:
uv run ruff check .
MICOM follows the NumPy docstring convention. Every public function, class, and method should have a comprehensive docstring containing:
- A one-line summary followed by an optional detailed description.
Parameters: Each parameter typed, followed by a clear description.Returns: The return type and description (orNothing/None).Raises: Any specific exceptions thrown.NotesorReferences: Mathematical details, publications, or algorithmic nuances where appropriate.
def cooperative_tradeoff(
self,
min_growth: float = 0.0,
fraction: float = 1.0,
fluxes: bool = False,
pfba: bool = False,
atol: float = None,
rtol: float = None,
) -> Union[CommunitySolution, pd.Series]:
"""Find the best tradeoff between community and individual growth.
Finds the set of growth rates which maintain a particular community
growth and spread growth across all taxa as evenly as possible.
This is achieved by minimizing the L2 norm of individual growth rates
subject to a minimum community growth constraint.
Parameters
----------
min_growth : float or array-like, optional
The minimal growth rate required for each individual taxon.
fraction : float or list of floats in [0, 1]
The minimum percentage of the community growth rate that must be
maintained. For instance, 0.8 preserves 80% of maximal community growth.
fluxes : bool, optional
Whether to calculate and return all reaction fluxes.
pfba : bool, optional
Whether to obtain fluxes by parsimonious FBA rather than classical FBA.
atol : float, optional
Absolute tolerance for the growth rates. If None, uses solver feasibility.
rtol : float, optional
Relative tolerance for the growth rates. If None, uses solver feasibility.
Returns
-------
micom.CommunitySolution or pandas.Series of CommunitySolution
The solution object after optimization, or a series of solutions if
multiple fraction values were passed.
Raises
------
OptimizationError
If no feasible solution can be found within the given tolerances.
"""- Use standard Python type hints (
typing.Union,typing.Optional,typing.Self,typing.Dict,pathlib.Path). - Path Coercion: Whenever a function or method accepts file system paths, decorate it with
@pathify. This decorator automatically converts strings oros.PathLikearguments intopathlib.Pathinstances:from micom.types import pathify from pathlib import Path from typing import Union @pathify def load_custom_medium(file_path: Union[str, Path]) -> pd.DataFrame: # file_path is guaranteed to be a Path object return pd.read_csv(file_path)
- Configuration Models: All settings in
micom.batch.configurationmust be validated via Pydantic v2 (pydantic.BaseModel) with explicit type annotations, default factories, and docstrings.
Before contributing code, please ensure you respect the separation of concerns defined in DESIGN.md:
- Maintain the Clean Separation between APIs:
Communityis a single-sample in-memory COBRA model subclassingcobra.Model. Do not add multi-sample batch orchestration logic directly intoCommunity.Batchorchestrates multi-sample cohorts, delegating single-sample builds and simulations to worker tasks. Do not manipulate reaction equations or optlang expressions directly inBatch.
- Prevent Solver Memory Leaks in Parallel Workflows:
- All multi-sample parallel routines must use
workflow, which enforcesmultiprocessing.get_context("spawn").Pool(maxtasksperchild=1). Never use shared-memory multiprocessing or unconstrained threads that pooloptlangsolver pointers across tasks.
- All multi-sample parallel routines must use
- Use Standardized Result Containers:
- Batch simulation routines must return
GrowthResults(growth_rates,exchanges,annotations).
- Batch simulation routines must return
- Preserve Validation Invariants:
- Input taxonomy tables must pass
check_taxonomy(df). - Input media tables must pass
check_medium(df).
- Input taxonomy tables must pass
MICOM has extensive test coverage across Linux, macOS, and Windows. Every new feature or bug fix must include corresponding tests.
Run tests locally using uv run pytest:
# Run all tests
uv run pytest tests/
# Run tests with coverage report
uv run pytest --cov=micom --cov-report=term-missing tests/
# Run a specific test module
uv run pytest tests/test_batch.py- Single Model & Optimization Tests: Add to
tests/test_community.py,tests/test_tradeoff.py,tests/test_optimizations.py. - Batch API & Configuration Tests: Add to
tests/test_batch.py,tests/test_config.py,tests/test_results.py. - Media & Database Tests: Add to
tests/test_media.py,tests/test_db_media.py,tests/test_db.py. - Host & Interaction Tests: Add to
tests/test_host.py,tests/test_interaction.py.
When writing assertions for flux rates or growth rates, always use pytest.approx or compare against atol/rtol tolerances (e.g. assert growth_rate == pytest.approx(0.5, abs=1e-5)), as floating-point results may vary slightly across solvers and architectures.
Documentation is generated using Sphinx, Furo, and nbsphinx from markdown, reStructuredText, and Jupyter notebooks in docs/source/.
uv sync --all-groups
uv run make -C docs htmlThe compiled HTML will be placed in docs/_build/html/index.html (or docs/index.html).
When adding a new feature or tutorial:
- Provide clear explanatory prose and code examples in a corresponding Jupyter notebook under
docs/source/. - Ensure notebooks are executed and can run end-to-end without unhandled errors.
The canonical package version is project.version in pyproject.toml. Bump it with uv before preparing a release:
uv version --bump patch
# Use --bump minor or --bump major instead when appropriate.micom.__version__ reads the installed distribution metadata, so no second version string needs to be updated.
- Sync with Main:
Ensure your branch is up to date with the latest
mainbranch:git fetch origin git rebase origin/main
- Pre-PR Quality Checklist:
- All tests pass locally (
uv run pytest tests/). - Code is formatted (
uv run ruff format --check micom tests). - Linter passes with no errors (
uv run ruff check .). - New public functions and classes have NumPy-formatted docstrings and type hints.
- If user-facing changes were made, add a brief bullet to
NEWS.md.
- All tests pass locally (
- Open the Pull Request:
- Provide a clear, descriptive PR title and summary explaining why the change is needed and what was altered.
- Link any related issues (e.g.,
Fixes #123). - CI workflows will automatically run the test suite across operating systems and Python versions. Verify that all status checks turn green.
If you have questions about whether an idea fits into MICOM, or need guidance on solver integration:
- Open a topic in GitHub Discussions.
- Join the cobrapy community on Gitter.
- For QIIME 2 plugin questions, visit the QIIME 2 Community Forum.