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

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

Browse Source
This commit is contained in:
q-posev 2021-09-16 14:47:50 +00:00
parent a82a291923
commit 9c60541b97
9 changed files with 491 additions and 727 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

5
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>
<!-- 2021-09-15 Wed 13:07 -->
<!-- 2021-09-16 Thu 14:47 -->
<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>
@ -310,6 +310,7 @@ for the JavaScript code in this tag.
<hr />
<ul class="org-ul">
<li><a href="./tutorial_benzene.html">Tutorial</a></li>
<li><a href="./trex.html">Data stored with TREXIO</a></li>
<li><a href="./templator_front.html">Front end API</a></li>
<li><a href="./templator_hdf5.html">HDF5 back end</a></li>
@ -342,7 +343,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: 2021-09-15 Wed 13:07</p>
<p class="date">Created: 2021-09-16 Thu 14:47</p>
<p class="validation"><a href="http://validator.w3.org/check?uri=referer">Validate</a></p>
</div>
</body>

16
Sparse.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>
<!-- 2021-09-15 Wed 13:07 -->
<!-- 2021-09-16 Thu 14:47 -->
<meta http-equiv="Content-Type" content="text/html;charset=utf-8" />
<meta name="viewport" content="width=device-width, initial-scale=1" />
<title>&lrm;</title>
@ -232,8 +232,8 @@ for the JavaScript code in this tag.
<h2>Table of Contents</h2>
<div id="text-table-of-contents">
<ul>
<li><a href="#orge6fac75">1. Text back end</a></li>
<li><a href="#orgb9ab3b3">2. HDF5 Back end</a></li>
<li><a href="#org39414f4">1. Text back end</a></li>
<li><a href="#orge8df5f1">2. HDF5 Back end</a></li>
</ul>
</div>
</div>
@ -241,8 +241,8 @@ for the JavaScript code in this tag.
See templator<sub>front.org</sub>
</p>
<div id="outline-container-orge6fac75" class="outline-2">
<h2 id="orge6fac75"><span class="section-number-2">1</span> Text back end</h2>
<div id="outline-container-org39414f4" class="outline-2">
<h2 id="org39414f4"><span class="section-number-2">1</span> Text back end</h2>
<div class="outline-text-2" id="text-1">
<p>
As the size of the dataset should be extensible, the simplest
@ -256,8 +256,8 @@ The offset can be used with <code>fseek(69L*offset, SEEK_SET)</code>
</div>
</div>
<div id="outline-container-orgb9ab3b3" class="outline-2">
<h2 id="orgb9ab3b3"><span class="section-number-2">2</span> HDF5 Back end</h2>
<div id="outline-container-orge8df5f1" class="outline-2">
<h2 id="orge8df5f1"><span class="section-number-2">2</span> HDF5 Back end</h2>
<div class="outline-text-2" id="text-2">
<p>
We need to declare the number of rows of the dataset as
@ -278,7 +278,7 @@ If the offset+num &gt; nmax, we need to extend the dataset.
</div>
</div>
<div id="postamble" class="status">
<p class="date">Created: 2021-09-15 Wed 13:07</p>
<p class="date">Created: 2021-09-16 Thu 14:47</p>
<p class="validation"><a href="http://validator.w3.org/check?uri=referer">Validate</a></p>
</div>
</body>

5
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>
<!-- 2021-09-15 Wed 13:07 -->
<!-- 2021-09-16 Thu 14:47 -->
<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>
@ -310,6 +310,7 @@ for the JavaScript code in this tag.
<hr />
<ul class="org-ul">
<li><a href="./tutorial_benzene.html">Tutorial</a></li>
<li><a href="./trex.html">Data stored with TREXIO</a></li>
<li><a href="./templator_front.html">Front end API</a></li>
<li><a href="./templator_hdf5.html">HDF5 back end</a></li>
@ -342,7 +343,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: 2021-09-15 Wed 13:07</p>
<p class="date">Created: 2021-09-16 Thu 14:47</p>
<p class="validation"><a href="http://validator.w3.org/check?uri=referer">Validate</a></p>
</div>
</body>

320
templator_front.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>
<!-- 2021-09-15 Wed 13:06 -->
<!-- 2021-09-16 Thu 14:47 -->
<meta http-equiv="Content-Type" content="text/html;charset=utf-8" />
<meta name="viewport" content="width=device-width, initial-scale=1" />
<title>Front end API</title>
@ -333,106 +333,106 @@ for the JavaScript code in this tag.
<h2>Table of Contents</h2>
<div id="text-table-of-contents">
<ul>
<li><a href="#org984de03">1. Coding conventions</a>
<li><a href="#orgac91e51">1. Coding conventions</a>
<ul>
<li><a href="#orgd6d2efd">1.1. Memory allocation</a></li>
<li><a href="#org7303f5d">1.1. Memory allocation</a></li>
</ul>
</li>
<li><a href="#org241ce29">2. Front end</a>
<li><a href="#org0ed731c">2. Front end</a>
<ul>
<li><a href="#org22db94d">2.1. Error handling</a>
<li><a href="#orgad4bf32">2.1. Error handling</a>
<ul>
<li><a href="#orga4a3f6c">2.1.1. Decoding errors</a>
<li><a href="#org0c590e0">2.1.1. Decoding errors</a>
<ul>
<li><a href="#org6c83ee2">2.1.1.1. C source code</a></li>
<li><a href="#orgccbca7b">2.1.1.2. Fortran interface</a></li>
<li><a href="#orgc9829f7">2.1.1.3. Python interface</a></li>
<li><a href="#orgfb3cc49">2.1.1.1. C source code</a></li>
<li><a href="#org9a5bddc">2.1.1.2. Fortran interface</a></li>
<li><a href="#orgb5b685d">2.1.1.3. Python interface</a></li>
</ul>
</li>
</ul>
</li>
<li><a href="#orgb75cf2f">2.2. Back ends</a>
<li><a href="#org010ba58">2.2. Back ends</a>
<ul>
<li><a href="#org81475d7">2.2.1. C</a></li>
<li><a href="#org231759d">2.2.2. Fortran</a></li>
<li><a href="#orgbc7af20">2.2.3. Python</a></li>
<li><a href="#orgceba57c">2.2.1. C</a></li>
<li><a href="#org6672d17">2.2.2. Fortran</a></li>
<li><a href="#org040bab1">2.2.3. Python</a></li>
</ul>
</li>
<li><a href="#org52357bf">2.3. Read/write behavior</a></li>
<li><a href="#org9763ecd">2.4. TREXIO file type</a>
<li><a href="#orgf8ad563">2.3. Read/write behavior</a></li>
<li><a href="#org940788e">2.4. TREXIO file type</a>
<ul>
<li><a href="#orga26e31f">2.4.1. TREXIO<sub>File</sub> Python class</a></li>
<li><a href="#orga619b31">2.4.1. TREXIO<sub>File</sub> Python class</a></li>
</ul>
</li>
<li><a href="#orgf8c651f">2.5. Polymorphism of the file handle</a></li>
<li><a href="#orgebf7145">2.6. File opening</a>
<li><a href="#orga7947c3">2.5. Polymorphism of the file handle</a></li>
<li><a href="#org95af478">2.6. File opening</a>
<ul>
<li><a href="#org058be08">2.6.1. C</a></li>
<li><a href="#org47bc42b">2.6.2. Fortran</a></li>
<li><a href="#org642eafe">2.6.3. Python</a></li>
<li><a href="#org0fb886f">2.6.4. Zero-based versus one-based arrays of indices</a></li>
<li><a href="#org69ff763">2.6.1. C</a></li>
<li><a href="#orgb66bef1">2.6.2. Fortran</a></li>
<li><a href="#orgdac714f">2.6.3. Python</a></li>
<li><a href="#org723d54b">2.6.4. Zero-based versus one-based arrays of indices</a></li>
</ul>
</li>
<li><a href="#org1fc4eeb">2.7. File closing</a>
<li><a href="#org2c095ce">2.7. File closing</a>
<ul>
<li><a href="#orgc296e4d">2.7.1. C</a></li>
<li><a href="#orga9c31b6">2.7.2. Fortran</a></li>
<li><a href="#org8181484">2.7.3. Python</a></li>
<li><a href="#orga522a7a">2.7.1. C</a></li>
<li><a href="#org8df0c7d">2.7.2. Fortran</a></li>
<li><a href="#orge504b2b">2.7.3. Python</a></li>
</ul>
</li>
</ul>
</li>
<li><a href="#org8bc44b2">3. Templates for front end</a>
<li><a href="#orgdaf108d">3. Templates for front end</a>
<ul>
<li><a href="#org394dada">3.1. Description</a></li>
<li><a href="#orgb25378b">3.2. Templates for front end has/read/write a single dimensioning variable</a>
<li><a href="#org22d4aa1">3.1. Description</a></li>
<li><a href="#orgd284f46">3.2. Templates for front end has/read/write a single dimensioning variable</a>
<ul>
<li><a href="#org77ca9ca">3.2.1. C templates for front end</a></li>
<li><a href="#org2089333">3.2.2. Fortran templates for front end</a></li>
<li><a href="#orga00d424">3.2.3. Python templates for front end</a></li>
<li><a href="#org2b27120">3.2.1. C templates for front end</a></li>
<li><a href="#org0ee88e6">3.2.2. Fortran templates for front end</a></li>
<li><a href="#orge0091a8">3.2.3. Python templates for front end</a></li>
</ul>
</li>
<li><a href="#org75c6b46">3.3. Templates for front end has/read/write a dataset of numerical data</a>
<li><a href="#org16b99a8">3.3. Templates for front end has/read/write a dataset of numerical data</a>
<ul>
<li><a href="#orgb7527c4">3.3.1. C templates for front end</a>
<li><a href="#org5e03693">3.3.1. C templates for front end</a>
<ul>
<li><a href="#orgd01611a">3.3.1.1. Function declarations</a></li>
<li><a href="#org19ce40d">3.3.1.2. Source code for double precision functions</a></li>
<li><a href="#orgf8f7be2">3.3.1.3. Source code for single precision functions</a></li>
<li><a href="#org2d0b973">3.3.1.4. Source code for memory-safe functions</a></li>
<li><a href="#org24c36b3">3.3.1.5. Source code for default functions</a></li>
<li><a href="#org08b5207">3.3.1.1. Function declarations</a></li>
<li><a href="#org18b002f">3.3.1.2. Source code for double precision functions</a></li>
<li><a href="#orgf1d90ef">3.3.1.3. Source code for single precision functions</a></li>
<li><a href="#org50d0cb1">3.3.1.4. Source code for memory-safe functions</a></li>
<li><a href="#org3ee523b">3.3.1.5. Source code for default functions</a></li>
</ul>
</li>
<li><a href="#orgc45dcd8">3.3.2. Fortran templates for front end</a></li>
<li><a href="#org538a288">3.3.3. Python templates for front end</a></li>
<li><a href="#org6e6b777">3.3.2. Fortran templates for front end</a></li>
<li><a href="#orgebb89b1">3.3.3. Python templates for front end</a></li>
</ul>
</li>
<li><a href="#org1a56fcf">3.4. Sparse data structures</a></li>
<li><a href="#org927b7bf">3.5. Templates for front end has/read/write a dataset of strings</a>
<li><a href="#orgee32a13">3.4. Sparse data structures</a></li>
<li><a href="#org513c03a">3.5. Templates for front end has/read/write a dataset of strings</a>
<ul>
<li><a href="#orgc0e60b5">3.5.1. Introduction</a></li>
<li><a href="#org5a27aec">3.5.2. C templates for front end</a></li>
<li><a href="#orgf88af50">3.5.3. Fortran templates for front end</a></li>
<li><a href="#org11cf704">3.5.4. Python templates for front end</a></li>
<li><a href="#orgdf1d0d1">3.5.1. Introduction</a></li>
<li><a href="#org35ba109">3.5.2. C templates for front end</a></li>
<li><a href="#org1e652ee">3.5.3. Fortran templates for front end</a></li>
<li><a href="#orgd6a6924">3.5.4. Python templates for front end</a></li>
</ul>
</li>
<li><a href="#org76dd5c9">3.6. Templates for front end has/read/write a single string attribute</a>
<li><a href="#org5deaed0">3.6. Templates for front end has/read/write a single string attribute</a>
<ul>
<li><a href="#org67a723a">3.6.1. Introduction</a></li>
<li><a href="#orgf341153">3.6.2. C templates for front end</a></li>
<li><a href="#org834801b">3.6.3. Fortran templates for front end</a></li>
<li><a href="#org7e80c7b">3.6.4. Python templates for front end</a></li>
<li><a href="#org414340f">3.6.1. Introduction</a></li>
<li><a href="#orgc82d373">3.6.2. C templates for front end</a></li>
<li><a href="#orgbb17101">3.6.3. Fortran templates for front end</a></li>
<li><a href="#orgb00c204">3.6.4. Python templates for front end</a></li>
</ul>
</li>
</ul>
</li>
<li><a href="#orgda42059">4. Fortran helper/wrapper functions</a></li>
<li><a href="#org7bba65f">4. Fortran helper/wrapper functions</a></li>
</ul>
</div>
</div>
<div id="outline-container-org984de03" class="outline-2">
<h2 id="org984de03"><span class="section-number-2">1</span> Coding conventions</h2>
<div id="outline-container-orgac91e51" class="outline-2">
<h2 id="orgac91e51"><span class="section-number-2">1</span> Coding conventions</h2>
<div class="outline-text-2" id="text-1">
<ul class="org-ul">
<li>integer types will be defined using types given in <code>stdint.h</code></li>
@ -447,8 +447,8 @@ for the JavaScript code in this tag.
</ul>
</div>
<div id="outline-container-orgd6d2efd" class="outline-3">
<h3 id="orgd6d2efd"><span class="section-number-3">1.1</span> Memory allocation</h3>
<div id="outline-container-org7303f5d" class="outline-3">
<h3 id="org7303f5d"><span class="section-number-3">1.1</span> Memory allocation</h3>
<div class="outline-text-3" id="text-1-1">
<p>
Memory allocation of structures can be facilitated by using the
@ -483,8 +483,8 @@ The maximum string size for the filenames is 4096 characters.
</div>
</div>
<div id="outline-container-org241ce29" class="outline-2">
<h2 id="org241ce29"><span class="section-number-2">2</span> Front end</h2>
<div id="outline-container-org0ed731c" class="outline-2">
<h2 id="org0ed731c"><span class="section-number-2">2</span> Front end</h2>
<div class="outline-text-2" id="text-2">
<p>
All calls to TREXIO are thread-safe.
@ -492,10 +492,10 @@ TREXIO front end is modular, which simplifies implementation of new back ends.
</p>
</div>
<div id="outline-container-org22db94d" class="outline-3">
<h3 id="org22db94d"><span class="section-number-3">2.1</span> Error handling</h3>
<div id="outline-container-orgad4bf32" class="outline-3">
<h3 id="orgad4bf32"><span class="section-number-3">2.1</span> Error handling</h3>
<div class="outline-text-3" id="text-2-1">
<table id="org31b49f9" border="2" cellspacing="0" cellpadding="6" rules="groups" frame="hsides">
<table id="org1606e6d" border="2" cellspacing="0" cellpadding="6" rules="groups" frame="hsides">
<colgroup>
@ -717,8 +717,8 @@ TREXIO front end is modular, which simplifies implementation of new back ends.
</div>
</div>
<div id="outline-container-orga4a3f6c" class="outline-4">
<h4 id="orga4a3f6c"><span class="section-number-4">2.1.1</span> Decoding errors</h4>
<div id="outline-container-org0c590e0" class="outline-4">
<h4 id="org0c590e0"><span class="section-number-4">2.1.1</span> Decoding errors</h4>
<div class="outline-text-4" id="text-2-1-1">
<p>
The <code>trexio_string_of_error</code> converts an exit code into a string. The
@ -741,8 +741,8 @@ The text strings are extracted from the previous table.
</p>
</div>
<div id="outline-container-org6c83ee2" class="outline-5">
<h5 id="org6c83ee2"><span class="section-number-5">2.1.1.1</span> C source code</h5>
<div id="outline-container-orgfb3cc49" class="outline-5">
<h5 id="orgfb3cc49"><span class="section-number-5">2.1.1.1</span> C source code</h5>
<div class="outline-text-5" id="text-2-1-1-1">
<div class="org-src-container">
<pre class="src src-c"><span style="color: #a020f0;">const</span> <span style="color: #228b22;">char</span>*
@ -847,8 +847,8 @@ The text strings are extracted from the previous table.
</div>
</div>
<div id="outline-container-orgccbca7b" class="outline-5">
<h5 id="orgccbca7b"><span class="section-number-5">2.1.1.2</span> Fortran interface</h5>
<div id="outline-container-org9a5bddc" class="outline-5">
<h5 id="org9a5bddc"><span class="section-number-5">2.1.1.2</span> Fortran interface</h5>
<div class="outline-text-5" id="text-2-1-1-2">
<div class="org-src-container">
<pre class="src src-f90"><span style="color: #a020f0;">interface</span>
@ -864,8 +864,8 @@ The text strings are extracted from the previous table.
</div>
</div>
<div id="outline-container-orgc9829f7" class="outline-5">
<h5 id="orgc9829f7"><span class="section-number-5">2.1.1.3</span> Python interface</h5>
<div id="outline-container-orgb5b685d" class="outline-5">
<h5 id="orgb5b685d"><span class="section-number-5">2.1.1.3</span> Python interface</h5>
<div class="outline-text-5" id="text-2-1-1-3">
<div class="org-src-container">
<pre class="src src-python"><span style="color: #a020f0;">class</span> <span style="color: #228b22;">Error</span>(<span style="color: #228b22;">Exception</span>):
@ -904,8 +904,8 @@ The text strings are extracted from the previous table.
</div>
</div>
<div id="outline-container-orgb75cf2f" class="outline-3">
<h3 id="orgb75cf2f"><span class="section-number-3">2.2</span> Back ends</h3>
<div id="outline-container-org010ba58" class="outline-3">
<h3 id="org010ba58"><span class="section-number-3">2.2</span> Back ends</h3>
<div class="outline-text-3" id="text-2-2">
<p>
TREXIO has several back ends:
@ -929,8 +929,8 @@ lines that correspond to the <code>TREXIO_JSON</code> back end (not implemented
</p>
</div>
<div id="outline-container-org81475d7" class="outline-4">
<h4 id="org81475d7"><span class="section-number-4">2.2.1</span> C</h4>
<div id="outline-container-orgceba57c" class="outline-4">
<h4 id="orgceba57c"><span class="section-number-4">2.2.1</span> C</h4>
<div class="outline-text-4" id="text-2-2-1">
<div class="org-src-container">
<pre class="src src-c"><span style="color: #a020f0;">typedef</span> <span style="color: #228b22;">int32_t</span> <span style="color: #228b22;">back_end_t</span>;
@ -946,8 +946,8 @@ lines that correspond to the <code>TREXIO_JSON</code> back end (not implemented
</div>
</div>
<div id="outline-container-org231759d" class="outline-4">
<h4 id="org231759d"><span class="section-number-4">2.2.2</span> Fortran</h4>
<div id="outline-container-org6672d17" class="outline-4">
<h4 id="org6672d17"><span class="section-number-4">2.2.2</span> Fortran</h4>
<div class="outline-text-4" id="text-2-2-2">
<div class="org-src-container">
<pre class="src src-f90"> <span style="color: #228b22;">integer</span>(trexio_backend), <span style="color: #a020f0;">parameter</span> ::<span style="color: #a0522d;"> TREXIO_HDF5 = 0</span>
@ -959,8 +959,8 @@ lines that correspond to the <code>TREXIO_JSON</code> back end (not implemented
</div>
</div>
<div id="outline-container-orgbc7af20" class="outline-4">
<h4 id="orgbc7af20"><span class="section-number-4">2.2.3</span> Python</h4>
<div id="outline-container-org040bab1" class="outline-4">
<h4 id="org040bab1"><span class="section-number-4">2.2.3</span> Python</h4>
<div class="outline-text-4" id="text-2-2-3">
<div class="org-src-container">
<pre class="src src-python"># <span style="color: #b22222;">define TREXIO back ends</span>
@ -974,8 +974,8 @@ lines that correspond to the <code>TREXIO_JSON</code> back end (not implemented
</div>
</div>
<div id="outline-container-org52357bf" class="outline-3">
<h3 id="org52357bf"><span class="section-number-3">2.3</span> Read/write behavior</h3>
<div id="outline-container-orgf8ad563" class="outline-3">
<h3 id="orgf8ad563"><span class="section-number-3">2.3</span> Read/write behavior</h3>
<div class="outline-text-3" id="text-2-3">
<p>
Every time a reading function is called, the data is read from the
@ -1003,8 +1003,8 @@ concurrent programs, the behavior is not specified.
</p>
</div>
</div>
<div id="outline-container-org9763ecd" class="outline-3">
<h3 id="org9763ecd"><span class="section-number-3">2.4</span> TREXIO file type</h3>
<div id="outline-container-org940788e" class="outline-3">
<h3 id="org940788e"><span class="section-number-3">2.4</span> TREXIO file type</h3>
<div class="outline-text-3" id="text-2-4">
<p>
<code>trexio_s</code> is the the main type for TREXIO files, visible to the users
@ -1038,8 +1038,8 @@ TREXIO files will have as a first argument the TREXIO file handle.
</div>
</div>
<div id="outline-container-orga26e31f" class="outline-4">
<h4 id="orga26e31f"><span class="section-number-4">2.4.1</span> TREXIO<sub>File</sub> Python class</h4>
<div id="outline-container-orga619b31" class="outline-4">
<h4 id="orga619b31"><span class="section-number-4">2.4.1</span> TREXIO<sub>File</sub> Python class</h4>
<div class="outline-text-4" id="text-2-4-1">
<div class="org-src-container">
<pre class="src src-python"><span style="color: #a020f0;">class</span> <span style="color: #228b22;">File</span>:
@ -1112,8 +1112,8 @@ TREXIO files will have as a first argument the TREXIO file handle.
</div>
</div>
<div id="outline-container-orgf8c651f" class="outline-3">
<h3 id="orgf8c651f"><span class="section-number-3">2.5</span> Polymorphism of the file handle</h3>
<div id="outline-container-orga7947c3" class="outline-3">
<h3 id="orga7947c3"><span class="section-number-3">2.5</span> Polymorphism of the file handle</h3>
<div class="outline-text-3" id="text-2-5">
<p>
Polymorphism of the <code>trexio_t</code> type is handled by ensuring that the
@ -1132,8 +1132,8 @@ corresponding types for all back ends can be safely casted to
</div>
</div>
<div id="outline-container-orgebf7145" class="outline-3">
<h3 id="orgebf7145"><span class="section-number-3">2.6</span> File opening</h3>
<div id="outline-container-org95af478" class="outline-3">
<h3 id="org95af478"><span class="section-number-3">2.6</span> File opening</h3>
<div class="outline-text-3" id="text-2-6">
<p>
<code>trexio_open</code> creates a new TREXIO file or opens existing one.
@ -1172,8 +1172,8 @@ renaming the <code>.txt</code> data files.
</p>
</div>
<div id="outline-container-org058be08" class="outline-4">
<h4 id="org058be08"><span class="section-number-4">2.6.1</span> C</h4>
<div id="outline-container-org69ff763" class="outline-4">
<h4 id="org69ff763"><span class="section-number-4">2.6.1</span> C</h4>
<div class="outline-text-4" id="text-2-6-1">
<div class="org-src-container">
<pre class="src src-c"><span style="color: #228b22;">trexio_t</span>*
@ -1327,8 +1327,8 @@ renaming the <code>.txt</code> data files.
</div>
</div>
<div id="outline-container-org47bc42b" class="outline-4">
<h4 id="org47bc42b"><span class="section-number-4">2.6.2</span> Fortran</h4>
<div id="outline-container-orgb66bef1" class="outline-4">
<h4 id="orgb66bef1"><span class="section-number-4">2.6.2</span> Fortran</h4>
<div class="outline-text-4" id="text-2-6-2">
<div class="org-src-container">
<pre class="src src-f90"><span style="color: #a020f0;">interface</span>
@ -1345,8 +1345,8 @@ renaming the <code>.txt</code> data files.
</div>
</div>
<div id="outline-container-org642eafe" class="outline-4">
<h4 id="org642eafe"><span class="section-number-4">2.6.3</span> Python</h4>
<div id="outline-container-orgdac714f" class="outline-4">
<h4 id="orgdac714f"><span class="section-number-4">2.6.3</span> Python</h4>
<div class="outline-text-4" id="text-2-6-3">
<div class="org-src-container">
<pre class="src src-python"><span style="color: #a020f0;">def</span> <span style="color: #0000ff;">open</span>(file_name: <span style="color: #483d8b;">str</span>, mode: <span style="color: #483d8b;">str</span>, back_end: <span style="color: #483d8b;">int</span>):
@ -1383,8 +1383,8 @@ renaming the <code>.txt</code> data files.
</div>
</div>
<div id="outline-container-org0fb886f" class="outline-4">
<h4 id="org0fb886f"><span class="section-number-4">2.6.4</span> Zero-based versus one-based arrays of indices</h4>
<div id="outline-container-org723d54b" class="outline-4">
<h4 id="org723d54b"><span class="section-number-4">2.6.4</span> Zero-based versus one-based arrays of indices</h4>
<div class="outline-text-4" id="text-2-6-4">
<p>
Because arrays are zero-based in Fortran, we need to set a flag to
@ -1417,8 +1417,8 @@ know if we need to shift by 1 arrays of indices.
</div>
</div>
<div id="outline-container-org1fc4eeb" class="outline-3">
<h3 id="org1fc4eeb"><span class="section-number-3">2.7</span> File closing</h3>
<div id="outline-container-org2c095ce" class="outline-3">
<h3 id="org2c095ce"><span class="section-number-3">2.7</span> File closing</h3>
<div class="outline-text-3" id="text-2-7">
<p>
<code>trexio_close</code> closes an existing <code>trexio_t</code> file.
@ -1435,8 +1435,8 @@ output:
</p>
</div>
<div id="outline-container-orgc296e4d" class="outline-4">
<h4 id="orgc296e4d"><span class="section-number-4">2.7.1</span> C</h4>
<div id="outline-container-orga522a7a" class="outline-4">
<h4 id="orga522a7a"><span class="section-number-4">2.7.1</span> C</h4>
<div class="outline-text-4" id="text-2-7-1">
<div class="org-src-container">
<pre class="src src-c"><span style="color: #228b22;">trexio_exit_code</span>
@ -1507,8 +1507,8 @@ output:
</div>
</div>
<div id="outline-container-orga9c31b6" class="outline-4">
<h4 id="orga9c31b6"><span class="section-number-4">2.7.2</span> Fortran</h4>
<div id="outline-container-org8df0c7d" class="outline-4">
<h4 id="org8df0c7d"><span class="section-number-4">2.7.2</span> Fortran</h4>
<div class="outline-text-4" id="text-2-7-2">
<div class="org-src-container">
<pre class="src src-f90"><span style="color: #a020f0;">interface</span>
@ -1522,8 +1522,8 @@ output:
</div>
</div>
<div id="outline-container-org8181484" class="outline-4">
<h4 id="org8181484"><span class="section-number-4">2.7.3</span> Python</h4>
<div id="outline-container-orge504b2b" class="outline-4">
<h4 id="orge504b2b"><span class="section-number-4">2.7.3</span> Python</h4>
<div class="outline-text-4" id="text-2-7-3">
<div class="org-src-container">
<pre class="src src-python"><span style="color: #a020f0;">def</span> <span style="color: #0000ff;">close</span>(trexio_file):
@ -1545,12 +1545,12 @@ output:
</div>
</div>
<div id="outline-container-org8bc44b2" class="outline-2">
<h2 id="org8bc44b2"><span class="section-number-2">3</span> Templates for front end</h2>
<div id="outline-container-orgdaf108d" class="outline-2">
<h2 id="orgdaf108d"><span class="section-number-2">3</span> Templates for front end</h2>
<div class="outline-text-2" id="text-3">
</div>
<div id="outline-container-org394dada" class="outline-3">
<h3 id="org394dada"><span class="section-number-3">3.1</span> Description</h3>
<div id="outline-container-org22d4aa1" class="outline-3">
<h3 id="org22d4aa1"><span class="section-number-3">3.1</span> Description</h3>
<div class="outline-text-3" id="text-3-1">
<p>
Consider the following block of <code>trex.json</code>:
@ -1746,8 +1746,8 @@ or double precision for integer and floating point numbers.
</div>
</div>
<div id="outline-container-orgb25378b" class="outline-3">
<h3 id="orgb25378b"><span class="section-number-3">3.2</span> Templates for front end has/read/write a single dimensioning variable</h3>
<div id="outline-container-orgd284f46" class="outline-3">
<h3 id="orgd284f46"><span class="section-number-3">3.2</span> Templates for front end has/read/write a single dimensioning variable</h3>
<div class="outline-text-3" id="text-3-2">
<p>
This section concerns API calls related to dimensioning variables.
@ -1816,8 +1816,8 @@ This section concerns API calls related to dimensioning variables.
</table>
</div>
<div id="outline-container-org77ca9ca" class="outline-4">
<h4 id="org77ca9ca"><span class="section-number-4">3.2.1</span> C templates for front end</h4>
<div id="outline-container-org2b27120" class="outline-4">
<h4 id="org2b27120"><span class="section-number-4">3.2.1</span> C templates for front end</h4>
<div class="outline-text-4" id="text-3-2-1">
<p>
The <code>C</code> templates that correspond to each of the abovementioned
@ -2008,8 +2008,8 @@ precision (see Table above).
</div>
</div>
<div id="outline-container-org2089333" class="outline-4">
<h4 id="org2089333"><span class="section-number-4">3.2.2</span> Fortran templates for front end</h4>
<div id="outline-container-org0ee88e6" class="outline-4">
<h4 id="org0ee88e6"><span class="section-number-4">3.2.2</span> Fortran templates for front end</h4>
<div class="outline-text-4" id="text-3-2-2">
<p>
The <code>Fortran</code> templates that provide an access to the <code>C</code> API calls from Fortran.
@ -2094,8 +2094,8 @@ These templates are based on the use of <code>iso_c_binding</code>. Pointers hav
</div>
</div>
<div id="outline-container-orga00d424" class="outline-4">
<h4 id="orga00d424"><span class="section-number-4">3.2.3</span> Python templates for front end</h4>
<div id="outline-container-orge0091a8" class="outline-4">
<h4 id="orge0091a8"><span class="section-number-4">3.2.3</span> Python templates for front end</h4>
<div class="outline-text-4" id="text-3-2-3">
<div class="org-src-container">
<pre class="src src-python"><span style="color: #a020f0;">def</span> <span style="color: #0000ff;">write_</span>$group_num$(trexio_file, num_w: <span style="color: #483d8b;">int</span>) -&gt; <span style="color: #008b8b;">None</span>:
@ -2180,8 +2180,8 @@ These templates are based on the use of <code>iso_c_binding</code>. Pointers hav
</div>
</div>
<div id="outline-container-org75c6b46" class="outline-3">
<h3 id="org75c6b46"><span class="section-number-3">3.3</span> Templates for front end has/read/write a dataset of numerical data</h3>
<div id="outline-container-org16b99a8" class="outline-3">
<h3 id="org16b99a8"><span class="section-number-3">3.3</span> Templates for front end has/read/write a dataset of numerical data</h3>
<div class="outline-text-3" id="text-3-3">
<p>
This section concerns API calls related to datasets.
@ -2262,8 +2262,8 @@ This section concerns API calls related to datasets.
</table>
</div>
<div id="outline-container-orgb7527c4" class="outline-4">
<h4 id="orgb7527c4"><span class="section-number-4">3.3.1</span> C templates for front end</h4>
<div id="outline-container-org5e03693" class="outline-4">
<h4 id="org5e03693"><span class="section-number-4">3.3.1</span> C templates for front end</h4>
<div class="outline-text-4" id="text-3-3-1">
<p>
The C templates that correspond to each of the abovementioned functions can be found below.
@ -2274,13 +2274,13 @@ The basic (non-suffixed) API call on datasets deals with double precision (see T
</p>
</div>
<div id="outline-container-orgd01611a" class="outline-5">
<h5 id="orgd01611a"><span class="section-number-5">3.3.1.1</span> Function declarations</h5>
<div id="outline-container-org08b5207" class="outline-5">
<h5 id="org08b5207"><span class="section-number-5">3.3.1.1</span> Function declarations</h5>
</div>
<div id="outline-container-org19ce40d" class="outline-5">
<h5 id="org19ce40d"><span class="section-number-5">3.3.1.2</span> Source code for double precision functions</h5>
<div id="outline-container-org18b002f" class="outline-5">
<h5 id="org18b002f"><span class="section-number-5">3.3.1.2</span> Source code for double precision functions</h5>
<div class="outline-text-5" id="text-3-3-1-2">
<div class="org-src-container">
<pre class="src src-c"><span style="color: #228b22;">trexio_exit_code</span>
@ -2408,8 +2408,8 @@ The basic (non-suffixed) API call on datasets deals with double precision (see T
</div>
</div>
<div id="outline-container-orgf8f7be2" class="outline-5">
<h5 id="orgf8f7be2"><span class="section-number-5">3.3.1.3</span> Source code for single precision functions</h5>
<div id="outline-container-orgf1d90ef" class="outline-5">
<h5 id="orgf1d90ef"><span class="section-number-5">3.3.1.3</span> Source code for single precision functions</h5>
<div class="outline-text-5" id="text-3-3-1-3">
<div class="org-src-container">
<pre class="src src-c"><span style="color: #228b22;">trexio_exit_code</span>
@ -2550,11 +2550,11 @@ The basic (non-suffixed) API call on datasets deals with double precision (see T
</div>
</div>
<div id="outline-container-org2d0b973" class="outline-5">
<h5 id="org2d0b973"><span class="section-number-5">3.3.1.4</span> Source code for memory-safe functions</h5>
<div id="outline-container-org50d0cb1" class="outline-5">
<h5 id="org50d0cb1"><span class="section-number-5">3.3.1.4</span> Source code for memory-safe functions</h5>
<div class="outline-text-5" id="text-3-3-1-4">
<div class="org-src-container">
<pre class="src src-c" id="org2795a23"><span style="color: #228b22;">trexio_exit_code</span> <span style="color: #a0522d;">rc</span>;
<pre class="src src-c" id="org7f2c2e7"><span style="color: #228b22;">trexio_exit_code</span> <span style="color: #a0522d;">rc</span>;
int64_t $group_dset_dim$ = 0;
/* <span style="color: #b22222;">Error handling for this call is added by the generator </span>*/
@ -2710,8 +2710,8 @@ rc = trexio_read_$group_dset_dim$_64(file, &amp;($group_dset_dim$));
</div>
</div>
<div id="outline-container-org24c36b3" class="outline-5">
<h5 id="org24c36b3"><span class="section-number-5">3.3.1.5</span> Source code for default functions</h5>
<div id="outline-container-org3ee523b" class="outline-5">
<h5 id="org3ee523b"><span class="section-number-5">3.3.1.5</span> Source code for default functions</h5>
<div class="outline-text-5" id="text-3-3-1-5">
<div class="org-src-container">
<pre class="src src-c"><span style="color: #228b22;">trexio_exit_code</span>
@ -2785,8 +2785,8 @@ rc = trexio_read_$group_dset_dim$_64(file, &amp;($group_dset_dim$));
</div>
</div>
<div id="outline-container-orgc45dcd8" class="outline-4">
<h4 id="orgc45dcd8"><span class="section-number-4">3.3.2</span> Fortran templates for front end</h4>
<div id="outline-container-org6e6b777" class="outline-4">
<h4 id="org6e6b777"><span class="section-number-4">3.3.2</span> Fortran templates for front end</h4>
<div class="outline-text-4" id="text-3-3-2">
<p>
The <code>Fortran</code> templates that provide an access to the <code>C</code> API calls from <code>Fortran</code>.
@ -2871,8 +2871,8 @@ These templates are based on the use of <code>iso_c_binding</code>. Pointers hav
</div>
</div>
<div id="outline-container-org538a288" class="outline-4">
<h4 id="org538a288"><span class="section-number-4">3.3.3</span> Python templates for front end</h4>
<div id="outline-container-orgebb89b1" class="outline-4">
<h4 id="orgebb89b1"><span class="section-number-4">3.3.3</span> Python templates for front end</h4>
<div class="outline-text-4" id="text-3-3-3">
<div class="org-src-container">
<pre class="src src-python"><span style="color: #a020f0;">def</span> <span style="color: #0000ff;">write_</span>$group_dset$(trexio_file, dset_w) -&gt; <span style="color: #008b8b;">None</span>:
@ -3067,8 +3067,8 @@ These templates are based on the use of <code>iso_c_binding</code>. Pointers hav
</div>
</div>
<div id="outline-container-org1a56fcf" class="outline-3">
<h3 id="org1a56fcf"><span class="section-number-3">3.4</span> Sparse data structures</h3>
<div id="outline-container-orgee32a13" class="outline-3">
<h3 id="orgee32a13"><span class="section-number-3">3.4</span> Sparse data structures</h3>
<div class="outline-text-3" id="text-3-4">
<p>
Sparse data structures are used typically for large tensors such as
@ -3209,12 +3209,12 @@ For the values,
</div>
</div>
<div id="outline-container-org927b7bf" class="outline-3">
<h3 id="org927b7bf"><span class="section-number-3">3.5</span> Templates for front end has/read/write a dataset of strings</h3>
<div id="outline-container-org513c03a" class="outline-3">
<h3 id="org513c03a"><span class="section-number-3">3.5</span> Templates for front end has/read/write a dataset of strings</h3>
<div class="outline-text-3" id="text-3-5">
</div>
<div id="outline-container-orgc0e60b5" class="outline-4">
<h4 id="orgc0e60b5"><span class="section-number-4">3.5.1</span> Introduction</h4>
<div id="outline-container-orgdf1d0d1" class="outline-4">
<h4 id="orgdf1d0d1"><span class="section-number-4">3.5.1</span> Introduction</h4>
<div class="outline-text-4" id="text-3-5-1">
<p>
This section concerns API calls related to datasets of strings.
@ -3254,8 +3254,8 @@ This section concerns API calls related to datasets of strings.
</div>
</div>
<div id="outline-container-org5a27aec" class="outline-4">
<h4 id="org5a27aec"><span class="section-number-4">3.5.2</span> C templates for front end</h4>
<div id="outline-container-org35ba109" class="outline-4">
<h4 id="org35ba109"><span class="section-number-4">3.5.2</span> C templates for front end</h4>
<div class="outline-text-4" id="text-3-5-2">
<p>
First parameter is the <code>TREXIO</code> file handle. Second parameter is the variable to be written/read
@ -3502,8 +3502,8 @@ to/from the <code>TREXIO</code> file (except for <code>trexio_has_</code> functi
</div>
</div>
<div id="outline-container-orgf88af50" class="outline-4">
<h4 id="orgf88af50"><span class="section-number-4">3.5.3</span> Fortran templates for front end</h4>
<div id="outline-container-org1e652ee" class="outline-4">
<h4 id="org1e652ee"><span class="section-number-4">3.5.3</span> Fortran templates for front end</h4>
<div class="outline-text-4" id="text-3-5-3">
<p>
The <code>Fortran</code> templates that provide an access to the <code>C</code> API calls from <code>Fortran</code>.
@ -3599,8 +3599,8 @@ These templates are based on the use of <code>iso_c_binding</code>. Pointers hav
</div>
</div>
<div id="outline-container-org11cf704" class="outline-4">
<h4 id="org11cf704"><span class="section-number-4">3.5.4</span> Python templates for front end</h4>
<div id="outline-container-orgd6a6924" class="outline-4">
<h4 id="orgd6a6924"><span class="section-number-4">3.5.4</span> Python templates for front end</h4>
<div class="outline-text-4" id="text-3-5-4">
<div class="org-src-container">
<pre class="src src-python"><span style="color: #a020f0;">def</span> <span style="color: #0000ff;">write_</span>$group_dset$(trexio_file, dset_w: <span style="color: #483d8b;">list</span>) -&gt; <span style="color: #008b8b;">None</span>:
@ -3716,12 +3716,12 @@ These templates are based on the use of <code>iso_c_binding</code>. Pointers hav
</div>
</div>
<div id="outline-container-org76dd5c9" class="outline-3">
<h3 id="org76dd5c9"><span class="section-number-3">3.6</span> Templates for front end has/read/write a single string attribute</h3>
<div id="outline-container-org5deaed0" class="outline-3">
<h3 id="org5deaed0"><span class="section-number-3">3.6</span> Templates for front end has/read/write a single string attribute</h3>
<div class="outline-text-3" id="text-3-6">
</div>
<div id="outline-container-org67a723a" class="outline-4">
<h4 id="org67a723a"><span class="section-number-4">3.6.1</span> Introduction</h4>
<div id="outline-container-org414340f" class="outline-4">
<h4 id="org414340f"><span class="section-number-4">3.6.1</span> Introduction</h4>
<div class="outline-text-4" id="text-3-6-1">
<p>
This section concerns API calls related to string attributes.
@ -3761,8 +3761,8 @@ This section concerns API calls related to string attributes.
</div>
</div>
<div id="outline-container-orgf341153" class="outline-4">
<h4 id="orgf341153"><span class="section-number-4">3.6.2</span> C templates for front end</h4>
<div id="outline-container-orgc82d373" class="outline-4">
<h4 id="orgc82d373"><span class="section-number-4">3.6.2</span> C templates for front end</h4>
<div class="outline-text-4" id="text-3-6-2">
<div class="org-src-container">
<pre class="src src-c"><span style="color: #228b22;">trexio_exit_code</span>
@ -3861,8 +3861,8 @@ This section concerns API calls related to string attributes.
</div>
</div>
<div id="outline-container-org834801b" class="outline-4">
<h4 id="org834801b"><span class="section-number-4">3.6.3</span> Fortran templates for front end</h4>
<div id="outline-container-orgbb17101" class="outline-4">
<h4 id="orgbb17101"><span class="section-number-4">3.6.3</span> Fortran templates for front end</h4>
<div class="outline-text-4" id="text-3-6-3">
<p>
The <code>Fortran</code> templates that provide an access to the <code>C</code> API calls from Fortran.
@ -3939,8 +3939,8 @@ These templates are based on the use of <code>iso_c_binding</code>. Pointers hav
</div>
</div>
<div id="outline-container-org7e80c7b" class="outline-4">
<h4 id="org7e80c7b"><span class="section-number-4">3.6.4</span> Python templates for front end</h4>
<div id="outline-container-orgb00c204" class="outline-4">
<h4 id="orgb00c204"><span class="section-number-4">3.6.4</span> Python templates for front end</h4>
<div class="outline-text-4" id="text-3-6-4">
<div class="org-src-container">
<pre class="src src-python"><span style="color: #a020f0;">def</span> <span style="color: #0000ff;">write_</span>$group_str$(trexio_file, str_w: <span style="color: #483d8b;">str</span>) -&gt; <span style="color: #008b8b;">None</span>:
@ -4030,8 +4030,8 @@ These templates are based on the use of <code>iso_c_binding</code>. Pointers hav
</div>
</div>
<div id="outline-container-orgda42059" class="outline-2">
<h2 id="orgda42059"><span class="section-number-2">4</span> Fortran helper/wrapper functions</h2>
<div id="outline-container-org7bba65f" class="outline-2">
<h2 id="org7bba65f"><span class="section-number-2">4</span> Fortran helper/wrapper functions</h2>
<div class="outline-text-2" id="text-4">
<p>
The function below adapts the original C-based <code>trexio_open</code> for Fortran.
@ -4165,7 +4165,7 @@ two code are identical, i.e. if the <code>assert</code> statement pass.
</div>
<div id="postamble" class="status">
<p class="author">Author: TREX-CoE</p>
<p class="date">Created: 2021-09-15 Wed 13:06</p>
<p class="date">Created: 2021-09-16 Thu 14:47</p>
<p class="validation"><a href="http://validator.w3.org/check?uri=referer">Validate</a></p>
</div>
</body>

52
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>
<!-- 2021-09-15 Wed 13:07 -->
<!-- 2021-09-16 Thu 14:47 -->
<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>
@ -311,27 +311,27 @@ for the JavaScript code in this tag.
<h2>Table of Contents</h2>
<div id="text-table-of-contents">
<ul>
<li><a href="#org228d36d">1. HDF5 back end</a>
<li><a href="#org26617cc">1. HDF5 back end</a>
<ul>
<li><a href="#org1cda204">1.1. Template for HDF5 definitions</a></li>
<li><a href="#orgf2a3f4f">1.2. Template for HDF5 structures</a></li>
<li><a href="#org64ad849">1.3. Template for HDF5 init/deinit</a></li>
<li><a href="#org3e5a582">1.4. Template for HDF5 has/read/write a single dimensioning variable</a></li>
<li><a href="#org33923b8">1.5. Template for HDF5 has/read/write a dataset of numerical data</a></li>
<li><a href="#orge1afe72">1.6. Template for HDF5 has/read/write a dataset of strings</a></li>
<li><a href="#org92155e5">1.7. Template for HDF5 has/read/write a single string attribute</a></li>
<li><a href="#org61e9dc2">1.1. Template for HDF5 definitions</a></li>
<li><a href="#org07b6511">1.2. Template for HDF5 structures</a></li>
<li><a href="#org6d62c11">1.3. Template for HDF5 init/deinit</a></li>
<li><a href="#orgd4e29e2">1.4. Template for HDF5 has/read/write a single dimensioning variable</a></li>
<li><a href="#org1996ea4">1.5. Template for HDF5 has/read/write a dataset of numerical data</a></li>
<li><a href="#org9f4f182">1.6. Template for HDF5 has/read/write a dataset of strings</a></li>
<li><a href="#orgb952d9b">1.7. Template for HDF5 has/read/write a single string attribute</a></li>
</ul>
</li>
</ul>
</div>
</div>
<div id="outline-container-org228d36d" class="outline-2">
<h2 id="org228d36d"><span class="section-number-2">1</span> HDF5 back end</h2>
<div id="outline-container-org26617cc" class="outline-2">
<h2 id="org26617cc"><span class="section-number-2">1</span> HDF5 back end</h2>
<div class="outline-text-2" id="text-1">
</div>
<div id="outline-container-org1cda204" class="outline-3">
<h3 id="org1cda204"><span class="section-number-3">1.1</span> Template for HDF5 definitions</h3>
<div id="outline-container-org61e9dc2" class="outline-3">
<h3 id="org61e9dc2"><span class="section-number-3">1.1</span> Template for HDF5 definitions</h3>
<div class="outline-text-3" id="text-1-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>
@ -343,8 +343,8 @@ for the JavaScript code in this tag.
</div>
</div>
<div id="outline-container-orgf2a3f4f" class="outline-3">
<h3 id="orgf2a3f4f"><span class="section-number-3">1.2</span> Template for HDF5 structures</h3>
<div id="outline-container-org07b6511" class="outline-3">
<h3 id="org07b6511"><span class="section-number-3">1.2</span> Template for HDF5 structures</h3>
<div class="outline-text-3" id="text-1-2">
<div class="org-src-container">
<pre class="src src-c"><span style="color: #a020f0;">typedef</span> <span style="color: #a020f0;">struct</span> <span style="color: #228b22;">trexio_hdf5_s</span> {
@ -358,8 +358,8 @@ for the JavaScript code in this tag.
</div>
<div id="outline-container-org64ad849" class="outline-3">
<h3 id="org64ad849"><span class="section-number-3">1.3</span> Template for HDF5 init/deinit</h3>
<div id="outline-container-org6d62c11" class="outline-3">
<h3 id="org6d62c11"><span class="section-number-3">1.3</span> Template for HDF5 init/deinit</h3>
<div class="outline-text-3" id="text-1-3">
<div class="org-src-container">
<pre class="src src-c"><span style="color: #228b22;">trexio_exit_code</span>
@ -439,8 +439,8 @@ for the JavaScript code in this tag.
</div>
</div>
<div id="outline-container-org3e5a582" class="outline-3">
<h3 id="org3e5a582"><span class="section-number-3">1.4</span> Template for HDF5 has/read/write a single dimensioning variable</h3>
<div id="outline-container-orgd4e29e2" class="outline-3">
<h3 id="orgd4e29e2"><span class="section-number-3">1.4</span> Template for HDF5 has/read/write a single dimensioning variable</h3>
<div class="outline-text-3" id="text-1-4">
<div class="org-src-container">
<pre class="src src-c"><span style="color: #228b22;">trexio_exit_code</span>
@ -556,8 +556,8 @@ for the JavaScript code in this tag.
</div>
</div>
<div id="outline-container-org33923b8" class="outline-3">
<h3 id="org33923b8"><span class="section-number-3">1.5</span> Template for HDF5 has/read/write a dataset of numerical data</h3>
<div id="outline-container-org1996ea4" class="outline-3">
<h3 id="org1996ea4"><span class="section-number-3">1.5</span> Template for HDF5 has/read/write a dataset of numerical data</h3>
<div class="outline-text-3" id="text-1-5">
<div class="org-src-container">
<pre class="src src-c"><span style="color: #228b22;">trexio_exit_code</span>
@ -686,8 +686,8 @@ for the JavaScript code in this tag.
</div>
</div>
<div id="outline-container-orge1afe72" class="outline-3">
<h3 id="orge1afe72"><span class="section-number-3">1.6</span> Template for HDF5 has/read/write a dataset of strings</h3>
<div id="outline-container-org9f4f182" class="outline-3">
<h3 id="org9f4f182"><span class="section-number-3">1.6</span> Template for HDF5 has/read/write a dataset of strings</h3>
<div class="outline-text-3" id="text-1-6">
<div class="org-src-container">
<pre class="src src-c"><span style="color: #228b22;">trexio_exit_code</span>
@ -898,8 +898,8 @@ for the JavaScript code in this tag.
</div>
</div>
<div id="outline-container-org92155e5" class="outline-3">
<h3 id="org92155e5"><span class="section-number-3">1.7</span> Template for HDF5 has/read/write a single string attribute</h3>
<div id="outline-container-orgb952d9b" class="outline-3">
<h3 id="orgb952d9b"><span class="section-number-3">1.7</span> Template for HDF5 has/read/write a single string attribute</h3>
<div class="outline-text-3" id="text-1-7">
<div class="org-src-container">
<pre class="src src-c"><span style="color: #228b22;">trexio_exit_code</span>
@ -1026,7 +1026,7 @@ for the JavaScript code in this tag.
</div>
<div id="postamble" class="status">
<p class="author">Author: TREX-CoE</p>
<p class="date">Created: 2021-09-15 Wed 13:07</p>
<p class="date">Created: 2021-09-16 Thu 14:47</p>
<p class="validation"><a href="http://validator.w3.org/check?uri=referer">Validate</a></p>
</div>
</body>

112
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>
<!-- 2021-09-15 Wed 13:07 -->
<!-- 2021-09-16 Thu 14:47 -->
<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>
@ -311,26 +311,26 @@ for the JavaScript code in this tag.
<h2>Table of Contents</h2>
<div id="text-table-of-contents">
<ul>
<li><a href="#org1cc3467">1. TEXT back end</a>
<li><a href="#org52f7e07">1. TEXT back end</a>
<ul>
<li><a href="#orgf188342">1.1. Template for group-related structures in text back end</a></li>
<li><a href="#org60279fb">1.2. Template for general structure in text back end</a></li>
<li><a href="#orgc9de416">1.3. Initialize function (constant part)</a></li>
<li><a href="#orgdd7568b">1.4. Deinitialize function (templated part)</a></li>
<li><a href="#org2fa3289">1.5. Template for text read struct</a></li>
<li><a href="#org7030614">1.6. Template for text flush struct</a></li>
<li><a href="#org2f69079">1.7. Template for text free memory</a></li>
<li><a href="#org812e5ca">1.8. Template for has/read/write the num attribute</a></li>
<li><a href="#org7ad639a">1.9. Template for has/read/write the dataset of numerical data</a></li>
<li><a href="#org982e671">1.10. Template for has/read/write the dataset of strings</a></li>
<li><a href="#orgf181cf6">1.11. Template for has/read/write the string attribute</a></li>
<li><a href="#org904841d">1.12. RDM struct (hard-coded)</a>
<li><a href="#org9ec603c">1.1. Template for group-related structures in text back end</a></li>
<li><a href="#org1aaf4f6">1.2. Template for general structure in text back end</a></li>
<li><a href="#org838d52e">1.3. Initialize function (constant part)</a></li>
<li><a href="#org3106705">1.4. Deinitialize function (templated part)</a></li>
<li><a href="#org7810f25">1.5. Template for text read struct</a></li>
<li><a href="#orga899e45">1.6. Template for text flush struct</a></li>
<li><a href="#org4704bff">1.7. Template for text free memory</a></li>
<li><a href="#org98dc9f8">1.8. Template for has/read/write the num attribute</a></li>
<li><a href="#org4e36999">1.9. Template for has/read/write the dataset of numerical data</a></li>
<li><a href="#org62fd780">1.10. Template for has/read/write the dataset of strings</a></li>
<li><a href="#org21d2224">1.11. Template for has/read/write the string attribute</a></li>
<li><a href="#orgaf090f2">1.12. RDM struct (hard-coded)</a>
<ul>
<li><a href="#org64fc9ac">1.12.1. Read the complete struct</a></li>
<li><a href="#org4bc5893">1.12.2. Flush the complete struct</a></li>
<li><a href="#org645a5c2">1.12.3. Free memory</a></li>
<li><a href="#org7e85cb2">1.12.4. Read/Write the one<sub>e</sub> attribute</a></li>
<li><a href="#orgb5fbe79">1.12.5. Read/Write the two<sub>e</sub> attribute</a></li>
<li><a href="#orgcb0d605">1.12.1. Read the complete struct</a></li>
<li><a href="#org58df0ff">1.12.2. Flush the complete struct</a></li>
<li><a href="#org6db163c">1.12.3. Free memory</a></li>
<li><a href="#org750d656">1.12.4. Read/Write the one<sub>e</sub> attribute</a></li>
<li><a href="#org6f559f9">1.12.5. Read/Write the two<sub>e</sub> attribute</a></li>
</ul>
</li>
</ul>
@ -339,8 +339,8 @@ for the JavaScript code in this tag.
</div>
</div>
<div id="outline-container-org1cc3467" class="outline-2">
<h2 id="org1cc3467"><span class="section-number-2">1</span> TEXT back end</h2>
<div id="outline-container-org52f7e07" class="outline-2">
<h2 id="org52f7e07"><span class="section-number-2">1</span> TEXT back end</h2>
<div class="outline-text-2" id="text-1">
<p>
The "file" produced by the text back end is a directory with one
@ -361,8 +361,8 @@ The file is written when closed, or when the flush function is called.
</p>
</div>
<div id="outline-container-orgf188342" class="outline-3">
<h3 id="orgf188342"><span class="section-number-3">1.1</span> Template for group-related structures in text back end</h3>
<div id="outline-container-org9ec603c" class="outline-3">
<h3 id="org9ec603c"><span class="section-number-3">1.1</span> Template for group-related structures in text back end</h3>
<div class="outline-text-3" id="text-1-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 {
@ -380,8 +380,8 @@ The file is written when closed, or when the flush function is called.
</div>
</div>
<div id="outline-container-org60279fb" class="outline-3">
<h3 id="org60279fb"><span class="section-number-3">1.2</span> Template for general structure in text back end</h3>
<div id="outline-container-org1aaf4f6" class="outline-3">
<h3 id="org1aaf4f6"><span class="section-number-3">1.2</span> Template for general structure in text back end</h3>
<div class="outline-text-3" id="text-1-2">
<div class="org-src-container">
<pre class="src src-c"><span style="color: #a020f0;">typedef</span> <span style="color: #a020f0;">struct</span> <span style="color: #228b22;">rdm_s</span> {
@ -407,8 +407,8 @@ The file is written when closed, or when the flush function is called.
</div>
</div>
<div id="outline-container-orgc9de416" class="outline-3">
<h3 id="orgc9de416"><span class="section-number-3">1.3</span> Initialize function (constant part)</h3>
<div id="outline-container-org838d52e" class="outline-3">
<h3 id="org838d52e"><span class="section-number-3">1.3</span> Initialize function (constant part)</h3>
<div class="outline-text-3" id="text-1-3">
<div class="org-src-container">
<pre class="src src-c"><span style="color: #228b22;">trexio_exit_code</span>
@ -509,8 +509,8 @@ The file is written when closed, or when the flush function is called.
</div>
</div>
<div id="outline-container-orgdd7568b" class="outline-3">
<h3 id="orgdd7568b"><span class="section-number-3">1.4</span> Deinitialize function (templated part)</h3>
<div id="outline-container-org3106705" class="outline-3">
<h3 id="org3106705"><span class="section-number-3">1.4</span> Deinitialize function (templated part)</h3>
<div class="outline-text-3" id="text-1-4">
<div class="org-src-container">
<pre class="src src-c"><span style="color: #228b22;">trexio_exit_code</span>
@ -535,8 +535,8 @@ The file is written when closed, or when the flush function is called.
</div>
</div>
<div id="outline-container-org2fa3289" class="outline-3">
<h3 id="org2fa3289"><span class="section-number-3">1.5</span> Template for text read struct</h3>
<div id="outline-container-org7810f25" class="outline-3">
<h3 id="org7810f25"><span class="section-number-3">1.5</span> Template for text read struct</h3>
<div class="outline-text-3" id="text-1-5">
<div class="org-src-container">
<pre class="src src-c">$group$_t*
@ -805,8 +805,8 @@ trexio_text_read_$group$ (<span style="color: #228b22;">trexio_text_t</span>* <s
</div>
</div>
<div id="outline-container-org7030614" class="outline-3">
<h3 id="org7030614"><span class="section-number-3">1.6</span> Template for text flush struct</h3>
<div id="outline-container-orga899e45" class="outline-3">
<h3 id="orga899e45"><span class="section-number-3">1.6</span> Template for text flush struct</h3>
<div class="outline-text-3" id="text-1-6">
<div class="org-src-container">
<pre class="src src-c"><span style="color: #228b22;">trexio_exit_code</span>
@ -870,8 +870,8 @@ trexio_text_read_$group$ (<span style="color: #228b22;">trexio_text_t</span>* <s
</div>
</div>
<div id="outline-container-org2f69079" class="outline-3">
<h3 id="org2f69079"><span class="section-number-3">1.7</span> Template for text free memory</h3>
<div id="outline-container-org4704bff" class="outline-3">
<h3 id="org4704bff"><span class="section-number-3">1.7</span> Template for text free memory</h3>
<div class="outline-text-3" id="text-1-7">
<p>
Memory is allocated when reading. The following function frees memory.
@ -916,8 +916,8 @@ Memory is allocated when reading. The following function frees memory.
</div>
</div>
<div id="outline-container-org812e5ca" class="outline-3">
<h3 id="org812e5ca"><span class="section-number-3">1.8</span> Template for has/read/write the num attribute</h3>
<div id="outline-container-org98dc9f8" class="outline-3">
<h3 id="org98dc9f8"><span class="section-number-3">1.8</span> Template for has/read/write the num attribute</h3>
<div class="outline-text-3" id="text-1-8">
<div class="org-src-container">
<pre class="src src-c"><span style="color: #228b22;">trexio_exit_code</span>
@ -979,8 +979,8 @@ Memory is allocated when reading. The following function frees memory.
</div>
</div>
<div id="outline-container-org7ad639a" class="outline-3">
<h3 id="org7ad639a"><span class="section-number-3">1.9</span> Template for has/read/write the dataset of numerical data</h3>
<div id="outline-container-org4e36999" class="outline-3">
<h3 id="org4e36999"><span class="section-number-3">1.9</span> Template for has/read/write the dataset of numerical data</h3>
<div class="outline-text-3" id="text-1-9">
<p>
The <code>group_dset</code> array is assumed allocated with the appropriate size.
@ -1076,8 +1076,8 @@ The <code>group_dset</code> array is assumed allocated with the appropriate size
</div>
</div>
</div>
<div id="outline-container-org982e671" class="outline-3">
<h3 id="org982e671"><span class="section-number-3">1.10</span> Template for has/read/write the dataset of strings</h3>
<div id="outline-container-org62fd780" class="outline-3">
<h3 id="org62fd780"><span class="section-number-3">1.10</span> Template for has/read/write the dataset of strings</h3>
<div class="outline-text-3" id="text-1-10">
<p>
The <code>group_dset</code> array is assumed allocated with the appropriate size.
@ -1178,8 +1178,8 @@ The <code>group_dset</code> array is assumed allocated with the appropriate size
</div>
</div>
</div>
<div id="outline-container-orgf181cf6" class="outline-3">
<h3 id="orgf181cf6"><span class="section-number-3">1.11</span> Template for has/read/write the string attribute</h3>
<div id="outline-container-org21d2224" class="outline-3">
<h3 id="org21d2224"><span class="section-number-3">1.11</span> Template for has/read/write the string attribute</h3>
<div class="outline-text-3" id="text-1-11">
<div class="org-src-container">
<pre class="src src-c"><span style="color: #228b22;">trexio_exit_code</span>
@ -1253,12 +1253,12 @@ The <code>group_dset</code> array is assumed allocated with the appropriate size
</div>
</div>
</div>
<div id="outline-container-org904841d" class="outline-3">
<h3 id="org904841d"><span class="section-number-3">1.12</span> RDM struct (hard-coded)</h3>
<div id="outline-container-orgaf090f2" class="outline-3">
<h3 id="orgaf090f2"><span class="section-number-3">1.12</span> RDM struct (hard-coded)</h3>
<div class="outline-text-3" id="text-1-12">
</div>
<div id="outline-container-org64fc9ac" class="outline-4">
<h4 id="org64fc9ac"><span class="section-number-4">1.12.1</span> Read the complete struct</h4>
<div id="outline-container-orgcb0d605" class="outline-4">
<h4 id="orgcb0d605"><span class="section-number-4">1.12.1</span> Read the complete struct</h4>
<div class="outline-text-4" id="text-1-12-1">
<div class="org-src-container">
<pre class="src src-c"><span style="color: #228b22;">rdm_t</span>* <span style="color: #0000ff;">trexio_text_read_rdm</span>(<span style="color: #228b22;">trexio_text_t</span>* <span style="color: #a020f0;">const</span> <span style="color: #a0522d;">file</span>);
@ -1353,8 +1353,8 @@ The <code>group_dset</code> array is assumed allocated with the appropriate size
</div>
</div>
<div id="outline-container-org4bc5893" class="outline-4">
<h4 id="org4bc5893"><span class="section-number-4">1.12.2</span> Flush the complete struct</h4>
<div id="outline-container-org58df0ff" class="outline-4">
<h4 id="org58df0ff"><span class="section-number-4">1.12.2</span> Flush the complete struct</h4>
<div class="outline-text-4" id="text-1-12-2">
<div class="org-src-container">
<pre class="src src-c"><span style="color: #228b22;">trexio_exit_code</span> <span style="color: #0000ff;">trexio_text_flush_rdm</span>(<span style="color: #228b22;">trexio_text_t</span>* <span style="color: #a020f0;">const</span> <span style="color: #a0522d;">file</span>);
@ -1396,8 +1396,8 @@ The <code>group_dset</code> array is assumed allocated with the appropriate size
</div>
</div>
<div id="outline-container-org645a5c2" class="outline-4">
<h4 id="org645a5c2"><span class="section-number-4">1.12.3</span> Free memory</h4>
<div id="outline-container-org6db163c" class="outline-4">
<h4 id="org6db163c"><span class="section-number-4">1.12.3</span> Free memory</h4>
<div class="outline-text-4" id="text-1-12-3">
<p>
Memory is allocated when reading. The followig function frees memory.
@ -1433,8 +1433,8 @@ Memory is allocated when reading. The followig function frees memory.
</div>
</div>
<div id="outline-container-org7e85cb2" class="outline-4">
<h4 id="org7e85cb2"><span class="section-number-4">1.12.4</span> Read/Write the one<sub>e</sub> attribute</h4>
<div id="outline-container-org750d656" class="outline-4">
<h4 id="org750d656"><span class="section-number-4">1.12.4</span> Read/Write the one<sub>e</sub> attribute</h4>
<div class="outline-text-4" id="text-1-12-4">
<p>
The <code>one_e</code> array is assumed allocated with the appropriate size.
@ -1500,8 +1500,8 @@ The <code>one_e</code> array is assumed allocated with the appropriate size.
</div>
</div>
<div id="outline-container-orgb5fbe79" class="outline-4">
<h4 id="orgb5fbe79"><span class="section-number-4">1.12.5</span> Read/Write the two<sub>e</sub> attribute</h4>
<div id="outline-container-org6f559f9" class="outline-4">
<h4 id="org6f559f9"><span class="section-number-4">1.12.5</span> Read/Write the two<sub>e</sub> attribute</h4>
<div class="outline-text-4" id="text-1-12-5">
<p>
<code>two_e</code> is a sparse data structure, which can be too large to fit
@ -1609,7 +1609,7 @@ file for each sparse float structure.
</div>
<div id="postamble" class="status">
<p class="author">Author: TREX-CoE</p>
<p class="date">Created: 2021-09-15 Wed 13:07</p>
<p class="date">Created: 2021-09-16 Thu 14:47</p>
<p class="validation"><a href="http://validator.w3.org/check?uri=referer">Validate</a></p>
</div>
</body>

118
trex.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>
<!-- 2021-09-15 Wed 13:07 -->
<!-- 2021-09-16 Thu 14:47 -->
<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>
@ -333,28 +333,28 @@ for the JavaScript code in this tag.
<h2>Table of Contents</h2>
<div id="text-table-of-contents">
<ul>
<li><a href="#org2a53987">1. Metadata (metadata group)</a></li>
<li><a href="#orge2d0929">2. Electron (electron group)</a></li>
<li><a href="#org6c8113e">3. Nucleus (nucleus group)</a></li>
<li><a href="#org8b5eed7">4. Effective core potentials (ecp group)</a></li>
<li><a href="#orga0c3eeb">5. Basis set (basis group)</a></li>
<li><a href="#orgc240234">6. Atomic orbitals (ao group)</a>
<li><a href="#orgf01cc8b">1. Metadata (metadata group)</a></li>
<li><a href="#org6e07d76">2. Electron (electron group)</a></li>
<li><a href="#orga389cc4">3. Nucleus (nucleus group)</a></li>
<li><a href="#orge373450">4. Effective core potentials (ecp group)</a></li>
<li><a href="#org9b59ff1">5. Basis set (basis group)</a></li>
<li><a href="#orged437c1">6. Atomic orbitals (ao group)</a>
<ul>
<li><a href="#ao_one_e">6.1. One-electron integrals (<code>ao_1e_int</code> group)</a></li>
<li><a href="#ao_two_e">6.2. Two-electron integrals (<code>ao_2e_int</code> group)</a></li>
</ul>
</li>
<li><a href="#org8f41f25">7. Molecular orbitals (mo group)</a>
<li><a href="#orgbb85665">7. Molecular orbitals (mo group)</a>
<ul>
<li><a href="#orgaf390ef">7.1. One-electron integrals (<code>mo_1e_int</code> group)</a></li>
<li><a href="#org86e7d45">7.2. Two-electron integrals (<code>mo_2e_int</code> group)</a></li>
<li><a href="#orgff9b4c2">7.1. One-electron integrals (<code>mo_1e_int</code> group)</a></li>
<li><a href="#org6aedef6">7.2. Two-electron integrals (<code>mo_2e_int</code> group)</a></li>
</ul>
</li>
<li><a href="#org108c8a9">8. <span class="todo TODO">TODO</span> Slater determinants</a></li>
<li><a href="#orgd42c485">9. <span class="todo TODO">TODO</span> Reduced density matrices (rdm group)</a></li>
<li><a href="#org4e8a5ab">10. Appendix</a>
<li><a href="#orgd7378f6">8. <span class="todo TODO">TODO</span> Slater determinants</a></li>
<li><a href="#orgb3124cb">9. <span class="todo TODO">TODO</span> Reduced density matrices (rdm group)</a></li>
<li><a href="#org951d21b">10. Appendix</a>
<ul>
<li><a href="#orgd0a9387">10.1. Python script from table to json</a></li>
<li><a href="#orgbd76282">10.1. Python script from table to json</a></li>
</ul>
</li>
</ul>
@ -386,8 +386,8 @@ arrays are 0-based. Hence, we introduce the <code>index</code> type which is an
1-based <code>int</code> in the Fortran interface and 0-based otherwise.
</p>
<div id="outline-container-org2a53987" class="outline-2">
<h2 id="org2a53987"><span class="section-number-2">1</span> Metadata (metadata group)</h2>
<div id="outline-container-orgf01cc8b" class="outline-2">
<h2 id="orgf01cc8b"><span class="section-number-2">1</span> Metadata (metadata group)</h2>
<div class="outline-text-2" id="text-1">
<p>
As we expect our files to be archived in open-data repositories, we
@ -397,7 +397,7 @@ which have participated to the creation of the file, a list of
authors of the file, and a textual description.
</p>
<table id="orgb315f18" border="2" cellspacing="0" cellpadding="6" rules="groups" frame="hsides">
<table id="orgae2a71e" border="2" cellspacing="0" cellpadding="6" rules="groups" frame="hsides">
<colgroup>
@ -464,15 +464,15 @@ authors of the file, and a textual description.
</div>
</div>
<div id="outline-container-orge2d0929" class="outline-2">
<h2 id="orge2d0929"><span class="section-number-2">2</span> Electron (electron group)</h2>
<div id="outline-container-org6e07d76" class="outline-2">
<h2 id="org6e07d76"><span class="section-number-2">2</span> Electron (electron group)</h2>
<div class="outline-text-2" id="text-2">
<p>
We consider wave functions expressed in the spin-free formalism, where
the number of &uarr; and &darr; electrons is fixed.
</p>
<table id="org5bdfa62" border="2" cellspacing="0" cellpadding="6" rules="groups" frame="hsides">
<table id="orgbaec19d" border="2" cellspacing="0" cellpadding="6" rules="groups" frame="hsides">
<colgroup>
@ -511,15 +511,15 @@ the number of &uarr; and &darr; electrons is fixed.
</div>
</div>
<div id="outline-container-org6c8113e" class="outline-2">
<h2 id="org6c8113e"><span class="section-number-2">3</span> Nucleus (nucleus group)</h2>
<div id="outline-container-orga389cc4" class="outline-2">
<h2 id="orga389cc4"><span class="section-number-2">3</span> Nucleus (nucleus group)</h2>
<div class="outline-text-2" id="text-3">
<p>
The nuclei are considered as fixed point charges. Coordinates are
given in Cartesian \((x,y,z)\) format.
</p>
<table id="orgb28e435" border="2" cellspacing="0" cellpadding="6" rules="groups" frame="hsides">
<table id="org4271e24" border="2" cellspacing="0" cellpadding="6" rules="groups" frame="hsides">
<colgroup>
@ -579,8 +579,8 @@ given in Cartesian \((x,y,z)\) format.
</div>
</div>
<div id="outline-container-org8b5eed7" class="outline-2">
<h2 id="org8b5eed7"><span class="section-number-2">4</span> Effective core potentials (ecp group)</h2>
<div id="outline-container-orge373450" class="outline-2">
<h2 id="orge373450"><span class="section-number-2">4</span> Effective core potentials (ecp group)</h2>
<div class="outline-text-2" id="text-4">
<p>
An effective core potential (ECP) \(V_A^{\text{ECP}}\) replacing the
@ -608,7 +608,7 @@ 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> for more info.
</p>
<table id="orgfd0a5cb" border="2" cellspacing="0" cellpadding="6" rules="groups" frame="hsides">
<table id="org3e82be2" border="2" cellspacing="0" cellpadding="6" rules="groups" frame="hsides">
<colgroup>
@ -717,8 +717,8 @@ See <a href="http://dx.doi.org/10.1063/1.4984046">http://dx.doi.org/10.1063/1.49
</div>
</div>
<div id="outline-container-orga0c3eeb" class="outline-2">
<h2 id="orga0c3eeb"><span class="section-number-2">5</span> Basis set (basis group)</h2>
<div id="outline-container-org9b59ff1" class="outline-2">
<h2 id="org9b59ff1"><span class="section-number-2">5</span> Basis set (basis group)</h2>
<div class="outline-text-2" id="text-5">
<p>
We consider here basis functions centered on nuclei. Hence, we enable
@ -771,7 +771,7 @@ If the the basis function is not considered normalized, \(\mathcal{N}_s=1\).
All the basis set parameters are stored in one-dimensional arrays:
</p>
<table id="org0a7f705" border="2" cellspacing="0" cellpadding="6" rules="groups" frame="hsides">
<table id="org7bbfbca" border="2" cellspacing="0" cellpadding="6" rules="groups" frame="hsides">
<colgroup>
@ -940,8 +940,8 @@ prim_factor =
</div>
</div>
<div id="outline-container-orgc240234" class="outline-2">
<h2 id="orgc240234"><span class="section-number-2">6</span> Atomic orbitals (ao group)</h2>
<div id="outline-container-orged437c1" class="outline-2">
<h2 id="orged437c1"><span class="section-number-2">6</span> Atomic orbitals (ao group)</h2>
<div class="outline-text-2" id="text-6">
<p>
Going from the atomic basis set to AOs implies a systematic
@ -989,13 +989,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="#orga0c3eeb">Basis set</a> section) to \(\mathcal{N}_{z^2}\), which is the
the <a href="#org9b59ff1">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="org7c3ae48" border="2" cellspacing="0" cellpadding="6" rules="groups" frame="hsides">
<table id="orge2b99d5" border="2" cellspacing="0" cellpadding="6" rules="groups" frame="hsides">
<colgroup>
@ -1047,8 +1047,8 @@ introduced here should be \(\frac{\mathcal{N}_{xy}}{\mathcal{N}_{z^2}}\).
</table>
</div>
<div id="outline-container-org9ba1f37" class="outline-3">
<h3 id="ao_one_e"><a id="org9ba1f37"></a><span class="section-number-3">6.1</span> One-electron integrals (<code>ao_1e_int</code> group)</h3>
<div id="outline-container-orgcaa1ff2" class="outline-3">
<h3 id="ao_one_e"><a id="orgcaa1ff2"></a><span class="section-number-3">6.1</span> One-electron integrals (<code>ao_1e_int</code> group)</h3>
<div class="outline-text-3" id="text-ao_one_e">
<ul class="org-ul">
<li>\[ \hat{V}_{\text{ne}} = \sum_{A=1}^{N_\text{nucl}}
@ -1066,7 +1066,7 @@ The one-electron integrals for a one-electron operator \(\hat{O}\) are
over atomic orbitals.
</p>
<table id="org70fde72" border="2" cellspacing="0" cellpadding="6" rules="groups" frame="hsides">
<table id="org508a477" border="2" cellspacing="0" cellpadding="6" rules="groups" frame="hsides">
<colgroup>
@ -1133,8 +1133,8 @@ over atomic orbitals.
</div>
</div>
<div id="outline-container-orgea6a56e" class="outline-3">
<h3 id="ao_two_e"><a id="orgea6a56e"></a><span class="section-number-3">6.2</span> Two-electron integrals (<code>ao_2e_int</code> group)</h3>
<div id="outline-container-org19a3d73" class="outline-3">
<h3 id="ao_two_e"><a id="org19a3d73"></a><span class="section-number-3">6.2</span> Two-electron integrals (<code>ao_2e_int</code> group)</h3>
<div class="outline-text-3" id="text-ao_two_e">
<p>
The two-electron integrals for a two-electron operator \(\hat{O}\) are
@ -1155,7 +1155,7 @@ notation.
\mathbf{r}_j \vert)}{\vert \mathbf{r}_i - \mathbf{r}_j \vert} \] : electron-electron long range potential</li>
</ul>
<table id="orgd62b53c" border="2" cellspacing="0" cellpadding="6" rules="groups" frame="hsides">
<table id="org095dd51" border="2" cellspacing="0" cellpadding="6" rules="groups" frame="hsides">
<colgroup>
@ -1195,10 +1195,10 @@ notation.
</div>
</div>
<div id="outline-container-org8f41f25" class="outline-2">
<h2 id="org8f41f25"><span class="section-number-2">7</span> Molecular orbitals (mo group)</h2>
<div id="outline-container-orgbb85665" class="outline-2">
<h2 id="orgbb85665"><span class="section-number-2">7</span> Molecular orbitals (mo group)</h2>
<div class="outline-text-2" id="text-7">
<table id="org3add026" border="2" cellspacing="0" cellpadding="6" rules="groups" frame="hsides">
<table id="orgad0e1ed" border="2" cellspacing="0" cellpadding="6" rules="groups" frame="hsides">
<colgroup>
@ -1264,8 +1264,8 @@ notation.
</table>
</div>
<div id="outline-container-orgaf390ef" class="outline-3">
<h3 id="orgaf390ef"><span class="section-number-3">7.1</span> One-electron integrals (<code>mo_1e_int</code> group)</h3>
<div id="outline-container-orgff9b4c2" class="outline-3">
<h3 id="orgff9b4c2"><span class="section-number-3">7.1</span> One-electron integrals (<code>mo_1e_int</code> group)</h3>
<div class="outline-text-3" id="text-7-1">
<p>
The operators as the same as those defined in the
@ -1273,7 +1273,7 @@ The operators as the same as those defined in the
the basis of molecular orbitals.
</p>
<table id="org1eac9e6" border="2" cellspacing="0" cellpadding="6" rules="groups" frame="hsides">
<table id="org276731f" border="2" cellspacing="0" cellpadding="6" rules="groups" frame="hsides">
<colgroup>
@ -1340,8 +1340,8 @@ the basis of molecular orbitals.
</div>
</div>
<div id="outline-container-org86e7d45" class="outline-3">
<h3 id="org86e7d45"><span class="section-number-3">7.2</span> Two-electron integrals (<code>mo_2e_int</code> group)</h3>
<div id="outline-container-org6aedef6" class="outline-3">
<h3 id="org6aedef6"><span class="section-number-3">7.2</span> Two-electron integrals (<code>mo_2e_int</code> group)</h3>
<div class="outline-text-3" id="text-7-2">
<p>
The operators as the same as those defined in the
@ -1349,7 +1349,7 @@ The operators as the same as those defined in the
the basis of molecular orbitals.
</p>
<table id="orge9432ed" border="2" cellspacing="0" cellpadding="6" rules="groups" frame="hsides">
<table id="org91cfad3" border="2" cellspacing="0" cellpadding="6" rules="groups" frame="hsides">
<colgroup>
@ -1389,13 +1389,13 @@ the basis of molecular orbitals.
</div>
</div>
<div id="outline-container-org108c8a9" class="outline-2">
<h2 id="org108c8a9"><span class="section-number-2">8</span> <span class="todo TODO">TODO</span> Slater determinants</h2>
<div id="outline-container-orgd7378f6" class="outline-2">
<h2 id="orgd7378f6"><span class="section-number-2">8</span> <span class="todo TODO">TODO</span> Slater determinants</h2>
</div>
<div id="outline-container-orgd42c485" class="outline-2">
<h2 id="orgd42c485"><span class="section-number-2">9</span> <span class="todo TODO">TODO</span> Reduced density matrices (rdm group)</h2>
<div id="outline-container-orgb3124cb" class="outline-2">
<h2 id="orgb3124cb"><span class="section-number-2">9</span> <span class="todo TODO">TODO</span> Reduced density matrices (rdm group)</h2>
<div class="outline-text-2" id="text-9">
<table id="orgf7f4844" border="2" cellspacing="0" cellpadding="6" rules="groups" frame="hsides">
<table id="orgf4ea161" border="2" cellspacing="0" cellpadding="6" rules="groups" frame="hsides">
<colgroup>
@ -1448,15 +1448,15 @@ the basis of molecular orbitals.
</div>
</div>
<div id="outline-container-org4e8a5ab" class="outline-2">
<h2 id="org4e8a5ab"><span class="section-number-2">10</span> Appendix</h2>
<div id="outline-container-org951d21b" class="outline-2">
<h2 id="org951d21b"><span class="section-number-2">10</span> Appendix</h2>
<div class="outline-text-2" id="text-10">
</div>
<div id="outline-container-orgd0a9387" class="outline-3">
<h3 id="orgd0a9387"><span class="section-number-3">10.1</span> Python script from table to json</h3>
<div id="outline-container-orgbd76282" class="outline-3">
<h3 id="orgbd76282"><span class="section-number-3">10.1</span> Python script from table to json</h3>
<div class="outline-text-3" id="text-10-1">
<div class="org-src-container">
<pre class="src src-python" id="org69e42ea"><span style="color: #a020f0;">print</span>(<span style="color: #8b2252;">"""#+begin_src python :tangle trex.json"""</span>)
<pre class="src src-python" id="org55db609"><span style="color: #a020f0;">print</span>(<span style="color: #8b2252;">"""#+begin_src python :tangle trex.json"""</span>)
<span style="color: #a020f0;">print</span>(<span style="color: #8b2252;">""" "%s": {"""</span>%(title))
<span style="color: #a0522d;">indent</span> = <span style="color: #8b2252;">" "</span>
<span style="color: #a0522d;">f1</span> = 0 ; <span style="color: #a0522d;">f2</span> = 0 ; <span style="color: #a0522d;">f3</span> = 0
@ -1509,7 +1509,7 @@ the basis of molecular orbitals.
</div>
<div id="postamble" class="status">
<p class="author">Author: TREX-CoE</p>
<p class="date">Created: 2021-09-15 Wed 13:07</p>
<p class="date">Created: 2021-09-16 Thu 14:47</p>
<p class="validation"><a href="http://validator.w3.org/check?uri=referer">Validate</a></p>
</div>
</body>

176
tutorial_benzene.html Normal file
View File

@ -0,0 +1,176 @@
<h1 id="trexio-tutorial">TREXIO Tutorial</h1>
<p>This interactive Tutorial covers some basic use cases of the TREXIO library based on the Python API. At this point, it is assumed that the TREXIO Python package has been sucessfully installed on the user machine or in the virtual environment. If this is not the case, feel free to follow the <a href="https://github.com/TREX-CoE/trexio/blob/master/python/README.md">installation guide</a>.</p>
<h2 id="importing-trexio">Importing TREXIO</h2>
<p>First of all, let’s import the TREXIO package.</p>
<div class="sourceCode" id="cb1"><pre class="sourceCode python"><code class="sourceCode python"><a class="sourceLine" id="cb1-1" title="1"><span class="cf">try</span>:</a>
<a class="sourceLine" id="cb1-2" title="2"> <span class="im">import</span> trexio</a>
<a class="sourceLine" id="cb1-3" title="3"><span class="cf">except</span> <span class="pp">ImportError</span>:</a>
<a class="sourceLine" id="cb1-4" title="4"> <span class="cf">raise</span> <span class="pp">Exception</span>(<span class="st">&quot;Unable to import trexio. Please check that trexio is properly instaled.&quot;</span>)</a></code></pre></div>
<p>If no error occurs, then it means that the TREXIO package has been sucessfully imported. Within the current import, TREXIO attributes can be accessed using the corresponding <code>trexio.attribute</code> notation. If you prefer to bound a shorter name to the imported module (as commonly done by the NumPy users with <code>import numpy as np</code>), this is also possible. To do so, replace <code>import trexio</code> with <code>import trexio as tr</code> for example. To learn more about importing modules, see the corresponding page of the <a href="https://docs.python.org/3/tutorial/modules.html#more-on-modules">Python documentation</a>.</p>
<h2 id="creating-a-new-trexio-file">Creating a new TREXIO file</h2>
<p>TREXIO currently supports two back ends for file I/O:</p>
<ol type="1">
<li><p><code>TREXIO_HDF5</code>, which relies on extensive use of the <a href="https://portal.hdfgroup.org/display/HDF5/HDF5">HDF5 library</a> and the associated binary file format. This back end is optimized for high performance but it requires HDF5 to be installed on the user machine.</p></li>
<li><p><code>TREXIO_TEXT</code>, which relies on basic I/O operations that are available in the standard C library. This back end is not optimized for performance but it is supposed to work “out-of-the-box” since there are no external dependencies.</p></li>
</ol>
<p>Armed with these new definitions, let’s proceed with the tutorial. The first task is to create a TREXIO file called <code>benzene_demo.h5</code>. But first we have to remove the file if it exists in the current directory</p>
<div class="sourceCode" id="cb2"><pre class="sourceCode python"><code class="sourceCode python"><a class="sourceLine" id="cb2-1" title="1">filename <span class="op">=</span> <span class="st">&#39;benzene_demo.h5&#39;</span></a>
<a class="sourceLine" id="cb2-2" title="2"></a>
<a class="sourceLine" id="cb2-3" title="3"><span class="im">import</span> os</a>
<a class="sourceLine" id="cb2-4" title="4"><span class="cf">try</span>:</a>
<a class="sourceLine" id="cb2-5" title="5"> os.remove(filename)</a>
<a class="sourceLine" id="cb2-6" title="6"><span class="cf">except</span>:</a>
<a class="sourceLine" id="cb2-7" title="7"> <span class="bu">print</span>(<span class="ss">f&quot;File </span><span class="sc">{</span>filename<span class="sc">}</span><span class="ss"> does not exist.&quot;</span>)</a></code></pre></div>
<pre><code>File benzene_demo.h5 does not exist.</code></pre>
<p>We are now ready to create a new TREXIO file:</p>
<div class="sourceCode" id="cb4"><pre class="sourceCode python"><code class="sourceCode python"><a class="sourceLine" id="cb4-1" title="1">demo_file <span class="op">=</span> trexio.File(filename, mode<span class="op">=</span><span class="st">&#39;w&#39;</span>, back_end<span class="op">=</span>trexio.TREXIO_HDF5)</a></code></pre></div>
<p>This creates an instance of the <code>trexio.File</code> class, which we refer to as <code>demo_file</code> in this tutorial. You can check that the corresponding file called <code>benzene_demo.h5</code> exists in the root directory. It is now open for writing as indicated by the user-supplied argument <code>mode='w'</code>. The file has been initiated using <code>TREXIO_HDF5</code> back end and will be accessed accordingly from now on. The information about back end is stored internally by TREXIO, which means that there is no need to specify it every time the I/O operation is performed. If the file named <code>benzene_demo.h5</code> already exists, then it is re-opened for writing (and not truncated to prevent data loss).</p>
<h2 id="writing-data-in-the-trexio-file">Writing data in the TREXIO file</h2>
<p>Prior to any work with TREXIO library, we highly recommend users to read about <a href="https://trex-coe.github.io/trexio/trex.html">TREXIO internal configuration</a>, which explains the structure of the wavefunction file. The reason is that TREXIO API has a naming convention, which is based on the groups and variables names that are pre-defined by the developers. In this Tutorial, we will only cover contents of the <code>nucleus</code> group. Note that custom groups and variables can be added to the TREXIO API.</p>
<p>In this Tutorial, we consider benzene molecule (C6H6) as an example. Since benzene has 12 atoms, let’s specify it in the previously created <code>demo_file</code>. In order to do so, one has to call <code>trexio.write_nucleus_num</code> function, which accepts an instance of the <code>trexio.File</code> class as a first argument and an <code>int</code> value corresponding to the number of nuclei as a second argument.</p>
<div class="sourceCode" id="cb5"><pre class="sourceCode python"><code class="sourceCode python"><a class="sourceLine" id="cb5-1" title="1">nucleus_num <span class="op">=</span> <span class="dv">12</span></a></code></pre></div>
<div class="sourceCode" id="cb6"><pre class="sourceCode python"><code class="sourceCode python"><a class="sourceLine" id="cb6-1" title="1">trexio.write_nucleus_num(demo_file, nucleus_num)</a></code></pre></div>
<p>In fact, all API functions that contain <code>write_</code> prefix can be used in a similar way. Variables that contain <code>_num</code> suffix are important part of the TREXIO file because some of them define dimensions of arrays. For example, <code>nucleus_num</code> variable corresponds to the number of atoms, which will be internally used to write/read the <code>nucleus_coord</code> array of nuclear coordinates. In order for TREXIO files to be self-consistent, overwriting num-suffixed variables is currently disabled.</p>
<p>The number of atoms is not sufficient to define a molecule. Let’s first create a list of nuclear charges, which correspond to benzene.</p>
<div class="sourceCode" id="cb7"><pre class="sourceCode python"><code class="sourceCode python"><a class="sourceLine" id="cb7-1" title="1">charges <span class="op">=</span> [<span class="fl">6.</span>, <span class="fl">6.</span>, <span class="fl">6.</span>, <span class="fl">6.</span>, <span class="fl">6.</span>, <span class="fl">6.</span>, <span class="fl">1.</span>, <span class="fl">1.</span>, <span class="fl">1.</span>, <span class="fl">1.</span>, <span class="fl">1.</span>, <span class="fl">1.</span>]</a></code></pre></div>
<p>According to the TREX configuration file, there is a <code>charge</code> attribute of the <code>nucleus</code> group, which has <code>float</code> type and <code>[nucleus_num]</code> dimension. The <code>charges</code> list defined above fits nicely in the description and can be written as follows</p>
<div class="sourceCode" id="cb8"><pre class="sourceCode python"><code class="sourceCode python"><a class="sourceLine" id="cb8-1" title="1">trexio.write_nucleus_charge(demo_file, charges)</a></code></pre></div>
<p><strong>Note: TREXIO function names only contain parts in singular form.</strong> This means that, both <code>write_nucleus_charges</code> and <code>write_nuclear_charges</code> are invalid API calls. These functions simply do not exist in the <code>trexio</code> Python package and the corresponding error message should appear.</p>
<p>Alternatively, one can provide a list of nuclear labels (chemical elements from the periodic table) that correspond to the aforementioned charges. There is a <code>label</code> attribute of the <code>nucleus</code> group, which has <code>str</code> type and <code>[nucleus_num]</code> dimension. Let’s create a list of 12 strings, which correspond to 6 carbon and 6 hydrogen atoms:</p>
<div class="sourceCode" id="cb9"><pre class="sourceCode python"><code class="sourceCode python"><a class="sourceLine" id="cb9-1" title="1">labels <span class="op">=</span> [</a>
<a class="sourceLine" id="cb9-2" title="2"> <span class="st">&#39;C&#39;</span>,</a>
<a class="sourceLine" id="cb9-3" title="3"> <span class="st">&#39;C&#39;</span>,</a>
<a class="sourceLine" id="cb9-4" title="4"> <span class="st">&#39;C&#39;</span>,</a>
<a class="sourceLine" id="cb9-5" title="5"> <span class="st">&#39;C&#39;</span>,</a>
<a class="sourceLine" id="cb9-6" title="6"> <span class="st">&#39;C&#39;</span>,</a>
<a class="sourceLine" id="cb9-7" title="7"> <span class="st">&#39;C&#39;</span>,</a>
<a class="sourceLine" id="cb9-8" title="8"> <span class="st">&#39;H&#39;</span>,</a>
<a class="sourceLine" id="cb9-9" title="9"> <span class="st">&#39;H&#39;</span>,</a>
<a class="sourceLine" id="cb9-10" title="10"> <span class="st">&#39;H&#39;</span>,</a>
<a class="sourceLine" id="cb9-11" title="11"> <span class="st">&#39;H&#39;</span>,</a>
<a class="sourceLine" id="cb9-12" title="12"> <span class="st">&#39;H&#39;</span>,</a>
<a class="sourceLine" id="cb9-13" title="13"> <span class="st">&#39;H&#39;</span>]</a></code></pre></div>
<p>This can now be written using the corresponding <code>trexio.write_nucleus_label</code> function:</p>
<div class="sourceCode" id="cb10"><pre class="sourceCode python"><code class="sourceCode python"><a class="sourceLine" id="cb10-1" title="1">trexio.write_nucleus_label(demo_file, labels)</a></code></pre></div>
<p>Two examples above demonstrate how to write arrays of numbers or strings in the file. TREXIO also supports I/O operations on single numerical or string attributes. In fact, in this Tutorial you have already written one numerical attribute: <code>nucleus_num</code>. Let’s now write a string <code>'D6h'</code>, which indicates a point group of benzene molecule. According to the TREX configuration file, <code>point_group</code> is a <code>str</code> attribute of the <code>nucleus</code> group, thus it can be written in the <code>demo_file</code> as follows</p>
<div class="sourceCode" id="cb11"><pre class="sourceCode python"><code class="sourceCode python"><a class="sourceLine" id="cb11-1" title="1">point_group <span class="op">=</span> <span class="st">&#39;D6h&#39;</span></a></code></pre></div>
<div class="sourceCode" id="cb12"><pre class="sourceCode python"><code class="sourceCode python"><a class="sourceLine" id="cb12-1" title="1">trexio.write_nucleus_point_group(demo_file, point_group)</a></code></pre></div>
<h3 id="writing-numpy-arrays-float-or-int-types">Writing NumPy arrays (float or int types)</h3>
<p>The aforementioned examples cover the majority of the currently implemented functionality related to writing data in the file. It is worth mentioning that I/O of numerical arrays in TREXIO Python API relies on extensive use of the <a href="https://numpy.org/">NumPy package</a>. This will be discussed in more details in the <a href="#Reading-data-from-the-TREXIO-file">section about reading data</a>. However, TREXIO <code>write_</code> functions that work with numerical arrays also accept <code>numpy.ndarray</code> objects. For example, consider a <code>coords</code> list of nuclear coordinates that correspond to benzene molecule</p>
<div class="sourceCode" id="cb13"><pre class="sourceCode python"><code class="sourceCode python"><a class="sourceLine" id="cb13-1" title="1">coords <span class="op">=</span> [</a>
<a class="sourceLine" id="cb13-2" title="2"> [<span class="fl">0.00000000</span> , <span class="fl">1.39250319</span> , <span class="fl">0.00000000</span> ],</a>
<a class="sourceLine" id="cb13-3" title="3"> [<span class="op">-</span><span class="fl">1.20594314</span> , <span class="fl">0.69625160</span> , <span class="fl">0.00000000</span> ],</a>
<a class="sourceLine" id="cb13-4" title="4"> [<span class="op">-</span><span class="fl">1.20594314</span> , <span class="fl">-0.69625160</span> , <span class="fl">0.00000000</span> ],</a>
<a class="sourceLine" id="cb13-5" title="5"> [<span class="fl">0.00000000</span> , <span class="fl">-1.39250319</span> , <span class="fl">0.00000000</span> ],</a>
<a class="sourceLine" id="cb13-6" title="6"> [<span class="fl">1.20594314</span> , <span class="fl">-0.69625160</span> , <span class="fl">0.00000000</span> ],</a>
<a class="sourceLine" id="cb13-7" title="7"> [<span class="fl">1.20594314</span> , <span class="fl">0.69625160</span> , <span class="fl">0.00000000</span> ],</a>
<a class="sourceLine" id="cb13-8" title="8"> [<span class="op">-</span><span class="fl">2.14171677</span> , <span class="fl">1.23652075</span> , <span class="fl">0.00000000</span> ],</a>
<a class="sourceLine" id="cb13-9" title="9"> [<span class="op">-</span><span class="fl">2.14171677</span> , <span class="fl">-1.23652075</span> , <span class="fl">0.00000000</span> ],</a>
<a class="sourceLine" id="cb13-10" title="10"> [<span class="fl">0.00000000</span> , <span class="fl">-2.47304151</span> , <span class="fl">0.00000000</span> ],</a>
<a class="sourceLine" id="cb13-11" title="11"> [<span class="fl">2.14171677</span> , <span class="fl">-1.23652075</span> , <span class="fl">0.00000000</span> ],</a>
<a class="sourceLine" id="cb13-12" title="12"> [<span class="fl">2.14171677</span> , <span class="fl">1.23652075</span> , <span class="fl">0.00000000</span> ],</a>
<a class="sourceLine" id="cb13-13" title="13"> [<span class="fl">0.00000000</span> , <span class="fl">2.47304151</span> , <span class="fl">0.00000000</span> ],</a>
<a class="sourceLine" id="cb13-14" title="14"> ]</a></code></pre></div>
<p>Let’s take advantage of using NumPy arrays with fixed precision for floating point numbers. But first, try to import the <code>numpy</code> package</p>
<div class="sourceCode" id="cb14"><pre class="sourceCode python"><code class="sourceCode python"><a class="sourceLine" id="cb14-1" title="1"><span class="cf">try</span>:</a>
<a class="sourceLine" id="cb14-2" title="2"> <span class="im">import</span> numpy <span class="im">as</span> np</a>
<a class="sourceLine" id="cb14-3" title="3"><span class="cf">except</span> <span class="pp">ImportError</span>:</a>
<a class="sourceLine" id="cb14-4" title="4"> <span class="cf">raise</span> <span class="pp">Exception</span>(<span class="st">&quot;Unable to import numpy. Please check that numpy is properly instaled.&quot;</span>)</a></code></pre></div>
<p>You can now convert the previously defined <code>coords</code> list into a numpy array with fixed <code>float64</code> type as follows</p>
<div class="sourceCode" id="cb15"><pre class="sourceCode python"><code class="sourceCode python"><a class="sourceLine" id="cb15-1" title="1">coords_np <span class="op">=</span> np.array(coords, dtype<span class="op">=</span>np.float64)</a></code></pre></div>
<p>TREXIO functions that write numerical arrays accept both lists and numpy arrays as a second argument. That is, both <code>trexio.write_nucleus_coord(demo_file, coords)</code> and <code>trexio.write_nucleus_coord(demo_file, coords_np)</code> are valid API calls. Let’s use the latter and see if it works</p>
<div class="sourceCode" id="cb16"><pre class="sourceCode python"><code class="sourceCode python"><a class="sourceLine" id="cb16-1" title="1">trexio.write_nucleus_coord(demo_file, coords_np)</a></code></pre></div>
<p>Congratulations, you have just completed the <code>nucleus</code> section of the TREXIO file for benzene molecule! Note that TREXIO API is rather permissive and do not impose any strict ordering on the I/O operations. The only requirement is that dimensioning (<code>_num</code> suffixed) variables have to be written in the file <strong>before</strong> writing arrays that depend on these variables. For example, attempting to write <code>nucleus_charge</code> or <code>nucleus_coord</code> fails if <code>nucleus_num</code> has not been written.</p>
<h3 id="trexio-error-handling">TREXIO error handling</h3>
<p>TREXIO Python API provides the <code>trexio.Error</code> class which simplifies exception handling in the Python scripts. This class wraps up TREXIO return codes and propagates them all the way from the C back end to the Python front end. Let’s try to write a negative number of basis set shells <code>basis_num</code> in the TREXIO file.</p>
<div class="sourceCode" id="cb17"><pre class="sourceCode python"><code class="sourceCode python"><a class="sourceLine" id="cb17-1" title="1"><span class="cf">try</span>:</a>
<a class="sourceLine" id="cb17-2" title="2"> trexio.write_basis_num(demo_file, <span class="dv">-256</span>)</a>
<a class="sourceLine" id="cb17-3" title="3"><span class="cf">except</span> trexio.Error <span class="im">as</span> e:</a>
<a class="sourceLine" id="cb17-4" title="4"> <span class="bu">print</span>(<span class="ss">f&quot;TREXIO error message: </span><span class="sc">{e.</span>message<span class="sc">}</span><span class="ss">&quot;</span>)</a></code></pre></div>
<pre><code>TREXIO error message: Invalid argument 2</code></pre>
<p>The error message says <strong>Invalid argument 2</strong>, which indicates that the user-provided value <code>-256</code> is not valid.</p>
<p>As mentioned before, <code>_num</code>-suffixed variables cannot be overwritten in the file. But what happens if you accidentally attempt to do so? Let’s have a look at the <code>write_nucleus_num</code> function as an example:</p>
<div class="sourceCode" id="cb19"><pre class="sourceCode python"><code class="sourceCode python"><a class="sourceLine" id="cb19-1" title="1"><span class="cf">try</span>:</a>
<a class="sourceLine" id="cb19-2" title="2"> trexio.write_nucleus_num(demo_file, <span class="dv">24</span>)</a>
<a class="sourceLine" id="cb19-3" title="3"><span class="cf">except</span> trexio.Error <span class="im">as</span> e:</a>
<a class="sourceLine" id="cb19-4" title="4"> <span class="bu">print</span>(<span class="ss">f&quot;TREXIO error message: </span><span class="sc">{e.</span>message<span class="sc">}</span><span class="ss">&quot;</span>)</a></code></pre></div>
<pre><code>TREXIO error message: Attribute already exists</code></pre>
<p>The API rightfully complains that the target attribute already exists and cannot be overwritten.</p>
<p>Alternatively, the aforementioned case can be handled using <code>trexio.has_nucleus_num</code> function as follows</p>
<div class="sourceCode" id="cb21"><pre class="sourceCode python"><code class="sourceCode python"><a class="sourceLine" id="cb21-1" title="1"><span class="cf">if</span> <span class="kw">not</span> trexio.has_nucleus_num:</a>
<a class="sourceLine" id="cb21-2" title="2"> trexio.write_nucleus_num(demo_file, <span class="dv">24</span>)</a></code></pre></div>
<p>TREXIO functions with <code>has_</code> prefix return <code>True</code> if the corresponding variable exists and <code>False</code> otherwise.</p>
<p>What about writing arrays? Let’s try to write an list of 48 nuclear indices instead of 12</p>
<div class="sourceCode" id="cb22"><pre class="sourceCode python"><code class="sourceCode python"><a class="sourceLine" id="cb22-1" title="1">indices <span class="op">=</span> [i <span class="cf">for</span> i <span class="kw">in</span> <span class="bu">range</span>(nucleus_num<span class="op">*</span><span class="dv">4</span>)]</a></code></pre></div>
<div class="sourceCode" id="cb23"><pre class="sourceCode python"><code class="sourceCode python"><a class="sourceLine" id="cb23-1" title="1"><span class="cf">try</span>:</a>
<a class="sourceLine" id="cb23-2" title="2"> trexio.write_basis_nucleus_index(demo_file, indices)</a>
<a class="sourceLine" id="cb23-3" title="3"><span class="cf">except</span> trexio.Error <span class="im">as</span> e:</a>
<a class="sourceLine" id="cb23-4" title="4"> <span class="bu">print</span>(<span class="ss">f&quot;TREXIO error message: </span><span class="sc">{e.</span>message<span class="sc">}</span><span class="ss">&quot;</span>)</a></code></pre></div>
<pre><code>TREXIO error message: Access to memory beyond allocated</code></pre>
<p>According to the TREX configuration file, <code>nucleus_index</code> attribute of a <code>basis</code> group is supposed to have <code>[nucleus_num]</code> elements. In the example above, we have tried to write 4 times more elements, which might lead to memory and/or file corruption. Luckily, TREXIO internally checks the array dimensions and returns an error in case of inconsistency.</p>
<h2 id="closing-the-trexio-file">Closing the TREXIO file</h2>
<p>It is good practice to close the TREXIO file at the end of the session. In fact, <code>trexio.File</code> class has a destructor, which normally takes care of that. However, if you intend to re-open the TREXIO file, it has to be closed explicitly before. This can be done using the <code>close</code> method, i.e.</p>
<div class="sourceCode" id="cb25"><pre class="sourceCode python"><code class="sourceCode python"><a class="sourceLine" id="cb25-1" title="1">demo_file.close()</a></code></pre></div>
<p>Good! You are now ready to inspect the contents of the <code>benzene_demo.h5</code> file using the reading functionality of TREXIO.</p>
<h2 id="reading-data-from-the-trexio-file">Reading data from the TREXIO file</h2>
<p>First, let’s try to open an existing TREXIO file in read-only mode. This can be done by creating a new instance of the <code>trexio.File</code> class but this time with <code>mode='r'</code> argument. Back end has to be specified as well.</p>
<div class="sourceCode" id="cb26"><pre class="sourceCode python"><code class="sourceCode python"><a class="sourceLine" id="cb26-1" title="1">demo_file_r <span class="op">=</span> trexio.File(filename, mode<span class="op">=</span><span class="st">&#39;r&#39;</span>, back_end<span class="op">=</span>trexio.TREXIO_HDF5)</a></code></pre></div>
<p>When reading data from the TREXIO file, the only required argument is a previously created instance of <code>trexio.File</code> class. In our case, it is <code>demo_file_r</code>. TREXIO functions with <code>read_</code> prefix return the desired variable as an output. For example, <code>nucleus_num</code> value can be read from the file as follows</p>
<div class="sourceCode" id="cb27"><pre class="sourceCode python"><code class="sourceCode python"><a class="sourceLine" id="cb27-1" title="1">nucleus_num_r <span class="op">=</span> trexio.read_nucleus_num(demo_file_r)</a></code></pre></div>
<div class="sourceCode" id="cb28"><pre class="sourceCode python"><code class="sourceCode python"><a class="sourceLine" id="cb28-1" title="1"><span class="bu">print</span>(<span class="ss">f&quot;nucleus_num from </span><span class="sc">{</span>filename<span class="sc">}</span><span class="ss"> file ---&gt; </span><span class="sc">{</span>nucleus_num_r<span class="sc">}</span><span class="ss">&quot;</span>)</a></code></pre></div>
<pre><code>nucleus_num from benzene_demo.h5 file ---&gt; 12</code></pre>
<p>The function call assigns <code>nucleus_num_r</code> to 12, which is consistent with the number of atoms in benzene that we wrote in the previous section.</p>
<p>All calls to functions that read data can be done in a very similar way. The key point here is a function name, which in turn defines the output format. Hopefully by now you got used to the TREXIO naming convention and the contents of the <code>nucleus</code> group. Which function would you call to read a <code>point_group</code> attribute of the <code>nucleus</code> group? What type does it return? See the answer below:</p>
<div class="sourceCode" id="cb30"><pre class="sourceCode python"><code class="sourceCode python"><a class="sourceLine" id="cb30-1" title="1">point_group_r <span class="op">=</span> trexio.read_nucleus_point_group(demo_file_r)</a></code></pre></div>
<div class="sourceCode" id="cb31"><pre class="sourceCode python"><code class="sourceCode python"><a class="sourceLine" id="cb31-1" title="1"><span class="bu">print</span>(<span class="ss">f&quot;nucleus_point_group from </span><span class="sc">{</span>filename<span class="sc">}</span><span class="ss"> TREXIO file ---&gt; </span><span class="sc">{</span>point_group_r<span class="sc">}</span><span class="ch">\n</span><span class="ss">&quot;</span>)</a>
<a class="sourceLine" id="cb31-2" title="2"><span class="bu">print</span>(<span class="ss">f&quot;Is return type of read_nucleus_point_group a string? ---&gt; </span><span class="sc">{</span><span class="bu">isinstance</span>(point_group_r, <span class="bu">str</span>)<span class="sc">}</span><span class="ss">&quot;</span>)</a></code></pre></div>
<pre><code>nucleus_point_group from benzene_demo.h5 TREXIO file ---&gt; D6h
Is return type of read_nucleus_point_group a string? ---&gt; True</code></pre>
<p>The <code>trexio.read_nucleus_point_group</code> function call returns a string <code>D6h</code>, which is exactly what we provided in the previous section. Now, let’s read nuclear charges and labels.</p>
<div class="sourceCode" id="cb33"><pre class="sourceCode python"><code class="sourceCode python"><a class="sourceLine" id="cb33-1" title="1">labels_r <span class="op">=</span> trexio.read_nucleus_label(demo_file_r)</a></code></pre></div>
<div class="sourceCode" id="cb34"><pre class="sourceCode python"><code class="sourceCode python"><a class="sourceLine" id="cb34-1" title="1"><span class="bu">print</span>(<span class="ss">f&quot;nucleus_label from </span><span class="sc">{</span>filename<span class="sc">}</span><span class="ss"> file </span><span class="ch">\n</span><span class="ss">---&gt; </span><span class="sc">{</span>labels_r<span class="sc">}</span><span class="ss">&quot;</span>)</a></code></pre></div>
<pre><code>nucleus_label from benzene_demo.h5 file
---&gt; [&#39;C&#39;, &#39;C&#39;, &#39;C&#39;, &#39;C&#39;, &#39;C&#39;, &#39;C&#39;, &#39;H&#39;, &#39;H&#39;, &#39;H&#39;, &#39;H&#39;, &#39;H&#39;, &#39;H&#39;]</code></pre>
<div class="sourceCode" id="cb36"><pre class="sourceCode python"><code class="sourceCode python"><a class="sourceLine" id="cb36-1" title="1">charges_r <span class="op">=</span> trexio.read_nucleus_charge(demo_file_r)</a></code></pre></div>
<div class="sourceCode" id="cb37"><pre class="sourceCode python"><code class="sourceCode python"><a class="sourceLine" id="cb37-1" title="1"><span class="bu">print</span>(<span class="ss">f&quot;nucleus_charge from </span><span class="sc">{</span>filename<span class="sc">}</span><span class="ss"> file </span><span class="ch">\n</span><span class="ss">---&gt; </span><span class="sc">{</span>charges_r<span class="sc">}</span><span class="ss">&quot;</span>)</a></code></pre></div>
<pre><code>nucleus_charge from benzene_demo.h5 file
---&gt; [6. 6. 6. 6. 6. 6. 1. 1. 1. 1. 1. 1.]</code></pre>
<p>The values are consistent with each other and with the previously written data. Not bad. What about the format of the output?</p>
<div class="sourceCode" id="cb39"><pre class="sourceCode python"><code class="sourceCode python"><a class="sourceLine" id="cb39-1" title="1"><span class="bu">print</span>(<span class="ss">f&quot;nucleus_label return type: </span><span class="sc">{</span><span class="bu">type</span>(labels_r)<span class="sc">}</span><span class="ss">&quot;</span>)</a></code></pre></div>
<pre><code>nucleus_label return type: &lt;class &#39;list&#39;&gt;</code></pre>
<p>This makes sense, isn’t it? We have written a <code>list</code> of nuclear labels and have received back a <code>list</code> of values from the file. What about nuclear charges?</p>
<div class="sourceCode" id="cb41"><pre class="sourceCode python"><code class="sourceCode python"><a class="sourceLine" id="cb41-1" title="1"><span class="bu">print</span>(<span class="ss">f&quot;nucleus_charge return type: </span><span class="sc">{</span><span class="bu">type</span>(charges_r)<span class="sc">}</span><span class="ss">&quot;</span>)</a></code></pre></div>
<pre><code>nucleus_charge return type: &lt;class &#39;numpy.ndarray&#39;&gt;</code></pre>
<p>Looks like <code>trexio.read_nucleus_charge</code> function returns a <code>numpy.ndarray</code> even though we have provided a python-ic <code>list</code> to <code>trexio.write_nucleus_charge</code> in the previous section. Why is it so? As has been mentioned before, TREXIO Python API internally relies on the use of the NumPy package to communicate arrays of <code>float</code>-like or <code>int</code>-like values. This prevents some memory leaks and grants additional flexibility to the API. What kind of flexibility? Check this out:</p>
<div class="sourceCode" id="cb43"><pre class="sourceCode python"><code class="sourceCode python"><a class="sourceLine" id="cb43-1" title="1"><span class="bu">print</span>(<span class="ss">f&quot;return dtype in NumPy notation: ---&gt; </span><span class="sc">{</span>charges_r<span class="sc">.</span>dtype<span class="sc">}</span><span class="ss">&quot;</span>)</a></code></pre></div>
<pre><code>return dtype in NumPy notation: ---&gt; float64</code></pre>
<p>It means that the default precision of the TREXIO output is double (<code>np.float64</code>) for arrays of floating point numbers like <code>nucleus_charge</code>. But what if you do not need this extra precision and would like to read nuclear charges in single (<code>np.float32</code>) or even reduced (e.g. <code>np.float16</code>) precision? TREXIO Python API provides an additional (optional) argument for this. This argument is called <code>dtype</code> and accepts one of the <a href="https://numpy.org/doc/stable/user/basics.types.html">NumPy data types</a>. For example,</p>
<div class="sourceCode" id="cb45"><pre class="sourceCode python"><code class="sourceCode python"><a class="sourceLine" id="cb45-1" title="1">charges_np <span class="op">=</span> trexio.read_nucleus_charge(demo_file_r, dtype<span class="op">=</span>np.float32)</a></code></pre></div>
<div class="sourceCode" id="cb46"><pre class="sourceCode python"><code class="sourceCode python"><a class="sourceLine" id="cb46-1" title="1"><span class="bu">print</span>(<span class="ss">f&quot;return dtype in NumPy notation: ---&gt; </span><span class="sc">{</span>charges_np<span class="sc">.</span>dtype<span class="sc">}</span><span class="ss">&quot;</span>)</a></code></pre></div>
<pre><code>return dtype in NumPy notation: ---&gt; float32</code></pre>
<h3 id="reading-multidimensional-arrays">Reading multidimensional arrays</h3>
<p>So far, we have only read flat 1D arrays. However, we have also written a 2D array of nuclear coordinates. Let’s now read it back from the file:</p>
<div class="sourceCode" id="cb48"><pre class="sourceCode python"><code class="sourceCode python"><a class="sourceLine" id="cb48-1" title="1">coords_r <span class="op">=</span> trexio.read_nucleus_coord(demo_file_r)</a></code></pre></div>
<div class="sourceCode" id="cb49"><pre class="sourceCode python"><code class="sourceCode python"><a class="sourceLine" id="cb49-1" title="1"><span class="bu">print</span>(<span class="ss">f&quot;nucleus_coord from </span><span class="sc">{</span>filename<span class="sc">}</span><span class="ss"> TREXIO file: </span><span class="ch">\n</span><span class="sc">{</span>coords_r<span class="sc">}</span><span class="ss">&quot;</span>)</a></code></pre></div>
<pre><code>nucleus_coord from benzene_demo.h5 TREXIO file:
[[ 0. 1.39250319 0. ]
[-1.20594314 0.6962516 0. ]
[-1.20594314 -0.6962516 0. ]
[ 0. -1.39250319 0. ]
[ 1.20594314 -0.6962516 0. ]
[ 1.20594314 0.6962516 0. ]
[-2.14171677 1.23652075 0. ]
[-2.14171677 -1.23652075 0. ]
[ 0. -2.47304151 0. ]
[ 2.14171677 -1.23652075 0. ]
[ 2.14171677 1.23652075 0. ]
[ 0. 2.47304151 0. ]]</code></pre>
<div class="sourceCode" id="cb51"><pre class="sourceCode python"><code class="sourceCode python"><a class="sourceLine" id="cb51-1" title="1"><span class="bu">print</span>(<span class="ss">f&quot;return shape: ---&gt; </span><span class="sc">{</span>coords_r<span class="sc">.</span>shape<span class="sc">}</span><span class="ss">&quot;</span>)</a></code></pre></div>
<pre><code>return shape: ---&gt; (12, 3)</code></pre>
<p>We can see that TREXIO returns a 2D array with 12 rows and 3 columns, which is consistent with the <code>nucleus_coord</code> dimensions <code>[nucleus_num, 3]</code>. What this means is that <strong>by default TREXIO reshapes the output flat array into a multidimensional one</strong> whenever applicable. This is done based on the shape specified in the TREX configuration file.</p>
<p>In some cases, it might be a good idea to explicitly check that the data exists in the file before reading it. This can be achieved using <code>has_</code>-suffixed functions of the API. For example,</p>
<div class="sourceCode" id="cb53"><pre class="sourceCode python"><code class="sourceCode python"><a class="sourceLine" id="cb53-1" title="1"><span class="cf">if</span> trexio.has_nucleus_coord(demo_file_r):</a>
<a class="sourceLine" id="cb53-2" title="2"> coords_safer <span class="op">=</span> trexio.read_nucleus_coord(demo_file_r)</a></code></pre></div>
<h2 id="conclusion">Conclusion</h2>
<p>In this Tutorial, you have created a TREXIO file using HDF5 back end and have written the number of atoms, point group, nuclear charges, labels and coordinates, which correspond to benzene molecule. You have also learned how to read this data back from the TREXIO file and how to handle some TREXIO errors.</p>

414
tutorial_benzene.md
View File

@ -1,414 +0,0 @@
# TREXIO Tutorial
This interactive Tutorial covers some basic use cases of the TREXIO library based on the Python API. At this point, it is assumed that the TREXIO Python package has been sucessfully installed on the user machine or in the virtual environment. If this is not the case, feel free to follow the [installation guide](https://github.com/TREX-CoE/trexio/blob/master/python/README.md).
## Importing TREXIO
First of all, let's import the TREXIO package.
```python
try:
import trexio
except ImportError:
raise Exception("Unable to import trexio. Please check that trexio is properly instaled.")
```
If no error occurs, then it means that the TREXIO package has been sucessfully imported. Within the current import, TREXIO attributes can be accessed using the corresponding `trexio.attribute` notation. If you prefer to bound a shorter name to the imported module (as commonly done by the NumPy users with `import numpy as np`), this is also possible. To do so, replace `import trexio` with `import trexio as tr` for example. To learn more about importing modules, see the corresponding page of the [Python documentation](https://docs.python.org/3/tutorial/modules.html#more-on-modules).
## Creating a new TREXIO file
TREXIO currently supports two back ends for file I/O:
1. `TREXIO_HDF5`, which relies on extensive use of the [HDF5 library](https://portal.hdfgroup.org/display/HDF5/HDF5) and the associated binary file format. This back end is optimized for high performance but it requires HDF5 to be installed on the user machine.
2. `TREXIO_TEXT`, which relies on basic I/O operations that are available in the standard C library. This back end is not optimized for performance but it is supposed to work "out-of-the-box" since there are no external dependencies.
Armed with these new definitions, let's proceed with the tutorial. The first task is to create a TREXIO file called `benzene_demo.h5`. But first we have to remove the file if it exists in the current directory
```python
filename = 'benzene_demo.h5'
import os
try:
os.remove(filename)
except:
print(f"File {filename} does not exist.")
```
File benzene_demo.h5 does not exist.
We are now ready to create a new TREXIO file:
```python
demo_file = trexio.File(filename, mode='w', back_end=trexio.TREXIO_HDF5)
```
This creates an instance of the `trexio.File` class, which we refer to as `demo_file` in this tutorial. You can check that the corresponding file called `benzene_demo.h5` exists in the root directory. It is now open for writing as indicated by the user-supplied argument `mode='w'`. The file has been initiated using `TREXIO_HDF5` back end and will be accessed accordingly from now on. The information about back end is stored internally by TREXIO, which means that there is no need to specify it every time the I/O operation is performed. If the file named `benzene_demo.h5` already exists, then it is re-opened for writing (and not truncated to prevent data loss).
## Writing data in the TREXIO file
Prior to any work with TREXIO library, we highly recommend users to read about [TREXIO internal configuration](https://trex-coe.github.io/trexio/trex.html), which explains the structure of the wavefunction file. The reason is that TREXIO API has a naming convention, which is based on the groups and variables names that are pre-defined by the developers. In this Tutorial, we will only cover contents of the `nucleus` group. Note that custom groups and variables can be added to the TREXIO API.
In this Tutorial, we consider benzene molecule (C6H6) as an example. Since benzene has 12 atoms, let's specify it in the previously created `demo_file`. In order to do so, one has to call `trexio.write_nucleus_num` function, which accepts an instance of the `trexio.File` class as a first argument and an `int` value corresponding to the number of nuclei as a second argument.
```python
nucleus_num = 12
```
```python
trexio.write_nucleus_num(demo_file, nucleus_num)
```
In fact, all API functions that contain `write_` prefix can be used in a similar way.
Variables that contain `_num` suffix are important part of the TREXIO file because some of them define dimensions of arrays. For example, `nucleus_num` variable corresponds to the number of atoms, which will be internally used to write/read the `nucleus_coord` array of nuclear coordinates. In order for TREXIO files to be self-consistent, overwriting num-suffixed variables is currently disabled.
The number of atoms is not sufficient to define a molecule. Let's first create a list of nuclear charges, which correspond to benzene.
```python
charges = [6., 6., 6., 6., 6., 6., 1., 1., 1., 1., 1., 1.]
```
According to the TREX configuration file, there is a `charge` attribute of the `nucleus` group, which has `float` type and `[nucleus_num]` dimension. The `charges` list defined above fits nicely in the description and can be written as follows
```python
trexio.write_nucleus_charge(demo_file, charges)
```
**Note: TREXIO function names only contain parts in singular form.** This means that, both `write_nucleus_charges` and `write_nuclear_charges` are invalid API calls. These functions simply do not exist in the `trexio` Python package and the corresponding error message should appear.
Alternatively, one can provide a list of nuclear labels (chemical elements from the periodic table) that correspond to the aforementioned charges. There is a `label` attribute of the `nucleus` group, which has `str` type and `[nucleus_num]` dimension. Let's create a list of 12 strings, which correspond to 6 carbon and 6 hydrogen atoms:
```python
labels = [
'C',
'C',
'C',
'C',
'C',
'C',
'H',
'H',
'H',
'H',
'H',
'H']
```
This can now be written using the corresponding `trexio.write_nucleus_label` function:
```python
trexio.write_nucleus_label(demo_file, labels)
```
Two examples above demonstrate how to write arrays of numbers or strings in the file. TREXIO also supports I/O operations on single numerical or string attributes. In fact, in this Tutorial you have already written one numerical attribute: `nucleus_num`. Let's now write a string `'D6h'`, which indicates a point group of benzene molecule. According to the TREX configuration file, `point_group` is a `str` attribute of the `nucleus` group, thus it can be written in the `demo_file` as follows
```python
point_group = 'D6h'
```
```python
trexio.write_nucleus_point_group(demo_file, point_group)
```
### Writing NumPy arrays (float or int types)
The aforementioned examples cover the majority of the currently implemented functionality related to writing data in the file. It is worth mentioning that I/O of numerical arrays in TREXIO Python API relies on extensive use of the [NumPy package](https://numpy.org/). This will be discussed in more details in the [section about reading data](#Reading-data-from-the-TREXIO-file). However, TREXIO `write_` functions that work with numerical arrays also accept `numpy.ndarray` objects. For example, consider a `coords` list of nuclear coordinates that correspond to benzene molecule
```python
coords = [
[0.00000000 , 1.39250319 , 0.00000000 ],
[-1.20594314 , 0.69625160 , 0.00000000 ],
[-1.20594314 , -0.69625160 , 0.00000000 ],
[0.00000000 , -1.39250319 , 0.00000000 ],
[1.20594314 , -0.69625160 , 0.00000000 ],
[1.20594314 , 0.69625160 , 0.00000000 ],
[-2.14171677 , 1.23652075 , 0.00000000 ],
[-2.14171677 , -1.23652075 , 0.00000000 ],
[0.00000000 , -2.47304151 , 0.00000000 ],
[2.14171677 , -1.23652075 , 0.00000000 ],
[2.14171677 , 1.23652075 , 0.00000000 ],
[0.00000000 , 2.47304151 , 0.00000000 ],
]
```
Let's take advantage of using NumPy arrays with fixed precision for floating point numbers. But first, try to import the `numpy` package
```python
try:
import numpy as np
except ImportError:
raise Exception("Unable to import numpy. Please check that numpy is properly instaled.")
```
You can now convert the previously defined `coords` list into a numpy array with fixed `float64` type as follows
```python
coords_np = np.array(coords, dtype=np.float64)
```
TREXIO functions that write numerical arrays accept both lists and numpy arrays as a second argument. That is, both `trexio.write_nucleus_coord(demo_file, coords)` and `trexio.write_nucleus_coord(demo_file, coords_np)` are valid API calls. Let's use the latter and see if it works
```python
trexio.write_nucleus_coord(demo_file, coords_np)
```
Congratulations, you have just completed the `nucleus` section of the TREXIO file for benzene molecule! Note that TREXIO API is rather permissive and do not impose any strict ordering on the I/O operations. The only requirement is that dimensioning (`_num` suffixed) variables have to be written in the file **before** writing arrays that depend on these variables. For example, attempting to write `nucleus_charge` or `nucleus_coord` fails if `nucleus_num` has not been written.
### TREXIO error handling
TREXIO Python API provides the `trexio.Error` class which simplifies exception handling in the Python scripts. This class wraps up TREXIO return codes and propagates them all the way from the C back end to the Python front end. Let's try to write a negative number of basis set shells `basis_num` in the TREXIO file.
```python
try:
trexio.write_basis_num(demo_file, -256)
except trexio.Error as e:
print(f"TREXIO error message: {e.message}")
```
TREXIO error message: Invalid argument 2
The error message says **Invalid argument 2**, which indicates that the user-provided value `-256` is not valid.
As mentioned before, `_num`-suffixed variables cannot be overwritten in the file. But what happens if you accidentally attempt to do so? Let's have a look at the `write_nucleus_num` function as an example:
```python
try:
trexio.write_nucleus_num(demo_file, 24)
except trexio.Error as e:
print(f"TREXIO error message: {e.message}")
```
TREXIO error message: Attribute already exists
The API rightfully complains that the target attribute already exists and cannot be overwritten.
Alternatively, the aforementioned case can be handled using `trexio.has_nucleus_num` function as follows
```python
if not trexio.has_nucleus_num:
trexio.write_nucleus_num(demo_file, 24)
```
TREXIO functions with `has_` prefix return `True` if the corresponding variable exists and `False` otherwise.
What about writing arrays? Let's try to write an list of 48 nuclear indices instead of 12
```python
indices = [i for i in range(nucleus_num*4)]
```
```python
try:
trexio.write_basis_nucleus_index(demo_file, indices)
except trexio.Error as e:
print(f"TREXIO error message: {e.message}")
```
TREXIO error message: Access to memory beyond allocated
According to the TREX configuration file, `nucleus_index` attribute of a `basis` group is supposed to have `[nucleus_num]` elements. In the example above, we have tried to write 4 times more elements, which might lead to memory and/or file corruption. Luckily, TREXIO internally checks the array dimensions and returns an error in case of inconsistency.
## Closing the TREXIO file
It is good practice to close the TREXIO file at the end of the session. In fact, `trexio.File` class has a destructor, which normally takes care of that. However, if you intend to re-open the TREXIO file, it has to be closed explicitly before. This can be done using the `close` method, i.e.
```python
demo_file.close()
```
Good! You are now ready to inspect the contents of the `benzene_demo.h5` file using the reading functionality of TREXIO.
## Reading data from the TREXIO file
First, let's try to open an existing TREXIO file in read-only mode. This can be done by creating a new instance of the `trexio.File` class but this time with `mode='r'` argument. Back end has to be specified as well.
```python
demo_file_r = trexio.File(filename, mode='r', back_end=trexio.TREXIO_HDF5)
```
When reading data from the TREXIO file, the only required argument is a previously created instance of `trexio.File` class. In our case, it is `demo_file_r`. TREXIO functions with `read_` prefix return the desired variable as an output. For example, `nucleus_num` value can be read from the file as follows
```python
nucleus_num_r = trexio.read_nucleus_num(demo_file_r)
```
```python
print(f"nucleus_num from {filename} file ---> {nucleus_num_r}")
```
nucleus_num from benzene_demo.h5 file ---> 12
The function call assigns `nucleus_num_r` to 12, which is consistent with the number of atoms in benzene that we wrote in the previous section.
All calls to functions that read data can be done in a very similar way. The key point here is a function name, which in turn defines the output format. Hopefully by now you got used to the TREXIO naming convention and the contents of the `nucleus` group. Which function would you call to read a `point_group` attribute of the `nucleus` group? What type does it return? See the answer below:
```python
point_group_r = trexio.read_nucleus_point_group(demo_file_r)
```
```python
print(f"nucleus_point_group from {filename} TREXIO file ---> {point_group_r}\n")
print(f"Is return type of read_nucleus_point_group a string? ---> {isinstance(point_group_r, str)}")
```
nucleus_point_group from benzene_demo.h5 TREXIO file ---> D6h
Is return type of read_nucleus_point_group a string? ---> True
The `trexio.read_nucleus_point_group` function call returns a string `D6h`, which is exactly what we provided in the previous section. Now, let's read nuclear charges and labels.
```python
labels_r = trexio.read_nucleus_label(demo_file_r)
```
```python
print(f"nucleus_label from {filename} file \n---> {labels_r}")
```
nucleus_label from benzene_demo.h5 file
---> ['C', 'C', 'C', 'C', 'C', 'C', 'H', 'H', 'H', 'H', 'H', 'H']
```python
charges_r = trexio.read_nucleus_charge(demo_file_r)
```
```python
print(f"nucleus_charge from {filename} file \n---> {charges_r}")
```
nucleus_charge from benzene_demo.h5 file
---> [6. 6. 6. 6. 6. 6. 1. 1. 1. 1. 1. 1.]
The values are consistent with each other and with the previously written data. Not bad. What about the format of the output?
```python
print(f"nucleus_label return type: {type(labels_r)}")
```
nucleus_label return type: <class 'list'>
This makes sense, isn't it? We have written a `list` of nuclear labels and have received back a `list` of values from the file. What about nuclear charges?
```python
print(f"nucleus_charge return type: {type(charges_r)}")
```
nucleus_charge return type: <class 'numpy.ndarray'>
Looks like `trexio.read_nucleus_charge` function returns a `numpy.ndarray` even though we have provided a python-ic `list` to `trexio.write_nucleus_charge` in the previous section. Why is it so? As has been mentioned before, TREXIO Python API internally relies on the use of the NumPy package to communicate arrays of `float`-like or `int`-like values. This prevents some memory leaks and grants additional flexibility to the API. What kind of flexibility? Check this out:
```python
print(f"return dtype in NumPy notation: ---> {charges_r.dtype}")
```
return dtype in NumPy notation: ---> float64
It means that the default precision of the TREXIO output is double (`np.float64`) for arrays of floating point numbers like `nucleus_charge`. But what if you do not need this extra precision and would like to read nuclear charges in single (`np.float32`) or even reduced (e.g. `np.float16`) precision? TREXIO Python API provides an additional (optional) argument for this. This argument is called `dtype` and accepts one of the [NumPy data types](https://numpy.org/doc/stable/user/basics.types.html). For example,
```python
charges_np = trexio.read_nucleus_charge(demo_file_r, dtype=np.float32)
```
```python
print(f"return dtype in NumPy notation: ---> {charges_np.dtype}")
```
return dtype in NumPy notation: ---> float32
### Reading multidimensional arrays
So far, we have only read flat 1D arrays. However, we have also written a 2D array of nuclear coordinates. Let's now read it back from the file:
```python
coords_r = trexio.read_nucleus_coord(demo_file_r)
```
```python
print(f"nucleus_coord from {filename} TREXIO file: \n{coords_r}")
```
nucleus_coord from benzene_demo.h5 TREXIO file:
[[ 0. 1.39250319 0. ]
[-1.20594314 0.6962516 0. ]
[-1.20594314 -0.6962516 0. ]
[ 0. -1.39250319 0. ]
[ 1.20594314 -0.6962516 0. ]
[ 1.20594314 0.6962516 0. ]
[-2.14171677 1.23652075 0. ]
[-2.14171677 -1.23652075 0. ]
[ 0. -2.47304151 0. ]
[ 2.14171677 -1.23652075 0. ]
[ 2.14171677 1.23652075 0. ]
[ 0. 2.47304151 0. ]]
```python
print(f"return shape: ---> {coords_r.shape}")
```
return shape: ---> (12, 3)
We can see that TREXIO returns a 2D array with 12 rows and 3 columns, which is consistent with the `nucleus_coord` dimensions `[nucleus_num, 3]`. What this means is that **by default TREXIO reshapes the output flat array into a multidimensional one** whenever applicable. This is done based on the shape specified in the TREX configuration file.
In some cases, it might be a good idea to explicitly check that the data exists in the file before reading it. This can be achieved using `has_`-suffixed functions of the API. For example,
```python
if trexio.has_nucleus_coord(demo_file_r):
coords_safer = trexio.read_nucleus_coord(demo_file_r)
```
## Conclusion
In this Tutorial, you have created a TREXIO file using HDF5 back end and have written the number of atoms, point group, nuclear charges, labels and coordinates, which correspond to benzene molecule. You have also learned how to read this data back from the TREXIO file and how to handle some TREXIO errors.