moyo 0.9.0

Library for Crystal Symmetry in Rust
Documentation 
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122

use serde::{Deserialize, Serialize};

use super::super::cell::{AtomicSpecie, Cell, Position};
use super::super::error::MoyoError;
use super::super::tolerance::AngleTolerance;
use super::layer_lattice::LayerLattice;

/// A cell whose third basis vector is the aperiodic stacking direction
/// of a layer system (paper Fu et al. 2024 ยง2).
///
/// Internally a tuple of `(LayerLattice, positions, numbers)` rather than a
/// wrapped `Cell`, so neither `LayerCell` nor `LayerLattice` hands out a borrow
/// of the bulk type at any visibility. In-crate sites that need a `Cell`
/// reconstruct one explicitly.
#[derive(Debug, Clone, Serialize, Deserialize)]
pub struct LayerCell {
    lattice: LayerLattice,
    positions: Vec<Position>,
    numbers: Vec<AtomicSpecie>,
}

impl LayerCell {
    /// Validate `cell.lattice` against the layer-group periodicity contract
    /// (`c` perpendicular to `a, b`) and decompose `cell` into a `LayerCell`.
    pub fn new(
        cell: Cell,
        symprec: f64,
        angle_tolerance: AngleTolerance,
    ) -> Result<Self, MoyoError> {
        let Cell {
            lattice,
            positions,
            numbers,
        } = cell;
        let layer_lattice = LayerLattice::new(lattice, symprec, angle_tolerance)?;
        Ok(Self {
            lattice: layer_lattice,
            positions,
            numbers,
        })
    }

    /// Wrap pre-validated parts without running the perpendicularity check.
    /// Use only at internal construction sites that produce parts guaranteed
    /// to satisfy the layer contract by construction.
    pub(crate) fn new_unchecked(
        lattice: LayerLattice,
        positions: Vec<Position>,
        numbers: Vec<AtomicSpecie>,
    ) -> Self {
        Self {
            lattice,
            positions,
            numbers,
        }
    }

    pub fn lattice(&self) -> &LayerLattice {
        &self.lattice
    }

    pub fn positions(&self) -> &[Position] {
        &self.positions
    }

    pub fn numbers(&self) -> &[AtomicSpecie] {
        &self.numbers
    }

    pub fn num_atoms(&self) -> usize {
        self.positions.len()
    }

    /// Bulk `Cell` view of this layer cell, for in-crate helpers that
    /// consume a `Cell` (the bulk symmetry search, primitive-cell finder,
    /// transformation routines). Allocates a fresh `Cell` rather than
    /// handing out a borrow so the layer-to-bulk crossing remains a value
    /// boundary: bulk-only state can never be aliased back into the
    /// `LayerCell`.
    pub(crate) fn as_cell(&self) -> Cell {
        Cell::new(
            self.lattice.as_lattice(),
            self.positions.clone(),
            self.numbers.clone(),
        )
    }
}

#[cfg(test)]
mod tests {
    use nalgebra::{matrix, vector};

    use super::*;
    use crate::base::Lattice;

    #[test]
    fn test_layer_cell_new_orthogonal() {
        let lattice = Lattice::new(matrix![
            1.0, 0.0, 0.0;
            0.0, 1.0, 0.0;
            0.0, 0.0, 5.0;
        ]);
        let cell = Cell::new(lattice, vec![vector![0.0, 0.0, 0.0]], vec![1]);
        let layer = LayerCell::new(cell, 1e-4, AngleTolerance::Default).unwrap();
        assert_eq!(layer.num_atoms(), 1);
        assert_eq!(layer.lattice().basis().column(2)[2], 5.0);
    }

    #[test]
    fn test_layer_cell_new_rejects_tilted_c() {
        let lattice = Lattice::new(matrix![
            1.0, 0.0, 0.0;
            0.0, 1.0, 0.0;
            0.5, 0.0, 5.0;
        ]);
        let cell = Cell::new(lattice, vec![vector![0.0, 0.0, 0.0]], vec![1]);
        assert!(matches!(
            LayerCell::new(cell, 1e-4, AngleTolerance::Default),
            Err(MoyoError::AperiodicAxisNotOrthogonal { .. })
        ));
    }
}