From 118765d6ed807bad162a0e7f1c35dde5f73ef774 Mon Sep 17 00:00:00 2001 From: "T.Tian" Date: Tue, 24 Sep 2024 16:43:49 +0800 Subject: [PATCH 01/16] Add initial paper md/ref for joss --- paper/paper.bib | 253 ++++++++++++++++++++++++++++++++++++++++++++++++ paper/paper.md | 57 +++++++++++ 2 files changed, 310 insertions(+) create mode 100644 paper/paper.bib create mode 100644 paper/paper.md diff --git a/paper/paper.bib b/paper/paper.bib new file mode 100644 index 00000000..95e11d82 --- /dev/null +++ b/paper/paper.bib @@ -0,0 +1,253 @@ +%% 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}, + bdsk-url-2 = {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}, + bdsk-url-2 = {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}, + bdsk-url-2 = {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, + bdsk-url-1 = {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, + bdsk-url-1 = {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, + bdsk-url-1 = {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, + bdsk-url-1 = {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 = {Larsen, Ask Hjorth and Mortensen, Jens J{\o}rgen and Blomqvist, Jakob and Castelli, Ivano E. and Christensen, Rune and Du{\l}ak, Marcin and Friis, Jesper and Groves, Michael N. and Hammer, Bj{\o}rk and Hargus, Cory and Hermes, Eric D. and Jennings, Paul C. and Jensen, Peter Bjerre and Kermode, James and Kitchin, John R. and Kolsbjerg, Esben Leonhard and Kubal, Joseph and Kaasbjerg, Kristen and Lysgaard, Steen and Maronsson, J{\'o}n Bergmann and Maxson, Tristan and Olsen, Thomas and Pastewka, Lars and Peterson, Andrew and Rostgaard, Carsten and Schi{\o}tz, Jakob and Sch{\"u}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.}, + date-modified = {2024-09-24 16:33:31 +0800}, + issn = {0953-8984}, + journaltitle = {J. Phys.: Condens. Matter}, + number = {27}, + pages = {273002}, + title = {The atomic simulation environment---a Python library for working with atoms}, + volume = {29}, + bdsk-url-1 = {https://dx.doi.org/10.1088/1361-648X/aa680e}} + +@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 = {https://www.nature.com/articles/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}, + } diff --git a/paper/paper.md b/paper/paper.md new file mode 100644 index 00000000..3d14bab9 --- /dev/null +++ b/paper/paper.md @@ -0,0 +1,57 @@ +--- +title: 'SPARC-X-API: Versatile Python Interface for Atomistic Ab-initio Real-space Calculations' +tags: + - Density Functional Theories + - Atomistic Simulations + - Python + - Atomic Simulation Environment + - Socket Interface +authors: + - name: Tian Tian + orcid: + affiliation: [1,2] + - name: Lucas Timmerman + orcid: + affiliation: 1 + - name: Shashikant Kumar + affiliation: 2 + - 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: [2, 3] +affiliations: + - name: School of Civil and Environmental Engineering, Georgia Institute of Technology + index: 1 + - name: School of Chemical and Biomolecular Engineering, Georgia Institute of Technology + index: 2 + - name: School of Computational Science and Engineering, Georgia Institute of Technology + index: 3 + +date: 24 September 2024 +bibliography: paper.bib +--- + +# Summary + + + + +# Statement of Need + + + +# Brief Description of the Program Use and Features + + + +# Acknowledgements + + +# References From 6a77f19ae1c2377f98368358177d01b0a863fdcf Mon Sep 17 00:00:00 2001 From: "T.Tian" Date: Tue, 24 Sep 2024 16:46:59 +0800 Subject: [PATCH 02/16] add readme in joss folder --- paper/README.md | 13 +++++++++++++ 1 file changed, 13 insertions(+) create mode 100644 paper/README.md diff --git a/paper/README.md b/paper/README.md new file mode 100644 index 00000000..efcd1c4d --- /dev/null +++ b/paper/README.md @@ -0,0 +1,13 @@ +# 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. + +## Using Building Actions + +TBD + +## Building Locally + +TBD From 748bd533b4544d1279babcbcaaecdad38881872f Mon Sep 17 00:00:00 2001 From: "T.Tian" Date: Sat, 28 Sep 2024 19:51:27 +0800 Subject: [PATCH 03/16] add joss paper workflow --- .github/workflows/joss_paper.yml | 24 ++++++++++++++++++++++++ .gitignore | 2 ++ paper/README.md | 15 +++++++++++++-- 3 files changed, 39 insertions(+), 2 deletions(-) create mode 100644 .github/workflows/joss_paper.yml diff --git a/.github/workflows/joss_paper.yml b/.github/workflows/joss_paper.yml new file mode 100644 index 00000000..be05c21a --- /dev/null +++ b/.github/workflows/joss_paper.yml @@ -0,0 +1,24 @@ +name: Draft Paper for JOSS +on: + push: + paths: + - paper/** + - .github/workflows/joss_paper.yml + +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 cc5cbc82..e93c03b0 100644 --- a/.gitignore +++ b/.gitignore @@ -784,3 +784,5 @@ examples/ex1-ase/ /test-2/ *.pt /README.html +/paper/paper.pdf +/paper/jats/ diff --git a/paper/README.md b/paper/README.md index efcd1c4d..9c2bdd62 100644 --- a/paper/README.md +++ b/paper/README.md @@ -6,8 +6,19 @@ SPARC doc in this directory. ## Using Building Actions -TBD + ## Building Locally -TBD +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. From be6132a2a343f4c63c95c547bfdd6f88608e4a9d Mon Sep 17 00:00:00 2001 From: "T.Tian" Date: Sat, 28 Sep 2024 20:15:31 +0800 Subject: [PATCH 04/16] update readme in the joss_paper branch --- paper/README.md | 18 +++++++++++++----- 1 file changed, 13 insertions(+), 5 deletions(-) diff --git a/paper/README.md b/paper/README.md index 9c2bdd62..5386dffc 100644 --- a/paper/README.md +++ b/paper/README.md @@ -2,17 +2,16 @@ 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. - -## Using Building Actions - - +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 \ @@ -22,3 +21,12 @@ docker run --rm \ 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/alchem0x2A/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. From 063a77abd643a3646e8516dcfd76242be7c2ed08 Mon Sep 17 00:00:00 2001 From: "T.Tian" Date: Mon, 30 Sep 2024 10:03:08 +0800 Subject: [PATCH 05/16] update refs --- paper/paper.bib | 66 +++++++++++++++++++++ paper/paper.md | 148 +++++++++++++++++++++++++++++++++++++++++++++++- 2 files changed, 211 insertions(+), 3 deletions(-) diff --git a/paper/paper.bib b/paper/paper.bib index 95e11d82..7a59ed1f 100644 --- a/paper/paper.bib +++ b/paper/paper.bib @@ -251,3 +251,69 @@ @article{bonomi_plumed_2019 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} +} diff --git a/paper/paper.md b/paper/paper.md index 3d14bab9..b8b0e75c 100644 --- a/paper/paper.md +++ b/paper/paper.md @@ -1,5 +1,5 @@ --- -title: 'SPARC-X-API: Versatile Python Interface for Atomistic Ab-initio Real-space Calculations' +title: 'SPARC-X-API: Versatile Python Interface for Real-space Density Functional Theory Calculations' tags: - Density Functional Theories - Atomistic Simulations @@ -40,16 +40,158 @@ bibliography: paper.bib # Summary +Density Functional Theory (DFT) is the de facto gold standard for +electronic structure calculations in chemistry and materials +science. While plane-wave DFT remains the most widely used, real-space +DFT provides advantages in handling complex boundary conditions and +scaling to very large systems. The SPARC-X project +(https://github.com/SPARC-X) has pioneered highly efficient real-space +DFT codes available in both Matlab [@xu_m-sparc-1.0_2020; +@zhang_m-sparc-2.0_2023] and C [@xu_sparc-1.0_2021; +@zhang_sparc-2.0_2024]. However, the specific input formats for SPARC +have often made it challenging for users accustomed to plane-wave DFT +to transition to real-space methods. To address this, we introduce +SPARC-X-API, a Python interface designed to bridge the SPARC-X project +with broader computational frameworks. Built on the atomic simulation +environment (ASE [@larsen_ase_2017]) standard, SPARC-X-API allows +users to handle SPARC file formats, and run SPARC calculations using +the same interface as with other computational packages. SPARC-X-API +provides additional features beyond the standard ASE package, +including 1) support of complex boundary conditions, 2) a JSON schema +for validating and converting calculation parameters, and 3) a +comprehensive calculator interface with advanced socket-communication +support. SPARC-X-API provides a smooth transition for users from +plane-wave DFT, making the access to real-space DFT calculations more +available and flexible for a wider range of users and computational +workflows. +# Statement of Need +Kohn-Sham Density Functional Theory (DFT) has unargubaly become the +cornerstone of electronic simulations in chemical and materials +sciences due to its simplicity and applications across a wide range of +systems. The popularity of DFT over other first-principle methods in +materials simulation largely stems from the simplicity of the +plane-wave pseudopotential implementation, where convergence is +controlled by simply the plane-wave cutoff energy, and solving the +Kohn-Sham equations can be benefited from highly-optimized Fast +Fourier Transform (FFT) packages. While many non-theoretical +researchers may associate DFT exclusively with plane-wave +implementations, this approach has notable limitations. 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. Additionally, the global nature of the +Fourier basis causes plane-wave codes to scale poorly with increasing +numbers of parallel processes. A compelling alternative to overcome +these limitations is to solve the Kohn-Sham equations using a +finite-difference approach on real-space grids. Real-space DFT +naturally supports both periodic and Dirichlet boundary conditions, +allowing for the flexible treatment of systems in any +dimensionality. Furthermore, the locality of the finite-difference +grids makes real-space DFT methods inherently scalable, paving the way +for the development of linearly-scaling solutions to the Kohn-Sham +equations. -# Statement of Need + Despite the advantages of +real-space DFT, plane-wave implementations remain dominant in the +field of computational chemistry and materials science, largely due to +the greater accessibility of plane-wave DFT codes and their more +established programmable interfaces. While real-space DFT offers +significant benefits, there are currently few widely used packages +that provide comprehensive real-space DFT capabilities. + +The only notable exception has been GPAW +[@mortensen_gpaw_original_2005; @enkovaara_gpaw_1_2011; +@mortensen_gpaw_2_2024], which originally focused on real-space +finite-difference methods. However, in recent years, the development +of GPAW has shifted its focus toward plane-wave implementations +[@@mortensen_gpaw_2_2024], leaving its finite-difference capabilities +underdeveloped and missing key functionality. In contrast, the SPARC-X +project (https://github.com/SPARC-X) has pioneered 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. + +SPARC-X offers real-space DFT algorithms through two implementations: +M-SPARC [@xu_m-sparc-1.0_2020; @zhang_m-sparc-2.0_2023] for +prototyping and small-system simulations, and 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. Although SPARC has demonstrated its computational efficiency +and features a rich set of algorithms, its adoption has been limited +by the lack of a user-friendly interface that can connect the code to +a broader audience of users and computational tools. + +To address this, we introduce SPARC-X-API, a Python-based interface +designed to bridge the SPARC-X code with a broader range of scientific +workflows. Built on the Atomic Simulation Environment (ASE +[@larsen_ase_2017]) standard, SPARC-X-API provides seamless file +read/write support for SPARC files and a feature-complete calculator +interface to the SPARC code. With SPARC-X-API, researchers can easily +incorporate real-space DFT into their workflows using familiar tools +and interfaces, making real-space DFT more accessible to a wider range +of users. + + + + + + +# Features and Functionalities + +SPARC-X-API offers two key functionalities: + +- File I/O: Through the sparc.io submodule, SPARC-X-API implements + file read/write support for SPARC file formats, including .inpt and + .ion files. SPARC-X-API operates on the directory level, treating + each calculation directory as a "SPARC bundle." From version 1.0 + onwards, SPARC-X-API is fully integrated with ASE (version 3.23), + automatically registering SPARC as an external I/O format. +- Calculator Interface: The sparc.calculator submodule provides a full + ASE-compatible calculator interface for running SPARC calculations, + enabling integration with ASE workflows. + +Unique Features of SPARC-X-API: + +1) Support for Bundled File Formats: Unlike typical single-file DFT implementations, SPARC requires both .inpt and .ion files. SPARC-X-API's design simplifies this by reading and writing at the directory level, streamlining the handling of SPARC bundles. + +2) JSON Schema for Parameter Validation: SPARC-X-API ensures parameter +consistency through a JSON schema derived from SPARC's LaTeX +documentation. This guarantees compatibility with SPARC's source code, +offering a robust mechanism for validating and converting parameters. +3) Unit Conversions: SPARC-X-API manages the conversion between atomic +units (Hartree, Bohr) used in SPARC and the eV/Å units in ASE. + +## Socket-Communication Calculator Interface +SPARC-X-API’s socket-communication layer allows for efficient and +flexible workflows by reducing the overhead of file I/O. This feature +is particularly useful for iterative calculations, such as structural +optimizations and saddle point searches, where traditional file-based +communication can become a bottleneck. +Key advantages: +Efficiency: Eliminates intermediate file I/O by streaming data +directly between processes. Speed: Enhances performance in iterative +calculations, critical for large-scale simulations. Flexibility: +Enables real-time modification of calculation parameters without +restarting processes. SPARC-X-API implements a backward-compatible +i-PI protocol, allowing both low-level and high-level interfacing with +SPARC's DFT code. -# Brief Description of the Program Use and Features +# Code Release and Maintenance +SPARC-X-API maximizes accessibility for users by providing streamlined +installation via the conda-forge channel, where the sparc-x-api +package can be installed with default ONCV pseudopotentials. It also +integrates continuous integration (CI) and continuous deployment (CD) +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 From 5b7d39be3c62b7e57420542837f60be59a42ac83 Mon Sep 17 00:00:00 2001 From: "T.Tian" Date: Tue, 15 Oct 2024 17:31:39 +0800 Subject: [PATCH 06/16] update --- paper/paper.md | 9 ++++++++- 1 file changed, 8 insertions(+), 1 deletion(-) diff --git a/paper/paper.md b/paper/paper.md index b8b0e75c..6483f263 100644 --- a/paper/paper.md +++ b/paper/paper.md @@ -152,7 +152,10 @@ SPARC-X-API offers two key functionalities: Unique Features of SPARC-X-API: -1) Support for Bundled File Formats: Unlike typical single-file DFT implementations, SPARC requires both .inpt and .ion files. SPARC-X-API's design simplifies this by reading and writing at the directory level, streamlining the handling of SPARC bundles. +1) Support for Bundled File Formats: Unlike typical single-file DFT +implementations, SPARC requires both .inpt and .ion +files. SPARC-X-API's design simplifies this by reading and writing at +the directory level, streamlining the handling of SPARC bundles. 2) JSON Schema for Parameter Validation: SPARC-X-API ensures parameter consistency through a JSON schema derived from SPARC's LaTeX @@ -195,5 +198,9 @@ 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 From 911ce561b3bfdddc62e04d0d64397878caab7d88 Mon Sep 17 00:00:00 2001 From: "T.Tian" Date: Wed, 16 Oct 2024 23:12:45 +0800 Subject: [PATCH 07/16] update joss paper and 1 figure --- paper/fig/fig_socket_hetero.svg | 1493 +++++++++++++++++++++++++++++++ paper/paper.bib | 307 +++++++ paper/paper.md | 477 +++++++--- 3 files changed, 2136 insertions(+), 141 deletions(-) create mode 100644 paper/fig/fig_socket_hetero.svg diff --git a/paper/fig/fig_socket_hetero.svg b/paper/fig/fig_socket_hetero.svg new file mode 100644 index 00000000..031001f9 --- /dev/null +++ b/paper/fig/fig_socket_hetero.svg @@ -0,0 +1,1493 @@ + + + + + + + + + + + + + + + ++ + + + + + + + + + + + + + + + + + + + + + + + +.inpt.out.ion.staticHardwareSoftwareINET socketserver:31415SPARC protocol(extending i-PI )(No file access)Server Node (AWS instance, GPU node, etc)Native i-PI Protocol/tmp/ipi_sparc_*Local file I/OComputational Nodes (CPU-intensive)SPARC C-binarympirun -np 256 sparc \ -n 8 -c 32 \ -name $fname \ -socket $sname:unixSPARC-X-API (Socket Client)Pickle dataExtra-info parsingE, F, SSPARCCalculatorSPARC-X-API (Socket Server)• ML models• Sampling algorithmsPickle dataSPARCCalculatorTraining Inferencehead nodenode groupsUNIX socketClient 1Client N...... diff --git a/paper/paper.bib b/paper/paper.bib index 7a59ed1f..c498a005 100644 --- a/paper/paper.bib +++ b/paper/paper.bib @@ -317,3 +317,310 @@ @article{mortensen_gpaw_2_2024 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 Abinitproject: 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} +} diff --git a/paper/paper.md b/paper/paper.md index 6483f263..0eb21d18 100644 --- a/paper/paper.md +++ b/paper/paper.md @@ -8,13 +8,14 @@ tags: - Socket Interface authors: - name: Tian Tian - orcid: - affiliation: [1,2] + orcid: 0000-0003-0634-0455 + affiliation: 1 - name: Lucas Timmerman orcid: affiliation: 1 - name: Shashikant Kumar - affiliation: 2 + orcid: 0009-0001-5134-1580 + affiliation: 1 - name: Ben Comer orcid: 0000-0002-7528-0049 affiliation: 1 @@ -25,14 +26,12 @@ authors: - name: Phanish Suryanarayana orcid: 0000-0001-5172-0049 corresponding: true - affiliation: [2, 3] + affiliation: [1, 2] affiliations: - - name: School of Civil and Environmental Engineering, Georgia Institute of Technology + - name: College of Engineering, Georgia Institute of Technology, Atlanta, GA 30332, USA index: 1 - - name: School of Chemical and Biomolecular Engineering, Georgia Institute of Technology + - name: College of Computing, Georgia Institute of Technology, Atlanta, GA 30332, USA index: 2 - - name: School of Computational Science and Engineering, Georgia Institute of Technology - index: 3 date: 24 September 2024 bibliography: paper.bib @@ -41,152 +40,348 @@ bibliography: paper.bib # Summary Density Functional Theory (DFT) is the de facto gold standard for -electronic structure calculations in chemistry and materials -science. While plane-wave DFT remains the most widely used, real-space -DFT provides advantages in handling complex boundary conditions and -scaling to very large systems. The SPARC-X project -(https://github.com/SPARC-X) has pioneered highly efficient real-space -DFT codes available in both Matlab [@xu_m-sparc-1.0_2020; -@zhang_m-sparc-2.0_2023] and C [@xu_sparc-1.0_2021; -@zhang_sparc-2.0_2024]. However, the specific input formats for SPARC -have often made it challenging for users accustomed to plane-wave DFT -to transition to real-space methods. To address this, we introduce -SPARC-X-API, a Python interface designed to bridge the SPARC-X project -with broader computational frameworks. Built on the atomic simulation -environment (ASE [@larsen_ase_2017]) standard, SPARC-X-API allows -users to handle SPARC file formats, and run SPARC calculations using -the same interface as with other computational packages. SPARC-X-API -provides additional features beyond the standard ASE package, -including 1) support of complex boundary conditions, 2) a JSON schema -for validating and converting calculation parameters, and 3) a -comprehensive calculator interface with advanced socket-communication -support. SPARC-X-API provides a smooth transition for users from -plane-wave DFT, making the access to real-space DFT calculations more -available and flexible for a wider range of users and computational -workflows. +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 straightforward-to-install 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 +(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, 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 validating and +compatibility check, 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 Python interface. The goal of 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 -Kohn-Sham Density Functional Theory (DFT) has unargubaly become the -cornerstone of electronic simulations in chemical and materials -sciences due to its simplicity and applications across a wide range of -systems. The popularity of DFT over other first-principle methods in -materials simulation largely stems from the simplicity of the -plane-wave pseudopotential implementation, where convergence is -controlled by simply the plane-wave cutoff energy, and solving the -Kohn-Sham equations can be benefited from highly-optimized Fast -Fourier Transform (FFT) packages. While many non-theoretical -researchers may associate DFT exclusively with plane-wave -implementations, this approach has notable limitations. 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. Additionally, the global nature of the -Fourier basis causes plane-wave codes to scale poorly with increasing -numbers of parallel processes. A compelling alternative to overcome -these limitations is to solve the Kohn-Sham equations using a -finite-difference approach on real-space grids. Real-space DFT -naturally supports both periodic and Dirichlet boundary conditions, -allowing for the flexible treatment of systems in any -dimensionality. Furthermore, the locality of the finite-difference -grids makes real-space DFT methods inherently scalable, paving the way -for the development of linearly-scaling solutions to the Kohn-Sham -equations. - - Despite the advantages of -real-space DFT, plane-wave implementations remain dominant in the -field of computational chemistry and materials science, largely due to -the greater accessibility of plane-wave DFT codes and their more -established programmable interfaces. While real-space DFT offers -significant benefits, there are currently few widely used packages -that provide comprehensive real-space DFT capabilities. - -The only notable exception has been GPAW -[@mortensen_gpaw_original_2005; @enkovaara_gpaw_1_2011; -@mortensen_gpaw_2_2024], which originally focused on real-space -finite-difference methods. However, in recent years, the development -of GPAW has shifted its focus toward plane-wave implementations -[@@mortensen_gpaw_2_2024], leaving its finite-difference capabilities -underdeveloped and missing key functionality. In contrast, the SPARC-X -project (https://github.com/SPARC-X) has pioneered 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. - -SPARC-X offers real-space DFT algorithms through two implementations: -M-SPARC [@xu_m-sparc-1.0_2020; @zhang_m-sparc-2.0_2023] for -prototyping and small-system simulations, and SPARC +Density Functional Theory (DFT) has unargubaly become the cornerstone +of electronic simulations in chemical and materials sciences due to +its simplicity and applications across a wide range of systems. 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. In plane-wave methods, +the global nature of the Fourier basis used limits the ability to +achieve linear scaling [@bowler_order_n_dft_2012]. 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. 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 grids makes real-space DFT methods +inherently scalable, paving 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, 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 +pioneered 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 easy to implement new algorithms, highly portable, and +straightforward to install and use across various computational +environments. 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-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. Although SPARC has demonstrated its computational efficiency -and features a rich set of algorithms, its adoption has been limited -by the lack of a user-friendly interface that can connect the code to -a broader audience of users and computational tools. +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; @kumar_ofdft_delta_ml_2023], +on-the-fly machine-learning force fields (OTF-MLFF) +[@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 fully automate SPARC calculation in +high-throughput scenarios. To address this, we introduce SPARC-X-API, +a Python interface designed to bridge the SPARC code with a +broader range of scientific workflows. 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 +Atomic Simulation Environment (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. A summary of the role +SPARC-X-API in the SPARC-X project is shown in +\ref{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. -To address this, we introduce SPARC-X-API, a Python-based interface -designed to bridge the SPARC-X code with a broader range of scientific -workflows. Built on the Atomic Simulation Environment (ASE -[@larsen_ase_2017]) standard, SPARC-X-API provides seamless file -read/write support for SPARC files and a feature-complete calculator -interface to the SPARC code. With SPARC-X-API, researchers can easily -incorporate real-space DFT into their workflows using familiar tools -and interfaces, making real-space DFT more accessible to a wider range -of users. + + + + + + + + + + + + + + + + + + + + + + + + + + + + - +![**NEED REVISION** Overview of SPARC-X-API in the SPARC-X project system +\label{fig:sparc-overview} +](){ width=100% } - # Features and Functionalities -SPARC-X-API offers two key functionalities: - -- File I/O: Through the sparc.io submodule, SPARC-X-API implements - file read/write support for SPARC file formats, including .inpt and - .ion files. SPARC-X-API operates on the directory level, treating - each calculation directory as a "SPARC bundle." From version 1.0 - onwards, SPARC-X-API is fully integrated with ASE (version 3.23), - automatically registering SPARC as an external I/O format. -- Calculator Interface: The sparc.calculator submodule provides a full - ASE-compatible calculator interface for running SPARC calculations, - enabling integration with ASE workflows. - -Unique Features of SPARC-X-API: - -1) Support for Bundled File Formats: Unlike typical single-file DFT -implementations, SPARC requires both .inpt and .ion -files. SPARC-X-API's design simplifies this by reading and writing at -the directory level, streamlining the handling of SPARC bundles. - -2) JSON Schema for Parameter Validation: SPARC-X-API ensures parameter -consistency through a JSON schema derived from SPARC's LaTeX -documentation. This guarantees compatibility with SPARC's source code, -offering a robust mechanism for validating and converting parameters. -3) Unit Conversions: SPARC-X-API manages the conversion between atomic -units (Hartree, Bohr) used in SPARC and the eV/Å units in ASE. - -## Socket-Communication Calculator Interface -SPARC-X-API’s socket-communication layer allows for efficient and -flexible workflows by reducing the overhead of file I/O. This feature -is particularly useful for iterative calculations, such as structural -optimizations and saddle point searches, where traditional file-based -communication can become a bottleneck. - -Key advantages: - -Efficiency: Eliminates intermediate file I/O by streaming data -directly between processes. Speed: Enhances performance in iterative -calculations, critical for large-scale simulations. Flexibility: -Enables real-time modification of calculation parameters without -restarting processes. SPARC-X-API implements a backward-compatible -i-PI protocol, allowing both low-level and high-level interfacing with -SPARC's DFT code. +SPARC-X-API is structured as a Python package `sparc`. A summary of +its key functionalities is provided below, and for detailed +documentation, please refer to the [official +documentation](https://github.com/SPARC-X/SPARC-X-API/blob/master/README.md). + +## `sparc.io`: File I/O Manupulation + +In SPARC and M-SPARC calculations, the input information are 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, 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, 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, +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") +``` + +SPARC-X-API 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. While standard ASE +objects do not natively support cyclic (C) or helical (H) boundary +conditions, SPARC-X-API treats them similarly to Dirichlet boundaries +and stores the original boundary condition information in the `info` +attribute of the atomic object, to preserve the correct boundary +combinations when re-writing to SPARC input files. + + +## `sparc.api`: Parameter Validation + +In the ASE ecosystem, the default calculator interface such as +`FileIOCalculator` does not implement parameter validation, which can +lead to issues such as incorrect parameter settings or incompatibility +when providing running calculations. To address this, 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 categorizes. The validation is handled via the `sparc.api.SparcAPI` class, including: +- 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 SPARC-X-API contains a copy of a JSON schema linked +with the latest SPARC release as the default validator, although the +user is free to choose a different combination of SPARC versions and +schemas. The separation between SPARC-X-API and SPARC 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 SPARC-X-API can focus on providing a user-friendly +interface without being tied to constant updates, maximizing +flexibility. + +## `sparc.calculator`: Socket-Communication Calculator Interface + +The submodule `sparc.calculator` provides a class `SPARC` as the main +entry point for driving SPARC calculations, which 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-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, SPARC-X-API is designed to +minimize adaptation effort. `SPARC` calculator class supports 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 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. Basic DFT calculations can be covered by using special +parameter sets alone in 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 easily exceeds SPARC's file count limit. The socket layer in +SPARC-X-API avoids this overhead by direct 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 code, and ease of installation without +requiring recompilation. + +The communication protocol used in SPARC-X-API, 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-code maintains compatibility +with the original i-PI standard, SPARC-X-API leverages this extended +version 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. SPARC-X-API +further makes running socket mode calculations at ease. Leveraging the +SPARC protocol, the API internally relays socket data 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 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 \autoref{fig:socket-hetero} summarizes the +server-client setup across hybrid computing platforms. + +![**NEED REVISION** Example of socket communication across hybrid computing platforms using SPARC-X-API +\label{fig:socket-hetero} +](fig/fig_socket_hetero.svg){ width=100% } + + +The design of the SPARC protocol allows insertion of bidirectional +additional routines between two DFT calls, allowing further control +over the low-level C-code. + + + +## Miscellaneous Helper Functionalities + +SPARC-X-API provides several helper functions to facilitate user +installation and testing, inlcuding: + +- `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 -SPARC-X-API maximizes accessibility for users by providing streamlined -installation via the conda-forge channel, where the sparc-x-api -package can be installed with default ONCV pseudopotentials. It also -integrates continuous integration (CI) and continuous deployment (CD) -workflows for: + +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 +installing 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 From af6b399c1cc399265b51ddb9cc5339d19e0945af Mon Sep 17 00:00:00 2001 From: "T.Tian" Date: Wed, 16 Oct 2024 23:15:07 +0800 Subject: [PATCH 08/16] update orcid --- paper/paper.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/paper/paper.md b/paper/paper.md index 0eb21d18..0116afda 100644 --- a/paper/paper.md +++ b/paper/paper.md @@ -11,7 +11,7 @@ authors: orcid: 0000-0003-0634-0455 affiliation: 1 - name: Lucas Timmerman - orcid: + orcid: 0000-0001-5664-5762 affiliation: 1 - name: Shashikant Kumar orcid: 0009-0001-5134-1580 From f1fc5f78e133b11a73e0fbc6a9cbd435c3277208 Mon Sep 17 00:00:00 2001 From: ajmedford Date: Thu, 17 Oct 2024 15:26:40 -0400 Subject: [PATCH 09/16] AJM edits to paper --- paper/paper.md | 173 +++++++++++++++++++++++++------------------------ 1 file changed, 90 insertions(+), 83 deletions(-) diff --git a/paper/paper.md b/paper/paper.md index 0116afda..226f92ea 100644 --- a/paper/paper.md +++ b/paper/paper.md @@ -39,33 +39,33 @@ bibliography: paper.bib # Summary -Density Functional Theory (DFT) is the de facto gold standard for -electronic structure calculations in chemistry and materials science. +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 straightforward-to-install real-space DFT codes +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 +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, SPARC-X-API +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 validating and -compatibility check, and 3) a comprehensive socket communication layer +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 Python interface. The goal of SPARC-X-API is to provide a +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 @@ -73,45 +73,46 @@ real-space methods. # Statement of Need -Density Functional Theory (DFT) has unargubaly become the cornerstone -of electronic simulations in chemical and materials sciences due to -its simplicity and applications across a wide range of systems. While +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. In plane-wave methods, -the global nature of the Fourier basis used limits the ability to -achieve linear scaling [@bowler_order_n_dft_2012]. This becomes +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. Moreover, +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 grids makes real-space DFT methods -inherently scalable, paving the way for the development of +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, allowing for the flexible treatment of systems in +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 -pioneered efforts to develop an open-source, real-space DFT code that +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 easy to implement new algorithms, highly portable, and -straightforward to install and use across various computational -environments. In line with this, SPARC-X offers real-space DFT +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-based SPARC +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 @@ -121,17 +122,17 @@ interactions, and advanced exchange-correlation (xc) functionals 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; @kumar_ofdft_delta_ml_2023], +(ODFT) [@ghosh_sparc_ofdft_2016], on-the-fly machine-learning force fields (OTF-MLFF) -[@timmerman_sparc_mlff_2024; @kumar_sparc_mlff_2024]. The rapid +[@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 fully automate SPARC calculation in -high-throughput scenarios. To address this, we introduce SPARC-X-API, +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 -broader range of scientific workflows. SPARC-X-API builds upon the +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 -Atomic Simulation Environment (ASE [@larsen_ase_2017]) standard and +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 @@ -186,14 +187,14 @@ high-throughput calculations. Details will be discussed in the Features and Func # Features and Functionalities -SPARC-X-API is structured as a Python package `sparc`. A summary of -its key functionalities is provided below, and for detailed +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://github.com/SPARC-X/SPARC-X-API/blob/master/README.md). ## `sparc.io`: File I/O Manupulation -In SPARC and M-SPARC calculations, the input information are provided +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, @@ -202,14 +203,14 @@ various output files may be written, such as`.static`, `.geopt` or 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, SPARC-X-API operates on the directory level, +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, SPARC-X-API also copies relevant +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, -SPARC-X-API leverages the new features introduced in ASE version 3.23 +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: @@ -221,70 +222,76 @@ atoms = read("sparc_output_dir", format="sparc") write("sparc_input_dir", atoms, format="sparc") ``` -SPARC-X-API supports parsing complex boundary conditions from the +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. While standard ASE +corresponding `pbc` direction of an `Atoms` object. Standard ASE objects do not natively support cyclic (C) or helical (H) boundary -conditions, SPARC-X-API treats them similarly to Dirichlet boundaries +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, to preserve the correct boundary -combinations when re-writing to SPARC input files. +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, the default calculator interface such as -`FileIOCalculator` does not implement parameter validation, which can +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 providing running calculations. To address this, SPARC-X-API +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 categorizes. The validation is handled via the `sparc.api.SparcAPI` class, including: -- 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) +supported data types and parameter categories. Validation is handled via the `sparc.api.SparcAPI` class, and includes: -Each release of SPARC-X-API contains a copy of a JSON schema linked +- 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 free to choose a different combination of SPARC versions and -schemas. The separation between SPARC-X-API and SPARC not only +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 SPARC-X-API can focus on providing a user-friendly -interface without being tied to constant updates, maximizing -flexibility. +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, which provides two modes +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-code. +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, SPARC-X-API is designed to -minimize adaptation effort. `SPARC` calculator class supports two sets +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 Angstrom-eV system, and 2) case-insensitive raw SPARC +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. Basic DFT calculations can be covered by using special -parameter sets alone in SPARC-X-API, as shown by the side-by-side +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: @@ -306,8 +313,8 @@ 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 easily exceeds SPARC's file count limit. The socket layer in -SPARC-X-API avoids this overhead by direct communicating with a +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, @@ -316,32 +323,37 @@ 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 code, and ease of installation without +modifications to the existing C/C++ code, and ease of installation without requiring recompilation. -The communication protocol used in SPARC-X-API, referred to as the +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-code maintains compatibility -with the original i-PI standard, SPARC-X-API leverages this extended -version with pickle decoding. The two-tier design offers flexibility +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. SPARC-X-API -further makes running socket mode calculations at ease. Leveraging the -SPARC protocol, the API internally relays socket data to the SPARC +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 SPARC protocol +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 \autoref{fig:socket-hetero} summarizes the +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. ![**NEED REVISION** Example of socket communication across hybrid computing platforms using SPARC-X-API @@ -349,16 +361,11 @@ server-client setup across hybrid computing platforms. ](fig/fig_socket_hetero.svg){ width=100% } -The design of the SPARC protocol allows insertion of bidirectional -additional routines between two DFT calls, allowing further control -over the low-level C-code. - - ## Miscellaneous Helper Functionalities -SPARC-X-API provides several helper functions to facilitate user -installation and testing, inlcuding: +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`. @@ -371,11 +378,11 @@ installation and testing, inlcuding: # Code Release and Maintenance -SPARC-X-API is released as source code in github repository +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 -installing using `conda-forge`, the package is bundled with the +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 From 02d949a7c5e32de841d0deb9e65ef32da1eddcdb Mon Sep 17 00:00:00 2001 From: "T.Tian" Date: Tue, 22 Oct 2024 17:12:31 +0800 Subject: [PATCH 10/16] update scheme socket --- paper/fig/fig_socket_hetero.svg | 192 ++++++++++++++++---------------- paper/paper.md | 2 +- 2 files changed, 97 insertions(+), 97 deletions(-) diff --git a/paper/fig/fig_socket_hetero.svg b/paper/fig/fig_socket_hetero.svg index 031001f9..b5972dee 100644 --- a/paper/fig/fig_socket_hetero.svg +++ b/paper/fig/fig_socket_hetero.svg @@ -9,7 +9,7 @@ id="svg5" xml:space="preserve" inkscape:version="1.2.2 (b0a84865, 2022-12-01)" - sodipodi:docname="scheme_socket_hetero.svg" + sodipodi:docname="fig_socket_hetero.svg" inkscape:export-filename="scheme_socket_hetero.png" inkscape:export-xdpi="300" inkscape:export-ydpi="300" @@ -28,14 +28,14 @@ inkscape:document-units="mm" showgrid="false" inkscape:zoom="1.4741937" - inkscape:cx="612.87741" - inkscape:cy="169.58423" - inkscape:window-width="1857" + inkscape:cx="580.6564" + inkscape:cy="105.82056" + inkscape:window-width="1680" inkscape:window-height="994" - inkscape:window-x="-32" - inkscape:window-y="40" + inkscape:window-x="0" + inkscape:window-y="12" inkscape:window-maximized="0" - inkscape:current-layer="g22952" />.inpt.out.ion.staticHardwareSoftwareINET socketserver:31415SPARC protocol(extending i-PI )(No file access)Server Node (AWS instance, GPU node, etc)Native i-PI Protocol/tmp/ipi_sparc_*Local file I/OComputational Nodes (CPU-intensive)SPARC C-binarympirun -np 256 sparc \ -n 8 -c 32 \ -name $fname \ -socket $sname:unixSPARC-X-API (Socket Client)Pickle dataExtra-info parsingSSPARCCalculatorSPARC-X-API (Socket Server)• ML models• Sampling algorithmsPickle dataSPARCCalculatorTraining Inferencehead nodenode groupsUNIX socketClient 1Client 1Client N Date: Wed, 23 Oct 2024 17:48:40 +0800 Subject: [PATCH 11/16] add fig 1 svg --- paper/fig/fig_socket_hetero.svg | 706 ++++---- paper/fig/fig_sparc_api_overview.svg | 2319 ++++++++++++++++++++++++++ paper/paper.bib | 56 +- paper/paper.md | 26 +- 4 files changed, 2796 insertions(+), 311 deletions(-) create mode 100644 paper/fig/fig_sparc_api_overview.svg diff --git a/paper/fig/fig_socket_hetero.svg b/paper/fig/fig_socket_hetero.svg index b5972dee..06f437b4 100644 --- a/paper/fig/fig_socket_hetero.svg +++ b/paper/fig/fig_socket_hetero.svg @@ -2,9 +2,9 @@ - - - - - - - - - - - - + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +.inpt.out.ion.staticHardwareHardwareSoftwareSoftwareINET socketserver:31415INET socketSPARC protocol(extending i-PI )(extending i-PI)(No file access)(No file access)Server Node (AWS instance, GPU node, etc)(AWS, GPU node, etc)Native i-PI Protocoli-PI Protocol/tmp/ipi_sparc_*Local file I/OComputational Nodes (CPU-intensive)SPARC C-binarySPARC C/C++ tbinarympirun -np 256 sparc \ -n 8 -c 32 \ -name $fname \ -socket $sname:unixSPARC-X-API (Socket Client)SPARC-X-API (Client)Pickle dataPickledataExtra-info parsingParsingE, E,F, F,SSPARCCalculatorSPARC-X-API (Socket Server)SPARC-X-API (Server)• ML models• Sampling algorithms• SamplingPickle dataPickle dataSPARCSPARCCalculatorTraining Inferencehead nodenode groupsTraining InferenceUNIX socketClient 1Client Client N...... + x="28.12138" + y="-19.500431">... diff --git a/paper/fig/fig_sparc_api_overview.svg b/paper/fig/fig_sparc_api_overview.svg new file mode 100644 index 00000000..e529cfa2 --- /dev/null +++ b/paper/fig/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/paper/paper.bib b/paper/paper.bib index c498a005..44b874c3 100644 --- a/paper/paper.bib +++ b/paper/paper.bib @@ -22,7 +22,8 @@ @article{ceriotti_i-pi-1.0_2014 urldate = {2024-01-10}, volume = {185}, bdsk-url-1 = {https://www.sciencedirect.com/science/article/pii/S001046551300372X}, - bdsk-url-2 = {https://doi.org/10.1016/j.cpc.2013.10.027}} + 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}, @@ -37,7 +38,7 @@ @article{kapil_i-pi-2.0_2019 urldate = {2024-09-19}, volume = {236}, bdsk-url-1 = {https://www.sciencedirect.com/science/article/pii/S0010465518303436}, - bdsk-url-2 = {https://doi.org/10.1016/j.cpc.2018.09.020}} + 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}, @@ -53,7 +54,7 @@ @article{litman_i-pi-3.0_2024 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}, - bdsk-url-2 = {https://doi.org/10.1063/5.0215869}} + url = {https://doi.org/10.1063/5.0215869}} @article{xu_m-sparc-1.0_2020, author = {Xu, Qimen and Sharma, Abhiraj and Suryanarayana, Phanish}, @@ -67,7 +68,7 @@ @article{xu_m-sparc-1.0_2020 title = {M-{SPARC}: Matlab-Simulation Package for Ab-initio Real-space Calculations}, volume = 11, year = 2020, - bdsk-url-1 = {http://dx.doi.org/10.1016/j.softx.2020.100423}} + 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}, @@ -80,7 +81,7 @@ @article{zhang_m-sparc-2.0_2023 title = {Version 2.0.0 - M-SPARC: Matlab-Simulation Package for Ab-initio Real-space Calculations}, volume = 21, year = 2023, - bdsk-url-1 = {http://dx.doi.org/10.1016/j.softx.2022.101295}} + 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}, @@ -93,7 +94,7 @@ @article{xu_sparc-1.0_2021 title = {SPARC: Simulation Package for Ab-initio Real-space Calculations}, volume = 15, year = 2021, - bdsk-url-1 = {http://dx.doi.org/10.1016/j.softx.2021.100709}} + 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}, @@ -106,7 +107,7 @@ @article{zhang_sparc-2.0_2024 title = {SPARC v2.0.0: Spin-orbit coupling, dispersion interactions, and advanced exchange--correlation functionals}, volume = 20, year = 2024, - bdsk-url-1 = {http://dx.doi.org/10.1016/j.simpa.2024.100649}} + url = {http://dx.doi.org/10.1016/j.simpa.2024.100649}} @article{gavini_exascale_2023, author = {Gavini, Vikram and Baroni, Stefano and Blum, Volker @@ -179,17 +180,36 @@ @article{kumar_otf_mlff_sparc_2024 } - @article{larsen_ase_2017, - author = {Larsen, Ask Hjorth and Mortensen, Jens J{\o}rgen and Blomqvist, Jakob and Castelli, Ivano E. and Christensen, Rune and Du{\l}ak, Marcin and Friis, Jesper and Groves, Michael N. and Hammer, Bj{\o}rk and Hargus, Cory and Hermes, Eric D. and Jennings, Paul C. and Jensen, Peter Bjerre and Kermode, James and Kitchin, John R. and Kolsbjerg, Esben Leonhard and Kubal, Joseph and Kaasbjerg, Kristen and Lysgaard, Steen and Maronsson, J{\'o}n Bergmann and Maxson, Tristan and Olsen, Thomas and Pastewka, Lars and Peterson, Andrew and Rostgaard, Carsten and Schi{\o}tz, Jakob and Sch{\"u}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.}, - date-modified = {2024-09-24 16:33:31 +0800}, - issn = {0953-8984}, - journaltitle = {J. Phys.: Condens. Matter}, - number = {27}, - pages = {273002}, - title = {The atomic simulation environment---a Python library for working with atoms}, - volume = {29}, - bdsk-url-1 = {https://dx.doi.org/10.1088/1361-648X/aa680e}} + 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}, @@ -417,7 +437,7 @@ @article{gonze_abinit_2020 Setten, Michiel J. and Van Troeye, Benoit and Verstraete, Matthieu J. and Zérah, Gilles and Zwanziger, Josef W.}, - title = {The Abinitproject: Impact, environment and recent + title = {The Abinit project: Impact, environment and recent developments}, journal = {Computer Physics Communications}, year = 2020, diff --git a/paper/paper.md b/paper/paper.md index da1f8834..9bace9de 100644 --- a/paper/paper.md +++ b/paper/paper.md @@ -33,7 +33,7 @@ affiliations: - name: College of Computing, Georgia Institute of Technology, Atlanta, GA 30332, USA index: 2 -date: 24 September 2024 +date: 24 October 2024 bibliography: paper.bib --- @@ -85,7 +85,7 @@ 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. +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 @@ -105,7 +105,7 @@ 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 +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 @@ -142,7 +142,7 @@ various popular DFT methods, including both plane-wave (e.g. VASP seamless integration of SPARC into existing workflows, allowing users to incorporate real-space DFT calculations with minimal adjustments. A summary of the role SPARC-X-API in the SPARC-X project is shown in -\ref{fig:sparc-overview}. +\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 @@ -179,9 +179,9 @@ high-throughput calculations. Details will be discussed in the Features and Func -![**NEED REVISION** Overview of SPARC-X-API in the SPARC-X project system +![Overview of SPARC-X-API in the SPARC-X project system \label{fig:sparc-overview} -](){ width=100% } +](fig/fig_sparc_api_overview.svg){ width=100% } @@ -227,7 +227,7 @@ The SPARC-X-API also supports parsing complex boundary conditions from the 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 +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 @@ -255,7 +255,7 @@ supported data types and parameter categories. Validation is handled via the `sp 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 +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 @@ -279,8 +279,8 @@ In file I/O mode, the SPARC calculator object utilizes the 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 +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 @@ -289,7 +289,7 @@ VASP) that use the ASE default Angstrom-eV system, and 2) case-insensitive raw S 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. +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 @@ -337,7 +337,7 @@ 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. +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 @@ -356,7 +356,7 @@ over the low-level C/C++ code. Figure \autoref{fig:socket-hetero} summarizes the server-client setup across hybrid computing platforms. -![**NEED REVISION** Example of socket communication across hybrid computing platforms using SPARC-X-API +![Example of socket communication across hybrid computing platforms using SPARC-X-API \label{fig:socket-hetero} ](fig/fig_socket_hetero.svg){ width=100% } From a8f5cc01f6e03835a464241cfb7491ab1f3d80de Mon Sep 17 00:00:00 2001 From: "T.Tian" Date: Wed, 23 Oct 2024 18:13:29 +0800 Subject: [PATCH 12/16] update references --- paper/fig/fig_sparc_api_overview.svg | 8 +-- paper/paper.bib | 76 +++++++++++++++++++++++++++- paper/paper.md | 73 ++++++++++++++------------ 3 files changed, 120 insertions(+), 37 deletions(-) diff --git a/paper/fig/fig_sparc_api_overview.svg b/paper/fig/fig_sparc_api_overview.svg index e529cfa2..a502d76c 100644 --- a/paper/fig/fig_sparc_api_overview.svg +++ b/paper/fig/fig_sparc_api_overview.svg @@ -2198,7 +2198,7 @@ AIBwgg8AIJzgAwAIJ/gAAMJ9ACZwEZHB4cT7AAAAAElFTkSuQmCC id="text19611">sparc.iosparc.apisparc.calculatorsparc.docparser @@ -181,7 +190,7 @@ high-throughput calculations. Details will be discussed in the Features and Func ![Overview of SPARC-X-API in the SPARC-X project system \label{fig:sparc-overview} -](fig/fig_sparc_api_overview.svg){ width=100% } +](fig/fig_sparc_api_overview.svg){ width=90% } From f017f762708ce83663f1389261f13039f3d90f7b Mon Sep 17 00:00:00 2001 From: "T.Tian" Date: Wed, 23 Oct 2024 18:16:39 +0800 Subject: [PATCH 13/16] fix typo --- paper/paper.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/paper/paper.md b/paper/paper.md index 6c33aa26..c732fdc3 100644 --- a/paper/paper.md +++ b/paper/paper.md @@ -144,7 +144,7 @@ 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 [@article{bonomi_plumed_2019], as +[@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 From 4d18ac49402233fd7341eca5b84718cef6b8de37 Mon Sep 17 00:00:00 2001 From: "T.Tian" Date: Mon, 18 Nov 2024 21:48:52 +0800 Subject: [PATCH 14/16] update paper --- paper/README.md | 2 +- paper/paper.md | 7 +++++-- 2 files changed, 6 insertions(+), 3 deletions(-) diff --git a/paper/README.md b/paper/README.md index 5386dffc..2aed8349 100644 --- a/paper/README.md +++ b/paper/README.md @@ -26,7 +26,7 @@ This command will create the `paper.pdf` under the `paper/` subfolder. 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/alchem0x2A/SPARC-X-API/actions/workflows/joss_paper.yml) +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/paper.md b/paper/paper.md index c732fdc3..31a5d7c8 100644 --- a/paper/paper.md +++ b/paper/paper.md @@ -9,7 +9,8 @@ tags: authors: - name: Tian Tian orcid: 0000-0003-0634-0455 - affiliation: 1 + corresponding: true + affiliation: [1,3] - name: Lucas R Timmerman orcid: 0000-0001-5664-5762 affiliation: 1 @@ -32,8 +33,10 @@ affiliations: 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: 24 October 2024 +date: 18 November 2024 bibliography: paper.bib --- From 965024a0b48140330b293322002ad565bf2621b0 Mon Sep 17 00:00:00 2001 From: "T.Tian" Date: Mon, 18 Nov 2024 21:52:55 +0800 Subject: [PATCH 15/16] change link to the doc --- paper/paper.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/paper/paper.md b/paper/paper.md index 31a5d7c8..844b0d77 100644 --- a/paper/paper.md +++ b/paper/paper.md @@ -202,7 +202,7 @@ discussed in the Features and Functionalities section. 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://github.com/SPARC-X/SPARC-X-API/blob/master/README.md). +documentation](https://sparc-x.github.io/SPARC-X-API). ## `sparc.io`: File I/O Manupulation From 88d1c4e3c9a841c0e5b577ea5759e6e40fb6de28 Mon Sep 17 00:00:00 2001 From: "T.Tian" Date: Mon, 18 Nov 2024 21:57:08 +0800 Subject: [PATCH 16/16] update joss workflow file --- .github/workflows/joss_paper.yml | 5 +++++ 1 file changed, 5 insertions(+) diff --git a/.github/workflows/joss_paper.yml b/.github/workflows/joss_paper.yml index be05c21a..349c0453 100644 --- a/.github/workflows/joss_paper.yml +++ b/.github/workflows/joss_paper.yml @@ -4,6 +4,11 @@ on: paths: - paper/** - .github/workflows/joss_paper.yml + pull_request: + paths: + - paper/** + - .github/workflows/joss_paper.yml + workflow_dispatch: jobs: paper: