doctest

moyo/src/base/cell.rs

@@ -18,6 +18,9 @@ pub struct Cell {
 }
 
 impl Cell {
+    /// * `lattice`: Lattice of the cell.
+    /// * `positions`: `positions[i]` is a fractional coordinates of the i-th site.
+    /// * `numbers`: `numbers[i]` is a number of the i-th site.
     pub fn new(lattice: Lattice, positions: Vec<Position>, numbers: Vec<AtomicSpecie>) -> Self {
         if positions.len() != numbers.len() {
             panic!("positions and numbers should be the same length");

moyo/src/base/tolerance.rs

@@ -7,8 +7,11 @@ pub const EPS: f64 = 1e-8;
 const INITIAL_SYMMETRY_SEARCH_STRIDE: f64 = 2.0;
 
 #[derive(Debug, Copy, Clone)]
+/// Tolerance for angle in comparing basis vectors in symmetry search.
 pub enum AngleTolerance {
+    /// Tolerance in radian.
     Radian(f64),
+    /// Default tolerance same as Spglib.
     Default,
 }
 

moyo/src/data/hall_symbol_database.rs

@@ -1,7 +1,9 @@
 use super::arithmetic_crystal_class::ArithmeticNumber;
 use super::hall_symbol::Centering;
 
+/// ITA number for space group types (1 - 230)
 pub type Number = i32;
+/// Number for Hall symbols (1 - 530)
 pub type HallNumber = i32;
 
 #[derive(Debug, Clone)]

moyo/src/data/setting.rs

@@ -1,6 +1,7 @@
 use super::hall_symbol_database::HallNumber;
 
 #[derive(Debug, Copy, Clone, PartialEq)]
+/// Preference for the setting of the space group.
 pub enum Setting {
     HallNumber(HallNumber),
     /// The setting of the smallest Hall number

moyo/src/lib.rs

@@ -9,12 +9,14 @@ pub mod math;
 pub mod search;
 pub mod symmetrize;
 
+pub use base::{
+    AngleTolerance, Cell, Lattice, MoyoError, Operations, OriginShift, Rotation, Translation,
+};
+pub use data::{HallNumber, Number, Setting};
+
 use nalgebra::Matrix3;
 
-use crate::base::{
-    AngleTolerance, Cell, MoyoError, Operations, OriginShift, ToleranceHandler, Transformation,
-};
-use crate::data::{HallNumber, Number, Setting};
+use crate::base::{ToleranceHandler, Transformation};
 use crate::identify::SpaceGroup;
 use crate::search::{PrimitiveCell, PrimitiveSymmetrySearch};
 use crate::symmetrize::{orbits_in_cell, StandardizedCell};
@@ -24,11 +26,14 @@ pub struct MoyoDataset {
     // ------------------------------------------------------------------------
     // Space-group type
     // ------------------------------------------------------------------------
+    /// Space group number.
     pub number: Number,
+    /// Hall symbol number.
     pub hall_number: HallNumber,
     // ------------------------------------------------------------------------
     // Symmetry operations in the input cell
     // ------------------------------------------------------------------------
+    /// Symmetry operations in the input cell.
     pub operations: Operations,
     // ------------------------------------------------------------------------
     // Site symmetry
@@ -45,6 +50,7 @@ pub struct MoyoDataset {
     // ------------------------------------------------------------------------
     // Standardized cell
     // ------------------------------------------------------------------------
+    /// Standardized cell
     pub std_cell: Cell,
     /// Linear part of transformation from the input cell to the standardized cell.
     pub std_linear: Matrix3<f64>,
@@ -55,6 +61,7 @@ pub struct MoyoDataset {
     // ------------------------------------------------------------------------
     // Primitive standardized cell
     // ------------------------------------------------------------------------
+    /// Primitive standardized cell
     pub prim_std_cell: Cell,
     /// Linear part of transformation from the input cell to the primitive standardized cell.
     pub prim_std_linear: Matrix3<f64>,
@@ -66,11 +73,41 @@ pub struct MoyoDataset {
     // ------------------------------------------------------------------------
     // Final parameters
     // ------------------------------------------------------------------------
+    /// Actually used `symprec` in iterative symmetry search.
     pub symprec: f64,
+    /// Actually used `angle_tolerance` in iterative symmetry search.
     pub angle_tolerance: AngleTolerance,
 }
 
 impl MoyoDataset {
+    /// Create a new `MoyoDataset` from the input cell.
+    ///
+    /// # Examples
+    /// ```
+    /// use nalgebra::{matrix, vector, Matrix3, Vector3};
+    /// use moyo::{MoyoDataset, Cell, AngleTolerance, Setting, Lattice};
+    /// let lattice = Lattice::new(matrix![
+    ///     4.603, 0.0, 0.0;
+    ///     0.0, 4.603, 0.0;
+    ///     0.0, 0.0, 2.969;
+    /// ]);
+    /// let x_4f = 0.3046;
+    /// let positions = vec![
+    ///     Vector3::new(0.0, 0.0, 0.0),                // Ti(2a)
+    ///     Vector3::new(0.5, 0.5, 0.5),                // Ti(2a)
+    ///     Vector3::new(x_4f, x_4f, 0.0),              // O(4f)
+    ///     Vector3::new(-x_4f, -x_4f, 0.0),            // O(4f)
+    ///     Vector3::new(-x_4f + 0.5, x_4f + 0.5, 0.5), // O(4f)
+    ///     Vector3::new(x_4f + 0.5, -x_4f + 0.5, 0.5), // O(4f)
+    /// ];
+    /// let numbers = vec![0, 0, 1, 1, 1, 1];
+    /// let cell = Cell::new(lattice, positions, numbers);
+    /// let symprec = 1e-5;
+    /// let angle_tolerance = AngleTolerance::Default;
+    /// let setting = Setting::Standard;
+    /// let dataset = MoyoDataset::new(&cell, symprec, angle_tolerance, setting).unwrap();
+    /// assert_eq!(dataset.number, 136);  // P4_2/mnm
+    /// ```
     pub fn new(
         cell: &Cell,
         symprec: f64,

moyo/tests/test_moyo_dataset.rs

@@ -7,9 +7,8 @@ use std::fs;
 use std::path::Path;
 use test_log::test;
 
-use moyo::base::{AngleTolerance, Cell, Lattice, Permutation, Rotation, Translation};
-use moyo::data::Setting;
-use moyo::MoyoDataset;
+use moyo::base::Permutation;
+use moyo::{AngleTolerance, Cell, Lattice, MoyoDataset, Rotation, Setting, Translation};
 
 /// Sanity-check MoyoDataset
 fn assert_dataset(

moyopy/Cargo.toml

@@ -25,6 +25,6 @@ log.workspace = true
 pyo3-log = "0.10"
 
 [dependencies.pyo3]
-pyo3 = "0.21"
+version = "0.21"
 # "abi3-py38" tells pyo3 (and maturin) to build using the stable ABI with minimum Python version 3.8
 features = ["abi3-py38"]

moyopy/src/base.rs

@@ -6,7 +6,8 @@ use serde::de::{Deserialize, Deserializer};
 use serde::ser::{Serialize, Serializer};
 use serde_json;
 
-use moyo::base::{Cell, Lattice, MoyoError, Operations};
+use moyo::base::Operations;
+use moyo::{Cell, Lattice, MoyoError};
 
 // Unfortunately, "PyCell" is already reversed by pyo3...
 #[derive(Debug, Clone)]

moyopy/src/data.rs

@@ -1,7 +1,7 @@
 use pyo3::prelude::*;
 use pyo3::types::PyType;
 
-use moyo::data::Setting;
+use moyo::Setting;
 
 #[derive(Debug, Clone)]
 #[pyclass(name = "Setting")]

moyopy/src/lib.rs

@@ -5,9 +5,7 @@ use std::sync::OnceLock;
 pub mod base;
 pub mod data;
 
-use moyo::base::AngleTolerance;
-use moyo::data::Setting;
-use moyo::MoyoDataset;
+use moyo::{AngleTolerance, MoyoDataset, Setting};
 
 use crate::base::{PyMoyoError, PyStructure};
 use crate::data::PySetting;