From 88aafb31777657e731ece05fb4d53dc4ed7b8091 Mon Sep 17 00:00:00 2001
From: Bonan Zhu <zhubonan@outlook.com>
Date: Sun, 14 Jan 2024 11:30:33 +0800
Subject: [PATCH] Update cell matrix convention notes

---
 docs/theory.md    | 35 +++++++++++++++++++++++++++++++++++
 easyunfold/cli.py |  2 +-
 2 files changed, 36 insertions(+), 1 deletion(-)

diff --git a/docs/theory.md b/docs/theory.md
index 3b88471..d00ca7a 100644
--- a/docs/theory.md
+++ b/docs/theory.md
@@ -74,5 +74,40 @@ cell, followed by a reduction using the symmetry of the supercell. The spectral
 is then a weighted combination of that set of $\vec{k_s^\prime}$ points that are inequivalent under the 
 symmetry of the supercell.
 
+
+## Cell and Transformation Matrix convention
+
+The cell matrix may be consisted of column or row lattice vectors. In this package we use the **row vector**
+convention as commonly found in many post-processing tools and DFT codes. The cell matrix is defined as:
+
+$$
+\mathbf{C} = \begin{pmatrix}
+x_a & y_a & z_a \\
+x_b & y_b & z_b \\
+x_c & y_c & z_c
+\end{pmatrix}
+$$
+
+where $x_a$, $y_a$, $z_a$ are components of the lattice vector $\mathbf{a}$.
+
+The cell matrix of the supercell $\mathbf{C_s}$ is obtained by (left) multiplying the original unit cell $\mathbf{C_u}$ by the transformation matrix $\mathbf{M}$:
+
+
+$$
+\mathbf{C_{s}} = \mathbf{M} \, \mathbf{C_u}
+$$
+
+:::{note}
+Sometimes the cell matrix is defined by **column** vectors of the lattice parameters, e.g. $\mathbf{C_u^c} = \mathbf{C_u^T}$, and the relationship becomes:
+$$
+\mathbf{C_u^c} = \mathbf{C_u^T} \, \mathbf{M^T}
+$$
+
+Hence, when the column vector convention is used, the transformation matrix is the **transpose** of that used by the row convention.
+
+One example of code using the column vector convention is [Phonopy](https://phonopy.github.io/phonopy/setting-tags.html#dim).
+:::
+
+
 [^1]: Popescu, V.; Zunger, A. Effective Band Structure of Random Alloys. Phys. Rev. Lett. 2010, 104 (23), 236403. https://doi.org/10.1103/PhysRevLett.104.236403.
 [^2]: Popescu, V.; Zunger, A. Extracting $E$ versus $\vec{k}$ Effective Band Structure from Supercell Calculations on Alloys and Impurities. Phys. Rev. B 2012, 85 (8), 085201. https://doi.org/10.1103/PhysRevB.85.085201.
\ No newline at end of file
diff --git a/easyunfold/cli.py b/easyunfold/cli.py
index 75e3097..f2241a4 100644
--- a/easyunfold/cli.py
+++ b/easyunfold/cli.py
@@ -51,7 +51,7 @@ def easyunfold():
 @click.option('--matrix',
               '-m',
               help='Transformation matrix, in the form "x y z" for a diagonal matrix, '
-              'or "x1 y1 z1, x2 y2 z2, x3 y3 z3" for a 3x3 matrix. Automatically guessed if not '
+              'or "x1 y1 z1 x2 y2 z2 x3 y3 z3" for a 3x3 matrix. Automatically guessed if not '
               'provided.')
 @click.option('--symprec', help='Tolerance for determining the symmetry', type=float, default=1e-5, show_default=True)
 @click.option('--out-file', '-o', default='easyunfold.json', help='Name of the output file')