TREX/trexio
1
0
Fork 0
mirror of https://github.com/TREX-CoE/trexio.git synced 2024-12-23 12:56:53 +01:00
Code Issues Projects Releases Wiki Activity

documentation for sparse arrays

Browse Source 
+ add safe functions to Fortran API
This commit is contained in:
q-posev 2021-12-24 12:40:23 +01:00
parent c92cae947f
commit 722c546113
1 changed files with 77 additions and 22 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

99
src/templates_front/templator_front.org
View File

@ -2378,35 +2378,58 @@ def has_$group_dset$(trexio_file) -> bool:
} }
#+end_src #+end_src
The electron repulsion integral (eri) $\langle ij | kl \rangle$ is The electron repulsion integral (eri) $\langle ij | kl \rangle$ is
represented as a quartet of integers $(i,j,k,l)$ and a floating represented as a quartet of integers $(i,j,k,l)$ and a floating
point value. point value.
To store $N$ integrals in the file, we store To store $N$ integrals in the file, we store
- An array of quartets of integers - An array of quartets of integers
- An array of values (floats) - An array of values (floats)
Both arrays have the same size, $N$, the number of non-zero integrals. Both arrays have the same size, $N$, the number of non-zero integrals.
Knowing the maximum dimensions allows to check that the integers are Knowing the maximum dimensions allows to check that the integers are
in a valid range, and also lets the library choose the smallest in a valid range, and also lets the library choose the smallest
integer representation to compress the storage. integer representation to compress the storage.
Fortran uses 1-based array indexing, while C uses 0-based indexing. Fortran uses 1-based array indexing, while C uses 0-based indexing.
Internally, we use a 0-based representation but the Fortran binding Internally, we use a 0-based representation but the Fortran binding
does the appropriate conversion when reading or writing. does the appropriate conversion when reading or writing.
As the number of integrals to store can be prohibitively large, we As the number of integrals to store can be prohibitively large, we
provide the possibility to read/write the integrals in chunks. So the provide the possibility to read/write the integrals in chunks. So the
functions take two extra parameters: functions take two extra parameters:
- ~offset~ : how many integrals in the file should be skipped when reading. - ~offset_file~ : how many integrals in the file should be skipped when reading/writing.
An offset of zero implies to read the first integral. An offset of zero implies to read the first integral.
- ~size~ : the number of integrals to read. - ~buffer_size~ : the number of integrals to read/write.
If EOF is encountered upon reading, the ~buffer_size~ is overwritten with the number
of integrals that have been read before EOF and the ~trexio_read_~ function return
~TREXIO_END~ exit code instead of ~TREXIO_SUCCESS~.
We provide a function to read a chunk of indices, and a function to The storage of ~int~ indices is internally compressed based on the maximum possible value of an index,
read a chunk of values, because some users might want to read only which is derived from the corresponding dimension of the sparse array (e.g. ~ao_num~ is the upper bound
the values of the integrals, or only the indices. of indices in the aforementioned ~ao_2e_int_eri~ dataset).
The upper bounds for different ~int~ types (e.g. ~uint16_t~) can be found in the in the =stdint.h= C library.
Currently implemented list of compressions based on the upper bound of indices can be found below:
| Max value of indices | Internal representation (in the TREXIO file) |
|---------------------------------+----------------------------------------------|
| ~UINT8_MAX~ (e.g. $< 255$) | 8-bit unsigned int |
| ~UINT16_MAX~ (e.g. $< 65535$) | 16-bit unsigned int |
| Otherwise (e.g. $\ge 65535$) | 32-bit signed int |
This section concerns API calls related to sparse data structures.
| Function name | Description | Precision |
|----------------------------------+-------------------------------------------------------------+----------------------------------|
| ~trexio_has_$group_dset$~ | Check if a sparse dset is present in a file | --- |
| ~trexio_read_$group_dset$~ | Read indices and values of a sparse dset | Single/Double for indices/values |
| ~trexio_read_$group_dset$_size~ | Read the number of sparse data elements stored in the file | Double for size |
| ~trexio_write_$group_dset$~ | Write indices and values of a sparse dset | Single/Double for indices/values |
| ~trexio_read_safe_$group_dset$~ | Safe (bounded) read of indices and values (for Python API) | Single/Double for indices/values |
| ~trexio_write_safe_$group_dset$~ | Safe (bounded) write of indices and values (for Python API) | Single/Double for indices/values |
*** C templates for front end *** C templates for front end
**** Function declarations **** Function declarations
@ -2674,6 +2697,22 @@ interface
double precision, intent(in) :: value_sparse(*) double precision, intent(in) :: value_sparse(*)
end function trexio_write_$group_dset$ end function trexio_write_$group_dset$
end interface end interface
interface
integer function trexio_write_safe_$group_dset$ (trex_file, &
offset_file, buffer_size, &
index_sparse, index_size, &
value_sparse, value_size) bind(C)
use, intrinsic :: iso_c_binding
integer(8), intent(in), value :: trex_file
integer(8), intent(in), value :: offset_file
integer(8), intent(in), value :: buffer_size
integer(4), intent(in) :: index_sparse(*)
integer(8), intent(in), value :: index_size
double precision, intent(in) :: value_sparse(*)
integer(8), intent(in), value :: value_size
end function trexio_write_safe_$group_dset$
end interface
#+end_src #+end_src
#+begin_src f90 :tangle read_dset_sparse_front_fortran.f90 #+begin_src f90 :tangle read_dset_sparse_front_fortran.f90
@ -2689,6 +2728,22 @@ interface
double precision, intent(out) :: value_sparse(*) double precision, intent(out) :: value_sparse(*)
end function trexio_read_$group_dset$ end function trexio_read_$group_dset$
end interface end interface
interface
integer function trexio_read_safe_$group_dset$ (trex_file, &
offset_file, buffer_size, &
index_sparse, index_size, &
value_sparse, value_size) bind(C)
use, intrinsic :: iso_c_binding
integer(8), intent(in), value :: trex_file
integer(8), intent(in), value :: offset_file
integer(8), intent(inout) :: buffer_size
integer(4), intent(out) :: index_sparse(*)
integer(8), intent(in), value :: index_size
double precision, intent(out) :: value_sparse(*)
integer(8), intent(in), value :: value_size
end function trexio_read_safe_$group_dset$
end interface
#+end_src #+end_src
#+begin_src f90 :tangle read_dset_sparse_size_front_fortran.f90 #+begin_src f90 :tangle read_dset_sparse_size_front_fortran.f90