deploy: d3d966b

_sources/index.md.txt

@@ -1,5 +1,7 @@
 ```{include} ../README.md
 :language: md
+:relative-docs: docs/
+:relative-images:
 ```
 <!-- # SPARC-X-API: A Python API for the SPARC-X DFT Code -->
 

_sources/maintainers.md.txt

@@ -1 +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
+
+##

index.html

@@ -89,10 +89,8 @@ <h1>SPARC-X-API: A Python API for the SPARC-X DFT Code<a class="headerlink" href
 <a class="reference external" href="https://raw.githubusercontent.com/SPARC-X/SPARC-X-API/badges/badges/api_version.svg"><img alt="JSON-API" src="https://raw.githubusercontent.com/SPARC-X/SPARC-X-API/badges/badges/api_version.svg" /></a></p>
 <p>SPARC-X-API is a versatile Python API for the real-space density
 functional (DFT) package <a class="reference external" href="https://github.com/SPARC-X/SPARC">SPARC</a>
-(<strong>S</strong>imulation <strong>P</strong>ackage for <strong>A</strong>b-initio <strong>R</strong>eal-<strong>S</strong>pace
-<strong>C</strong>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
 (<a class="reference external" href="https://wiki.fysik.dtu.dk/ase/">ASE</a>) 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:</p>
@@ -101,27 +99,42 @@ <h1>SPARC-X-API: A Python API for the SPARC-X DFT Code<a class="headerlink" href
 <li><p>A JSON Schema interfacing with SPARC’s C/C++ code for parameter validation and conversion</p></li>
 <li><p>A comprehensive calculator interface for SPARC with file I/O and socket-communication support.</p></li>
 </ol>
-<section id="id1">
-<h2><a class="headerlink" href="#id1" title="Link to this heading"></a></h2>
+<section id="overview">
+<h2>Overview<a class="headerlink" href="#overview" title="Link to this heading"></a></h2>
+<p>SPARC-X-API is part of the <a class="reference external" href="https://github.com/SPARC-X">SPARC-X
+project</a>, 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 <strong>S</strong>imulation <strong>P</strong>ackage for <strong>A</strong>b-initio
+<strong>R</strong>eal-<strong>S</strong>pace <strong>C</strong>alculations, which comes in two variations:</p>
+<ul class="simple">
+<li><p><a class="reference external" href="https://github.com/SPARC-X/M-SPARC"><strong>M-SPARC</strong></a>: self-consistent
+Matlab code for algorithm prototyping and testing</p></li>
+<li><p><a class="reference external" href="https://github.com/SPARC-X/SPARC"><strong>SPARC</strong></a>: C/C++ implementation
+of efficient production code scaling up to millions of atoms</p></li>
+</ul>
+<p>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.</p>
+<p><img alt="Overview of SPARC-X-API" src="_images/fig_sparc_api_overview.svg" /></p>
 </section>
 <section id="quick-start">
 <h2>Quick start<a class="headerlink" href="#quick-start" title="Link to this heading"></a></h2>
 <p>SPARC-X-API is straightforward to install and use, adhering to the ASE
 standard for seamless integration into other computational workflows.</p>
 <section id="installation">
 <h3>Installation<a class="headerlink" href="#installation" title="Link to this heading"></a></h3>
-<p>We recommend to use the
-<a class="reference external" href="https://docs.conda.io/projects/conda/en/latest/index.html"><code class="docutils literal notranslate"><span class="pre">conda</span></code></a>
-for installation on UNIX systems.</p>
+<p>Install SPARC-X-API via
+<a class="reference external" href="https://docs.conda.io/projects/conda/en/latest/index.html"><code class="docutils literal notranslate"><span class="pre">conda</span></code></a>.</p>
 <div class="highlight-bash notranslate"><div class="highlight"><pre><span></span>conda<span class="w"> </span>install<span class="w"> </span>-c<span class="w"> </span>conda-forge<span class="w"> </span>sparc-x-api
 </pre></div>
 </div>
-<p>You can also install the pre-compiled SPARC binary alongside SPARC-X-API (Linux only).</p>
+<p>Install the pre-compiled SPARC binary alongside SPARC-X-API (Linux only).</p>
 <div class="highlight-bash notranslate"><div class="highlight"><pre><span></span>conda<span class="w"> </span>install<span class="w"> </span>-c<span class="w"> </span>conda-forge<span class="w"> </span>sparc-x
 </pre></div>
 </div>
-<p>More installation options please see documentations for <a class="reference internal" href="#"><span class="xref myst">installation</span></a> and
-<a class="reference internal" href="#"><span class="xref myst">environment setup</span></a>.</p>
 </section>
 <section id="reading-writing-sparc-files">
 <h3>Reading / Writing SPARC files<a class="headerlink" href="#reading-writing-sparc-files" title="Link to this heading"></a></h3>
@@ -166,8 +179,9 @@ <h3>Parameter Validation with JSON Schema<a class="headerlink" href="#parameter-
 <h3>Running SPARC Calculations<a class="headerlink" href="#running-sparc-calculations" title="Link to this heading"></a></h3>
 <p>SPARC-X-API provides two ways to run a DFT calculation via SPARC C/C++ code:</p>
 <ol class="arabic simple">
-<li><p><strong>File I/O mode</strong>: generate input files, run a standard SPARC
-process and read results until calculation finishes. Suitable for:</p>
+<li><p><strong>File I/O mode</strong>: 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:</p>
 <ul class="simple">
 <li><p>Single point evaluation</p></li>
 <li><p>Band structure calculations</p></li>
@@ -199,17 +213,13 @@ <h4>File I/O mode<a class="headerlink" href="#file-i-o-mode" title="Link to this
 <span class="n">atoms</span><span class="o">.</span><span class="n">get_forces</span><span class="p">()</span>
 </pre></div>
 </div>
-<!-- The file I/O mode is capable of running single point DFT calculations, -->
-<!-- geometric optimization (using SPARC's internal routines), Ab-init -->
-<!-- molecular dynamics (AIMD). Optimization and AIMD tasks may also -->
-<!-- benefit from the built-in machine learning force field (MLFF) module. -->
 </section>
 <section id="socket-mode">
 <h4>Socket mode<a class="headerlink" href="#socket-mode" title="Link to this heading"></a></h4>
-<p>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:</p>
+<p>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:</p>
 <div class="highlight-python notranslate"><div class="highlight"><pre><span></span><span class="kn">from</span> <span class="nn">sparc.calculator</span> <span class="kn">import</span> <span class="n">SPARC</span>
 <span class="kn">from</span> <span class="nn">ase.build</span> <span class="kn">import</span> <span class="n">molecule</span>
 <span class="kn">from</span> <span class="nn">ase.optimize</span> <span class="kn">import</span> <span class="n">BFGS</span>
@@ -224,6 +234,13 @@ <h4>Socket mode<a class="headerlink" href="#socket-mode" title="Link to this hea
 </section>
 </section>
 </section>
+<section id="documentation">
+<h2>Documentation<a class="headerlink" href="#documentation" title="Link to this heading"></a></h2>
+<p>Please check the <a class="reference external" href="https://sparc-x.github.io/SPARC-X-API">full
+documentation</a> for details
+regarding installation, usage, troubleshooting and contribution
+guidelines.</p>
+</section>
 <section id="how-to-cite">
 <h2>How to cite<a class="headerlink" href="#how-to-cite" title="Link to this heading"></a></h2>
 <p>If you find SPARC-X-API help, please consider cite the relevant
@@ -250,29 +267,11 @@ <h2>How to cite<a class="headerlink" href="#how-to-cite" title="Link to this hea
 <li><p><a class="reference external" href="https://github.com/SPARC-X/SPMS-psps?tab=readme-ov-file#citation">Pseudopotentials</a></p></li>
 </ul>
 </section>
-<section id="documentation">
-<h2>Documentation<a class="headerlink" href="#documentation" title="Link to this heading"></a></h2>
-<p>Please check the <a class="reference external" href="https://sparc-x.github.io/sparc-x-api">full
-documentation</a> for details
-regarding installation, usage, troubleshooting and contribution
-guidelines.</p>
-</section>
 <section id="acknowledgment">
 <h2>Acknowledgment<a class="headerlink" href="#acknowledgment" title="Link to this heading"></a></h2>
-<p>The authors gratefully acknowledge the support of the U.S. Department
-of Energy, Office of Science, under Grant No. DE-SC0019410 and
+<p>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.</p>
-<!-- [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) -->
-<!-- ## Troubleshooting -->
-<!-- Please refer to the [troubleshooting](doc/troubleshooting.md) guidelines -->
-<!-- ## Advanced topics -->
-<!-- A detailed description about how the API works can be found [here](doc/advanced_topics.md) -->
-<!-- ## API changes -->
-<!-- The API changes compared to the older release ([v0.1](https://github.com/SPARC-X/SPARC-X-API/tree/eac557f214b402122a506f88f38c7a8767283503)) are summarized [here](doc/changes_v0.1.md) -->
-<!-- ## How to contribute -->
-<!-- Please refer to our [guidelines for contributors](doc/contribution_guideline.md) -->
 <!-- # 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 -->
@@ -327,7 +326,12 @@ <h2>Acknowledgment<a class="headerlink" href="#acknowledgment" title="Link to th
 <li class="toctree-l2"><a class="reference internal" href="contribute.html#notes-for-developers">Notes for developers</a></li>
 </ul>
 </li>
-<li class="toctree-l1"><a class="reference internal" href="maintainers.html">Documentation for Maintainers</a></li>
+<li class="toctree-l1"><a class="reference internal" href="maintainers.html">Documentation for Maintainers</a><ul>
+<li class="toctree-l2"><a class="reference internal" href="maintainers.html#github-settings">Github Settings</a></li>
+<li class="toctree-l2"><a class="reference internal" href="maintainers.html#adding-a-new-badge-in-readme">Adding a New Badge in Readme</a></li>
+<li class="toctree-l2"><a class="reference internal" href="maintainers.html#id1"></a></li>
+</ul>
+</li>
 </ul>
 </div>
 </section>

maintainers.html

@@ -54,7 +54,16 @@
 <li class="toctree-l1"><a class="reference internal" href="api_changes.html">Changes in API</a></li>
 <li class="toctree-l1"><a class="reference internal" href="troubleshooting.html">Troubleshooting</a></li>
 <li class="toctree-l1"><a class="reference internal" href="contribute.html">How to Contribute</a></li>
-<li class="toctree-l1 current"><a class="current reference internal" href="#">Documentation for Maintainers</a></li>
+<li class="toctree-l1 current"><a class="current reference internal" href="#">Documentation for Maintainers</a><ul>
+<li class="toctree-l2"><a class="reference internal" href="#github-settings">Github Settings</a><ul>
+<li class="toctree-l3"><a class="reference internal" href="#github-branches">Github Branches</a></li>
+<li class="toctree-l3"><a class="reference internal" href="#github-pages-settings">Github Pages Settings</a></li>
+</ul>
+</li>
+<li class="toctree-l2"><a class="reference internal" href="#adding-a-new-badge-in-readme">Adding a New Badge in Readme</a></li>
+<li class="toctree-l2"><a class="reference internal" href="#id1"></a></li>
+</ul>
+</li>
 </ul>
 
         </div>
@@ -83,6 +92,41 @@
 
   <section id="documentation-for-maintainers">
 <h1>Documentation for Maintainers<a class="headerlink" href="#documentation-for-maintainers" title="Link to this heading"></a></h1>
+<p>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 <a class="reference internal" href="contribute.html"><span class="std std-doc">how to contribute</span></a> page.</p>
+<p>Most of the tasks in this documentation require <code class="docutils literal notranslate"><span class="pre">maintain</span></code> or <code class="docutils literal notranslate"><span class="pre">admin</span></code>
+role for the repository.</p>
+<section id="github-settings">
+<h2>Github Settings<a class="headerlink" href="#github-settings" title="Link to this heading"></a></h2>
+<section id="github-branches">
+<h3>Github Branches<a class="headerlink" href="#github-branches" title="Link to this heading"></a></h3>
+<p>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.</p>
+<ul>
+<li><p><a class="reference external" href="https://github.com/SPARC-X/SPARC-X-API/tree/badges"><code class="docutils literal notranslate"><span class="pre">badges</span></code></a>:
+branch for maintaining the svg badges (package version, CI status,
+etc.)</p>
+<p>A list of svg badges can be found under <code class="docutils literal notranslate"><span class="pre">badges/</span></code> directory of this
+branch. See <strong>TODO</strong> for how to add / modify badges to be shown in
+the README.</p>
+</li>
+<li><p><a class="reference external" href="https://github.com/SPARC-X/SPARC-X-API/tree/gh_pages"><code class="docutils literal notranslate"><span class="pre">gh_pages</span></code></a>:
+branch to publish the documentation site.</p></li>
+</ul>
+</section>
+<section id="github-pages-settings">
+<h3>Github Pages Settings<a class="headerlink" href="#github-pages-settings" title="Link to this heading"></a></h3>
+<p>To change how the documentation pages</p>
+<p><strong>TODO</strong> only maintainers</p>
+</section>
+</section>
+<section id="adding-a-new-badge-in-readme">
+<h2>Adding a New Badge in Readme<a class="headerlink" href="#adding-a-new-badge-in-readme" title="Link to this heading"></a></h2>
+</section>
+<section id="id1">
+<h2><a class="headerlink" href="#id1" title="Link to this heading"></a></h2>
+</section>
 </section>