Crate molframe

Expand description

A batteries-included structural bioinformatics engine.

This crate is the composition layer, and it is the whole 1.0 contract: what is reachable from the root or from prelude is curated and stable, and everything else — the raw storage engine — lives under engine, documented there as the uncurated, lower-stability door. The default feature set includes mmCIF and PDB; callers opt into analysis domains independently.

§What the root carries

The root namespace is curated, not a mirror of the workspace. It holds the curated structure handles (Structure, Selection, StructureEditor, the Chains/Residues/Atoms/Models collections), the reading and writing verbs, and the policy and diagnostic vocabulary.

Everything else is module-only. molframe::analysis::hydrogen_bonds, never a flat molframe::hydrogen_bonds; molframe::chemistry::vdw_radius, never molframe::vdw_radius; molframe::interop::AtomTable, never molframe::AtomTable. geometry, analysis, compare, sequence, surface, validation, trajectory, crystal, motif, chemistry, spatial, query, ic, interop, audit and adapters are all reached that way, so the root stays a page a reader can hold. The four structure formats live under formats.

§Reading, and saying what was wrong with the file

use molframe::prelude::*;

fn main() -> Result<(), Box<dyn std::error::Error>> {
    let (structure, findings) =
        read_bytes(PDB.into(), Some("1abc.pdb"), &ReadOptions::new())?;

    println!("{} atoms in {} chains", structure.atom_count(), structure.chain_count());
    for finding in &findings {
        eprintln!("{}", Rendered::new(finding));
    }
    Ok(())
}

read_with_diagnostics is the honest form and is what a pipeline should use: the findings say what was wrong with the file, and a file that parses is not the same as a file that is right. read discards them for convenience. Both return Findings, which is an Error — hence the ? above, and hence anyhow::Result or Box<dyn Error> at a main without a match anywhere.

§Navigating and editing

use molframe::prelude::*;

fn main() -> Result<(), Box<dyn std::error::Error>> {
    let (structure, _) = read_bytes(PDB.into(), Some("1abc.pdb"), &ReadOptions::new())?;

    for chain in structure.chains() {
        println!("chain {:?}: {} residues", chain.label(), chain.residues().count());
    }

    let mut editor = structure.edit();
    editor
        .rename_chain(molframe::ChainIndex::new(0), "B")
        .map_err(Findings::from)?;
    let renamed = editor.finish().map_err(Findings::from)?;
    assert_eq!(renamed.chain_at(0).and_then(|chain| chain.label()), Some("B"));
    Ok(())
}

§Examples are owed, not owed everywhere

The in-memory paths above run as doctests. The remaining public items follow the reference documentation of the crate that owns them rather than repeating it here; the rule that every public item carry an example is not yet met for the facade’s format writers, which is a known debt.

Re-exports§

pub use molframe_chem as chemistry;
pub use molframe_spatial as spatial;
pub use molframe_query as query;

Modules§

engine: The uncurated, low-level door onto the storage engine.
formats: The structure formats, grouped by the crate that reads and writes them.
prelude: The names most programs want in scope.

Structs§

Aabb: An axis-aligned bounding box.
AlgorithmId: Stable name and version of the algorithm that produced a result.
AltId: An alternate-location label.
Analysis: An outcome, and everything needed to judge it.
AnalysisPolicy: Every semantic decision an analysis depends on.
AnisotropicDisplacement: One anisotropic displacement ellipsoid before it is packed into columns.
AnisotropyIndex: Position of an anisotropic displacement row in the anisotropy table.
AnisotropyTable: A compact, immutable anisotropic displacement table sorted by atom.
AnisotropyTableBuilder: Deterministic anisotropy-table construction with atom deduplication.
AnnotationColumn: One immutable typed annotation column with three-state validity.
ApplicationConfiguration: Strict top-level configuration shared by library-backed applications.
Assumption: One decision made on the caller’s behalf.
AtomAnnotations: Custom per-atom columns, ordered by name for deterministic iteration.
AtomIndex: Position of an atom row in the structure’s flat atom order.
AtomRef: One atom.
Atoms: Every atom of a structure, in structure order.
AtomsIter: Every atom of a structure, in structure order.
BatchContinuity: Whether hierarchy rows continue across adjacent batches.
BatchDemand: Maximum work a consumer is prepared to accept from one pull.
BatchLease: A batch whose retained bytes are charged to an execution context.
BondAdjacency: A compressed sparse row view of an undirected bond graph.
BondIndex: Position of a bond in the bond table.
BondInference: Parameters for explicitly requested geometric bond inference.
BondInferenceReport: A new connectivity snapshot and atoms lacking a covalent radius.
BondRecord: One bond before it is packed into columns.
BondTable: A compact, immutable edge table.
BondTableBuilder: Deterministic bond-table construction with endpoint deduplication.
ByteSpan: A half-open byte range within a source file, with the start’s line and column.
CancellationToken: A cheap, thread-safe cooperative cancellation handle.
ChainIndex: Position of a chain in the chain table.
ChainRef: One chain.
Chains: Every chain of a structure, in structure order.
ChainsIter: Every chain of a structure, in structure order.
ChemistryConfiguration: Explicit chemistry resources; merely loading configuration performs no I/O.
Code: A stable diagnostic code, rendered as MOLFRAME-E1103 or MOLFRAME-W3011.
CompiledWorkflow: A validated, optimized workflow reusable across input sets.
CompletionItem: One supported completion candidate.
CompletionResult: Completion response with a byte-addressed replacement range.
ContextItem: A named piece of supporting detail attached to a finding.
CoordinateEditor: A private coordinate copy that becomes a new structure only on commit.
CoordinateSample: A topology-aligned linear sample of two retained coordinate columns. Periodic reconstruction and alignment belong to the caller before sampling.
Coverage: How much of what an analysis meant to use it actually used.
Diagnostic: One finding about the data.
Diagnostics: A growing list of findings that keeps itself in reproducible order.
DictionaryVersion: The version of a body of reference data.
Element: A chemical element, represented by its atomic number.
EntityIndex: Position of an entity in the entity table.
EntryMetadata: What the entry as a whole says about itself.
ExecutionContext: Shared controls passed through every stage of an out-of-core operation.
Explanation: Logical and physical views of a compiled workflow.
ExtensionStore: Cold, typed metadata owned by a structure snapshot.
Findings: The findings an operation produced, as a finished set.
Fingerprint: A fast, stable 64-bit fingerprint of a policy, a record or a cache entry.
InputBuffer: Bytes to read, however they were obtained.
InstanceId: Identifier of one generated copy of an assembly’s contents.
Limits: Ceilings that turn hostile input into diagnostics rather than exhaustion.
MeasuredImpact: The measured effect of one decision on one analysis.
MemoryBudget: A validated upper bound for memory retained by one execution context.
MetadataDifference: Entry-level metadata changes.
MissingResidue: One canonical residue absent from the observed structure.
ModelIndex: Position of a model in the model table.
ModelRef: One model of a structure.
Models: Every model of a structure.
ModelsIter: Every model of a structure, in structure order.
Node: A typed immutable expression node.
OperationMetadata: Static information used by compilation, explanation and memory admission.
Output: A typed named workflow output handle.
OutputConfiguration: Output preferences that an application may apply before explicit flags.
OutputOptions: Working-memory policy for incremental output.
PhysicalNode: One node in a compiled physical explanation.
PolicyOverrides: String vocabulary accepted by policy files and command-line overrides.
PolicyParseError: A named choice (a policy decision, a spatial backend, a file format) was spelled with a word outside its vocabulary.
Position: A point in a source file.
ProfileId: The name and version of a policy profile.
Provenance: Everything needed to reproduce a result.
Query: A parsed and reusable selection plan.
QueryAliases: An ordered set of named query definitions.
QueryFingerprint: Stable identity of a normalized molecular query.
ReadOptions: What a read should and should not bother doing.
ReferenceAlignment: One canonical-to-reference interval from _struct_ref_seq.
ReferenceSequence: One database sequence named by _struct_ref.
Rendered: A finding prepared for display.
ResidueIndex: Position of a residue in the residue table.
ResidueRef: One residue.
Residues: Every residue of a structure, in structure order.
ResiduesIter: Every residue of a structure, in structure order.
ScratchPolicy: Upper bound for reusable in-memory scratch owned by one stage.
SecondaryAssignment: One residue’s state together with where it came from.
SelectAll: A filter that writes everything.
Selection: A zero-copy subset of a Structure’s atoms.
SequenceMapping: One observed residue’s correspondence across sequence namespaces.
SequenceReferences: Typed reference sequence metadata attached to a structure.
Structure: An immutable structure snapshot.
StructureAtomRecord: One atom row accepted by StructureBatchBuilder.
StructureBatch: Bounded structure rows in a format-neutral layout.
StructureBatchBuilder: Incremental builder that interns each distinct identifier once per batch.
StructureDifference: Complete semantic difference summary for two normalised structures.
StructureDifferenceOptions: Explicit controls for semantic structure comparison.
StructureEditor: A transactional structural edit, scoped to one snapshot.
SymbolId: An interned identifier.
Tolerance: How close two floating-point values must be to count as equal.
Topology: The whole hierarchy.
UnitCell: The crystallographic cell.
ValueDifference: A value before and after a semantic change.
Workflow: A symbolic computation graph under construction.
WorkflowInputs: Owned values supplied to a compiled workflow by input name.
WorkflowResults: Named, owner-backed values returned by one workflow execution.
WriteOptions: The decisions a write makes: which identifiers the projection invents, per format family, plus the output working-memory policy.

Enums§

AlignmentPolicy: How two structures are put into correspondence before comparison.
AltlocPolicy: How to resolve alternate conformations.
AmbiguousResidueBoundaryPolicy: Policy for adjacent mmCIF atom groups whose residue identifiers are identical.
AssemblyChoice: Which arrangement of the contents to analyse.
AssumptionSource: Where a decision came from.
AtomAnnotation: The supported physical types for a custom atom annotation.
Backpressure: Outcome of one non-blocking batch pull.
BondOrder: The chemical order assigned to a bond.
BondProvenance: Where a bond assignment came from.
CategoryFilter: Which optional categories (mmCIF/BinaryCIF) or records (PDB) a read keeps.
Class: The class of problem a code’s leading digit names.
CompletionKind: The category of a completion item.
Compression: How a stream of bytes was compressed.
ContactDefinition: What counts as a contact.
ContextError: Inconsistent execution policies supplied to a context builder.
ContinuityLevel: Deepest hierarchy level that continues across one batch boundary.
CoordinateSampleError: Invalid coordinate-sample metadata.
Cost: The data-movement cost attached to an input or operation.
DifferenceError: Why a structure comparison could not be performed.
EntityKind: What kind of chemical species an entity is.
EquivalencePolicy: How two atoms are decided to correspond.
Format: A format molframe can read or write.
HydrogenPolicy: How hydrogens enter a calculation.
Impact: How much a decision changed the answer, where that is known.
Indeterminacy: Why no defensible answer exists under a policy.
InputDigest: Whether a read records a digest of the bytes it parsed.
InputKind: The storage that backs an input byte slice.
Kind: Whether a code denotes a failure or an observation.
MemoryBudgetError: Failure to construct or reserve an execution-memory budget.
MissingElementPolicy: Policy for atom rows whose format-specific element field is absent or invalid.
MissingPolicy: What to do about atoms a component should have but the model does not.
ModelChoice: Which model to analyse.
Namespace: Which identifier namespace an unqualified selector means.
OccupancyPolicy: Policy for atoms whose recorded occupancy lies outside zero to one.
Outcome: A value, or the reason there is none.
ParameterValue: A typed, deterministic result-affecting algorithm parameter.
ParseMode: How much irregularity a read tolerates, and what it does about it.
Perception: Whether a read infers bonds, components and secondary structure afterwards.
PeriodicPolicy: How periodic boundaries are handled.
PlddtBand: One of the four pLDDT confidence bands.
PolicyConfigError: Failure while loading a declarative analysis policy.
PolicyField: Which field of a policy something refers to.
PolymerKind: What kind of polymer a chain is, where it is one.
Precision: The width accumulation runs at.
Presence: What a column says about one position.
Quality: How complete a determinate answer is.
RadiiSet: Which published set of van der Waals radii to use.
SecondarySource: Where a residue’s secondary-structure state came from.
SecondaryStructure: A residue-level structural assignment, in the DSSP vocabulary.
Severity: How bad a finding is, independent of how the caller wants to react.
SourceRef: Where an input came from.
Status: How far an analysis got.
Strictness: How much irregularity the caller is willing to accept.
StructureBatchError: Failure shared by bounded structural batch readers and collectors.
StructureBatchReader: One linked structural batch reader selected by content or explicit format.
SymmetryPolicy: Whether symmetry copies participate.
TempStoragePolicy: Policy controlling whether and where execution may spill temporary data.
WorkflowBuildError: Graph-construction errors detected before compilation.
WorkflowError: Workflow compilation or execution failure.

Constants§

AROMATIC_ATOM_ANNOTATION: Aromatic-atom flag assigned from a chemical component definition.
ATOM_RADIUS_ANNOTATION: Conventional custom column name for per-atom PQR radii.
AUTODOCK_TYPE_ANNOTATION: Conventional custom column name for AutoDock atom types.
COMPONENT_KIND_ANNOTATION: Component role assigned from a chemical component definition.
DEFAULT_BOND_RADIUS_SCALE: Default multiplier applied to the sum of two CCD covalent radii.
DEFAULT_MINIMUM_BOND_DISTANCE: Default minimum accepted interatomic distance in angstroms.
FORMAL_CHARGE_ANNOTATION: Formal charge assigned from a chemical component definition.
HBOND_ACCEPTOR_ANNOTATION: Hydrogen-bond acceptor role perceived from CCD connectivity and protonation.
HBOND_DONOR_ANNOTATION: Hydrogen-bond donor role perceived from CCD connectivity and protonation.
INSTANCE_ID_ANNOTATION: Per-atom stable identifier of the materialised chain copy an atom belongs to.
MISSING_BAND_CODE: Code written for an atom that has no recorded score.
PAE_ANNOTATION: Conventional custom column name for per-atom predicted aligned error.
PARTIAL_CHARGE_ANNOTATION: Conventional custom column name for partial atomic charge.
PLDDT_ANNOTATION: Conventional custom column name for per-atom predicted confidence.
POLYMER_ATOM_ROLE_ANNOTATION: Explicit polymer atom role assigned from a CCD-aware or caller-supplied profile.
SEGMENT_ID_ANNOTATION: Conventional custom column name for atom segment identifiers.
SEQUENCE_REFERENCES_EXTENSION: Stable extension key for database sequence references and alignments.
STEREO_CONFIGURATION_ANNOTATION: Modelled stereochemical configuration anchored to component coordinates.

Traits§

BatchSource: A pull source whose live workspace is governed by an ExecutionContext.
ChainSequenceExt: Sequence views carried by a hierarchy chain handle.
QueryStructure: Selection methods implemented by immutable structure snapshots.
Reader: A reader for one format.
Select: Which parts of a structure a write should include.
StructureValues: Lent, structure-derived completion values.

Functions§

altloc_compatible: Whether two atoms with these alternate labels can be present together.
collect_structure: Materialises a bounded snapshot from a structural batch source.
complete: Computes completion using a UTF-8 byte cursor.
infer_bonds: Infers bonds by covalent-radius distance using the shared spatial planner.
open_component_dictionary: Opens a Chemical Component Dictionary that lowers components on demand.
open_structure_batches: Opens a structural file without reserving memory proportional to file size.
perceive: Applies the default chemistry perception pass to a caller-created structure.
perceive_in: perceive on the worker budget of context.
read: Reads a structure, discarding what was wrong with the file.
read_buffer: Reads a structure from an already-acquired buffer, without a further copy.
read_buffer_in: read_buffer on the budgets of context.
read_bytes: Reads a structure from bytes already in hand.
read_bytes_in: read_bytes on the budgets of context.
read_component_dictionary: Reads a Chemical Component Dictionary file as a versioned provider.
read_configuration: Loads a strict application configuration without accessing referenced resources.
read_document: Reads a document, preserving everything the file held.
read_policy: Loads and validates a complete policy document from JSON or TOML.
read_with_diagnostics: Reads a structure and everything that was wrong with the file it came from.
read_with_options: Reads a structure under explicit options.
read_with_options_in: read_with_options on the worker budget, memory budget and cancellation of context.
structure_difference: Reports how two snapshots differ.
write: Writes a structure in the format named by the destination.
write_as: As write_with_options, in the stated format instead of the one the destination’s name selects. A .gz or .zst suffix still applies its compression.
write_mmcif: Renders a structure as valid, self-consistent mmCIF in memory.
write_mmcif_with_findings: Renders mmCIF like write_mmcif_with_options and also reports what the write rewrote or could not carry.
write_mmcif_with_options: Renders mmCIF in memory with explicit identifier decisions.
write_pdb: Writes a structure in the legacy fixed-column format, or explains why it cannot be written.
write_pdb_with_findings: Writes a structure like write_pdb and also reports what the format could not carry.
write_pdbqt_with_findings: Writes a rigid PDBQT model and reports what the format could not carry.
write_pqr_with_findings: Writes PQR and reports what the format could not carry.
write_with_options: Streams a structure under explicit projection and memory decisions.

Type Aliases§

AnalysisParameters: Sorted algorithm parameters that participate in provenance fingerprints.
CountDifference: A row count before and after a structural change.
Input: A typed named workflow input.
ReadResult: A structure and everything that was wrong with the file it came from.

Crate molframe

Crate molframe Copy item path

§What the root carries

§Reading, and saying what was wrong with the file

§Navigating and editing

§Examples are owed, not owed everywhere

Re-exports§

Modules§

Structs§

Enums§

Constants§

Traits§

Functions§

Type Aliases§

Crate molframe