documentation for sparse arrays

+ add safe functions to Fortran API

src/templates_front/templator_front.org

@@ -2378,35 +2378,58 @@ def has_$group_dset$(trexio_file) -> bool:
    }
    #+end_src
 
-  The electron repulsion integral (eri) $\langle ij | kl \rangle$ is
-  represented as a quartet of integers $(i,j,k,l)$ and a floating
-  point value.
+   The electron repulsion integral (eri) $\langle ij | kl \rangle$ is
+   represented as a quartet of integers $(i,j,k,l)$ and a floating
+   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 values (floats)
+   - An array of quartets of integers
+   - An array of values (floats)
 
-  Both arrays have the same size, $N$, the number of non-zero integrals.
-  Knowing the maximum dimensions allows to check that the integers are
-  in a valid range, and also lets the library choose the smallest
-  integer representation to compress the storage.
+   Both arrays have the same size, $N$, the number of non-zero integrals.
+   Knowing the maximum dimensions allows to check that the integers are
+   in a valid range, and also lets the library choose the smallest
+   integer representation to compress the storage.
 
-  Fortran uses 1-based array indexing, while C uses 0-based indexing.
-  Internally, we use a 0-based representation but the Fortran binding
-  does the appropriate conversion when reading or writing.
+   Fortran uses 1-based array indexing, while C uses 0-based indexing.
+   Internally, we use a 0-based representation but the Fortran binding
+   does the appropriate conversion when reading or writing.
 
-  As the number of integrals to store can be prohibitively large, we
-  provide the possibility to read/write the integrals in chunks. So the
-  functions take two extra parameters:
+   As the number of integrals to store can be prohibitively large, we
+   provide the possibility to read/write the integrals in chunks. So the
+   functions take two extra parameters:
 
-  - ~offset~ : how many integrals in the file should be skipped when reading.
-    An offset of zero implies to read the first integral.
-  - ~size~ : the number of integrals to read.
+   - ~offset_file~ : how many integrals in the file should be skipped when reading/writing.
+     An offset of zero implies to read the first integral.
+   - ~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
-  read a chunk of values, because some users might want to read only
-  the values of the integrals, or only the indices.
+   The storage of ~int~ indices is internally compressed based on the maximum possible value of an index,
+   which is derived from the corresponding dimension of the sparse array (e.g. ~ao_num~ is the upper bound
+   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
 **** Function declarations
@@ -2674,6 +2697,22 @@ interface
      double precision, intent(in)  :: value_sparse(*)
    end function trexio_write_$group_dset$
 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
 
      #+begin_src f90 :tangle read_dset_sparse_front_fortran.f90
@@ -2689,6 +2728,22 @@ interface
      double precision, intent(out) :: value_sparse(*)
    end function trexio_read_$group_dset$
 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
 
      #+begin_src f90 :tangle read_dset_sparse_size_front_fortran.f90