Merge pull request #68 from alchem0x2A/master

enhance doc

.github/workflows/unit_test.yml

@@ -1,4 +1,4 @@
-name: Unit tests for SPARC-X-API
+name: Unit tests
 
 on:
   push:
@@ -60,7 +60,7 @@ jobs:
         PIPVER=`pip show sparc-x-api | grep Version | cut -d ' ' -f2`
         anybadge --value=$PIPVER --file=badges/package.svg -l sparc-x-api
         # api version badge
-        anybadge --value=${API_VERSION} --file=badges/api_version.svg -l "json-api version"
+        anybadge --value=${API_VERSION} --file=badges/api_version.svg -l "JSON schema version"
     - name: Manually add git badges
       run: |
         # Assuming a badges branch already exists!

README.md

@@ -1,7 +1,7 @@
 # SPARC-X-API: A Python API for the SPARC-X DFT Code
 [![Package](https://raw.githubusercontent.com/SPARC-X/SPARC-X-API/badges/badges/package.svg)](https://raw.githubusercontent.com/SPARC-X/SPARC-X-API/badges/badges/package.svg)
 [![Coverage](https://raw.githubusercontent.com/SPARC-X/SPARC-X-API/badges/badges/coverage.svg)](https://raw.githubusercontent.com/SPARC-X/SPARC-X-API/badges/badges/coverage.svg)
-[![Unit tests](https://github.com/SPARC-X/SPARC-X-API/actions/workflows/installation_test.yml/badge.svg)](https://github.com/SPARC-X/SPARC-X-API/actions/workflows/installation_test.yml)
+[![Unit tests for SPARC-X-API](https://github.com/SPARC-X/SPARC-X-API/actions/workflows/unit_test.yml/badge.svg)](https://github.com/SPARC-X/SPARC-X-API/actions/workflows/unit_test.yml)
 [![JSON-API](https://raw.githubusercontent.com/SPARC-X/SPARC-X-API/badges/badges/api_version.svg)](https://raw.githubusercontent.com/SPARC-X/SPARC-X-API/badges/badges/api_version.svg)
 
 

doc/advanced_socket.md

@@ -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

doc/advanced_topics.md

@@ -1,10 +1,8 @@
 # Advanced Topics
-<!-- TODO move this section with package components -->
-## Advanced Topics
 The design of `SPARC-X-API` is schematically shown in the following figure
 <img width="929" alt="image" src="https://github.com/alchem0x2A/sparc-dft-api/assets/6829706/3419b1c4-3c56-4fd1-a6de-1ce2aea426e7">
 
-### Behind the bundle file format
+## Behind the bundle file format
 
 Instead of parsing individual `.ion` and `.inpt` files,
 the bundle format (recognized by ASE by `format="sparc"`) will
@@ -36,7 +34,7 @@ Each `_read_<format>` method will return the structured raw-data dictionary of t
 Similarly, `_write_<format>` takes the structured dictionary as input and write the file
 using only relevant data.
 
-### Behind the JSON API
+## Behind the JSON API
 
 The JSON API are directly parsed from the `SPARC` documentation [LaTeX files](https://github.com/SPARC-X/SPARC/tree/master/doc/.LaTeX).
 The JSON API file (`sparc/sparc_json_api/parameters.json`) distributed by `SPARC-X-API` is generated by:
@@ -77,7 +75,7 @@ from sparc.api import SparcAPI
 sis = SparcAPI()
 ```
 
-### Retriving parameters from old SPARC calculations
+## Retriving parameters from old SPARC calculations
 
 `sparc.SPARC` calculator supports the `restart` mode which will reconstruct all
 parameters, psp files and atomic information from an existing SPARC calculation and
@@ -96,7 +94,7 @@ old_atoms.get_potential_energy()
 
 
 
-### Rules for input parameters in `sparc.SPARC` calculator
+## Rules for input parameters in `sparc.SPARC` calculator
 
 When constructing the `sparc.SPARC` calculator using the syntax
 ```python
@@ -114,7 +112,7 @@ We accept parameters in both upper and lower cases, in other words, `FD_GRID=[10
 Additionally, boolean inputs (i.e. `PRINT_FORCES`) can be written in both integer or boolean values.
 
 
-### Multiple occurance of output files
+## Multiple occurance of output files
 
 In a typical SPARC calculation, there may be multiple result files in the SPARC bundle, with different suffixes (e.g. `.out`, `.out_01`, `.out_02` etc.).
 These files can be a result of restarted geometry optimization / AIMD or written by an ASE optimizer.

doc/api_changes.md

@@ -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                   |

doc/basic_usage.md

@@ -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.
 

doc/conf.py

@@ -33,3 +33,7 @@
 
 html_theme = "sphinx_rtd_theme"
 html_static_path = ["_static"]
+
+myst_enable_extensions = [
+    "html_admonition",
+]