deploy: 9676fd6

alchem0x2A · Nov 6, 2024 · 1daa030 · 1daa030
1 parent f466bc0
commit 1daa030
Show file tree

Hide file tree

Showing 37 changed files with 210 additions and 164 deletions.
diff --git a/.doctrees/advanced_socket.doctree b/.doctrees/advanced_socket.doctree
diff --git a/.doctrees/api_changes.doctree b/.doctrees/api_changes.doctree
diff --git a/.doctrees/basic_usage.doctree b/.doctrees/basic_usage.doctree
diff --git a/.doctrees/contribute.doctree b/.doctrees/contribute.doctree
diff --git a/.doctrees/environment.pickle b/.doctrees/environment.pickle
diff --git a/.doctrees/examples.doctree b/.doctrees/examples.doctree
diff --git a/.doctrees/index.doctree b/.doctrees/index.doctree
diff --git a/.doctrees/installation.doctree b/.doctrees/installation.doctree
diff --git a/.doctrees/setup_environment.doctree b/.doctrees/setup_environment.doctree
diff --git a/_images/scheme-SPARC-socket-modes.png b/_images/scheme-SPARC-socket-modes.png
diff --git a/_images/scheme_socket_hetero.png b/_images/scheme_socket_hetero.png
diff --git a/_images/scheme_sparc_protocol.png b/_images/scheme_sparc_protocol.png
diff --git a/_sources/advanced_socket.md.txt b/_sources/advanced_socket.md.txt
@@ -1,8 +1,7 @@
 # Advanced Usage: SPARC-X-API as a Socket Interface
 
-*Disclaimer: The socket communication feature in SPARC and SPARC-X-API are experimental and subject to changes until the release of v2.0 SPARC-X-API.*
 
-### Overview
+## Overview
 Experienced users can harness the power of SPARC and SPARC-X-API's
 socket communication layer to build efficient and flexible
 computational workflows. By integrating a socket communication
@@ -11,22 +10,22 @@ overhead typically associated with file I/O during calculation
 restarts. This feature is particularly beneficial for tasks involving
 repetitive operations like structural optimization and saddle point
 searches, where traditional file-based communication can become a
-bottleneck. The underlying software architecture is shown in [Fig. 3](#fig-3-sparc-electronic-calculations-with-socket-communication-across-hybrid-computing-platforms):
+bottleneck. The underlying software architecture is shown in [the following figure](#fig-3-sparc-electronic-calculations-with-socket-communication-across-hybrid-computing-platforms):
 
-#### Fig. 3. SPARC electronic calculations with socket communication across hybrid computing platforms
-
-![scheme-sparc-socket](doc/img/scheme_socket_hetero.png)
+<!-- #### Fig. 3. SPARC electronic calculations with socket communication across hybrid computing platforms -->
 
+![scheme-sparc-socket](img/scheme_socket_hetero.png)
 
 
+**TODO** change doc source
 
 **Requirements**: the SPARC binary must be manually compiled from the source
 code with [socket
 support](https://github.com/alchem0x2A/SPARC/tree/socket) and with the
 `USE_SOCKET=1` flag enabled (see the [installation
 instructions](https://github.com/alchem0x2A/SPARC/tree/socket).
 
-### Usage
+## Usage
 The socket communication layer in SPARC and SPARC-X-API are designed for:
 - **Efficiency:** Eliminates the need for intermediate file I/O, directly streaming data between processes.
 - **Speed:** Enhances the performance of iterative calculations, crucial for large-scale simulations.
@@ -39,13 +38,13 @@ the SPARC C-source code, while the python SPARC-X-API uses a
 backward-compatible protocol based on i-PI. The dual-mode design is aimed for both low-level and
 high-level interfacing of the DFT codes, providing the following features as shown in [Fig. 4](#fig-4-overview-of-the-sparc-protocol-as-an-extension-to-the-standard-i-pi-protocol):
 
-#### Fig. 4. Overview of the SPARC protocol as an extension to the standard i-PI protocol.
-![scheme-sparc-protocol](doc/img/scheme_sparc_protocol.png)
+### Fig. 4. Overview of the SPARC protocol as an extension to the standard i-PI protocol.
+![scheme-sparc-protocol](img/scheme_sparc_protocol.png)
 
 Based on the scenarios, the socket communication layer can be accessed via the following approaches as shown in [Fig. 5](#fig-5-different-ways-of-using-sparcs-socket-mode):
 
-#### Fig. 5. Different ways of using SPARC's socket mode.
-![scheme-sparc-modes](doc/img/scheme-SPARC-socket-modes.png)
+### Fig. 5. Different ways of using SPARC's socket mode.
+![scheme-sparc-modes](img/scheme-SPARC-socket-modes.png)
 
 
 1. **SPARC binary only** ([Fig. 5](#fig-5-different-ways-of-using-sparcs-socket-mode) **a**)
@@ -131,7 +130,7 @@ Based on the scenarios, the socket communication layer can be accessed via the f
    file systems on the client side.
 
 
-### (In-progress) Controlling SPARC routines from socket interface
+## (In-progress) Controlling SPARC routines from socket interface
 
 As shown in [Fig. 4](#fig-4-overview-of-the-sparc-protocol-as-an-extension-to-the-standard-i-pi-protocol),
 the SPARC socket protocol designs allows bidirectional control of

diff --git a/_sources/api_changes.md.txt b/_sources/api_changes.md.txt
@@ -1,10 +1,16 @@
 # Changes in API
-## Major changes from `SPARC-X-API` [v0.1](https://github.com/SPARC-X/SPARC-X-API/tree/eac557f214b402122a506f88f38c7a8767283503)
+## Major changes from [v1.0](https://github.com/SPARC-X/SPARC-X-API/tree/v1.0.0)
 
-`SPARC-X-API` has been heavily refactored in v1.0. If you're using legacy Python codes
+- Support of socket communication layer
+- Migration to ASE 3.23 standard
+- Enhanced documents
+
+## Major changes from  [v0.1](https://github.com/SPARC-X/SPARC-X-API/tree/eac557f214b402122a506f88f38c7a8767283503)
+
+SPARC-X-API has been heavily refactored in v1.0. If you're using legacy Python codes
 that are written under v0.1 API, there are a few major changes that require your attention:
 
-1. Support for single `.ion` file format is deprecated. Instead, `v0.2` API treats the whole SPARC directory as a bundle format. Please use `read_sparc` and `write_sparc` methods for basic file I/O instead.
+1. Support for single `.ion` file format is deprecated. Instead, v1.0 API treats the whole SPARC directory as a bundle format. Please use `read_sparc` and `write_sparc` methods for basic file I/O instead.
 Nevertheless, reading calculation results generated by a v0.1 API code will not be affected.
 
 2. v1.0 API uses a different mapping scheme for the sorting of ASE atoms objects (similar to `Vasp`), add a comment section in `.ion` file similar to follows:
@@ -13,16 +19,21 @@ Nevertheless, reading calculation results generated by a v0.1 API code will not
 # 3 2 1 0
 # END ASE-SORT
 ```
-which maps atoms 3, 2, 1, 0 from the SPARC .ion file order to atoms 0, 1, 2, 3 in ASE order. This is useful for systems that are constructed by ASE's `add_adsorbate` method.
-
-3. v1.0 API accepts all SPARC internal parameters (i.e. **CAPITALIZED**) in *atomic units* for consistency reason.
-However, we also keep a list of "special input params" that are conventionally used in other ASE calculators, that use Å / eV / GPa / fs unit system.
+which maps atoms 3, 2, 1, 0 from the SPARC .ion file order to
+atoms 0, 1, 2, 3 in ASE order. This is useful for systems that are
+constructed by ASE's `add_adsorbate` method.
 
-4. Defining `LATVEC`, `LATVEC_SCALE`, or `CELL` via the calculator parameters is no longer encouraged. Instead, all structure changes should be made to the `Atoms` object.
+3. v1.0 API accepts all SPARC internal parameters
+(i.e. **CAPITALIZED**) in *atomic units* for consistency reason.
+However, we also keep a list of "special input params" that are
+conventionally used in other ASE calculators, that use Å / eV / GPa /
+fs unit system.
 
-For more discussion please see [Advanced Topic] section.
+4. Defining `LATVEC`, `LATVEC_SCALE`, or `CELL` via the calculator
+   parameters is no longer encouraged. Instead, all structure changes
+   should be made to the `Atoms` object.
 
-Below are a list of v0.1 method of the `SPARC` calculator and their current status in v0.2 API.
+Below are a list of v0.1 method of the `SPARC` calculator and their current status in v1.0 API.
 `calc` is an instance of `sparc.SPARC`.
 
 |  old methods           | status in v1.0 API |     alternatives                   |

diff --git a/_sources/basic_usage.md.txt b/_sources/basic_usage.md.txt
@@ -1,6 +1,6 @@
 # Basic Usage
 
-### 1. Read / write SPARC files
+## Read / write SPARC files
 
 In contrast to many other DFT codes, where the ASE I/O formats refer
 to a single file, `SPARC-X-API` operates on the whole calculation
@@ -27,9 +27,9 @@ atoms = Bulk("Al") * [4, 4, 4]
 atoms.write("test.sparc")
 ```
 
-For a deeper dive into the bundle I/O format, see [Advanced Topics](doc/advanced_topics.md).
+For a deeper dive into the bundle I/O format, see [Advanced Topics](advanced_topics.md).
 
-### 2. JSON Schema for SPARC calculator
+### JSON Schema for SPARC calculator
 
 A recurring challenge of Python interfaces to DFT codes it the
 inconsistencies between low-level codes (Fortran/C/C++) and outdated
@@ -50,10 +50,10 @@ python -m sparc.docparser <sparc-source-code-root>/doc/.LaTeX
 which produces a `parameters.json` file.
 
 To learn more about the JSON schema design, please refer to [Advanced
-Topics](doc/advanced_topics.md).
+Topics](advanced_topics.md).
 
 
-### 3. Calculator interface (File-IO mode)
+### Calculator interface (File-IO mode)
 
 `SPARC-X-API` offers a calculator interface based on file I/O that aligns with many
 other ASE calculators.  If you've worked with ASE modules like `Vasp`,
@@ -122,7 +122,7 @@ opt = LBFGS(atoms, alpha=90)
 opt.run(fmax=0.02)
 ```
 
-### 4. Command-line tools
+### Command-line tools
 
 A simple command wrapper `sparc-ase` is provided to add
 support of SPARC file formats to the `ase` cli tools. Simple
@@ -139,7 +139,7 @@ short [MD trajectory](tests/outputs/NH3_sort_lbfgs_opt.sparc).
 #### Fig 2. A screenshot of the `sparc-ase` program
 <img width="1200" alt="image" src="https://github.com/alchem0x2A/SPARC-X-API/assets/6829706/e72329ff-7194-4819-94f8-486ef2218844">
 
-### 5. Parameters and units used in `SPARC-X-API`
+### Parameters and units used in `SPARC-X-API`
 
 In the SPARC DFT code, all input parameters conventionally employ atomic units, such as Hartree and Bohr. Conversely, ASE objects (like `Atoms.positions`, `Atoms.cell`, `Atoms.get_potential_energy()`) utilize eV/Angstrom units.
 

diff --git a/_sources/contribute.md.txt b/_sources/contribute.md.txt
@@ -48,9 +48,11 @@ for pre-commit hooks used in this project, and change them if needed.
 
 ### Installing SPARC C/C++ binary
 
-If you need to test running DFT using the API, compile or install the `sparc` executables following the [manual](https://github.com/SPARC-X/SPARC/blob/master/README.md).
-
-**TODO** refer to the installation guide instead.
+If you need to test running DFT using the API, compile or install the
+`sparc` executables following the
+[manual](https://github.com/SPARC-X/SPARC/blob/master/README.md). Check
+[some examples](#install-the-sparc-binary-code) for our recommended
+approaches.
 
 
 ### Running tests
@@ -101,6 +103,11 @@ and then open `doc/_build/index.html` in a browser.
 Details about hosting the doc on Github pages please refer to the
 [maintenance guide](maintainers.md).
 
+```{note}
+1. Do not add contents directly in [`index.md`](https://github.com/SPARC-X/SPARC-X-API/blob/master/doc/index.md) except the `{toctree}` block for editing crosslinks.
+2. [`README.md`](https://github.com/SPARC-X/SPARC-X-API/blob/master/README.md) should be kept as concise as possible.
+```
+
 ### Adding examples
 
 All examples are listed in `examples/` directory. Please add examples

diff --git a/_sources/examples.md.txt b/_sources/examples.md.txt
@@ -1 +1,3 @@
 # Examples
+
+Examples can be found under the `examples/` directory.
diff --git a/_sources/index.md.txt b/_sources/index.md.txt
@@ -3,21 +3,13 @@
 :relative-docs: docs/
 :relative-images:
 ```
-<!-- # SPARC-X-API: A Python API for the SPARC-X DFT Code -->
-
-<!--  Through SPARC-X-API, users can -->
-<!-- easily integrate real-space SPARC calculations seamlessly into their -->
-<!-- existing atomistic simulation workflows, thanks to the calculator -->
-<!-- interface provided by ASE.  -->
-
-
 
 
 
 
 ```{toctree}
 :maxdepth: 2
-:caption: Contents:
+:caption: Contents
 introduction.md
 installation.md
 setup_environment.md

diff --git a/_sources/installation.md.txt b/_sources/installation.md.txt
@@ -4,13 +4,16 @@
 SPARC-X-API may be installed via the following approaches:
 
 (use-conda)=
-### Using [`conda`]() (recommended)
+### Using [`conda`](https://docs.conda.io/en/latest/) (recommended)
 
-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
+You can use any of [`anaconda`](https://docs.anaconda.com/),
+[`miniconda`](https://docs.anaconda.com/miniconda/), or
+[`micromamba`](https://mamba.readthedocs.io/en/latest/user_guide/micromamba.html)
+tools 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:
+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
@@ -32,7 +35,7 @@ conda activate sparc-env
 
 
 (pip-install)=
-### [`pip`]() install from source
+### [`pip`](https://pip.pypa.io/en/stable/cli/pip_install/) install from source
 
 You can installed the SPARC-X-API from the latest commit using `pip`
 
@@ -91,15 +94,18 @@ 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:
+MKL/MPICH on Georgia Tech's [Pheonix Cluster](https://sites.gatech.edu/ewanparktest/phoenix-cluster/):
 
+**TODO** make sure modules are correct.
 ```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
 ```
 
+**TODO** add module in script.
+
 The compiled binary will be at `SPARC/lib/sparc`, and running it
 requires the dependent modules to be loaded at runtime.
 

diff --git a/_sources/setup_environment.md.txt b/_sources/setup_environment.md.txt
@@ -115,15 +115,15 @@ sparc.sparc_json_api.default_json_api -->
 
 ### Pseudopotential files
 
-Pseudopotential files (in `Abinit` [psp8 format]() are loaded in the
+Pseudopotential files (in `Abinit` [psp8 format](https://docs.abinit.org/developers/psp8_info/) are loaded in the
 following order:
 
-1. Via the `psp_dir` argument passed to the `sparc.SPARC` calculator.
-2. Through the environment variables `$SPARC_PSP_PATH` or `$SPARC_PP_PATH` (this is the
- method employed by [`conda` installation](#1-via-anaconda-or-miniconda-recommended)).
-(manual-psp8)=
-3. By using `psp8` files bundled with the SPARC-X-API installation (see the
-[pip installation](#pip-install)).
+<!-- 1. Via the `psp_dir` argument passed to the `sparc.SPARC` calculator. -->
+<!-- 2. Through the environment variables `$SPARC_PSP_PATH` or `$SPARC_PP_PATH` (this is the -->
+<!--  method employed by [`conda` installation](#use-conda)). -->
+<!-- (manual-psp8)= -->
+<!-- 3. By using `psp8` files bundled with the SPARC-X-API installation (see the -->
+<!-- [pip installation](#pip-install)). -->
 
 To specify a custom path for your pseudopotential files (in Abinit [psp8 format]()),
 use the environment variable `$SPARC_PSP_PATH` or `$SPARC_PP_PATH` variable:
@@ -138,7 +138,7 @@ When installing SPARC [via `conda-forge`](#use-conda),
 conda environment.
 
 
-To determine the location of default psp8 files (as in [option 3](#manual-psp8)), run the following code:
+To determine the location of default psp8 files (as in [manual pip installation](#pip-install)), run the following code:
 ```bash
 python -c "from sparc.common import psp_dir; print(psp_dir)"
 ```
@@ -151,7 +151,7 @@ following priority:
 
 1. The command argument provided directly to the `sparc.SPARC` calculator.
 2. The environment variable `$ASE_SPARC_COMMAND`
-3. If neither of the above is defined, `SPARC-X-API` looks for the SPARC binary under current `$PATH` and combine with the suitable `mpi` command prefix.
+3. If neither of the above is defined, `SPARC-X-API` looks for the SPARC binary under current `$PATH` and combine with the suitable MPI command prefix.
 
 Example to set `$ASE_SPARC_COMMAND`
 
@@ -160,17 +160,16 @@ Example to set `$ASE_SPARC_COMMAND`
 export ASE_SPARC_COMMAND="mpirun -n 8 -mca orte_abort_on_non_zero_status 1 /path/to/sparc -name PREFIX"
 ```
 
-2. Using `srun` (e.g. in HPC slurm job system)
+2. Using `srun` (e.g. [SLURM](https://slurm.schedmd.com/documentation.html) job system HPCs)
 ```bash
 export ASE_SPARC_COMMAND="srun -n 8 --kill-on-bad-exit /path/to/sparc -name PREFIX"
 ```
 
-**TODO** sphinx's way for notes
-*Notes*:
-1. The `-name PREFIX` part can be omitted the `label` property of the `sparc.SPARC` calculator is set (which is the default behavior). Any extra features of the SPARC code (e.g. GPU acceleration) should be specified in the command.
+```{note}
+1. The `-name PREFIX` is optional and will automatically replaced by the `sparc.SPARC` calculator.
 
 2. We recommend adding kill switches for your MPI commands like the examples above when running `sparc` to avoid unexpected behaviors with exit signals.
-
+```
 
 ## Post-installation check
 
@@ -267,11 +266,15 @@ Please check additional information from:
 </div>
 ```
 
-
-When using SPARC-X-API to parse SPARC files, it's essential that at
-least the "Import" and "JSON API" tests are successful. For running
-SPARC calculations, "SPARC Command" and "Calculation (File I/O)" must
+```{note}
+1. When using SPARC-X-API to parse SPARC files, it's essential that at
+least the "Import" and "JSON API" tests are successful.
+2. For running
+SPARC calculations, "SPARC Command" and "Calculation (File I/O)" must also
 succeed.
+3. "Calculation (UNIX socket)" ensures the SPARC binary is compatible with socket communication,
+see [calculation in socket mode](advanced_socket.md).
+```
 
 If you run into further problems, consult our [troubleshooting
 guidlines](troubleshooting.md) or [raise an issue](contribute.md).