MolPy

a LLM-ready toolkit for building molecular systems.

Quick Start GitHub

---

Features

• LLM-Friendly

  ---

  Stateless functions, explicit types, zero global state. Every parameter is documented and visible, making it trivial for AI agents to read, understand, and generate correct code.

• Extensible

  ---

  Build custom workflows by composing functions and data structures. No inheritance hierarchies to navigate, just pure functions you can mix and match.

• Interoperable

  ---

  Native adapters for industry-standard tools: AmberTools, LAMMPS, OpenMM, Packmol, RDKit. One-function export to simulation engines or analysis pipelines.

• Modular Architecture

  ---

  Organized into domain-specific modules (builder, parser, typifier, adapter) around a unified Frame/Block data model. Use only what you need.

• Flexible Structures

  ---

  Lightweight Frame for single configurations, hierarchical Block for composed systems, memory-mapped Trajectory for multi-million atom simulations.

• Force-Field System

  ---

  Rule-based atom typing with SMARTS/SMIRKS patterns. Store, validate, and export force field parameters to any simulation engine with full provenance tracking.

---

Why MolPy?

MolPy is designed for researchers and engineers who need reliable, transparent, and composable molecular modeling workflows. Whether you're building simulation systems, designing force fields, or integrating ML/AI pipelines, MolPy provides the building blocks you need.

• Typical Use Cases

  ---

  • System preparation – build polymer melts, solvated proteins, or crystal interfaces
  • Force field development – define custom atom types with SMARTS/SMIRKS patterns
  • Simulation workflows – export to LAMMPS, OpenMM, or GROMACS with one function call
  • LLM-driven research – let AI agents write and run molecular modeling scripts

• Design Highlights

  ---

  • No global state – all functions are pure and testable
  • Explicit over implicit – every parameter is visible and documented
  • Composition over inheritance – mix and match components freely
  • Memory efficiency – lazy loading and memory-mapped trajectories for large systems

• When to Choose MolPy

  ---

  • You need type-safe APIs for LLM integration or code generation
  • You want full control without framework lock-in
  • You're building custom workflows that don't fit traditional GUI tools
  • You need interoperability between multiple simulation engines

---

Quick Links

Documentation

New to MolPy? Start with our Quick Start. Explore comprehensive guides in our User Guide and Tutorials with runnable notebooks and end-to-end examples.

API Reference

Detailed API documentation is available in the API Reference section.

Need Help?

Check out our FAQ or open an issue on GitHub.

---

Comprehensive Documentation

MolPy provides a growing collection of runnable Jupyter notebooks alongside generated API documentation.

• Runnable Notebooks

  ---

  Practical examples across the core modules: Parser, Reacter, Builder, Typifier, IO, Adapter, Potential, and more.

• :wrapped_gift:{ .lg .middle } Extensive API Coverage

  ---

  Public APIs are documented with parameters, return values, and usage examples.

• Architecture Guides

  ---

  Developer documentation covering recipe system, design patterns, IR principles, and contribution guidelines.

Explore the User Guide →

---

Roadmap

Core Foundations

• Stabilize core data structures (Frame, Block, Box, Trajectory)
• Unify topology representation (bonds/angles/dihedrals)
• Improve I/O layer (XYZ, PDB, LAMMPS DATA)
• Strengthen typing, doctests, and basic documentation

Modeling & Construction

• General lattice + crystal builder (SC/BCC/FCC/HCP + regions)
• Basic molecular builders (monomers, ports, polymer assembly)
• System assembly utilities (packing, placement, initialization)
• Core editing tools (add/remove atoms, merge fragments, simple reactions)

Force Fields & Typing

• Force field container (atom types + bonded parameters)
• Typifier system (rule-based SMARTS-style typing)
• Parameter assignment and export for external engines
• Validation / consistency tools for typed systems

Compute & Analysis

• Unified Compute + Result abstraction
• Common analysis functions (RDF, MSD, basic time series)
• Optional shared context (neighbor lists, box info)
• Export analysis results to arrays / DataFrames

Performance & User Experience

• Rust backend for performance-critical operations
• Visualization integration with molvis

---

Ecosystem

• MolVis — Production-level visualization with WebGL acceleration and real-time manipulation
• MolRS — Rust backend for performance-critical operations

MolPy is the core Python library in the MolCrafts ecosystem. MolVis provides high-performance 3D visualization, while MolRS offers compiled speed for compute-intensive tasks. All three projects share a unified data model and can be used independently or together.

---

Community & Contributing

We welcome contributions from researchers, developers, and users. There are three main ways to get involved:

Contribute Code

Found a bug or have an idea for improvement? Read the Contributing Guide and submit a pull request on GitHub.

Share & Discuss

Built something with MolPy or want to discuss workflows, design choices, or publications? Join the conversation in Discussions.

Get Help & Request Features

Need help or missing a feature? Start with the FAQ, then open an issue or proposal on GitHub Issues or Discussions.

---

Dependencies

• numpy — Numerical computing
• python-igraph — Graph analysis
• lark — SMARTS/SMILES parsing
• h5py - Serialization

---

License

This project is licensed under the BSD-3-Clause License. See LICENSE for details.