Skip to main content

Cell

Struct Cell 

pub struct Cell { /* private fields */ }
Expand description

Periodic parallelepiped: columns of H, origin, and an ortho flag.

let cell = Cell::ortho(10.0, 11.0, 12.0)?;
assert!(cell.is_ortho());
let sheared = Cell::from_vectors(
    [10.0, 0.0, 0.0],
    [5.0, 8.66, 0.0],
    [0.0, 0.0, 10.0],
    [0.0, 0.0, 0.0],
)?;
assert!(!sheared.is_ortho());

Implementations§

§

impl Cell

pub fn ortho(lx: f64, ly: f64, lz: f64) -> Result<Cell, Error>

Diagonal box with origin at zero.

Sets Self::is_ortho so Self::dist2 and Self::lattice_shift skip the two 3x3 matvecs.

pub fn ortho_origin( lx: f64, ly: f64, lz: f64, origin: [f64; 3], ) -> Result<Cell, Error>

Diagonal box with an explicit dump-cell origin.

pub fn from_vectors( a: [f64; 3], b: [f64; 3], c: [f64; 3], origin: [f64; 3], ) -> Result<Cell, Error>

Parallelepiped from lattice vectors a, b, c and an origin.

Vectors are the columns of H. A non-diagonal H clears Self::is_ortho.

Inlined so the caller writes the cell once. An outlined return stores it and then copies it.

pub fn from_ase(rows: [[f64; 3]; 3]) -> Result<Cell, Error>

ASE-style 3x3 cell: rows are lattice vectors a, b, c.

Origin is zero. Matches atoms.cell in ASE.

pub fn from_con(rows: [[f64; 3]; 3]) -> Result<Cell, Error>

CON lattice: rows are lattice vectors a, b, c, origin zero.

Same storage as readcon lattice_vectors and an eOn CON header that already holds the 3x3 basis.

pub fn from_con_box(boxl: [f64; 3], angles_deg: [f64; 3]) -> Result<Cell, Error>

CON / crystallographic lengths and angles (degrees).

alpha is the angle at the origin between b and c, beta between a and c, gamma between a and b. The basis is the standard reduced triclinic frame used by ASE and eOn.

pub fn from_vesin(rows: [[f64; 3]; 3]) -> Result<Cell, Error>

vesin box: rows are lattice vectors a, b, c, origin zero.

pub fn from_lammps( xlo: f64, xhi: f64, ylo: f64, yhi: f64, zlo: f64, zhi: f64, xy: f64, xz: f64, yz: f64, ) -> Result<Cell, Error>

LAMMPS restricted-triclinic box from xlo xhi ylo yhi zlo zhi and tilt factors xy, xz, yz.

Recovers the same H and origin as a dump ITEM BOX BOUNDS line whose bound lo/hi already include the tilt padding.

pub fn from_lammps_bounds( xspan: f64, yspan: f64, zspan: f64, xy: f64, xz: f64, yz: f64, xlo_b: f64, ylo_b: f64, zlo_b: f64, ) -> Result<Cell, Error>

LAMMPS dump bound spans plus tilts and bound lo.

xspan, yspan, zspan are xhi_bound - xlo_bound etc. xy, xz, yz are the tilt factors. xlo_b, ylo_b, zlo_b are the bound lo. Inverse of xlo_bound = xlo + min(0, xy, xz, xy+xz).

pub fn is_ortho(&self) -> bool

True when H is diagonal. Distances and lattice shifts then skip the two 3x3 matvecs and use three independent wraps.

pub fn a(&self) -> [f64; 3]

Lattice vector a (first column of H).

pub fn b(&self) -> [f64; 3]

Lattice vector b.

pub fn c(&self) -> [f64; 3]

Lattice vector c.

pub fn origin(&self) -> [f64; 3]

Dump-cell origin.

pub fn widths(&self) -> [f64; 3]

Perpendicular widths of the three faces.

pub fn h(&self) -> [[f64; 3]; 3]

Columns of H.

pub fn hinv(&self) -> [[f64; 3]; 3]

Inverse of H, stored by columns.

pub fn fractional(&self, r: [f64; 3]) -> [f64; 3]

Fractional coordinates in [0, 1).

Orthorhombic boxes divide by the three widths. The general path is s = Hinv (r - origin), then wrap.

pub fn fixed(&self, r: [f64; 3]) -> [u64; 3]

Fixed-point fractional coordinates: the fraction of r along each lattice vector as round(s * 2^52) * 2^12 on 64 bits.

Convert positions once; Self::dist2_fixed and the fixed-point batches then wrap with integer subtraction, for any cell shape.

pub fn displacement_fixed(&self, a: [u64; 3], b: [u64; 3]) -> [f64; 3]

Engine-wrap displacement between two Self::fixed positions.

The difference modulo 2^64 is the wrap, exactly; a fraction one half apart wraps to -1/2. Agrees with Self::displacement to a few units in the last place.

pub fn dist2_fixed(&self, a: [u64; 3], b: [u64; 3]) -> f64

Squared engine-wrap distance between two Self::fixed positions.

pub fn fixed32(&self, r: [f64; 3]) -> [u32; 3]

Self::fixed rounded to 32 bits per fraction: half the bytes, fractions within 2^-33 of the cell’s.

pub fn displacement_fixed32(&self, a: [u32; 3], b: [u32; 3]) -> [f64; 3]

Engine-wrap displacement between two Self::fixed32 positions: the difference modulo 2^32, exact, then one product with H. A fraction one half apart wraps to -1/2. Within 2^-32 (|a| + |b| + |c|) of Self::displacement.

pub fn dist2_fixed32(&self, a: [u32; 3], b: [u32; 3]) -> f64

Squared distance between two Self::fixed32 positions.

pub fn cartesian(&self, s: [f64; 3]) -> [f64; 3]

Cartesian from fractional: r = H s + origin.

pub fn lattice_shift(&self, na: i32, nb: i32, nc: i32) -> [f64; 3]

Cartesian translation by integer lattice counts (na, nb, nc).

pub fn dist2_shifted(&self, p: [f64; 3], q: [f64; 3], shift: [f64; 3]) -> f64

Squared Cartesian distance after applying a lattice shift to q.

This is not a minimum-image wrap. The caller supplies the image via Self::lattice_shift.

pub fn displacement(&self, p: [f64; 3], q: [f64; 3]) -> [f64; 3]

Minimum-image displacement from p to q: wrap(q - p).

Orthorhombic boxes wrap each axis independently. The general path is ds = wrap(Hinv (q - p)), then dr = H ds.

pub fn dist2(&self, p: [f64; 3], q: [f64; 3]) -> f64

Squared minimum-image distance.

pub fn displacement_cartesian(&self, p: [f64; 3], q: [f64; 3]) -> [f64; 3]

Euclidean MIC by checking the 27 nearest lattice images.

Self::displacement wraps in fractional coordinates. That is the LAMMPS / eOn / ASE convention and is the Cartesian nearest image on a reduced (restricted-triclinic) cell. A highly skewed H can make a neighbouring image shorter in Cartesian space. This walk is the check those codes omit.

pub fn is_restricted(&self) -> bool

True when a is along x and b lies in the xy plane.

This is the GROMACS / LAMMPS / HOOMD restricted-triclinic frame. Those engines refuse or rotate any other orientation before wrap.

pub fn tilts_reduced(&self) -> bool

True when the cell is restricted and the tilts sit inside the GROMACS correct_box / LAMMPS half-box limits |xy| <= lx/2, |xz| <= lx/2, |yz| <= ly/2.

On that domain the fractional wrap is the Euclidean MIC, which is why LAMMPS Domain::minimum_image and HOOMD BoxDim::minImage never search extra images.

pub fn reduce_tilts(&self) -> Result<Cell, Error>

Unimodular tilt reduction: GROMACS correct_box.

Subtracts integer lattice vectors so |xy|, |xz|, |yz| sit inside half the corresponding edge. Same Cartesian lattice, new basis. No-op when Self::tilts_reduced is already true. A general orientation is rotated into the restricted frame first (LAMMPS define_general_triclinic).

pub fn to_restricted(&self) -> Result<Cell, Error>

Rotate a general parallelepiped onto the restricted-triclinic frame (LAMMPS general-to-restricted). Identity when already restricted.

pub fn displacement_euclidean(&self, p: [f64; 3], q: [f64; 3]) -> [f64; 3]

Euclidean nearest image, including displacements longer than the cell.

An orthorhombic box is the per-axis wrap. Otherwise Smith, CCP5 Newsletter 1989: the engine wrap is nearest when its length is strictly below half the smallest face altitude. That is the cutoff regime of GROMACS, LAMMPS, and HOOMD. Linkcell k-NN has no cutoff. A hex-prism body diagonal is an engine wrap that is longer than another image.

Past that test the closest point is Babai’s rounding in the Selling superbasis of H, then the iterative slicer of Sommer, Feder, and Shalvi (SIAM J. Discrete Math. 23, 715, 2009) over the seven Voronoi-relevant vector classes of that superbasis. The superbasis is cached on the calling thread, keyed by H, and is not stored in the cell. A tie keeps the engine vector. Self::displacement stays that engine vector on the caller’s H.

pub fn dist2_shifted_many( &self, p: [f64; 3], qs: &[[f64; 3]], shift: [f64; 3], out: &mut [f64], ) -> Result<(), Error>

Squared distances from p to each q, with one lattice shift already applied to every q.

Rapaport’s linked-cell pair: |q + shift - p|^2. No wrap and no Hinv. out has one entry per q.

pub fn dist2_shifted_indexed( &self, p: [f64; 3], positions: &[[f64; 3]], indices: &[usize], shift: [f64; 3], out: &mut [f64], ) -> Result<(), Error>

Squared distances from p to positions named by indices, with one lattice shift already applied.

A linked-cell bin is an index list into the neighbour array, not a contiguous slice. This gathers a chunk of those positions and runs the same kernel as Self::dist2_shifted_many. The gather copies every point before the kernel runs, and on a long index list that copy was slower than the inlined subtract, so the production walk keeps the subtract.

out has one entry per index. An index past positions panics.

pub fn dist2_euclidean(&self, p: [f64; 3], q: [f64; 3]) -> f64

Squared Euclidean MIC distance.

pub fn fractional_matches_cartesian(&self) -> bool

True when fractional wrap matches the 27-image check on a grid of short Cartesian probes (the cutoff-scale displacements MD engines actually wrap).

A hex prism at the tilt limit can still make a body-diagonal fractional wrap longer than a neighbouring image. Production codes ignore that because the cutoff is well below half the long diagonal.

Trait Implementations§

§

impl Clone for Cell

§

fn clone(&self) -> Cell

Returns a duplicate of the value. Read more
1.0.0 (const: unstable) · Source§

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

Performs copy-assignment from source. Read more
§

impl Copy for Cell

§

impl Debug for Cell

§

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

Formats the value using the given formatter. Read more
§

impl PartialEq for Cell

§

fn eq(&self, other: &Cell) -> bool

Equality operator ==. Read more
1.0.0 (const: unstable) · Source§

fn ne(&self, other: &Rhs) -> bool

Inequality operator !=. Read more
§

impl StructuralPartialEq for Cell

Auto Trait Implementations§

§

impl Freeze for Cell

§

impl RefUnwindSafe for Cell

§

impl Send for Cell

§

impl Sync for Cell

§

impl Unpin for Cell

§

impl UnsafeUnpin for Cell

§

impl UnwindSafe for Cell

Blanket Implementations§

Source§

impl<T> Any for T
where T: 'static + ?Sized,

Source§

fn type_id(&self) -> TypeId

Gets the TypeId of self. Read more
Source§

impl<T> Borrow<T> for T
where T: ?Sized,

Source§

fn borrow(&self) -> &T

Immutably borrows from an owned value. Read more
Source§

impl<T> BorrowMut<T> for T
where T: ?Sized,

Source§

fn borrow_mut(&mut self) -> &mut T

Mutably borrows from an owned value. Read more
Source§

impl<T> CloneToUninit for T
where T: Clone,

Source§

unsafe fn clone_to_uninit(&self, dest: *mut u8)

🔬This is a nightly-only experimental API. (clone_to_uninit)
Performs copy-assignment from self to dest. Read more
Source§

impl<T> From<T> for T

Source§

fn from(t: T) -> T

Returns the argument unchanged.

Source§

impl<T, U> Into<U> for T
where U: From<T>,

Source§

fn into(self) -> U

Calls U::from(self).

That is, this conversion is whatever the implementation of From<T> for U chooses to do.

Source§

impl<T> IntoEither for T

Source§

fn into_either(self, into_left: bool) -> Either<Self, Self> ⓘ

Converts self into a Left variant of Either<Self, Self> if into_left is true. Converts self into a Right variant of Either<Self, Self> otherwise. Read more
Source§

fn into_either_with<F>(self, into_left: F) -> Either<Self, Self> ⓘ
where F: FnOnce(&Self) -> bool,

Converts self into a Left variant of Either<Self, Self> if into_left(&self) returns true. Converts self into a Right variant of Either<Self, Self> otherwise. Read more
§

impl<T> Pointable for T

§

const ALIGN: usize

The alignment of pointer.
§

type Init = T

The type for initializers.
§

unsafe fn init(init: <T as Pointable>::Init) -> usize

Initializes a with the given initializer. Read more
§

unsafe fn deref<'a>(ptr: usize) -> &'a T

Dereferences the given pointer. Read more
§

unsafe fn deref_mut<'a>(ptr: usize) -> &'a mut T

Mutably dereferences the given pointer. Read more
§

unsafe fn drop(ptr: usize)

Drops the object pointed to by the given pointer. Read more
Source§

impl<T> ToOwned for T
where T: Clone,

Source§

type Owned = T

The resulting type after obtaining ownership.
Source§

fn to_owned(&self) -> T

Creates owned data from borrowed data, usually by cloning. Read more
Source§

fn clone_into(&self, target: &mut T)

Uses borrowed data to replace owned data, usually by cloning. Read more
Source§

impl<T, U> TryFrom<U> for T
where U: Into<T>,

Source§

type Error = !

The type returned in the event of a conversion error.
Source§

fn try_from(value: U) -> Result<T, !>

Performs the conversion.
Source§

impl<T, U> TryInto<U> for T
where U: TryFrom<T>,

Source§

type Error = <U as TryFrom<T>>::Error

The type returned in the event of a conversion error.
Source§

fn try_into(self) -> Result<U, <U as TryFrom<T>>::Error>

Performs the conversion.