Front end API

typedef int32_t back_end_t;

#define TREXIO_HDF5             ( (back_end_t) 0 )
#define TREXIO_TEXT             ( (back_end_t) 1 )
#define TREXIO_INVALID_BACK_END ( (back_end_t) 2 )
/*#define TREXIO_JSON             ( (back_end_t) 2 )*/

#define TREXIO_DELIM            "\n"

bool trexio_has_backend(back_end_t back_end);

bool trexio_has_backend(back_end_t back_end) {
  switch (back_end) {
    case TREXIO_TEXT:
      return true;
    case TREXIO_HDF5:
#ifdef HAVE_HDF5
      return true;
#else
      return false;
#endif
  }
  return false;
}

  integer(trexio_backend), parameter :: TREXIO_HDF5 = 0
  integer(trexio_backend), parameter :: TREXIO_TEXT = 1
! integer(trexio_backend), parameter :: TREXIO_JSON = 2
  integer(trexio_backend), parameter :: TREXIO_INVALID_BACK_END = 2

interface
   logical function trexio_has_backend (back_end) bind(C)
     use, intrinsic :: iso_c_binding
     integer(4), intent(in), value :: back_end
   end function trexio_has_backend
end interface

# define TREXIO back ends
TREXIO_HDF5 = 0
TREXIO_TEXT = 1
#TREXIO_JSON = 2
TREXIO_INVALID_BACK_END = 2

class File:
    """TREXIO File object.

    General information about the TREXIO file.

    Parameters:

    filename: str
        Is a name of the full path to the TREXIO file.
    back_end: int
        One of the currently supported TREXIO back ends.
        For example, TREXIO_HDF5 (0) or TREXIO_TEXT (1).
    mode: str
        One of the currently supported TREXIO open modes.
        For example, 'r' or 'w'.
    isOpen: bool
        Flag indicating whether the current object is still open for I/O
    pytrexio_s:
        A PyObject corresponding to SWIG proxy of the trexio_s struct in C.
        This argument is in fact a TREXIO file handle, which is required for
        communicating with the C back end.
    info: dict
        Dictionary of key-value pairs with additional information about the file.
    """


    def __init__(self, filename, mode='r', back_end=TREXIO_HDF5,
                 pytrexio_s=None, info=None):
        """This is a TREXIO File constructor."""

        self.filename = filename
        self.mode = mode
        self.back_end = back_end

        self.isOpen = False
        if pytrexio_s is None:
            self.pytrexio_s = open(filename, mode, back_end)
            self.isOpen = True
        else:
            self.pytrexio_s = pytrexio_s
            self.isOpen = None

        self.info = info


    def close(self):
        """Close a TREXIO File."""

        if self.isOpen:
            close(self.pytrexio_s)
            self.isOpen = False
        else:
            raise Exception("TREXIO File object has not been opened.")


    def __del__(self):
        """This is a TREXIO File destructor."""

        if self.isOpen:
            close(self.pytrexio_s)
        elif self.isOpen is None:
            raise Exception("[WIP]: TREXIO file handle provided but what if the file is already closed?")
        else:
            pass

trexio_t*
trexio_open(const char* file_name, const char mode,
            const back_end_t back_end, trexio_exit_code* const rc_open)
{

  if (file_name == NULL || file_name[0] == '\0') {
    if (rc_open != NULL) *rc_open = TREXIO_INVALID_ARG_1;
    return NULL;
  }
  /* Check overflow in file_name */

  if (back_end <  0 || back_end >= TREXIO_INVALID_BACK_END) {
    if (rc_open != NULL) *rc_open = TREXIO_INVALID_ARG_3;
    return NULL;
  }

  if (mode != 'r' && mode != 'w') {
    if (rc_open != NULL) *rc_open = TREXIO_INVALID_ARG_2;
    return NULL;
  }

  trexio_t* result = NULL;
  void* result_tmp = NULL;

  /* Allocate data structures */
  switch (back_end) {

  case TREXIO_TEXT:
    result_tmp = malloc(sizeof(trexio_text_t));
    break;

  case TREXIO_HDF5:
#ifdef HAVE_HDF5
    result_tmp = malloc(sizeof(trexio_hdf5_t));
    break;
#else
    if (rc_open != NULL) *rc_open = TREXIO_BACK_END_MISSING;
    return NULL;
#endif
/*
  case TREXIO_JSON:
    result = (trexio_t*) malloc (sizeof(trexio_json_t));
    break;
*/
  }
  result = (trexio_t*) result_tmp;

  assert (result != NULL);    /* TODO: Error handling */

  /* Data for the parent type */

  strncpy(result->file_name, file_name, TREXIO_MAX_FILENAME_LENGTH);
  if (result->file_name[TREXIO_MAX_FILENAME_LENGTH-1] != '\0') {
    if (rc_open != NULL) *rc_open = TREXIO_INVALID_ARG_1;
    free(result);
    return NULL;
  }

  strncpy(result->version, TREXIO_PACKAGE_VERSION, 16);
  if (result->version[15] != '\0') {
    if (rc_open != NULL) *rc_open = TREXIO_FAILURE;
    free(result);
    return NULL;
  }

  result->back_end    = back_end;
  result->mode        = mode;
  result->one_based   = false;  // Need to be flipped in Fortran interface
  int irc = pthread_mutex_init ( &(result->thread_lock), NULL);
  if (irc != 0) {
    if (rc_open != NULL) *rc_open = TREXIO_FAILURE;
    free(result);
    return NULL;
  }
  // assert (irc == 0);

  trexio_exit_code rc;

  /* Back end initialization */

  rc = TREXIO_OPEN_ERROR;

  switch (back_end) {

  case TREXIO_TEXT:
    rc = trexio_text_init(result);
    break;

  case TREXIO_HDF5:
#ifdef HAVE_HDF5
    rc = trexio_hdf5_init(result);
    break;
#else
    if (rc_open != NULL) *rc_open = TREXIO_BACK_END_MISSING;
    return NULL;
#endif
/*
  case TREXIO_JSON:
    rc = trexio_json_init(result);
    break;
*/
  }

  if (rc != TREXIO_SUCCESS) {
    if (rc_open != NULL) *rc_open = TREXIO_OPEN_ERROR;
    free(result);
    return NULL;
  }


  /* File locking */

  rc = TREXIO_LOCK_ERROR;

  switch (back_end) {

  case TREXIO_TEXT:
    rc = trexio_text_lock(result);
    break;
  /* HDF5 v.>=1.10 has file locking activated by default */
  case TREXIO_HDF5:
#ifdef HAVE_HDF5
    rc = TREXIO_SUCCESS;
    break;
#else
    if (rc_open != NULL) *rc_open = TREXIO_BACK_END_MISSING;
    return NULL;
#endif
/*
  case TREXIO_JSON:
    rc = trexio_json_lock(result);
    break;
*/
  }

  if (rc != TREXIO_SUCCESS) {
    if (rc_open != NULL) *rc_open = TREXIO_LOCK_ERROR;
    free(result);
    return NULL;
  }

  /* Write metadata (i.e. package version) upon creation */
  rc = trexio_has_metadata_package_version(result);
  if (rc == TREXIO_FAILURE) {
    if (rc_open != NULL) *rc_open = TREXIO_OPEN_ERROR;
    free(result);
    return NULL;
  }

  if (rc == TREXIO_HAS_NOT) {
    switch (back_end) {

    case TREXIO_TEXT:
      rc = trexio_text_write_metadata_package_version(result, TREXIO_PACKAGE_VERSION);
      break;

    case TREXIO_HDF5:
#ifdef HAVE_HDF5
      rc = trexio_hdf5_write_metadata_package_version(result, TREXIO_PACKAGE_VERSION);
      break;
#else
      if (rc_open != NULL) *rc_open = TREXIO_BACK_END_MISSING;
      return NULL;
#endif

    }
  }

  if (rc != TREXIO_SUCCESS) {
    if (rc_open != NULL) *rc_open = TREXIO_OPEN_ERROR;
    free(result);
    return NULL;
  }

  /* Exit upon success */
  if (rc_open != NULL) *rc_open = TREXIO_SUCCESS;

  return result;
}

interface
   integer(8) function trexio_open_c (filename, mode, backend, rc_open) bind(C, name="trexio_open")
     use, intrinsic :: iso_c_binding
     import
     character(kind=c_char), dimension(*)       :: filename
     character, intent(in), value               :: mode
     integer(trexio_backend), intent(in), value :: backend
     integer(trexio_exit_code), intent(out)     :: rc_open
   end function trexio_open_c
end interface

def open(file_name: str, mode: str, back_end: int):
    """Create TREXIO file or open existing one.

    Parameters:

    file_name: str
        Name of the TREXIO file

    mode: str
        One of the currently supported ~open~ modes (e.g. 'w', 'r')

    back_end: int
        One of the currently supported TREXIO back ends (e.g. TREXIO_HDF5, TREXIO_TEXT)

    Return:
        SWIG object of type trexio_s.

    Examples:
    >>> from trexio import open as tr_open
    >>> trex_file = tr_open("example.h5", "w", TREXIO_HDF5)
    """

    # The new trexio_open function is capable of returning error code which SWIG can append to the output trexio_s file struct
    # However, if trexio_s* == NULL, then SWIG returns only an error code rc_open instead of a list [trexio_s, rc_open]
    # Thus, the following try/except sequence is needed
    try:
        return_obj = pytr.trexio_open(file_name, mode, back_end)
        assert return_obj is not None
        if isinstance(return_obj, int):
            raise Error(return_obj)
        else:
            rc_open = return_obj[1]
            # this is a sanity check in case the code evolves and SWIG issue is patched
            if rc_open == TREXIO_SUCCESS:
                trexio_file = return_obj[0]
                assert trexio_file is not None
    except AssertionError:
        raise Exception(f"Could not open TREXIO file {file_name} using trexio_open function. The return value is None (NULL pointer).")

    return trexio_file

trexio_exit_code trexio_set_one_based(trexio_t* file)
{
  if (file == NULL)
    return TREXIO_FILE_ERROR;

  file->one_based = true;

  return TREXIO_SUCCESS;
}

interface
   integer function trexio_set_one_based(trex_file) bind(C)
     use, intrinsic :: iso_c_binding
     integer(8), intent(in), value :: trex_file
   end function trexio_set_one_based
end interface

trexio_exit_code
trexio_close (trexio_t* file)
{

  if (file == NULL) return TREXIO_FILE_ERROR;

  trexio_exit_code rc = TREXIO_FAILURE;

  assert(file->back_end < TREXIO_INVALID_BACK_END);

  /* Terminate the back end */
  switch (file->back_end) {

  case TREXIO_TEXT:
    rc = trexio_text_deinit(file);
    break;

  case TREXIO_HDF5:
#ifdef HAVE_HDF5
    rc = trexio_hdf5_deinit(file);
    break;
#else
    FREE(file);
    return TREXIO_BACK_END_MISSING;
#endif
/*
  case TREXIO_JSON:
    rc = trexio_json_deinit(file);
    break;
*/
  }

  if (rc != TREXIO_SUCCESS) {
    FREE(file);
    return rc;
  }

  /* File unlocking */

  rc = TREXIO_UNLOCK_ERROR;

  switch (file->back_end) {

  case TREXIO_TEXT:
    rc = trexio_text_unlock(file);
    break;

  case TREXIO_HDF5:
#ifdef HAVE_HDF5
    rc = TREXIO_SUCCESS;
    break;
#else
    FREE(file);
    return TREXIO_BACK_END_MISSING;
#endif
/*
  case TREXIO_JSON:
    rc = trexio_json_unlock(file);
    break;
*/
  }

  /* Terminate front end */

  int irc = pthread_mutex_destroy( &(file->thread_lock) );

  free(file);

  if (irc != 0) return TREXIO_ERRNO;
  if (rc != TREXIO_SUCCESS) return rc;

  return TREXIO_SUCCESS;
}

interface
   integer function trexio_close (trex_file) bind(C)
     use, intrinsic :: iso_c_binding
     integer(8), intent(in), value :: trex_file
   end function trexio_close
end interface

def close(trexio_file):
    """Close TREXIO file.

    Parameter is a ~trexio_file~ object that has been created by a call to ~open~ function.
    """

    try:
        rc = pytr.trexio_close(trexio_file)
        if rc != TREXIO_SUCCESS:
            raise Error(rc)
    except:
        raise

interface
   integer function trexio_write_$group_num$_64 (trex_file, num) bind(C)
     use, intrinsic :: iso_c_binding
     integer(8), intent(in), value :: trex_file
     $group_num_f_dtype_double$, intent(in), value :: num
   end function trexio_write_$group_num$_64
end interface

interface
   integer function trexio_read_$group_num$_64 (trex_file, num) bind(C)
     use, intrinsic :: iso_c_binding
     integer(8), intent(in), value :: trex_file
     $group_num_f_dtype_double$, intent(out) :: num
   end function trexio_read_$group_num$_64
end interface

interface
   integer function trexio_write_$group_num$_32 (trex_file, num) bind(C)
     use, intrinsic :: iso_c_binding
     integer(8), intent(in), value :: trex_file
     $group_num_f_dtype_single$, intent(in), value :: num
   end function trexio_write_$group_num$_32
end interface

interface
   integer function trexio_read_$group_num$_32 (trex_file, num) bind(C)
     use, intrinsic :: iso_c_binding
     integer(8), intent(in), value :: trex_file
     $group_num_f_dtype_single$, intent(out) :: num
   end function trexio_read_$group_num$_32
end interface

interface
   integer function trexio_write_$group_num$ (trex_file, num) bind(C)
     use, intrinsic :: iso_c_binding
     integer(8), intent(in), value :: trex_file
     $group_num_f_dtype_default$, intent(in), value :: num
   end function trexio_write_$group_num$
end interface

interface
   integer function trexio_read_$group_num$ (trex_file, num) bind(C)
     use, intrinsic :: iso_c_binding
     integer(8), intent(in), value :: trex_file
     $group_num_f_dtype_default$, intent(out) :: num
   end function trexio_read_$group_num$
end interface

interface
   integer function trexio_has_$group_num$ (trex_file) bind(C)
     use, intrinsic :: iso_c_binding
     integer(8), intent(in), value :: trex_file
   end function trexio_has_$group_num$
end interface

def write_$group_num$(trexio_file, num_w: $group_num_py_dtype$) -> None:
    """Write the $group_num$ variable in the TREXIO file.

    Parameters:

    trexio_file:
        TREXIO File object.

    num_w: int
        Value of the $group_num$ variable to be written.

    Raises:
        - Exception from AssertionError if TREXIO return code ~rc~ is different from TREXIO_SUCCESS and prints the error message using trexio_string_of_error.
        - Exception from some other error (e.g. RuntimeError).
    """

    try:
        rc = pytr.trexio_write_$group_num$(trexio_file.pytrexio_s, num_w)
        if rc != TREXIO_SUCCESS:
            raise Error(rc)
    except:
        raise

def read_$group_num$(trexio_file) -> $group_num_py_dtype$:
    """Read the $group_num$ variable from the TREXIO file.

    Parameter is a ~TREXIO File~ object that has been created by a call to ~open~ function.

    Returns:
        ~num_r~: int
        Integer value of $group_num$ variable read from ~trexio_file~.

    Raises:
        - Exception from AssertionError if TREXIO return code ~rc~ is different from TREXIO_SUCCESS and prints the error message using trexio_string_of_error.
        - Exception from some other error (e.g. RuntimeError).
    """

    try:
        rc, num_r = pytr.trexio_read_$group_num$(trexio_file.pytrexio_s)
        if rc != TREXIO_SUCCESS:
            raise Error(rc)
    except:
        raise

    return num_r

def has_$group_num$(trexio_file) -> bool:
    """Check that $group_num$ variable exists in the TREXIO file.

    Parameter is a ~TREXIO File~ object that has been created by a call to ~open~ function.

    Returns:
          True if the variable exists, False otherwise

    Raises:
        - Exception from trexio.Error class if TREXIO return code ~rc~ is TREXIO_FAILURE and prints the error message using string_of_error.
        - Exception from some other error (e.g. RuntimeError).
    """

    try:
        rc = pytr.trexio_has_$group_num$(trexio_file.pytrexio_s)
        if rc == TREXIO_FAILURE:
            raise Error(rc)
    except:
        raise

    if rc == TREXIO_SUCCESS:
        return True
    else:
        return False

interface
   integer function trexio_write_$group_dset$_64 (trex_file, dset) bind(C)
     use, intrinsic :: iso_c_binding
     integer(8), intent(in), value :: trex_file
     $group_dset_f_dtype_double$, intent(in) :: dset$group_dset_f_dims$
   end function trexio_write_$group_dset$_64
end interface

interface
   integer function trexio_read_$group_dset$_64 (trex_file, dset) bind(C)
     use, intrinsic :: iso_c_binding
     integer(8), intent(in), value :: trex_file
     $group_dset_f_dtype_double$, intent(out) :: dset$group_dset_f_dims$
   end function trexio_read_$group_dset$_64
end interface

interface
   integer function trexio_write_$group_dset$_32 (trex_file, dset) bind(C)
     use, intrinsic :: iso_c_binding
     integer(8), intent(in), value :: trex_file
     $group_dset_f_dtype_single$, intent(in) :: dset$group_dset_f_dims$
   end function trexio_write_$group_dset$_32
end interface

interface
   integer function trexio_read_$group_dset$_32 (trex_file, dset) bind(C)
     use, intrinsic :: iso_c_binding
     integer(8), intent(in), value :: trex_file
     $group_dset_f_dtype_single$, intent(out) :: dset$group_dset_f_dims$
   end function trexio_read_$group_dset$_32
end interface

interface
   integer function trexio_write_$group_dset$ (trex_file, dset) bind(C)
     use, intrinsic :: iso_c_binding
     integer(8), intent(in), value :: trex_file
     $group_dset_f_dtype_default$, intent(in) :: dset$group_dset_f_dims$
   end function trexio_write_$group_dset$
end interface

interface
   integer function trexio_read_$group_dset$ (trex_file, dset) bind(C)
     use, intrinsic :: iso_c_binding
     integer(8), intent(in), value :: trex_file
     $group_dset_f_dtype_default$, intent(out) :: dset$group_dset_f_dims$
   end function trexio_read_$group_dset$
end interface

interface
   integer function trexio_has_$group_dset$ (trex_file) bind(C)
     use, intrinsic :: iso_c_binding
     integer(8), intent(in), value :: trex_file
   end function trexio_has_$group_dset$
end interface

def write_$group_dset$(trexio_file, dset_w) -> None:
    """Write the $group_dset$ array of numbers in the TREXIO file.

    Parameters:

    trexio_file:
        TREXIO File object.

    dset_w: list OR numpy.ndarray
        Array of $group_dset$ values to be written. If array data type does not correspond to int64 or float64, the conversion is performed.

    Raises:
        - Exception from AssertionError if TREXIO return code ~rc~ is different from TREXIO_SUCCESS and prints the error message using trexio_string_of_error.
        - Exception from some other error (e.g. RuntimeError).
    """

    try:
        import numpy as np
    except ImportError:
        raise Exception("NumPy cannot be imported.")

    doConversion = False
    doFlatten = False
    if not isinstance(dset_w, (list, tuple)):
       # if input array is not a list or tuple then it is probably a numpy array
       if isinstance(dset_w, np.ndarray) and (not dset_w.dtype==np.int64 or not dset_w.dtype==np.float64):
           doConversion = True

       if len(dset_w.shape) > 1:
           doFlatten = True
           if doConversion:
               dset_64 = np.$group_dset_py_dtype$64(dset_w).flatten()
           else:
               dset_flat = np.array(dset_w, dtype=np.$group_dset_py_dtype$64).flatten()
       else:
           if doConversion:
               dset_64 = np.$group_dset_py_dtype$64(dset_w)

    else:
       # if input array is a multidimensional list or tuple, we have to convert it
       try:
           doFlatten = True
           ncol = len(dset_w[0])
           dset_flat = np.array(dset_w, dtype=np.$group_dset_py_dtype$64).flatten()
       except TypeError:
           doFlatten = False
           pass


    if doConversion:
        rc = pytr.trexio_write_safe_$group_dset$_64(trexio_file.pytrexio_s, dset_64)
    elif doFlatten:
        rc = pytr.trexio_write_safe_$group_dset$_64(trexio_file.pytrexio_s, dset_flat)
    else:
        rc = pytr.trexio_write_safe_$group_dset$_64(trexio_file.pytrexio_s, dset_w)

    if rc != TREXIO_SUCCESS:
        raise Error(rc)

def read_$group_dset$(trexio_file, dim = None, doReshape = None, dtype = None):
    """Read the $group_dset$ array of numbers from the TREXIO file.

    Parameters:

    trexio_file:
        TREXIO File object.

    dim (Optional): int
        Size of the block to be read from the file (i.e. how many items of $group_dset$ will be returned)
        If None, the function will read all necessary array dimensions from the file.

    dtype (Optional): type
        NumPy data type of the output (e.g. np.int32|int16 or np.float32|float16). If specified, the output array will be converted from the default double precision.

    doReshape (Optional): bool
        Flag to determine whether the output NumPy array has be reshaped or not. Be default, reshaping is performed
        based on the dimensions from the ~trex.json~ file. Otherwise, ~shape~ array (list or tuple) is used if provided by the user.

    Returns:
        ~dset_64~ if dtype is None or ~dset_converted~ otherwise: numpy.ndarray
        1D NumPy array with ~dim~ elements corresponding to $group_dset$ values read from the TREXIO file.

    Raises:
        - Exception from AssertionError if TREXIO return code ~rc~ is different from TREXIO_SUCCESS and prints the error message using trexio_string_of_error.
        - Exception from some other error (e.g. RuntimeError).
"""

    try:
        import numpy as np
    except ImportError:
        raise Exception("NumPy cannot be imported.")

    if doReshape is None:
        doReshape = True

    # if dim is not specified, read dimensions from the TREXIO file
    dims_list = None
    if dim is None or doReshape:
        $group_dset_dim$ = read_$group_dset_dim$(trexio_file)

        dims_list = [$group_dset_dim_list$]
        dim = 1
        for i in range($group_dset_rank$):
            dim *= dims_list[i]


    shape = tuple(dims_list)
    if shape is None and doReshape:
        raise ValueError("Reshaping failure: shape is None.")

    try:
        rc, dset_64 = pytr.trexio_read_safe_$group_dset$_64(trexio_file.pytrexio_s, dim)

        if rc != TREXIO_SUCCESS:
            raise Error(rc)
    except:
        raise


    isConverted = False
    dset_converted = None
    if dtype is not None:

        try:
            assert isinstance(dtype, type)
        except AssertionError:
            raise TypeError("dtype argument has to be an instance of the type class (e.g. np.float32).")


        if not dtype==np.int64 or not dtype==np.float64:
            try:
                dset_converted = np.array(dset_64, dtype=dtype)
            except:
                raise

            isConverted = True

    # additional assert can be added here to check that read_safe functions returns numpy array of proper dimension

    if doReshape:
        try:
            # in-place reshaping did not work so I have to make a copy
            if isConverted:
                dset_reshaped = np.reshape(dset_converted, shape, order='C')
            else:
                dset_reshaped = np.reshape(dset_64, shape, order='C')
        except:
            raise

    if isConverted:
        return dset_converted
    elif doReshape:
        return dset_reshaped
    else:
        return dset_64

def has_$group_dset$(trexio_file) -> bool:
    """Check that $group_dset$ variable exists in the TREXIO file.

    Parameter is a ~TREXIO File~ object that has been created by a call to ~open~ function.

    Returns:
          True if the variable exists, False otherwise

    Raises:
        - Exception from trexio.Error class if TREXIO return code ~rc~ is TREXIO_FAILURE and prints the error message using string_of_error.
        - Exception from some other error (e.g. RuntimeError).
    """

    try:
        rc = pytr.trexio_has_$group_dset$(trexio_file.pytrexio_s)
        if rc == TREXIO_FAILURE:
            raise Error(rc)
    except:
        raise

    if rc == TREXIO_SUCCESS:
        return True
    else:
        return False

"ao_2e_int"  : {
  "eri"      : [ "float sparse", [ "ao.num", "ao.num", "ao.num", "ao.num" ] ]
}

interface
   integer function trexio_write_$group_dset$ (trex_file, &
                                               offset_file, buffer_size, &
                                               index_sparse, value_sparse) 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(*)
     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

interface
   integer function trexio_read_$group_dset$ (trex_file, &
                                              offset_file, buffer_size, &
                                              index_sparse, value_sparse) 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(*)
     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

interface
   integer function trexio_read_$group_dset$_size (trex_file, &
                                                   size_max) bind(C)
     use, intrinsic :: iso_c_binding
     integer(8), intent(in), value :: trex_file
     integer(8), intent(out) :: size_max
   end function trexio_read_$group_dset$_size
end interface

interface
   integer function trexio_has_$group_dset$ (trex_file) bind(C)
     use, intrinsic :: iso_c_binding
     integer(8), intent(in), value :: trex_file
   end function trexio_has_$group_dset$
end interface

def write_$group_dset$(trexio_file: File, offset_file: int, buffer_size: int, indices: list, values: list) -> None:
    """Write the $group_dset$ indices and values in the TREXIO file.

    Parameters:

    trexio_file:
        TREXIO File object.

    offset_file: int
        The number of integrals to be skipped in the file when writing.

    buffer_size: int
        The number of integrals to write in the file from the provided sparse arrays.

    values: list OR numpy.ndarray
        Array of $group_dset$ indices to be written. If array data type does not correspond to int32, the conversion is performed.

    values: list OR numpy.ndarray
        Array of $group_dset$ values to be written. If array data type does not correspond to float64, the conversion is performed.

    Raises:
        - Exception from AssertionError if TREXIO return code ~rc~ is different from TREXIO_SUCCESS and prints the error message using trexio_string_of_error.
        - Exception from some other error (e.g. RuntimeError).
    """

    try:
        import numpy as np
    except ImportError:
        raise Exception("NumPy cannot be imported.")

    if not isinstance(offset_file, int):
        raise TypeError("offset_file argument has to be an integer.")
    if not isinstance(buffer_size, int):
        raise TypeError("buffer_size argument has to be an integer.")
    if not isinstance(indices, (list, tuple, np.ndarray)):
        raise TypeError("indices argument has to be an array (list, tuple or NumPy ndarray).")
    if not isinstance(values, (list, tuple, np.ndarray)):
        raise TypeError("values argument has to be an array (list, tuple or NumPy ndarray).")

    convertIndices = False
    convertValues = False
    flattenIndices = False
    if isinstance(indices, np.ndarray):
       # convert to int32 if input indices are in a different precision
       if not indices.dtype==np.int32:
           convertIndices = True

       if len(indices.shape) > 1:
           flattenIndices = True
           if convertIndices:
               indices_32 = np.int32(indices).flatten()
           else:
               indices_32 = np.array(indices, dtype=np.int32).flatten()
       else:
           if convertIndices:
               indices_32 = np.int32(indices)
    else:
       # if input array is a multidimensional list or tuple, we have to convert it
       try:
           doFlatten = True
           # if list of indices is flat - the attempt to compute len(indices[0]) will raise a TypeError
           ncol = len(indices[0])
           indices_32 = np.array(indices, dtype=np.int32).flatten()
       except TypeError:
           doFlatten = False
           pass

    if isinstance(values, np.ndarray):
       # convert to float64 if input values are in a different precision
       if not values.dtype==np.float64:
           convertValues = True
       if convertValues:
           values_64 = np.float64(values)

    if (convertIndices or flattenIndices) and convertValues:
        rc = pytr.trexio_write_safe_$group_dset$(trexio_file.pytrexio_s, offset_file, buffer_size, indices_32, values_64)
    elif (convertIndices or flattenIndices) and not convertValues:
        rc = pytr.trexio_write_safe_$group_dset$(trexio_file.pytrexio_s, offset_file, buffer_size, indices_32, values)
    elif not (convertIndices or flattenIndices) and convertValues:
        rc = pytr.trexio_write_safe_$group_dset$(trexio_file.pytrexio_s, offset_file, buffer_size, indices, values_64)
    else:
        rc = pytr.trexio_write_safe_$group_dset$(trexio_file.pytrexio_s, offset_file, buffer_size, indices, values)

    if rc != TREXIO_SUCCESS:
        raise Error(rc)

def read_$group_dset$(trexio_file: File, offset_file: int, buffer_size: int) -> tuple:
    """Read the $group_dset$ indices and values from the TREXIO file.

    Parameters:

    trexio_file:
        TREXIO File object.

    offset_file: int
        The number of integrals to be skipped in the file when reading.

    buffer_size: int
        The number of integrals to read from the file.

    Returns:
        (indices, values, n_int_read, eof_flag) tuple where
          - indices and values are NumPy arrays [numpy.ndarray] with the default int32 and float64 precision, respectively;
          - n_int_read [int] is the number of integrals read from the trexio_file
            (either strictly equal to buffer_size or less than buffer_size if EOF has been reached);
          - eof_flag [bool] is True when EOF has been reached (i.e. when call to low-level pytrexio API returns TREXIO_END)
                               False otherwise.

    Raises:
        - Exception from AssertionError if TREXIO return code ~rc~ is different from TREXIO_SUCCESS
            and prints the error message using trexio_string_of_error.
        - Exception from some other error (e.g. RuntimeError).
    """

    try:
        import numpy as np
    except ImportError:
        raise Exception("NumPy cannot be imported.")

    if not isinstance(offset_file, int):
        raise TypeError("offset_file argument has to be an integer.")
    if not isinstance(buffer_size, int):
        raise TypeError("buffer_size argument has to be an integer.")


    # read the number of integrals already in the file
    integral_num = read_$group_dset$_size(trexio_file)

    # additional modification needed to avoid allocating more memory than needed if EOF will be reached during read
    overflow = offset_file + buffer_size - integral_num
    eof_flag = False
    if overflow > 0:
        verified_size = buffer_size - overflow
        eof_flag = True
    else:
        verified_size = buffer_size

    # main call to the low-level (SWIG-wrapped) trexio_read function, which also requires the sizes of the output to be provided
    # as the last 2 arguments (for numpy arrays of indices and values, respectively)
    # read_buf_size contains the number of elements being read from the file, useful when EOF has been reached
    rc, n_int_read, indices, values = pytr.trexio_read_safe_$group_dset$(trexio_file.pytrexio_s,
                                                                         offset_file,
                                                                         verified_size,
                                                                         verified_size * $group_dset_rank$,
                                                                         verified_size)
    if rc != TREXIO_SUCCESS:
        raise Error(rc)
    if n_int_read == 0:
        raise ValueError("No integrals have been read from the file.")
    if indices is None or values is None:
        raise ValueError("Returned NULL array from the low-level pytrexio API.")

    # conversion to custom types can be performed on the user side, here we only reshape the returned flat array of indices according to group_dset_rank
    shape = tuple([verified_size, $group_dset_rank$])
    indices_reshaped = np.reshape(indices, shape, order='C')

    return (indices_reshaped, values, n_int_read, eof_flag)


def read_$group_dset$_size(trexio_file) -> int:
    """Read the number of $group_dset$ integrals stored in the TREXIO file.

    Parameter is a ~TREXIO File~ object that has been created by a call to ~open~ function.

    Returns:
        ~num_integral~: int
        Integer value of corresponding to the size of the $group_dset$ sparse array from ~trexio_file~.

    Raises:
        - Exception from AssertionError if TREXIO return code ~rc~ is different from TREXIO_SUCCESS and prints the error message using trexio_string_of_error.
        - Exception from some other error (e.g. RuntimeError).
    """

    try:
        rc, num_integral = pytr.trexio_read_$group_dset$_size(trexio_file.pytrexio_s)
        if rc != TREXIO_SUCCESS:
            raise Error(rc)
    except:
        raise

    return num_integral

def has_$group_dset$(trexio_file) -> bool:
    """Check that $group_dset$ variable exists in the TREXIO file.

    Parameter is a ~TREXIO File~ object that has been created by a call to ~open~ function.

    Returns:
          True if the variable exists, False otherwise

    Raises:
        - Exception from trexio.Error class if TREXIO return code ~rc~ is TREXIO_FAILURE and prints the error message using string_of_error.
        - Exception from some other error (e.g. RuntimeError).
    """

    try:
        rc = pytr.trexio_has_$group_dset$(trexio_file.pytrexio_s)
        if rc == TREXIO_FAILURE:
            raise Error(rc)
    except:
        raise

    if rc == TREXIO_SUCCESS:
        return True
    else:
        return False

interface
   integer function trexio_write_$group_dset$_low (trex_file, dset, max_str_len) bind(C)
     use, intrinsic :: iso_c_binding
     integer(8), intent(in), value :: trex_file
     character, intent(in) :: dset(*)
     integer(4), intent(in), value :: max_str_len
   end function trexio_write_$group_dset$_low
end interface

interface
   integer function trexio_read_$group_dset$_low (trex_file, dset, max_str_len) bind(C)
     use, intrinsic :: iso_c_binding
     integer(8), intent(in), value :: trex_file
     character, intent(out) :: dset(*)
     integer(4), intent(in), value :: max_str_len
   end function trexio_read_$group_dset$_low
end interface

interface
   integer function trexio_has_$group_dset$ (trex_file) bind(C)
     use, intrinsic :: iso_c_binding
     integer(8), intent(in), value :: trex_file
   end function trexio_has_$group_dset$
end interface

integer function trexio_read_$group_dset$ (trex_file, dset, max_str_len)
  implicit none
  integer(8), intent(in), value :: trex_file
  integer(4), intent(in), value :: max_str_len
  character(len=*), intent(inout) :: dset(*)

  character, allocatable :: str_compiled(:)
  integer(8) :: $group_dset_dim$
  integer :: rc

  rc = trexio_read_$group_dset_dim$_64(trex_file, $group_dset_dim$)
  if (rc /= TREXIO_SUCCESS) trexio_read_$group_dset$ = rc

  allocate(str_compiled($group_dset_dim$*(max_str_len+1)+1))

  rc = trexio_read_$group_dset$_low(trex_file, str_compiled, max_str_len)
  if (rc /= TREXIO_SUCCESS) then
    deallocate(str_compiled)
    trexio_read_$group_dset$ = rc
  else
    call trexio_str2strarray(str_compiled, $group_dset_dim$, max_str_len, dset)
    deallocate(str_compiled)
    trexio_read_$group_dset$ = TREXIO_SUCCESS
  endif

end function trexio_read_$group_dset$

integer function trexio_write_$group_dset$ (trex_file, dset, max_str_len)
  implicit none
  integer(8), intent(in), value :: trex_file
  integer(4), intent(in), value :: max_str_len
  character(len=*), intent(in) :: dset(*)

  character(len=:), allocatable :: str_compiled
  integer(8) :: $group_dset_dim$
  integer :: rc

  rc = trexio_read_$group_dset_dim$_64(trex_file, $group_dset_dim$)
  if (rc /= TREXIO_SUCCESS) then
    trexio_write_$group_dset$ = rc
  else
    call trexio_strarray2str(dset, $group_dset_dim$, max_str_len, str_compiled)
    trexio_write_$group_dset$ = trexio_write_$group_dset$_low(trex_file, str_compiled, max_str_len)
  endif

end function trexio_write_$group_dset$

def write_$group_dset$(trexio_file, dset_w: list) -> None:
    """Write the $group_dset$ array of strings in the TREXIO file.

    Parameters:

    trexio_file:
        TREXIO File object.

    dset_w: list
        Array of $group_dset$ strings to be written.

    Raises:
        - Exception from AssertionError if TREXIO return code ~rc~ is different from TREXIO_SUCCESS and prints the error message using trexio_string_of_error.
        - Exception from some other error (e.g. RuntimeError).
    """

    max_str_length = len(max(dset_w, key=len)) + 1

    try:
        rc = pytr.trexio_write_$group_dset$(trexio_file.pytrexio_s, dset_w, max_str_length)

        if rc != TREXIO_SUCCESS:
            raise Error(rc)
    except:
        raise

def read_$group_dset$(trexio_file, dim = None) -> list:
    """Read the $group_dset$ array of strings from the TREXIO file.

    Parameters:

    trexio_file:
        TREXIO File object.

    dim (Optional): int
        Size of the block to be read from the file (i.e. how many items of $group_dset$ will be returned)
        If None, the function will read all necessary array dimensions from the file.

    Returns:
        ~dset_r~: list
        1D list with ~dim~ elements corresponding to $group_dset$ strings read from the TREXIO file.

    Raises:
        - Exception from AssertionError if TREXIO return code ~rc~ is different from TREXIO_SUCCESS and prints the error message using trexio_string_of_error.
        - Exception from some other error (e.g. RuntimeError).
    """

    # if dim is not specified, read dimensions from the TREXIO file
    if dim is None:
        $group_dset_dim$ = read_$group_dset_dim$(trexio_file)

        dims_list = [$group_dset_dim_list$]
        dim = 1
        for i in range($group_dset_rank$):
            dim *= dims_list[i]


    try:
        rc, dset_1d_r = pytr.trexio_read_$group_dset$_low(trexio_file.pytrexio_s, PYTREXIO_MAX_STR_LENGTH)

        if rc != TREXIO_SUCCESS:
            raise Error(rc)
    except:
        raise


    try:
        dset_full = dset_1d_r.split(pytr.TREXIO_DELIM)
        dset_2d_r = [dset_full[i] for i in range(dim) if dset_full[i]]
        if not dset_2d_r:
            raise ValueError(f"Output of {read_$group_dset$.__name__} function cannot be an empty list.")
    except:
        raise

    return dset_2d_r

def has_$group_dset$(trexio_file) -> bool:
    """Check that $group_dset$ variable exists in the TREXIO file.

    Parameter is a ~TREXIO File~ object that has been created by a call to ~open~ function.

    Returns:
          True if the variable exists, False otherwise

    Raises:
        - Exception from trexio.Error class if TREXIO return code ~rc~ is TREXIO_FAILURE and prints the error message using string_of_error.
        - Exception from some other error (e.g. RuntimeError).
    """

    try:
        rc = pytr.trexio_has_$group_dset$(trexio_file.pytrexio_s)
        if rc == TREXIO_FAILURE:
            raise Error(rc)
    except:
        raise

    if rc == TREXIO_SUCCESS:
        return True
    else:
        return False

interface
   integer function trexio_write_$group_str$_c (trex_file, str, max_str_len) &
           bind(C, name="trexio_write_$group_str$")
     use, intrinsic :: iso_c_binding
     integer(8), intent(in), value :: trex_file
     character, intent(in) :: str(*)
     integer(4), intent(in), value :: max_str_len
   end function trexio_write_$group_str$_c
end interface

interface
   integer function trexio_read_$group_str$_c (trex_file, str, max_str_len) &
           bind(C, name="trexio_read_$group_str$")
     use, intrinsic :: iso_c_binding
     integer(8), intent(in), value :: trex_file
     character, intent(out) :: str(*)
     integer(4), intent(in), value :: max_str_len
   end function trexio_read_$group_str$_c
end interface

interface
   integer function trexio_has_$group_str$ (trex_file) bind(C)
     use, intrinsic :: iso_c_binding
     integer(8), intent(in), value :: trex_file
   end function trexio_has_$group_str$
end interface

integer function trexio_read_$group_str$ (trex_file, str, max_str_len)
  implicit none
  integer(8), intent(in), value :: trex_file
  integer(4), intent(in), value :: max_str_len
  character, intent(out) :: str(*)

  trexio_read_$group_str$ = trexio_read_$group_str$_c(trex_file, str, max_str_len)

end function trexio_read_$group_str$

integer function trexio_write_$group_str$ (trex_file, str, max_str_len)
  use, intrinsic :: iso_c_binding, only : c_null_char
  implicit none
  integer(8), intent(in), value :: trex_file
  integer(4), intent(in), value :: max_str_len
  character(len=*), intent(in) :: str

  character(len=len_trim(str)+1) :: str_c

  str_c = trim(str) // c_null_char

  trexio_write_$group_str$ = trexio_write_$group_str$_c(trex_file, str_c, max_str_len)

end function trexio_write_$group_str$

def write_$group_str$(trexio_file, str_w: str) -> None:
    """Write the $group_str$ variable in the TREXIO file.

    Parameters:

    trexio_file:
        TREXIO File object.

    str_w: str
        String corresponding to the $group_str$ variable to be written.

    Raises:
        - Exception from AssertionError if TREXIO return code ~rc~ is different from TREXIO_SUCCESS and prints the error message using trexio_string_of_error.
        - Exception from some other error (e.g. RuntimeError).
    """

    max_str_length = len(str_w) + 1

    try:
        rc = pytr.trexio_write_$group_str$(trexio_file.pytrexio_s, str_w, max_str_length)

        if rc != TREXIO_SUCCESS:
            raise Error(rc)
    except:
        raise

def read_$group_str$(trexio_file) -> str:
    """Read the $group_str$ variable from the TREXIO file.

    Parameter is a ~TREXIO File~ object that has been created by a call to ~open~ function.

    Returns:
        ~str_r~: str
        String corresponding to the $group_str$ variable read from ~trexio_file~.

    Raises:
        - Exception from AssertionError if TREXIO return code ~rc~ is different from TREXIO_SUCCESS and prints the error message using trexio_string_of_error.
        - Exception from some other error (e.g. RuntimeError).
    """

    try:
        rc, str_r = pytr.trexio_read_$group_str$(trexio_file.pytrexio_s, PYTREXIO_MAX_STR_LENGTH)

        if rc != TREXIO_SUCCESS:
            raise Error(rc)
    except:
        raise

    return str_r

def has_$group_str$(trexio_file) -> bool:
    """Check that $group_str$ variable exists in the TREXIO file.

    Parameter is a ~TREXIO File~ object that has been created by a call to ~open~ function.

    Returns:
          True if the variable exists, False otherwise

    Raises:
        - Exception from trexio.Error class if TREXIO return code ~rc~ is TREXIO_FAILURE and prints the error message using string_of_error.
        - Exception from some other error (e.g. RuntimeError).
    """

    try:
        rc = pytr.trexio_has_$group_str$(trexio_file.pytrexio_s)
        if rc == TREXIO_FAILURE:
            raise Error(rc)
    except:
        raise

    if rc == TREXIO_SUCCESS:
        return True
    else:
        return False