Update document (API and workflow)

doc/_static/procedure.dot

@@ -0,0 +1,42 @@
+digraph phonopy {
+  graph [bgcolor=transparent];
+  "Phono3py (force-sets)" [shape = box, style = filled];
+  "Phono3py (FC)" [shape = box, style = filled];
+  "Phono3py (LTC)" [shape = box, style = filled];
+  "Supercell + displacements" [shape = box];
+  "Supercell & displacements generation" [shape = box];
+  "Force calc." [shape = octagon];
+  "Force-constants calc." [shape = octagon];
+
+  subgraph ph3force {
+  "Unit cell" -> "Phono3py (force-sets)";
+  "Supercell matrix" -> "Phono3py (force-sets)";
+  "Phono3py (force-sets)" -> "Supercell & displacements generation";
+  "Supercell & displacements generation" -> "Displacements dataset";
+  "Supercell & displacements generation" -> "Supercell";
+  "Supercell & displacements generation"
+  "Supercell" -> "Supercell + displacements";
+  "Displacements dataset" -> "Supercell + displacements";
+  "Supercell + displacements" -> "Supercells with displacements";
+  "Supercells with displacements" -> "Force calc.";
+  "Force calc." -> "Supercell-force sets";
+  }
+
+  subgraph ph3fc {
+  "Unit cell" -> "Phono3py (FC)";
+  "Supercell matrix" -> "Phono3py (FC)";
+  "Displacements dataset" -> "Phono3py (FC)";
+  "Supercell-force sets" -> "Phono3py (FC)";
+  "Phono3py (FC)" -> "Force-constants calc.";
+  "Force-constants calc." -> "Force constants (fc2, fc3)";
+  }
+
+  subgraph ph3ltc {
+  "Unit cell" -> "Phono3py (LTC)";
+  "Supercell matrix" -> "Phono3py (LTC)";
+  "Primitive cell matrix\n(optional)" -> "Phono3py (LTC)";
+  "Non-analytical term\ncorrection parameters\n(optional)" -> "Phono3py (LTC)";
+  "Force constants (fc2, fc3)" -> "Phono3py (LTC)";
+  "Phono3py (LTC)" -> "Lattice thermal conductivity";
+  }
+}

doc/direct-solution.md

@@ -265,40 +265,33 @@ $10^{-8}$ are treated as 0 and those solutions are considered
 as null spaces.
 ```
 
-## Installation of diagonalization solvers with multithreaded BLAS
+## Diagonalization solver interfaces
 
 Multithreaded BLAS is recommended to use for the calculation of the direct
-solution of LBTE since the diagonalization of the collision matrix is
-computationally demanding. A few examples of how to install multithreded BLAS
-libraries are presented below.
+solution of LBTE because the diagonalization of the collision matrix is
+computationally highly demanding. The diagonalization in Phono3py relies on
+LAPACK via BLAS library. There are choices of the BLAS libraries. OpenBLAS and
+MKL are considered most popular choices. For non-INTEL (or AMD) systems such as
+ARM64, MKL can not be used. How to choose the BLAS library in installation via
+conda-forge is written {ref}`here<install_an_example>`.
 
-### MKL linked scipy
+Phono3py has two different interfaces to the LAPACK library. One is via scipy
+(or numpy), and the other is via LAPACKE as shown below. How to switch between
+interfaces is described in the
+{ref}`next section<direct_solution_solver_choice>`.
 
-Scipy (also numpy) has an interface to LAPACK dsyev
-(`scipy.linalg.lapack.dsyev`). An MKL LAPACK linked scipy (also numpy) gives
-very good computing performance and is easily obtained using the anaconda
-package manager. In this choice, usual installation of LAPACKE is necessary for
-running `dgesvd` and `zheev`. When using anaconda, installing OpenBLAS is the
-easiest way to do. See {ref}`install_openblas_lapacke`
+### OpenBLAS or MKL linked scipy and numpy
+
+Scipy and numpy have interfaces to LAPACK `dsyevd`, and scipy also has the
+interface to `dsyev`. OpenBLAS and MKL linked scipy and numpy are provided by
+conda-forge.
 
 ### OpenBLAS or MKL via LAPACKE
 
-Using LAPACKE via python C-API is implemented. By this, phono3py can use LAPACK
-dsyev. This uses smaller memory space than using MKL linked scipy. Practically
-there are two choices, OpenBLAS and MKL. For MKL, proper installatin of the MKL
-package is necessary. The MKL library installed obtained from anaconda can not
-be used.
+LAPACK `dsyev` and `dsyevd` can be accessed via LAPACKE in the phono3py's C
+language implementation through the python C-API.
 
-#### OpenBLAS
-
-Use of OpenBLAS is an easy choice if the anaconda package is used. See
-{ref}`install_openblas_lapacke`.
-
-#### MKL
-
-The BLAS multithread performance may be better in that in MKL. Using MKL-LAPACK
-via MKL-LAPACKE via python C-API is also implemented if the link is succeeded.
-See {ref}`install_mkl_lapacke`.
+(direct_solution_solver_choice)=
 
 ## Solver choice for diagonalization
 

doc/index.md

@@ -41,6 +41,7 @@ Papers that may introduce phono3py:
 ```{toctree}
 :maxdepth: 1
 install
+workflow
 examples
 Interfaces to calculators (VASP, QE, CRYSTAL, Abinit, TURBOMOLE) <interfaces>
 command-options
@@ -51,6 +52,7 @@ direct-solution
 workload-distribution
 cutoff-pair
 external-tools
+phono3py-api
 tips
 citation
 changelog

doc/install.md

@@ -94,7 +94,7 @@ LAPACKE (http://www.netlib.org/lapack/lapacke.html) can be installed from the
 Ubuntu package manager (`liblapacke` and `liblapacke-dev`):
 
 ```bash
-   % sudo apt-get install liblapack-dev liblapacke-dev
+% sudo apt-get install liblapack-dev liblapacke-dev
 ```
 
 ### Compiling Netlib LAPACKE

doc/phono3py-api.md

@@ -0,0 +1,34 @@
+(phono3py_api)=
+
+# Phono3py API
+
+```{contents}
+:depth: 2
+:local:
+```
+
+## `Phono3py` class
+
+To operate phono3py from python, there is phono3py API. The main class is
+`Phono3py` that is imported by
+
+```python
+from phono3py import Phono3py
+```
+
+The minimum set of inputs are `unitcell` (1st argument), `supercell_matrix` (2nd
+argument), and `primitive_matrix`, which are used as
+
+```python
+ph3 = Phono3py(unitcell,
+               [[2, 0, 0], [0, 2, 0], [0, 0, 2]],
+               primitive_matrix='auto')
+```
+
+The `unitcell` is an instance of the
+[`PhonopyAtoms` class](https://phonopy.github.io/phonopy/phonopy-module.html#phonopyatoms-class).
+`supercell_matrix` and `primitive_matrix` are the transformation matrices to
+generate supercell and primitive cell from `unitcell` (see
+[definitions](https://phonopy.github.io/phonopy/phonopy-module.html#definitions-of-variables)).
+This step is similar to the
+[instantiation of `Phonopy` class](https://phonopy.github.io/phonopy/phonopy-module.html#pre-process).

doc/workflow.md

@@ -0,0 +1,21 @@
+(workflow)=
+
+# Workflow
+
+Phono3py calculate phonon-phonon interaction related properties. Diagram shown
+below is an example of workflow to calculate lattice thermal conductivity using
+phono3py. The other properties such as spectral function can be calculated in
+similar ways.
+
+The calculation is divided into roughly three parts:
+
+1. Calculation of supercell-force sets
+2. Calculation of force constants
+3. Calculation of lattice thermal conductivity (or other properties)
+
+```{figure} procedure.png
+:scale: 80
+:align: center
+
+Work flow of lattice thermal conductivity calculation
+```