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 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 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 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.