Struct Frame 

pub struct Frame {
    pub meta: HashMap<String, String>,
    pub simbox: Option<SimBox>,
    /* private fields */
}

A dictionary from string keys to Blocks.

Frame provides a simple container for organizing multiple blocks of data, typically representing different aspects of a molecular system (e.g., atoms, bonds, velocities). Each block can have different numbers of rows and different column types.

Fields

meta: HashMap<String, String>

Arbitrary key-value metadata associated with the frame.

simbox: Option<SimBox>

Simulation box defining periodic boundary conditions.

Implementations

impl Frame

pub fn new() -> Frame

Creates an empty Frame.

Examples

use molrs_core::frame::Frame;

let frame = Frame::new();
assert!(frame.is_empty());

pub fn with_capacity(cap: usize) -> Frame

Creates an empty Frame with the specified capacity for blocks.

Examples

use molrs_core::frame::Frame;

let frame = Frame::with_capacity(10);
assert!(frame.is_empty());

pub fn from_map(map: HashMap<String, Block>) -> Frame

Creates a Frame from an existing HashMap of blocks.

Examples

use molrs_core::frame::Frame;
use molrs_core::block::Block;
use std::collections::HashMap;

let mut map = HashMap::new();
map.insert("atoms".to_string(), Block::new());

let frame = Frame::from_map(map);
assert_eq!(frame.len(), 1);

pub fn into_inner( self, ) -> (HashMap<String, Block>, HashMap<String, Grid>, HashMap<String, String>, Option<SimBox>)

Consumes the Frame and returns the inner HashMap of blocks, grids, metadata, and simbox.

Examples

use molrs_core::frame::Frame;
use molrs_core::block::Block;

let mut frame = Frame::new();
frame.insert("atoms", Block::new());
frame.meta.insert("title".into(), "Test".into());

let (blocks, grids, meta, simbox) = frame.into_inner();
assert_eq!(blocks.len(), 1);
assert!(grids.is_empty());
assert_eq!(meta.get("title").unwrap(), "Test");
assert!(simbox.is_none());

pub fn len(&self) -> usize

Number of blocks (keys) in the frame.

Examples

use molrs_core::frame::Frame;
use molrs_core::block::Block;

let mut frame = Frame::new();
assert_eq!(frame.len(), 0);

frame.insert("atoms", Block::new());
assert_eq!(frame.len(), 1);

pub fn is_empty(&self) -> bool

Returns true if the frame contains no blocks.

Note: This only checks blocks, not metadata.

pub fn contains_key(&self, key: &str) -> bool

Returns true if the frame contains the specified key.

pub fn get(&self, key: &str) -> Option<&Block>

Gets an immutable reference to the block for key if present.

For a panicking version, use the Index trait: &frame["key"].

pub fn get_mut(&mut self, key: &str) -> Option<&mut Block>

Gets a mutable reference to the block for key if present.

For a panicking version, use the IndexMut trait: &mut frame["key"].

pub fn insert(&mut self, key: impl Into<String>, block: Block) -> Option<Block>

Inserts a block under key. Returns the previous block if any.

Examples

use molrs_core::frame::Frame;
use molrs_core::block::Block;

let mut frame = Frame::new();
let old = frame.insert("atoms", Block::new());
assert!(old.is_none());

let old = frame.insert("atoms", Block::new());
assert!(old.is_some());

pub fn remove(&mut self, key: &str) -> Option<Block>

Removes and returns the block for key, if present.

pub fn clear(&mut self)

Clears the frame, removing all blocks.

Note: This does NOT clear metadata. Use clear_all() to clear both.

Examples

use molrs_core::frame::Frame;
use molrs_core::block::Block;

let mut frame = Frame::new();
frame.insert("atoms", Block::new());
frame.meta.insert("title".into(), "Test".into());

frame.clear();
assert!(frame.is_empty());
assert!(!frame.meta.is_empty()); // metadata preserved

pub fn clear_all(&mut self)

Clears both blocks and metadata.

Examples

use molrs_core::frame::Frame;
use molrs_core::block::Block;

let mut frame = Frame::new();
frame.insert("atoms", Block::new());
frame.meta.insert("title".into(), "Test".into());

frame.clear_all();
assert!(frame.is_empty());
assert!(frame.meta.is_empty());

pub fn insert_grid( &mut self, name: impl Into<String>, grid: Grid, ) -> Option<Grid>

Insert or replace a named grid.

pub fn remove_grid(&mut self, name: &str) -> Option<Grid>

Remove a named grid.

pub fn get_grid(&self, name: &str) -> Option<&Grid>

Borrow a grid by name.

pub fn get_grid_mut(&mut self, name: &str) -> Option<&mut Grid>

Borrow a grid mutably by name.

pub fn has_grid(&self, name: &str) -> bool

Returns true if the frame contains a named grid.

pub fn grids(&self) -> impl Iterator<Item = (&str, &Grid)>

Returns an iterator over (name, grid) pairs.

pub fn grid_keys(&self) -> impl Iterator<Item = &str>

Returns an iterator over grid names.

pub fn rename_column( &mut self, block_key: &str, old_col_key: &str, new_col_key: &str, ) -> bool

Renames a column in the specified block.

Returns true if the column was successfully renamed, false if the block doesn’t exist, the old column key doesn’t exist, or the new column key already exists.

Examples

use molrs_core::frame::Frame;
use molrs_core::block::Block;
use molrs_core::types::F;
use ndarray::Array1;

let mut frame = Frame::new();
let mut atoms = Block::new();
atoms.insert("x", Array1::from_vec(vec![1.0 as F, 2.0 as F]).into_dyn()).unwrap();
frame.insert("atoms", atoms);

assert!(frame.rename_column("atoms", "x", "position_x"));
assert!(!frame["atoms"].contains_key("x"));
assert!(frame["atoms"].contains_key("position_x"));

pub fn rename_block(&mut self, old_key: &str, new_key: &str) -> bool

Renames a block in the frame.

Returns true if the block was successfully renamed, false if the old block doesn’t exist or the new block name already exists.

Examples

use molrs_core::frame::Frame;
use molrs_core::block::Block;
use molrs_core::types::F;
use ndarray::Array1;

let mut frame = Frame::new();
let mut atoms = Block::new();
atoms.insert("x", Array1::from_vec(vec![1.0 as F]).into_dyn()).unwrap();
frame.insert("atoms", atoms);

assert!(frame.rename_block("atoms", "molecules"));
assert!(!frame.contains_key("atoms"));
assert!(frame.contains_key("molecules"));

pub fn iter(&self) -> impl Iterator<Item = (&str, &Block)>

Returns an iterator over (&str, &Block).

pub fn iter_mut(&mut self) -> impl Iterator<Item = (&str, &mut Block)>

Returns a mutable iterator over (&str, &mut Block).

Examples

use molrs_core::frame::Frame;
use molrs_core::block::Block;
use molrs_core::types::F;
use ndarray::Array1;

let mut frame = Frame::new();
let mut atoms = Block::new();
atoms.insert("x", Array1::from_vec(vec![1.0 as F]).into_dyn()).unwrap();
frame.insert("atoms", atoms);

for (_name, block) in frame.iter_mut() {
    // Can mutate blocks
    if let Some(x) = block.get_float_mut("x") {
        x[[0]] = 99.0 as F;
    }
}

pub fn keys(&self) -> impl Iterator<Item = &str>

Returns an iterator over keys.

pub fn values(&self) -> impl Iterator<Item = &Block>

Returns an iterator over block references.

pub fn values_mut(&mut self) -> impl Iterator<Item = &mut Block>

Returns a mutable iterator over block references.

pub fn validate(&self) -> Result<(), MolRsError>

Validates cross-block consistency.

This method checks for common consistency issues:

• All blocks with “atoms” prefix should have the same nrows
• Bond indices (if present) should reference valid atoms

Returns

• Ok(()) if validation passes
• Err(MolRsError::Validation) with details if validation fails

Examples

use molrs_core::frame::Frame;
use molrs_core::block::Block;
use molrs_core::types::F;
use ndarray::Array1;

let mut frame = Frame::new();
let mut atoms = Block::new();
atoms.insert("x", Array1::from_vec(vec![1.0 as F, 2.0 as F, 3.0 as F]).into_dyn()).unwrap();
atoms.insert("y", Array1::from_vec(vec![0.0 as F, 1.0 as F, 2.0 as F]).into_dyn()).unwrap();
frame.insert("atoms", atoms);

assert!(frame.validate().is_ok());

pub fn is_consistent(&self) -> bool

Checks if the frame is consistent without returning an error.

This is a non-panicking version of validate() that returns a boolean.

Examples

use molrs_core::frame::Frame;
use molrs_core::block::Block;

let frame = Frame::new();
assert!(frame.is_consistent());

Trait Implementations

impl Clone for Frame

fn clone(&self) -> Frame

Returns a duplicate of the value.

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

Performs copy-assignment from source.

impl Debug for Frame

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

Formats the value using the given formatter.

impl Default for Frame

fn default() -> Frame

Returns the “default value” for a type.

impl FrameAccess for Frame

fn get_float( &self, block_key: &str, col_key: &str, ) -> Option<ArrayBase<ViewRepr<&f64>, Dim<IxDynImpl>>>

Gets a float array view from a column inside a block.

fn get_int( &self, block_key: &str, col_key: &str, ) -> Option<ArrayBase<ViewRepr<&i32>, Dim<IxDynImpl>>>

Gets an int array view from a column inside a block.

fn get_bool( &self, block_key: &str, col_key: &str, ) -> Option<ArrayBase<ViewRepr<&bool>, Dim<IxDynImpl>>>

Gets a bool array view from a column inside a block.

fn get_uint( &self, block_key: &str, col_key: &str, ) -> Option<ArrayBase<ViewRepr<&u32>, Dim<IxDynImpl>>>

Gets a uint array view from a column inside a block.

fn get_u8( &self, block_key: &str, col_key: &str, ) -> Option<ArrayBase<ViewRepr<&u8>, Dim<IxDynImpl>>>

Gets a u8 array view from a column inside a block.

fn get_string( &self, block_key: &str, col_key: &str, ) -> Option<ArrayBase<ViewRepr<&String>, Dim<IxDynImpl>>>

Gets a string array view from a column inside a block.

fn simbox_ref(&self) -> Option<&SimBox>

Returns a reference to the simulation box, if present.

fn meta_ref(&self) -> &HashMap<String, String>

Returns a reference to the metadata map.

fn block_keys(&self) -> Vec<&str>

Returns block keys as a Vec.

fn contains_block(&self, key: &str) -> bool

Returns true if the frame contains the specified block key.

fn block_count(&self) -> usize

Number of blocks.

fn is_empty(&self) -> bool

Returns true if the frame contains no blocks.

fn visit_block<R>( &self, key: &str, f: impl FnOnce(&dyn BlockAccess) -> R, ) -> Option<R>

Visits a block by key through the BlockAccess trait, using the visitor pattern to avoid lifetime/return-type issues. Returns None if the block does not exist.

impl<'a> From<&'a Frame> for FrameView<'a>

fn from(frame: &'a Frame) -> FrameView<'a>

Converts to this type from the input type.

impl Index<&str> for Frame

type Output = Block

The returned type after indexing.

fn index(&self, key: &str) -> &<Frame as Index<&str>>::Output

Performs the indexing (container[index]) operation.

impl IndexMut<&str> for Frame

fn index_mut(&mut self, key: &str) -> &mut <Frame as Index<&str>>::Output

Performs the mutable indexing (container[index]) operation.