trexio-hs: Bindings to the TREXIO library for wave function data

This package provides low- and high-level Haskell bindings for TREXIO, a portable file format for storing wave function data. The vast majority of the bindings in this package is generated via TemplateHaskell from the TREXIO JSON specification, that then defines the C-API. For more details see the TREXIO documentation. Consequently, this package is able to adapt to changes in the TREXIO specification, but the Hackage version reflects the canonical upstream TREXIO specification.

The low-level API is a direct mapping of the C-API, with minimal abstraction, i.e. passing raw pointers around and responsibility for memory management is on the user. See the TREXIO.LowLevel module for more details. The TREXIO.LowLevel.Scheme module is the Aeson representation of the TREXIO JSON specification and reflects the structure that was used by TemplateHaskell for code generation. However, the low-level bindings are very complete and allow for buffered IO of large quantities such as the Electron Repulsion Integrals or Configuration State Functions.

The high-level API is more haskellish and provides a more type-safe and user-friendly interface to the TREXIO library. The TREXIO module provides your entry point to the high-level API. Function names are automatically generated by stripping the trexio_ prefix from the C-API and converting to camel case. Furthermore, TREXIO.HighLevel.Records provides a direct translation of the TREXIO JSON specification to Haskell records (without buffered IO, however). The TREXIO.HighLevel.Records is not used for any other purpose within this library, however.

The high-level API utilises TREXIO.CooArray to provide a more idiomatic interface to sparse arrays used for many high-dimensional quantities within TREXIO.

These bindings heavily rely on Massiv for handling arrays.

Example usage:

import TREXIO
import TREXIO.CooArray
import Data.Massiv.Array as Massiv

main :: IO ()
main = do
    -- Get the version of TREXIO we have linked against
    ver <- version
    putStrLn $ "TREXIO version: " <> ver

    withTrexio "example.h5" FileWrite Hdf5 $ \trexio -> do
        -- Write nuclear coordinates to a TREXIO file
        coords <- Massiv.fromListsM Par
            [ [0. , 0., -0.24962655]
            , [0. , 2.70519714, 1.85136466]
            , [0. , -2.70519714, 1.85136466]
            ]
        writeNucleusCoord trexio coords

        -- Read reduced 2-electron density matrix (assuming it exists in the example.h5)
        rdm2e <- readRdm2e trexio
        print rdm2e