| Copyright | Phillip Seeber 2024 |
|---|---|
| License | BSD-3-Clause |
| Maintainer | phillip.seeber@uni-jena.de |
| Stability | experimental |
| Portability | POSIX |
| Safe Haskell | Safe-Inferred |
| Language | GHC2021 |
TREXIO
Description
This module provides the high-level bindings to the TREXIO library for wave function data.
The HighLevel modules provides complete high-level bindings to the TREXIO and the function names are generated by stripping the trexio_ prefix from the C function names and converting to camel case.
E.g. the C function trexio_read_rdm_2e_updn_cholesky is available as readRdm2eUpdnCholesky.
The high-level bindings abstract mainly over three aspects of the C- (and also Python-API):
Memory management is done by the Haskell garbage collector and no pointers need to be moved around.
All multidimensional data is safely handled by the Array type or the CooArray type.
Error handling is done by throwing ExitCode exceptions in IO, i.e. you don't need to check for error codes manually.
You may catch ExitCode exceptions via the usual mechanisms, however.
In the Python- and C-APIs, Mutlidimensional quantities require writing their size to another field, referenced by the TREXIO specification first. For example, see this example for Python in TREXIO:
import trexio
coord = [ # xyz coordinates in atomic units
[0. , 0., -0.24962655],
[0. , 2.70519714, 1.85136466],
[0. , -2.70519714, 1.85136466]
]
with trexio.File("water.trexio", w,
back_end=trexio.TREXIO_HDF5) as f:
trexio.write_nucleus_num(f, len(coord))
trexio.write_nucleus_coord(f, coord)
This high-level API abstracts over this and automatically writes the size of the array to the corresponding field.
Safety checks are employed to ensure, should the size already exist, that it is consistent with the array size and other arrays utilising the same size field.
Should this safety check be violated, an the AttrAlreadyExists exception will be thrown, as the corresponding size field already exists and is inconsistent with the new size.
Thus, the Haskell equivalent to this is:
import TREXIO
import Data.Massiv.Array as Massiv
coord <- Massiv.fromListsM Par
[ [0. , 0., -0.24962655]
, [0. , 2.70519714, 1.85136466]
, [0. , -2.70519714, 1.85136466]
]
withTrexio "water.trexio" FileWrite Hdf5 $ \trexio ->
writeNucleusCoord trexio coord
Synopsis
- data ExitCode
- = Failure
- | Success
- | InvalidArg1
- | InvalidArg2
- | InvalidArg3
- | InvalidArg4
- | InvalidArg5
- | End
- | ReadOnly
- | Errno
- | InvalidID
- | AllocationFailed
- | HasNot
- | InvalidNum
- | AttrAlreadyExists
- | DSetAlreadyExists
- | OpenError
- | LockError
- | UnlockError
- | FileError
- | GroupReadError
- | GroupWriteError
- | ElemReadError
- | ElemWriteError
- | UnsafeArrayDim
- | AttrMissing
- | DSetMissing
- | BackEndMissing
- | InvalidArg6
- | InvalidArg7
- | InvalidArg8
- | InvalidStrLen
- | IntSizeOverflow
- | SafeMode
- | InvalidElectronNum
- | InvalidDeterminantNum
- | InvalidState
- | VersionParsingIssue
- | PhaseChange
- type ExitCodeC = Int32
- version :: (Int, Int, Int)
- data Backend
- data Trexio
- data FileMode
- hasBackend :: Backend -> Bool
- open :: (MonadIO m, MonadThrow m) => FilePath -> FileMode -> Backend -> m Trexio
- close :: (MonadIO m, MonadThrow m) => Trexio -> m ()
- markSafety :: (MonadIO m, MonadThrow m) => Trexio -> m ()
- newtype TrexioScheme = TrexioScheme (Map GroupName Group)
- data GroupName
- newtype Group = Group (Map DataName Typ)
- data Typ
- newtype Length = Length [DimLength]
- data DimLength
- data DataName
- scheme :: TrexioScheme
- intsPerDet :: (MonadIO m, MonadThrow m) => Trexio -> m Int
- withTrexio :: (MonadMask m, MonadIO m) => FilePath -> FileMode -> Backend -> (Trexio -> m a) -> m a
- module TREXIO.HighLevel
Basic Operations
Constructors
Instances
Instances
| Enum Backend | |
| Show Backend | |
| Eq Backend | |
| Ord Backend | |
Defined in TREXIO.Internal.Base | |
Constructors
| FileRead | |
| FileWrite | |
| FileUnsafe |
Instances
| Generic FileMode | |
| Show FileMode | |
| Eq FileMode | |
| Ord FileMode | |
Defined in TREXIO.Internal.Base | |
| type Rep FileMode | |
Defined in TREXIO.Internal.Base type Rep FileMode = D1 ('MetaData "FileMode" "TREXIO.Internal.Base" "trexio-hs-0.1.0-inplace-trexio-internal" 'False) (C1 ('MetaCons "FileRead" 'PrefixI 'False) (U1 :: Type -> Type) :+: (C1 ('MetaCons "FileWrite" 'PrefixI 'False) (U1 :: Type -> Type) :+: C1 ('MetaCons "FileUnsafe" 'PrefixI 'False) (U1 :: Type -> Type))) | |
hasBackend :: Backend -> Bool #
close :: (MonadIO m, MonadThrow m) => Trexio -> m () #
markSafety :: (MonadIO m, MonadThrow m) => Trexio -> m () #
newtype TrexioScheme Source #
The overall data structure TREXIO uses to represent a wave function as a JSON specification. A TREXIO scheme consists of multiple data groups and each data group has multiple fields. A field may require knowledge of other fields.
Constructors
| TrexioScheme (Map GroupName Group) |
Instances
The name of a data group, e.g. ao for atomic orbitals, basis for basis
functions, etc.
Instances
| FromJSONKey GroupName Source # | |
Defined in TREXIO.Internal.TH Methods | |
| ToJSONKey GroupName Source # | |
Defined in TREXIO.Internal.TH | |
| Generic GroupName Source # | |
| Show GroupName Source # | |
| Eq GroupName Source # | |
| Ord GroupName Source # | |
| Lift GroupName Source # | |
| type Rep GroupName Source # | |
Defined in TREXIO.Internal.TH | |
A data group is a record like data structure with named fields of different
types. Each field may or may not be set, thus the Maybe type.
The TREXIO type of a data field including sparsity, buffering, dimensionality etc.
Constructors
| Dim Bool Length | A 32 integer but meant to represent the size in a given dimension. The Bool indicates if field can also be written |
| Int Length | A 32 bit integer |
| Float Bool Length | A double precision float. The Bool indicates whether this field is buffered |
| Str Length | A string with a given length |
| Idx Length | An index type |
| SparseFloat Length | Sparse array of floats |
| BitField Length | A bit field |
Instances
TREXIO data fields are annotated with a length specification. This
specification is a list of sizes along the dimensions of an $n$D array.
An empty length specification refers to a scalar. A dimension may have a
constant size or refer to another field that stores its size, see DimLength.
The size along a dimension of a field. It can be a constant or refer to a field that stores a scalar describing a length.
Instances
| FromJSON DimLength Source # | |
| ToJSON DimLength Source # | |
Defined in TREXIO.Internal.TH | |
| Generic DimLength Source # | |
| Show DimLength Source # | |
| Eq DimLength Source # | |
| Ord DimLength Source # | |
| Lift DimLength Source # | |
| type Rep DimLength Source # | |
Defined in TREXIO.Internal.TH type Rep DimLength = D1 ('MetaData "DimLength" "TREXIO.Internal.TH" "trexio-hs-0.1.0-inplace" 'False) (C1 ('MetaCons "Const" 'PrefixI 'False) (S1 ('MetaSel ('Nothing :: Maybe Symbol) 'NoSourceUnpackedness 'NoSourceStrictness 'DecidedLazy) (Rec0 Int)) :+: C1 ('MetaCons "Field" 'PrefixI 'False) (S1 ('MetaSel ('Nothing :: Maybe Symbol) 'NoSourceUnpackedness 'NoSourceStrictness 'DecidedLazy) (Rec0 GroupName) :*: S1 ('MetaSel ('Nothing :: Maybe Symbol) 'NoSourceUnpackedness 'NoSourceStrictness 'DecidedLazy) (Rec0 DataName))) | |
The name of a data field, as specified by the TREXIO scheme. There is no
guarantee that the name is a valid Haskell identifier. To ensure that, use the
sanId function.
Instances
| FromJSON DataName Source # | |
| FromJSONKey DataName Source # | |
Defined in TREXIO.Internal.TH Methods | |
| ToJSON DataName Source # | |
Defined in TREXIO.Internal.TH | |
| ToJSONKey DataName Source # | |
Defined in TREXIO.Internal.TH | |
| Generic DataName Source # | |
| Show DataName Source # | |
| Eq DataName Source # | |
| Ord DataName Source # | |
Defined in TREXIO.Internal.TH | |
| Lift DataName Source # | |
| type Rep DataName Source # | |
Defined in TREXIO.Internal.TH | |
High Level Interface
scheme :: TrexioScheme Source #
The JSON specification of the code generator, that constructs the C-API and that this package binds to.
intsPerDet :: (MonadIO m, MonadThrow m) => Trexio -> m Int #
withTrexio :: (MonadMask m, MonadIO m) => FilePath -> FileMode -> Backend -> (Trexio -> m a) -> m a Source #
module TREXIO.HighLevel