Struct chemfiles::UnitCell

source ·
pub struct UnitCell { /* private fields */ }
Expand description

An UnitCell represent the box containing the atoms, and its periodicity.

An unit cell is fully represented by three lengths (a, b, c); and three angles (alpha, beta, gamma). The angles are stored in degrees, and the lengths in Angstroms.

A cell also has a matricial representation, by projecting the three base vector into an orthonormal base. We choose to represent such matrix as an upper triangular matrix:

| a_x   b_x   c_x |
|  0    b_y   c_y |
|  0     0    c_z |

Implementations§

source§

impl UnitCell

source

pub fn new(lengths: [f64; 3]) -> UnitCell

Create an Orthorhombic UnitCell from the three lengths, in Angstroms.

Example
let cell = UnitCell::new([30.0, 30.0, 23.0]);

assert_eq!(cell.lengths(), [30.0, 30.0, 23.0]);
assert_eq!(cell.angles(), [90.0, 90.0, 90.0]);
assert_eq!(cell.shape(), CellShape::Orthorhombic);
source

pub fn infinite() -> UnitCell

Create an Infinite UnitCell.

Example
let cell = UnitCell::infinite();

assert_eq!(cell.lengths(), [0.0, 0.0, 0.0]);
assert_eq!(cell.angles(), [90.0, 90.0, 90.0]);
assert_eq!(cell.shape(), CellShape::Infinite);
source

pub fn triclinic(lengths: [f64; 3], angles: [f64; 3]) -> UnitCell

Create an Triclinic UnitCell from the three lengths (in Angstroms) and three angles (in degree). alpha is the angle between the vectors b and c; beta is the between the vectors a and c and gamma is the angle between the vectors a and b.

Example
let cell = UnitCell::triclinic([10.0, 10.0, 10.0], [98.0, 99.0, 90.0]);

assert_eq!(cell.lengths(), [10.0, 10.0, 10.0]);
assert_eq!(cell.angles()[0], 98.0);
// Rounding errors might occur due to internal representation
assert!((cell.angles()[1] - 99.0).abs() < 1e-12);
assert_eq!(cell.angles()[2], 90.0);
assert_eq!(cell.shape(), CellShape::Triclinic);
source

pub fn from_matrix(matrix: [[f64; 3]; 3]) -> UnitCell

Create an UnitCell from a cell matrix. If matrix contains only zeros, then an Infinite cell is created. If only the diagonal of the matrix is non-zero, then the cell is Orthorhombic. Else a Triclinic cell is created. The matrix entries should be in Angstroms.

Panics

If the matrix has a negative determinant, or more generally is not representing a unit cell.

Example
let cell = UnitCell::from_matrix([
    [1.0, 0.0, 0.0], [0.0, 2.0, 0.0], [0.0, 0.0, 3.0]
]);

assert_eq!(cell.lengths(), [1.0, 2.0, 3.0]);
assert_eq!(cell.angles(), [90.0, 90.0, 90.0]);
assert_eq!(cell.shape(), CellShape::Orthorhombic);
source

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

Get the three lengths of the cell, in Angstroms.

Example
let cell = UnitCell::new([30.0, 30.0, 23.0]);
assert_eq!(cell.lengths(), [30.0, 30.0, 23.0]);
source

pub fn set_lengths(&mut self, lengths: [f64; 3]) -> Result<(), Error>

Set the three lengths of the cell, in Angstroms.

Errors

This function fails if the unit cell is infinite, or if one of the lengths is negative.

Example
let mut cell = UnitCell::new([30.0, 30.0, 23.0]);

cell.set_lengths([10.0, 30.0, 42.0]).unwrap();
assert_eq!(cell.lengths(), [10.0, 30.0, 42.0]);

assert!(UnitCell::infinite().set_lengths([1.0, 1.0, 1.0]).is_err());
source

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

Get the three angles of the cell, in degrees.

Example
let cell = UnitCell::new([20.0, 20.0, 20.0]);
assert_eq!(cell.angles(), [90.0, 90.0, 90.0]);

let cell = UnitCell::triclinic([20.0, 20.0, 20.0], [100.0, 120.0, 90.0]);
assert_eq!(cell.angles()[0], 100.0);
// Rounding errors might occur due to internal representation
assert!((cell.angles()[1] - 120.0).abs() < 1e-12);
assert_eq!(cell.angles()[2], 90.0);
source

pub fn set_angles(&mut self, angles: [f64; 3]) -> Result<(), Error>

Set the three angles of the cell, in degrees.

Errors

This function fails if the unit cell is not Triclinic.

Example
let mut cell = UnitCell::triclinic([20.0, 20.0, 20.0], [100.0, 120.0, 90.0]);
assert_eq!(cell.angles()[0], 100.0);
// Rounding errors might occur due to internal representation
assert!((cell.angles()[1] - 120.0).abs() < 1e-12);
assert_eq!(cell.angles()[2], 90.0);

cell.set_angles([90.0, 90.0, 90.0]).unwrap();
assert_eq!(cell.angles(), [90.0, 90.0, 90.0]);
source

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

Get the unit cell matricial representation.

The unit cell representation is obtained by aligning the a vector along the x axis and putting the b vector in the xy plane. This make the matrix an upper triangular matrix:

| a_x   b_x   c_x |
|  0    b_y   c_y |
|  0     0    c_z |
Example
let cell = UnitCell::new([10.0, 20.0, 30.0]);

let matrix = cell.matrix();

assert_eq!(matrix[0][0], 10.0);
assert_eq!(matrix[1][1], 20.0);
assert_eq!(matrix[2][2], 30.0);

assert!(matrix[1][2].abs() < 1e-9);
source

pub fn shape(&self) -> CellShape

Get the shape of the unit cell.

Example
let cell = UnitCell::new([10.0, 20.0, 30.0]);
assert_eq!(cell.shape(), CellShape::Orthorhombic);
source

pub fn set_shape(&mut self, shape: CellShape) -> Result<(), Error>

Set the shape of the unit cell to shape.

Errors

This can fail if the cell length or angles are incompatible with the new shape.

Example
let mut cell = UnitCell::new([10.0, 20.0, 30.0]);
assert_eq!(cell.shape(), CellShape::Orthorhombic);

cell.set_shape(CellShape::Triclinic).unwrap();
assert_eq!(cell.shape(), CellShape::Triclinic);
source

pub fn volume(&self) -> f64

Get the volume of the unit cell.

Example
let cell = UnitCell::new([10.0, 20.0, 30.0]);
assert_eq!(cell.volume(), 10.0 * 20.0 * 30.0);
source

pub fn wrap(&self, vector: &mut [f64; 3])

Wrap a vector in this unit cell.

Example
let cell = UnitCell::new([10.0, 20.0, 30.0]);

let mut vector = [12.0, 5.2, -45.3];
cell.wrap(&mut vector);
assert_eq!(vector, [2.0, 5.2, 14.700000000000003]);

Trait Implementations§

source§

impl Clone for UnitCell

source§

fn clone(&self) -> UnitCell

Returns a copy of the value. Read more
1.0.0 · source§

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

Performs copy-assignment from source. Read more
source§

impl Debug for UnitCell

source§

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

Formats the value using the given formatter. Read more
source§

impl Drop for UnitCell

source§

fn drop(&mut self)

Executes the destructor for this type. Read more

Auto Trait Implementations§

Blanket Implementations§

source§

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

source§

fn type_id(&self) -> TypeId

Gets the TypeId of self. Read more
source§

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

const: unstable · source§

fn borrow(&self) -> &T

Immutably borrows from an owned value. Read more
source§

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

const: unstable · source§

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

Mutably borrows from an owned value. Read more
source§

impl<T> From<T> for T

const: unstable · source§

fn from(t: T) -> T

Returns the argument unchanged.

source§

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

const: unstable · 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> ToOwned for Twhere T: Clone,

§

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 Twhere U: Into<T>,

§

type Error = Infallible

The type returned in the event of a conversion error.
const: unstable · source§

fn try_from(value: U) -> Result<T, <T as TryFrom<U>>::Error>

Performs the conversion.
source§

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

§

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

The type returned in the event of a conversion error.
const: unstable · source§

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

Performs the conversion.