Developer Guide¶

This guide addresses contributors and library developers working on MolPy as a research software library. It is organized around what you came here to do:

• Fix a bug or land a first PR → Development Setup, then Contributing Workflow and Testing
• Add an analysis operation, file format, or tool integration → the plug-in recipes under Extending MolPy; no core changes required
• Change typification, the data model, or force-field internals → read the Architecture Overview first, open a GitHub issue to discuss, then follow Extending Typifiers, Extending the Data Model, or Extending the Force Field
• Understand how MolPy is put together → Architecture Overview and molrs Backend
• Cut a release → Release Process

Canonical field names and topology keys live in the Naming Conventions appendix of the Tutorials.

Contributing¶

Day-to-day development practices:

• Development Setup — repository cloning, editable installation, building molrs from source, and test execution
• Contributing Workflow — the pull request workflow, commit message conventions, and the pre-commit hook suite
• Coding Style — identifier style, formatting requirements, and the mutation contract
• Testing — pytest conventions, test markers, coverage requirements, and the distinction between local and external tests
• Release Process — the shared molpy/molrs minor line and CI-driven package publication

Architecture¶

The design context that the extension recipes assume:

• Architecture Overview — module responsibilities, the graph and tabular layers, field-name translation, the mutation contract, and the performance model of assembly
• molrs Backend — how the Rust column store and compute kernels surface in Python: boxes, neighbor lists, RDF, and the analysis catalog

Extending MolPy¶

Ordered from plug-in interfaces (implement a subclass, register a handler) to core internals (discuss in a GitHub issue before implementation):

• Adding a Compute Operation — the Compute protocol for reusable analysis operations
• Adding an I/O Format — native read_X / write_X doors re-exported on mp.io, and when molpy adds a function of its own
• Adding a Wrapper or Adapter — subprocess wrapper conventions and in-memory adapter patterns
• Extending Typifiers — the match → Match contract, matcher boundaries, and where a typifier lives (native vs. tool-driven)
• Extending the Data Model — why a new node or relation kind is a molrs change, and what Python may add on top
• Extending the Force Field — molrs kernels, styles by name, and the writer arms that export them

Issue Tracking and Discussion¶

• Bug reports and feature requests: https://github.com/MolCrafts/molpy/issues
• Design discussions: https://github.com/MolCrafts/molpy/discussions