diff --git a/index.html b/index.html index 5844750..dc07312 100644 --- a/index.html +++ b/index.html @@ -3,7 +3,7 @@ "http://www.w3.org/TR/xhtml1/DTD/xhtml1-strict.dtd"> - + QMCkl source code documentation @@ -261,67 +261,67 @@ for the JavaScript code in this tag.

Table of Contents

-
-

1 Introduction

+
+

1 Introduction

The ultimate goal of QMCkl is to provide a high-performance @@ -348,8 +348,8 @@ compiled.

-
-

1.1 Language used

+
+

1.1 Language used

Fortran is one of the most common languages used by the community, @@ -373,8 +373,8 @@ justified.

-
-

1.2 Source code editing

+
+

1.2 Source code editing

Any text editor can be used to edit org-mode files. For a better @@ -409,8 +409,8 @@ And pandoc can convert multiple markdown formats into org-mode.

-
-

1.3 Writing in Fortran

+
+

1.3 Writing in Fortran

The Fortran source files should provide a C interface using @@ -428,8 +428,8 @@ For more guidelines on using Fortran to generate a C interface, see

-
-

1.4 Coding style

+
+

1.4 Coding style

To improve readability, we maintain a consistent coding style in @@ -448,8 +448,8 @@ Coding style can be automatically checked with -

1.5 Design of the library

+
+

1.5 Design of the library

The proposed API should allow the library to: @@ -465,8 +465,8 @@ functions (see below).

-
-

1.5.1 Naming conventions

+
+

1.5.1 Naming conventions

Use qmckl_ as a prefix for all exported functions and variables. @@ -491,8 +491,8 @@ form is allowed.

-
-

1.5.2 Application programming interface

+
+

1.5.2 Application programming interface

The application programming interface (API) is designed to be @@ -521,8 +521,8 @@ bindings in other languages in other repositories.

-
-

1.5.3 Global state

+
+

1.5.3 Global state

Global variables should be avoided in the library, because it is @@ -549,8 +549,8 @@ versions can be destroyed with qmckl_context_destroy.

-
-

1.5.4 Low-level functions

+
+

1.5.4 Low-level functions

Low-level functions are very simple functions which are leaves of @@ -565,8 +565,8 @@ if they need temporary memory it should be provided in input.

-
-

1.5.5 High-level functions

+
+

1.5.5 High-level functions

High-level functions are at the top of the function call tree. @@ -584,8 +584,8 @@ the context variable.

-
-

1.5.6 Numerical precision

+
+

1.5.6 Numerical precision

The number of bits of precision required for a function should be @@ -599,8 +599,8 @@ variable.

-
-

1.6 Algorithms

+
+

1.6 Algorithms

Reducing the scaling of an algorithm usually implies also reducing @@ -613,8 +613,8 @@ implemented adapted to different problem sizes.

-
-

1.7 Rules for the API

+
+

1.7 Rules for the API

  • stdint should be used for integers (int32_t, int64_t)
    • @@ -626,12 +626,12 @@ implemented adapted to different problem sizes.
-
-

2 Documentation

+
+

2 Documentation

-
-

2.1 qmckl.h header file

+
+

2.1 qmckl.h header file

This file produces the qmckl.h header file, which is to be included @@ -643,12 +643,12 @@ We also create here the qmckl_f.f90 which is the Fortran interface

-
-

2.1.1 Constants

+
+

2.1.1 Constants

    -
  1. Success/failure
    +
  2. Success/failure

    These are the codes returned by the functions to indicate success @@ -673,7 +673,7 @@ or failure. All such functions should have as a return type qmckl_exit_cod

    3. -
  3. Precision-related constants
    +
  4. Precision-related constants

    Controlling numerical precision enables optimizations. Here, the @@ -697,8 +697,8 @@ range are defined.

-
-

2.2 Memory management

+
+

2.2 Memory management

We override the allocation functions to enable the possibility of @@ -714,12 +714,14 @@ optimized libraries to fine-tune the memory allocation.

-
-

2.2.1 qmckl_malloc

+
+

2.2.1 qmckl_malloc

Memory allocation function, letting the library choose how the memory will be allocated, and a pointer is returned to the user. +The context is passed to let the library store data related to the +allocation inside the context.

@@ -740,15 +742,14 @@ memory will be allocated, and a pointer is returned to the user.
    -
  1. Source
    +
  2. Source
    void* qmckl_malloc(const qmckl_context ctx, const size_t size) {
-  if (ctx == (qmckl_context) 0) {
-    /* Avoids unused parameter error */
-    return malloc( (size_t) size );
-  }
-  return malloc( (size_t) size );
+  if (ctx == (qmckl_context) 0) {}; /* Avoid unused argument warning */
+  void * result = malloc( (size_t) size );
+  assert (result != NULL) ;
+  return result;
 }
    @@ -758,31 +759,34 @@ memory will be allocated, and a pointer is returned to the user.
-
-

2.2.2 qmckl_free

+
+

2.2.2 qmckl_free

-
void qmckl_free(void *ptr);
+
void* qmckl_free(void *ptr);
 

 
interface
-   subroutine qmckl_free (ptr) bind(C)
+   type (c_ptr) function qmckl_free (ptr) bind(C)
      use, intrinsic :: iso_c_binding
      type (c_ptr), intent(in), value :: ptr
-   end subroutine qmckl_free
+   end function qmckl_free
 end interface
    -
  1. Source
    +
  2. Source
    -
    void qmckl_free(void *ptr) {
+
    void* qmckl_free(void *ptr) {
+  assert (ptr != NULL);
   free(ptr);
+  return NULL;
 }
+
    @@ -790,8 +794,8 @@ memory will be allocated, and a pointer is returned to the user.
-
-

2.3 Context

+
+

2.3 Context

This file is written in C because it is more natural to express the @@ -807,8 +811,8 @@ context in C than in Fortran.

-
-

2.3.1 Context

+
+

2.3.1 Context

The context variable is a handle for the state of the library, and @@ -826,7 +830,7 @@ A value of 0 for the context is equivalent to a NULL pointer.

    -
  1. Basis set data structure
    +
  2. Basis set data structure

    Data structure for the info related to the atomic orbitals @@ -852,7 +856,7 @@ basis set.

    3. -
  3. Source
    +
  4. Source

    The tag is used internally to check if the memory domain pointed @@ -885,7 +889,7 @@ by a pointer is a valid context.

    5. -
  5. qmckl_context_check
    +
  6. qmckl_context_check

    Checks if the domain pointed by the pointer is a valid context. @@ -900,7 +904,7 @@ otherwise.

      -
    1. Source
      +
    2. Source
      qmckl_context qmckl_context_check(const qmckl_context context) {
@@ -920,7 +924,7 @@ otherwise.
    7. -
  7. qmckl_context_create
    +
  8. qmckl_context_create

    To create a new context, use qmckl_context_create(). @@ -939,7 +943,7 @@ Returns 0 upon failure to allocate the internal data structure

      -
    1. Source
      +
    2. Source
      qmckl_context qmckl_context_create() {
@@ -963,7 +967,7 @@ Returns 0 upon failure to allocate the internal data structure
      3. -
    3. Fortran interface
      +
    4. Fortran interface
      interface
@@ -978,7 +982,7 @@ Returns 0 upon failure to allocate the internal data structure
    9. -
  9. qmckl_context_copy
    +
  10. qmckl_context_copy

    This function makes a shallow copy of the current context. @@ -999,7 +1003,7 @@ for the new context

      -
    1. Source
      +
    2. Source
      qmckl_context qmckl_context_copy(const qmckl_context context) {
@@ -1032,7 +1036,7 @@ for the new context
      3. -
    3. Fortran interface
      +
    4. Fortran interface
      interface
@@ -1048,7 +1052,7 @@ for the new context
    11. -
  11. qmckl_context_previous
    +
  12. qmckl_context_previous

    Returns the previous context @@ -1068,7 +1072,7 @@ Returns 0 for the 0-valued context

      -
    1. Source
      +
    2. Source
      qmckl_context qmckl_context_previous(const qmckl_context context) {
@@ -1086,7 +1090,7 @@ Returns 0 for the 0-valued context
      3. -
    3. Fortran interface
      +
    4. Fortran interface
      interface
@@ -1102,7 +1106,7 @@ Returns 0 for the 0-valued context
    13. -
  13. qmckl_context_destroy
    +
  14. qmckl_context_destroy

    Destroys the current context, leaving the ancestors untouched. @@ -1121,7 +1125,7 @@ Destroys the current context, leaving the ancestors untouched.

      -
    1. Source
      +
    2. Source
      qmckl_exit_code qmckl_context_destroy(const qmckl_context context) {
@@ -1141,7 +1145,7 @@ Destroys the current context, leaving the ancestors untouched.
      3. -
    3. Fortran interface
      +
    4. Fortran interface
      interface
@@ -1159,8 +1163,8 @@ Destroys the current context, leaving the ancestors untouched.
-
-

2.3.2 Basis set

+
+

2.3.2 Basis set

For H2 with the following basis set, @@ -1208,7 +1212,7 @@ COEFFICIENT = [ 0.006068, 0.045308, 0.202822, 0.503903, 0.383421,

    -
  1. qmckl_context_update_ao_basis
    +
  2. qmckl_context_update_ao_basis

    Updates the data describing the AO basis set into the context. @@ -1288,7 +1292,7 @@ Updates the data describing the AO basis set into the context.

      -
    1. Source
      +
    2. Source
      qmckl_exit_code
@@ -1407,7 +1411,7 @@ Updates the data describing the AO basis set into the context.
      3. -
    3. Fortran interface
      +
    4. Fortran interface
      interface
@@ -1433,11 +1437,11 @@ Updates the data describing the AO basis set into the context.
      5. -
    5. TODO Test
      6. +
    6. TODO Test
    3. -
  3. qmckl_context_set_ao_basis
    +
  4. qmckl_context_set_ao_basis

    Sets the data describing the AO basis set into the context. @@ -1517,7 +1521,7 @@ Sets the data describing the AO basis set into the context.

      -
    1. Source
      +
    2. Source
      qmckl_context
@@ -1546,7 +1550,7 @@ Sets the data describing the AO basis set into the context.
      3. -
    3. Fortran interface
      +
    4. Fortran interface
      interface
@@ -1572,14 +1576,14 @@ Sets the data describing the AO basis set into the context.
      5. -
    5. TODO Test
      6. +
    6. TODO Test
-
-

2.3.3 Precision

+
+

2.3.3 Precision

The following functions set and get the expected required @@ -1596,7 +1600,7 @@ integer. The update functions return QMCKL_SUCCESS or

    -
  1. qmckl_context_update_precision
    +
  2. qmckl_context_update_precision

    Modifies the parameter for the numerical precision in a given context. @@ -1608,7 +1612,7 @@ Modifies the parameter for the numerical precision in a given context.

      -
    1. Source
      +
    2. Source
      qmckl_exit_code qmckl_context_update_precision(const qmckl_context context, const int precision) {
@@ -1627,7 +1631,7 @@ Modifies the parameter for the numerical precision in a given context.
      3. -
    3. Fortran interface
      +
    4. Fortran interface
      interface
@@ -1643,7 +1647,7 @@ Modifies the parameter for the numerical precision in a given context.
    3. -
  3. qmckl_context_update_range
    +
  4. qmckl_context_update_range

    Modifies the parameter for the numerical range in a given context. @@ -1655,7 +1659,7 @@ Modifies the parameter for the numerical range in a given context.

      -
    1. Source
      +
    2. Source
      qmckl_exit_code qmckl_context_update_range(const qmckl_context context, const int range) {
@@ -1674,7 +1678,7 @@ Modifies the parameter for the numerical range in a given context.
      3. -
    3. Fortran interface
      +
    4. Fortran interface
      interface
@@ -1690,7 +1694,7 @@ Modifies the parameter for the numerical range in a given context.
    5. -
  5. qmckl_context_set_precision
    +
  6. qmckl_context_set_precision

    Returns a copy of the context with a different precision parameter. @@ -1702,7 +1706,7 @@ Returns a copy of the context with a different precision parameter.

      -
    1. Source
      +
    2. Source
      qmckl_context qmckl_context_set_precision(const qmckl_context context, const int precision) {
@@ -1718,7 +1722,7 @@ Returns a copy of the context with a different precision parameter.
      3. -
    3. Fortran interface
      +
    4. Fortran interface
      interface
@@ -1734,7 +1738,7 @@ Returns a copy of the context with a different precision parameter.
    7. -
  7. qmckl_context_set_range
    +
  8. qmckl_context_set_range

    Returns a copy of the context with a different precision parameter. @@ -1746,7 +1750,7 @@ Returns a copy of the context with a different precision parameter.

      -
    1. Source
      +
    2. Source
      qmckl_context qmckl_context_set_range(const qmckl_context context, const int range) {
@@ -1762,7 +1766,7 @@ Returns a copy of the context with a different precision parameter.
      3. -
    3. Fortran interface
      +
    4. Fortran interface
      interface
@@ -1779,7 +1783,7 @@ Returns a copy of the context with a different precision parameter.
    9. -
  9. qmckl_context_get_precision
    +
  10. qmckl_context_get_precision

    Returns the value of the numerical precision in the context @@ -1791,7 +1795,7 @@ Returns the value of the numerical precision in the context

      -
    1. Source
      +
    2. Source
      int qmckl_context_get_precision(const qmckl_context context) {
@@ -1803,7 +1807,7 @@ Returns the value of the numerical precision in the context
      3. -
    3. Fortran interface
      +
    4. Fortran interface
      interface
@@ -1818,7 +1822,7 @@ Returns the value of the numerical precision in the context
    11. -
  11. qmckl_context_get_range
    +
  12. qmckl_context_get_range

    Returns the value of the numerical range in the context @@ -1830,7 +1834,7 @@ Returns the value of the numerical range in the context

      -
    1. Source
      +
    2. Source
      int qmckl_context_get_range(const qmckl_context context) {
@@ -1842,7 +1846,7 @@ Returns the value of the numerical range in the context
      3. -
    3. Fortran interface
      +
    4. Fortran interface
      interface
@@ -1858,7 +1862,7 @@ Returns the value of the numerical range in the context
    13. -
  13. qmckl_context_get_epsilon
    +
  14. qmckl_context_get_epsilon

    Returns \(\epsilon = 2^{1-n}\) where n is the precision @@ -1870,7 +1874,7 @@ Returns \(\epsilon = 2^{1-n}\) where n is the precision

      -
    1. Source
      +
    2. Source
      double qmckl_context_get_epsilon(const qmckl_context context) {
@@ -1882,7 +1886,7 @@ Returns \(\epsilon = 2^{1-n}\) where n is the precision
      3. -
    3. Fortran interface
      +
    4. Fortran interface
      interface
@@ -1900,8 +1904,8 @@ Returns \(\epsilon = 2^{1-n}\) where n is the precision
-
-

2.4 Computation of distances

+
+

2.4 Computation of distances

Function for the computation of distances between particles. @@ -1917,12 +1921,12 @@ Function for the computation of distances between particles.

-
-

2.4.1 Squared distance

+
+

2.4.1 Squared distance

    -
  1. qmckl_distance_sq
    +
  2. qmckl_distance_sq

    Computes the matrix of the squared distances between all pairs of @@ -1934,7 +1938,7 @@ points in two sets, one point within each set:

      -
    1. Arguments
      +
    2. Arguments
      @@ -2017,7 +2021,7 @@ points in two sets, one point within each set: -
    3. Requirements
      +
    4. Requirements
      • context is not 0
        • @@ -2035,7 +2039,7 @@ points in two sets, one point within each set:
      5. -
    5. Performance
      +
    6. Performance

      This function might be more efficient when A and B are @@ -2054,7 +2058,7 @@ transposed.

      7. -
    7. Source
      +
    8. Source
      integer function qmckl_distance_sq_f(context, transa, transb, m, n, A, LDA, B, LDB, C, LDC) result(info)
@@ -2190,8 +2194,8 @@ transposed.
      -
      -

      2.5 Atomic Orbitals

      +
      +

      2.5 Atomic Orbitals

      This files contains all the routines for the computation of the @@ -2208,14 +2212,15 @@ values, gradients and Laplacian of the atomic basis functions.

      -
      -

      2.5.1 Polynomials

      +
      +

      2.5.1 Polynomials

      \[ P_l(\mathbf{r},\mathbf{R}_i) = (x-X_i)^a (y-Y_i)^b (z-Z_i)^c \]

      + \begin{eqnarray*} \frac{\partial }{\partial x} P_l\left(\mathbf{r},\mathbf{R}_i \right) & = & a (x-X_i)^{a-1} (y-Y_i)^b (z-Z_i)^c \\ @@ -2224,6 +2229,8 @@ values, gradients and Laplacian of the atomic basis functions. \frac{\partial }{\partial z} P_l\left(\mathbf{r},\mathbf{R}_i \right) & = & c (x-X_i)^a (y-Y_i)^b (z-Z_i)^{c-1} \\ \end{eqnarray*} + + \begin{eqnarray*} \left( \frac{\partial }{\partial x^2} + \frac{\partial }{\partial y^2} + @@ -2236,7 +2243,7 @@ values, gradients and Laplacian of the atomic basis functions.
        -
      1. qmckl_ao_power
        +
      2. qmckl_ao_power

        Computes all the powers of the n input data up to the given @@ -2249,7 +2256,7 @@ maximum value given in input for each of the \(n\) points:

          -
        1. Arguments
          +
        2. Arguments
      9. @@ -2302,7 +2309,7 @@ maximum value given in input for each of the \(n\) points: -
    9. Requirements
      +
    10. Requirements
      • context is not 0
        • @@ -2315,7 +2322,7 @@ maximum value given in input for each of the \(n\) points:
      11. -
    11. Header
      +
    12. Header
      qmckl_exit_code qmckl_ao_power(const qmckl_context context,
@@ -2327,7 +2334,7 @@ maximum value given in input for each of the \(n\) points:
      13. -
    13. Source
      +
    14. Source
      integer function qmckl_ao_power_f(context, n, X, LMAX, P, ldp) result(info)
@@ -2369,7 +2376,7 @@ maximum value given in input for each of the \(n\) points:
      15. -
    15. qmckl_ao_polynomial_vgl
      +
    16. qmckl_ao_polynomial_vgl

      Computes the values, gradients and Laplacians at a given point of @@ -2378,7 +2385,7 @@ all polynomials with an angular momentum up to lmax.

        -
      1. Arguments
        +
      2. Arguments
      17. @@ -2449,7 +2456,7 @@ all polynomials with an angular momentum up to lmax. -
    17. Requirements
      +
    18. Requirements
      • context is not 0
        • @@ -2474,7 +2481,7 @@ For example, with a=0, b=2 and c=1 the string is "yyz"
      19. -
    19. Error codes
      +
    20. Error codes
      21. @@ -2509,7 +2516,7 @@ For example, with a=0, b=2 and c=1 the string is "yyz" -
    21. Header
      +
    22. Header
      qmckl_exit_code qmckl_ao_polynomial_vgl(const qmckl_context context,
@@ -2522,7 +2529,7 @@ For example, with a=0, b=2 and c=1 the string is "yyz"
      23. -
    23. Source
      +
    24. Source
      integer function qmckl_ao_polynomial_vgl_f(context, X, R, lmax, n, L, ldl, VGL, ldv) result(info)
@@ -2660,12 +2667,12 @@ For example, with a=0, b=2 and c=1 the string is "yyz"
      25. -
      -

      2.5.2 Gaussian basis functions

      +
      +

      2.5.2 Gaussian basis functions

        -
      1. qmckl_ao_gaussian_vgl
        +
      2. qmckl_ao_gaussian_vgl

        Computes the values, gradients and Laplacians at a given point of @@ -2673,7 +2680,7 @@ Computes the values, gradients and Laplacians at a given point of

        -\[ v_i = exp(-a_i |X-R|^2) \] +\[ v_i = \exp(-a_i |X-R|^2) \] \[ \nabla_x v_i = -2 a_i (X_x - R_x) v_i \] \[ \nabla_y v_i = -2 a_i (X_y - R_y) v_i \] \[ \nabla_z v_i = -2 a_i (X_z - R_z) v_i \] @@ -2682,7 +2689,7 @@ Computes the values, gradients and Laplacians at a given point of

          -
        1. Arguments
          +
        2. Arguments
      @@ -2741,7 +2748,7 @@ Computes the values, gradients and Laplacians at a given point of -
    25. Requirements
      +
    26. Requirements
      • context is not 0
        • @@ -2756,7 +2763,7 @@ Computes the values, gradients and Laplacians at a given point of
      27. -
    27. Header
      +
    28. Header
      qmckl_exit_code qmckl_ao_gaussian_vgl(const qmckl_context context,
@@ -2768,7 +2775,7 @@ Computes the values, gradients and Laplacians at a given point of
      29. -
    29. Source
      +
    30. Source
      integer function qmckl_ao_gaussian_vgl_f(context, X, R, n, A, VGL, ldv) result(info)
@@ -2840,14 +2847,14 @@ Computes the values, gradients and Laplacians at a given point of
      -
      -

      2.5.3 TODO Slater basis functions

      +
      +

      2.5.3 TODO Slater basis functions

      -
      -

      3 Acknowledgments

      +
      +

      3 Acknowledgments

      euflag.jpg @@ -2857,7 +2864,7 @@ Computes the values, gradients and Laplacians at a given point of

      -

      Created: 2020-12-24 Thu 16:49

      +

      Created: 2021-02-19 Fri 00:40

      Validate