From 5ce5fc845ce5a8a5dc652bc4f371adfffac92fb9 Mon Sep 17 00:00:00 2001
From: "T.Tian" <alchem0x2a@gmail.com>
Date: Wed, 6 Nov 2024 10:34:16 +0800
Subject: [PATCH] refine install part

---
 doc/installation.md | 89 ++++++++++++++++++++++++++++++++++++++-------
 1 file changed, 76 insertions(+), 13 deletions(-)

diff --git a/doc/installation.md b/doc/installation.md
index e51d0e9..8f230e3 100644
--- a/doc/installation.md
+++ b/doc/installation.md
@@ -1,30 +1,39 @@
 # Installation
 
-The Python API may be installed via either of the following approaches:
+SPARC-X-API may be installed via the following approaches:
 
-### 1. Via `anaconda` or `miniconda` (recommended)
+(use-conda)=
+## Using [`conda`]() (recommended)
 
-Set up a [conda environment](https://conda.io/projects/conda/en/latest/user-guide/tasks/manage-environments.html#creating-an-environment-with-commands) and install the Python API,
-which includes the pseudopotential files:
+You can use any of [`anaconda`](), [`miniconda`](), or
+[`micromamba`]() to install a `conda` package engine.  The rest of the
+steps will be made in a [conda
+environment](https://conda.io/projects/conda/en/latest/user-guide/tasks/manage-environments.html#creating-an-environment-with-commands)
+to get the latest release of SPARC-X-API that comes with the pseudopotentials installed:
 
 ```bash
 # Change 'sparc-env' to your desired name if needed
-conda create -n sparc-env
+conda create -n sparc-env python=3.11 pip mamba
 conda activate sparc-env
 conda install -c conda-forge sparc-x-api
 ```
 
+
 On Linux platforms (x86_64, aarch64), you can also install the
-precompiled `sparc` DFT binaries alongside the API:
+pre-compiled SPARC DFT binaries alongside the API:
 
 ```bash
 conda install -c conda-forge sparc-x
-conda activate sparc-env   # Re-activate to have the env variables effective
+# Re-activate to have the env variables effective
+conda activate sparc-env
 ```
 
-### 2. Manual installation from source with `pip`
 
 
+## [`pip`]() install from source
+
+You can installed the SPARC-X-API from the latest commit using `pip`
+
 ```bash
 python -m pip install git+https://github.com/SPARC-X/SPARC-X-API
 ```
@@ -35,14 +44,68 @@ Optionally, you can download the latest SPMS pseudopotentials and unpacks the ps
 python -m sparc.download_data
 ```
 
+For developers, please check the [how to
+contribute](#setting-up-environment) page for setting up a development
+environment for SPARC-X-API.
+
+## Install the SPARC binary code
+
+To utilize the API for drive SPARC calculations, please following the
+[SPARC manual](https://github.com/SPARC-X/SPARC) for compilation and
+installation of the SPARC DFT code itself.
+
+We recommend using the [`conda-forge` package](#use-conda) to install
+the pre-compiled SPARC binary. If you want to compile the latest SPARC
+C/C++, it is also straightforward:
+
+### Use `conda` toolchains
+
+In the previously configured `sparc-env` environment, install the
+build dependencies and compile. The following process compilers SPARC
+with OpenMPI/OpenBLAS/Scalapack toolchains.
+
+```bash
+conda activate sparc-env
+mamba install -c conda-forge \
+                 make compilers \
+				 fftw=*=mpi_openmpi_* \
+				 openblas openmpi scalapack
+git clone https://github.com/SPARC-X/SPARC.git
+cd SPARC/src
+make USE_MKL=0 USE_SCALAPACK=1 USE_FFTW=1
+```
+
+The compiled binary will be at `SPARC/lib/sparc`, and will run when
+`sparc-env` environment is activated.
+
+**TODO** MKL available?
+
+### Compiling SPARC on HPC
+
+High Performance Clusters (HPC) machines usually have some specific
+requirements about the parallel and numerical library setups. While
+conda installation works in most cases, it is often true to compile
+SPARC with existing MPI/MKL/BLAS libraries to ensure optimal
+performance. The following example shows the compilation with Intel
+MKL/MPICH on Georgia Tech's Pheonix cluster:
+
+```bash
+module load git intel-one-api fftw
+git clone https://github.com/SPARC-X/SPARC.git
+cd SPARC/src
+make USE_MKL=1 USE_SCALAPACK=0 USE_FFTW=1
+```
+
+The compiled binary will be at `SPARC/lib/sparc`, and running it
+requires the dependent modules to be loaded at runtime.
+
+
 
-To utilize the API for drive SPARC calculations, please
-following the [SPARC manual](https://github.com/SPARC-X/SPARC) for
-compilation and installation of the SPARC DFT code itself.
 
-### Post-installation check
+## Post-installation check
 
-We recommend the users to run a simple test after installation and setup:
+We recommend the users to run a simple test after installation and
+setup:
 
 ```bash
 python -m sparc.quicktest