diff --git a/.github/workflows/joss_paper.yml b/.github/workflows/joss_paper.yml
new file mode 100644
index 00000000..349c0453
--- /dev/null
+++ b/.github/workflows/joss_paper.yml
@@ -0,0 +1,29 @@
+name: Draft Paper for JOSS
+on:
+ push:
+ paths:
+ - paper/**
+ - .github/workflows/joss_paper.yml
+ pull_request:
+ paths:
+ - paper/**
+ - .github/workflows/joss_paper.yml
+ workflow_dispatch:
+
+jobs:
+ paper:
+ runs-on: ubuntu-latest
+ name: Paper Draft
+ steps:
+ - name: Checkout
+ uses: actions/checkout@v4
+ - name: Build draft PDF
+ uses: openjournals/openjournals-draft-action@master
+ with:
+ journal: joss
+ paper-path: paper/paper.md
+ - name: Upload
+ uses: actions/upload-artifact@v4
+ with:
+ name: paper
+ path: paper/paper.pdf
diff --git a/.gitignore b/.gitignore
index b68ac118..2e6415d1 100644
--- a/.gitignore
+++ b/.gitignore
@@ -784,4 +784,6 @@ examples/ex1-ase/
/test-2/
*.pt
/README.html
+/paper/paper.pdf
+/paper/jats/
/doc/_build/
diff --git a/paper/README.md b/paper/README.md
new file mode 100644
index 00000000..2aed8349
--- /dev/null
+++ b/paper/README.md
@@ -0,0 +1,32 @@
+# Folder for JOSS submission
+
+This folder contains the `paper.md`, `paper.bib` and supporting
+figures for the JOSS submission of the SPARC-X-API. Please do not add
+SPARC doc in this directory. While most of the writings should be done
+in Markdown, please use either of the following methods for rendering
+the draft into pdf format.
+
+## Building Locally
+
+Follow the instructions in the [JOSS
+manual](https://joss.readthedocs.io/en/latest/paper.html#docker), use
+docker (or equivalent) to build the paper locally:
+
+```bash
+# At the paper/ subfolder of the SPARC-X-API repository
+docker run --rm \
+ --volume $PWD:/data \
+ --user $(id -u):$(id -g) \
+ --env JOURNAL=joss \
+ openjournals/inara
+```
+This command will create the `paper.pdf` under the `paper/` subfolder.
+
+## Use Github Actions
+
+The draft pdf will be rendered after any changes are pushed the
+`paper/` under the `joss_paper` branch. Please check the [status
+page](https://github.com/SPARC-X/SPARC-X-API/actions/workflows/joss_paper.yml)
+for the latest build action. Once the compilation is finished, the zip
+archive containing the rendered `paper.pdf` can be downloaded via the
+link in the "Artifacts" section of the action status.
diff --git a/paper/fig/fig_socket_hetero.svg b/paper/fig/fig_socket_hetero.svg
new file mode 100644
index 00000000..06f437b4
--- /dev/null
+++ b/paper/fig/fig_socket_hetero.svg
@@ -0,0 +1,1639 @@
+
+
+
+
diff --git a/paper/fig/fig_sparc_api_overview.svg b/paper/fig/fig_sparc_api_overview.svg
new file mode 100644
index 00000000..a502d76c
--- /dev/null
+++ b/paper/fig/fig_sparc_api_overview.svg
@@ -0,0 +1,2319 @@
+
+
+
+
diff --git a/paper/paper.bib b/paper/paper.bib
new file mode 100644
index 00000000..952ffeb8
--- /dev/null
+++ b/paper/paper.bib
@@ -0,0 +1,720 @@
+%% This BibTeX bibliography file was created using BibDesk.
+%% https://bibdesk.sourceforge.io/
+
+%% Created for Tian at 2024-09-24 16:33:38 +0800
+
+
+%% Saved with string encoding Unicode (UTF-8)
+
+
+
+@article{ceriotti_i-pi-1.0_2014,
+ author = {Ceriotti, Michele and More, Joshua and Manolopoulos, David E.},
+ date = {2014-03-01},
+ date-modified = {2024-09-24 16:33:31 +0800},
+ issn = {0010-4655},
+ journaltitle = {Computer Physics Communications},
+ keywords = {Molecular dynamics, Path integral},
+ number = {3},
+ pages = {1019--1026},
+ shorttitle = {i-{PI}},
+ title = {i-{PI}: A Python interface for ab initio path integral molecular dynamics simulations},
+ urldate = {2024-01-10},
+ volume = {185},
+ bdsk-url-1 = {https://www.sciencedirect.com/science/article/pii/S001046551300372X},
+ url = {https://doi.org/10.1016/j.cpc.2013.10.027}
+ }
+
+@article{kapil_i-pi-2.0_2019,
+ author = {Kapil, Venkat and Rossi, Mariana and Marsalek, Ondrej and Petraglia, Riccardo and Litman, Yair and Spura, Thomas and Cheng, Bingqing and Cuzzocrea, Alice and Mei{\ss}ner, Robert H. and Wilkins, David M. and Helfrecht, Benjamin A. and Juda, Przemys{\l}aw and Bienvenue, S{\'e}bastien P. and Fang, Wei and Kessler, Jan and Poltavsky, Igor and Vandenbrande, Steven and Wieme, Jelle and Corminboeuf, Clemence and K{\"u}hne, Thomas D. and Manolopoulos, David E. and Markland, Thomas E. and Richardson, Jeremy O. and Tkatchenko, Alexandre and Tribello, Gareth A. and Van Speybroeck, Veronique and Ceriotti, Michele},
+ date = {2019-03-01},
+ date-modified = {2024-09-24 16:33:31 +0800},
+ issn = {0010-4655},
+ journaltitle = {Computer Physics Communications},
+ keywords = {Accelerated sampling, Geometry optimizers, Molecular dynamics, Path integral},
+ pages = {214--223},
+ shorttitle = {i-{PI} 2.0},
+ title = {i-{PI} 2.0: A universal force engine for advanced molecular simulations},
+ urldate = {2024-09-19},
+ volume = {236},
+ bdsk-url-1 = {https://www.sciencedirect.com/science/article/pii/S0010465518303436},
+ url = {https://doi.org/10.1016/j.cpc.2018.09.020}}
+
+@article{litman_i-pi-3.0_2024,
+ author = {Litman, Yair and Kapil, Venkat and Feldman, Yotam M. Y. and Tisi, Davide and Begu{\v s}i{\'c}, Tomislav and Fidanyan, Karen and Fraux, Guillaume and Higer, Jacob and Kellner, Matthias and Li, Tao E. and P{\'o}s, Eszter S. and Stocco, Elia and Trenins, George and Hirshberg, Barak and Rossi, Mariana and Ceriotti, Michele},
+ date = {2024-08-14},
+ date-modified = {2024-09-24 16:33:31 +0800},
+ issn = {0021-9606, 1089-7690},
+ journaltitle = {The Journal of Chemical Physics},
+ langid = {english},
+ number = {6},
+ pages = {062504},
+ shorttitle = {i-{PI} 3.0},
+ title = {i-{PI} 3.0: A flexible and efficient framework for advanced atomistic simulations},
+ urldate = {2024-09-18},
+ volume = {161},
+ bdsk-url-1 = {https://pubs.aip.org/jcp/article/161/6/062504/3308034/i-PI-3-0-A-flexible-and-efficient-framework-for},
+ url = {https://doi.org/10.1063/5.0215869}}
+
+@article{xu_m-sparc-1.0_2020,
+ author = {Xu, Qimen and Sharma, Abhiraj and Suryanarayana, Phanish},
+ date-modified = {2024-09-24 16:33:31 +0800},
+ issn = {2352-7110},
+ journal = {SoftwareX},
+ langid = {english},
+ month = jan,
+ pages = 100423,
+ publisher = {Elsevier BV},
+ title = {M-{SPARC}: Matlab-Simulation Package for Ab-initio Real-space Calculations},
+ volume = 11,
+ year = 2020,
+ url = {http://dx.doi.org/10.1016/j.softx.2020.100423}}
+
+@article{zhang_m-sparc-2.0_2023,
+ author = {Zhang, Boqin and Jing, Xin and Kumar, Shashikant and Suryanarayana, Phanish},
+ date-modified = {2024-09-24 16:33:31 +0800},
+ issn = {2352-7110},
+ journal = {SoftwareX},
+ month = feb,
+ pages = 101295,
+ publisher = {Elsevier BV},
+ title = {Version 2.0.0 - M-SPARC: Matlab-Simulation Package for Ab-initio Real-space Calculations},
+ volume = 21,
+ year = 2023,
+ url = {http://dx.doi.org/10.1016/j.softx.2022.101295}}
+
+@article{xu_sparc-1.0_2021,
+ author = {Xu, Qimen and Sharma, Abhiraj and Comer, Benjamin and Huang, Hua and Chow, Edmond and Medford, Andrew J. and Pask, John E. and Suryanarayana, Phanish},
+ date-modified = {2024-09-24 16:33:31 +0800},
+ issn = {2352-7110},
+ journal = {SoftwareX},
+ month = jul,
+ pages = 100709,
+ publisher = {Elsevier BV},
+ title = {SPARC: Simulation Package for Ab-initio Real-space Calculations},
+ volume = 15,
+ year = 2021,
+ url = {http://dx.doi.org/10.1016/j.softx.2021.100709}}
+
+@article{zhang_sparc-2.0_2024,
+ author = {Zhang, Boqin and Jing, Xin and Xu, Qimen and Kumar, Shashikant and Sharma, Abhiraj and Erlandson, Lucas and Sahoo, Sushree Jagriti and Chow, Edmond and Medford, Andrew J. and Pask, John E. and Suryanarayana, Phanish},
+ date-modified = {2024-09-24 16:33:31 +0800},
+ issn = {2665-9638},
+ journal = {Software Impacts},
+ month = may,
+ pages = 100649,
+ publisher = {Elsevier BV},
+ title = {SPARC v2.0.0: Spin-orbit coupling, dispersion interactions, and advanced exchange--correlation functionals},
+ volume = 20,
+ year = 2024,
+ url = {http://dx.doi.org/10.1016/j.simpa.2024.100649}}
+
+@article{gavini_exascale_2023,
+ author = {Gavini, Vikram and Baroni, Stefano and Blum, Volker
+ and Bowler, David R and Buccheri, Alexander and
+ Chelikowsky, James R and Das, Sambit and Dawson,
+ William and Delugas, Pietro and Dogan, Mehmet and
+ Draxl, Claudia and Galli, Giulia and Genovese, Luigi
+ and Giannozzi, Paolo and Giantomassi, Matteo and
+ Gonze, Xavier and Govoni, Marco and Gygi, François
+ and Gulans, Andris and Herbert, John M and Kokott,
+ Sebastian and Kühne, Thomas D and Liou, Kai-Hsin and
+ Miyazaki, Tsuyoshi and Motamarri, Phani and Nakata,
+ Ayako and Pask, John E and Plessl, Christian and
+ Ratcliff, Laura E and Richard, Ryan M and Rossi,
+ Mariana and Schade, Robert and Scheffler, Matthias
+ and Schütt, Ole and Suryanarayana, Phanish and
+ Torrent, Marc and Truflandier, Lionel and Windus,
+ Theresa L and Xu, Qimen and Yu, Victor W-Z and
+ Perez, D},
+ title = {Roadmap on electronic structure codes in the
+ exascale era},
+ journal = {Modelling and Simulation in Materials Science and
+ Engineering},
+ year = 2023,
+ volume = 31,
+ number = 6,
+ month = aug,
+ pages = 063301,
+ issn = {1361-651X},
+ doi = {10.1088/1361-651x/acdf06},
+ url = {http://dx.doi.org/10.1088/1361-651X/acdf06},
+ publisher = {IOP Publishing}
+}
+
+
+
+@article{timmerman_otf_md_sparc_2024,
+ author = {Timmerman, Lucas R. and Kumar, Shashikant and
+ Suryanarayana, Phanish and Medford, Andrew J.},
+ title = {Overcoming the Chemical Complexity Bottleneck in
+ on-the-Fly Machine Learned Molecular Dynamics
+ Simulations},
+ journal = {Journal of Chemical Theory and Computation},
+ year = 2024,
+ volume = 20,
+ number = 14,
+ month = jul,
+ pages = {5788–5795},
+ issn = {1549-9626},
+ doi = {10.1021/acs.jctc.4c00474},
+ url = {http://dx.doi.org/10.1021/acs.jctc.4c00474},
+ publisher = {American Chemical Society (ACS)}
+}
+
+@article{kumar_otf_mlff_sparc_2024,
+ author = {Kumar, Shashikant and Jing, Xin and Pask, John
+ E. and Suryanarayana, Phanish},
+ title = {On-the-fly machine learned force fields for the
+ study of warm dense matter: Application to diffusion
+ and viscosity of CH},
+ journal = {Physics of Plasmas},
+ year = 2024,
+ volume = 31,
+ number = 4,
+ month = apr,
+ issn = {1089-7674},
+ doi = {10.1063/5.0204229},
+ url = {http://dx.doi.org/10.1063/5.0204229},
+ publisher = {AIP Publishing}
+}
+
+
+@article{larsen_ase_2017,
+ author = {Hjorth Larsen, Ask and Jørgen Mortensen, Jens and
+ Blomqvist, Jakob and Castelli, Ivano E and
+ Christensen, Rune and Dułak, Marcin and Friis,
+ Jesper and Groves, Michael N and Hammer, Bjørk and
+ Hargus, Cory and Hermes, Eric D and Jennings, Paul C
+ and Bjerre Jensen, Peter and Kermode, James and
+ Kitchin, John R and Leonhard Kolsbjerg, Esben and
+ Kubal, Joseph and Kaasbjerg, Kristen and Lysgaard,
+ Steen and Bergmann Maronsson, Jón and Maxson,
+ Tristan and Olsen, Thomas and Pastewka, Lars and
+ Peterson, Andrew and Rostgaard, Carsten and Schiøtz,
+ Jakob and Schütt, Ole and Strange, Mikkel and
+ Thygesen, Kristian S and Vegge, Tejs and Vilhelmsen,
+ Lasse and Walter, Michael and Zeng, Zhenhua and
+ Jacobsen, Karsten W},
+ title = {The atomic simulation environment—a Python library
+ for working with atoms},
+ journal = {Journal of Physics: Condensed Matter},
+ year = 2017,
+ volume = 29,
+ number = 27,
+ month = jun,
+ pages = 273002,
+ issn = {1361-648X},
+ doi = {10.1088/1361-648x/aa680e},
+ url = {http://dx.doi.org/10.1088/1361-648X/aa680e},
+ publisher = {IOP Publishing}
+}
+
+
+@article{bartok_soap_2013,
+ author = {Bart{\'o}k, Albert P. and Kondor, Risi and Cs{\'a}nyi, G{\'a}bor},
+ date = {2013-05-28},
+ date-modified = {2024-09-24 16:33:31 +0800},
+ file = {APS Snapshot:/Users/ttian/Zotero/storage/RTK2PZJT/PhysRevB.87.html:text/html;Full Text PDF:/Users/ttian/Zotero/storage/H68MFXR2/Bart{\'o}k et al. - 2013 - On representing chemical environments.pdf:application/pdf},
+ journaltitle = {Phys. Rev. B},
+ note = {Publisher: American Physical Society},
+ number = {18},
+ pages = {184115},
+ title = {On representing chemical environments},
+ urldate = {2024-01-10},
+ volume = {87},
+ bdsk-url-1 = {https://link.aps.org/doi/10.1103/PhysRevB.87.184115},
+ bdsk-url-2 = {https://doi.org/10.1103/PhysRevB.87.184115}}
+
+@article{deringer_gpr_2021,
+ author = {Deringer, Volker L. and Bart{\'o}k, Albert P. and Bernstein, Noam and Wilkins, David M. and Ceriotti, Michele and Cs{\'a}nyi, G{\'a}bor},
+ date = {2021-08-25},
+ date-modified = {2024-09-24 16:33:31 +0800},
+ issn = {0009-2665},
+ journaltitle = {Chem. Rev.},
+ number = {16},
+ pages = {10073--10141},
+ title = {Gaussian Process Regression for Materials and Molecules},
+ urldate = {2024-01-10},
+ volume = {121},
+ bdsk-url-1 = {https://doi.org/10.1021/acs.chemrev.1c00022}}
+
+@article{ong_pymatgen_2013,
+ author = {Ong, Shyue Ping and Richards, William Davidson and Jain, Anubhav and Hautier, Geoffroy and Kocher, Michael and Cholia, Shreyas and Gunter, Dan and Chevrier, Vincent L. and Persson, Kristin A. and Ceder, Gerbrand},
+ date = {2013-02-01},
+ date-modified = {2024-09-24 16:33:31 +0800},
+ issn = {0927-0256},
+ journaltitle = {Computational Materials Science},
+ keywords = {Materials, Design, High-throughput, Project, Thermodynamics},
+ pages = {314--319},
+ shorttitle = {Python Materials Genomics (pymatgen)},
+ title = {Python Materials Genomics (pymatgen): A robust, open-source python library for materials analysis},
+ urldate = {2024-01-10},
+ volume = {68},
+ bdsk-url-1 = {https://www.sciencedirect.com/science/article/pii/S0927025612006295},
+ bdsk-url-2 = {https://doi.org/10.1016/j.commatsci.2012.10.028}}
+
+@article{bonomi_plumed_2019,
+ title = {Promoting transparency and reproducibility in enhanced molecular simulations},
+ volume = {16},
+ rights = {2019 Springer Nature America, Inc.},
+ issn = {1548-7105},
+ url = {http://dx.doi.org/10.1038/s41592-019-0506-8},
+ doi = {10.1038/s41592-019-0506-8},
+ pages = {670--673},
+ number = {8},
+ journaltitle = {Nat Methods},
+ author = {Bonomi, Massimiliano and Bussi, Giovanni and Camilloni, Carlo and Tribello, Gareth A. and Banáš, Pavel and Barducci, Alessandro and Bernetti, Mattia and Bolhuis, Peter G. and Bottaro, Sandro and Branduardi, Davide and Capelli, Riccardo and Carloni, Paolo and Ceriotti, Michele and Cesari, Andrea and Chen, Haochuan and Chen, Wei and Colizzi, Francesco and De, Sandip and De La Pierre, Marco and Donadio, Davide and Drobot, Viktor and Ensing, Bernd and Ferguson, Andrew L. and Filizola, Marta and Fraser, James S. and Fu, Haohao and Gasparotto, Piero and Gervasio, Francesco Luigi and Giberti, Federico and Gil-Ley, Alejandro and Giorgino, Toni and Heller, Gabriella T. and Hocky, Glen M. and Iannuzzi, Marcella and Invernizzi, Michele and Jelfs, Kim E. and Jussupow, Alexander and Kirilin, Evgeny and Laio, Alessandro and Limongelli, Vittorio and Lindorff-Larsen, Kresten and Löhr, Thomas and Marinelli, Fabrizio and Martin-Samos, Layla and Masetti, Matteo and Meyer, Ralf and Michaelides, Angelos and Molteni, Carla and Morishita, Tetsuya and Nava, Marco and Paissoni, Cristina and Papaleo, Elena and Parrinello, Michele and Pfaendtner, Jim and Piaggi, Pablo and Piccini, GiovanniMaria and Pietropaolo, Adriana and Pietrucci, Fabio and Pipolo, Silvio and Provasi, Davide and Quigley, David and Raiteri, Paolo and Raniolo, Stefano and Rydzewski, Jakub and Salvalaglio, Matteo and Sosso, Gabriele Cesare and Spiwok, Vojtěch and Šponer, Jiří and Swenson, David W. H. and Tiwary, Pratyush and Valsson, Omar and Vendruscolo, Michele and Voth, Gregory A. and White, Andrew and {The PLUMED consortium}},
+ urldate = {2024-09-18},
+ date = {2019-08},
+ langid = {english},
+ note = {Publisher: Nature Publishing Group},
+ keywords = {Culture, Software},
+ }
+
+@article{mortensen_gpaw_original_2005,
+ author = {Mortensen, J. J. and Hansen, L. B. and Jacobsen,
+ K. W.},
+ title = {Real-space grid implementation of the projector
+ augmented wave method},
+ journal = {Physical Review B},
+ year = 2005,
+ volume = 71,
+ number = 3,
+ month = jan,
+ issn = {1550-235X},
+ doi = {10.1103/physrevb.71.035109},
+ url = {http://dx.doi.org/10.1103/PhysRevB.71.035109},
+ publisher = {American Physical Society (APS)}
+}
+
+@article{enkovaara_gpaw_1_2011,
+ author = {Enkovaara, Jussi and Romero, Nichols A. and Shende,
+ Sameer and Mortensen, Jens J.},
+ title = {GPAW - massively parallel electronic structure
+ calculations with Python-based software},
+ journal = {Procedia Computer Science},
+ year = 2011,
+ volume = 4,
+ pages = {17–25},
+ issn = {1877-0509},
+ doi = {10.1016/j.procs.2011.04.003},
+ url = {http://dx.doi.org/10.1016/j.procs.2011.04.003},
+ publisher = {Elsevier BV}
+}
+
+@article{mortensen_gpaw_2_2024,
+ author = {Mortensen, Jens Jørgen and Larsen, Ask Hjorth and
+ Kuisma, Mikael and Ivanov, Aleksei V. and
+ Taghizadeh, Alireza and Peterson, Andrew and Haldar,
+ Anubhab and Dohn, Asmus Ougaard and Schäfer,
+ Christian and Jónsson, Elvar Örn and Hermes, Eric
+ D. and Nilsson, Fredrik Andreas and Kastlunger,
+ Georg and Levi, Gianluca and Jónsson, Hannes and
+ Häkkinen, Hannu and Fojt, Jakub and Kangsabanik,
+ Jiban and Sødequist, Joachim and Lehtomäki, Jouko
+ and Heske, Julian and Enkovaara, Jussi and Winther,
+ Kirsten Trøstrup and Dulak, Marcin and Melander,
+ Marko M. and Ovesen, Martin and Louhivuori, Martti
+ and Walter, Michael and Gjerding, Morten and
+ Lopez-Acevedo, Olga and Erhart, Paul and Warmbier,
+ Robert and Würdemann, Rolf and Kaappa, Sami and
+ Latini, Simone and Boland, Tara Maria and Bligaard,
+ Thomas and Skovhus, Thorbjørn and Susi, Toma and
+ Maxson, Tristan and Rossi, Tuomas and Chen, Xi and
+ Schmerwitz, Yorick Leonard A. and Schiøtz, Jakob and
+ Olsen, Thomas and Jacobsen, Karsten Wedel and
+ Thygesen, Kristian Sommer},
+ title = {GPAW: An open Python package for electronic
+ structure calculations},
+ journal = {The Journal of Chemical Physics},
+ year = 2024,
+ volume = 160,
+ number = 9,
+ month = mar,
+ issn = {1089-7690},
+ doi = {10.1063/5.0182685},
+ url = {http://dx.doi.org/10.1063/5.0182685},
+ publisher = {AIP Publishing}
+}
+@article{tancogne_dejean_octopus_2020,
+ author = {Tancogne-Dejean, Nicolas and Oliveira, Micael
+ J. T. and Andrade, Xavier and Appel, Heiko and
+ Borca, Carlos H. and Le Breton, Guillaume and
+ Buchholz, Florian and Castro, Alberto and Corni,
+ Stefano and Correa, Alfredo A. and De Giovannini,
+ Umberto and Delgado, Alain and Eich, Florian G. and
+ Flick, Johannes and Gil, Gabriel and Gomez, Adrián
+ and Helbig, Nicole and Hübener, Hannes and Jestädt,
+ René and Jornet-Somoza, Joaquim and Larsen, Ask
+ H. and Lebedeva, Irina V. and Lüders, Martin and
+ Marques, Miguel A. L. and Ohlmann, Sebastian T. and
+ Pipolo, Silvio and Rampp, Markus and Rozzi, Carlo
+ A. and Strubbe, David A. and Sato, Shunsuke A. and
+ Schäfer, Christian and Theophilou, Iris and Welden,
+ Alicia and Rubio, Angel},
+ title = {Octopus, a computational framework for exploring
+ light-driven phenomena and quantum dynamics in
+ extended and finite systems},
+ journal = {The Journal of Chemical Physics},
+ year = 2020,
+ volume = 152,
+ number = 12,
+ month = mar,
+ issn = {1089-7690},
+ doi = {10.1063/1.5142502},
+ url = {http://dx.doi.org/10.1063/1.5142502},
+ publisher = {AIP Publishing}
+}
+@article{kresse_vasp_1996,
+ author = {Kresse, G. and Furthmüller, J.},
+ title = {Efficiency of ab-initio total energy calculations
+ for metals and semiconductors using a plane-wave
+ basis set},
+ journal = {Computational Materials Science},
+ year = 1996,
+ volume = 6,
+ number = 1,
+ month = jul,
+ pages = {15–50},
+ issn = {0927-0256},
+ doi = {10.1016/0927-0256(96)00008-0},
+ url = {http://dx.doi.org/10.1016/0927-0256(96)00008-0},
+ publisher = {Elsevier BV}
+}
+@article{giannozzi_qe_2017,
+ author = {Giannozzi, P and Andreussi, O and Brumme, T and
+ Bunau, O and Buongiorno Nardelli, M and Calandra, M
+ and Car, R and Cavazzoni, C and Ceresoli, D and
+ Cococcioni, M and Colonna, N and Carnimeo, I and Dal
+ Corso, A and de Gironcoli, S and Delugas, P and
+ DiStasio, R A and Ferretti, A and Floris, A and
+ Fratesi, G and Fugallo, G and Gebauer, R and
+ Gerstmann, U and Giustino, F and Gorni, T and Jia, J
+ and Kawamura, M and Ko, H-Y and Kokalj, A and
+ Küçükbenli, E and Lazzeri, M and Marsili, M and
+ Marzari, N and Mauri, F and Nguyen, N L and Nguyen,
+ H-V and Otero-de-la-Roza, A and Paulatto, L and
+ Poncé, S and Rocca, D and Sabatini, R and Santra, B
+ and Schlipf, M and Seitsonen, A P and Smogunov, A
+ and Timrov, I and Thonhauser, T and Umari, P and
+ Vast, N and Wu, X and Baroni, S},
+ title = {Advanced capabilities for materials modelling with
+ Quantum ESPRESSO},
+ journal = {Journal of Physics: Condensed Matter},
+ year = 2017,
+ volume = 29,
+ number = 46,
+ month = oct,
+ pages = 465901,
+ issn = {1361-648X},
+ doi = {10.1088/1361-648x/aa8f79},
+ url = {http://dx.doi.org/10.1088/1361-648X/aa8f79},
+ publisher = {IOP Publishing}
+}
+@article{gonze_abinit_2020,
+ author = {Gonze, Xavier and Amadon, Bernard and Antonius,
+ Gabriel and Arnardi, Frédéric and Baguet, Lucas and
+ Beuken, Jean-Michel and Bieder, Jordan and Bottin,
+ François and Bouchet, Johann and Bousquet, Eric and
+ Brouwer, Nils and Bruneval, Fabien and Brunin,
+ Guillaume and Cavignac, Théo and Charraud,
+ Jean-Baptiste and Chen, Wei and Côté, Michel and
+ Cottenier, Stefaan and Denier, Jules and Geneste,
+ Grégory and Ghosez, Philippe and Giantomassi, Matteo
+ and Gillet, Yannick and Gingras, Olivier and Hamann,
+ Donald R. and Hautier, Geoffroy and He, Xu and
+ Helbig, Nicole and Holzwarth, Natalie and Jia,
+ Yongchao and Jollet, François and
+ Lafargue-Dit-Hauret, William and Lejaeghere, Kurt
+ and Marques, Miguel A.L. and Martin, Alexandre and
+ Martins, Cyril and Miranda, Henrique P.C. and
+ Naccarato, Francesco and Persson, Kristin and
+ Petretto, Guido and Planes, Valentin and Pouillon,
+ Yann and Prokhorenko, Sergei and Ricci, Fabio and
+ Rignanese, Gian-Marco and Romero, Aldo H. and
+ Schmitt, Michael Marcus and Torrent, Marc and van
+ Setten, Michiel J. and Van Troeye, Benoit and
+ Verstraete, Matthieu J. and Zérah, Gilles and
+ Zwanziger, Josef W.},
+ title = {The Abinit project: Impact, environment and recent
+ developments},
+ journal = {Computer Physics Communications},
+ year = 2020,
+ volume = 248,
+ month = mar,
+ pages = 107042,
+ issn = {0010-4655},
+ doi = {10.1016/j.cpc.2019.107042},
+ url = {http://dx.doi.org/10.1016/j.cpc.2019.107042},
+ publisher = {Elsevier BV}
+}
+
+@article{suryanarayana_sparc_sq_2018,
+ author = {Suryanarayana, Phanish and Pratapa, Phanisri P. and
+ Sharma, Abhiraj and Pask, John E.},
+ title = {SQDFT: Spectral Quadrature method for large-scale
+ parallel O(N) Kohn–Sham calculations at high
+ temperature},
+ journal = {Computer Physics Communications},
+ year = 2018,
+ volume = 224,
+ month = mar,
+ pages = {288–298},
+ issn = {0010-4655},
+ doi = {10.1016/j.cpc.2017.12.003},
+ url = {http://dx.doi.org/10.1016/j.cpc.2017.12.003},
+ publisher = {Elsevier BV}
+}
+
+@article{sharma_sparc_cyclix_2021,
+ author = {Sharma, Abhiraj and Suryanarayana, Phanish},
+ title = {Real-space density functional theory adapted to
+ cyclic and helical symmetry: Application to
+ torsional deformation of carbon nanotubes},
+ journal = {Physical Review B},
+ year = 2021,
+ volume = 103,
+ number = 3,
+ month = jan,
+ issn = {2469-9969},
+ doi = {10.1103/physrevb.103.035101},
+ url = {http://dx.doi.org/10.1103/PhysRevB.103.035101},
+ publisher = {American Physical Society (APS)}
+}
+
+@article{sharma_sparc_dfpt_2023,
+ author = {Sharma, Abhiraj and Suryanarayana, Phanish},
+ title = {Calculation of phonons in real-space density
+ functional theory},
+ journal = {Physical Review E},
+ year = 2023,
+ volume = 108,
+ number = 4,
+ month = oct,
+ issn = {2470-0053},
+ doi = {10.1103/physreve.108.045302},
+ url = {http://dx.doi.org/10.1103/PhysRevE.108.045302},
+ publisher = {American Physical Society (APS)}
+}
+
+@article{ghosh_sparc_ofdft_2016,
+ author = {Ghosh, Swarnava and Suryanarayana, Phanish},
+ title = {Higher-order finite-difference formulation of
+ periodic Orbital-free Density Functional Theory},
+ journal = {Journal of Computational Physics},
+ year = 2016,
+ volume = 307,
+ month = feb,
+ pages = {634–652},
+ issn = {0021-9991},
+ doi = {10.1016/j.jcp.2015.12.027},
+ url = {http://dx.doi.org/10.1016/j.jcp.2015.12.027},
+ publisher = {Elsevier BV}
+}
+
+@article{kumar_ofdft_delta_ml_2023,
+ author = {Kumar, Shashikant and Jing, Xin and Pask, John
+ E. and Medford, Andrew J. and Suryanarayana,
+ Phanish},
+ title = {Kohn–Sham accuracy from orbital-free density
+ functional theory via Δ-machine learning},
+ journal = {The Journal of Chemical Physics},
+ year = 2023,
+ volume = 159,
+ number = 24,
+ month = dec,
+ issn = {1089-7690},
+ doi = {10.1063/5.0180541},
+ url = {http://dx.doi.org/10.1063/5.0180541},
+ publisher = {AIP Publishing}
+}
+
+@article{timmerman_sparc_mlff_2024,
+ author = {Timmerman, Lucas R. and Kumar, Shashikant and
+ Suryanarayana, Phanish and Medford, Andrew J.},
+ title = {Overcoming the Chemical Complexity Bottleneck in
+ on-the-Fly Machine Learned Molecular Dynamics
+ Simulations},
+ journal = {Journal of Chemical Theory and Computation},
+ year = 2024,
+ volume = 20,
+ number = 14,
+ month = jul,
+ pages = {5788–5795},
+ issn = {1549-9626},
+ doi = {10.1021/acs.jctc.4c00474},
+ url = {http://dx.doi.org/10.1021/acs.jctc.4c00474},
+ publisher = {American Chemical Society (ACS)}
+}
+
+@article{kumar_sparc_mlff_2024,
+ author = {Kumar, Shashikant and Pask, John E. and
+ Suryanarayana, Phanish},
+ title = {Shock Hugoniot calculations using on-the-fly machine
+ learned force fields with ab initio accuracy},
+ journal = {Physics of Plasmas},
+ year = 2024,
+ volume = 31,
+ number = 10,
+ month = oct,
+ issn = {1089-7674},
+ doi = {10.1063/5.0230060},
+ url = {http://dx.doi.org/10.1063/5.0230060},
+ publisher = {AIP Publishing}
+}
+
+@article{goedecker_order_n_dft_1999,
+ author = {Goedecker, Stefan},
+ title = {Linear scaling electronic structure methods},
+ journal = {Reviews of Modern Physics},
+ year = 1999,
+ volume = 71,
+ number = 4,
+ month = jul,
+ pages = {1085–1123},
+ issn = {1539-0756},
+ doi = {10.1103/revmodphys.71.1085},
+ url = {http://dx.doi.org/10.1103/revmodphys.71.1085},
+ publisher = {American Physical Society (APS)}
+}
+
+
+
+@article{bowler_order_n_dft_2012,
+ author = {Bowler, D R and Miyazaki, T},
+ title = {O(N) methods in electronic structure
+ calculations},
+ journal = {Reports on Progress in Physics},
+ year = 2012,
+ volume = 75,
+ number = 3,
+ month = feb,
+ pages = 036503,
+ issn = {1361-6633},
+ doi = {10.1088/0034-4885/75/3/036503},
+ url = {http://dx.doi.org/10.1088/0034-4885/75/3/036503},
+ publisher = {IOP Publishing}
+}
+
+
+@article{shojaei_sparc_pseudopot_2023,
+ author = {Shojaei, Mostafa Faghih and Pask, John E. and
+ Medford, Andrew J. and Suryanarayana, Phanish},
+ title = {Soft and transferable pseudopotentials from
+ multi-objective optimization},
+ journal = {Computer Physics Communications},
+ year = 2023,
+ volume = 283,
+ month = feb,
+ pages = 108594,
+ issn = {0010-4655},
+ doi = {10.1016/j.cpc.2022.108594},
+ url = {http://dx.doi.org/10.1016/j.cpc.2022.108594},
+ publisher = {Elsevier BV}
+}
+
+@article{smith_psi4_2020,
+ author = {Smith, Daniel G. A. and Burns, Lori A. and
+ Simmonett, Andrew C. and Parrish, Robert M. and
+ Schieber, Matthew C. and Galvelis, Raimondas and
+ Kraus, Peter and Kruse, Holger and Di Remigio,
+ Roberto and Alenaizan, Asem and James, Andrew M. and
+ Lehtola, Susi and Misiewicz, Jonathon P. and
+ Scheurer, Maximilian and Shaw, Robert A. and
+ Schriber, Jeffrey B. and Xie, Yi and Glick, Zachary
+ L. and Sirianni, Dominic A. and O’Brien, Joseph
+ Senan and Waldrop, Jonathan M. and Kumar, Ashutosh
+ and Hohenstein, Edward G. and Pritchard, Benjamin
+ P. and Brooks, Bernard R. and Schaefer, Henry F. and
+ Sokolov, Alexander Yu. and Patkowski, Konrad and
+ DePrince, A. Eugene and Bozkaya, Uğur and King,
+ Rollin A. and Evangelista, Francesco A. and Turney,
+ Justin M. and Crawford, T. Daniel and Sherrill,
+ C. David},
+ title = {PSI4 1.4: Open-source software for
+ high-throughput quantum chemistry},
+ journal = {The Journal of Chemical Physics},
+ year = 2020,
+ volume = 152,
+ number = 18,
+ month = may,
+ issn = {1089-7690},
+ doi = {10.1063/5.0006002},
+ url = {http://dx.doi.org/10.1063/5.0006002},
+ publisher = {AIP Publishing}
+}
+
+@article{musielewicz_finetuna_2022,
+ author = {Musielewicz, Joseph and Wang, Xiaoxiao and Tian,
+ Tian and Ulissi, Zachary},
+ title = {FINETUNA: fine-tuning accelerated molecular
+ simulations},
+ journal = {Machine Learning: Science and Technology},
+ year = 2022,
+ volume = 3,
+ number = 3,
+ month = sep,
+ pages = {03LT01},
+ issn = {2632-2153},
+ doi = {10.1088/2632-2153/ac8fe0},
+ url = {http://dx.doi.org/10.1088/2632-2153/ac8fe0},
+ publisher = {IOP Publishing}
+}
+
+@misc{ilyes_mace_2023,
+ author = {Batatia, Ilyes and Benner, Philipp and Chiang, Yuan
+ and Elena, Alin M. and Kovács, Dávid P. and
+ Riebesell, Janosh and Advincula, Xavier R. and Asta,
+ Mark and Avaylon, Matthew and Baldwin, William
+ J. and Berger, Fabian and Bernstein, Noam and
+ Bhowmik, Arghya and Blau, Samuel M. and Cărare, Vlad
+ and Darby, James P. and De, Sandip and Della Pia,
+ Flaviano and Deringer, Volker L. and Elijošius,
+ Rokas and El-Machachi, Zakariya and Falcioni, Fabio
+ and Fako, Edvin and Ferrari, Andrea C. and
+ Genreith-Schriever, Annalena and George, Janine and
+ Goodall, Rhys E. A. and Grey, Clare P. and Grigorev,
+ Petr and Han, Shuang and Handley, Will and Heenen,
+ Hendrik H. and Hermansson, Kersti and Holm,
+ Christian and Jaafar, Jad and Hofmann, Stephan and
+ Jakob, Konstantin S. and Jung, Hyunwook and Kapil,
+ Venkat and Kaplan, Aaron D. and Karimitari, Nima and
+ Kermode, James R. and Kroupa, Namu and Kullgren,
+ Jolla and Kuner, Matthew C. and Kuryla, Domantas and
+ Liepuoniute, Guoda and Margraf, Johannes T. and
+ Magdău, Ioan-Bogdan and Michaelides, Angelos and
+ Moore, J. Harry and Naik, Aakash A. and Niblett,
+ Samuel P. and Norwood, Sam Walton and O'Neill, Niamh
+ and Ortner, Christoph and Persson, Kristin A. and
+ Reuter, Karsten and Rosen, Andrew S. and Schaaf,
+ Lars L. and Schran, Christoph and Shi, Benjamin
+ X. and Sivonxay, Eric and Stenczel, Tamás K. and
+ Svahn, Viktor and Sutton, Christopher and Swinburne,
+ Thomas D. and Tilly, Jules and van der Oord, Cas and
+ Varga-Umbrich, Eszter and Vegge, Tejs and Vondrák,
+ Martin and Wang, Yangshuai and Witt, William C. and
+ Zills, Fabian and Csányi, Gábor},
+ title = {A foundation model for atomistic materials
+ chemistry},
+ year = 2024,
+ doi = {10.48550/ARXIV.2401.00096},
+ url = {https://arxiv.org/abs/2401.00096},
+ keywords = {Chemical Physics (physics.chem-ph), Materials
+ Science (cond-mat.mtrl-sci), FOS: Physical sciences,
+ FOS: Physical sciences},
+ publisher = {arXiv},
+ copyright = {Creative Commons Attribution Non Commercial No
+ Derivatives 4.0 International}
+}
+
+@misc{fairchem_2024,
+ author = {},
+ title = {fairchem by FAIR Chemistry},
+ year = {2024},
+ publisher = {GitHub},
+ journal = {GitHub repository},
+ howpublished = {\url{https://github.com/FAIR-Chem/fairchem}},
+ url={https://github.com/FAIR-Chem/fairchem},
+ commit = {f22dbdf5498912e519459831ac58668566e38e67}
+}
diff --git a/paper/paper.md b/paper/paper.md
new file mode 100644
index 00000000..844b0d77
--- /dev/null
+++ b/paper/paper.md
@@ -0,0 +1,420 @@
+---
+title: 'SPARC-X-API: Versatile Python Interface for Real-space Density Functional Theory Calculations'
+tags:
+ - Density Functional Theories
+ - Atomistic Simulations
+ - Python
+ - Atomic Simulation Environment
+ - Socket Interface
+authors:
+ - name: Tian Tian
+ orcid: 0000-0003-0634-0455
+ corresponding: true
+ affiliation: [1,3]
+ - name: Lucas R Timmerman
+ orcid: 0000-0001-5664-5762
+ affiliation: 1
+ - name: Shashikant Kumar
+ orcid: 0009-0001-5134-1580
+ affiliation: 1
+ - name: Ben Comer
+ orcid: 0000-0002-7528-0049
+ affiliation: 1
+ - name: Andrew J Medford
+ orcid: 0000-0001-8311-9581
+ corresponding: true
+ affiliation: 1
+ - name: Phanish Suryanarayana
+ orcid: 0000-0001-5172-0049
+ corresponding: true
+ affiliation: [1, 2]
+affiliations:
+ - name: College of Engineering, Georgia Institute of Technology, Atlanta, GA 30332, USA
+ index: 1
+ - name: College of Computing, Georgia Institute of Technology, Atlanta, GA 30332, USA
+ index: 2
+ - name: Department of Chemical and Materials Engineering, University of Alberta, Edmonton AB, T6G 2R3, Canada
+ index: 3
+
+date: 18 November 2024
+bibliography: paper.bib
+---
+
+# Summary
+
+Density Functional Theory (DFT) is the de facto workhorse for
+large-scale electronic structure calculations in chemistry and materials science.
+While plane-wave DFT implementations remain the most widely used,
+real-space DFT provides advantages in handling complex boundary
+conditions and scaling to very large systems by allowing for the
+efficient use of large-scale supercomputers and linear-scaling methods
+that circumvent the cubic scaling bottleneck. The SPARC-X project
+([https://github.com/SPARC-X](https://github.com/SPARC-X)) provides
+highly efficient and portable real-space DFT codes
+for a wide range of first principle applications, available in both
+Matlab (M-SPARC [@xu_m-sparc-1.0_2020; @zhang_m-sparc-2.0_2023]) and C/C++
+(SPARC [@xu_sparc-1.0_2021; @zhang_sparc-2.0_2024]). The rapid growth
+of SPARC’s feature set has created the need for a fully functional
+interface to drive SPARC in high-throughput calculations. Here we
+introduce SPARC-X-API, a Python package designed to bridge the SPARC-X
+project with broader computational frameworks. Built on the atomic
+simulation environment (ASE [@larsen_ase_2017]) standard, the SPARC-X-API
+allows users to handle SPARC file formats and run SPARC calculations
+through the same interface as with other ASE-compatible DFT packages.
+Beyond standard ASE capabilities, SPARC-X-API provides additional
+features including 1) support of SPARC-specific setups, including
+complex boundary conditions and unit conversion, 2) a JSON schema
+parsed from SPARC's documentation for parameter validation and
+compatibility checks, and 3) a comprehensive socket communication layer
+derived from the i-PI protol [@ceriotti_i-pi-1.0_2014;
+@kapil_i-pi-2.0_2019] facilitating message passing between low-level C
+code and the Python interface. The goal of the SPARC-X-API is to provide a
+easy-to-use interface for users with diverse needs and levels of
+expertise, allowing for minimal effort in adapting SPARC to existing
+computational workflows, while also supporting developers of advanced
+real-space methods.
+
+# Statement of Need
+
+DFT has unargubaly become one of the cornerstones
+of electronic structure simulations in chemical and materials sciences due to
+its simplicity and wide range of applicability. While
+many researchers primarily associate DFT with the plane-wave
+pseudopotential method, due to the maturity and wide availability of
+such codes, these approaches do have limitations. One long-standing
+challenge in DFT is to develop methods that overcomes the huge
+computational cost for solving the Kohn-Sham equation, which scales
+cubically with respect to the system size. This becomes
+especially problematic in massively parallel computing environments,
+where the extensive global communication required during Fourier
+transformations limits the scalability, making it challenging to
+efficiently simulate very large systems in plane-wave DFT.
+In plane-wave methods, the global nature of the Fourier basis used limits the ability to
+achieve linear scaling [@bowler_order_n_dft_2012]. Moreover,
+the periodic nature of the Fourier basis enforces the use of periodic
+boundary conditions, making the simulation setup of isolated and
+semi-finite systems non-straightforward. A compelling
+alternative to overcome these limitations is to solve the Kohn-Sham
+equations using a finite-difference (FD) approach on real-space
+grids. The locality of the FD method makes real-space DFT methods
+inherently scalable, and paves the way for the development of
+linearly-scaling solutions to the Kohn-Sham equations.
+Real-space DFT also naturally supports both periodic and Dirichlet
+boundary conditions, and combinations thereof,
+allowing for the flexible treatment of systems in
+any dimensionality.
+
+In the past few years, the SPARC-X project
+([https://github.com/SPARC-X](https://github.com/SPARC-X)) has led
+efforts to develop an open-source, real-space DFT code that is both
+user-friendly and competitive with state-of-the-art plane-wave
+codes. The philosophy of the SPARC-X project is to provide codes that
+are highly efficient and portable (i.e. straightforward to install and
+use across various computational environments). The codes also seek to
+be user-friendly and developer-friendly to facilitate the
+implementation of new algorithms. In line with this, SPARC-X offers
+real-space DFT algorithms through two implementations: 1) Matlab-based
+M-SPARC [@xu_m-sparc-1.0_2020; @zhang_m-sparc-2.0_2023] for algorithm
+prototyping and small-system simulations, with no external
+dependencies other than Matlab itself, and 2) C/C++ based SPARC
+[@xu_sparc-1.0_2021; @zhang_sparc-2.0_2024] for large-scale production
+calculations that can accommodate a wide range of system sizes and
+requires only MPI and MKL/BLAS for compilation. New development of
+SPARC has covered topics including spin-orbit coupling, dispersion
+interactions, and advanced exchange-correlation (xc) functionals
+[@zhang_sparc-2.0_2024], linear-scaling Spectral Quadrature (SQ)
+method [@suryanarayana_sparc_sq_2018], cyclic/helical symmetry
+[@sharma_sparc_cyclix_2021], real-space density functional
+perturbation theory (DFPT) [@sharma_sparc_dfpt_2023], orbital-free DFT
+(ODFT) [@ghosh_sparc_ofdft_2016], on-the-fly machine-learning force
+fields (OTF-MLFF) [@kumar_ofdft_delta_ml_2023;
+@timmerman_sparc_mlff_2024; @kumar_sparc_mlff_2024]. The rapid
+development of SPARC has led to the need for a fully functional and
+user-friendly interface that facilitates the use of SPARC with
+high-throughput workflows. To address this, we introduce the
+SPARC-X-API, a Python interface designed to bridge the SPARC code with
+a wide range of scientific workflows. The SPARC-X-API builds upon the
+Python wrapper originally shipped with SPARC version 1.0
+[@xu_sparc-1.0_2021], offering an API compatible with the widely-used
+ASE (ASE [@larsen_ase_2017]) standard and updated with the latest
+versions of SPARC. With ASE's support for various popular DFT methods,
+including both plane-wave (e.g. VASP [@kresse_vasp_1996], Quantum
+ESPRESSO [@giannozzi_qe_2017], and Abinit [@gonze_abinit_2020]), and
+real-space (e.g. GPAW [@enkovaara_gpaw_1_2011; @mortensen_gpaw_2_2024]
+and Octopus [@tancogne_dejean_octopus_2020]) implementations,
+SPARC-X-API enables seamless integration of SPARC into existing
+workflows, allowing users to incorporate real-space DFT calculations
+with minimal adjustments. The modular design of SPARC-X-API makes it
+straightforward to be plugged into complex computational workflows,
+for example high-throughput dynamics simulations by i-PI
+[@litman_i-pi-3.0_2024] and PLUMED [@bonomi_plumed_2019], as
+well as active machine learning frameworks including FineTuna
+[@musielewicz_finetuna_2022], powered by state-of-art neural network
+interatomic potentials such as FAIR-Chem
+(https://github.com/FAIR-Chem/fairchem)[https://github.com/FAIR-Chem/fairchem]
+and MACE-MP [@ilyes_mace_2023] model series. A summary of the role
+SPARC-X-API in the SPARC-X project is shown in
+\autoref{fig:sparc-overview}. In addition to the capabilities
+inherited from ASE, SPARC-X-API seeks to enhance the user experience
+in a few key aspects, including 1) supporting SPARC-specific features
+in an ASE-comatible API, 2) a parameter validation mechanism based on
+SPARC's `LaTeX` documentation, and 3) a versatile socket communication
+layer for efficient high-throughput calculations. Details will be
+discussed in the Features and Functionalities section.
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+{ width=90% }
+
+
+
+# Features and Functionalities
+
+The SPARC-X-API is structured as a Python package, `sparc`. A summary of
+its key functionalities is provided below; for current detailed
+documentation, please refer to the [official
+documentation](https://sparc-x.github.io/SPARC-X-API).
+
+## `sparc.io`: File I/O Manupulation
+
+In SPARC and M-SPARC calculations, input information is provided
+by two files: a `.inpt` (cell dimensions, boundary conditions,
+calculation flags), and a `.ion` file (atomic configurations and
+locations to pseudopotential). Depending on the type of calculation,
+various output files may be written, such as`.static`, `.geopt` or
+`.aimd`. The separation of information across multiple files means
+converting ASE `Atoms` objects to SPARC input files or retrieving
+energy and forces information from SPARC calculations requires
+handling more than just a single file, as is common in most ASE I/O
+formats. To manage this, the SPARC-X-API operates on the directory level,
+treating each calculation directory as a "SPARC bundle". The
+`sparc.io.SparcBundle` class facilitates reading from and writing to
+this bundle, ensuring that all necessary input and output files are
+properly handled. By default, the SPARC-X-API also copies relevant
+pseudopotential files into the calculation directory, making the SPARC
+bundle portable across different machines. From version 2.0 onwards,
+the SPARC-X-API leverages the new features introduced in ASE version 3.23
+to register as an external I/O format, allowing reading and writing
+SPARC files directly using `ase.io` submodule:
+
+```py
+from ase.io import read, write
+# 1. Read a SPARC bundle by specifying the `sparc` format
+atoms = read("sparc_output_dir", format="sparc")
+# 2. Write to a SPARC bundle from aboth object
+write("sparc_input_dir", atoms, format="sparc")
+```
+
+The SPARC-X-API also supports parsing complex boundary conditions from the
+`.inpt` file. The periodic (P) and Dirichlet (D) boundary conditions
+are translated into `True` and `False` values, respectively, in the
+corresponding `pbc` direction of an `Atoms` object. Standard ASE
+objects do not natively support cyclic (C) or helical (H) boundary
+conditions that are available in SPARC, so the SPARC-X-API
+treats them similarly to Dirichlet boundaries
+and stores the original boundary condition information in the `info`
+attribute of the atomic object. This ensures that the correct boundary
+combinations are preserved when re-writing to SPARC input files.
+
+
+## `sparc.api`: Parameter Validation
+
+In the ASE ecosystem, default calculator interfaces such as
+`FileIOCalculator` do not implement parameter validation, which can
+lead to issues such as incorrect parameter settings or incompatibility
+when running calculations through ASE. To address this, the SPARC-X-API
+introduces a robust parameter validation system using a JSON schema
+generated from SPARC’s [LaTeX
+documentation](https://github.com/SPARC-X/SPARC/tree/master/doc/.LaTeX). A
+JSON schema contains the version of the SPARC software, a list of
+input parameters used in `.inpt` and `.ion` files, as well as
+supported data types and parameter categories. Validation is handled via the `sparc.api.SparcAPI` class, and includes:
+
+- Verify that the schema is compatible with the version of SPARC binary.
+- Convert `.inpt` fields into Python data types.
+- Validate input parameters in both string and numerical formats.
+- Output help information about specific parameter(s).
+
+Each release of the SPARC-X-API contains a copy of a JSON schema linked
+with the latest SPARC release as the default validator, although the
+user is can select different combination of SPARC versions and
+schemas depending on the version they are using. The separation between the
+SPARC-X-API and the core SPARC code not only
+prevents the need for hard-coding parameter lists into the API, but
+also facilitates easier maintenance: the "central truth" of parameters
+remains in the SPARC documentation, maintained by the SPARC core
+developers, while the SPARC-X-API focuses on providing a user-friendly
+interface without being tied to constant updates. This approach maximizes
+flexibility and avoids version conflicts between the API and the underlying code.
+
+## `sparc.calculator`: Socket-Communication Calculator Interface
+
+The submodule `sparc.calculator` provides a class `SPARC` as the main
+entry point for driving SPARC calculations. This class provides two modes
+of operation: 1) a file I/O-based calculator extending the
+`ase.calculators.FileIOCalculator` class, and 2) a comprehensive
+socket communication layer that allows direct communication between
+the Python API and low-level C/C++ code.
+
+In file I/O mode, the SPARC calculator object utilizes the
+`sparc.io.SparcBundle` for generating input files and
+`sparc.api.SparcAPI` for parameter validation, while the mode of
+calculation (single-point, relaxation or molecular dynamics) is
+controlled by the input flags. For users transitioning from other DFT
+packages and their ASE calculators, the SPARC-X-API is designed to
+minimize adaptation effort, but the API is designed to also enable
+advanced inputs from expert users. The `SPARC` calculator class
+achieves this by supporting two sets
+of input parameters: 1) lower-case special parameters that follow
+conventions from other ASE DFT calculators (e.g. real-space grid
+spacing `h` from GPAW, and exchange-correlation keyword `xc` from
+VASP) that use the ASE default Angstrom-eV system, and 2) case-insensitive raw SPARC
+input parameters in Bohr-Hartree units for fine-grained control. This
+dual approach is designed so that users familiar with other DFT codes
+can adopt SPARC with minimal changes to their existing
+workflows, while expert users can exert full control.
+Basic DFT calculations can be covered by using standard ASE
+parameter sets in the SPARC-X-API, as shown by the side-by-side
+constructor with VASP and GPAW, using the same
+exchange-correlation functional and compatible convergence settings:
+
+
+```py
+#1. Using VASP
+from ase.calculators.vasp import Vasp
+calc = Vasp(xc="pbe", kpts=(9, 9, 9), ecut=450, ediff=1.e-4)
+
+#2. Using GPAW
+from gpaw import GPAW
+calc = GPAW(xc="pbe", kpts=(9, 9, 9), h=0.25, convergence={"energy": 1.e-4})
+
+#3. Using SPARC
+from sparc.calculator import SPARC
+calc = SPARC(xc="pbe", kpts=(9, 9, 9), h=0.25, convergence={"energy": 1.e-4})
+```
+
+In high-throughput frameworks requiring thousands of single-point DFT
+evaluations, relying on file I/O mode can be inefficient, as
+calculations are restarted at each DFT call and the total number of
+files may exceed SPARC's default file count limit. The socket layer in
+the SPARC-X-API avoids these limitations by directly communicating with a
+long-running SPARC process for updating atomic positions, while
+keeping density and orbitals in memory and reducing self-consistent
+field (SCF) cycles. While alternative communication methods exist,
+such as C-binding approaches seen in GPAW [@mortensen_gpaw_2_2024] and
+Psi4 [@smith_psi4_2020], these typically involve complex compilation
+and integration steps when installing the Python package. We chose a
+socket-based communication layer for its simplicity, which allows for
+a clear separation between the Python and SPARC codebases, minimal
+modifications to the existing C/C++ code, and ease of installation without
+requiring recompilation.
+
+The communication protocol used in the SPARC-X-API socket, referred to as the
+SPARC protocol, is based on the i-PI protocol
+[@ceriotti_i-pi-1.0_2014; @kapil_i-pi-2.0_2019], which is also adapted
+by a wide range of ASE calculators. The SPARC protocol introduces
+additional header types and supporting binary data transfers via
+Python's pickle format. While SPARC’s C/C++ code maintains compatibility
+with the original i-PI standard, the SPARC-X-API leverages the extended
+protocol with pickle decoding. The two-tier design offers flexibility
+for socket calculations. At its core, the SPARC binary can communicate
+directly with any i-PI-compatible server, such as
+`ase.calculators.socketio.SocketIOCalculator` in ASE, using the basic
+protocol, though this requires careful setup by the user.
+However, the SPARC-X-API leverages the
+SPARC protocol, which allows the API to internally relay more advanced
+ data types to the SPARC
+binary, handling object decoding and socket resets automatically. When
+running socket calculations on a single machine, users can activate
+socket mode by simply adding `use_socket=True` to the `SPARC`
+calculator constructor, enabling UNIX socket communication without
+additional setup. More importantly, the design of the SPARC protocol
+allows easy and seamless integration in distributed computational
+systems, offering the following features: 1) flexible client
+initialization / restart 2) efficient data transfer 3) heterogeneous
+computational setup.
+The design of the SPARC protocol allows insertion of bidirectional
+additional routines between two DFT calls, allowing further control
+over the low-level C/C++ code.
+Figure \autoref{fig:socket-hetero} summarizes the
+server-client setup across hybrid computing platforms.
+
+{ width=100% }
+
+
+
+## Miscellaneous Helper Functionalities
+
+The SPARC-X-API also provides several helper functions to facilitate user
+installation and testing, including:
+
+- `sparc.quicktest`: a utility to verify the installation and
+ environment setups for `SPARC-X-API` and `SPARC`.
+- `sparc.docparser`: a submodule to convert existing `LaTeX`
+ documentation included in SPARC source code into JSON schema.
+- `sparc.download_data`: a tool to download the latest ONCV
+ pseudopotentials released by SPARC.
+- `sparc-ase`: an extension to the commandline `ase` tool, adding
+ compatibility with SPARC file formats.
+
+# Code Release and Maintenance
+
+The SPARC-X-API is released as source code in github repository
+[https://github.com/SPARC-X/SPARC-X-API](https://github.com/SPARC-X/SPARC-X-API),
+and as a `conda-forge` package
+[`sparc-x-api`](https://anaconda.org/conda-forge/sparc-x-api). When
+installed using `conda-forge`, the package is bundled with the
+optimized pseudopotentials [@shojaei_sparc_pseudopot_2023], and
+compatible with the
+[`sparc`](https://anaconda.org/conda-forge/sparc-x) package that
+contains the compiled SPARC binary.
+
+It also integrates continuous integration (CI) workflows for:
+
+- Unit testing and code coverage
+- Fetching the latest SPARC documentation for updating the JSON schema
+- Validating all test examples from the SPARC repository
+
+These workflows ensure that SPARC-X-API remains up-to-date with
+ongoing SPARC developments while separating parameter updates from the
+main SPARC maintainers’ efforts.
+
+# Acknowledgements
+
+The authors gratefully acknowledge the support of the U.S. Department
+of Energy, Office of Science, under Grant No. DE-SC0019410 and
+DE-SC0023445.
+
+
+# References