trexio-hs.cabal

cabal-version:      3.0
name:               trexio-hs
-- The package version.
-- See the Haskell package versioning policy (PVP) for standards
-- guiding when and how versions should be incremented.
-- https://pvp.haskell.org
-- PVP summary:     +-+------- breaking API changes
--                  | | +----- non-breaking API additions
--                  | | | +--- code changes with no API change
version:            0.1.0
synopsis: Bindings to the TREXIO library for wave function data
homepage:           https://github.com/TREX-CoE/trexio-hs
license:            BSD-3-Clause
author:             Phillip Seeber
maintainer:         phillip.seeber@uni-jena.de
category:           Data
build-type:         Simple
extra-doc-files:    CHANGELOG.md
tested-with:        GHC == {9.6, 9.8, 9.10}
description:
    This package provides low- and high-level Haskell bindings for [TREXIO, a portable file format for storing wave function data](https://trex-coe.github.io/trexio/).
    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](https://trex-coe.github.io/trexio/lib.html).
    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](https://hackage.haskell.org/package/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
    @

common warnings
    ghc-options: -Wall

common deps
    build-depends:
        aeson >= 2.1 && < 2.3,
        base >= 4.18 && < 4.22,
        bitvec >= 1.1.5.0 && < 1.2,
        bytestring >= 0.10 && < 0.13,
        casing >= 0.1.4 && < 0.2,
        containers >= 0.6 && < 0.8,
        filepath >= 1.4 && < 1.6,
        massiv >= 1.0.0.0 && < 1.1,
        safe-exceptions >= 0.1.7 && < 0.2,
        template-haskell >= 2.19 && < 2.24,
        temporary >= 1.3 && < 1.4,
        typed-process >= 0.2.12 && < 0.3,
        text >= 2.0 && < 2.2,
        vector >= 0.13 && < 0.14

common extensions
    default-extensions:
        CApiFFI,
        DataKinds,
        DeriveAnyClass,
        DerivingVia,
        DerivingStrategies,
        OverloadedStrings,
        OverloadedRecordDot,
        RecordWildCards,
        DuplicateRecordFields,
        LambdaCase

library trexio-internal
    import:
        deps,
        extensions,
        warnings
    exposed-modules:        
        TREXIO.Internal.Base        
    hs-source-dirs:   src-int
    default-language: GHC2021
    extra-libraries:
        trexio

library
    import:
        deps,
        extensions,
        warnings
    exposed-modules:
        TREXIO,
        TREXIO.LowLevel,
        TREXIO.LowLevel.Scheme,
        TREXIO.HighLevel,
        TREXIO.HighLevel.Records,
        TREXIO.CooArray
    other-modules:
        TREXIO.Internal.Marshaller,
        TREXIO.Internal.TH
    hs-source-dirs:   src
    default-language: GHC2021
    build-depends:
        trexio-internal        
    extra-libraries:
        trexio

test-suite trexio-test
    import:
        deps,
        extensions,
        warnings
    default-language: GHC2021
    type:             exitcode-stdio-1.0
    hs-source-dirs:   test
    main-is:          trexio-test.hs
    build-depends:
        trexio-hs,
        directory >= 1.3 && < 1.4,
        tasty >= 1.4 && < 1.6,
        tasty-hunit >= 0.10 && < 0.11,
        tasty-hedgehog >= 1.4 && < 1.5,
        hedgehog >= 1.4 && < 1.6