Core Concepts¶

This page provides a high-level overview of MolPy's core concepts and architecture. For detailed explanations, see the Core Concepts section.

Core Data Structures¶

Block¶

A Block is a column-oriented, dict-like data structure used in MolPy to store tabular data efficiently. Each entry (column) is stored as an array, and all columns share the same row count. This makes Block ideal for representing structured datasets such as atomic coordinates, velocities, topology tables, or simulation frames.

In [1]:

import numpy as np

import molpy as mp

n_atoms = 3
n_dims = 3
block = mp.Block()
block["scale"] = np.ones(n_atoms)
block["vector"] = np.zeros((n_atoms, n_dims))

import numpy as np import molpy as mp n_atoms = 3 n_dims = 3 block = mp.Block() block["scale"] = np.ones(n_atoms) block["vector"] = np.zeros((n_atoms, n_dims))

Frame¶

A Frame represents a single snapshot of a molecular system. It contains:

• Multiple Block objects for different data groups (atoms, bonds, etc.)
• Metadata dictionary for storing additional information (like Box)
• Methods for manipulation and I/O

In [2]:

import molpy as mp

# Create a frame and add data using tuple syntax
frame = mp.Frame()
frame["atoms"] = block

# Store box in metadata
frame.metadata["box"] = mp.Box.cubic(10.0)

import molpy as mp # Create a frame and add data using tuple syntax frame = mp.Frame() frame["atoms"] = block # Store box in metadata frame.metadata["box"] = mp.Box.cubic(10.0)

Trajectory¶

A Trajectory is a sequence of Frame objects, representing a time series of molecular configurations. It supports:

• Lazy loading for memory efficiency
• Slicing and indexing
• Memory-mapped reading for large files

Molecule Graph¶

MolPy represents molecular structures using a graph-based data model, where molecules are modeled as graphs composed of nodes and edges.

Graph-based Molecule Representation¶

Entity represents a node in the molecular graph—an atom-like object that stores element, coordinates, and other properties in a lightweight dict-like form.

Link represents an edge in the molecular graph—a bond-like relationship connecting entities, also stored as a dict-like object with optional parameters such as order or force-field type.

Struct represents the molecular graph itself, containing collections of entities and links, providing basic topology, traversal, and editing operations.

Atomistic is a domain-specific subclass of Struct tailored for atomistic simulations. It standardizes atom, bond, angle, and dihedral management, enforces common molecular conventions, and serves as the main high-level structure used throughout MolPy.