From d3d966be256d466e4eff040047f24865e2d26bae Mon Sep 17 00:00:00 2001 From: "T.Tian" Date: Tue, 5 Nov 2024 18:34:37 +0800 Subject: [PATCH] move docs --> doc --- .github/workflows/publish_doc_pages.yml | 10 +- .gitignore | 1 + README.md | 97 +- {docs => doc}/Makefile | 0 {docs => doc}/advanced_socket.md | 0 doc/advanced_topics.md | 2 + {docs => doc}/api_changes.md | 0 {docs => doc}/basic_usage.md | 0 doc/changes_v0.1.md | 50 - {docs => doc}/conf.py | 0 {docs => doc}/contribute.md | 0 doc/contribution_guideline.md | 102 - {docs => doc}/examples.md | 0 doc/img/fig_sparc_api_overview.svg | 2319 +++++++++++++++++++++++ doc/index.md | 37 +- {docs => doc}/installation.md | 0 {docs => doc}/introduction.md | 0 doc/maintainers.md | 37 + {docs => doc}/make.bat | 0 {docs => doc}/package_components.md | 0 {docs => doc}/setup_environment.md | 0 doc/troubleshooting.md | 1 + docs/advanced_topics.md | 134 -- docs/index.md | 31 - docs/maintainers.md | 1 - docs/troubleshooting.md | 6 - 26 files changed, 2437 insertions(+), 391 deletions(-) rename {docs => doc}/Makefile (100%) rename {docs => doc}/advanced_socket.md (100%) rename {docs => doc}/api_changes.md (100%) rename {docs => doc}/basic_usage.md (100%) delete mode 100644 doc/changes_v0.1.md rename {docs => doc}/conf.py (100%) rename {docs => doc}/contribute.md (100%) delete mode 100644 doc/contribution_guideline.md rename {docs => doc}/examples.md (100%) create mode 100644 doc/img/fig_sparc_api_overview.svg rename {docs => doc}/installation.md (100%) rename {docs => doc}/introduction.md (100%) create mode 100644 doc/maintainers.md rename {docs => doc}/make.bat (100%) rename {docs => doc}/package_components.md (100%) rename {docs => doc}/setup_environment.md (100%) delete mode 100644 docs/advanced_topics.md delete mode 100644 docs/index.md delete mode 100644 docs/maintainers.md delete mode 100644 docs/troubleshooting.md diff --git a/.github/workflows/publish_doc_pages.yml b/.github/workflows/publish_doc_pages.yml index a2f7765..8b2eab4 100644 --- a/.github/workflows/publish_doc_pages.yml +++ b/.github/workflows/publish_doc_pages.yml @@ -4,12 +4,12 @@ on: push: branches: - master - - 'docs/**' + - 'doc/**' pull_request: branches: - master paths: - - 'docs/**' + - 'doc/**' workflow_dispatch: @@ -34,17 +34,17 @@ jobs: pip install -e ".[doc]" - name: Build sphix doc run: | - sphinx-build docs docs/_build + sphinx-build doc doc/_build - name: Deploy to github pages uses: peaceiris/actions-gh-pages@v4 if: github.ref == 'refs/heads/master' && github.event_name == 'push' with: github_token: ${{ secrets.GITHUB_TOKEN }} publish_branch: gh_pages - publish_dir: docs/_build + publish_dir: doc/_build - name: Upload preview when creating pull request if: github.event_name == 'pull_request' uses: actions/upload-artifact@v3 with: name: docs_build_preview - path: docs/_build + path: doc/_build diff --git a/.gitignore b/.gitignore index cc5cbc8..b68ac11 100644 --- a/.gitignore +++ b/.gitignore @@ -784,3 +784,4 @@ examples/ex1-ase/ /test-2/ *.pt /README.html +/doc/_build/ diff --git a/README.md b/README.md index 01e779a..d3df679 100644 --- a/README.md +++ b/README.md @@ -7,10 +7,8 @@ SPARC-X-API is a versatile Python API for the real-space density functional (DFT) package [SPARC](https://github.com/SPARC-X/SPARC) -(**S**imulation **P**ackage for **A**b-initio **R**eal-**S**pace -**C**alculations) distributed under the GPLv3 license. -SPARC-X-API -leverages the powerful Atomic Simulation Environment +distributed under the GPLv3 license. SPARC-X-API leverages the +powerful Atomic Simulation Environment ([ASE](https://wiki.fysik.dtu.dk/ase/)) framework for manipulating input / output files, as well as running DFT calculations and analysis via the SPARC code written in C/C++. Key features include: @@ -19,7 +17,27 @@ via the SPARC code written in C/C++. Key features include: 2. A JSON Schema interfacing with SPARC's C/C++ code for parameter validation and conversion 3. A comprehensive calculator interface for SPARC with file I/O and socket-communication support. -## +## Overview + +SPARC-X-API is part of the [SPARC-X +project](https://github.com/SPARC-X), a collection of open-source +packages aim to provide modern and efficient implementation of real +space DFT simulations, led by the research groups of Phanish +Suryanarayana and Andrew J. Medford from Georgia Tech. The name SPARC +stands for **S**imulation **P**ackage for **A**b-initio +**R**eal-**S**pace **C**alculations, which comes in two variations: +- [**M-SPARC**](https://github.com/SPARC-X/M-SPARC): self-consistent + Matlab code for algorithm prototyping and testing +- [**SPARC**](https://github.com/SPARC-X/SPARC): C/C++ implementation + of efficient production code scaling up to millions of atoms + +The SPARC-X project shares common input / output file formats, and +parameter specification. SPARC-X-API serves as the interface that +connects the core SPARC-X components with external workflows, as +illustrated in the diagram below. + +![Overview of SPARC-X-API](doc/img/fig_sparc_api_overview.svg) + ## Quick start @@ -28,21 +46,17 @@ standard for seamless integration into other computational workflows. ### Installation -We recommend to use the -[`conda`](https://docs.conda.io/projects/conda/en/latest/index.html) -for installation on UNIX systems. +Install SPARC-X-API via +[`conda`](https://docs.conda.io/projects/conda/en/latest/index.html). ```bash conda install -c conda-forge sparc-x-api ``` -You can also install the pre-compiled SPARC binary alongside SPARC-X-API (Linux only). +Install the pre-compiled SPARC binary alongside SPARC-X-API (Linux only). ```bash conda install -c conda-forge sparc-x ``` -More installation options please see documentations for [installation]() and -[environment setup](). - ### Reading / Writing SPARC files SPARC-X-API provides a file format `sparc` compatible with the ASE @@ -86,8 +100,9 @@ print(SparcAPI().help_info("LATVEC")) SPARC-X-API provides two ways to run a DFT calculation via SPARC C/C++ code: -1. **File I/O mode**: generate input files, run a standard SPARC - process and read results until calculation finishes. Suitable for: +1. **File I/O mode**: classic way to drive SPARC calculation by + running a standard SPARC process with input files. Suitable for + things implemented internally in SPARC C/C++ codes: - Single point evaluation - Band structure calculations - Structural optimization (SPARC internal routines) @@ -116,17 +131,12 @@ atoms.get_potential_energy() atoms.get_forces() ``` - - - - - #### Socket mode -With just a few parameters, you can switch to the socket mode, ideal -for evaluating hundreds or thousands of single point DFT energy and -forces with much less overhead and more flexibility compared with the -file I/O mode: +Switching to the socket mode requires just a few parameters, ideal for +workflows with hundreds or thousands of single point DFT calls with +much less overhead and more flexibility. An example for optimization +using socket mode and ASE optimizer: ```python from sparc.calculator import SPARC @@ -140,7 +150,11 @@ with atoms.calc: opt.run(fmax=0.01) ``` - +## Documentation +Please check the [full +documentation](https://sparc-x.github.io/SPARC-X-API) for details +regarding installation, usage, troubleshooting and contribution +guidelines. ## How to cite If you find SPARC-X-API help, please consider cite the relevant @@ -158,38 +172,7 @@ For a full list of publications in the SPARC-X project please refer to: - [M-SPARC development](https://github.com/SPARC-X/M-SPARC?tab=readme-ov-file#6-citation) - [Pseudopotentials](https://github.com/SPARC-X/SPMS-psps?tab=readme-ov-file#citation) -## Documentation - -Please check the [full -documentation](https://sparc-x.github.io/sparc-x-api) for details -regarding installation, usage, troubleshooting and contribution -guidelines. - ## Acknowledgment -The authors gratefully acknowledge the support of the U.S. Department -of Energy, Office of Science, under Grant No. DE-SC0019410 and +The development of SPARC-X-API is supported by the U.S. Department of +Energy, Office of Science, under Grant No. DE-SC0019410 and DE-SC0023445. - - - - - - - - - - - - - - - - - - - - - - - - diff --git a/docs/Makefile b/doc/Makefile similarity index 100% rename from docs/Makefile rename to doc/Makefile diff --git a/docs/advanced_socket.md b/doc/advanced_socket.md similarity index 100% rename from docs/advanced_socket.md rename to doc/advanced_socket.md diff --git a/doc/advanced_topics.md b/doc/advanced_topics.md index 74b71ce..03893f6 100644 --- a/doc/advanced_topics.md +++ b/doc/advanced_topics.md @@ -1,3 +1,5 @@ +# Advanced Topics + ## Advanced Topics The design of `SPARC-X-API` is schematically shown in the following figure image diff --git a/docs/api_changes.md b/doc/api_changes.md similarity index 100% rename from docs/api_changes.md rename to doc/api_changes.md diff --git a/docs/basic_usage.md b/doc/basic_usage.md similarity index 100% rename from docs/basic_usage.md rename to doc/basic_usage.md diff --git a/doc/changes_v0.1.md b/doc/changes_v0.1.md deleted file mode 100644 index b7d30d5..0000000 --- a/doc/changes_v0.1.md +++ /dev/null @@ -1,50 +0,0 @@ -## Major changes from `SPARC-X-API` [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. -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: -```python -# ASE-SORT: -# 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. - -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. - -For more discussion please see [Advanced Topic] section. - -Below are a list of v0.1 method of the `SPARC` calculator and their current status in v0.2 API. -`calc` is an instance of `sparc.SPARC`. - -| old methods | status in v1.0 API | alternatives | -|------------------------|--------------------|------------------------------------| -| `interpret_grid_input` | deprecated | `calc.set(fd_grid=[20, 20, 20])` | -| `interpret_kpoint_input` | deprecated | `calc.set(kpts=[3, 3, 3])` | -| `interpret_downsampling_input` | deprecated | Manual setting not recommended | -| `interpret_kpoint_shift` | deprecated | `calc.set(kpoint_shift=[0, 0, 0])` | -| `get_pseudopotential_directory` | deprecated | `calc.psp_dir` | -| `get_nstates` | maintained | | -| `setup_parallel_env` | deprecated | Manual set | -| `generate_command` | deprecated | `calc._make_command()` | -| `estimate_memory` | maintained | | -| `get_scf_steps` | maintained | | -| `get_geometric_steps` | deprecated | `calc.get_number_of_ionic_steps()`| -| `get_runtime` | maintained | | -| `get_fermi_level` | maintained | | -| `concatinate_output` | deprecated | Use `sparc.SparcBundle` instead | -| `read_line` | deprecated | Use `sparc.SparcBundle` instead | -| `parse_output` | deprecated | `calc.read_results()` | -| `parse_relax` | deprecated | `calc.read_results()` | -| `parse_md` | deprecated | `calc.read_results()` | -| `parse_input_args` | deprecated | `calc.set(**kwargs)` | -| `recover_index_order_from_ion_file` | deprecated | Use `calc.sort` and `calc.resort` | -| `atoms_dict` | deprecated | Use third party library like `bson` | -| `dict_atoms` | deprecated | Use third party library like `bson` | diff --git a/docs/conf.py b/doc/conf.py similarity index 100% rename from docs/conf.py rename to doc/conf.py diff --git a/docs/contribute.md b/doc/contribute.md similarity index 100% rename from docs/contribute.md rename to doc/contribute.md diff --git a/doc/contribution_guideline.md b/doc/contribution_guideline.md deleted file mode 100644 index 13a62d7..0000000 --- a/doc/contribution_guideline.md +++ /dev/null @@ -1,102 +0,0 @@ -## Submitting issues and pull requests -We welcome users of SPARC-X and SPARC-X-API to submit issues and pull requests via github. -When reporting a bug, please make sure to include the following information: - -- `SPARC` version (if available. Should look like "Month Day, Year" in the `.out` file) -- `SPARC-X-API` version or commit hash -- Minimal example for reproducing the error -- Error trace message - -## Notes for developers - -We recommend the following steps to setup the test environment and modify codes - -### Setting up environment - -Pip installation from github's master branch (or your own fork), and download -a copy of the latest pseudopotential files. - -```python -git clone https://github.com/SPARC-X/SPARC-X-API.git -pip install -e "sparc-x-api[test]" -python -m sparc.download_data -``` - -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). - - -### Running tests - -All unit tests are based on `pytest` and inside `tests/` directory. -To run all tests (no heavy DFT calculations): -```python -python -m pytest -svv tests/ -``` - -If you are on a HPC environment, you can opt to run a comprehensive test suite with DFT calculations: -```python -python -m pytest -svv tests/test_all_dft.py -``` - -(*Draft, to be implemented later*) - -### Adding examples - -All examples are listed in `examples/` directory. Please add examples that are important -for demonstrating the functionalities of `SPARC-X-API` while the calculations can be -finished using moderate computating power (e.g. a few minutes with 4 CPU cores). - -The examples can have the name in the format `ex[Number]-[purpose].py`. - -### 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**. diff --git a/docs/examples.md b/doc/examples.md similarity index 100% rename from docs/examples.md rename to doc/examples.md diff --git a/doc/img/fig_sparc_api_overview.svg b/doc/img/fig_sparc_api_overview.svg new file mode 100644 index 0000000..a502d76 --- /dev/null +++ b/doc/img/fig_sparc_api_overview.svg @@ -0,0 +1,2319 @@ + + + +.inpt.ion.static.geopt.aimd.outM-SPARC (Matlab)•Matlab Routines •Algorithm prototyping•Small-to-medium systemsSPARC (C/C++)•MKL/BLAS + MPI •Production code•Scalable >O(104) atomsSPARC-X-API (PY3)•ASE-standard interface•General-purpose API •Complex worflows"CALC_STRESS": { "symbol": "CALC_STRESS", "label": "CALC_STRESS", "type": "integer", "default": 0, "unit": "No unit", "example": "CALC_STRESS: 1", "description": "Flag for ...", ... },I-PIPLUMEDShared ComponentsInput / Output FilesLaTeX DocumentationJSON SchemaExternal DFT CodesHigh-throughput DynamicsMachine LearningFAIR-ChemMACE-MPsparc.io• File I/O manipulation• Bundle file formatsparc.api• SPARC compatibility check• Parameter validationsparc.calculator• File-I/O calculations• Socket calculationssparc.docparserSimulation Package for Ab-initio Real-Space Calculations diff --git a/doc/index.md b/doc/index.md index d5ae649..4e3ce63 100644 --- a/doc/index.md +++ b/doc/index.md @@ -1,6 +1,33 @@ -# `SPARC-X-API`: A Python API for the Real-Space SPARC-X DFT Code +```{include} ../README.md +:language: md +:relative-docs: docs/ +:relative-images: +``` + -The `SPARC-X-API` is a versatile Python API for the real-space density -functional package SPARC (**S**imulation **P**ackage for **A**b-initio -**R**eal-**S**pace **C**alculations) distributed under the GPLv3 -license. + + + + + + + + + + +```{toctree} +:maxdepth: 2 +:caption: Contents: +introduction.md +installation.md +setup_environment.md +basic_usage.md +advanced_socket.md +examples.md +package_components.md +advanced_topics.md +api_changes.md +troubleshooting.md +contribute.md +maintainers.md +``` diff --git a/docs/installation.md b/doc/installation.md similarity index 100% rename from docs/installation.md rename to doc/installation.md diff --git a/docs/introduction.md b/doc/introduction.md similarity index 100% rename from docs/introduction.md rename to doc/introduction.md diff --git a/doc/maintainers.md b/doc/maintainers.md new file mode 100644 index 0000000..41446f9 --- /dev/null +++ b/doc/maintainers.md @@ -0,0 +1,37 @@ +# Documentation for Maintainers + +This part contains maintenance guidelines for SPARC-X-API core +developers. For general guidelines regarding how to contribute to this +project please refer to the [how to contribute](contribute.md) page. + +Most of the tasks in this documentation require `maintain` or `admin` +role for the repository. + +## Github Settings +### Github Branches + +There are multiple branches required for the CI/CD workflow in +SPARC-X-API. Push / pull request to these branches should only be made by automatic github actions. + +- [`badges`](https://github.com/SPARC-X/SPARC-X-API/tree/badges): + branch for maintaining the svg badges (package version, CI status, + etc.) + + A list of svg badges can be found under `badges/` directory of this + branch. See **TODO** for how to add / modify badges to be shown in + the README. + +- [`gh_pages`](https://github.com/SPARC-X/SPARC-X-API/tree/gh_pages): + branch to publish the documentation site. + + +### Github Pages Settings + +To change how the documentation pages + + +**TODO** only maintainers + +## Adding a New Badge in Readme + +## diff --git a/docs/make.bat b/doc/make.bat similarity index 100% rename from docs/make.bat rename to doc/make.bat diff --git a/docs/package_components.md b/doc/package_components.md similarity index 100% rename from docs/package_components.md rename to doc/package_components.md diff --git a/docs/setup_environment.md b/doc/setup_environment.md similarity index 100% rename from docs/setup_environment.md rename to doc/setup_environment.md diff --git a/doc/troubleshooting.md b/doc/troubleshooting.md index da0db72..006115a 100644 --- a/doc/troubleshooting.md +++ b/doc/troubleshooting.md @@ -1,3 +1,4 @@ +# Troubleshooting ### Known issues *This is a list of known bugs with the current SPARC-X-API, remove them when PRs are contributed* - [ ] `sparc-ase` command currently does not support multi-image yet diff --git a/docs/advanced_topics.md b/docs/advanced_topics.md deleted file mode 100644 index 03893f6..0000000 --- a/docs/advanced_topics.md +++ /dev/null @@ -1,134 +0,0 @@ -# Advanced Topics - -## Advanced Topics -The design of `SPARC-X-API` is schematically shown in the following figure -image - -### Behind the bundle file format - -Instead of parsing individual `.ion` and `.inpt` files, -the bundle format (recognized by ASE by `format="sparc"`) will -gather information from all files and check if atomic information -and calculation results can be retrieved. -The central piece for handling the bundle format is -`sparc.io.SpardBundle` class. You can use it to parse an existing bundle - -```python -from sparc.io import SparcBundle -bundle = SparcBundle("path/to/your-calc.sparc", mode="r") -images = bundle.convert_to_ase(index=":") -``` - -or write an `Atoms` object to a bundle with a minimal set of `.ion` and `.inpt` -files. - -```python -from sparc.io import SparcBundle -from ase.io import read -atoms = read("some-externalfile.xyz") -bundle = SparcBundle("path/to/your-calc.sparc", mode="w") -bundle._write_ion_and_inpt(atoms, label="SPARC") -``` - -For each individual SPARC file (e.g. `.ion`, `.inpt`, `.static`, `.geopt`, `.aimd`), -file-specific parsers are in `sparc.sparc_parsers.` files. -Each `_read_` method will return the structured raw-data dictionary of the files. -Similarly, `_write_` takes the structured dictionary as input and write the file -using only relevant data. - -### 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: - -```bash -git clone https://github.com/SPARC-X/SPARC.git -python -m sparc.docparser SPARC/doc/.LaTeX -``` - -You can use `sparc.api.SparcAPI` together with the generated JSON API schema: -1. Load the latest SPARC api -```python -from sparc.api import SparcAPI -sis = SparcAPI() -print(sis.sparc_version) -``` - - -2. Check if a variable is available -```python -from sparc.api import SparcAPI -sis = SparcAPI() -# A typo will be detected (actual parameter is CALC_PRESS) -assert "CALC_PRESSURE" not in sis.parameters -``` - -3. Convert string <--> valid value -```python -from sparc.api import SparcAPI -sis = SparcAPI() -latvec = sis.convert_string_to_value("LATVEC", "1.0 0 0\n 0 1.0 0\n 0 0 1.0") -latvec_string = sis.convert_value_to_string("LATVEC", latvec) -``` - -4. Provide help info for a given parameter -```python -from sparc.api import SparcAPI -sis = SparcAPI() -``` - -### 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 -rerun them. - -```python -from sparc import SPARC -calc = SPARC(restart=True, directory="old-calc.sparc") -old_atoms = calc.atoms.copy() -# Redo the calculation with updated parameters -old_atoms.rattle() -calc.set(h=0.2, directory="new-calc.sparc") -old_atoms.calc = calc -old_atoms.get_potential_energy() -``` - - - -### Rules for input parameters in `sparc.SPARC` calculator - -When constructing the `sparc.SPARC` calculator using the syntax -```python -calc = SPARC(directory="", **kwargs) -``` -the parameters are handled in the following priority: -1) Parameters available to `.inpt` files (i.e. **CAPITALIZED**) have highest priority and overwrite all special inputs. They should be set directly using the atomic unit values (i.e the same value as they appear in the `.inpt` files). -2) Special inputs (i.e, `h`, `kpts`, `gpts`, `xc`, `convergence`) have second highest priority and overwrite default values. They are using the ASE unit system (i.e. Å, eV, GPa, fs). -3) If none of the parameters are provided, `SPARC` uses its default parameter set, currently -```python -{"xc": "pbe", "h": 0.25, "kpts": (1, 1, 1)} -``` - -We accept parameters in both upper and lower cases, in other words, `FD_GRID=[10, 10, 10]` and `fd_grid=[10, 10, 10]` are equivalent. -Additionally, boolean inputs (i.e. `PRINT_FORCES`) can be written in both integer or boolean values. - - -### 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. - -When using `read_sparc` to access the files, you can add `include_all_files=True` option to parse -trajectories from all files. - -```python -from sparc.io import read_sparc -# Read all images from .static, .static_01, .static_02 etc. -images = read_sparc("path/to/calc.sparc", index=":", include_all_files=True) - -# Read only from .static_02 -last_atoms = read_sparc("path/to/calc.sparc", include_all_files=False) -``` - -By default, `sparc.SPARC` calculator only access the last image of last output file when reading the calculation results. diff --git a/docs/index.md b/docs/index.md deleted file mode 100644 index 8469fc2..0000000 --- a/docs/index.md +++ /dev/null @@ -1,31 +0,0 @@ -```{include} ../README.md -:language: md -``` - - - - - - - - - - - - -```{toctree} -:maxdepth: 2 -:caption: Contents: -introduction.md -installation.md -setup_environment.md -basic_usage.md -advanced_socket.md -examples.md -package_components.md -advanced_topics.md -api_changes.md -troubleshooting.md -contribute.md -maintainers.md -``` diff --git a/docs/maintainers.md b/docs/maintainers.md deleted file mode 100644 index 7306015..0000000 --- a/docs/maintainers.md +++ /dev/null @@ -1 +0,0 @@ -# Documentation for Maintainers diff --git a/docs/troubleshooting.md b/docs/troubleshooting.md deleted file mode 100644 index 006115a..0000000 --- a/docs/troubleshooting.md +++ /dev/null @@ -1,6 +0,0 @@ -# Troubleshooting -### Known issues -*This is a list of known bugs with the current SPARC-X-API, remove them when PRs are contributed* -- [ ] `sparc-ase` command currently does not support multi-image yet -- [ ] `SPARC` calculator may occasionally require more DFT steps than needed during optimization -- [ ] Raw result parsing from SPARC files may need to be re-factored in a generator form