TREX/trexio
1
0
Fork 0
mirror of https://github.com/TREX-CoE/trexio.git synced 2024-11-03 12:43:55 +01:00
Code Issues Projects Releases Wiki Activity

Deploying to gh-pages from @ TREX-CoE/trexio@d37f4d6610 🚀

Browse Source
This commit is contained in:
scemama 2023-02-17 16:43:15 +00:00
parent 65cb997b48
commit 13510df405
17 changed files with 2876 additions and 699 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

47
README.html
View File

@ -3,7 +3,7 @@
"http://www.w3.org/TR/xhtml1/DTD/xhtml1-strict.dtd">
<html xmlns="http://www.w3.org/1999/xhtml" lang="en" xml:lang="en">
<head>
<!-- 2023-02-16 Thu 08:31 -->
<!-- 2023-02-17 Fri 16:43 -->
<meta http-equiv="Content-Type" content="text/html;charset=utf-8" />
<meta name="viewport" content="width=device-width, initial-scale=1" />
<title>TREXIO source code documentation</title>
@ -261,7 +261,7 @@ org_html_manager.set("LOCAL_TOC", "1");
org_html_manager.set("VIEW_BUTTONS", "0");
org_html_manager.set("MOUSE_HINT", "underline");
org_html_manager.set("FIXED_TOC", "0");
org_html_manager.set("TOC", "1");
org_html_manager.set("TOC", "0");
org_html_manager.set("VIEW", "info");
org_html_manager.setup(); // activate after the parameters are set
/*]]>*///-->
@ -320,31 +320,50 @@ for the JavaScript code in this tag.
<a accesskey="H" href="index.html"> HOME </a>
</div><div id="content">
<h1 class="title">TREXIO source code documentation</h1>
<hr />
<script async src="https://cse.google.com/cse.js?cx=a67f8ab65a66f97f2"></script>
<div class="gcse-search"></div>
<hr />
<p>
TREXIO is an open-source file format and library developed for the storage and
manipulation of data produced by quantum chemistry calculations. It was
designed with the goal of providing a reliable and efficient method of storing
and exchanging wave function parameters and matrix elements.
</p>
<p>
The library consists of a front-end implemented in the C programming language
and two different back-ends: a text back-end and a binary back-end utilizing
the HDF5 library enabling fast read and write speeds. It is compatible with a
variety of platforms and has interfaces for Fortran, Python, and OCaml.
</p>
<hr />
<table style="width:100%">
<tr><td style="width:50%">
<ul class="org-ul">
<li><a href="./tutorial_benzene.html">Tutorial</a></li>
<li><a href="./intro.html">Motivation</a></li>
<li><a href="./lib.html">The TREXIO library</a></li>
<li><a href="./trex.html">Data stored with TREXIO</a></li>
<li><a href="./tutorial_benzene.html">Tutorial</a></li>
<li><a href="./examples.html">How-to guide</a></li>
<li><a href="./templator_front.html">Front end API</a></li>
<li><a href="./templator_hdf5.html">HDF5 back end</a></li>
<li><a href="./templator_text.html">TEXT back end</a></li>
</ul>
</td>
<td>
<img src="trexio.png" alt="T-Rex talking about chemistry"
align="right" width="300"/>
</td></tr>
</table>
<hr />
<p>
The TREXIO library defines a standard format for storing wave functions,
together with an C-compatible API such that it can be easily used in any
programming language.
</p>
<p>
The source code of the library is available at
<a href="https://github.com/trex-coe/trexio">https://github.com/trex-coe/trexio</a>
@ -352,6 +371,10 @@ and bug reports should be submitted at
<a href="https://github.com/trex-coe/trexio/issues">https://github.com/trex-coe/trexio/issues</a>.
</p>
<p>
The TREXIO library is licensed under the open-source 3-clause BSD license.
</p>
<hr />
<p>
@ -360,7 +383,7 @@ and bug reports should be submitted at
</div>
<div id="postamble" class="status">
<p class="author">Author: TREX-CoE</p>
<p class="date">Created: 2023-02-16 Thu 08:31</p>
<p class="date">Created: 2023-02-17 Fri 16:43</p>
<p class="validation"><a href="http://validator.w3.org/check?uri=referer">Validate</a></p>
</div>
</body>

303
examples.html
View File

@ -3,7 +3,7 @@
"http://www.w3.org/TR/xhtml1/DTD/xhtml1-strict.dtd">
<html xmlns="http://www.w3.org/1999/xhtml" lang="en" xml:lang="en">
<head>
<!-- 2023-02-16 Thu 08:31 -->
<!-- 2023-02-17 Fri 16:43 -->
<meta http-equiv="Content-Type" content="text/html;charset=utf-8" />
<meta name="viewport" content="width=device-width, initial-scale=1" />
<title>Examples</title>
@ -261,7 +261,7 @@ org_html_manager.set("LOCAL_TOC", "1");
org_html_manager.set("VIEW_BUTTONS", "0");
org_html_manager.set("MOUSE_HINT", "underline");
org_html_manager.set("FIXED_TOC", "0");
org_html_manager.set("TOC", "1");
org_html_manager.set("TOC", "0");
org_html_manager.set("VIEW", "info");
org_html_manager.setup(); // activate after the parameters are set
/*]]>*///-->
@ -346,46 +346,220 @@ for the JavaScript code in this tag.
<h2>Table of Contents</h2>
<div id="text-table-of-contents">
<ul>
<li><a href="#org0ada7bb">1. Accessing sparse quantities (integrals)</a>
<li><a href="#org9d44225">1. Writing nuclear coordinates</a>
<ul>
<li><a href="#org2def822">1.1. Fortran</a>
<ul>
<li><a href="#orge19a482">1.1.1. Declare Temporary variables</a></li>
<li><a href="#orgcefbbd9">1.1.2. Obtain the name of the TREXIO file from the command line, and open it for reading</a></li>
<li><a href="#orgd05b398">1.1.3. Read the nuclear repulsion energy</a></li>
<li><a href="#orgbfdeed9">1.1.4. Read the number of molecular orbitals</a></li>
<li><a href="#org0110ca9">1.1.5. Allocate memory</a></li>
<li><a href="#org46d6ccb">1.1.6. Read one-electron quantities</a></li>
<li><a href="#orgdcb4a96">1.1.7. Read two-electron quantities</a>
<ul>
<li><a href="#org69d43a9">1.1.7.1. Electron repulsion integrals</a></li>
<li><a href="#org01decab">1.1.7.2. Reduced density matrix</a></li>
<li><a href="#org5bf9fc1">1.1. C</a></li>
<li><a href="#org4e8b910">1.2. Python</a></li>
<li><a href="#org75174f1">1.3. Fortran</a></li>
</ul>
</li>
<li><a href="#org0b229e7">1.1.8. Compute the energy</a></li>
<li><a href="#org607bde5">1.1.9. Terminate</a></li>
<li><a href="#org8bd7540">2. Accessing sparse quantities (integrals)</a>
<ul>
<li><a href="#org3620457">2.1. Fortran</a>
<ul>
<li><a href="#org65e066f">2.1.1. Declare Temporary variables</a></li>
<li><a href="#orgc5df3a4">2.1.2. Obtain the name of the TREXIO file from the command line, and open it for reading</a></li>
<li><a href="#orgd76708e">2.1.3. Read the nuclear repulsion energy</a></li>
<li><a href="#org499fef1">2.1.4. Read the number of molecular orbitals</a></li>
<li><a href="#org5cf759e">2.1.5. Allocate memory</a></li>
<li><a href="#org5b16bb7">2.1.6. Read one-electron quantities</a></li>
<li><a href="#org6d6b440">2.1.7. Read two-electron quantities</a>
<ul>
<li><a href="#org2e199b5">2.1.7.1. Electron repulsion integrals</a></li>
<li><a href="#orgbf98524">2.1.7.2. Reduced density matrix</a></li>
</ul>
</li>
<li><a href="#org59c6f27">2.1.8. Compute the energy</a></li>
<li><a href="#org05f886c">2.1.9. Terminate</a></li>
</ul>
</li>
</ul>
</li>
<li><a href="#org2c345eb">2. Reading determinants</a>
<li><a href="#orgbe07a22">3. Reading determinants</a>
<ul>
<li><a href="#orgf294611">2.1. Fortran</a></li>
<li><a href="#org13d3890">3.1. Fortran</a></li>
</ul>
</li>
</ul>
</div>
</div>
<div id="outline-container-org0ada7bb" class="outline-2">
<h2 id="org0ada7bb"><span class="section-number-2">1</span> Accessing sparse quantities (integrals)</h2>
<div id="outline-container-org9d44225" class="outline-2">
<h2 id="org9d44225"><span class="section-number-2">1</span> Writing nuclear coordinates</h2>
<div class="outline-text-2" id="text-1">
<p>
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.
</p>
</div>
<div id="outline-container-org2def822" class="outline-3">
<h3 id="org2def822"><span class="section-number-3">1.1</span> Fortran</h3>
<div id="outline-container-org5bf9fc1" class="outline-3">
<h3 id="org5bf9fc1"><span class="section-number-3">1.1</span> C</h3>
<div class="outline-text-3" id="text-1-1">
<div class="org-src-container">
<pre class="src src-c"><span style="color: #483d8b;">#include</span> <span style="color: #8b2252;">&lt;stdio.h&gt;</span>
<span style="color: #483d8b;">#include</span> <span style="color: #8b2252;">&lt;trexio.h&gt;</span>
<span style="color: #228b22;">int</span> <span style="color: #0000ff;">main</span>() {
<span style="color: #228b22;">int</span> <span style="color: #a0522d;">num</span> = 3; // <span style="color: #b22222;">Number of atoms</span>
<span style="color: #228b22;">double</span> <span style="color: #a0522d;">coord</span>[][3] = {
// <span style="color: #b22222;">xyz coordinates in atomic units</span>
0. , 0. , -0.24962655,
0. , 2.70519714, 1.85136466,
0. , -2.70519714, 1.85136466 };
<span style="color: #228b22;">trexio_exit_code</span> <span style="color: #a0522d;">rc</span>;
// <span style="color: #b22222;">Open the TREXIO file</span>
<span style="color: #228b22;">trexio_t</span>* <span style="color: #a0522d;">f</span> = trexio_open(<span style="color: #8b2252;">"water.trexio"</span>, <span style="color: #8b2252;">'w'</span>, TREXIO_HDF5, &amp;rc);
<span style="color: #a020f0;">if</span> (rc != TREXIO_SUCCESS) {
fprintf(stderr, <span style="color: #8b2252;">"Error: %s\n"</span>, trexio_string_of_error(rc));
<span style="color: #a020f0;">return</span> -1;
}
// <span style="color: #b22222;">Write the number of nuclei</span>
rc = trexio_write_nucleus_num (f, num);
<span style="color: #a020f0;">if</span> (rc != TREXIO_SUCCESS) {
fprintf(stderr, <span style="color: #8b2252;">"Error: %s\n"</span>, trexio_string_of_error(rc));
<span style="color: #a020f0;">return</span> -1;
}
// <span style="color: #b22222;">Write the nuclear coordinates</span>
rc = trexio_write_nucleus_coord (f, &amp;coord[0][0]);
<span style="color: #a020f0;">if</span> (rc != TREXIO_SUCCESS) {
fprintf(stderr, <span style="color: #8b2252;">"Error: %s\n"</span>, trexio_string_of_error(rc));
<span style="color: #a020f0;">return</span> -1;
}
// <span style="color: #b22222;">Close the TREXIO file</span>
rc = trexio_close(f);
<span style="color: #a020f0;">if</span> (rc != TREXIO_SUCCESS) {
fprintf(stderr, <span style="color: #8b2252;">"Error: %s\n"</span>, trexio_string_of_error(rc));
<span style="color: #a020f0;">return</span> -1;
}
<span style="color: #a020f0;">return</span> 0;
}
</pre>
</div>
</div>
</div>
<div id="outline-container-org4e8b910" class="outline-3">
<h3 id="org4e8b910"><span class="section-number-3">1.2</span> Python</h3>
<div class="outline-text-3" id="text-1-2">
<p>
This code uses the TREXIO Python binding to create a new TREXIO file named
<code>water.trexio</code>, and write the nuclear coordinates of a water molecule.
</p>
<p>
The <code>coord</code> variable is a list of three lists, each containing the x, y,
and z coordinates of the water molecule's nuclei.
</p>
<p>
The <code>with</code> statement is used to ensure the file is properly closed after
the write is complete.
</p>
<p>
The <code>trexio.write_nucleus_num</code> function is used to write the number of
nuclei in the system.
</p>
<p>
The <code>trexio.write_nucleus_coord</code> function is used to write the nuclear
coordinates of the system.
</p>
<div class="org-src-container">
<pre class="src src-python"><span style="color: #a020f0;">import</span> trexio
<span style="color: #a0522d;">coord</span> = [ # <span style="color: #b22222;">xyz coordinates in atomic units</span>
[0. , 0., -0.24962655],
[0. , 2.70519714, 1.85136466],
[0. , -2.70519714, 1.85136466]
]
# <span style="color: #b22222;">The Python API calls can raise `trexio.Error`</span>
# <span style="color: #b22222;">exceptions to be handled via try/except clauses</span>
# <span style="color: #b22222;">in the user application</span>
<span style="color: #a020f0;">with</span> trexio.File(<span style="color: #8b2252;">"water.trexio"</span>, <span style="color: #8b2252;">'w'</span>,
back_end=trexio.TREXIO_HDF5) <span style="color: #a020f0;">as</span> f:
trexio.write_nucleus_num(f, <span style="color: #483d8b;">len</span>(coord))
trexio.write_nucleus_coord(f, coord)
</pre>
</div>
</div>
</div>
<div id="outline-container-org75174f1" class="outline-3">
<h3 id="org75174f1"><span class="section-number-3">1.3</span> Fortran</h3>
<div class="outline-text-3" id="text-1-3">
<div class="org-src-container">
<pre class="src src-f90"><span style="color: #a020f0;">program</span> <span style="color: #0000ff;">trexio_water</span>
<span style="color: #a020f0;">use</span> <span style="color: #0000ff;">trexio</span>
<span style="color: #228b22;">integer</span>, <span style="color: #a020f0;">parameter</span> ::<span style="color: #a0522d;"> num=3 </span>! <span style="color: #b22222;">Number of nuclei</span>
<span style="color: #228b22;">double precision</span> ::<span style="color: #a0522d;"> coord(3,3) </span>! <span style="color: #b22222;">Array of atom coordinates</span>
<span style="color: #228b22;">integer</span>(trexio_t) ::<span style="color: #a0522d;"> f </span>! <span style="color: #b22222;">The TREXIO file handle</span>
<span style="color: #228b22;">integer</span>(trexio_exit_code) ::<span style="color: #a0522d;"> rc </span>! <span style="color: #b22222;">TREXIO return code</span>
<span style="color: #228b22;">character</span>*(128) ::<span style="color: #a0522d;"> err_msg </span>! <span style="color: #b22222;">String holding the error message</span>
coord(:,:) = <span style="color: #a020f0;">reshape</span>( (/ 0.d0 , 0.d0 , -0.24962655d0, <span style="color: #a020f0;">&amp;</span>
0.d0 , 2.70519714d0, 1.85136466d0, <span style="color: #a020f0;">&amp;</span>
0.d0 , -2.70519714d0, 1.85136466d0 /), <span style="color: #a020f0;">&amp;</span>
<span style="color: #a020f0;">shape</span>(coord) )
! <span style="color: #b22222;">Open the TREXIO file</span>
f = trexio_open (<span style="color: #8b2252;">'water.trexio'</span>, <span style="color: #8b2252;">'w'</span>, TREXIO_HDF5, rc)
<span style="color: #a020f0;">if</span> (rc /= TREXIO_SUCCESS) <span style="color: #a020f0;">then</span>
<span style="color: #a020f0;">call</span> <span style="color: #0000ff;">trexio_string_of_error</span>(rc, err_msg)
<span style="color: #a020f0;">print</span> *, <span style="color: #8b2252;">'Error: '</span>//<span style="color: #a020f0;">trim</span>(err_msg)
<span style="color: #a020f0;">call</span> <span style="color: #0000ff;">exit</span>(-1)
<span style="color: #a020f0;">end if</span>
! <span style="color: #b22222;">Write the number of nuclei</span>
rc = trexio_write_nucleus_num (f, num)
<span style="color: #a020f0;">if</span> (rc /= TREXIO_SUCCESS) <span style="color: #a020f0;">then</span>
<span style="color: #a020f0;">call</span> <span style="color: #0000ff;">trexio_string_of_error</span>(rc, err_msg)
<span style="color: #a020f0;">print</span> *, <span style="color: #8b2252;">'Error: '</span>//<span style="color: #a020f0;">trim</span>(err_msg)
<span style="color: #a020f0;">call</span> <span style="color: #0000ff;">exit</span>(-1)
<span style="color: #a020f0;">end if</span>
! <span style="color: #b22222;">Write the nuclear coordinates</span>
rc = trexio_write_nucleus_coord (f, coord)
<span style="color: #a020f0;">if</span> (rc /= TREXIO_SUCCESS) <span style="color: #a020f0;">then</span>
<span style="color: #a020f0;">call</span> <span style="color: #0000ff;">trexio_string_of_error</span>(rc, err_msg)
<span style="color: #a020f0;">print</span> *, <span style="color: #8b2252;">'Error: '</span>//<span style="color: #a020f0;">trim</span>(err_msg)
<span style="color: #a020f0;">call</span> <span style="color: #0000ff;">exit</span>(-1)
<span style="color: #a020f0;">end if</span>
! <span style="color: #b22222;">Close the TREXIO file</span>
rc = trexio_close(f)
<span style="color: #a020f0;">if</span> (rc /= TREXIO_SUCCESS) <span style="color: #a020f0;">then</span>
<span style="color: #a020f0;">call</span> <span style="color: #0000ff;">trexio_string_of_error</span>(rc, err_msg)
<span style="color: #a020f0;">print</span> *, <span style="color: #8b2252;">'Error: '</span>//<span style="color: #a020f0;">trim</span>(err_msg)
<span style="color: #a020f0;">call</span> <span style="color: #0000ff;">exit</span>(-1)
<span style="color: #a020f0;">end if</span>
<span style="color: #a020f0;">end program</span>
</pre>
</div>
</div>
</div>
</div>
<div id="outline-container-org8bd7540" class="outline-2">
<h2 id="org8bd7540"><span class="section-number-2">2</span> Accessing sparse quantities (integrals)</h2>
<div class="outline-text-2" id="text-2">
</div>
<div id="outline-container-org3620457" class="outline-3">
<h3 id="org3620457"><span class="section-number-3">2.1</span> Fortran</h3>
<div class="outline-text-3" id="text-2-1">
<div class="org-src-container">
<pre class="src src-f90"><span style="color: #a020f0;">program</span> <span style="color: #0000ff;">print_energy</span>
<span style="color: #a020f0;">use</span> <span style="color: #0000ff;">trexio</span>
<span style="color: #a020f0;">implicit</span> <span style="color: #228b22;">none</span>
@ -429,9 +603,9 @@ One needs to read from the TREXIO file:
</div>
</div>
<div id="outline-container-orge19a482" class="outline-4">
<h4 id="orge19a482"><span class="section-number-4">1.1.1</span> Declare Temporary variables</h4>
<div class="outline-text-4" id="text-1-1-1">
<div id="outline-container-org65e066f" class="outline-4">
<h4 id="org65e066f"><span class="section-number-4">2.1.1</span> Declare Temporary variables</h4>
<div class="outline-text-4" id="text-2-1-1">
<div class="org-src-container">
<pre class="src src-f90"><span style="color: #228b22;">integer</span> ::<span style="color: #a0522d;"> i, j, k, l, m</span>
<span style="color: #228b22;">integer</span>(8), <span style="color: #a020f0;">parameter</span> ::<span style="color: #a0522d;"> BUFSIZE = 100000_8</span>
@ -445,9 +619,9 @@ One needs to read from the TREXIO file:
</div>
</div>
<div id="outline-container-orgcefbbd9" class="outline-4">
<h4 id="orgcefbbd9"><span class="section-number-4">1.1.2</span> Obtain the name of the TREXIO file from the command line, and open it for reading</h4>
<div class="outline-text-4" id="text-1-1-2">
<div id="outline-container-orgc5df3a4" class="outline-4">
<h4 id="orgc5df3a4"><span class="section-number-4">2.1.2</span> Obtain the name of the TREXIO file from the command line, and open it for reading</h4>
<div class="outline-text-4" id="text-2-1-2">
<div class="org-src-container">
<pre class="src src-f90"><span style="color: #a020f0;">call</span> <span style="color: #0000ff;">getarg</span>(1, filename)
@ -462,9 +636,9 @@ f = trexio_open (filename, <span style="color: #8b2252;">'r'</span>, TREXIO_HDF5
</div>
</div>
<div id="outline-container-orgd05b398" class="outline-4">
<h4 id="orgd05b398"><span class="section-number-4">1.1.3</span> Read the nuclear repulsion energy</h4>
<div class="outline-text-4" id="text-1-1-3">
<div id="outline-container-orgd76708e" class="outline-4">
<h4 id="orgd76708e"><span class="section-number-4">2.1.3</span> Read the nuclear repulsion energy</h4>
<div class="outline-text-4" id="text-2-1-3">
<div class="org-src-container">
<pre class="src src-f90">rc = trexio_read_nucleus_repulsion(f, E_nn)
<span style="color: #a020f0;">if</span> (rc /= TREXIO_SUCCESS) <span style="color: #a020f0;">then</span>
@ -477,9 +651,9 @@ f = trexio_open (filename, <span style="color: #8b2252;">'r'</span>, TREXIO_HDF5
</div>
</div>
<div id="outline-container-orgbfdeed9" class="outline-4">
<h4 id="orgbfdeed9"><span class="section-number-4">1.1.4</span> Read the number of molecular orbitals</h4>
<div class="outline-text-4" id="text-1-1-4">
<div id="outline-container-org499fef1" class="outline-4">
<h4 id="org499fef1"><span class="section-number-4">2.1.4</span> Read the number of molecular orbitals</h4>
<div class="outline-text-4" id="text-2-1-4">
<div class="org-src-container">
<pre class="src src-f90">rc = trexio_read_mo_num(f, n)
<span style="color: #a020f0;">if</span> (rc /= TREXIO_SUCCESS) <span style="color: #a020f0;">then</span>
@ -492,9 +666,9 @@ f = trexio_open (filename, <span style="color: #8b2252;">'r'</span>, TREXIO_HDF5
</div>
</div>
<div id="outline-container-org0110ca9" class="outline-4">
<h4 id="org0110ca9"><span class="section-number-4">1.1.5</span> Allocate memory</h4>
<div class="outline-text-4" id="text-1-1-5">
<div id="outline-container-org5cf759e" class="outline-4">
<h4 id="org5cf759e"><span class="section-number-4">2.1.5</span> Allocate memory</h4>
<div class="outline-text-4" id="text-2-1-5">
<div class="org-src-container">
<pre class="src src-f90"><span style="color: #a020f0;">allocate</span>( D(n,n), h0(n,n) )
<span style="color: #a020f0;">allocate</span>( G(n,n,n,n), W(n,n,n,n) )
@ -505,9 +679,9 @@ W(:,:,:,:) = 0.d0
</div>
</div>
<div id="outline-container-org46d6ccb" class="outline-4">
<h4 id="org46d6ccb"><span class="section-number-4">1.1.6</span> Read one-electron quantities</h4>
<div class="outline-text-4" id="text-1-1-6">
<div id="outline-container-org5b16bb7" class="outline-4">
<h4 id="org5b16bb7"><span class="section-number-4">2.1.6</span> Read one-electron quantities</h4>
<div class="outline-text-4" id="text-2-1-6">
<div class="org-src-container">
<pre class="src src-f90">rc = trexio_has_mo_1e_int_core_hamiltonian(f)
<span style="color: #a020f0;">if</span> (rc /= TREXIO_SUCCESS) <span style="color: #a020f0;">then</span>
@ -538,9 +712,9 @@ rc = trexio_read_rdm_1e(f, D)
</div>
</div>
<div id="outline-container-orgdcb4a96" class="outline-4">
<h4 id="orgdcb4a96"><span class="section-number-4">1.1.7</span> Read two-electron quantities</h4>
<div class="outline-text-4" id="text-1-1-7">
<div id="outline-container-org6d6b440" class="outline-4">
<h4 id="org6d6b440"><span class="section-number-4">2.1.7</span> Read two-electron quantities</h4>
<div class="outline-text-4" id="text-2-1-7">
<p>
Reading is done with OpenMP. Each thread reads its own buffer, and
the buffers are then processed in parallel.
@ -555,9 +729,9 @@ to be protected in the critical section when modified.
</p>
</div>
<div id="outline-container-org69d43a9" class="outline-5">
<h5 id="org69d43a9"><span class="section-number-5">1.1.7.1</span> Electron repulsion integrals</h5>
<div class="outline-text-5" id="text-1-1-7-1">
<div id="outline-container-org2e199b5" class="outline-5">
<h5 id="org2e199b5"><span class="section-number-5">2.1.7.1</span> Electron repulsion integrals</h5>
<div class="outline-text-5" id="text-2-1-7-1">
<div class="org-src-container">
<pre class="src src-f90">rc = trexio_has_mo_2e_int_eri(f)
<span style="color: #a020f0;">if</span> (rc /= TREXIO_SUCCESS) <span style="color: #a020f0;">then</span>
@ -605,9 +779,9 @@ icount = BUFSIZE
</div>
</div>
<div id="outline-container-org01decab" class="outline-5">
<h5 id="org01decab"><span class="section-number-5">1.1.7.2</span> Reduced density matrix</h5>
<div class="outline-text-5" id="text-1-1-7-2">
<div id="outline-container-orgbf98524" class="outline-5">
<h5 id="orgbf98524"><span class="section-number-5">2.1.7.2</span> Reduced density matrix</h5>
<div class="outline-text-5" id="text-2-1-7-2">
<div class="org-src-container">
<pre class="src src-f90">rc = trexio_has_rdm_2e(f)
<span style="color: #a020f0;">if</span> (rc /= TREXIO_SUCCESS) <span style="color: #a020f0;">then</span>
@ -650,9 +824,9 @@ icount = bufsize
</div>
</div>
<div id="outline-container-org0b229e7" class="outline-4">
<h4 id="org0b229e7"><span class="section-number-4">1.1.8</span> Compute the energy</h4>
<div class="outline-text-4" id="text-1-1-8">
<div id="outline-container-org59c6f27" class="outline-4">
<h4 id="org59c6f27"><span class="section-number-4">2.1.8</span> Compute the energy</h4>
<div class="outline-text-4" id="text-2-1-8">
<p>
When the orbitals are real, we can use
</p>
@ -697,9 +871,9 @@ E = E + E_nn
</div>
</div>
<div id="outline-container-org607bde5" class="outline-4">
<h4 id="org607bde5"><span class="section-number-4">1.1.9</span> Terminate</h4>
<div class="outline-text-4" id="text-1-1-9">
<div id="outline-container-org05f886c" class="outline-4">
<h4 id="org05f886c"><span class="section-number-4">2.1.9</span> Terminate</h4>
<div class="outline-text-4" id="text-2-1-9">
<div class="org-src-container">
<pre class="src src-f90"> <span style="color: #a020f0;">deallocate</span>( D, h0, G, W )
@ -711,14 +885,13 @@ E = E + E_nn
</div>
</div>
<div id="outline-container-org2c345eb" class="outline-2">
<h2 id="org2c345eb"><span class="section-number-2">2</span> Reading determinants</h2>
<div class="outline-text-2" id="text-2">
<div id="outline-container-orgbe07a22" class="outline-2">
<h2 id="orgbe07a22"><span class="section-number-2">3</span> Reading determinants</h2>
<div class="outline-text-2" id="text-3">
</div>
<div id="outline-container-orgf294611" class="outline-3">
<h3 id="orgf294611"><span class="section-number-3">2.1</span> Fortran</h3>
<div class="outline-text-3" id="text-2-1">
<div id="outline-container-org13d3890" class="outline-3">
<h3 id="org13d3890"><span class="section-number-3">3.1</span> Fortran</h3>
<div class="outline-text-3" id="text-3-1">
<div class="org-src-container">
<pre class="src src-f90"><span style="color: #a020f0;">program</span> <span style="color: #0000ff;">test</span>
@ -796,7 +969,7 @@ end
</div>
<div id="postamble" class="status">
<p class="author">Author: TREX-CoE</p>
<p class="date">Created: 2023-02-16 Thu 08:31</p>
<p class="date">Created: 2023-02-17 Fri 16:43</p>
<p class="validation"><a href="http://validator.w3.org/check?uri=referer">Validate</a></p>
</div>
</body>

490
examples.org Normal file
View File

@ -0,0 +1,490 @@
#+TITLE: Examples
#+STARTUP: latexpreview
#+SETUPFILE: ./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)
** Fortran
:PROPERTIES:
:header-args: :tangle print_energy.f90
:END:
#+begin_src f90
program print_energy
use trexio
implicit none
character*(128) :: filename ! Name of the input file
integer :: rc ! Return code for error checking
integer(8) :: f ! TREXIO file handle
character*(128) :: err_msg ! Error message
#+end_src
This program computes the energy as:
\[
E = E_{\text{NN}} + \sum_{ij} \gamma_{ij}\, \langle j | h | i \rangle\,
+\, \frac{1}{2} \sum_{ijkl} \Gamma_{ijkl}\, \langle k l | i j
\rangle\; \textrm{ with } \; 0 < i,j,k,l \le n
\]
One needs to read from the TREXIO file:
- $n$ :: The number of molecular orbitals
- $E_{\text{NN}}$ :: The nuclear repulsion energy
- $\gamma_{ij}$ :: The one-body reduced density matrix
- $\langle j |h| i \rangle$ :: The one-electron Hamiltonian integrals
- $\Gamma_{ijkl}$ :: The two-body reduced density matrix
- $\langle k l | i j \rangle$ :: The electron repulsion integrals
#+begin_src f90
integer :: n
double precision :: E, E_nn
double precision, allocatable :: D(:,:), h0(:,:)
double precision, allocatable :: G(:,:,:,:), W(:,:,:,:)
#+end_src
*** Declare Temporary variables
#+begin_src f90
integer :: i, j, k, l, m
integer(8), parameter :: BUFSIZE = 100000_8
integer(8) :: offset, icount, size_max
integer :: buffer_index(4,BUFSIZE)
double precision :: buffer_values(BUFSIZE)
double precision, external :: ddot ! BLAS dot product
#+end_src
*** Obtain the name of the TREXIO file from the command line, and open it for reading
#+begin_src f90
call getarg(1, filename)
f = trexio_open (filename, 'r', TREXIO_HDF5, rc)
if (rc /= TREXIO_SUCCESS) then
call trexio_string_of_error(rc, err_msg)
print *, 'Error opening TREXIO file: '//trim(err_msg)
stop
end if
#+end_src
*** Read the nuclear repulsion energy
#+begin_src f90
rc = trexio_read_nucleus_repulsion(f, E_nn)
if (rc /= TREXIO_SUCCESS) then
call trexio_string_of_error(rc, err_msg)
print *, 'Error reading nuclear repulsion: '//trim(err_msg)
stop
end if
#+end_src
*** Read the number of molecular orbitals
#+begin_src f90
rc = trexio_read_mo_num(f, n)
if (rc /= TREXIO_SUCCESS) then
call trexio_string_of_error(rc, err_msg)
print *, 'Error reading number of MOs: '//trim(err_msg)
stop
end if
#+end_src
*** Allocate memory
#+begin_src f90
allocate( D(n,n), h0(n,n) )
allocate( G(n,n,n,n), W(n,n,n,n) )
G(:,:,:,:) = 0.d0
W(:,:,:,:) = 0.d0
#+end_src
*** Read one-electron quantities
#+begin_src f90
rc = trexio_has_mo_1e_int_core_hamiltonian(f)
if (rc /= TREXIO_SUCCESS) then
stop 'No core hamiltonian in file'
end if
rc = trexio_read_mo_1e_int_core_hamiltonian(f, h0)
if (rc /= TREXIO_SUCCESS) then
call trexio_string_of_error(rc, err_msg)
print *, 'Error reading core Hamiltonian: '//trim(err_msg)
stop
end if
rc = trexio_has_rdm_1e(f)
if (rc /= TREXIO_SUCCESS) then
stop 'No 1e RDM in file'
end if
rc = trexio_read_rdm_1e(f, D)
if (rc /= TREXIO_SUCCESS) then
call trexio_string_of_error(rc, err_msg)
print *, 'Error reading one-body RDM: '//trim(err_msg)
stop
end if
#+end_src
*** Read two-electron quantities
Reading is done with OpenMP. Each thread reads its own buffer, and
the buffers are then processed in parallel.
Reading the file requires a lock, so it is done in a critical
section. The ~offset~ variable is shared, and it is incremented in
the critical section. For each read, the function returns in
~icount~ the number of read integrals, so this variable needs also
to be protected in the critical section when modified.
**** Electron repulsion integrals
#+begin_src f90
rc = trexio_has_mo_2e_int_eri(f)
if (rc /= TREXIO_SUCCESS) then
stop 'No electron repulsion integrals in file'
end if
rc = trexio_read_mo_2e_int_eri_size (f, size_max)
if (rc /= TREXIO_SUCCESS) then
call trexio_string_of_error(rc, err_msg)
print *, 'Error reading number of ERIs: '//trim(err_msg)
stop
end if
offset = 0_8
!$OMP PARALLEL DEFAULT(SHARED) PRIVATE(icount, i, j, k, l, &
!$OMP buffer_index, buffer_values, m)
icount = BUFSIZE
do while (icount == BUFSIZE)
!$OMP CRITICAL
if (offset < size_max) then
rc = trexio_read_mo_2e_int_eri(f, offset, icount, buffer_index, buffer_values)
offset = offset + icount
else
icount = 0
end if
!$OMP END CRITICAL
do m=1,icount
i = buffer_index(1,m)
j = buffer_index(2,m)
k = buffer_index(3,m)
l = buffer_index(4,m)
W(i,j,k,l) = buffer_values(m)
W(k,j,i,l) = buffer_values(m)
W(i,l,k,j) = buffer_values(m)
W(k,l,i,j) = buffer_values(m)
W(j,i,l,k) = buffer_values(m)
W(j,k,l,i) = buffer_values(m)
W(l,i,j,k) = buffer_values(m)
W(l,k,j,i) = buffer_values(m)
end do
end do
!$OMP END PARALLEL
#+end_src
**** Reduced density matrix
#+begin_src f90
rc = trexio_has_rdm_2e(f)
if (rc /= TREXIO_SUCCESS) then
stop 'No two-body density matrix in file'
end if
rc = trexio_read_rdm_2e_size (f, size_max)
if (rc /= TREXIO_SUCCESS) then
call trexio_string_of_error(rc, err_msg)
print *, 'Error reading number of 2-RDM elements: '//trim(err_msg)
stop
end if
offset = 0_8
!$OMP PARALLEL DEFAULT(SHARED) PRIVATE(icount, i, j, k, l, &
!$OMP buffer_index, buffer_values, m)
icount = bufsize
do while (offset < size_max)
!$OMP CRITICAL
if (offset < size_max) then
rc = trexio_read_rdm_2e(f, offset, icount, buffer_index, buffer_values)
offset = offset + icount
else
icount = 0
end if
!$OMP END CRITICAL
do m=1,icount
i = buffer_index(1,m)
j = buffer_index(2,m)
k = buffer_index(3,m)
l = buffer_index(4,m)
G(i,j,k,l) = buffer_values(m)
end do
end do
!$OMP END PARALLEL
#+end_src
*** Compute the energy
When the orbitals are real, we can use
\begin{eqnarray*}
E &=& E_{\text{NN}} + \sum_{ij} \gamma_{ij}\, \langle j | h | i \rangle\,
+\, \frac{1}{2} \sum_{ijkl} \Gamma_{ijkl}\, \langle k l | i j
\rangle \\
&=& E_{\text{NN}} + \sum_{ij} \gamma_{ij}\, \langle i | h | j \rangle\,
+\, \frac{1}{2} \sum_{ijkl} \Gamma_{ijkl}\, \langle i j | k l
\rangle \\
\end{eqnarray*}
As $(n,m)$ 2D arrays are stored in memory as $(n \times m)$ 1D
arrays, we could pass the matrices to the ~ddot~ BLAS function to
perform the summations in a single call for the 1-electron quantities.
Instead, we prefer to interleave the 1-electron (negative) and
2-electron (positive) summations to have a better cancellation of
numerical errors.
Here $n^4$ can be larger than the largest possible 32-bit integer,
so it is not safe to pass $n^4$ to the ~ddot~ BLAS
function. Hence, we perform $n^2$ loops, using vectors of size $n^2$.
#+begin_src f90
E = 0.d0
do l=1,n
E = E + ddot( n, D(1,l), 1, h0(1,l), 1 )
do k=1,n
E = E + 0.5d0 * ddot( n*n, G(1,1,k,l), 1, W(1,1,k,l), 1 )
end do
end do
E = E + E_nn
print *, 'Energy: ', E
#+end_src
*** Terminate
#+begin_src f90
deallocate( D, h0, G, W )
end program
#+end_src
* Reading determinants
** Fortran
:PROPERTIES:
:header-args: :tangle print_dets.f90
:END:
#+begin_src f90
program test
use trexio
implicit none
character*(128) :: filename ! Name of the input file
integer(trexio_exit_code) :: rc ! Return code for error checking
integer(trexio_t) :: trex_determinant_file ! TREXIO file handle
character*(128) :: err_msg ! Error message
integer*8, allocatable :: buffer(:,:,:)
integer(8) :: offset, icount, BUFSIZE
integer :: ndet, int64_num, m
integer :: occ_num_up, occ_num_dn
integer, allocatable :: orb_list_up(:), orb_list_dn(:)
call getarg(1, filename)
trex_determinant_file = trexio_open(filename, 'r', TREXIO_AUTO, rc)
if (rc /= TREXIO_SUCCESS) then
call trexio_string_of_error(rc, err_msg)
print *, 'Error opening TREXIO file: '//trim(err_msg)
stop
end if
rc = trexio_read_determinant_num(trex_determinant_file, ndet)
if (rc /= TREXIO_SUCCESS) then
call trexio_string_of_error(rc, err_msg)
print *, 'Error reading determinant_num: '//trim(err_msg)
stop
end if
print *, 'ndet', ndet
rc = trexio_get_int64_num(trex_determinant_file, int64_num)
if (rc /= TREXIO_SUCCESS) then
call trexio_string_of_error(rc, err_msg)
print *, 'Error reading int64_num: '//trim(err_msg)
stop
end if
print *, 'int64_num', int64_num
BUFSIZE = 1000_8
allocate(buffer(int64_num, 2, BUFSIZE))
allocate(orb_list_up(int64_num*64), orb_list_dn(int64_num*64))
offset = 0_8
icount = BUFSIZE
do while (icount == BUFSIZE)
if (offset < ndet) then
rc = trexio_read_determinant_list(trex_determinant_file, offset, icount, buffer)
offset = offset + icount
else
icount = 0
end if
print *, '---'
do m=1,icount
rc = trexio_to_orbital_list_up_dn(int64_num, buffer(1,1,m), &
orb_list_up, orb_list_dn, occ_num_up, occ_num_dn)
print '(100(I3,X))', (orb_list_up(1:occ_num_up)), (orb_list_dn(1:occ_num_dn))
print *, ''
end do
end do
deallocate(buffer, orb_list_dn, orb_list_up)
end
#+end_src

47
index.html
View File

@ -3,7 +3,7 @@
"http://www.w3.org/TR/xhtml1/DTD/xhtml1-strict.dtd">
<html xmlns="http://www.w3.org/1999/xhtml" lang="en" xml:lang="en">
<head>
<!-- 2023-02-16 Thu 08:31 -->
<!-- 2023-02-17 Fri 16:43 -->
<meta http-equiv="Content-Type" content="text/html;charset=utf-8" />
<meta name="viewport" content="width=device-width, initial-scale=1" />
<title>TREXIO source code documentation</title>
@ -261,7 +261,7 @@ org_html_manager.set("LOCAL_TOC", "1");
org_html_manager.set("VIEW_BUTTONS", "0");
org_html_manager.set("MOUSE_HINT", "underline");
org_html_manager.set("FIXED_TOC", "0");
org_html_manager.set("TOC", "1");
org_html_manager.set("TOC", "0");
org_html_manager.set("VIEW", "info");
org_html_manager.setup(); // activate after the parameters are set
/*]]>*///-->
@ -320,31 +320,50 @@ for the JavaScript code in this tag.
<a accesskey="H" href="index.html"> HOME </a>
</div><div id="content">
<h1 class="title">TREXIO source code documentation</h1>
<hr />
<script async src="https://cse.google.com/cse.js?cx=a67f8ab65a66f97f2"></script>
<div class="gcse-search"></div>
<hr />
<p>
TREXIO is an open-source file format and library developed for the storage and
manipulation of data produced by quantum chemistry calculations. It was
designed with the goal of providing a reliable and efficient method of storing
and exchanging wave function parameters and matrix elements.
</p>
<p>
The library consists of a front-end implemented in the C programming language
and two different back-ends: a text back-end and a binary back-end utilizing
the HDF5 library enabling fast read and write speeds. It is compatible with a
variety of platforms and has interfaces for Fortran, Python, and OCaml.
</p>
<hr />
<table style="width:100%">
<tr><td style="width:50%">
<ul class="org-ul">
<li><a href="./tutorial_benzene.html">Tutorial</a></li>
<li><a href="./intro.html">Motivation</a></li>
<li><a href="./lib.html">The TREXIO library</a></li>
<li><a href="./trex.html">Data stored with TREXIO</a></li>
<li><a href="./tutorial_benzene.html">Tutorial</a></li>
<li><a href="./examples.html">How-to guide</a></li>
<li><a href="./templator_front.html">Front end API</a></li>
<li><a href="./templator_hdf5.html">HDF5 back end</a></li>
<li><a href="./templator_text.html">TEXT back end</a></li>
</ul>
</td>
<td>
<img src="trexio.png" alt="T-Rex talking about chemistry"
align="right" width="300"/>
</td></tr>
</table>
<hr />
<p>
The TREXIO library defines a standard format for storing wave functions,
together with an C-compatible API such that it can be easily used in any
programming language.
</p>
<p>
The source code of the library is available at
<a href="https://github.com/trex-coe/trexio">https://github.com/trex-coe/trexio</a>
@ -352,6 +371,10 @@ and bug reports should be submitted at
<a href="https://github.com/trex-coe/trexio/issues">https://github.com/trex-coe/trexio/issues</a>.
</p>
<p>
The TREXIO library is licensed under the open-source 3-clause BSD license.
</p>
<hr />
<p>
@ -360,7 +383,7 @@ and bug reports should be submitted at
</div>
<div id="postamble" class="status">
<p class="author">Author: TREX-CoE</p>
<p class="date">Created: 2023-02-16 Thu 08:31</p>
<p class="date">Created: 2023-02-17 Fri 16:43</p>
<p class="validation"><a href="http://validator.w3.org/check?uri=referer">Validate</a></p>
</div>
</body>

391
intro.html Normal file
View File

@ -0,0 +1,391 @@
<?xml version="1.0" encoding="utf-8"?>
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Strict//EN"
"http://www.w3.org/TR/xhtml1/DTD/xhtml1-strict.dtd">
<html xmlns="http://www.w3.org/1999/xhtml" lang="en" xml:lang="en">
<head>
<!-- 2023-02-17 Fri 16:43 -->
<meta http-equiv="Content-Type" content="text/html;charset=utf-8" />
<meta name="viewport" content="width=device-width, initial-scale=1" />
<title>Motivation</title>
<meta name="generator" content="Org mode" />
<meta name="author" content="TREX-CoE" />
<style type="text/css">
<!--/*--><![CDATA[/*><!--*/
.title { text-align: center;
margin-bottom: .2em; }
.subtitle { text-align: center;
font-size: medium;
font-weight: bold;
margin-top:0; }
.todo { font-family: monospace; color: red; }
.done { font-family: monospace; color: green; }
.priority { font-family: monospace; color: orange; }
.tag { background-color: #eee; font-family: monospace;
padding: 2px; font-size: 80%; font-weight: normal; }
.timestamp { color: #bebebe; }
.timestamp-kwd { color: #5f9ea0; }
.org-right { margin-left: auto; margin-right: 0px; text-align: right; }
.org-left { margin-left: 0px; margin-right: auto; text-align: left; }
.org-center { margin-left: auto; margin-right: auto; text-align: center; }
.underline { text-decoration: underline; }
#postamble p, #preamble p { font-size: 90%; margin: .2em; }
p.verse { margin-left: 3%; }
pre {
border: 1px solid #ccc;
box-shadow: 3px 3px 3px #eee;
padding: 8pt;
font-family: monospace;
overflow: auto;
margin: 1.2em;
}
pre.src {
position: relative;
overflow: visible;
padding-top: 1.2em;
}
pre.src:before {
display: none;
position: absolute;
background-color: white;
top: -10px;
right: 10px;
padding: 3px;
border: 1px solid black;
}
pre.src:hover:before { display: inline;}
/* Languages per Org manual */
pre.src-asymptote:before { content: 'Asymptote'; }
pre.src-awk:before { content: 'Awk'; }
pre.src-C:before { content: 'C'; }
/* pre.src-C++ doesn't work in CSS */
pre.src-clojure:before { content: 'Clojure'; }
pre.src-css:before { content: 'CSS'; }
pre.src-D:before { content: 'D'; }
pre.src-ditaa:before { content: 'ditaa'; }
pre.src-dot:before { content: 'Graphviz'; }
pre.src-calc:before { content: 'Emacs Calc'; }
pre.src-emacs-lisp:before { content: 'Emacs Lisp'; }
pre.src-fortran:before { content: 'Fortran'; }
pre.src-gnuplot:before { content: 'gnuplot'; }
pre.src-haskell:before { content: 'Haskell'; }
pre.src-hledger:before { content: 'hledger'; }
pre.src-java:before { content: 'Java'; }
pre.src-js:before { content: 'Javascript'; }
pre.src-latex:before { content: 'LaTeX'; }
pre.src-ledger:before { content: 'Ledger'; }
pre.src-lisp:before { content: 'Lisp'; }
pre.src-lilypond:before { content: 'Lilypond'; }
pre.src-lua:before { content: 'Lua'; }
pre.src-matlab:before { content: 'MATLAB'; }
pre.src-mscgen:before { content: 'Mscgen'; }
pre.src-ocaml:before { content: 'Objective Caml'; }
pre.src-octave:before { content: 'Octave'; }
pre.src-org:before { content: 'Org mode'; }
pre.src-oz:before { content: 'OZ'; }
pre.src-plantuml:before { content: 'Plantuml'; }
pre.src-processing:before { content: 'Processing.js'; }
pre.src-python:before { content: 'Python'; }
pre.src-R:before { content: 'R'; }
pre.src-ruby:before { content: 'Ruby'; }
pre.src-sass:before { content: 'Sass'; }
pre.src-scheme:before { content: 'Scheme'; }
pre.src-screen:before { content: 'Gnu Screen'; }
pre.src-sed:before { content: 'Sed'; }
pre.src-sh:before { content: 'shell'; }
pre.src-sql:before { content: 'SQL'; }
pre.src-sqlite:before { content: 'SQLite'; }
/* additional languages in org.el's org-babel-load-languages alist */
pre.src-forth:before { content: 'Forth'; }
pre.src-io:before { content: 'IO'; }
pre.src-J:before { content: 'J'; }
pre.src-makefile:before { content: 'Makefile'; }
pre.src-maxima:before { content: 'Maxima'; }
pre.src-perl:before { content: 'Perl'; }
pre.src-picolisp:before { content: 'Pico Lisp'; }
pre.src-scala:before { content: 'Scala'; }
pre.src-shell:before { content: 'Shell Script'; }
pre.src-ebnf2ps:before { content: 'ebfn2ps'; }
/* additional language identifiers per "defun org-babel-execute"
in ob-*.el */
pre.src-cpp:before { content: 'C++'; }
pre.src-abc:before { content: 'ABC'; }
pre.src-coq:before { content: 'Coq'; }
pre.src-groovy:before { content: 'Groovy'; }
/* additional language identifiers from org-babel-shell-names in
ob-shell.el: ob-shell is the only babel language using a lambda to put
the execution function name together. */
pre.src-bash:before { content: 'bash'; }
pre.src-csh:before { content: 'csh'; }
pre.src-ash:before { content: 'ash'; }
pre.src-dash:before { content: 'dash'; }
pre.src-ksh:before { content: 'ksh'; }
pre.src-mksh:before { content: 'mksh'; }
pre.src-posh:before { content: 'posh'; }
/* Additional Emacs modes also supported by the LaTeX listings package */
pre.src-ada:before { content: 'Ada'; }
pre.src-asm:before { content: 'Assembler'; }
pre.src-caml:before { content: 'Caml'; }
pre.src-delphi:before { content: 'Delphi'; }
pre.src-html:before { content: 'HTML'; }
pre.src-idl:before { content: 'IDL'; }
pre.src-mercury:before { content: 'Mercury'; }
pre.src-metapost:before { content: 'MetaPost'; }
pre.src-modula-2:before { content: 'Modula-2'; }
pre.src-pascal:before { content: 'Pascal'; }
pre.src-ps:before { content: 'PostScript'; }
pre.src-prolog:before { content: 'Prolog'; }
pre.src-simula:before { content: 'Simula'; }
pre.src-tcl:before { content: 'tcl'; }
pre.src-tex:before { content: 'TeX'; }
pre.src-plain-tex:before { content: 'Plain TeX'; }
pre.src-verilog:before { content: 'Verilog'; }
pre.src-vhdl:before { content: 'VHDL'; }
pre.src-xml:before { content: 'XML'; }
pre.src-nxml:before { content: 'XML'; }
/* add a generic configuration mode; LaTeX export needs an additional
(add-to-list 'org-latex-listings-langs '(conf " ")) in .emacs */
pre.src-conf:before { content: 'Configuration File'; }
table { border-collapse:collapse; }
caption.t-above { caption-side: top; }
caption.t-bottom { caption-side: bottom; }
td, th { vertical-align:top; }
th.org-right { text-align: center; }
th.org-left { text-align: center; }
th.org-center { text-align: center; }
td.org-right { text-align: right; }
td.org-left { text-align: left; }
td.org-center { text-align: center; }
dt { font-weight: bold; }
.footpara { display: inline; }
.footdef { margin-bottom: 1em; }
.figure { padding: 1em; }
.figure p { text-align: center; }
.equation-container {
display: table;
text-align: center;
width: 100%;
}
.equation {
vertical-align: middle;
}
.equation-label {
display: table-cell;
text-align: right;
vertical-align: middle;
}
.inlinetask {
padding: 10px;
border: 2px solid gray;
margin: 10px;
background: #ffffcc;
}
#org-div-home-and-up
{ text-align: right; font-size: 70%; white-space: nowrap; }
textarea { overflow-x: auto; }
.linenr { font-size: smaller }
.code-highlighted { background-color: #ffff00; }
.org-info-js_info-navigation { border-style: none; }
#org-info-js_console-label
{ font-size: 10px; font-weight: bold; white-space: nowrap; }
.org-info-js_search-highlight
{ background-color: #ffff00; color: #000000; font-weight: bold; }
.org-svg { width: 90%; }
/*]]>*/-->
</style>
<link rel="stylesheet" title="Standard" href="trexio.css" type="text/css" />
<script type="text/javascript" src="org-info.js">
/**
*
* @source: org-info.js
*
* @licstart The following is the entire license notice for the
* JavaScript code in org-info.js.
*
* Copyright (C) 2012-2020 Free Software Foundation, Inc.
*
*
* The JavaScript code in this tag is free software: you can
* redistribute it and/or modify it under the terms of the GNU
* General Public License (GNU GPL) as published by the Free Software
* Foundation, either version 3 of the License, or (at your option)
* any later version. The code is distributed WITHOUT ANY WARRANTY;
* without even the implied warranty of MERCHANTABILITY or FITNESS
* FOR A PARTICULAR PURPOSE. See the GNU GPL for more details.
*
* As additional permission under GNU GPL version 3 section 7, you
* may distribute non-source (e.g., minimized or compacted) forms of
* that code without the copy of the GNU GPL normally required by
* section 4, provided you include this license notice and a URL
* through which recipients can access the Corresponding Source.
*
* @licend The above is the entire license notice
* for the JavaScript code in org-info.js.
*
*/
</script>
<script type="text/javascript">
/*
@licstart The following is the entire license notice for the
JavaScript code in this tag.
Copyright (C) 2012-2020 Free Software Foundation, Inc.
The JavaScript code in this tag is free software: you can
redistribute it and/or modify it under the terms of the GNU
General Public License (GNU GPL) as published by the Free Software
Foundation, either version 3 of the License, or (at your option)
any later version. The code is distributed WITHOUT ANY WARRANTY;
without even the implied warranty of MERCHANTABILITY or FITNESS
FOR A PARTICULAR PURPOSE. See the GNU GPL for more details.
As additional permission under GNU GPL version 3 section 7, you
may distribute non-source (e.g., minimized or compacted) forms of
that code without the copy of the GNU GPL normally required by
section 4, provided you include this license notice and a URL
through which recipients can access the Corresponding Source.
@licend The above is the entire license notice
for the JavaScript code in this tag.
*/
<!--/*--><![CDATA[/*><!--*/
org_html_manager.set("TOC_DEPTH", "4");
org_html_manager.set("LINK_HOME", "index.html");
org_html_manager.set("LINK_UP", "");
org_html_manager.set("LOCAL_TOC", "1");
org_html_manager.set("VIEW_BUTTONS", "0");
org_html_manager.set("MOUSE_HINT", "underline");
org_html_manager.set("FIXED_TOC", "0");
org_html_manager.set("TOC", "0");
org_html_manager.set("VIEW", "info");
org_html_manager.setup(); // activate after the parameters are set
/*]]>*///-->
</script>
<script type="text/javascript">
/*
@licstart The following is the entire license notice for the
JavaScript code in this tag.
Copyright (C) 2012-2020 Free Software Foundation, Inc.
The JavaScript code in this tag is free software: you can
redistribute it and/or modify it under the terms of the GNU
General Public License (GNU GPL) as published by the Free Software
Foundation, either version 3 of the License, or (at your option)
any later version. The code is distributed WITHOUT ANY WARRANTY;
without even the implied warranty of MERCHANTABILITY or FITNESS
FOR A PARTICULAR PURPOSE. See the GNU GPL for more details.
As additional permission under GNU GPL version 3 section 7, you
may distribute non-source (e.g., minimized or compacted) forms of
that code without the copy of the GNU GPL normally required by
section 4, provided you include this license notice and a URL
through which recipients can access the Corresponding Source.
@licend The above is the entire license notice
for the JavaScript code in this tag.
*/
<!--/*--><![CDATA[/*><!--*/
function CodeHighlightOn(elem, id)
{
var target = document.getElementById(id);
if(null != target) {
elem.cacheClassElem = elem.className;
elem.cacheClassTarget = target.className;
target.className = "code-highlighted";
elem.className = "code-highlighted";
}
}
function CodeHighlightOff(elem, id)
{
var target = document.getElementById(id);
if(elem.cacheClassElem)
elem.className = elem.cacheClassElem;
if(elem.cacheClassTarget)
target.className = elem.cacheClassTarget;
}
/*]]>*///-->
</script>
</head>
<body>
<div id="org-div-home-and-up">
<a accesskey="h" href=""> UP </a>
|
<a accesskey="H" href="index.html"> HOME </a>
</div><div id="content">
<h1 class="title">Motivation</h1>
</td>
<td>
<img src="trexio_logo.png" alt="TREXIO logo"
align="left" width="200" vspace="20" hspace="20" />
</td></tr>
</table>
<p>
Quantum chemistry relies on quantum mechanics to explain and predict
the properties and behaviors of atoms, molecules, and materials.
Although density functional theory (DFT) is one of the most widely
used approaches thanks to its excellent ratio between computational
cost and accuracy, another important tool is wave function theory
(WFT), which describes the behavior of a quantum system in terms of
its wave function.
In order to perform WFT calculations, it is necessary to manipulate a
large number of parameters, such as the expansion coefficients of the
wave function and the matrix elements of the Hamiltonian operator.
These parameters can be numerous and difficult to handle, making it
important to have a robust and efficient method for storing and
accessing them.
</p>
<p>
Reproducible research remains a challenging topic, despite recent
advances such as the introduction of the FAIR (findable, accessible,
interoperable, reusable) data principles. A key
aspect of reproducibility is software interoperability, which refers
to the ability of different programs to work together and exchange
information, allowing different systems to communicate and exchange
data in order to function as a cohesive whole.
Interoperable software is prevalent nowadays and is a key component of
the Unix philosophy. In Unix shells, the most
straightforward application of software interoperability is made
through the use of the <i>pipe</i> operator, where the output of a
program is the input of another program.
Similarly, shell scripts are created through the composition of
smaller programs, exchanging data through files or pipes.
</p>
<p>
A major challenge of reproducible research is the unified input/output
(I/O) of data within a particular research domain. The Unix
philosophy recommends the use of text files because they are
architecture-independent, readable in any language, and can be read as
a stream, which is useful for making programs communicate over a
network.
However, storing data in a text format can result in larger file sizes
and conversion from ASCII to binary format can be computationally
expensive for large data sets. To address this concern,
domain-specific binary formats have been developed, such as the Joint
Photographic Experts Group (JPEG) format for digital images
and the Moving Picture Experts Group (MPEG) format for videos.
These binary formats are utilized through a standardized application
programming interface (API).
</p>
<p>
In the field of wave function theory such a standard format and API is
still lacking, and the purpose of the TREXIO library is to fill this gap.
</p>
</div>
<div id="postamble" class="status">
<p class="author">Author: TREX-CoE</p>
<p class="date">Created: 2023-02-17 Fri 16:43</p>
<p class="validation"><a href="http://validator.w3.org/check?uri=referer">Validate</a></p>
</div>
</body>
</html>

60
intro.org Normal file
View File

@ -0,0 +1,60 @@
#+TITLE: Motivation
#+STARTUP: latexpreview
#+SETUPFILE: ./theme.setup
#+BEGIN_EXPORT html
</td>
<td>
<img src="trexio_logo.png" alt="TREXIO logo"
align="left" width="200" vspace="20" hspace="20" />
</td></tr>
</table>
#+END_EXPORT
Quantum chemistry relies on quantum mechanics to explain and predict
the properties and behaviors of atoms, molecules, and materials.
Although density functional theory (DFT) is one of the most widely
used approaches thanks to its excellent ratio between computational
cost and accuracy, another important tool is wave function theory
(WFT), which describes the behavior of a quantum system in terms of
its wave function.
In order to perform WFT calculations, it is necessary to manipulate a
large number of parameters, such as the expansion coefficients of the
wave function and the matrix elements of the Hamiltonian operator.
These parameters can be numerous and difficult to handle, making it
important to have a robust and efficient method for storing and
accessing them.
Reproducible research remains a challenging topic, despite recent
advances such as the introduction of the FAIR (findable, accessible,
interoperable, reusable) data principles. A key
aspect of reproducibility is software interoperability, which refers
to the ability of different programs to work together and exchange
information, allowing different systems to communicate and exchange
data in order to function as a cohesive whole.
Interoperable software is prevalent nowadays and is a key component of
the Unix philosophy. In Unix shells, the most
straightforward application of software interoperability is made
through the use of the /pipe/ operator, where the output of a
program is the input of another program.
Similarly, shell scripts are created through the composition of
smaller programs, exchanging data through files or pipes.
A major challenge of reproducible research is the unified input/output
(I/O) of data within a particular research domain. The Unix
philosophy recommends the use of text files because they are
architecture-independent, readable in any language, and can be read as
a stream, which is useful for making programs communicate over a
network.
However, storing data in a text format can result in larger file sizes
and conversion from ASCII to binary format can be computationally
expensive for large data sets. To address this concern,
domain-specific binary formats have been developed, such as the Joint
Photographic Experts Group (JPEG) format for digital images
and the Moving Picture Experts Group (MPEG) format for videos.
These binary formats are utilized through a standardized application
programming interface (API).
In the field of wave function theory such a standard format and API is
still lacking, and the purpose of the TREXIO library is to fill this gap.

761
lib.html Normal file
View File

@ -0,0 +1,761 @@
<?xml version="1.0" encoding="utf-8"?>
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Strict//EN"
"http://www.w3.org/TR/xhtml1/DTD/xhtml1-strict.dtd">
<html xmlns="http://www.w3.org/1999/xhtml" lang="en" xml:lang="en">
<head>
<!-- 2023-02-17 Fri 16:43 -->
<meta http-equiv="Content-Type" content="text/html;charset=utf-8" />
<meta name="viewport" content="width=device-width, initial-scale=1" />
<title>The TREXIO library</title>
<meta name="generator" content="Org mode" />
<meta name="author" content="TREX-CoE" />
<style type="text/css">
<!--/*--><![CDATA[/*><!--*/
.title { text-align: center;
margin-bottom: .2em; }
.subtitle { text-align: center;
font-size: medium;
font-weight: bold;
margin-top:0; }
.todo { font-family: monospace; color: red; }
.done { font-family: monospace; color: green; }
.priority { font-family: monospace; color: orange; }
.tag { background-color: #eee; font-family: monospace;
padding: 2px; font-size: 80%; font-weight: normal; }
.timestamp { color: #bebebe; }
.timestamp-kwd { color: #5f9ea0; }
.org-right { margin-left: auto; margin-right: 0px; text-align: right; }
.org-left { margin-left: 0px; margin-right: auto; text-align: left; }
.org-center { margin-left: auto; margin-right: auto; text-align: center; }
.underline { text-decoration: underline; }
#postamble p, #preamble p { font-size: 90%; margin: .2em; }
p.verse { margin-left: 3%; }
pre {
border: 1px solid #ccc;
box-shadow: 3px 3px 3px #eee;
padding: 8pt;
font-family: monospace;
overflow: auto;
margin: 1.2em;
}
pre.src {
position: relative;
overflow: visible;
padding-top: 1.2em;
}
pre.src:before {
display: none;
position: absolute;
background-color: white;
top: -10px;
right: 10px;
padding: 3px;
border: 1px solid black;
}
pre.src:hover:before { display: inline;}
/* Languages per Org manual */
pre.src-asymptote:before { content: 'Asymptote'; }
pre.src-awk:before { content: 'Awk'; }
pre.src-C:before { content: 'C'; }
/* pre.src-C++ doesn't work in CSS */
pre.src-clojure:before { content: 'Clojure'; }
pre.src-css:before { content: 'CSS'; }
pre.src-D:before { content: 'D'; }
pre.src-ditaa:before { content: 'ditaa'; }
pre.src-dot:before { content: 'Graphviz'; }
pre.src-calc:before { content: 'Emacs Calc'; }
pre.src-emacs-lisp:before { content: 'Emacs Lisp'; }
pre.src-fortran:before { content: 'Fortran'; }
pre.src-gnuplot:before { content: 'gnuplot'; }
pre.src-haskell:before { content: 'Haskell'; }
pre.src-hledger:before { content: 'hledger'; }
pre.src-java:before { content: 'Java'; }
pre.src-js:before { content: 'Javascript'; }
pre.src-latex:before { content: 'LaTeX'; }
pre.src-ledger:before { content: 'Ledger'; }
pre.src-lisp:before { content: 'Lisp'; }
pre.src-lilypond:before { content: 'Lilypond'; }
pre.src-lua:before { content: 'Lua'; }
pre.src-matlab:before { content: 'MATLAB'; }
pre.src-mscgen:before { content: 'Mscgen'; }
pre.src-ocaml:before { content: 'Objective Caml'; }
pre.src-octave:before { content: 'Octave'; }
pre.src-org:before { content: 'Org mode'; }
pre.src-oz:before { content: 'OZ'; }
pre.src-plantuml:before { content: 'Plantuml'; }
pre.src-processing:before { content: 'Processing.js'; }
pre.src-python:before { content: 'Python'; }
pre.src-R:before { content: 'R'; }
pre.src-ruby:before { content: 'Ruby'; }
pre.src-sass:before { content: 'Sass'; }
pre.src-scheme:before { content: 'Scheme'; }
pre.src-screen:before { content: 'Gnu Screen'; }
pre.src-sed:before { content: 'Sed'; }
pre.src-sh:before { content: 'shell'; }
pre.src-sql:before { content: 'SQL'; }
pre.src-sqlite:before { content: 'SQLite'; }
/* additional languages in org.el's org-babel-load-languages alist */
pre.src-forth:before { content: 'Forth'; }
pre.src-io:before { content: 'IO'; }
pre.src-J:before { content: 'J'; }
pre.src-makefile:before { content: 'Makefile'; }
pre.src-maxima:before { content: 'Maxima'; }
pre.src-perl:before { content: 'Perl'; }
pre.src-picolisp:before { content: 'Pico Lisp'; }
pre.src-scala:before { content: 'Scala'; }
pre.src-shell:before { content: 'Shell Script'; }
pre.src-ebnf2ps:before { content: 'ebfn2ps'; }
/* additional language identifiers per "defun org-babel-execute"
in ob-*.el */
pre.src-cpp:before { content: 'C++'; }
pre.src-abc:before { content: 'ABC'; }
pre.src-coq:before { content: 'Coq'; }
pre.src-groovy:before { content: 'Groovy'; }
/* additional language identifiers from org-babel-shell-names in
ob-shell.el: ob-shell is the only babel language using a lambda to put
the execution function name together. */
pre.src-bash:before { content: 'bash'; }
pre.src-csh:before { content: 'csh'; }
pre.src-ash:before { content: 'ash'; }
pre.src-dash:before { content: 'dash'; }
pre.src-ksh:before { content: 'ksh'; }
pre.src-mksh:before { content: 'mksh'; }
pre.src-posh:before { content: 'posh'; }
/* Additional Emacs modes also supported by the LaTeX listings package */
pre.src-ada:before { content: 'Ada'; }
pre.src-asm:before { content: 'Assembler'; }
pre.src-caml:before { content: 'Caml'; }
pre.src-delphi:before { content: 'Delphi'; }
pre.src-html:before { content: 'HTML'; }
pre.src-idl:before { content: 'IDL'; }
pre.src-mercury:before { content: 'Mercury'; }
pre.src-metapost:before { content: 'MetaPost'; }
pre.src-modula-2:before { content: 'Modula-2'; }
pre.src-pascal:before { content: 'Pascal'; }
pre.src-ps:before { content: 'PostScript'; }
pre.src-prolog:before { content: 'Prolog'; }
pre.src-simula:before { content: 'Simula'; }
pre.src-tcl:before { content: 'tcl'; }
pre.src-tex:before { content: 'TeX'; }
pre.src-plain-tex:before { content: 'Plain TeX'; }
pre.src-verilog:before { content: 'Verilog'; }
pre.src-vhdl:before { content: 'VHDL'; }
pre.src-xml:before { content: 'XML'; }
pre.src-nxml:before { content: 'XML'; }
/* add a generic configuration mode; LaTeX export needs an additional
(add-to-list 'org-latex-listings-langs '(conf " ")) in .emacs */
pre.src-conf:before { content: 'Configuration File'; }
table { border-collapse:collapse; }
caption.t-above { caption-side: top; }
caption.t-bottom { caption-side: bottom; }
td, th { vertical-align:top; }
th.org-right { text-align: center; }
th.org-left { text-align: center; }
th.org-center { text-align: center; }
td.org-right { text-align: right; }
td.org-left { text-align: left; }
td.org-center { text-align: center; }
dt { font-weight: bold; }
.footpara { display: inline; }
.footdef { margin-bottom: 1em; }
.figure { padding: 1em; }
.figure p { text-align: center; }
.equation-container {
display: table;
text-align: center;
width: 100%;
}
.equation {
vertical-align: middle;
}
.equation-label {
display: table-cell;
text-align: right;
vertical-align: middle;
}
.inlinetask {
padding: 10px;
border: 2px solid gray;
margin: 10px;
background: #ffffcc;
}
#org-div-home-and-up
{ text-align: right; font-size: 70%; white-space: nowrap; }
textarea { overflow-x: auto; }
.linenr { font-size: smaller }
.code-highlighted { background-color: #ffff00; }
.org-info-js_info-navigation { border-style: none; }
#org-info-js_console-label
{ font-size: 10px; font-weight: bold; white-space: nowrap; }
.org-info-js_search-highlight
{ background-color: #ffff00; color: #000000; font-weight: bold; }
.org-svg { width: 90%; }
/*]]>*/-->
</style>
<link rel="stylesheet" title="Standard" href="trexio.css" type="text/css" />
<script type="text/javascript" src="org-info.js">
/**
*
* @source: org-info.js
*
* @licstart The following is the entire license notice for the
* JavaScript code in org-info.js.
*
* Copyright (C) 2012-2020 Free Software Foundation, Inc.
*
*
* The JavaScript code in this tag is free software: you can
* redistribute it and/or modify it under the terms of the GNU
* General Public License (GNU GPL) as published by the Free Software
* Foundation, either version 3 of the License, or (at your option)
* any later version. The code is distributed WITHOUT ANY WARRANTY;
* without even the implied warranty of MERCHANTABILITY or FITNESS
* FOR A PARTICULAR PURPOSE. See the GNU GPL for more details.
*
* As additional permission under GNU GPL version 3 section 7, you
* may distribute non-source (e.g., minimized or compacted) forms of
* that code without the copy of the GNU GPL normally required by
* section 4, provided you include this license notice and a URL
* through which recipients can access the Corresponding Source.
*
* @licend The above is the entire license notice
* for the JavaScript code in org-info.js.
*
*/
</script>
<script type="text/javascript">
/*
@licstart The following is the entire license notice for the
JavaScript code in this tag.
Copyright (C) 2012-2020 Free Software Foundation, Inc.
The JavaScript code in this tag is free software: you can
redistribute it and/or modify it under the terms of the GNU
General Public License (GNU GPL) as published by the Free Software
Foundation, either version 3 of the License, or (at your option)
any later version. The code is distributed WITHOUT ANY WARRANTY;
without even the implied warranty of MERCHANTABILITY or FITNESS
FOR A PARTICULAR PURPOSE. See the GNU GPL for more details.
As additional permission under GNU GPL version 3 section 7, you
may distribute non-source (e.g., minimized or compacted) forms of
that code without the copy of the GNU GPL normally required by
section 4, provided you include this license notice and a URL
through which recipients can access the Corresponding Source.
@licend The above is the entire license notice
for the JavaScript code in this tag.
*/
<!--/*--><![CDATA[/*><!--*/
org_html_manager.set("TOC_DEPTH", "4");
org_html_manager.set("LINK_HOME", "index.html");
org_html_manager.set("LINK_UP", "");
org_html_manager.set("LOCAL_TOC", "1");
org_html_manager.set("VIEW_BUTTONS", "0");
org_html_manager.set("MOUSE_HINT", "underline");
org_html_manager.set("FIXED_TOC", "0");
org_html_manager.set("TOC", "0");
org_html_manager.set("VIEW", "info");
org_html_manager.setup(); // activate after the parameters are set
/*]]>*///-->
</script>
<script type="text/javascript">
/*
@licstart The following is the entire license notice for the
JavaScript code in this tag.
Copyright (C) 2012-2020 Free Software Foundation, Inc.
The JavaScript code in this tag is free software: you can
redistribute it and/or modify it under the terms of the GNU
General Public License (GNU GPL) as published by the Free Software
Foundation, either version 3 of the License, or (at your option)
any later version. The code is distributed WITHOUT ANY WARRANTY;
without even the implied warranty of MERCHANTABILITY or FITNESS
FOR A PARTICULAR PURPOSE. See the GNU GPL for more details.
As additional permission under GNU GPL version 3 section 7, you
may distribute non-source (e.g., minimized or compacted) forms of
that code without the copy of the GNU GPL normally required by
section 4, provided you include this license notice and a URL
through which recipients can access the Corresponding Source.
@licend The above is the entire license notice
for the JavaScript code in this tag.
*/
<!--/*--><![CDATA[/*><!--*/
function CodeHighlightOn(elem, id)
{
var target = document.getElementById(id);
if(null != target) {
elem.cacheClassElem = elem.className;
elem.cacheClassTarget = target.className;
target.className = "code-highlighted";
elem.className = "code-highlighted";
}
}
function CodeHighlightOff(elem, id)
{
var target = document.getElementById(id);
if(elem.cacheClassElem)
elem.className = elem.cacheClassElem;
if(elem.cacheClassTarget)
target.className = elem.cacheClassTarget;
}
/*]]>*///-->
</script>
<script type="text/x-mathjax-config">
MathJax.Hub.Config({
displayAlign: "center",
displayIndent: "0em",
"HTML-CSS": { scale: 100,
linebreaks: { automatic: "false" },
webFont: "TeX"
},
SVG: {scale: 100,
linebreaks: { automatic: "false" },
font: "TeX"},
NativeMML: {scale: 100},
TeX: { equationNumbers: {autoNumber: "AMS"},
MultLineWidth: "85%",
TagSide: "right",
TagIndent: ".8em"
}
});
</script>
<script type="text/javascript"
src="https://cdnjs.cloudflare.com/ajax/libs/mathjax/2.7.0/MathJax.js?config=TeX-AMS_HTML"></script>
</head>
<body>
<div id="org-div-home-and-up">
<a accesskey="h" href=""> UP </a>
|
<a accesskey="H" href="index.html"> HOME </a>
</div><div id="content">
<h1 class="title">The TREXIO library</h1>
<div id="table-of-contents">
<h2>Table of Contents</h2>
<div id="text-table-of-contents">
<ul>
<li><a href="#org73c1e31">1. Format specification</a>
<ul>
<li><a href="#org900892a">1.1. Organization of the data</a></li>
<li><a href="#org09f1f96">1.2. Data types</a></li>
</ul>
</li>
<li><a href="#orge5bfed7">2. The TREXIO library</a>
<ul>
<li><a href="#org9a83e99">2.1. The front-end</a></li>
<li><a href="#org9db6970">2.2. The back-end</a></li>
<li><a href="#org9987497">2.3. Supported languages</a></li>
<li><a href="#org7d0bd5a">2.4. Source code generation and documentation</a></li>
<li><a href="#org0dcad23">2.5. Availability</a></li>
</ul>
</li>
</ul>
</div>
</div>
<div id="outline-container-org73c1e31" class="outline-2">
<h2 id="org73c1e31"><span class="section-number-2">1</span> Format specification</h2>
<div class="outline-text-2" id="text-1">
</td>
<td>
<img src="trex_specs.png" alt="TREX in a library"
align="right" width="300" vspace="20" hspace="20" />
</td></tr>
</table>
<p>
The TREXIO format is designed to store all the necessary information
to represent a wave function.
One notable feature of TREXIO is that it is self-contained, meaning
that all the parameters needed to recreate the wave function are
explicitly stored within the file, eliminating the need for external
databases. For example, instead of storing the name of a basis set
(such as cc-pVDZ), the actual basis set parameters used in the
calculation are stored.
</p>
</div>
<div id="outline-container-org900892a" class="outline-3">
<h3 id="org900892a"><span class="section-number-3">1.1</span> Organization of the data</h3>
<div class="outline-text-3" id="text-1-1">
<p>
The data in TREXIO are organized into <b>groups</b>, each containing
multiple <b>attributes</b> defined by their <b>type</b> and <b>dimensions</b>. Each
attribute within a group corresponds to a single scalar or array
variable in a code. In what follows, the notation
<code>&lt;group&gt;.&lt;attribute&gt;</code> will be used to identify an attribute within a
group. For example, <code>nucleus.charge</code> refers to the
<code>charge</code> attribute in the <code>nucleus</code> group. It is an array of type
<code>float</code> with dimensions <code>nucleus.num</code>, the attribute describing the
number of nuclei.
</p>
</div>
</div>
<div id="outline-container-org09f1f96" class="outline-3">
<h3 id="org09f1f96"><span class="section-number-3">1.2</span> Data types</h3>
<div class="outline-text-3" id="text-1-2">
<p>
So that TREXIO can be used in any language, we use a limited number
of data types. The main data types are <code>int</code> for integers,
<code>float</code> for floating-point values, and <code>str</code> for
character strings. For complex numbers, their real and imaginary
parts are stored as <code>float</code>. To minimize the risk of integer
overflow and accuracy loss, numerical data types are stored using
64-bit representations by default. However, in specific cases where
integers are bounded (such as orbital indices in four-index
integrals), the smallest possible representation is used to reduce the
file size. The API handles any necessary type conversions.
</p>
<p>
There are also two types derived from <code>int</code>: <code>dim</code> and <code>index</code>.
<code>dim</code> is used for dimensioning variables, which are positive integers
used to specify the dimensions of an array. In the previous example,
<code>nucleus.num</code> is a dimensioning variable that specifies the
dimensions of the <code>nucleus.charge</code> array. <code>index</code> is used for
integers that correspond to array indices, because some languages
(such as C or Python) use zero-based indexing, while others (such as
Fortran) use one-based indexing. For convenience, values of the
<code>index</code> type are shifted by one when TREXIO is used in one-based
languages to be consistent with the semantics of the language.
You may also encounter some <code>dim readonly</code> variables. It means
that the value is automatically computed and written by the TREXIO
library, thus it is read-only and cannot be (over)written by the
user.
</p>
<p>
Arrays can be stored in either dense or sparse formats. If the
sparse format is selected, the data is stored in coordinate format.
For example, the element <code>A(i,j,k,l)</code> is stored as a quadruplet of
integers \((i,j,k,l)\) along with the corresponding value. Typically,
two-dimensional arrays are stored as dense arrays, while arrays with
higher dimensions are stored in sparse format.
For sparse data structures the data can be too large to fit in memory
and the data needs to be fetched using multiple function calls to
perform I/O on buffers. For more information on how to read/write
sparse data structures, see the <a href="./examples.html">examples</a>.
</p>
<p>
For the Configuration Interaction (CI) and Configuration State
Function (CSF) groups, the <code>buffered</code> data type is introduced, which
allows similar incremental I/O as for <code>sparse</code> data but without the
need to write indices of the sparse values.
</p>
<p>
For determinant lists (integer bit fields), the <code>special</code> attribute
is present in the type. This means that the source code is not
produced by the generator, but hand-written.
</p>
<p>
Some data may be complex. In that case, the real part should be stored
in the variable, and the imaginary part will be stored in the variable
with the same name suffixed by <code>_im</code>.
</p>
</div>
</div>
</div>
<div id="outline-container-orge5bfed7" class="outline-2">
<h2 id="orge5bfed7"><span class="section-number-2">2</span> The TREXIO library</h2>
<div class="outline-text-2" id="text-2">
</td>
<td>
<img src="trex_lib.png" alt="TREX in a library"
align="left" width="300" vspace="20" hspace="20" />
</td></tr>
</table>
<p>
The TREXIO library is written is the C language, and is licensed under
the open-source 3-clause BSD license to allow for use in all types of
quantum chemistry software, whether commercial or not.
</p>
<p>
The design of the library is divided into two main sections: the
front-end and the back-end. The front-end serves as the interface
between users and the library, while the back-end acts as the
interface between the library and the physical storage.
</p>
</div>
<div id="outline-container-org9a83e99" class="outline-3">
<h3 id="org9a83e99"><span class="section-number-3">2.1</span> The front-end</h3>
<div class="outline-text-3" id="text-2-1">
<p>
By using the TREXIO library, users can store and extract data in a
consistent and organized manner. The library provides a user-friendly
API, including functions for reading, writing, and checking for the
existence of data. The functions follow the pattern
<code>trexio_[has|read|write]_&lt;group&gt;_&lt;attribute&gt;</code>, where the
group and attribute specify the particular data being accessed. It
also includes an error handling mechanism, in which each function call
returns an exit code of type <code>trexio_exit_code</code>, explaining
the type of error.
This can be used to catch exceptions and improve debugging in the
upstream user application.
</p>
<p>
To ensure the consistency of the data, the attributes can only be
written if all the other attributes on which they explicitly depend
have been written. For example, as the <code>nucleus.coord</code> array is
dimensioned by the number of nuclei <code>nucleus.num</code>, the <code>nucleus.coord</code>
attribute can only be written after <code>nucleus.num</code>. However, the
library is not aware of non-explicit dependencies, such as the
relation between the electron repulsion integrals (ERIs) and MO
coefficients. A complete control of the consistency of the data is
therefore impossible, so the attributes were chosen to be by default
<i>immutable</i>. By only allowing data to be written only once, the
risk of modifying data in a way that creates inconsistencies is
reduced. For example, if the ERIs have already been written, it would
be inconsistent to later modify the MO coefficients. To allow for
flexibility, the library also allows for the use of an <i>unsafe</i>
mode, in which data can be overwritten. However, this mode carries
the risk of producing inconsistent files, and the <code>metadata</code> group's
<code>unsafe</code> attribute is set to <code>1</code> to indicate that the file has
potentially been modified in a dangerous way. This attribute can be
manually reset to <code>0</code> if the user is confident that the modifications
made are safe.
</p>
</div>
</div>
<div id="outline-container-org9db6970" class="outline-3">
<h3 id="org9db6970"><span class="section-number-3">2.2</span> The back-end</h3>
<div class="outline-text-3" id="text-2-2">
<p>
At present, TREXIO supports two back-ends: one relying only on the
C standard library to produce plain text files (the so-called <i>text</i>
back-end), and one relying on the HDF5 library.
</p>
<p>
With the text back-end, the TREXIO "file" is a directory containing
multiple text files, one for each group. This back end is intended
to be used in development environments, as it gives access to the
user to the standard tools such as <code>diff</code> and <code>grep</code>.
In addition, text files are better adapted than binary files for
version control systems such as Git, so this format can be also
used for storing reference data for unit tests.
</p>
<p>
HDF5 is a binary file format and library for storing and managing
large amounts of data in a hierarchical structure. It allows users
to manipulate data in a way similar to how files and directories
are manipulated within the file system. The HDF5 library provides
optimal performance through its memory mapping mechanism and
supports advanced features such as serial and parallel I/O,
chunking, and compression filters. However, HDF5 files are in
binary format, which requires additional tools such as <code>h5dump</code> to
view them in a human-readable format. It is widely used in
scientific and engineering applications, and is known for its high
performance and ability to handle large data sets efficiently.
</p>
<p>
The TREXIO HDF5 back-end is the recommended choice for production
environments, as it provides high I/O performance. Furthermore,
all data is stored in a single file, making it especially suitable
for parallel file systems like Lustre. These file systems are
optimized for large, sequential I/O operations and are not
well-suited for small, random I/O operations. When multiple small
files are used, the file system may become overwhelmed with
metadata operations like creating, deleting, or modifying files,
which can adversely affect performance.
</p>
<p>
In a benchmarking program designed to compare the two back-ends of
the library, the HDF5 back-end was found to be significantly faster
than the text back-end. The program wrote a wave function made up
of 100 million Slater determinants and measured the time taken to
write the Slater determinants and CI coefficients. The HDF5
back-end achieved a speed of \(10.4\times10^6\) Slater determinants
per second and a data transfer rate of 406 MB/s, while the text
back-end had a speed of \(1.1\times10^6\) determinants per second and
a transfer rate of 69 MB/s. These results were obtained on a DELL
960 GB mix-use solid-state drive (SSD). The HDF5 back-end was able
to achieve a performance level close to the peak performance of the
SSD, while the text back-end's performance was limited by the speed
of the CPU for performing binary to ASCII conversions.
</p>
<p>
In addition to the HDF5 and text back-ends, it is also possible to
introduce new back-ends to the library. For example, a back-end
could be created to support object storage systems, such as those
used in cloud-based applications or for archiving in open data
repositories.
</p>
</div>
</div>
<div id="outline-container-org9987497" class="outline-3">
<h3 id="org9987497"><span class="section-number-3">2.3</span> Supported languages</h3>
<div class="outline-text-3" id="text-2-3">
<p>
One of the main benefits of using C as the interface for a library is
that it is easy to use from other programming languages. Many
programming languages, such as Python or Julia, provide built-in
support for calling C functions, which means that it is relatively
straightforward to write a wrapper that allows a library written in C
to be called from another language.
In general, libraries with a C interface are the easiest to use from
other programming languages, because C is widely supported and has a
simple, stable application binary interface (ABI). Other languages,
such as Fortran and C++, may have more complex ABIs and may
require more work to interface with them.
</p>
<p>
TREXIO has been employed in codes developed in various programming
languages, including C, C++, Fortran, Python, OCaml, and Julia. While
Julia is designed to enable the use of C functions without the need
for additional manual interfacing, the TREXIO C header file was
automatically integrated into Julia programs using the
<code>CBindings.jl</code> package.
In contrast, specific bindings have been provided for Fortran, Python,
and OCaml to simplify the user experience.
</p>
<p>
In particular, the binding for Fortran is not distributed as multiple
compiled Fortran module files (<code>.mod</code>), but instead as a single
Fortran source file (<code>.F90</code>). The distribution of the source file
instead of the compiled module has multiple benefits. It ensures that
the TREXIO module is always compiled with the same compiler as the
client code, avoiding the compatibility problem of <code>.mod</code> files
between different compiler versions and vendors. The single-file
model requires very little changes in the build system of the user's
codes, and it facilitates the search for the interface of a particular
function. In addition, advanced text editors can parse the TREXIO
interface to propose interactive auto-completion of the TREXIO
function names to the developers.
</p>
<p>
Finally, the Python module, partly generated with SWIG and fully
compatible with NumPy, allows Python users to interact with the
library in a more intuitive and user-friendly way. Using the Python
interface is likely the easiest way to begin using TREXIO and
understanding its features. In order to help users get started with
TREXIO and understand its functionality, tutorials in Jupyter
notebooks are available on GitHub
(<a href="https://github.com/TREX-CoE/trexio-tutorials">https://github.com/TREX-CoE/trexio-tutorials</a>), and can be executed
via the Binder platform.
</p>
</div>
</div>
<div id="outline-container-org7d0bd5a" class="outline-3">
<h3 id="org7d0bd5a"><span class="section-number-3">2.4</span> Source code generation and documentation</h3>
<div class="outline-text-3" id="text-2-4">
<p>
Source code generation is a valuable technique that can significantly
improve the efficiency and consistency of software development. By
using templates to generate code automatically, developers can avoid
manual coding and reduce the risk of errors or inconsistencies. This
approach is particularly useful when a large number of functions
follow similar patterns, as in the case of the TREXIO library, where
functions are named according to the pattern
<code>trexio_[has|read|write]_&lt;group&gt;_&lt;attribute&gt;</code>.
By generating these functions from the format specification using
templates, the developers can ensure that the resulting code follows a
consistent structure and is free from errors or inconsistencies.
</p>
<p>
The description of the format is written in a text file in the Org
format. Org is a structured plain text format, containing information
expressed in a lightweight markup language similar to the popular
Markdown language. While Org was introduced as a mode of the GNU
Emacs text editor, its basic functionalities have been implemented in
most text editors such as Vim, Atom or VS Code.
</p>
<p>
There are multiple benefits in using the Org format. The first
benefit is that the Org syntax is easy to learn and allows for the
insertion of equations in \LaTeX{} syntax. Additionally, Org files
can be easily converted to HyperText Markup Language (HTML) or
Portable Document Format (PDF) for generating documentation. The
second benefit is that GNU Emacs is a programmable text editor and
code blocks in Org files can be executed interactively, similar to
Jupyter notebooks. These code blocks can also manipulate data defined
in tables and this feature is used to automatically transform tables
describing groups and attributes in the documentation into a
JavaScript Object Notation (JSON) file.
This JSON file is then used by a Python script to generate the needed
functions in C language, as well as header files and some files
required for the Fortran, Python, and OCaml interfaces.
</p>
<p>
With this approach, contributions to the development of the TREXIO
library can be made simply by adding new tables to the Org file, which
can be submitted as <i>pull requests</i> on the project's GitHub
repository (<a href="https://github.com/trex-coe/trexio">https://github.com/trex-coe/trexio</a>). Overall, this
process allows for a more efficient and consistent development process
and enables contributions from a wider range of individuals,
regardless of their programming skills.
</p>
</div>
</div>
<div id="outline-container-org0dcad23" class="outline-3">
<h3 id="org0dcad23"><span class="section-number-3">2.5</span> Availability</h3>
<div class="outline-text-3" id="text-2-5">
<p>
The TREXIO library is designed to be portable and easy to install
on a wide range of systems. It follows the C99 standard to ensure
compatibility with older systems, and can be configured with either
the GNU Autotools or the CMake build systems. The only external
dependency is the HDF5 library, which is widely available on HPC
platforms and as packages on major Linux distributions. Note that
it is possible to disable the HDF5 back-end at configuration time,
allowing TREXIO to operate only with the text back-end and have
zero external dependencies. This can be useful for users who may
not be able to install HDF5 on certain systems.
</p>
<p>
TREXIO is distributed as a tarball containing the source code,
generated code, documentation, and Fortran interface. It is also
available as a binary <code>.deb</code> package for Debian-based Linux
distributions and as packages for Guix, Spack and Conda. The Python
module can be found in the PyPI repository, the OCaml binding is
available in the official OPAM repository, and the <code>.deb</code> packages
are available in Ubuntu 23.04.
</p>
</div>
</div>
</div>
</div>
<div id="postamble" class="status">
<p class="author">Author: TREX-CoE</p>
<p class="date">Created: 2023-02-17 Fri 16:43</p>
<p class="validation"><a href="http://validator.w3.org/check?uri=referer">Validate</a></p>
</div>
</body>
</html>

311
lib.org Normal file
View File

@ -0,0 +1,311 @@
#+TITLE: The TREXIO library
#+STARTUP: latexpreview
#+SETUPFILE: ./theme.setup
* Format specification
#+BEGIN_EXPORT html
</td>
<td>
<img src="trex_specs.png" alt="TREX in a library"
align="right" width="300" vspace="20" hspace="20" />
</td></tr>
</table>
#+END_EXPORT
#
The TREXIO format is designed to store all the necessary information
to represent a wave function.
One notable feature of TREXIO is that it is self-contained, meaning
that all the parameters needed to recreate the wave function are
explicitly stored within the file, eliminating the need for external
databases. For example, instead of storing the name of a basis set
(such as cc-pVDZ), the actual basis set parameters used in the
calculation are stored.
** Organization of the data
The data in TREXIO are organized into *groups*, each containing
multiple *attributes* defined by their *type* and *dimensions*. Each
attribute within a group corresponds to a single scalar or array
variable in a code. In what follows, the notation
~<group>.<attribute>~ will be used to identify an attribute within a
group. For example, ~nucleus.charge~ refers to the
~charge~ attribute in the ~nucleus~ group. It is an array of type
~float~ with dimensions ~nucleus.num~, the attribute describing the
number of nuclei.
** Data types
So that TREXIO can be used in any language, we use a limited number
of data types. The main data types are ~int~ for integers,
~float~ for floating-point values, and ~str~ for
character strings. For complex numbers, their real and imaginary
parts are stored as ~float~. To minimize the risk of integer
overflow and accuracy loss, numerical data types are stored using
64-bit representations by default. However, in specific cases where
integers are bounded (such as orbital indices in four-index
integrals), the smallest possible representation is used to reduce the
file size. The API handles any necessary type conversions.
There are also two types derived from ~int~: ~dim~ and ~index~.
~dim~ is used for dimensioning variables, which are positive integers
used to specify the dimensions of an array. In the previous example,
~nucleus.num~ is a dimensioning variable that specifies the
dimensions of the ~nucleus.charge~ array. ~index~ is used for
integers that correspond to array indices, because some languages
(such as C or Python) use zero-based indexing, while others (such as
Fortran) use one-based indexing. For convenience, values of the
~index~ type are shifted by one when TREXIO is used in one-based
languages to be consistent with the semantics of the language.
You may also encounter some ~dim readonly~ variables. It means
that the value is automatically computed and written by the TREXIO
library, thus it is read-only and cannot be (over)written by the
user.
Arrays can be stored in either dense or sparse formats. If the
sparse format is selected, the data is stored in coordinate format.
For example, the element ~A(i,j,k,l)~ is stored as a quadruplet of
integers $(i,j,k,l)$ along with the corresponding value. Typically,
two-dimensional arrays are stored as dense arrays, while arrays with
higher dimensions are stored in sparse format.
For sparse data structures the data can be too large to fit in memory
and the data needs to be fetched using multiple function calls to
perform I/O on buffers. For more information on how to read/write
sparse data structures, see the [[./examples.html][examples]].
For the Configuration Interaction (CI) and Configuration State
Function (CSF) groups, the ~buffered~ data type is introduced, which
allows similar incremental I/O as for ~sparse~ data but without the
need to write indices of the sparse values.
For determinant lists (integer bit fields), the ~special~ attribute
is present in the type. This means that the source code is not
produced by the generator, but hand-written.
Some data may be complex. In that case, the real part should be stored
in the variable, and the imaginary part will be stored in the variable
with the same name suffixed by ~_im~.
* The TREXIO library
#+BEGIN_EXPORT html
</td>
<td>
<img src="trex_lib.png" alt="TREX in a library"
align="left" width="300" vspace="20" hspace="20" />
</td></tr>
</table>
#+END_EXPORT
The TREXIO library is written is the C language, and is licensed under
the open-source 3-clause BSD license to allow for use in all types of
quantum chemistry software, whether commercial or not.
The design of the library is divided into two main sections: the
front-end and the back-end. The front-end serves as the interface
between users and the library, while the back-end acts as the
interface between the library and the physical storage.
** The front-end
By using the TREXIO library, users can store and extract data in a
consistent and organized manner. The library provides a user-friendly
API, including functions for reading, writing, and checking for the
existence of data. The functions follow the pattern
~trexio_[has|read|write]_<group>_<attribute>~, where the
group and attribute specify the particular data being accessed. It
also includes an error handling mechanism, in which each function call
returns an exit code of type ~trexio_exit_code~, explaining
the type of error.
This can be used to catch exceptions and improve debugging in the
upstream user application.
To ensure the consistency of the data, the attributes can only be
written if all the other attributes on which they explicitly depend
have been written. For example, as the ~nucleus.coord~ array is
dimensioned by the number of nuclei ~nucleus.num~, the ~nucleus.coord~
attribute can only be written after ~nucleus.num~. However, the
library is not aware of non-explicit dependencies, such as the
relation between the electron repulsion integrals (ERIs) and MO
coefficients. A complete control of the consistency of the data is
therefore impossible, so the attributes were chosen to be by default
/immutable/. By only allowing data to be written only once, the
risk of modifying data in a way that creates inconsistencies is
reduced. For example, if the ERIs have already been written, it would
be inconsistent to later modify the MO coefficients. To allow for
flexibility, the library also allows for the use of an /unsafe/
mode, in which data can be overwritten. However, this mode carries
the risk of producing inconsistent files, and the ~metadata~ group's
~unsafe~ attribute is set to ~1~ to indicate that the file has
potentially been modified in a dangerous way. This attribute can be
manually reset to ~0~ if the user is confident that the modifications
made are safe.
** The back-end
At present, TREXIO supports two back-ends: one relying only on the
C standard library to produce plain text files (the so-called /text/
back-end), and one relying on the HDF5 library.
With the text back-end, the TREXIO "file" is a directory containing
multiple text files, one for each group. This back end is intended
to be used in development environments, as it gives access to the
user to the standard tools such as ~diff~ and ~grep~.
In addition, text files are better adapted than binary files for
version control systems such as Git, so this format can be also
used for storing reference data for unit tests.
HDF5 is a binary file format and library for storing and managing
large amounts of data in a hierarchical structure. It allows users
to manipulate data in a way similar to how files and directories
are manipulated within the file system. The HDF5 library provides
optimal performance through its memory mapping mechanism and
supports advanced features such as serial and parallel I/O,
chunking, and compression filters. However, HDF5 files are in
binary format, which requires additional tools such as ~h5dump~ to
view them in a human-readable format. It is widely used in
scientific and engineering applications, and is known for its high
performance and ability to handle large data sets efficiently.
The TREXIO HDF5 back-end is the recommended choice for production
environments, as it provides high I/O performance. Furthermore,
all data is stored in a single file, making it especially suitable
for parallel file systems like Lustre. These file systems are
optimized for large, sequential I/O operations and are not
well-suited for small, random I/O operations. When multiple small
files are used, the file system may become overwhelmed with
metadata operations like creating, deleting, or modifying files,
which can adversely affect performance.
In a benchmarking program designed to compare the two back-ends of
the library, the HDF5 back-end was found to be significantly faster
than the text back-end. The program wrote a wave function made up
of 100 million Slater determinants and measured the time taken to
write the Slater determinants and CI coefficients. The HDF5
back-end achieved a speed of $10.4\times10^6$ Slater determinants
per second and a data transfer rate of 406 MB/s, while the text
back-end had a speed of $1.1\times10^6$ determinants per second and
a transfer rate of 69 MB/s. These results were obtained on a DELL
960 GB mix-use solid-state drive (SSD). The HDF5 back-end was able
to achieve a performance level close to the peak performance of the
SSD, while the text back-end's performance was limited by the speed
of the CPU for performing binary to ASCII conversions.
In addition to the HDF5 and text back-ends, it is also possible to
introduce new back-ends to the library. For example, a back-end
could be created to support object storage systems, such as those
used in cloud-based applications or for archiving in open data
repositories.
** Supported languages
One of the main benefits of using C as the interface for a library is
that it is easy to use from other programming languages. Many
programming languages, such as Python or Julia, provide built-in
support for calling C functions, which means that it is relatively
straightforward to write a wrapper that allows a library written in C
to be called from another language.
In general, libraries with a C interface are the easiest to use from
other programming languages, because C is widely supported and has a
simple, stable application binary interface (ABI). Other languages,
such as Fortran and C++, may have more complex ABIs and may
require more work to interface with them.
TREXIO has been employed in codes developed in various programming
languages, including C, C++, Fortran, Python, OCaml, and Julia. While
Julia is designed to enable the use of C functions without the need
for additional manual interfacing, the TREXIO C header file was
automatically integrated into Julia programs using the
~CBindings.jl~ package.
In contrast, specific bindings have been provided for Fortran, Python,
and OCaml to simplify the user experience.
In particular, the binding for Fortran is not distributed as multiple
compiled Fortran module files (~.mod~), but instead as a single
Fortran source file (~.F90~). The distribution of the source file
instead of the compiled module has multiple benefits. It ensures that
the TREXIO module is always compiled with the same compiler as the
client code, avoiding the compatibility problem of ~.mod~ files
between different compiler versions and vendors. The single-file
model requires very little changes in the build system of the user's
codes, and it facilitates the search for the interface of a particular
function. In addition, advanced text editors can parse the TREXIO
interface to propose interactive auto-completion of the TREXIO
function names to the developers.
Finally, the Python module, partly generated with SWIG and fully
compatible with NumPy, allows Python users to interact with the
library in a more intuitive and user-friendly way. Using the Python
interface is likely the easiest way to begin using TREXIO and
understanding its features. In order to help users get started with
TREXIO and understand its functionality, tutorials in Jupyter
notebooks are available on GitHub
(https://github.com/TREX-CoE/trexio-tutorials), and can be executed
via the Binder platform.
** Source code generation and documentation
Source code generation is a valuable technique that can significantly
improve the efficiency and consistency of software development. By
using templates to generate code automatically, developers can avoid
manual coding and reduce the risk of errors or inconsistencies. This
approach is particularly useful when a large number of functions
follow similar patterns, as in the case of the TREXIO library, where
functions are named according to the pattern
~trexio_[has|read|write]_<group>_<attribute>~.
By generating these functions from the format specification using
templates, the developers can ensure that the resulting code follows a
consistent structure and is free from errors or inconsistencies.
The description of the format is written in a text file in the Org
format. Org is a structured plain text format, containing information
expressed in a lightweight markup language similar to the popular
Markdown language. While Org was introduced as a mode of the GNU
Emacs text editor, its basic functionalities have been implemented in
most text editors such as Vim, Atom or VS Code.
There are multiple benefits in using the Org format. The first
benefit is that the Org syntax is easy to learn and allows for the
insertion of equations in \LaTeX{} syntax. Additionally, Org files
can be easily converted to HyperText Markup Language (HTML) or
Portable Document Format (PDF) for generating documentation. The
second benefit is that GNU Emacs is a programmable text editor and
code blocks in Org files can be executed interactively, similar to
Jupyter notebooks. These code blocks can also manipulate data defined
in tables and this feature is used to automatically transform tables
describing groups and attributes in the documentation into a
JavaScript Object Notation (JSON) file.
This JSON file is then used by a Python script to generate the needed
functions in C language, as well as header files and some files
required for the Fortran, Python, and OCaml interfaces.
With this approach, contributions to the development of the TREXIO
library can be made simply by adding new tables to the Org file, which
can be submitted as /pull requests/ on the project's GitHub
repository (https://github.com/trex-coe/trexio). Overall, this
process allows for a more efficient and consistent development process
and enables contributions from a wider range of individuals,
regardless of their programming skills.
** Availability
The TREXIO library is designed to be portable and easy to install
on a wide range of systems. It follows the C99 standard to ensure
compatibility with older systems, and can be configured with either
the GNU Autotools or the CMake build systems. The only external
dependency is the HDF5 library, which is widely available on HPC
platforms and as packages on major Linux distributions. Note that
it is possible to disable the HDF5 back-end at configuration time,
allowing TREXIO to operate only with the text back-end and have
zero external dependencies. This can be useful for users who may
not be able to install HDF5 on certain systems.
TREXIO is distributed as a tarball containing the source code,
generated code, documentation, and Fortran interface. It is also
available as a binary ~.deb~ package for Debian-based Linux
distributions and as packages for Guix, Spack and Conda. The Python
module can be found in the PyPI repository, the OCaml binding is
available in the official OPAM repository, and the ~.deb~ packages
are available in Ubuntu 23.04.

652
templator_front.html
View File

File diff suppressed because it is too large Load Diff

84
templator_hdf5.html
View File

@ -3,7 +3,7 @@
"http://www.w3.org/TR/xhtml1/DTD/xhtml1-strict.dtd">
<html xmlns="http://www.w3.org/1999/xhtml" lang="en" xml:lang="en">
<head>
<!-- 2023-02-16 Thu 08:31 -->
<!-- 2023-02-17 Fri 16:43 -->
<meta http-equiv="Content-Type" content="text/html;charset=utf-8" />
<meta name="viewport" content="width=device-width, initial-scale=1" />
<title>HDF5 back end</title>
@ -261,7 +261,7 @@ org_html_manager.set("LOCAL_TOC", "1");
org_html_manager.set("VIEW_BUTTONS", "0");
org_html_manager.set("MOUSE_HINT", "underline");
org_html_manager.set("FIXED_TOC", "0");
org_html_manager.set("TOC", "1");
org_html_manager.set("TOC", "0");
org_html_manager.set("VIEW", "info");
org_html_manager.setup(); // activate after the parameters are set
/*]]>*///-->
@ -324,25 +324,25 @@ for the JavaScript code in this tag.
<h2>Table of Contents</h2>
<div id="text-table-of-contents">
<ul>
<li><a href="#orgf5ffd52">1. Template for HDF5 definitions</a></li>
<li><a href="#org0eb6385">2. Template for HDF5 structures</a></li>
<li><a href="#orgd17ce03">3. Template for HDF5 init/deinit</a></li>
<li><a href="#orge31791e">4. Template for HDF5 has a group</a></li>
<li><a href="#orgf8a7e04">5. Template for HDF5 has/read/write a numerical attribute</a></li>
<li><a href="#org63fa7ef">6. Template for HDF5 has/read/write a dataset of numerical data</a></li>
<li><a href="#org51eca4f">7. Template for HDF5 has/read/write a dataset of sparse data</a></li>
<li><a href="#org4dc838b">8. Template for HDF5 has/read/write a dataset of buffered vectors</a></li>
<li><a href="#orgb8d7595">9. Template for HDF5 has/read/write a dataset of strings</a></li>
<li><a href="#org4b60a49">10. Template for HDF5 has/read/write a string attribute</a></li>
<li><a href="#org2d247a4">11. Template for HDF5 delete a group (UNSAFE mode)</a></li>
<li><a href="#org315ad20">12. Source code for the determinant part</a></li>
<li><a href="#org89fa238">13. Helper functions</a></li>
<li><a href="#org3ede3d5">1. Template for HDF5 definitions</a></li>
<li><a href="#org523d95d">2. Template for HDF5 structures</a></li>
<li><a href="#orgb88d155">3. Template for HDF5 init/deinit</a></li>
<li><a href="#org8d3c1b5">4. Template for HDF5 has a group</a></li>
<li><a href="#orgfcbeb30">5. Template for HDF5 has/read/write a numerical attribute</a></li>
<li><a href="#orgf028474">6. Template for HDF5 has/read/write a dataset of numerical data</a></li>
<li><a href="#org35d74f0">7. Template for HDF5 has/read/write a dataset of sparse data</a></li>
<li><a href="#org6c4dde3">8. Template for HDF5 has/read/write a dataset of buffered vectors</a></li>
<li><a href="#org3503f8e">9. Template for HDF5 has/read/write a dataset of strings</a></li>
<li><a href="#org254ed29">10. Template for HDF5 has/read/write a string attribute</a></li>
<li><a href="#org33b3e9a">11. Template for HDF5 delete a group (UNSAFE mode)</a></li>
<li><a href="#org9dc56c7">12. Source code for the determinant part</a></li>
<li><a href="#orgb91257d">13. Helper functions</a></li>
</ul>
</div>
</div>
<div id="outline-container-orgf5ffd52" class="outline-2">
<h2 id="orgf5ffd52"><span class="section-number-2">1</span> Template for HDF5 definitions</h2>
<div id="outline-container-org3ede3d5" class="outline-2">
<h2 id="org3ede3d5"><span class="section-number-2">1</span> Template for HDF5 definitions</h2>
<div class="outline-text-2" id="text-1">
<div class="org-src-container">
<pre class="src src-c"><span style="color: #483d8b;">#define</span> $GROUP$_GROUP_NAME <span style="color: #8b2252;">"$group$"</span>
@ -354,8 +354,8 @@ for the JavaScript code in this tag.
</div>
</div>
<div id="outline-container-org0eb6385" class="outline-2">
<h2 id="org0eb6385"><span class="section-number-2">2</span> Template for HDF5 structures</h2>
<div id="outline-container-org523d95d" class="outline-2">
<h2 id="org523d95d"><span class="section-number-2">2</span> Template for HDF5 structures</h2>
<div class="outline-text-2" id="text-2">
<p>
Polymorphism of the <code>trexio_t</code> type is handled by ensuring that the
@ -375,8 +375,8 @@ corresponding types for all back ends can be safely casted to
</div>
</div>
<div id="outline-container-orgd17ce03" class="outline-2">
<h2 id="orgd17ce03"><span class="section-number-2">3</span> Template for HDF5 init/deinit</h2>
<div id="outline-container-orgb88d155" class="outline-2">
<h2 id="orgb88d155"><span class="section-number-2">3</span> Template for HDF5 init/deinit</h2>
<div class="outline-text-2" id="text-3">
<div class="org-src-container">
<pre class="src src-c"><span style="color: #228b22;">trexio_exit_code</span>
@ -496,8 +496,8 @@ corresponding types for all back ends can be safely casted to
</div>
</div>
<div id="outline-container-orge31791e" class="outline-2">
<h2 id="orge31791e"><span class="section-number-2">4</span> Template for HDF5 has a group</h2>
<div id="outline-container-org8d3c1b5" class="outline-2">
<h2 id="org8d3c1b5"><span class="section-number-2">4</span> Template for HDF5 has a group</h2>
<div class="outline-text-2" id="text-4">
<div class="org-src-container">
<pre class="src src-c"><span style="color: #228b22;">trexio_exit_code</span>
@ -527,8 +527,8 @@ corresponding types for all back ends can be safely casted to
</div>
</div>
<div id="outline-container-orgf8a7e04" class="outline-2">
<h2 id="orgf8a7e04"><span class="section-number-2">5</span> Template for HDF5 has/read/write a numerical attribute</h2>
<div id="outline-container-orgfcbeb30" class="outline-2">
<h2 id="orgfcbeb30"><span class="section-number-2">5</span> Template for HDF5 has/read/write a numerical attribute</h2>
<div class="outline-text-2" id="text-5">
<div class="org-src-container">
<pre class="src src-c"><span style="color: #228b22;">trexio_exit_code</span>
@ -632,8 +632,8 @@ corresponding types for all back ends can be safely casted to
</div>
</div>
<div id="outline-container-org63fa7ef" class="outline-2">
<h2 id="org63fa7ef"><span class="section-number-2">6</span> Template for HDF5 has/read/write a dataset of numerical data</h2>
<div id="outline-container-orgf028474" class="outline-2">
<h2 id="orgf028474"><span class="section-number-2">6</span> Template for HDF5 has/read/write a dataset of numerical data</h2>
<div class="outline-text-2" id="text-6">
<div class="org-src-container">
<pre class="src src-c"><span style="color: #228b22;">trexio_exit_code</span>
@ -770,8 +770,8 @@ corresponding types for all back ends can be safely casted to
</div>
</div>
<div id="outline-container-org51eca4f" class="outline-2">
<h2 id="org51eca4f"><span class="section-number-2">7</span> Template for HDF5 has/read/write a dataset of sparse data</h2>
<div id="outline-container-org35d74f0" class="outline-2">
<h2 id="org35d74f0"><span class="section-number-2">7</span> Template for HDF5 has/read/write a dataset of sparse data</h2>
<div class="outline-text-2" id="text-7">
<p>
Sparse data is stored using extensible datasets of HDF5. Extensibility is required
@ -973,8 +973,8 @@ due to the fact that the sparse data will be written in chunks of user-defined s
</div>
</div>
<div id="outline-container-org4dc838b" class="outline-2">
<h2 id="org4dc838b"><span class="section-number-2">8</span> Template for HDF5 has/read/write a dataset of buffered vectors</h2>
<div id="outline-container-org6c4dde3" class="outline-2">
<h2 id="org6c4dde3"><span class="section-number-2">8</span> Template for HDF5 has/read/write a dataset of buffered vectors</h2>
<div class="outline-text-2" id="text-8">
<p>
Chunked I/O in HDF5 for <code>buffered</code> data.
@ -1108,8 +1108,8 @@ Chunked I/O in HDF5 for <code>buffered</code> data.
</div>
</div>
<div id="outline-container-orgb8d7595" class="outline-2">
<h2 id="orgb8d7595"><span class="section-number-2">9</span> Template for HDF5 has/read/write a dataset of strings</h2>
<div id="outline-container-org3503f8e" class="outline-2">
<h2 id="org3503f8e"><span class="section-number-2">9</span> Template for HDF5 has/read/write a dataset of strings</h2>
<div class="outline-text-2" id="text-9">
<div class="org-src-container">
<pre class="src src-c"><span style="color: #228b22;">trexio_exit_code</span>
@ -1306,8 +1306,8 @@ Chunked I/O in HDF5 for <code>buffered</code> data.
</div>
</div>
<div id="outline-container-org4b60a49" class="outline-2">
<h2 id="org4b60a49"><span class="section-number-2">10</span> Template for HDF5 has/read/write a string attribute</h2>
<div id="outline-container-org254ed29" class="outline-2">
<h2 id="org254ed29"><span class="section-number-2">10</span> Template for HDF5 has/read/write a string attribute</h2>
<div class="outline-text-2" id="text-10">
<div class="org-src-container">
<pre class="src src-c"><span style="color: #228b22;">trexio_exit_code</span>
@ -1434,8 +1434,8 @@ Chunked I/O in HDF5 for <code>buffered</code> data.
</div>
</div>
</div>
<div id="outline-container-org2d247a4" class="outline-2">
<h2 id="org2d247a4"><span class="section-number-2">11</span> Template for HDF5 delete a group (UNSAFE mode)</h2>
<div id="outline-container-org33b3e9a" class="outline-2">
<h2 id="org33b3e9a"><span class="section-number-2">11</span> Template for HDF5 delete a group (UNSAFE mode)</h2>
<div class="outline-text-2" id="text-11">
<p>
<b><b>Note:</b></b> in early versions of the HDF5 library (v &lt; 1.10) unlinking an object was not working as expected
@ -1475,8 +1475,8 @@ Thus, any corrupted/lost file space will remain in the first file. The use of <c
</div>
</div>
<div id="outline-container-org315ad20" class="outline-2">
<h2 id="org315ad20"><span class="section-number-2">12</span> Source code for the determinant part</h2>
<div id="outline-container-org9dc56c7" class="outline-2">
<h2 id="org9dc56c7"><span class="section-number-2">12</span> Source code for the determinant part</h2>
<div class="outline-text-2" id="text-12">
<p>
Each array is stored in a separate HDF5 dataset due to the fact that determinant I/O has to be decoupled.
@ -1578,8 +1578,8 @@ Size specifies the number of data items (e.g. determinants) to process.
</div>
</div>
<div id="outline-container-org89fa238" class="outline-2">
<h2 id="org89fa238"><span class="section-number-2">13</span> Helper functions</h2>
<div id="outline-container-orgb91257d" class="outline-2">
<h2 id="orgb91257d"><span class="section-number-2">13</span> Helper functions</h2>
<div class="outline-text-2" id="text-13">
<div class="org-src-container">
<pre class="src src-c"><span style="color: #228b22;">trexio_exit_code</span>
@ -1842,7 +1842,7 @@ Size specifies the number of data items (e.g. determinants) to process.
</div>
<div id="postamble" class="status">
<p class="author">Author: TREX-CoE</p>
<p class="date">Created: 2023-02-16 Thu 08:31</p>
<p class="date">Created: 2023-02-17 Fri 16:43</p>
<p class="validation"><a href="http://validator.w3.org/check?uri=referer">Validate</a></p>
</div>
</body>

108
templator_text.html
View File

@ -3,7 +3,7 @@
"http://www.w3.org/TR/xhtml1/DTD/xhtml1-strict.dtd">
<html xmlns="http://www.w3.org/1999/xhtml" lang="en" xml:lang="en">
<head>
<!-- 2023-02-16 Thu 08:31 -->
<!-- 2023-02-17 Fri 16:43 -->
<meta http-equiv="Content-Type" content="text/html;charset=utf-8" />
<meta name="viewport" content="width=device-width, initial-scale=1" />
<title>TEXT back end</title>
@ -261,7 +261,7 @@ org_html_manager.set("LOCAL_TOC", "1");
org_html_manager.set("VIEW_BUTTONS", "0");
org_html_manager.set("MOUSE_HINT", "underline");
org_html_manager.set("FIXED_TOC", "0");
org_html_manager.set("TOC", "1");
org_html_manager.set("TOC", "0");
org_html_manager.set("VIEW", "info");
org_html_manager.setup(); // activate after the parameters are set
/*]]>*///-->
@ -324,23 +324,23 @@ for the JavaScript code in this tag.
<h2>Table of Contents</h2>
<div id="text-table-of-contents">
<ul>
<li><a href="#orga640ee0">1. Template for group-related structures in text back end</a></li>
<li><a href="#orgc330155">2. Template for general structure in text back end</a></li>
<li><a href="#org44d0b5b">3. Initialize function (constant part)</a></li>
<li><a href="#orgad27d10">4. Deinitialize function (templated part)</a></li>
<li><a href="#orgd43e45e">5. Flush function (templated part)</a></li>
<li><a href="#orgd54b267">6. Template for text read a group</a></li>
<li><a href="#orgbb4eb72">7. Template for text has a group</a></li>
<li><a href="#org516f934">8. Template for text flush a group</a></li>
<li><a href="#orgc1a5739">9. Template for text free memory</a></li>
<li><a href="#org6ade7f3">10. Template for has/read/write a numerical attribute</a></li>
<li><a href="#org6eb727a">11. Template for has/read/write a dataset of numerical data</a></li>
<li><a href="#orgd47ed4e">12. Template for has/read/write a dataset of strings</a></li>
<li><a href="#org813c770">13. Template for has/read/write a string attribute</a></li>
<li><a href="#org927a9d2">14. Template for has/read/write the dataset of sparse data</a></li>
<li><a href="#org18d8e7c">15. Template for has/read/write a buffered vector</a></li>
<li><a href="#orgc9f8921">16. Template for text delete a group (UNSAFE mode)</a></li>
<li><a href="#org28743d8">17. Source code for the determinant part</a></li>
<li><a href="#orgc6064b7">1. Template for group-related structures in text back end</a></li>
<li><a href="#orgaa7f132">2. Template for general structure in text back end</a></li>
<li><a href="#org4c9070e">3. Initialize function (constant part)</a></li>
<li><a href="#orgbabe9b3">4. Deinitialize function (templated part)</a></li>
<li><a href="#orgafa467c">5. Flush function (templated part)</a></li>
<li><a href="#org5b14e8d">6. Template for text read a group</a></li>
<li><a href="#orgca046f1">7. Template for text has a group</a></li>
<li><a href="#org6c0ce53">8. Template for text flush a group</a></li>
<li><a href="#org2e1247a">9. Template for text free memory</a></li>
<li><a href="#org879efe8">10. Template for has/read/write a numerical attribute</a></li>
<li><a href="#orga4d9e15">11. Template for has/read/write a dataset of numerical data</a></li>
<li><a href="#org883fd81">12. Template for has/read/write a dataset of strings</a></li>
<li><a href="#org78ea370">13. Template for has/read/write a string attribute</a></li>
<li><a href="#orgf63ea65">14. Template for has/read/write the dataset of sparse data</a></li>
<li><a href="#orga62a1b7">15. Template for has/read/write a buffered vector</a></li>
<li><a href="#org2521d77">16. Template for text delete a group (UNSAFE mode)</a></li>
<li><a href="#org5c94036">17. Source code for the determinant part</a></li>
</ul>
</div>
</div>
@ -362,8 +362,8 @@ directory.
The file is written when closed, or when the flush function is called.
</p>
<div id="outline-container-orga640ee0" class="outline-2">
<h2 id="orga640ee0"><span class="section-number-2">1</span> Template for group-related structures in text back end</h2>
<div id="outline-container-orgc6064b7" class="outline-2">
<h2 id="orgc6064b7"><span class="section-number-2">1</span> Template for group-related structures in text back end</h2>
<div class="outline-text-2" id="text-1">
<div class="org-src-container">
<pre class="src src-c"><span style="color: #a020f0;">typedef</span> <span style="color: #a020f0;">struct</span> $group$_s {
@ -382,8 +382,8 @@ The file is written when closed, or when the flush function is called.
</div>
</div>
<div id="outline-container-orgc330155" class="outline-2">
<h2 id="orgc330155"><span class="section-number-2">2</span> Template for general structure in text back end</h2>
<div id="outline-container-orgaa7f132" class="outline-2">
<h2 id="orgaa7f132"><span class="section-number-2">2</span> Template for general structure in text back end</h2>
<div class="outline-text-2" id="text-2">
<p>
Polymorphism of the <code>trexio_t</code> type is handled by ensuring that the
@ -403,8 +403,8 @@ corresponding types for all back ends can be safely casted to
</div>
</div>
<div id="outline-container-org44d0b5b" class="outline-2">
<h2 id="org44d0b5b"><span class="section-number-2">3</span> Initialize function (constant part)</h2>
<div id="outline-container-org4c9070e" class="outline-2">
<h2 id="org4c9070e"><span class="section-number-2">3</span> Initialize function (constant part)</h2>
<div class="outline-text-2" id="text-3">
<div class="org-src-container">
<pre class="src src-c"><span style="color: #228b22;">bool</span>
@ -571,8 +571,8 @@ corresponding types for all back ends can be safely casted to
</div>
</div>
<div id="outline-container-orgad27d10" class="outline-2">
<h2 id="orgad27d10"><span class="section-number-2">4</span> Deinitialize function (templated part)</h2>
<div id="outline-container-orgbabe9b3" class="outline-2">
<h2 id="orgbabe9b3"><span class="section-number-2">4</span> Deinitialize function (templated part)</h2>
<div class="outline-text-2" id="text-4">
<div class="org-src-container">
<pre class="src src-c"><span style="color: #228b22;">trexio_exit_code</span>
@ -594,8 +594,8 @@ corresponding types for all back ends can be safely casted to
</div>
</div>
<div id="outline-container-orgd43e45e" class="outline-2">
<h2 id="orgd43e45e"><span class="section-number-2">5</span> Flush function (templated part)</h2>
<div id="outline-container-orgafa467c" class="outline-2">
<h2 id="orgafa467c"><span class="section-number-2">5</span> Flush function (templated part)</h2>
<div class="outline-text-2" id="text-5">
<div class="org-src-container">
<pre class="src src-c"><span style="color: #228b22;">trexio_exit_code</span>
@ -618,8 +618,8 @@ corresponding types for all back ends can be safely casted to
</div>
</div>
<div id="outline-container-orgd54b267" class="outline-2">
<h2 id="orgd54b267"><span class="section-number-2">6</span> Template for text read a group</h2>
<div id="outline-container-org5b14e8d" class="outline-2">
<h2 id="org5b14e8d"><span class="section-number-2">6</span> Template for text read a group</h2>
<div class="outline-text-2" id="text-6">
<div class="org-src-container">
<pre class="src src-c">$group$_t*
@ -845,8 +845,8 @@ trexio_text_read_$group$ (<span style="color: #228b22;">trexio_text_t</span>* <s
</div>
</div>
<div id="outline-container-orgbb4eb72" class="outline-2">
<h2 id="orgbb4eb72"><span class="section-number-2">7</span> Template for text has a group</h2>
<div id="outline-container-orgca046f1" class="outline-2">
<h2 id="orgca046f1"><span class="section-number-2">7</span> Template for text has a group</h2>
<div class="outline-text-2" id="text-7">
<div class="org-src-container">
<pre class="src src-c"><span style="color: #228b22;">trexio_exit_code</span>
@ -886,8 +886,8 @@ trexio_text_read_$group$ (<span style="color: #228b22;">trexio_text_t</span>* <s
</div>
</div>
<div id="outline-container-org516f934" class="outline-2">
<h2 id="org516f934"><span class="section-number-2">8</span> Template for text flush a group</h2>
<div id="outline-container-org6c0ce53" class="outline-2">
<h2 id="org6c0ce53"><span class="section-number-2">8</span> Template for text flush a group</h2>
<div class="outline-text-2" id="text-8">
<div class="org-src-container">
<pre class="src src-c"><span style="color: #228b22;">trexio_exit_code</span>
@ -951,8 +951,8 @@ trexio_text_read_$group$ (<span style="color: #228b22;">trexio_text_t</span>* <s
</div>
</div>
<div id="outline-container-orgc1a5739" class="outline-2">
<h2 id="orgc1a5739"><span class="section-number-2">9</span> Template for text free memory</h2>
<div id="outline-container-org2e1247a" class="outline-2">
<h2 id="org2e1247a"><span class="section-number-2">9</span> Template for text free memory</h2>
<div class="outline-text-2" id="text-9">
<p>
Memory is allocated when reading. The following function frees memory.
@ -1021,8 +1021,8 @@ This function is called upon the non-successful exit from the <code>trexio_text_
</div>
</div>
<div id="outline-container-org6ade7f3" class="outline-2">
<h2 id="org6ade7f3"><span class="section-number-2">10</span> Template for has/read/write a numerical attribute</h2>
<div id="outline-container-org879efe8" class="outline-2">
<h2 id="org879efe8"><span class="section-number-2">10</span> Template for has/read/write a numerical attribute</h2>
<div class="outline-text-2" id="text-10">
<div class="org-src-container">
<pre class="src src-c"><span style="color: #228b22;">trexio_exit_code</span>
@ -1085,8 +1085,8 @@ This function is called upon the non-successful exit from the <code>trexio_text_
</div>
</div>
<div id="outline-container-org6eb727a" class="outline-2">
<h2 id="org6eb727a"><span class="section-number-2">11</span> Template for has/read/write a dataset of numerical data</h2>
<div id="outline-container-orga4d9e15" class="outline-2">
<h2 id="orga4d9e15"><span class="section-number-2">11</span> Template for has/read/write a dataset of numerical data</h2>
<div class="outline-text-2" id="text-11">
<p>
The <code>group_dset</code> array is assumed allocated with the appropriate size.
@ -1182,8 +1182,8 @@ The <code>group_dset</code> array is assumed allocated with the appropriate size
</div>
</div>
</div>
<div id="outline-container-orgd47ed4e" class="outline-2">
<h2 id="orgd47ed4e"><span class="section-number-2">12</span> Template for has/read/write a dataset of strings</h2>
<div id="outline-container-org883fd81" class="outline-2">
<h2 id="org883fd81"><span class="section-number-2">12</span> Template for has/read/write a dataset of strings</h2>
<div class="outline-text-2" id="text-12">
<p>
The <code>group_dset</code> array is assumed allocated with the appropriate size.
@ -1284,8 +1284,8 @@ The <code>group_dset</code> array is assumed allocated with the appropriate size
</div>
</div>
</div>
<div id="outline-container-org813c770" class="outline-2">
<h2 id="org813c770"><span class="section-number-2">13</span> Template for has/read/write a string attribute</h2>
<div id="outline-container-org78ea370" class="outline-2">
<h2 id="org78ea370"><span class="section-number-2">13</span> Template for has/read/write a string attribute</h2>
<div class="outline-text-2" id="text-13">
<div class="org-src-container">
<pre class="src src-c"><span style="color: #228b22;">trexio_exit_code</span>
@ -1359,8 +1359,8 @@ The <code>group_dset</code> array is assumed allocated with the appropriate size
</div>
</div>
</div>
<div id="outline-container-org927a9d2" class="outline-2">
<h2 id="org927a9d2"><span class="section-number-2">14</span> Template for has/read/write the dataset of sparse data</h2>
<div id="outline-container-orgf63ea65" class="outline-2">
<h2 id="orgf63ea65"><span class="section-number-2">14</span> Template for has/read/write the dataset of sparse data</h2>
<div class="outline-text-2" id="text-14">
<p>
Each sparse array is stored in a separate <code>.txt</code> file due to the fact that sparse I/O has to be decoupled
@ -1650,8 +1650,8 @@ User provides indices and values of the sparse array as two separate variables.
</div>
</div>
<div id="outline-container-org18d8e7c" class="outline-2">
<h2 id="org18d8e7c"><span class="section-number-2">15</span> Template for has/read/write a buffered vector</h2>
<div id="outline-container-orga62a1b7" class="outline-2">
<h2 id="orga62a1b7"><span class="section-number-2">15</span> Template for has/read/write a buffered vector</h2>
<div class="outline-text-2" id="text-15">
<p>
Each array is stored in a separate <code>.txt</code> file due to the fact that buffered I/O has to be decoupled
@ -1881,8 +1881,8 @@ Size specifies the number of vector elements to be written.
</div>
</div>
</div>
<div id="outline-container-orgc9f8921" class="outline-2">
<h2 id="orgc9f8921"><span class="section-number-2">16</span> Template for text delete a group (UNSAFE mode)</h2>
<div id="outline-container-org2521d77" class="outline-2">
<h2 id="org2521d77"><span class="section-number-2">16</span> Template for text delete a group (UNSAFE mode)</h2>
<div class="outline-text-2" id="text-16">
<div class="org-src-container">
<pre class="src src-c"><span style="color: #228b22;">trexio_exit_code</span>
@ -1910,8 +1910,8 @@ Size specifies the number of vector elements to be written.
</div>
</div>
<div id="outline-container-org28743d8" class="outline-2">
<h2 id="org28743d8"><span class="section-number-2">17</span> Source code for the determinant part</h2>
<div id="outline-container-org5c94036" class="outline-2">
<h2 id="org5c94036"><span class="section-number-2">17</span> Source code for the determinant part</h2>
<div class="outline-text-2" id="text-17">
<p>
Each array is stored in a separate <code>.txt</code> file due to the fact that determinant I/O has to be decoupled
@ -2103,7 +2103,7 @@ Size specifies the number of data items, e.g. determinants.
</div>
<div id="postamble" class="status">
<p class="author">Author: TREX-CoE</p>
<p class="date">Created: 2023-02-16 Thu 08:31</p>
<p class="date">Created: 2023-02-17 Fri 16:43</p>
<p class="validation"><a href="http://validator.w3.org/check?uri=referer">Validate</a></p>
</div>
</body>

4
theme.setup
View File

@ -1,11 +1,11 @@
# -*- mode: org; -*-
#+HTML_LINK_HOME: index.html
#+OPTIONS: H:4 num:t toc:t \n:nil @:t ::t |:t ^:t -:t f:t *:t <:t d:(HIDE)
#+OPTIONS: H:4 num:t toc:nil \n:nil @:t ::t |:t ^:t -:t f:t *:t <:t d:(HIDE)
####### #+SETUPFILE: ../docs/org-html-themes/org/theme-readtheorg.setup
#+INFOJS_OPT: toc:t mouse:underline path:org-info.js
#+INFOJS_OPT: mouse:underline path:org-info.js
#+HTML_HEAD: <link rel="stylesheet" title="Standard" href="trexio.css" type="text/css" />
#+STARTUP: align nodlcheck hidestars oddeven lognotestate

317
trex.html
View File

@ -3,10 +3,10 @@
"http://www.w3.org/TR/xhtml1/DTD/xhtml1-strict.dtd">
<html xmlns="http://www.w3.org/1999/xhtml" lang="en" xml:lang="en">
<head>
<!-- 2023-02-16 Thu 08:31 -->
<!-- 2023-02-17 Fri 16:43 -->
<meta http-equiv="Content-Type" content="text/html;charset=utf-8" />
<meta name="viewport" content="width=device-width, initial-scale=1" />
<title>TREX Configuration file</title>
<title>Data stored in TREXIO</title>
<meta name="generator" content="Org mode" />
<meta name="author" content="TREX-CoE" />
<style type="text/css">
@ -261,7 +261,7 @@ org_html_manager.set("LOCAL_TOC", "1");
org_html_manager.set("VIEW_BUTTONS", "0");
org_html_manager.set("MOUSE_HINT", "underline");
org_html_manager.set("FIXED_TOC", "0");
org_html_manager.set("TOC", "1");
org_html_manager.set("TOC", "0");
org_html_manager.set("VIEW", "info");
org_html_manager.setup(); // activate after the parameters are set
/*]]>*///-->
@ -341,144 +341,89 @@ for the JavaScript code in this tag.
|
<a accesskey="H" href="index.html"> HOME </a>
</div><div id="content">
<h1 class="title">TREX Configuration file</h1>
<h1 class="title">Data stored in TREXIO</h1>
<div id="table-of-contents">
<h2>Table of Contents</h2>
<div id="text-table-of-contents">
<ul>
<li><a href="#org33ce91d">1. Metadata (metadata group)</a></li>
<li><a href="#org70a683c">2. System</a>
<li><a href="#org859882f">1. Metadata (metadata group)</a></li>
<li><a href="#org42df71b">2. System</a>
<ul>
<li><a href="#org92d6f0a">2.1. Nucleus (nucleus group)</a></li>
<li><a href="#org5b8f3d8">2.2. Cell (cell group)</a></li>
<li><a href="#org2f9c849">2.3. Periodic boundary calculations (pbc group)</a></li>
<li><a href="#org5d3e21f">2.4. Electron (electron group)</a></li>
<li><a href="#orgca11162">2.5. Ground or excited states (state group)</a></li>
<li><a href="#org79125a2">2.1. Nucleus (nucleus group)</a></li>
<li><a href="#org91bb2e8">2.2. Cell (cell group)</a></li>
<li><a href="#orgbe095d4">2.3. Periodic boundary calculations (pbc group)</a></li>
<li><a href="#org5276b4a">2.4. Electron (electron group)</a></li>
<li><a href="#org359996c">2.5. Ground or excited states (state group)</a></li>
</ul>
</li>
<li><a href="#org5ca96fe">3. Basis functions</a>
<li><a href="#org88b75a2">3. Basis functions</a>
<ul>
<li><a href="#orgd28bb5b">3.1. Basis set (basis group)</a>
<li><a href="#org8b79c8d">3.1. Basis set (basis group)</a>
<ul>
<li><a href="#org827b6e4">3.1.1. Gaussian and Slater-type orbitals</a></li>
<li><a href="#org0212469">3.1.2. Plane waves</a></li>
<li><a href="#orga2715ca">3.1.3. Data definitions</a></li>
<li><a href="#org38f5e8d">3.1.4. Example</a></li>
<li><a href="#org2b74425">3.1.1. Gaussian and Slater-type orbitals</a></li>
<li><a href="#orgecb22c0">3.1.2. Plane waves</a></li>
<li><a href="#org360d707">3.1.3. Data definitions</a></li>
<li><a href="#orgdbf207d">3.1.4. Example</a></li>
</ul>
</li>
<li><a href="#orgb395003">3.2. Effective core potentials (ecp group)</a>
<li><a href="#org48febc7">3.2. Effective core potentials (ecp group)</a>
<ul>
<li><a href="#orge49cb3b">3.2.1. Example</a></li>
<li><a href="#org8abdb00">3.2.1. Example</a></li>
</ul>
</li>
<li><a href="#org8a449f8">3.3. Numerical integration grid (grid group)</a></li>
<li><a href="#orgd8cddc6">3.3. Numerical integration grid (grid group)</a></li>
</ul>
</li>
<li><a href="#org312e279">4. Orbitals</a>
<li><a href="#org7ea1eb7">4. Orbitals</a>
<ul>
<li><a href="#orge8a94c0">4.1. Atomic orbitals (ao group)</a>
<li><a href="#org447f348">4.1. Atomic orbitals (ao group)</a>
<ul>
<li><a href="#ao_one_e">4.1.1. One-electron integrals (<code>ao_1e_int</code> group)</a></li>
<li><a href="#ao_two_e">4.1.2. Two-electron integrals (<code>ao_2e_int</code> group)</a></li>
</ul>
</li>
<li><a href="#org784c310">4.2. Molecular orbitals (mo group)</a>
<li><a href="#org748becf">4.2. Molecular orbitals (mo group)</a>
<ul>
<li><a href="#orgcb6f756">4.2.1. One-electron integrals (<code>mo_1e_int</code> group)</a></li>
<li><a href="#org107f204">4.2.2. Two-electron integrals (<code>mo_2e_int</code> group)</a></li>
<li><a href="#org352e287">4.2.1. One-electron integrals (<code>mo_1e_int</code> group)</a></li>
<li><a href="#orgba10a3d">4.2.2. Two-electron integrals (<code>mo_2e_int</code> group)</a></li>
</ul>
</li>
</ul>
</li>
<li><a href="#orgd8b5719">5. Multi-determinant information</a>
<li><a href="#orgd3fd272">5. Multi-determinant information</a>
<ul>
<li><a href="#org1f9bd75">5.1. Slater determinants (determinant group)</a></li>
<li><a href="#orgb43c55b">5.2. Configuration state functions (csf group)</a></li>
<li><a href="#orgc58d4a0">5.3. Amplitudes (amplitude group)</a></li>
<li><a href="#org56a57e1">5.4. Reduced density matrices (rdm group)</a></li>
<li><a href="#org4480625">5.1. Slater determinants (determinant group)</a></li>
<li><a href="#org39f2e23">5.2. Configuration state functions (csf group)</a></li>
<li><a href="#org795c83c">5.3. Amplitudes (amplitude group)</a></li>
<li><a href="#org1489d77">5.4. Reduced density matrices (rdm group)</a></li>
</ul>
</li>
<li><a href="#org3bfd9bc">6. Correlation factors</a>
<li><a href="#orgbe33c50">6. Correlation factors</a>
<ul>
<li><a href="#orgbfcbb42">6.1. Jastrow factor (jastrow group)</a>
<li><a href="#org1a7a9da">6.1. Jastrow factor (jastrow group)</a>
<ul>
<li><a href="#orgb47e682">6.1.1. CHAMP</a></li>
<li><a href="#orgb962d45">6.1.2. Mu</a></li>
<li><a href="#orgab4862f">6.1.3. Table of values</a></li>
<li><a href="#org5542241">6.1.1. CHAMP</a></li>
<li><a href="#orgc87f972">6.1.2. Mu</a></li>
<li><a href="#orgc780997">6.1.3. Table of values</a></li>
</ul>
</li>
</ul>
</li>
<li><a href="#org8e6038b">7. Quantum Monte Carlo data (qmc group)</a></li>
<li><a href="#orgbe6c975">7. Quantum Monte Carlo data (qmc group)</a></li>
</ul>
</div>
</div>
<p>
This page contains information about the general structure of the
TREXIO library. The source code of the library can be automatically
generated based on the contents of the <code>trex.json</code> configuration file,
which itself is generated from different sections (groups) presented
below.
For simplicity, the singular form is always used for the names of
groups and attributes, and all data are stored in atomic units.
The dimensions of the arrays in the tables below are given in
column-major order (as in Fortran), and the ordering of the dimensions
is reversed in the produced <code>trex.json</code> configuration file as the
library is written in C.
</p>
<p>
All quantities are saved in TREXIO files in atomic units. The
dimensions of the arrays in the tables below are given in column-major
order (as in Fortran), and the ordering of the dimensions is reversed
in the produced <code>trex.json</code> configuration file as the library is
written in C.
</p>
<p>
TREXIO currently supports <code>int</code>, <code>float</code> and <code>str</code> types for both
single attributes and arrays. Note, that some attributes might have
<code>dim</code> type (e.g. <code>num</code> of the <code>nucleus</code> group). This type is treated
exactly in the same way as <code>int</code> with the only difference that <code>dim</code>
variables cannot be negative. This additional constraint is required
because <code>dim</code> attributes are used internally to allocate memory and to
check array boundaries in the memory-safe API. Most of the times, the
<code>dim</code> variables contain the <code>num</code> suffix.
You may also encounter some <code>dim readonly</code> variables.
It means that the value is automatically computed and written by the
TREXIO library, thus it is read-only and cannot be (over)written by the
user.
</p>
<p>
In Fortran, arrays are 1-based and in most other languages the
arrays are 0-based. Hence, we introduce the <code>index</code> type which is a
1-based <code>int</code> in the Fortran interface and 0-based otherwise.
</p>
<p>
For sparse data structures such as electron replusion integrals,
the data can be too large to fit in memory and the data needs to be
fetched using multiple function calls to perform I/O on buffers.
For more information on how to read/write sparse data structures, see
the <a href="./examples.html">examples</a>. The <code>sparse</code> data representation implies the
<a href="https://en.wikipedia.org/wiki/Sparse_matrix#Coordinate_list_(COO)">coordinate list</a> representation, namely the user has to write a list
of indices and values.
</p>
<p>
For the Configuration Interaction (CI) and Configuration State Function (CSF)
groups, the <code>buffered</code> data type is introduced, which allows similar incremental
I/O as for <code>sparse</code> data but without the need to write indices of the sparse values.
</p>
<p>
For determinant lists (integer bit fields), the <code>special</code> attribute is present in the type.
This means that the source code is not produced by the generator, but hand-written.
</p>
<p>
Some data may be complex. In that case, the real part should be stored
in the variable, and the imaginary part will be stored in the variable
with the same name suffixed by <code>_im</code>.
</p>
<div id="outline-container-org33ce91d" class="outline-2">
<h2 id="org33ce91d"><span class="section-number-2">1</span> Metadata (metadata group)</h2>
<div id="outline-container-org859882f" class="outline-2">
<h2 id="org859882f"><span class="section-number-2">1</span> Metadata (metadata group)</h2>
<div class="outline-text-2" id="text-1">
<p>
As we expect TREXIO files to be archived in open-data repositories,
@ -488,7 +433,7 @@ have participated to the creation of the file, a list of authors of
the file, and a textual description.
</p>
<table id="orgd42ddd1" border="2" cellspacing="0" cellpadding="6" rules="groups" frame="hsides">
<table id="org0fcc1f6" border="2" cellspacing="0" cellpadding="6" rules="groups" frame="hsides">
<colgroup>
@ -571,19 +516,19 @@ value can be manually overwritten (in unsafe mode) from <code>1</code> to <code>
</div>
</div>
<div id="outline-container-org70a683c" class="outline-2">
<h2 id="org70a683c"><span class="section-number-2">2</span> System</h2>
<div id="outline-container-org42df71b" class="outline-2">
<h2 id="org42df71b"><span class="section-number-2">2</span> System</h2>
<div class="outline-text-2" id="text-2">
</div>
<div id="outline-container-org92d6f0a" class="outline-3">
<h3 id="org92d6f0a"><span class="section-number-3">2.1</span> Nucleus (nucleus group)</h3>
<div id="outline-container-org79125a2" class="outline-3">
<h3 id="org79125a2"><span class="section-number-3">2.1</span> Nucleus (nucleus group)</h3>
<div class="outline-text-3" id="text-2-1">
<p>
The nuclei are considered as fixed point charges. Coordinates are
given in Cartesian \((x,y,z)\) format.
</p>
<table id="org6aa242a" border="2" cellspacing="0" cellpadding="6" rules="groups" frame="hsides">
<table id="orga5810d5" border="2" cellspacing="0" cellpadding="6" rules="groups" frame="hsides">
<colgroup>
@ -650,15 +595,15 @@ given in Cartesian \((x,y,z)\) format.
</div>
</div>
<div id="outline-container-org5b8f3d8" class="outline-3">
<h3 id="org5b8f3d8"><span class="section-number-3">2.2</span> Cell (cell group)</h3>
<div id="outline-container-org91bb2e8" class="outline-3">
<h3 id="org91bb2e8"><span class="section-number-3">2.2</span> Cell (cell group)</h3>
<div class="outline-text-3" id="text-2-2">
<p>
3 Lattice vectors to define a box containing the system, for example
used in periodic calculations.
</p>
<table id="org8cc056f" border="2" cellspacing="0" cellpadding="6" rules="groups" frame="hsides">
<table id="org8f8e3e3" border="2" cellspacing="0" cellpadding="6" rules="groups" frame="hsides">
<colgroup>
@ -732,15 +677,15 @@ used in periodic calculations.
</div>
</div>
<div id="outline-container-org2f9c849" class="outline-3">
<h3 id="org2f9c849"><span class="section-number-3">2.3</span> Periodic boundary calculations (pbc group)</h3>
<div id="outline-container-orgbe095d4" class="outline-3">
<h3 id="orgbe095d4"><span class="section-number-3">2.3</span> Periodic boundary calculations (pbc group)</h3>
<div class="outline-text-3" id="text-2-3">
<p>
A single $k$-point per TREXIO file can be stored. The $k$-point is
defined in this group.
</p>
<table id="orgd21ff56" border="2" cellspacing="0" cellpadding="6" rules="groups" frame="hsides">
<table id="orge5380f6" border="2" cellspacing="0" cellpadding="6" rules="groups" frame="hsides">
<colgroup>
@ -779,15 +724,15 @@ defined in this group.
</div>
</div>
<div id="outline-container-org5d3e21f" class="outline-3">
<h3 id="org5d3e21f"><span class="section-number-3">2.4</span> Electron (electron group)</h3>
<div id="outline-container-org5276b4a" class="outline-3">
<h3 id="org5276b4a"><span class="section-number-3">2.4</span> Electron (electron group)</h3>
<div class="outline-text-3" id="text-2-4">
<p>
We consider wave functions expressed in the spin-free formalism, where
the number of &uarr; and &darr; electrons is fixed.
</p>
<table id="orgf25a63e" border="2" cellspacing="0" cellpadding="6" rules="groups" frame="hsides">
<table id="org4922b3a" border="2" cellspacing="0" cellpadding="6" rules="groups" frame="hsides">
<colgroup>
@ -833,8 +778,8 @@ the number of &uarr; and &darr; electrons is fixed.
</div>
</div>
<div id="outline-container-orgca11162" class="outline-3">
<h3 id="orgca11162"><span class="section-number-3">2.5</span> Ground or excited states (state group)</h3>
<div id="outline-container-org359996c" class="outline-3">
<h3 id="org359996c"><span class="section-number-3">2.5</span> Ground or excited states (state group)</h3>
<div class="outline-text-3" id="text-2-5">
<p>
This group contains information about excited states. Since only a
@ -851,7 +796,7 @@ integrals, etc.
The <code>id</code> and <code>current_label</code> attributes need to be specified for each file.
</p>
<table id="org9290cb9" border="2" cellspacing="0" cellpadding="6" rules="groups" frame="hsides">
<table id="org96a8c8d" border="2" cellspacing="0" cellpadding="6" rules="groups" frame="hsides">
<colgroup>
@ -912,16 +857,16 @@ The <code>id</code> and <code>current_label</code> attributes need to be specifi
</div>
</div>
<div id="outline-container-org5ca96fe" class="outline-2">
<h2 id="org5ca96fe"><span class="section-number-2">3</span> Basis functions</h2>
<div id="outline-container-org88b75a2" class="outline-2">
<h2 id="org88b75a2"><span class="section-number-2">3</span> Basis functions</h2>
<div class="outline-text-2" id="text-3">
</div>
<div id="outline-container-orgd28bb5b" class="outline-3">
<h3 id="orgd28bb5b"><span class="section-number-3">3.1</span> Basis set (basis group)</h3>
<div id="outline-container-org8b79c8d" class="outline-3">
<h3 id="org8b79c8d"><span class="section-number-3">3.1</span> Basis set (basis group)</h3>
<div class="outline-text-3" id="text-3-1">
</div>
<div id="outline-container-org827b6e4" class="outline-4">
<h4 id="org827b6e4"><span class="section-number-4">3.1.1</span> Gaussian and Slater-type orbitals</h4>
<div id="outline-container-org2b74425" class="outline-4">
<h4 id="org2b74425"><span class="section-number-4">3.1.1</span> Gaussian and Slater-type orbitals</h4>
<div class="outline-text-4" id="text-3-1-1">
<p>
We consider here basis functions centered on nuclei. Hence, we enable
@ -975,8 +920,8 @@ All the basis set parameters are stored in one-dimensional arrays.
</div>
</div>
<div id="outline-container-org0212469" class="outline-4">
<h4 id="org0212469"><span class="section-number-4">3.1.2</span> Plane waves</h4>
<div id="outline-container-orgecb22c0" class="outline-4">
<h4 id="orgecb22c0"><span class="section-number-4">3.1.2</span> Plane waves</h4>
<div class="outline-text-4" id="text-3-1-2">
<p>
A plane wave is defined as
@ -997,10 +942,10 @@ plane waves.
</div>
</div>
<div id="outline-container-orga2715ca" class="outline-4">
<h4 id="orga2715ca"><span class="section-number-4">3.1.3</span> Data definitions</h4>
<div id="outline-container-org360d707" class="outline-4">
<h4 id="org360d707"><span class="section-number-4">3.1.3</span> Data definitions</h4>
<div class="outline-text-4" id="text-3-1-3">
<table id="org5a62610" border="2" cellspacing="0" cellpadding="6" rules="groups" frame="hsides">
<table id="orgd20fcf4" border="2" cellspacing="0" cellpadding="6" rules="groups" frame="hsides">
<colgroup>
@ -1109,8 +1054,8 @@ plane waves.
</div>
</div>
<div id="outline-container-org38f5e8d" class="outline-4">
<h4 id="org38f5e8d"><span class="section-number-4">3.1.4</span> Example</h4>
<div id="outline-container-orgdbf207d" class="outline-4">
<h4 id="orgdbf207d"><span class="section-number-4">3.1.4</span> Example</h4>
<div class="outline-text-4" id="text-3-1-4">
<p>
For example, consider H<sub>2</sub> with the following basis set (in GAMESS
@ -1188,8 +1133,8 @@ prim_factor =
</div>
</div>
<div id="outline-container-orgb395003" class="outline-3">
<h3 id="orgb395003"><span class="section-number-3">3.2</span> Effective core potentials (ecp group)</h3>
<div id="outline-container-org48febc7" class="outline-3">
<h3 id="org48febc7"><span class="section-number-3">3.2</span> Effective core potentials (ecp group)</h3>
<div class="outline-text-3" id="text-3-2">
<p>
An effective core potential (ECP) \(V_A^{\text{ECP}}\) replacing the
@ -1221,7 +1166,7 @@ All the functions \(V_{A\ell}\) are parameterized as:
See <a href="http://dx.doi.org/10.1063/1.4984046">http://dx.doi.org/10.1063/1.4984046</a> or <a href="https://doi.org/10.1063/1.5121006">https://doi.org/10.1063/1.5121006</a> for more info.
</p>
<table id="orge41735c" border="2" cellspacing="0" cellpadding="6" rules="groups" frame="hsides">
<table id="org98022c7" border="2" cellspacing="0" cellpadding="6" rules="groups" frame="hsides">
<colgroup>
@ -1325,8 +1270,8 @@ If you encounter the aforementioned issue, please report it to our
</p>
</div>
<div id="outline-container-orge49cb3b" class="outline-4">
<h4 id="orge49cb3b"><span class="section-number-4">3.2.1</span> Example</h4>
<div id="outline-container-org8abdb00" class="outline-4">
<h4 id="org8abdb00"><span class="section-number-4">3.2.1</span> Example</h4>
<div class="outline-text-4" id="text-3-2-1">
<p>
For example, consider H<sub>2</sub> molecule with the following
@ -1389,8 +1334,8 @@ power = [
</div>
</div>
<div id="outline-container-org8a449f8" class="outline-3">
<h3 id="org8a449f8"><span class="section-number-3">3.3</span> Numerical integration grid (grid group)</h3>
<div id="outline-container-orgd8cddc6" class="outline-3">
<h3 id="orgd8cddc6"><span class="section-number-3">3.3</span> Numerical integration grid (grid group)</h3>
<div class="outline-text-3" id="text-3-3">
<p>
In some applications, such as DFT calculations, integrals have to
@ -1405,7 +1350,7 @@ The structure of this group is adapted for the <a href="https://github.com/dftli
Feel free to submit a PR if you find missing options/functionalities.
</p>
<table id="org393430d" border="2" cellspacing="0" cellpadding="6" rules="groups" frame="hsides">
<table id="org95734f6" border="2" cellspacing="0" cellpadding="6" rules="groups" frame="hsides">
<colgroup>
@ -1522,12 +1467,12 @@ Feel free to submit a PR if you find missing options/functionalities.
</div>
</div>
<div id="outline-container-org312e279" class="outline-2">
<h2 id="org312e279"><span class="section-number-2">4</span> Orbitals</h2>
<div id="outline-container-org7ea1eb7" class="outline-2">
<h2 id="org7ea1eb7"><span class="section-number-2">4</span> Orbitals</h2>
<div class="outline-text-2" id="text-4">
</div>
<div id="outline-container-orge8a94c0" class="outline-3">
<h3 id="orge8a94c0"><span class="section-number-3">4.1</span> Atomic orbitals (ao group)</h3>
<div id="outline-container-org447f348" class="outline-3">
<h3 id="org447f348"><span class="section-number-3">4.1</span> Atomic orbitals (ao group)</h3>
<div class="outline-text-3" id="text-4-1">
<p>
Going from the atomic basis set to AOs implies a systematic
@ -1580,13 +1525,13 @@ shell, as in the GAMESS convention where
<p>
In such a case, one should set the normalization of the shell (in
the <a href="#orgd28bb5b">Basis set</a> section) to \(\mathcal{N}_{z^2}\), which is the
the <a href="#org8b79c8d">Basis set</a> section) to \(\mathcal{N}_{z^2}\), which is the
normalization factor of the atomic orbitals in spherical coordinates.
The normalization factor of the \(xy\) function which should be
introduced here should be \(\frac{\mathcal{N}_{xy}}{\mathcal{N}_{z^2}}\).
</p>
<table id="orgd888ed2" border="2" cellspacing="0" cellpadding="6" rules="groups" frame="hsides">
<table id="orgb587e10" border="2" cellspacing="0" cellpadding="6" rules="groups" frame="hsides">
<colgroup>
@ -1638,7 +1583,7 @@ introduced here should be \(\frac{\mathcal{N}_{xy}}{\mathcal{N}_{z^2}}\).
</table>
</div>
<div id="outline-container-orgb594dc9" class="outline-4">
<div id="outline-container-org32fe513" class="outline-4">
<h4 id="ao_one_e"><span class="section-number-4">4.1.1</span> One-electron integrals (<code>ao_1e_int</code> group)</h4>
<div class="outline-text-4" id="text-ao_one_e">
<ul class="org-ul">
@ -1656,7 +1601,7 @@ The one-electron integrals for a one-electron operator \(\hat{O}\) are
over atomic orbitals.
</p>
<table id="org53c5ab9" border="2" cellspacing="0" cellpadding="6" rules="groups" frame="hsides">
<table id="orge706a22" border="2" cellspacing="0" cellpadding="6" rules="groups" frame="hsides">
<colgroup>
@ -1751,7 +1696,7 @@ over atomic orbitals.
</div>
</div>
<div id="outline-container-orga3a2567" class="outline-4">
<div id="outline-container-org3cf111d" class="outline-4">
<h4 id="ao_two_e"><span class="section-number-4">4.1.2</span> Two-electron integrals (<code>ao_2e_int</code> group)</h4>
<div class="outline-text-4" id="text-ao_two_e">
<p>
@ -1783,7 +1728,7 @@ The Cholesky decomposition of the integrals can also be stored:
\]
</p>
<table id="orgf3bd6f0" border="2" cellspacing="0" cellpadding="6" rules="groups" frame="hsides">
<table id="orgd3385e2" border="2" cellspacing="0" cellpadding="6" rules="groups" frame="hsides">
<colgroup>
@ -1851,10 +1796,10 @@ The Cholesky decomposition of the integrals can also be stored:
</div>
</div>
<div id="outline-container-org784c310" class="outline-3">
<h3 id="org784c310"><span class="section-number-3">4.2</span> Molecular orbitals (mo group)</h3>
<div id="outline-container-org748becf" class="outline-3">
<h3 id="org748becf"><span class="section-number-3">4.2</span> Molecular orbitals (mo group)</h3>
<div class="outline-text-3" id="text-4-2">
<table id="org195bdf3" border="2" cellspacing="0" cellpadding="6" rules="groups" frame="hsides">
<table id="orgd2f813c" border="2" cellspacing="0" cellpadding="6" rules="groups" frame="hsides">
<colgroup>
@ -1941,8 +1886,8 @@ The Cholesky decomposition of the integrals can also be stored:
</table>
</div>
<div id="outline-container-orgcb6f756" class="outline-4">
<h4 id="orgcb6f756"><span class="section-number-4">4.2.1</span> One-electron integrals (<code>mo_1e_int</code> group)</h4>
<div id="outline-container-org352e287" class="outline-4">
<h4 id="org352e287"><span class="section-number-4">4.2.1</span> One-electron integrals (<code>mo_1e_int</code> group)</h4>
<div class="outline-text-4" id="text-4-2-1">
<p>
The operators as the same as those defined in the
@ -1950,7 +1895,7 @@ The operators as the same as those defined in the
the basis of molecular orbitals.
</p>
<table id="orge2a805b" border="2" cellspacing="0" cellpadding="6" rules="groups" frame="hsides">
<table id="org3ea2094" border="2" cellspacing="0" cellpadding="6" rules="groups" frame="hsides">
<colgroup>
@ -2045,8 +1990,8 @@ the basis of molecular orbitals.
</div>
</div>
<div id="outline-container-org107f204" class="outline-4">
<h4 id="org107f204"><span class="section-number-4">4.2.2</span> Two-electron integrals (<code>mo_2e_int</code> group)</h4>
<div id="outline-container-orgba10a3d" class="outline-4">
<h4 id="orgba10a3d"><span class="section-number-4">4.2.2</span> Two-electron integrals (<code>mo_2e_int</code> group)</h4>
<div class="outline-text-4" id="text-4-2-2">
<p>
The operators are the same as those defined in the
@ -2054,7 +1999,7 @@ The operators are the same as those defined in the
the basis of molecular orbitals.
</p>
<table id="orgee4f335" border="2" cellspacing="0" cellpadding="6" rules="groups" frame="hsides">
<table id="org65de704" border="2" cellspacing="0" cellpadding="6" rules="groups" frame="hsides">
<colgroup>
@ -2123,12 +2068,12 @@ the basis of molecular orbitals.
</div>
</div>
<div id="outline-container-orgd8b5719" class="outline-2">
<h2 id="orgd8b5719"><span class="section-number-2">5</span> Multi-determinant information</h2>
<div id="outline-container-orgd3fd272" class="outline-2">
<h2 id="orgd3fd272"><span class="section-number-2">5</span> Multi-determinant information</h2>
<div class="outline-text-2" id="text-5">
</div>
<div id="outline-container-org1f9bd75" class="outline-3">
<h3 id="org1f9bd75"><span class="section-number-3">5.1</span> Slater determinants (determinant group)</h3>
<div id="outline-container-org4480625" class="outline-3">
<h3 id="org4480625"><span class="section-number-3">5.1</span> Slater determinants (determinant group)</h3>
<div class="outline-text-3" id="text-5-1">
<p>
The configuration interaction (CI) wave function \(\Psi\)
@ -2170,7 +2115,7 @@ produced by the code generator.
An illustration on how to read determinants is presented in the <a href="./examples.html">examples</a>.
</p>
<table id="org72b5bd1" border="2" cellspacing="0" cellpadding="6" rules="groups" frame="hsides">
<table id="orgd924921" border="2" cellspacing="0" cellpadding="6" rules="groups" frame="hsides">
<colgroup>
@ -2216,8 +2161,8 @@ An illustration on how to read determinants is presented in the <a href="./examp
</div>
</div>
<div id="outline-container-orgb43c55b" class="outline-3">
<h3 id="orgb43c55b"><span class="section-number-3">5.2</span> Configuration state functions (csf group)</h3>
<div id="outline-container-org39f2e23" class="outline-3">
<h3 id="org39f2e23"><span class="section-number-3">5.2</span> Configuration state functions (csf group)</h3>
<div class="outline-text-3" id="text-5-2">
<p>
The configuration interaction (CI) wave function \(\Psi\) can be
@ -2239,7 +2184,7 @@ matrix \(\langle D_I | \psi_J \rangle\) needed to project the CSFs in
the basis of Slater determinants.
</p>
<table id="org117f756" border="2" cellspacing="0" cellpadding="6" rules="groups" frame="hsides">
<table id="orgf723169" border="2" cellspacing="0" cellpadding="6" rules="groups" frame="hsides">
<colgroup>
@ -2285,8 +2230,8 @@ the basis of Slater determinants.
</div>
</div>
<div id="outline-container-orgc58d4a0" class="outline-3">
<h3 id="orgc58d4a0"><span class="section-number-3">5.3</span> Amplitudes (amplitude group)</h3>
<div id="outline-container-org795c83c" class="outline-3">
<h3 id="org795c83c"><span class="section-number-3">5.3</span> Amplitudes (amplitude group)</h3>
<div class="outline-text-3" id="text-5-3">
<p>
The wave function may be expressed in terms of action of the cluster
@ -2357,7 +2302,7 @@ The order of the indices is chosen such that
<li>\(\dots\)</li>
</ul>
<table id="org9bcca6b" border="2" cellspacing="0" cellpadding="6" rules="groups" frame="hsides">
<table id="org423b6b7" border="2" cellspacing="0" cellpadding="6" rules="groups" frame="hsides">
<colgroup>
@ -2438,8 +2383,8 @@ The order of the indices is chosen such that
</div>
</div>
<div id="outline-container-org56a57e1" class="outline-3">
<h3 id="org56a57e1"><span class="section-number-3">5.4</span> Reduced density matrices (rdm group)</h3>
<div id="outline-container-org1489d77" class="outline-3">
<h3 id="org1489d77"><span class="section-number-3">5.4</span> Reduced density matrices (rdm group)</h3>
<div class="outline-text-3" id="text-5-4">
<p>
The reduced density matrices are defined in the basis of molecular
@ -2517,7 +2462,7 @@ expressed in a basis of a one-electron function
\(g_{ik}(\mathbf{r}_1) = \phi_i(\mathbf{r}_1) \phi_k(\mathbf{r}_1)\).
</p>
<table id="org076b848" border="2" cellspacing="0" cellpadding="6" rules="groups" frame="hsides">
<table id="org5a7f5da" border="2" cellspacing="0" cellpadding="6" rules="groups" frame="hsides">
<colgroup>
@ -2648,12 +2593,12 @@ expressed in a basis of a one-electron function
</div>
</div>
<div id="outline-container-org3bfd9bc" class="outline-2">
<h2 id="org3bfd9bc"><span class="section-number-2">6</span> Correlation factors</h2>
<div id="outline-container-orgbe33c50" class="outline-2">
<h2 id="orgbe33c50"><span class="section-number-2">6</span> Correlation factors</h2>
<div class="outline-text-2" id="text-6">
</div>
<div id="outline-container-orgbfcbb42" class="outline-3">
<h3 id="orgbfcbb42"><span class="section-number-3">6.1</span> Jastrow factor (jastrow group)</h3>
<div id="outline-container-org1a7a9da" class="outline-3">
<h3 id="org1a7a9da"><span class="section-number-3">6.1</span> Jastrow factor (jastrow group)</h3>
<div class="outline-text-3" id="text-6-1">
<p>
The Jastrow factor is an $N$-electron function to which the CI
@ -2678,8 +2623,8 @@ following:
</ul>
</div>
<div id="outline-container-orgb47e682" class="outline-4">
<h4 id="orgb47e682"><span class="section-number-4">6.1.1</span> CHAMP</h4>
<div id="outline-container-org5542241" class="outline-4">
<h4 id="org5542241"><span class="section-number-4">6.1.1</span> CHAMP</h4>
<div class="outline-text-4" id="text-6-1-1">
<p>
The first form of Jastrow factor is the one used in
@ -2756,8 +2701,8 @@ The terms \(J_{\text{ee}}^\infty\) and \(J_{\text{eN}}^\infty\) are shifts to en
</div>
</div>
<div id="outline-container-orgb962d45" class="outline-4">
<h4 id="orgb962d45"><span class="section-number-4">6.1.2</span> Mu</h4>
<div id="outline-container-orgc87f972" class="outline-4">
<h4 id="orgc87f972"><span class="section-number-4">6.1.2</span> Mu</h4>
<div class="outline-text-4" id="text-6-1-2">
<p>
<a href="https://aip.scitation.org/doi/10.1063/5.0044683">Mu-Jastrow</a> is based on a one-parameter correlation factor that has
@ -2854,10 +2799,10 @@ The parameter \(\mu\) is stored in the <code>ee</code> array, the parameters
</div>
</div>
<div id="outline-container-orgab4862f" class="outline-4">
<h4 id="orgab4862f"><span class="section-number-4">6.1.3</span> Table of values</h4>
<div id="outline-container-orgc780997" class="outline-4">
<h4 id="orgc780997"><span class="section-number-4">6.1.3</span> Table of values</h4>
<div class="outline-text-4" id="text-6-1-3">
<table id="org430db76" border="2" cellspacing="0" cellpadding="6" rules="groups" frame="hsides">
<table id="org82e8d8c" border="2" cellspacing="0" cellpadding="6" rules="groups" frame="hsides">
<colgroup>
@ -2961,8 +2906,8 @@ The parameter \(\mu\) is stored in the <code>ee</code> array, the parameters
</div>
</div>
<div id="outline-container-org8e6038b" class="outline-2">
<h2 id="org8e6038b"><span class="section-number-2">7</span> Quantum Monte Carlo data (qmc group)</h2>
<div id="outline-container-orgbe6c975" class="outline-2">
<h2 id="orgbe6c975"><span class="section-number-2">7</span> Quantum Monte Carlo data (qmc group)</h2>
<div class="outline-text-2" id="text-7">
<p>
In quantum Monte Carlo calculations, the wave function is evaluated
@ -2976,7 +2921,7 @@ By convention, the electron coordinates contain first all the electrons
of $&uarr;$-spin and then all the $&darr;$-spin.
</p>
<table id="org0125719" border="2" cellspacing="0" cellpadding="6" rules="groups" frame="hsides">
<table id="org6e8c0ee" border="2" cellspacing="0" cellpadding="6" rules="groups" frame="hsides">
<colgroup>
@ -3031,7 +2976,7 @@ of $&uarr;$-spin and then all the $&darr;$-spin.
</div>
<div id="postamble" class="status">
<p class="author">Author: TREX-CoE</p>
<p class="date">Created: 2023-02-16 Thu 08:31</p>
<p class="date">Created: 2023-02-17 Fri 16:43</p>
<p class="validation"><a href="http://validator.w3.org/check?uri=referer">Validate</a></p>
</div>
</body>

BIN
trex_lib.png Normal file
View File

Binary file not shown.
Side by Side

After

Width:  |  Height:  |  Size: 1.6 MiB

BIN
trex_specs.png Normal file
View File

Binary file not shown.
Side by Side

After

Width:  |  Height:  |  Size: 1.5 MiB

BIN
trexio.png Normal file
View File

Binary file not shown.
Side by Side

After

Width:  |  Height:  |  Size: 425 KiB

BIN
trexio_logo.png Normal file
View File

Binary file not shown.
Side by Side

After

Width:  |  Height:  |  Size: 37 KiB