Struct chemfiles::UnitCell[][src]

pub struct UnitCell { /* fields omitted */ }
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

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);

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);

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);

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);

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]);

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());

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);

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]);

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);

Get the shape of the unit cell.

Example

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

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);

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);

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

Returns a copy of the value. Read more

Performs copy-assignment from source. Read more

Executes the destructor for this type. Read more

Auto Trait Implementations

Blanket Implementations

Gets the TypeId of self. Read more

Immutably borrows from an owned value. Read more

Mutably borrows from an owned value. Read more

Performs the conversion.

Performs the conversion.

The resulting type after obtaining ownership.

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

🔬 This is a nightly-only experimental API. (toowned_clone_into)

recently added

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

The type returned in the event of a conversion error.

Performs the conversion.

The type returned in the event of a conversion error.

Performs the conversion.