Merge pull request #44 from alchem0x2A/master

Update doc and schemes for socket mode

.gitignore

@@ -782,3 +782,5 @@ examples/ex1-ase/
 /*.psp8
 /test-1/
 /test-2/
+*.pt
+/README.html

README.md

@@ -4,11 +4,27 @@
 [![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)
 [![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)
 
+# Table of Contents
+- [Installation](#installation)
+- [Setting Up Environment](#setting-up-the-environment)
+- [Basic Usage](#basic-usage-of-the-python-api)
+- [Advanced Usage: Socket Interface](#advanced-usage-sparc-x-api-as-a-socket-interface)
+- [Troubleshooting](#troubleshooting)
+- [Advanced Topics](#advanced-topics)
+- [Support and Contribution](#how-to-contribute)
+
 `SPARC-X-API` is an [ASE](https://wiki.fysik.dtu.dk/ase/)-compatible Python API for the density functional theory (DFT) code [SPARC](https://github.com/SPARC-X/SPARC). It offers:
 
 1. ASE-compatible I/O format for SPARC files
-2. A JSON API interfacing with SPARC's C-code for parameter validation and conversion
-3. A comprehensive calculator interface for SPARC.
+2. A JSON Schema interfacing with SPARC's C-code for parameter validation and conversion
+3. A comprehensive calculator interface for SPARC with socket-communication support.
+
+
+[Fig. 1](#fig-1-schematic-drawing-for-the-architecture-of-the-sparc-x-api-package) provides an overlook of the components of `SPARC-X-API` and its relation with the SPARC C-code.
+
+#### Fig. 1 Schematic drawing for the architecture of the `SPARC-X-API` package
+![scheme-sparc-api-outlook](doc/img/scheme_api_architecture.png)
+
 
 
 ## Installation:
@@ -53,7 +69,7 @@ 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:
 
@@ -206,9 +222,9 @@ To learn more about the JSON schema design, please refer to [Advanced
 Topics](doc/advanced_topics.md).
 
 
-### 3. Calculator interface
+### 3. Calculator interface (File-IO mode)
 
-`SPARC-X-API` offers a calculator interface that aligns with many
+`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`,
 `QuantumEspresso`, or `GPAW`, you'll find this package intuitive,
 as shown in the following examples:
@@ -277,7 +293,7 @@ opt.run(fmax=0.02)
 
 ### 4. Command-line tools
 
-`SPARC-X-API` provides a simple command wrapper `sparc-ase` to add
+A simple command wrapper `sparc-ase` is provided to add
 support of SPARC file formats to the `ase` cli tools. Simple
 replace `ase [subcommand] [args]` with `sparc-ase [subcommand] [args]`
 to access your SPARC bundle files as you would use for other file
@@ -286,9 +302,10 @@ for the visualization of atomistic structures. Depending on the
 bundle's contents, this could display individual atoms or multiple
 images.
 
-Below is a screenshot showing the usage of `sparc-ase gui` to visualize a
+[Fig. 2](#fig-2-a-screenshot-of-the-sparc-ase-program) is a screenshot showing the usage of `sparc-ase gui` to visualize a
 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`
@@ -362,15 +379,22 @@ calc = SPARC(xc="PBE", kpts=(9, 9, 9), h=0.25, directory="sparc-calc.sparc", con
 *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
-Experienced users can now harness the power of SPARC and SPARC-X-API's
+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
 interface directly into SPARC, users can significantly reduce the
 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.
+bottleneck. The underlying software architecture is shown in [Fig. 3](#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)
+
+
+
 
 **Requirements**: the SPARC binary must be manually compiled from the source
 code with [socket
@@ -389,15 +413,18 @@ adheres to the [i-PI protocol](https://github.com/i-pi/i-pi)
 standard. Specifically, we implement the original i-PI protocol within
 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:
+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)
+
+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):
 
-1. **Unified Interface**: A consistent interface for both client and server codes, simplifying user interaction across different modes.
-2. **Versatile Operation Modes:** Supports various modes (Local-only, Client, Server) to cater to diverse computational needs.
-3. **Seamless Calculation Restart:** Automates the restarting process on the client side, enhancing user convenience.
+#### Fig. 5. Different ways of using SPARC's socket mode.
+![scheme-sparc-modes](doc/img/scheme-SPARC-socket-modes.png)
 
-Based on the user scenarios, the socket communication layer can be accessed via the following approaches:
 
-1. **SPARC binary only**
+1. **SPARC binary only** ([Fig. 5](#fig-5-different-ways-of-using-sparcs-socket-mode) **a**)
 
  SPARC binary with socket support can be readily coupled with any i-PI compatible socker server, such as
  `ase.calculators.socketio.SocketIOCalculator`, for example
@@ -419,7 +446,7 @@ Based on the user scenarios, the socket communication layer can be accessed via
  to be run on a single computer system. 
 
 
-2. **Local-only Mode**
+2. **Local-only Mode** ([Fig. 5](#fig-5-different-ways-of-using-sparcs-socket-mode) **b**)
 
  Ideal for standalone calculations, this mode simulates a conventional calculator while benefiting from socket-based efficiency.
 
@@ -429,7 +456,7 @@ Based on the user scenarios, the socket communication layer can be accessed via
  ```
  For most users we recommend using this mode when performing a calculation on a single HPC node.
 
-3. **Client (Relay) Mode** 
+3. **Client (Relay) Mode** ([Fig. 5](#fig-5-different-ways-of-using-sparcs-socket-mode) **c**)
 
  In this mode, the `sparc.SPARC` calculator servers as a passive
  client which listens to a remote i-PI-compatible server. When
@@ -457,7 +484,7 @@ Based on the user scenarios, the socket communication layer can be accessed via
  automatically determine if it is necessary to restart the SPARC
  subprocess.
 
-4. **Server Mode**
+4. **Server Mode** ([Fig. 5](#fig-5-different-ways-of-using-sparcs-socket-mode) **d**)
 
  Paired with the client mode in (3), SPARC-X-API can be run as a
  socket server, isolated from the node that performs the
@@ -482,7 +509,8 @@ Based on the user scenarios, the socket communication layer can be accessed via
 
 ### (In-progress) Controlling SPARC routines from socket interface
 
-Our SPARC socket protocol designs allows bidirectional control of
+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
 internal SPARC routines. Local- or server-mode `sparc.SPARC`
 calculators can communicate with the SPARC binary via functions like
 `set_params`. This can be useful for applications like on-the-fly