Versatile Python Interface for Real-space Density Functional Theory Calculations (2024)

Summary

Density Functional Theory (DFT) is the de facto workhorse forlarge-scale electronic structure calculations in chemistry and materialsscience. While plane-wave DFT implementations remain the most widelyused, real-space DFT provides advantages in handling complex boundaryconditions and scaling to very large systems by allowing for theefficient use of large-scale supercomputers and linear-scaling methodsthat circumvent the cubic scaling bottleneck. The SPARC-X project(https://github.com/SPARC-X) provides highly efficient andportable real-space DFT codes for a wide range of first principleapplications, available in both Matlab (M-SPARC([];[])) and C/C++(SPARC ([];[])). The rapidgrowth of SPARC’s feature set has created the need for a fullyfunctional interface to drive SPARC in high-throughput calculations.Here we introduce SPARC-X-API, a Python package designed to bridge theSPARC-X project with broader computational frameworks. Built on theatomic simulation environment (ASE([])) standard,the SPARC-X-API allows users to handle SPARC file formats and run SPARCcalculations through the same interface as with other ASE-compatible DFTpackages. Beyond standard ASE capabilities, SPARC-X-API providesadditional features including 1) support of SPARC-specific setups,including complex boundary conditions and unit conversion, 2) a JSONschema parsed from SPARC’s documentation for parameter validation andcompatibility checks, and 3) a comprehensive socket communication layerderived from the i-PI protol([];[]) facilitatingmessage passing between low-level C code and the Python interface. Thegoal of the SPARC-X-API is to provide a easy-to-use interface for userswith diverse needs and levels of expertise, allowing for minimal effortin adapting SPARC to existing computational workflows, while alsosupporting developers of advanced real-space methods.

Statement of Need

DFT has unargubaly become one of the cornerstones of electronicstructure simulations in chemical and materials sciences due to itssimplicity and wide range of applicability. Among the various numericalimplementations of DFT, the plane-wave pseudopotential method has gainedsignificant popularity, owing to both its robustness and the maturity ofassociated software packages. However, despite their widespread use,plane-wave methods are not without limitations. One long-standingchallenge in DFT is to develop methods that overcomes the hugecomputational cost for solving the Kohn-Sham equation, which scalescubically with respect to the system size. This becomes especiallyproblematic in massively parallel computing environments, where theextensive global communication required during Fourier transformationslimits the scalability, making it challenging to efficiently simulatevery large systems in plane-wave DFT. In plane-wave methods, the globalnature of the Fourier basis used limits the ability to achieve linearscaling ([]). Moreover, the periodic nature of the Fourier basis enforces theuse of periodic boundary conditions, making the simulation setup ofisolated and semi-finite systems non-straightforward. A compellingalternative to overcome these limitations is to solve the Kohn-Shamequations using a finite-difference (FD) approach on real-space grids.The locality of the FD method makes real-space DFT methods inherentlyscalable, and paves the way for the development of linearly-scalingsolutions to the Kohn-Sham equations. Real-space DFT also naturallysupports both periodic and Dirichlet boundary conditions, andcombinations thereof, allowing for the flexible treatment of systems inany dimensionality.

In the past few years, the SPARC-X project(https://github.com/SPARC-X) has led efforts to develop anopen-source, real-space DFT code that is both user-friendly andcompetitive with state-of-the-art plane-wave codes. The philosophy ofthe SPARC-X project is to provide codes that are highly efficient andportable (i.e., straightforward to install and use across variouscomputational environments). The codes also seek to be user-friendly anddeveloper-friendly to facilitate the implementation of new algorithms.In line with this, SPARC-X offers real-space DFT algorithms through twoimplementations: 1) Matlab-based M-SPARC([];[]) for algorithmprototyping and small-system simulations, with no external dependenciesother than Matlab itself, and 2) C/C++ based SPARC([];[]) for large-scaleproduction calculations that can accommodate a wide range of systemsizes and requires only MPI and MKL/BLAS for compilation. New featuresof SPARC include spin-orbit coupling, dispersion interactions, andadvanced exchange-correlation (xc) functionals([]),linear-scaling Spectral Quadrature (SQ) method([]), cyclic/helical symmetry([]), real-space density functional perturbation theory (DFPT)([]),orbital-free DFT (ODFT) ([]), on-the-fly machine-learning force fields(OTF-MLFF) ([], [];[]). Therapid development of SPARC has led to the need for a fully functionaland user-friendly interface that facilitates the use of SPARC withhigh-throughput workflows. To address this, we introduce theSPARC-X-API, a Python interface designed to bridge the SPARC code with awide range of scientific workflows. The SPARC-X-API builds upon thePython wrapper originally shipped with SPARC version 1.0([]), offering an APIcompatible with the widely-used ASE (ASE([])) standardand updated with the latest versions of SPARC. With ASE’s support forvarious popular DFT methods, including both plane-wave (e.g.VASP([]), QuantumESPRESSO ([]), andAbinit ([])), andreal-space (e.g.GPAW ([]; []) and Octopus([])) implementations, SPARC-X-API enables seamless integration ofSPARC into existing workflows, allowing users to incorporate real-spaceDFT calculations with minimal adjustments. The modular design ofSPARC-X-API makes it straightforward to be plugged into complexcomputational workflows, for example high-throughput dynamicssimulations by i-PI ([]) and PLUMED ([]), as well as active machine learning frameworks including FineTuna([]),powered by state-of-art neural network interatomic potentials such asFAIR-Chem(https://github.com/FAIR-Chem/fairchem)[https://github.com/FAIR-Chem/fairchem]and MACE-MP ([]) modelseries. A summary of the role SPARC-X-API in the SPARC-X project isshown in Figure1. In addition to the capabilitiesinherited from ASE, SPARC-X-API seeks to enhance the user experience ina few key aspects, including 1) supporting SPARC-specific features in anASE-comatible API, 2) a parameter validation mechanism based on SPARC’sLaTeX documentation, and 3) a versatile socket communicationlayer for efficient high-throughput calculations. Details will bediscussed next.

Features andFunctionalities

The SPARC-X-API is structured as a Python package, sparc. Asummary of its key functionalities is provided below; for currentdetailed documentation, please refer to theofficial documentation.

sparc.calculator:Socket-Communication CalculatorInterface

The submodule sparc.calculator provides a class SPARCas the main entry point for driving SPARC calculations. This classprovides two modes of operation: 1) a file I/O-based calculatorextending the ase.calculators.FileIOCalculator class, and 2) acomprehensive socket communication layer that allows directcommunication between the Python API and low-level C/C++ code.

In file I/O mode, the SPARC calculator object utilizes thesparc.io.SparcBundle for generating input files andsparc.api.SparcAPI for parameter validation, while the mode ofcalculation (single-point, relaxation or molecular dynamics) iscontrolled by the input flags. For users transitioning from other DFTpackages and their ASE calculators, the SPARC-X-API is designed tominimize adaptation effort, but the API is designed to also enableadvanced inputs from expert users. The SPARC calculator classachieves this by supporting two sets of input parameters: 1) lower-casespecial parameters that follow conventions from other ASE DFTcalculators (e.g.real-space grid spacing h from GPAW, andexchange-correlation keyword xc from VASP) that use the ASEdefault Angstrom-eV system, and 2) case-insensitive raw SPARC inputparameters in Bohr-Hartree units for fine-grained control. This dualapproach is designed so that users familiar with other DFT codes canadopt SPARC with minimal changes to their existing workflows, whileexpert users can exert full control. Basic DFT calculations can becovered by using standard ASE parameter sets in the SPARC-X-API, asshown by the side-by-side constructor with VASP and GPAW, using the sameexchange-correlation functional and compatible convergence settings:

#1.UsingVASPfromase.calculators.vaspimportVaspcalc=Vasp(xc="pbe",kpts=(9,9,9),ecut=450,ediff=1.e-4)#2.UsingGPAWfromgpawimportGPAWcalc=GPAW(xc="pbe",kpts=(9,9,9),h=0.25,convergence={"energy":1.e-4})#3.UsingSPARCfromsparc.calculatorimportSPARCcalc=SPARC(xc="pbe",kpts=(9,9,9),h=0.25,convergence={"energy":1.e-4})

In high-throughput frameworks requiring thousands of single-point DFTevaluations, relying on file I/O mode can be inefficient, ascalculations are restarted at each DFT call and the total number offiles may exceed SPARC’s default file count limit. The socket layer inthe SPARC-X-API avoids these limitations by directly communicating witha long-running SPARC process for updating atomic positions, whilekeeping density and orbitals in memory and reducing self-consistentfield (SCF) cycles. While alternative communication methods exist, suchas C-binding approaches seen in GPAW([]) and Psi4([]), these typicallyinvolve complex compilation and integration steps when installing thePython package. We chose a socket-based communication layer for itssimplicity, which allows for a clear separation between the Python andSPARC codebases, minimal modifications to the existing C/C++ code, andease of installation without requiring recompilation.

The communication protocol used in the SPARC-X-API socket, referred toas the SPARC protocol, is based on the i-PI protocol([];[]), which is alsoadapted by a wide range of ASE calculators. The SPARC protocolintroduces additional header types and supporting binary data transfersvia Python’s pickle format. While SPARC’s C/C++ code maintainscompatibility with the original i-PI standard, the SPARC-X-API leveragesthe extended protocol with pickle decoding. The two-tier design offersflexibility for socket calculations. At its core, the SPARC binary cancommunicate directly with any i-PI-compatible server, such asase.calculators.socketio.SocketIOCalculator in ASE, using thebasic protocol, though this requires careful setup by the user. However,the SPARC-X-API leverages the SPARC protocol, which allows the API tointernally relay more advanced data types to the SPARC binary, handlingobject decoding and socket resets automatically. When running socketcalculations on a single machine, users can activate socket mode bysimply adding use_socket=True to the SPARC calculatorconstructor, enabling UNIX socket communication without additionalsetup. More importantly, the design of the SPARC protocol allows easyand seamless integration in distributed computational systems, offeringthe following features: 1) flexible client initialization / restart 2)efficient data transfer 3) heterogeneous computational setup. The designof the SPARC protocol allows insertion of bidirectional additionalroutines between two DFT calls, allowing further control over thelow-level C/C++ code. Figure Figure2 summarizes theserver-client setup across hybrid computing platforms.

Code Release andMaintenance

The SPARC-X-API is released as source code in github repositoryhttps://github.com/SPARC-X/SPARC-X-API, and as aconda-forge packagesparc-x-api.When installed using conda-forge, the package is bundled withthe optimized SPMS pseudopotentials([]), andcompatible with thesparc packagethat contains the compiled SPARC binary.

It also integrates continuous integration (CI) workflows for:

These workflows ensure that SPARC-X-API remains up-to-date with ongoingSPARC developments while separating parameter updates from the mainSPARC maintainers’ efforts.

Acknowledgements

The authors gratefully acknowledge the support of the U.S. Department ofEnergy, Office of Science, under Grant No.DE-SC0019410 andDE-SC0023445.

References

References

• Batatia, I., Benner, P., Chiang, Y., Elena, A. M., Kovács, D. P.,Riebesell, J., Advincula, X. R., Asta, M., Avaylon, M., Baldwin, W. J.,Berger, F., Bernstein, N., Bhowmik, A., Blau, S. M., Cărare, V., Darby,J. P., De, S., Della Pia, F., Deringer, V. L., … Csányi, G. (2024).A foundation model for atomistic materials chemistry. arXiv.https://doi.org/10.48550/ARXIV.2401.00096
• Bonomi, M., Bussi, G., Camilloni, C., Tribello, G. A., Banáš, P.,Barducci, A., Bernetti, M., Bolhuis, P. G., Bottaro, S., Branduardi, D.,Capelli, R., Carloni, P., Ceriotti, M., Cesari, A., Chen, H., Chen, W.,Colizzi, F., De, S., De La Pierre, M., … The PLUMED consortium. (2019).Promoting transparency and reproducibility in enhanced molecularsimulations. Nat Methods, 16(8), 670–673.https://doi.org/10.1038/s41592-019-0506-8
• Bowler, D. R., & Miyazaki, T. (2012). O(n) methods in electronicstructure calculations. Reports on Progress in Physics,75(3), 036503.https://doi.org/10.1088/0034-4885/75/3/036503
• Ceriotti, M., More, J., & Manolopoulos, D. E. (2014). I-PI: A pythoninterface for ab initio path integral molecular dynamics simulations.Computer Physics Communications, 185(3), 1019–1026.https://doi.org/10.1016/j.cpc.2013.10.027
• Enkovaara, J., Romero, N. A., Shende, S., & Mortensen, J. J. (2011).GPAW - massively parallel electronic structure calculations withpython-based software. Procedia Computer Science, 4,17–25. https://doi.org/10.1016/j.procs.2011.04.003
• Ghosh, S., & Suryanarayana, P. (2016). Higher-order finite-differenceformulation of periodic orbital-free density functional theory.Journal of Computational Physics, 307, 634–652.https://doi.org/10.1016/j.jcp.2015.12.027
• Giannozzi, P., Andreussi, O., Brumme, T., Bunau, O., BuongiornoNardelli, M., Calandra, M., Car, R., Cavazzoni, C., Ceresoli, D.,Cococcioni, M., Colonna, N., Carnimeo, I., Dal Corso, A., Gironcoli, S.de, Delugas, P., DiStasio, R. A., Ferretti, A., Floris, A., Fratesi, G.,… Baroni, S. (2017). Advanced capabilities for materials modelling withquantum ESPRESSO. Journal of Physics: Condensed Matter,29(46), 465901. https://doi.org/10.1088/1361-648x/aa8f79
• Gonze, X., Amadon, B., Antonius, G., Arnardi, F., Baguet, L., Beuken,J.-M., Bieder, J., Bottin, F., Bouchet, J., Bousquet, E., Brouwer, N.,Bruneval, F., Brunin, G., Cavignac, T., Charraud, J.-B., Chen, W., Côté,M., Cottenier, S., Denier, J., … Zwanziger, J. W. (2020). The abinitproject: Impact, environment and recent developments. ComputerPhysics Communications, 248, 107042.https://doi.org/10.1016/j.cpc.2019.107042
• Hjorth Larsen, A., Jørgen Mortensen, J., Blomqvist, J., Castelli, I. E.,Christensen, R., Dułak, M., Friis, J., Groves, M. N., Hammer, B.,Hargus, C., Hermes, E. D., Jennings, P. C., Bjerre Jensen, P., Kermode,J., Kitchin, J. R., Leonhard Kolsbjerg, E., Kubal, J., Kaasbjerg, K.,Lysgaard, S., … Jacobsen, K. W. (2017). The atomic simulationenvironment—a python library for working with atoms. Journal ofPhysics: Condensed Matter, 29(27), 273002.https://doi.org/10.1088/1361-648x/aa680e
• Kapil, V., Rossi, M., Marsalek, O., Petraglia, R., Litman, Y., Spura,T., Cheng, B., Cuzzocrea, A., Meißner, R. H., Wilkins, D. M., Helfrecht,B. A., Juda, P., Bienvenue, S. P., Fang, W., Kessler, J., Poltavsky, I.,Vandenbrande, S., Wieme, J., Corminboeuf, C., … Ceriotti, M. (2019).I-PI 2.0: A universal force engine for advanced molecular simulations.Computer Physics Communications, 236, 214–223.https://doi.org/10.1016/j.cpc.2018.09.020
• Kresse, G., & Furthmüller, J. (1996). Efficiency of ab-initio totalenergy calculations for metals and semiconductors using a plane-wavebasis set. Computational Materials Science, 6(1), 15–50.https://doi.org/10.1016/0927-0256(96)00008-0
• Kumar, S., Jing, X., Pask, J. E., Medford, A. J., & Suryanarayana, P.(2023). Kohn–sham accuracy from orbital-free density functional theoryvia $\delta$-machine learning. The Journal of Chemical Physics,159(24). https://doi.org/10.1063/5.0180541
• Kumar, S., Pask, J. E., & Suryanarayana, P. (2024). Shock hugoniotcalculations using on-the-fly machine learned force fields with abinitio accuracy. Physics of Plasmas, 31(10).https://doi.org/10.1063/5.0230060
• Litman, Y., Kapil, V., Feldman, Y. M. Y., Tisi, D., Begušić, T.,Fidanyan, K., Fraux, G., Higer, J., Kellner, M., Li, T. E., Pós, E. S.,Stocco, E., Trenins, G., Hirshberg, B., Rossi, M., & Ceriotti, M.(2024). I-PI 3.0: A flexible and efficient framework for advancedatomistic simulations. The Journal of Chemical Physics,161(6), 062504. https://doi.org/10.1063/5.0215869
• Mortensen, J. J., Larsen, A. H., Kuisma, M., Ivanov, A. V., Taghizadeh,A., Peterson, A., Haldar, A., Dohn, A. O., Schäfer, C., Jónsson, E. Ö.,Hermes, E. D., Nilsson, F. A., Kastlunger, G., Levi, G., Jónsson, H.,Häkkinen, H., Fojt, J., Kangsabanik, J., Sødequist, J., … Thygesen, K.S. (2024). GPAW: An open python package for electronic structurecalculations. The Journal of Chemical Physics, 160(9).https://doi.org/10.1063/5.0182685
• Musielewicz, J., Wang, X., Tian, T., & Ulissi, Z. (2022). FINETUNA:Fine-tuning accelerated molecular simulations. Machine Learning:Science and Technology, 3(3), 03LT01.https://doi.org/10.1088/2632-2153/ac8fe0
• Sharma, A., & Suryanarayana, P. (2021). Real-space density functionaltheory adapted to cyclic and helical symmetry: Application to torsionaldeformation of carbon nanotubes. Physical Review B,103(3). https://doi.org/10.1103/physrevb.103.035101
• Sharma, A., & Suryanarayana, P. (2023). Calculation of phonons inreal-space density functional theory. Physical Review E,108(4). https://doi.org/10.1103/physreve.108.045302
• Shojaei, M. F., Pask, J. E., Medford, A. J., & Suryanarayana, P.(2023). Soft and transferable pseudopotentials from multi-objectiveoptimization. Computer Physics Communications, 283,108594. https://doi.org/10.1016/j.cpc.2022.108594
• Smith, D. G. A., Burns, L. A., Simmonett, A. C., Parrish, R. M.,Schieber, M. C., Galvelis, R., Kraus, P., Kruse, H., Di Remigio, R.,Alenaizan, A., James, A. M., Lehtola, S., Misiewicz, J. P., Scheurer,M., Shaw, R. A., Schriber, J. B., Xie, Y., Glick, Z. L., Sirianni, D.A., … Sherrill, C. D. (2020). PSI4 1.4: Open-source software forhigh-throughput quantum chemistry. The Journal of ChemicalPhysics, 152(18). https://doi.org/10.1063/5.0006002
• Suryanarayana, P., Pratapa, P. P., Sharma, A., & Pask, J. E. (2018).SQDFT: Spectral quadrature method for large-scale parallel o(n)kohn–sham calculations at high temperature. Computer PhysicsCommunications, 224, 288–298.https://doi.org/10.1016/j.cpc.2017.12.003
• Tancogne-Dejean, N., Oliveira, M. J. T., Andrade, X., Appel, H., Borca,C. H., Le Breton, G., Buchholz, F., Castro, A., Corni, S., Correa, A.A., De Giovannini, U., Delgado, A., Eich, F. G., Flick, J., Gil, G.,Gomez, A., Helbig, N., Hübener, H., Jestädt, R., … Rubio, A. (2020).Octopus, a computational framework for exploring light-driven phenomenaand quantum dynamics in extended and finite systems. The Journalof Chemical Physics, 152(12).https://doi.org/10.1063/1.5142502
• Timmerman, L. R., Kumar, S., Suryanarayana, P., & Medford, A. J.(2024). Overcoming the chemical complexity bottleneck in on-the-flymachine learned molecular dynamics simulations. Journal ofChemical Theory and Computation, 20(14), 5788–5795.https://doi.org/10.1021/acs.jctc.4c00474
• Xu, Q., Sharma, A., Comer, B., Huang, H., Chow, E., Medford, A. J.,Pask, J. E., & Suryanarayana, P. (2021). SPARC: Simulation package forab-initio real-space calculations. SoftwareX, 15, 100709.http://dx.doi.org/10.1016/j.softx.2021.100709
• Xu, Q., Sharma, A., & Suryanarayana, P. (2020). M-SPARC:Matlab-simulation package for ab-initio real-space calculations.SoftwareX, 11, 100423.http://dx.doi.org/10.1016/j.softx.2020.100423