Merge pull request #128 from singularitti:docs

Update docs

docs/src/lib/public.md

@@ -53,7 +53,6 @@ get_dataset
 get_dataset_with_hall_number
 get_spacegroup_type
 get_symmetry_from_database
-get_spacegroup_number
 get_international
 get_schoenflies
 standardize_cell

docs/src/man/definitions.md

@@ -7,7 +7,8 @@ Depth = 3
 
 !!! warning
     Our definitions and conventions are mostly adapted from
-    [here](https://spglib.readthedocs.io/en/latest/definition.html), with some notable differences, such as the matrix representation of lattices.
+    [here](https://spglib.readthedocs.io/en/latest/definition.html), with some minor
+    differences, such as the matrix representation of lattices.
 
 ## Basis vectors
 
@@ -102,6 +103,22 @@ or
 \mathbf{r} = \sum_i x_i \mathbf{a}_i.
 ```
 
+!!! note
+    In the Python version of Spglib,
+    lattice parameters `lattice` are given by a ``3\times 3`` matrix with floating
+    point values, where ``\mathbf{a}``, ``\mathbf{b}``, ``\mathbf{c}`` are
+    given as rows, which results in the transpose of the definition for
+    C-API. That is, in Python, the basis vectors are written as
+    [follows](https://spglib.readthedocs.io/en/latest/variable.html#lattice):
+
+    ```python
+    [ [ a_x, b_x, c_x ],
+      [ a_y, b_y, c_y ],
+      [ a_z, b_z, c_z ] ]
+    ```
+
+    Here, we adopt the C-API convention, i.e., writing basis vectors as columns.
+
 ## Space group operation and change of basis
 
 ### Symmetry operation ``(\mathbf{W}, \mathbf{w})``

src/reduce.jl

@@ -3,6 +3,24 @@
     niggli_reduce(cell::Cell, symprec=1e-5)
 
 Apply Niggli reduction to input basis vectors `lattice`.
+
+The transformation from original basis vectors 
+``\\begin{bmatrix} \\mathbf{a} & \\mathbf{b} & \\mathbf{c} \\end{bmatrix}``
+to final basis vectors
+``\\begin{bmatrix} \\mathbf{a}' & \\mathbf{b}' & \\mathbf{c}' \\end{bmatrix}``
+is achieved by linear
+combination of basis vectors with integer coefficients without
+rotating coordinates. Therefore the transformation matrix is obtained
+by
+
+```math
+\\mathbf{P} = \\begin{bmatrix} \\mathbf{a} & \\mathbf{b} & \\mathbf{c} \\end{bmatrix}
+\\bigl(\\begin{bmatrix} \\mathbf{a}' & \\mathbf{b}' & \\mathbf{c}' \\end{bmatrix}\\bigr)^{-1}
+```
+
+and the matrix elements have to be almost integers.
+
+See also [Computing rigid rotation introduced by idealization](@ref).
 """
 function niggli_reduce(lattice::Lattice, symprec=1e-5)
     clattice = transpose(convert(Matrix{Cdouble}, lattice))
@@ -24,6 +42,24 @@ end
     delaunay_reduce(cell::Cell, symprec=1e-5)
 
 Apply Delaunay reduction to input basis vectors `lattice`.
+
+The transformation from original basis vectors 
+``\\begin{bmatrix} \\mathbf{a} & \\mathbf{b} & \\mathbf{c} \\end{bmatrix}``
+to final basis vectors
+``\\begin{bmatrix} \\mathbf{a}' & \\mathbf{b}' & \\mathbf{c}' \\end{bmatrix}``
+is achieved by linear
+combination of basis vectors with integer coefficients without
+rotating coordinates. Therefore the transformation matrix is obtained
+by
+
+```math
+\\mathbf{P} = \\begin{bmatrix} \\mathbf{a} & \\mathbf{b} & \\mathbf{c} \\end{bmatrix}
+\\bigl(\\begin{bmatrix} \\mathbf{a}' & \\mathbf{b}' & \\mathbf{c}' \\end{bmatrix}\\bigr)^{-1}
+```
+
+and the matrix elements have to be almost integers.
+
+See also [Computing rigid rotation introduced by idealization](@ref).
 """
 function delaunay_reduce(lattice::Lattice, symprec=1e-5)
     clattice = transpose(convert(Matrix{Cdouble}, lattice))

src/symmetry.jl

@@ -2,7 +2,31 @@
 """
     get_symmetry(cell::Cell, symprec=1e-5)
 
-Return the symmetry operations of a `cell`.
+Return the symmetry operations (rotations, translations) of a `cell`.
+
+Returned value `rotations` is a `Vector` of matrices. It has the length of
+"number of symmetry operations". Each matrix is a ``3 \\times 3`` integer matrix.
+Returned value `translations` is a `Vector` of vectors. It has the length of
+"number of symmetry operations". Each vector is a length-``3`` vector of floating point numbers.
+
+The orders of the rotation matrices and the translation
+vectors correspond with each other, e.g., the second symmetry
+operation is organized by the set of the second rotation matrix and second
+translation vector in the respective arrays. Therefore a set of
+symmetry operations may obtained by
+`[(r, t) for r, t in zip(rotations, translations)]`.
+
+The operations are given with respect to the fractional coordinates
+(not for Cartesian coordinates). The rotation matrix and translation
+vector are used as follows:
+
+```math
+new_vector_{3 \\times 1} = rotation_{3 \\times 3} * vector_{3 \\times 1} + translation_{3 \\times 1}.
+```
+
+The three values in the vector are given for the ``a``, ``b``, and ``c`` axes, respectively.
+
+See also [`get_magnetic_symmetry`](@ref) for magnetic symmetry search.
 """
 function get_symmetry(cell::Cell, symprec=1e-5)
     lattice, positions, atoms = _expand_cell(cell)