Add configuration file

.github/workflows/unit_test.yml

@@ -122,10 +122,10 @@ jobs:
     needs: test-linux
 
     steps:
-    - uses: actions/checkout@v3
+    - uses: actions/checkout@v4
     - uses: conda-incubator/setup-miniconda@v3
       with:
-        python-version: "3.10"
+        python-version: "3.11"
         mamba-version: "*"
         channels: conda-forge,defaults
         channel-priority: true
@@ -140,9 +140,11 @@ jobs:
         python -m sparc.download_data
     - name: Download SPARC output files to SPARC-master
       run: |
-        # TODO: merge to master
-        wget -O SPARC-socket.zip https://codeload.github.com/alchem0x2A/SPARC/zip/refs/heads/socket
-        unzip SPARC-socket.zip
+        # Use latest SPARC public code with socket support
+        HASH=99e4b7e94ca6f7b4ca1dde9135bea4075b0678f4
+        wget -O SPARC-socket.zip https://codeload.github.com/SPARC-X/SPARC/zip/$HASH
+        unzip SPARC-socket.zip && rm -rf SPARC-socket.zip
+        mv SPARC-$HASH SPARC-socket
     - name: Compile SPARC with socket
       run: |
         cd SPARC-socket/src

README.md

@@ -60,6 +60,22 @@ Install the pre-compiled SPARC binary alongside SPARC-X-API (Linux only).
 conda install -c conda-forge sparc-x
 ```
 
+### Setup SPARC-X-API
+
+Preferences for SPARC-X-API and SPARC C/C++ code can be defined in ASE [configuration file](https://wiki.fysik.dtu.dk/ase/ase/calculators/calculators.html#calculator-configuration), located at `~/.config/ase/config.ini`, such as following example:
+
+```ini
+[sparc]
+; `command`: full shell command (include MPI directives) to run SPARC
+command = srun -n 24 path/to/sparc
+
+; `psp_path`: directory containing pseudopotential files (optional)
+psp_path = path/to/SPARC/psps
+
+; `doc_path`: directory for SPARC LaTeX documentation to build JSON schema on the fly (optional)
+doc_path = path/to/SPARC/doc/.LaTeX/
+```
+
 ### Reading / Writing SPARC files
 
 SPARC-X-API provides a file format `sparc` compatible with the ASE
@@ -68,12 +84,14 @@ in-/output files as a bundle:
 
 - Read from a SPARC bundle
 ```python
+# `format="sparc"` should be specified
 from ase.io import read
 atoms = read("sparc_calc_dir/", format="sparc")
 ```
 
 - Write input files
 ```python
+# `format="sparc"` should be specified
 from ase.build import Bulk
 atoms = Bulk("Al") * [4, 4, 4]
 atoms.write("sparc_calc_dir/", format="sparc")

doc/advanced_socket.md

@@ -21,10 +21,14 @@ Fig. 1. SPARC electronic calculations with socket communication across hybrid co
 ```
 
 **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
+code with socket
+support and with the
 `USE_SOCKET=1` flag enabled (see the [installation
-instructions](https://github.com/alchem0x2A/SPARC/tree/socket).
+instructions](https://github.com/SPARC-X/SPARC?tab=readme-ov-file#2-installation).
+
+```{note}
+You need SPARC C/C++ after version 2024.11.18 to enable socket support.
+```
 
 ## Usage
 The socket communication layer in SPARC and SPARC-X-API are designed for:
@@ -38,11 +42,11 @@ 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 as shown in [Fig. 2](#SPARC-protocol-overview):
+providing the following features as shown in [Fig. 2](#scheme-sparc-protocol):
 
-(scheme-sparc-protocol)=
 ```{figure} img/scheme_sparc_protocol.png
 :alt: scheme-sparc-protocol
+:name: scheme-sparc-protocol
 
 Fig. 2. Overview of the SPARC protocol as an extension to the standard i-PI protocol.
 ```
@@ -51,8 +55,8 @@ Based on the scenarios, the socket communication layer can be accessed
 via the following approaches as shown in
 [Fig. 3](#scheme-sparc-modes):
 
-(scheme-sparc-modes)=
 ```{figure} img/scheme-SPARC-socket-modes.png
+:name: scheme-sparc-modes
 :alt: scheme-sparc-modes
 
 Fig. 3. Different ways of using SPARC's socket mode.
@@ -81,7 +85,7 @@ Fig. 3. Different ways of using SPARC's socket mode.
    to be run on a single computer system.
 
 
-2. **Local-only Mode** ([Fig. 3](#scheme-sparc-modes) **b**)
+2. **Local-only mode** ([Fig. 3](#scheme-sparc-modes) **b**)
 
    Ideal for standalone calculations, this mode simulates a conventional calculator while benefiting from socket-based efficiency.
 
@@ -91,7 +95,7 @@ Fig. 3. Different ways of using SPARC's socket mode.
    ```
    For most users we recommend using this mode when performing a calculation on a single HPC node.
 
-3. **Client (Relay) Mode** ([Fig. 3](#scheme-sparc-modes) **c**)
+3. **Client (Relay) mode** ([Fig. 3](#scheme-sparc-modes) **c**)
 
    In this mode, the `sparc.SPARC` calculator servers as a passive
    client which listens to a remote i-PI-compatible server. When
@@ -119,7 +123,7 @@ Fig. 3. Different ways of using SPARC's socket mode.
    automatically determine if it is necessary to restart the SPARC
    subprocess.
 
-4. **Server Mode** ([Fig. 3](#scheme-sparc-modes) **d**)
+4. **Server mode** ([Fig. 3](#scheme-sparc-modes) **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

doc/advanced_topics.md

@@ -93,7 +93,7 @@ old_atoms.get_potential_energy()
 ```
 
 
-
+(rule-input-param)=
 ## Rules for input parameters in `sparc.SPARC` calculator
 
 When constructing the `sparc.SPARC` calculator using the syntax

doc/basic_usage.md

@@ -13,7 +13,7 @@ file format:
 ```python
 import sparc
 from ase.io import read, write
-atoms = read("test.sparc", index=-1)
+atoms = read("test.sparc", index=-1, format="sparc")
 ```
 *Note*: To read multiple output files from the same directory, e.g., SPARC.aimd, SPARC.aimd\_01, pass the keyword argument `include_all_files=True` to `read()`
 
@@ -24,7 +24,11 @@ import sparc
 from ase.io import read, write
 from ase.build import Bulk
 atoms = Bulk("Al") * [4, 4, 4]
-atoms.write("test.sparc")
+atoms.write("test.sparc", format="sparc")
+```
+
+```{note}
+You need to specify `format="sparc"` when using the `read` and `write` functions from `ase.io`, as automatic file extension detection doesn't work for directories.
 ```
 
 For a deeper dive into the bundle I/O format, see [Advanced Topics](advanced_topics.md).
@@ -109,7 +113,7 @@ If you want to extract more information about the MD simulation steps, take a lo
 
 4. Geometric optimization using ASE's optimizers
 
-The power of `SPARC-X-API` is to combine single point `SPARC` calculations with advanced ASE optimizers, such as BFGS, FIRE or GPMin. Example 2 can be re-written as:
+The power of `SPARC-X-API` is to combine single point `SPARC` calculations with advanced ASE optimizers, such as `BFGS`, `FIRE` or `GPMin`. Example 2 can be re-written as:
 
 ```python
 from sparc.calculator import SPARC
@@ -133,11 +137,14 @@ for the visualization of atomistic structures. Depending on the
 bundle's contents, this could display individual atoms or multiple
 images.
 
-[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. 1](#fig-screenshot-sparc-ase) is a screenshot showing the usage of `sparc-ase gui` to visualize a
+short MD trajectory.
 
-#### 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">
+(fig-screenshot-sparc-ase)=
+```{figure} https://github.com/alchem0x2A/SPARC-X-API/assets/6829706/e72329ff-7194-4819-94f8-486ef2218844
+
+Fig 1. A screenshot of the `sparc-ase` program
+```
 
 ### Parameters and units used in `SPARC-X-API`
 
@@ -149,7 +156,7 @@ atoms.calc = SPARC(h=0.25, REFERENCE_CUTOFF=0.5, EXX_RANGE_PBE=0.16, **params)
 ```
 inputs following ASE's convention (e.g., `h`) adopt eV/Angstrom units (thus the same setting can be applied to other DFT calculators),
 On the other hand, all SPARC-specific parameters, which can often be recognized by their capitalized format (like `REFERENCE_CUTOFF`, `EXX_RANGE_PBE`), retain their original values consistent with their representation in the `.inpt` files.
-The reasoning and details about unit conversion can be found in the [Rules for Input Parameters](https://github.com/alchem0x2A/SPARC-X-API/blob/master/doc/advanced_topics.md#rules-for-input-parameters-in-sparcsparc-calculator)  in Advanced Topics.
+The reasoning and details about unit conversion can be found in the [Rules for Input Parameters](#rule-input-param)  in Advanced Topics.
 
 
 In order for `SPARC-X-API` to be compatible with other ASE-based DFT calculators,

doc/contribute.md

@@ -51,7 +51,7 @@ for pre-commit hooks used in this project, and change them if needed.
 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
+[some examples](#install-binary) for our recommended
 approaches.
 
 
@@ -109,7 +109,7 @@ flavor](https://myst-parser.readthedocs.io/en/latest/) of
 Markdown. The source `.md` files, together with the main `README.md`
 are then rendered to html files using `sphinx`.
 
-After [setting up the test environment](#setting-up-environment),
+After [setting up the test environment](setup_environment.md),
 additional packages for doc rendering can be installed via:
 ```bash
 cd SPARC-X-API
@@ -145,55 +145,7 @@ computating power (e.g. a few minutes with 4 CPU cores).
 Please check the [maintenance guide](maintainers.md) for roles
 involving admin privileges.
 
-<!-- ### Code structure -->
-
-<!-- Below is a brief overview of the modules in `SPARC-X-API` with simple explanations -->
-<!-- ``` -->
-<!-- sparc -->
-<!-- ├── __init__.py -->
-<!-- ├── api.py                 # Includes SparcAPI class for parameter validation -->
-<!-- ├── calculator.py          # Interface to the SPARC DFT code -->
-<!-- ├── cli.py                 # `sparc-ase` interface -->
-<!-- ├── common.py              # Definition of common directories -->
-<!-- ├── docparser.py           # Function and cli interface for parsing the SPARC DFT document -->
-<!-- ├── download_data.py       # Cli tool to download pseudopotential files -->
-<!-- ├── io.py                  # Provides `SparcBundle` class, `read_sparc` and `write_sparc` functions -->
-<!-- ├── quicktest.py           # Cli tool for post-installation sanity check -->
-<!-- ├── utils.py               # Common utilities -->
-<!-- ├── psp/                   # Place-holder directory for pseudopotentials (used for `download_data.py`) -->
-<!-- ├── sparc_json_api         # Directory for maintaining the JSON API -->
-<!-- │   └── parameters.json -->
-<!-- ├── sparc_parsers          # Parsers for individual SPARC in-/output formats -->
-<!-- │   ├── __init__.py -->
-<!-- │   ├── aimd.py -->
-<!-- │   ├── atoms.py -->
-<!-- │   ├── geopt.py -->
-<!-- │   ├── inpt.py -->
-<!-- │   ├── ion.py -->
-<!-- │   ├── out.py -->
-<!-- │   ├── pseudopotential.py -->
-<!-- │   ├── static.py -->
-<!-- │   └── utils.py -->
-<!-- ``` -->
-
-<!-- ### CI/CD by Github Actions -->
-
-<!-- The repo contains a few CI/CD pipelines based on Github Actions. You -->
-<!-- may need to take care of the settings if you're one of the -->
-<!-- maintainers. For normal code contributors, this section may be -->
-<!-- omitted. -->
-
-<!-- - Unit test -->
-
-<!-- The steps are described [here](.github/workflows/installation_test.yml). -->
-<!-- Please make sure to exclude any computationally-heavy tests from the step "Test with pytest". -->
-
-<!-- - Coverage -->
-
-<!-- The CI workflow contains a coverage report step based on the unit test -->
-<!-- and generates a [coverage -->
-<!-- badge](https://github.com/SPARC-X/SPARC-X-API/blob/badges/badges/coverage.svg) -->
-<!-- on the [`badges` -->
-<!-- branch](https://github.com/SPARC-X/SPARC-X-API/tree/badges). -->
-
-<!-- For repo maintainers, please make sure the `badges` branch is present and **do not merge to this branch**. -->
+```{toctree}
+:max_depth: 1
+test_coverage.md
+```