Struct Structure 

pub struct Structure(/* private fields */);

An immutable structure, shared by reference.

Cloning one is a reference count, not a copy, so passing a structure to another thread or holding several versions at once is cheap.

Examples

use molframe_core::structure::{Structure, StructureData};

let structure = Structure::new(StructureData::empty());
assert_eq!(structure.atom_count(), 0);
assert_eq!(structure.model_count(), 1);

Implementations

impl Structure

pub fn with_distinct_labels(&self) -> Option<Self>

This structure with repeated normalised chain labels and repeated normalised residue numbers made distinct, or None when every chain and residue already has its own.

A repeated chain takes the label with the lowest unused number appended. Within a chain that repeats a residue number, each later residue steps the numbering on by one so the order is kept. The depositor identifiers are untouched, so the original survives in its own namespace.

impl Structure

pub fn new(data: StructureData) -> Self

Wraps structure data for sharing.

pub fn with_input( self, name: Option<Box<str>>, digest: Option<ContentDigest>, ) -> Self

Returns this structure recording the input it was read from.

The digest is of the bytes the reader parsed, after any decompression.

pub fn data(&self) -> &StructureData

The data behind the reference.

pub fn shared(&self) -> Arc<StructureData>

The shared handle, for a view that must outlive this reference.

pub fn atom_count(&self) -> u32

The number of atoms in one model.

pub fn atom(&self, atom: AtomIndex) -> Option<AtomRef<'_>>

A lightweight handle on one atom.

pub fn model(&self, model: ModelIndex) -> Option<ModelRef<'_>>

A lightweight handle on one model.

pub fn model_snapshot(&self, model: ModelIndex) -> Option<(Self, ModelIndex)>

The structure and local model position that represent one model.

Dense models share this structure and retain their position. Ragged models are independent single-model structures, so their local position is zero. This keeps callers from padding unlike topologies.

pub fn chain(&self, chain: ChainIndex) -> Option<ChainRef<'_>>

A lightweight handle on one chain.

pub fn residue(&self, residue: ResidueIndex) -> Option<ResidueRef<'_>>

A lightweight handle on one residue.

pub fn model_count(&self) -> usize

The number of models.

pub fn ragged_models(&self) -> Option<&[Self]>

The independent model structures when topology differs between models.

pub fn is_ragged_ensemble(&self) -> bool

Whether this is the outer shell of a ragged ensemble.

The shell carries the models and shared metadata but an empty topology of its own: atoms, residues and chains live in the independent model structures. Any analysis that walks this structure’s atoms sees nothing, which is indistinguishable from an empty molecule unless it asks.

pub fn require_resolved_model(&self) -> Result<&Self, Diagnostic>

Refuses a structure whose atoms are not held in this structure.

Structure-level analyses that read atoms, residues or chains must call this first: on a ragged ensemble they would otherwise return empty results silently. Select one model with Structure::model_snapshot (or iterate Structure::ragged_models) and analyse that instead.

Errors

Returns Code::E6003 for a ragged ensemble, with the model count as context.

pub fn chain_count(&self) -> usize

The number of chains.

pub fn residue_count(&self) -> usize

The number of residues.

pub fn entity_count(&self) -> usize

The number of distinct chemical species.

pub fn positions(&self) -> &[[f32; 3]]

The positions of the first model, contiguously.

This slice is the buffer itself, not a copy of it, which is what makes handing coordinates to a numeric array free.

pub fn model_positions(&self, model: ModelIndex) -> Option<&[[f32; 3]]>

The positions of one model.

pub fn generation(&self) -> CoordinateGeneration

How many times the positions have changed.

pub fn annotations(&self) -> &AtomAnnotations

Structure-local typed columns aligned to atom rows.

pub fn secondary_structure(&self) -> &[SecondaryStructure]

Secondary-structure assignments aligned to residue rows.

pub fn secondary_source(&self) -> &[SecondarySource]

Where each residue’s secondary-structure state came from, aligned to Self::secondary_structure.

pub fn extensions(&self) -> &ExtensionStore

Cold, typed domain metadata attached to this snapshot.

pub fn with_extension<T>(&self, key: &'static str, value: T) -> Self

where T: Any + Send + Sync + RefUnwindSafe,

Returns a new snapshot with one typed domain extension attached.

pub fn without_extensions(&self) -> Self

Returns a new snapshot without domain extensions.

pub fn resolve(&self, symbol: SymbolId) -> Option<&str>

The string an interned identifier names.

impl Structure

pub fn resolve_altlocs( &self, policy: &AnalysisPolicy, ) -> Analysis<AtomSelection>

Selects atom rows under the policy’s alternate-conformation rule.

Blank-labelled atoms are retained under every rule because they belong to every conformation. The stored structure is never changed.

Panics

This function does not intentionally panic when an internal selector reports an impossible cardinality; such a result is returned as an indeterminate analysis instead.

impl Structure

pub fn resolved_atoms( &self, policy: &AnalysisPolicy, ) -> Result<(AtomSelection, Vec<Diagnostic>), Diagnostic>

The atoms an altloc policy selects, with the findings that came with them.

For callers that cannot do anything with a refusal: it becomes the diagnostic that explains it. Code that can carry an indeterminate result should use Structure::resolve_altlocs and keep the outcome.

Errors

Returns the first finding, or Code::E3001, when the policy selects no consistent set of atoms.

impl Structure

pub fn edit_coordinates( &self, context: &ExecutionContext, ) -> Result<CoordinateEditor, MemoryBudgetError>

Starts a scoped coordinate edit under the shared execution account.

Coordinate storage is copied for the new snapshot; topology and atom annotations remain untouched. Call CoordinateEditor::commit to validate and publish the new snapshot. Shared topology remains borrowed. Direct coordinate frames detach under the supplied account, and their reservations follow the copied backing buffers through committed snapshots and clones.

Errors

Returns before publishing an editor when all coordinate copies cannot fit.

impl Structure

pub fn ensemble_positions( &self, models: Option<&[ModelIndex]>, ) -> Result<EnsembleBlock, Diagnostic>

Gathers the positions of models (every model when None) into one buffer.

The buffer is allocated once at its final size, so peak memory is the result itself. Models keep the order given.

Errors

Returns Code::E6003 for a ragged ensemble (naming ragged_models) or for a model index the structure does not have, and Code::E7001 when the buffer size overflows usize or cannot be reserved.

impl Structure

pub fn label_rewrites(&self) -> LabelRewrites

The rewrites Structure::with_distinct_labels would make, in the first model’s topology.

impl Structure

pub fn merge(structures: &[Self]) -> Result<Self, Vec<Diagnostic>>

Concatenates compatible structures into one immutable system.

Atom, residue, chain and entity order follows input order. Dense inputs must have equal frame counts; their corresponding frames are concatenated. Dictionary identifiers, bonds and symbolic annotations are remapped rather than compared by structure-local integer value.

Errors

Returns diagnostics for invalid inputs, ragged or unequal model axes, incompatible same-named annotation types, or representational overflow.

impl Structure

pub fn edit(&self) -> StructureEditor

Starts a transactional structural edit.

pub fn materialize( &self, selection: &AtomSelection, ) -> Result<Structure, Vec<Diagnostic>>

Copies a selected atom set into a compact, independent structure.

Empty residues, chains and unreferenced entities are removed. Secondary states and their provenance follow the retained residue rows; unavailable columns stay unavailable. Dense frames share the compacted hierarchy. Bonds retain their order and provenance when both endpoints survive. Domain extensions are discarded because their topology-aligned contents cannot remain valid after materialisation.

Errors

Returns diagnostics for an out-of-range atom, a ragged ensemble, or an invalid source hierarchy.

impl Structure

pub fn view(&self) -> StructureView

A view of every atom.

pub fn view_of(&self, selection: AtomSelection) -> StructureView

A view of the atoms in selection.

Trait Implementations

impl Clone for Structure

fn clone(&self) -> Self

Returns a duplicate of the value.

fn clone_from(&mut self, source: &Self)

Performs copy-assignment from source.

impl Debug for Structure

fn fmt(&self, f: &mut Formatter<'_>) -> Result

Formats the value using the given formatter.

impl Display for Structure

fn fmt(&self, f: &mut Formatter<'_>) -> Result

Formats the value using the given formatter.

impl From<StructureData> for Structure

fn from(data: StructureData) -> Self

Converts to this type from the input type.