documentation for sparse arrays

+ add safe functions to Fortran API

src/templates_front/templator_front.org

@@ -2400,13 +2400,36 @@ def has_$group_dset$(trexio_file) -> bool:
    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.
+   - ~offset_file~ : how many integrals in the file should be skipped when reading/writing.
      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
 **** 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