MolFrame is a structural bioinformatics engine for macromolecular structures, trajectories, and derived scientific data.

It combines high-performance Rust kernels with native Python bindings and a columnar molecular representation shared across I/O, selection, geometry, chemistry, surfaces, validation, structural comparison, trajectories, and machine-learning workflows.

The guiding principle is simple:

Structural data is more than coordinates.

Alternate conformations, biological assemblies, insertion codes, identifier namespaces, missing atoms, and provenance can all change the interpretation of a result. MolFrame is designed to preserve that context throughout the analysis pipeline.

Why MolFrame?

Structural workflows often combine parsers, hierarchy libraries, array representations, trajectory packages, and specialized analysis tools.

Each conversion introduces another data model — and another opportunity to lose structural meaning.

MolFrame keeps the workflow inside one representation.

• One structural model — parse, query, analyze, compare, and export without translating between unrelated representations.
• Semantics-preserving I/O — retain alternate locations, insertion codes, author and label identifiers, assemblies, and format-specific information.
• Native performance — core parsing and analysis kernels are implemented in Rust with parallel and vectorized execution where appropriate.
• Zero-copy interoperability — expose coordinates directly to NumPy and columnar annotations through Apache Arrow.
• Explicit scientific context — analysis APIs can carry ambiguity, coverage, diagnostics, policy, and provenance instead of hiding important decisions behind defaults.
• Python and Rust — native interfaces over the same computational engine.
• Modular Rust API — use the complete engine or compile only the format and analysis domains an application requires.

Installation

Python

pip install molframe

import molframe

Rust

cargo add molframe

use molframe::prelude::*;

MolFrame is currently pre-1.0. Public APIs may evolve while the core contracts are finalized.

Quick start

Python

import molframe

structure = molframe.read("1ubq.cif")

print(structure.atom_count)
print(structure.chain_count)

coordinates = structure.coordinates
print(coordinates.shape)

structure.coordinates exposes coordinates as an N × 3 read-only float32 NumPy view without rebuilding the molecular structure in Python. A Selection.to_coordinates() call is intentionally named because a discontiguous selection must be materialized.

The same structure can be used directly for querying and analysis:

structure = molframe.read("1ubq.cif")

backbone = structure.select("name CA")
print(backbone.to_coordinates().shape)

Rust

use molframe::prelude::*;

fn main() -> Result<(), Box<dyn std::error::Error>> {
    let (structure, diagnostics) =
        molframe::read_with_diagnostics("1ubq.cif")?;

    println!(
        "{} atoms in {} chains",
        structure.atom_count(),
        structure.chain_count()
    );

    for diagnostic in diagnostics {
        eprintln!("{diagnostic}");
    }

    Ok(())
}

read_with_diagnostics preserves problems and ambiguities encountered while loading a structure instead of reducing parsing to a success/failure decision.

Workflow and data-movement contract

Workflow builds an immutable typed DAG with named inputs and outputs. Compile once, then reuse the CompiledWorkflow; compilation validates types and cycles, removes dead and common nodes, fixes deterministic execution order, plans value lifetimes, and estimates peak retained memory. Kernels keep their bounded internal parallelism while graph nodes run in stable topological order.

Logical and physical explanations label movement explicitly: Borrow aliases a live input, Adopt retains an owner without copying its payload, Decode converts encoded data, Copy duplicates native storage, and Materialize computes or gathers a new representation. Python follows the same rule: compatible contiguous arrays are borrowed for eager calls, non-contiguous arrays are rejected with an instruction to use numpy.ascontiguousarray, and values retained by a compiled workflow require the explicit copy=True choice.

Potentially large interaction results are native structure-of-arrays tables. Their columns are borrowed directly in Rust, reducer blocks append column by column, and Python arrays retain native owners. A Selection is structure-bound and zero-copy; Selection.to_coordinates() is the explicit gather operation.

One model from file to result

flowchart LR
    Input["PDB · mmCIF · BinaryCIF · ModelCIF · PQR · PDBQT"]

    Input --> Structure["MolFrame Structure"]

    Structure --> Query["Selection & Query"]
    Structure --> Geometry["Geometry & Spatial"]
    Structure --> Chemistry["Chemistry"]
    Structure --> Trajectory["Trajectories"]

    Query --> Analysis["Analysis"]
    Geometry --> Analysis
    Chemistry --> Analysis
    Trajectory --> Analysis

    Analysis --> Validation["Validation"]
    Analysis --> Compare["Structural Comparison"]
    Analysis --> Surface["Surfaces & Contacts"]
    Analysis --> ML["Scientific / ML Export"]

    Structure --> NumPy["NumPy"]
    Structure --> Arrow["Apache Arrow"]

All of these operations share the same underlying structural representation.

Formats are inputs and outputs. The model between them is the core of MolFrame.

Capabilities

Structural semantics

A molecular structure contains information that is easy to erase accidentally.

Consider an atom belonging to a residue with:

• an author-assigned residue number;
• a separate canonical identifier;
• an insertion code;
• multiple alternate conformations;
• partial occupancy;
• coordinates from one model;
• biological assembly context.

Reducing that structure prematurely to:

x, y, z, element

can preserve its geometry while losing the information required to interpret it correctly.

MolFrame keeps structural context alongside coordinates:

Structure
├── coordinates
├── model
├── chain
├── residue
├── atom
├── altloc
├── occupancy
├── identifiers
├── assembly context
└── provenance

Selections and analyses therefore operate on a representation that still understands what the coordinates mean.

Explicit scientific results

Many structural analyses depend on choices that are often implicit:

• Which model should be analyzed?
• Which biological assembly?
• Which alternate conformer?
• Which identifier namespace?
• What should happen when atoms are missing?
• How much of the requested structure was actually analyzable?

MolFrame's analysis architecture is designed to make such decisions inspectable.

An enriched analysis result can conceptually carry:

Analysis<T>
├── value
├── coverage
├── ambiguity
├── diagnostics
└── provenance

This allows the value and the conditions under which it was produced to travel together.

An analysis may also be indeterminate when the available structure does not support a scientifically defensible result.

Producing no answer is preferable to silently producing a misleading one.

Columnar by construction

MolFrame stores molecular information in a column-oriented representation rather than building the primary data model from individually allocated atom and residue objects.

This supports:

• contiguous coordinate storage;
• efficient scans and selections;
• compact identifiers;
• chunk-level statistics;
• parallel kernels;
• SIMD-friendly numeric operations;
• direct NumPy views;
• Arrow interoperability;
• efficient serialization and transfer.

Hierarchical access remains available as a view over the same structure:

for chain in structure.chains:
    for residue in chain.residues:
        print(chain.label, residue.name)

The hierarchy is an interface over the molecular data, not a second independent copy of it.

File formats

PDBx/mmCIF

mmCIF is treated as a first-class structural format rather than immediately reduced to a legacy PDB-shaped schema.

MolFrame's CIF infrastructure is designed to preserve categories beyond the core atomic structure, including extension data that should survive round trips.

BinaryCIF

BinaryCIF provides compact binary encoding for PDBx data and maps into the same structural representation.

Legacy PDB

Legacy fixed-column PDB remains widely used and is supported directly.

Writers treat format limits explicitly. Data that cannot be safely represented should produce an error rather than silently truncating scientifically meaningful fields.

ModelCIF, PQR, and PDBQT

Specialized structure formats enter the same model so downstream algorithms do not require separate representations for each source.

Zero-copy Python interoperability

The Python API is a native interface to the Rust engine rather than a reimplementation of its computational kernels.

structure = molframe.read("1ubq.cif")

xyz = structure.coordinates

Coordinate buffers can be exposed directly to NumPy-compatible code.

Columnar annotations can be represented through Apache Arrow, enabling efficient exchange with scientific and analytical Python tools without reconstructing a hierarchy of Python objects.

MolFrame is designed to integrate with the Python scientific ecosystem rather than replace it.

Query and selection

Selections are part of the computational model rather than string filters bolted onto individual algorithms.

A selection can describe structural concepts such as:

polymer
ligand
water
chain
residue range
element
spatial neighborhood
arbitrary predicate

The same selection semantics can then be reused across compatible analyses.

This prevents each algorithm from inventing its own interpretation of what constitutes the selected structure.

Textual, typed, and reusable queries

A query is compiled once into a typed plan and reused. Text and the typed builder produce the same plan, and the plan's fingerprint is its identity:

import molframe

structure = molframe.read("4hhb.cif")

text = molframe.Query("byres (within 5 of resname HEM) and protein")
typed = molframe.sel.residues_within(5.0, molframe.sel.residue("HEM")) & molframe.sel.protein()

structure.select(text)            # a compiled Query is evaluated directly
structure.select("chain A")       # text is compiled and evaluated
text.fingerprint                  # stable identity of the normalized plan

use molframe::{Query, QueryStructure, AnalysisPolicy};

let query = Query::compile("byres (within 5 of resname HEM) and protein")?;
let selected = structure.select_query(&query, &AnalysisPolicy::default())?;

Syntax errors carry the exact byte range of the offending token (with its line and column), so a caller embedding a query inside a larger text can point at it.

Named queries

A query can refer to a named definition with $name (or the longer group name). QueryAliases holds definitions and resolves a query into a closed query that mentions no name, by substituting typed plans — nothing is re-parsed and no atom is evaluated to do it:

aliases = molframe.QueryAliases()
aliases.define("heme", molframe.Query("resname HEM"))
aliases.define("pocket", molframe.Query("byres (within 5 of $heme) and protein"))

pocket = aliases.resolve(molframe.Query("$pocket"))
pocket.source        # canonical closed text: no names remain
pocket.references    # []
molframe.Query("$pocket and not $heme").references   # ['heme', 'pocket']

Definitions are live: redefining heme changes what $pocket resolves to. Resolution is deterministic, rejects unknown names (E4005), cycles such as a -> b -> a (E4006), and chains nested deeper than a fixed bound (E4007). A runtime Groups map — atoms already selected, supplied at evaluation time — remains available for group names that are meant to be evaluated as given.

Geometry and spatial analysis

MolFrame provides reusable kernels for common structural operations including:

• distances;
• angles and dihedrals;
• coordinate transforms;
• centroids and extents;
• radius of gyration;
• structural alignment;
• internal coordinates;
• spatial indexing;
• neighbor queries;
• contact analysis.

Numeric kernels operate directly over the underlying coordinate representation whenever possible.

Structural comparison

Comparison workflows use the same molecular identifiers and structure model as ordinary analysis.

This supports operations such as:

mapping
alignment
superposition
RMSD
local comparison
sequence-aware correspondence

without first converting structures into an unrelated comparison-specific representation.

Validation

Parsing answers:

Can this file be interpreted?

Validation asks:

Does the interpreted structure make sense?

MolFrame separates these concerns.

Validation can report structural inconsistencies, suspicious geometry, incomplete data, representation problems, and other findings without conflating them with parser failure.

Diagnostics remain machine-readable so applications can decide how to handle them.

Trajectories

Trajectory support extends the structural model across coordinate frames without redefining molecular identity at every timestep.

This enables analyses over:

frame sequences
coordinate evolution
time-dependent measurements
structural comparison
aggregated trajectory statistics

while keeping topology and coordinate data appropriately separated.

Command line

Common operations are also available from the command line:

molframe info 1ubq.cif

molframe convert input.pdb output.cif

molframe validate structure.cif

molframe measure structure.cif

molframe rmsd model-a.cif model-b.cif

The CLI uses the same parsing and computational engine as the library APIs.

Performance

Performance claims should be reproducible.

MolFrame includes benchmark infrastructure for:

• parsing;
• structural access;
• selections;
• geometry;
• spatial operations;
• analysis;
• serialization;
• Python-boundary operations.

The architecture emphasizes properties that scale well:

contiguous data
low allocation pressure
parallel execution
SIMD-friendly kernels
zero-copy boundaries
memory mapping where appropriate
feature-gated dependencies

Specific benchmark numbers belong with their dataset, hardware, software revision, and methodology rather than as context-free claims in this README.

Benchmark sources live beside the subsystem they measure in each crate's benches/ directory; deterministic allocation and resident-memory cases live in crates/molframe-resource-bench.

Rust features

The Rust facade is modular.

Applications can enable only the domains they require.

Feature areas include:

mmcif
bcif
modelcif
pdb

geometry
query
spatial
chemistry
crystal

surface
analysis
validation
compare
trajectory
sequence
interop
audit
motif

The default configuration enables mmCIF and PDB only. Applications opt into analysis domains individually, and full is available for complete builds.

Project status

MolFrame is under active development and has not reached 1.0.

The project distinguishes three different properties:

Implemented
The capability exists.

Validated
The behavior has the appropriate deterministic, golden, differential, or scientific evidence.

Stable
The public contract is expected to remain backwards compatible.

A feature being implemented does not automatically imply that it has reached the other two stages.

Pre-1.0 releases may contain breaking API changes while these contracts are finalized.

Development

Build the complete Rust workspace:

cargo build --workspace

Run the test suite:

cargo test --workspace

The repository also contains project-specific verification tooling for formatting, linting, packaging, bindings, scientific fixtures, and reproducibility checks.

See CONTRIBUTING.md for the development workflow.

Citation

If MolFrame contributes to published research, please cite the software.

Machine-readable citation metadata is provided in CITATION.cff.

License

MolFrame is released under the MIT License.

The bundled reference data keeps the licence of its upstream source, carried beside the data it covers: mendeleev's MIT notice in crates/molframe-chem/data/LICENSE.mendeleev, and spglib's BSD-3-Clause notice in crates/molframe-xtal/data/LICENSE.spglib.