Python API index
Guide to the main MolFrame Python entry points and their native contracts.
This guide lists the main entry points of the supported Python facade. The complete typed surface is maintained in the package’s handwritten .pyi files and checked against native registration. Start with the linked guides for examples and scientific interpretation.
Root functions
| API | Purpose |
|---|---|
read(source, *, name=None, format=None, options=None, context=None) | Read a path, path-like value, or bytes into a Structure. |
Identifier acquisition is not currently part of the Python facade. The verified boundary is local paths or caller-supplied bytes through read(). The Rust adapters expose a typed unavailable-provider diagnostic rather than guessing a remote URL when no authoritative identifier manifest and checksum are configured. See Structures for the distinction between loading and acquisition.
Structure and hierarchy
| API | Purpose |
|---|---|
Structure | Root object: counts, hierarchy collections, coordinates, select(), and edit(). |
Models / Model | Indexable model collection and an individual model. |
Chains / Chain | Indexable chain collection and an individual chain with residues. |
Residues / Residue | Indexable residue collection and an individual residue with atoms. |
Atoms / Atom | Indexable atom collection and an atom's index, name, element, and coordinate. |
Collections support len() and integer indexing. Negative indexes follow Python collection conventions. See Structures.
Selection and input objects
| API | Purpose |
|---|---|
Selection | Atom indices, stale-selection check, model-specific coordinates, and ` |
Query | Compiled selection text with source, stable fingerprint, select(), and query &, ` |
QueryError | Raised by a query that cannot run; a ValueError whose message quotes and underlines the query. |
QueryWarning | Warned by a query that runs but is probably not what was meant; a UserWarning. |
Reader | Read named in-memory bytes; exposes byte_length. |
StructureEditor | Rename a chain by hierarchy index, then finish() a new structure. |
See Selecting atoms and Reading bytes and editing structures.
Analysis and interoperability
| Module or object | Public entry points |
|---|---|
molframe.geometry | centroid, distance_matrix, rmsd, internal_coordinates, place_atom |
molframe.analysis | atom_contacts, contacts, hydrogen_bonds, salt_bridges, dssp (needs no role profile: amino-acid residues take the built-in backbone roles, and roles you apply are never overridden) |
molframe.validation | clashes |
molframe.surface | sasa, lee_richards, cavities, surface_points, surface_points_at_density, solvent_excluded_surface (a Mesh), buried_surface, buried_solvent_excluded_surface, atom_depths; Mesh carries components, curvatures, edge distances, patches and OBJ output |
molframe.compare | tm_score, gdt_ts, gdt_ha, weighted_rmsd, lddt, dockq, qs_score and their mapped forms, ce_align, contact_areas, cad_score, contact_similarity, assign_chains, map_sequence_to_structure |
molframe.spatial | neighbor_pairs |
molframe.sequence | align, Scoring, parse_fasta, write_fasta, kmer_counts |
molframe.chemistry | element, vdw_radius, vdw_radii, annotate, Molecule, read_sdf, read_mol, write_sdf, molecule, smarts (plus charges, carbohydrates and polymer roles) |
molframe.motif | evaluate, MotifReport, MotifEvaluation, ConstraintResult |
molframe.crystal | UnitCell, SpaceGroup (by name, Hall symbol or type; its SymmetryOperations), space_group, structure_factors, ResolutionBins, normalizers, reduce_cell, assemblies, DensityMap and read_mrc, ReflectionTable and read_mtz |
molframe.trajectory | read, rmsd, Trajectory; ensemble analyses over (frames, atoms, 3) arrays: pairwise_rmsd, pca, mean_structure, diffusion_map, kmeans, agglomerative_clustering, dbscan, medoid, msd, group_variance, block_convergence, harmonic_similarity, population_similarity, path_similarity |
molframe.formats | write, to_mmcif, to_pdb, to_bcif |
molframe.interop | graph, Graph, coordinates, CoordinateTensor, Dataset, DatasetSplit, ManifestEntry, write_atoms_parquet, write_atoms_ipc |
molframe.sel | Category, column, and spatial query constructors including within() |
AnalysisPolicy | All fourteen analysis decisions (assembly, model, altloc, hydrogens, symmetry, contact_def, …); accepted by select and the governed analyses. See Decisions, outcomes and audits |
Analysis / Coverage | A value with its status, coverage, warnings, assumptions and provenance |
Table | Read-only named array columns returned inside an Analysis; Arrow C-stream export |
ContactTable | len() and Arrow C-stream export through __arrow_c_stream__() |
BondTable | structure.bonds: len() and Arrow C-stream export |
Functions that take coordinates take C-contiguous float32 arrays of shape (n, 3); ones that take a structure read its own coordinates. The governed analyses (contacts, hydrogen_bonds, salt_bridges, validation.clashes, trajectory.rmsd) take policy= and return an Analysis.
See Structural analysis and NumPy and Arrow interoperability.
Workflows
| API | Purpose |
|---|---|
Workflow / WorkflowNode | Declare typed calculation inputs, operations, and named outputs. |
CompiledWorkflow | Run a compiled graph and inspect its explanation. |
See Compiled workflows.
Array protocols
Float32Array and UInt32Array are typing protocols for coordinate and index arrays. At runtime, MolFrame returns NumPy-compatible values; users normally work with their .shape or pass them to NumPy-aware libraries.
molframe.motif.evaluate(structure, specification) runs the declarative functional-geometry evaluation a TOML or JSON specification describes and returns one verdict per admitted mapping, with every constraint measurement kept beside it and the mapping's residues identifying it. Pruning is on by default (constrained=True, shared by count, matches, first and iter_matches): a spatial index keeps a mapping when each distance constraint is within its tolerance or inside the range the verdict profile accepts, so cost follows the output, no passing mapping is dropped, and every kept verdict equals the unpruned one. Pass constrained=False to report every structural mapping, failures included; pass components= for chemistry-aware atom mapping. The trajectory readers cover the self-describing formats only; formats that need caller-supplied units or topology (GSD, H5MD, AMBER ASCII) are rejected by name rather than guessed.
Verification status
The Python suite (python -m pytest python/tests) ran 73 tests green against an extension built from this tree, including real-Gemmi reference values for structure factors, analytic checks for accessible area and cavities, and a brute-force oracle for neighbour search. Interaction analyses are tested with a small hand-written component dictionary; they have not been run against the full wwPDB dictionary. The exact workspace verification commands are maintained in molframe/AGENTS.md.
geometry.internal_coordinates(structure, model=0) exposes the native deterministic
bond-graph forest. InternalCoordinates.seeds retains Cartesian seeds and atoms
retains atom indices, reference indices and the six dihedron measurements.
rebuild() preserves absent atoms as None. Reuse the forest across frames with
measure_bat(positions) and rebuild_bat(frame): BatFrame.coordinates stores
bond length, angle and torsion in Å and radians, matching Rust's molframe.ic.
geometry.place_atom also accepts radians; the existing angles and dihedrals
functions return degrees.