Skip to content

Tutorials

Welcome to the MolPy Tutorials! These hands-on, example-driven guides help you learn MolPy by doing. Each tutorial is a Jupyter notebook you can run interactively to master specific concepts and workflows.

How to Use These Tutorials

Learning path:

  • 📘 Foundational – Start here if you're new to MolPy
  • 🔧 Practical – Learn by running real examples
  • 🎯 Task-focused – Each tutorial solves a specific problem
  • 🔗 Progressive – Tutorials build on each other

Prerequisites: Basic Python knowledge and familiarity with molecular modeling concepts.

Getting Started

If you haven't already:

  1. 📦 Install MolPy – Set up your environment
  2. 🚀 Quickstart Guide – 5-minute introduction
  3. 📚 Core Concepts – Understand the data model

Tutorial Categories

🏗️ Core Data Structures

Master MolPy's fundamental building blocks before diving into advanced features.

Block

Start here if: You need to understand MolPy’s columnar table container.

What you'll learn: 

atoms = mp.Block({"id": [1, 2], "x": [0.0, 1.0]})
atoms["x"]
atoms[0:1]

Frame

Start here if: You need to keep multiple tables (atoms/bonds/…) + metadata together.

What you'll learn: 

frame = mp.Frame(blocks={"atoms": {"x": [0, 1]}})
frame["atoms"]["x"]
frame.metadata["timestep"] = 0

Molecular Graph

Start here if: You need create or edit molecule.

What you'll learn:

atoms = mp.Atomistic()
C = atoms.def_atom(symbol="C", xyz=[0, 0, 0])
O = atoms.def_atom(symbol="O", xyz=[1.2, 0, 0])
atoms.def_bond(C, O, order=2)

Note: See Parser and Polymer SMILES user guides for detailed molecular construction.

Box

Start here if: You need to define simulation boundaries or work with periodic systems.

Key concepts: Cell dimensions, PBC wrapping, lattice vectors

box = mp.Box.cubic(length=10.0, origin=[0, 0, 0], pbc=[True, True, False])

Topology

Start here if: You're working with abstract molecular graph or graph algorithms.

from igraph import Graph
topo: Graph = mp.Atomistic().get_topo()

Force Field

Start here if: You're manupulating force field parameters

ff = mp.ForceField()
atype = ff.def_style(mp.AtomStyle("full"))
atype.def_type("C", mass=12.01, charge=0.0)

Trajectory

Start here if: You need to analyze simulation results or process large trajectory files.

traj = mp.Trajectory.read_lammps_trajectory("traj.lammpstrj")
for frame in traj:
    print(frame.metadata["temperature"])

🛠️ Building & Construction

Learn to construct molecular systems from scratch.

Crystal Builder

Generate crystal structures and lattices

  • Building crystal unit cells
  • Common lattice types (FCC, BCC, HCP, diamond)
  • Supercell generation
  • Custom lattice parameters

Start here if: You're working with crystalline materials or periodic systems.

Example use cases: - Metal nanoparticles - Mineral surfaces - Semiconductor structures

Quick example: 

from molpy.builder.crystal import fcc
crystal = fcc(element="Cu", a=3.61, n_cells=(3, 3, 3))

Note: See Builder user guide for detailed construction workflows.

⚗️ Chemistry & Reactions

Work with chemical structures and transformations.

Selector

Select and filter molecular substructures

  • Pattern-based selection (SMARTS)
  • Atom and bond selectors
  • Combining selection criteria
  • Integration with reactions

Start here if: You need to identify specific atoms or groups for reactions or analysis.

Use cases: - Finding reactive sites - Selecting functional groups - Filtering by properties

Pattern: 

selector = SMARTSSelector("[OH]")  # Find hydroxyl groups
selected = selector(atomistic)

🔧 Advanced Features

Extend MolPy with custom functionality.

External Tools: Wrappers & Adapters

Learn MolPy's external integration layers

  • molpy.wrapper: subprocess wrappers for external binaries/CLIs
  • molpy.adapter: data + file-artifact adapters (no subprocess execution)
  • Optional RDKit in-memory adapter (guarded)

Start here if: You want to integrate AmberTools / RDKit-style tooling while keeping MolPy core structures stable.

Learning Paths

Path 1: Complete Beginner

Goal: Learn MolPy from scratch

1. Frame & Block -> Understand data structures
2. Box -> Learn about simulation cells
3. Topology -> Master molecular connectivity
4. Force Field -> Prepare for simulation

Path 2: Simulation Setup

Goal: Prepare systems for MD simulations

1. Box -> Define simulation boundaries
2. Crystal Builder OR import structure
3. Molecular Graph -> Edit molecule manually
4. Force Field -> Assign types
5. IO modules -> Export for simulation

Path 3: Trajectory Analysis

Goal: Analyze simulation results

1. Frame & Block -> Understand data format
2. Trajectory -> Learn trajectory handling
3. Analysis with Compute module

Running the Tutorials

What's Next?

After completing tutorials:

  1. 📖 User Guide – Comprehensive module documentation

  2. Deeper coverage of each module

  3. Production workflow patterns

  4. Best practices and optimization tips

  5. 🔬 API Reference – Complete function documentation

  6. Full API specifications

  7. Parameter details

  8. Return value documentation

  9. 🛠️ Developer Guide – Contribute to MolPy

  10. Development setup

  11. Coding standards
  12. Creating custom modules

Need Help?

  • 💬 GitHub Discussions – Ask questions
  • 🐛 Issues – Report problems
  • 📧 Email: support@molcrafts.org
  • ❓ FAQ – Common questions

Happy learning! 🧪✨