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