Additional example

examples.org

@@ -2,6 +2,144 @@
 #+STARTUP: latexpreview
 #+SETUPFILE: docs/theme.setup
 
+* Writing nuclear coordinates
+  
+  Here is a demonstration of how to use TREXIO to write the nuclear
+  coordinates of a water molecule to a file. It shows the basic steps
+  involved in opening a file, writing the data, and closing the file,
+  as well as the necessary TREXIO functions to perform these actions.
+
+** C
+   #+begin_src c
+#include <stdio.h>
+#include <trexio.h>
+
+int main() {
+  int num = 3;  // Number of atoms
+  double coord[][3] = {
+    // xyz coordinates in atomic units
+    0.  ,  0.        , -0.24962655,
+    0.  ,  2.70519714,  1.85136466,
+    0.  , -2.70519714,  1.85136466 };
+
+  trexio_exit_code rc;
+
+  // Open the TREXIO file
+  trexio_t* f = trexio_open("water.trexio", 'w', TREXIO_HDF5, &rc);
+  if (rc != TREXIO_SUCCESS) {
+    fprintf(stderr, "Error: %s\n", trexio_string_of_error(rc));
+    return -1;
+  }
+
+  // Write the number of nuclei
+  rc = trexio_write_nucleus_num (f, num);
+  if (rc != TREXIO_SUCCESS) {
+    fprintf(stderr, "Error: %s\n", trexio_string_of_error(rc));
+    return -1;
+  }
+
+  // Write the nuclear coordinates
+  rc = trexio_write_nucleus_coord (f, &coord[0][0]);
+  if (rc != TREXIO_SUCCESS) {
+    fprintf(stderr, "Error: %s\n", trexio_string_of_error(rc));
+    return -1;
+  }
+
+  // Close the TREXIO file
+  rc = trexio_close(f);
+  if (rc != TREXIO_SUCCESS) {
+    fprintf(stderr, "Error: %s\n", trexio_string_of_error(rc));
+    return -1;
+  }
+  return 0;
+}
+   #+end_src
+
+** Python
+
+   This code uses the TREXIO Python binding to create a new TREXIO file named
+ =water.trexio=, and write the nuclear coordinates of a water molecule.
+
+   The ~coord~ variable is a list of three lists, each containing the x, y,
+   and z coordinates of the water molecule's nuclei.
+
+   The ~with~ statement is used to ensure the file is properly closed after
+   the write is complete.
+
+   The ~trexio.write_nucleus_num~ function is used to write the number of
+   nuclei in the system.
+
+   The ~trexio.write_nucleus_coord~ function is used to write the nuclear
+   coordinates of the system.
+
+   #+begin_src python
+import trexio
+coord = [    # xyz coordinates in atomic units
+    [0. , 0., -0.24962655],
+    [0. , 2.70519714, 1.85136466],
+    [0. , -2.70519714, 1.85136466]
+]
+# The Python API calls can raise `trexio.Error`
+# exceptions to be handled via try/except clauses
+# in the user application
+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)
+    
+   #+end_src
+
+** Fortran
+   #+begin_src f90
+program trexio_water
+  use trexio
+
+  integer, parameter        :: num=3       ! Number of nuclei
+  double precision          :: coord(3,3)  ! Array of atom coordinates
+
+  integer(trexio_t)         :: f        ! The TREXIO file handle
+  integer(trexio_exit_code) :: rc       ! TREXIO return code
+  character*(128)           :: err_msg  ! String holding the error message
+
+  coord(:,:) = reshape( (/ 0.d0  ,  0.d0        , -0.24962655d0, &
+                           0.d0  ,  2.70519714d0,  1.85136466d0, &
+                           0.d0  , -2.70519714d0,  1.85136466d0  /), &
+                         shape(coord) )
+
+  ! Open the TREXIO file
+  f = trexio_open ('water.trexio', 'w', TREXIO_HDF5, rc)
+  if (rc /= TREXIO_SUCCESS) then
+     call trexio_string_of_error(rc, err_msg)
+     print *, 'Error: '//trim(err_msg)
+     call exit(-1)
+  end if
+
+  ! Write the number of nuclei
+  rc = trexio_write_nucleus_num (f, num)
+  if (rc /= TREXIO_SUCCESS) then
+     call trexio_string_of_error(rc, err_msg)
+     print *, 'Error: '//trim(err_msg)
+     call exit(-1)
+  end if
+
+  ! Write the nuclear coordinates
+  rc = trexio_write_nucleus_coord (f, coord)
+  if (rc /= TREXIO_SUCCESS) then
+     call trexio_string_of_error(rc, err_msg)
+     print *, 'Error: '//trim(err_msg)
+     call exit(-1)
+  end if
+
+  ! Close the TREXIO file
+  rc = trexio_close(f)
+  if (rc /= TREXIO_SUCCESS) then
+     call trexio_string_of_error(rc, err_msg)
+     print *, 'Error: '//trim(err_msg)
+     call exit(-1)
+  end if
+
+end program
+   #+end_src
 
 * Accessing sparse quantities (integrals)
 
@@ -272,7 +410,6 @@ program print_energy
 end program
     #+end_src
 
-
 * Reading determinants
   
 ** Fortran