Skip to content

Commit

Permalink
build based on 0433e34
Browse files Browse the repository at this point in the history
  • Loading branch information
Documenter.jl committed Dec 5, 2023
1 parent efc36b9 commit bf9715f
Show file tree
Hide file tree
Showing 20 changed files with 999 additions and 3 deletions.
2 changes: 1 addition & 1 deletion stable
View file
Original file line number Diff line number Diff line change
@@ -1 +1 @@
v0.2.3
v0.2.4
2 changes: 1 addition & 1 deletion v0.2
View file
Original file line number Diff line number Diff line change
@@ -1 +1 @@
v0.2.3
v0.2.4
20 changes: 20 additions & 0 deletions v0.2.4/api/convention/index.html
View file
Original file line number Diff line number Diff line change
@@ -0,0 +1,20 @@
<!DOCTYPE html>
<html lang="en"><head><meta charset="UTF-8"/><meta name="viewport" content="width=device-width, initial-scale=1.0"/><title>Convention · WannierIO.jl</title><script data-outdated-warner src="../../assets/warner.js"></script><link href="https://cdnjs.cloudflare.com/ajax/libs/lato-font/3.0.0/css/lato-font.min.css" rel="stylesheet" type="text/css"/><link href="https://cdnjs.cloudflare.com/ajax/libs/juliamono/0.045/juliamono.min.css" rel="stylesheet" type="text/css"/><link href="https://cdnjs.cloudflare.com/ajax/libs/font-awesome/5.15.4/css/fontawesome.min.css" rel="stylesheet" type="text/css"/><link href="https://cdnjs.cloudflare.com/ajax/libs/font-awesome/5.15.4/css/solid.min.css" rel="stylesheet" type="text/css"/><link href="https://cdnjs.cloudflare.com/ajax/libs/font-awesome/5.15.4/css/brands.min.css" rel="stylesheet" type="text/css"/><link href="https://cdnjs.cloudflare.com/ajax/libs/KaTeX/0.13.24/katex.min.css" rel="stylesheet" type="text/css"/><script>documenterBaseURL="../.."</script><script src="https://cdnjs.cloudflare.com/ajax/libs/require.js/2.3.6/require.min.js" data-main="../../assets/documenter.js"></script><script src="../../siteinfo.js"></script><script src="../../../versions.js"></script><link class="docs-theme-link" rel="stylesheet" type="text/css" href="../../assets/themes/documenter-dark.css" data-theme-name="documenter-dark" data-theme-primary-dark/><link class="docs-theme-link" rel="stylesheet" type="text/css" href="../../assets/themes/documenter-light.css" data-theme-name="documenter-light" data-theme-primary/><script src="../../assets/themeswap.js"></script></head><body><div id="documenter"><nav class="docs-sidebar"><div class="docs-package-name"><span class="docs-autofit"><a href="../../">WannierIO.jl</a></span></div><form class="docs-search" action="../../search/"><input class="docs-search-query" id="documenter-search-query" name="q" type="text" placeholder="Search docs"/></form><ul class="docs-menu"><li><a class="tocitem" href="../../">Home</a></li><li><span class="tocitem">API</span><ul><li class="is-active"><a class="tocitem" href>Convention</a><ul class="internal"><li><a class="tocitem" href="#Units"><span>Units</span></a></li><li><a class="tocitem" href="#Variables"><span>Variables</span></a></li><li><a class="tocitem" href="#Functions"><span>Functions</span></a></li></ul></li><li><a class="tocitem" href="../util/">Utilities</a></li><li><a class="tocitem" href="../w90/">Wannier90</a></li><li><a class="tocitem" href="../volumetric/">Volumetric data</a></li><li><a class="tocitem" href="../qe/">Quantum ESPRESSO</a></li><li><a class="tocitem" href="../epw/">EPW</a></li><li><a class="tocitem" href="../">Index</a></li></ul></li></ul><div class="docs-version-selector field has-addons"><div class="control"><span class="docs-label button is-static is-size-7">Version</span></div><div class="docs-selector control is-expanded"><div class="select is-fullwidth is-size-7"><select id="documenter-version-selector"></select></div></div></div></nav><div class="docs-main"><header class="docs-navbar"><nav class="breadcrumb"><ul class="is-hidden-mobile"><li><a class="is-disabled">API</a></li><li class="is-active"><a href>Convention</a></li></ul><ul class="is-hidden-tablet"><li class="is-active"><a href>Convention</a></li></ul></nav><div class="docs-right"><a class="docs-edit-link" href="https://github.com/qiaojunfeng/WannierIO.jl/blob/main/docs/src/api/convention.md" title="Edit on GitHub"><span class="docs-icon fab"></span><span class="docs-label is-hidden-touch">Edit on GitHub</span></a><a class="docs-settings-button fas fa-cog" id="documenter-settings-button" href="#" title="Settings"></a><a class="docs-sidebar-button fa fa-bars is-hidden-desktop" id="documenter-sidebar-button" href="#"></a></div></header><article class="content" id="documenter-page"><h1 id="Conventions"><a class="docs-heading-anchor" href="#Conventions">Conventions</a><a id="Conventions-1"></a><a class="docs-heading-anchor-permalink" href="#Conventions" title="Permalink"></a></h1><h2 id="Units"><a class="docs-heading-anchor" href="#Units">Units</a><a id="Units-1"></a><a class="docs-heading-anchor-permalink" href="#Units" title="Permalink"></a></h2><p>In most cases, the units of the function arguments and returned values are in angstrom for lattice, and fractional (w.r.t. lattice) for atomic positions, etc.</p><h2 id="Variables"><a class="docs-heading-anchor" href="#Variables">Variables</a><a id="Variables-1"></a><a class="docs-heading-anchor-permalink" href="#Variables" title="Permalink"></a></h2><p>Here are some variable conventions used throughout the code and documentation.</p><h3 id="Names"><a class="docs-heading-anchor" href="#Names">Names</a><a id="Names-1"></a><a class="docs-heading-anchor-permalink" href="#Names" title="Permalink"></a></h3><ul><li><code>U</code>: unitary transformation matrices<ul><li><code>A</code>: to differentiate between <code>U</code>, some times we use <code>A</code> specifically for the initial projection matrix, i.e., <code>amn</code> of Wannier90</li></ul></li><li><code>M</code>: overlap matrices between neighboring kpoints, i.e., <code>mmn</code> of Wannier90</li></ul><h3 id="Dimensions"><a class="docs-heading-anchor" href="#Dimensions">Dimensions</a><a id="Dimensions-1"></a><a class="docs-heading-anchor-permalink" href="#Dimensions" title="Permalink"></a></h3><p>Prefixed by <code>n_</code>, indicating this is an integer specifying the length of some quantities; then followed by a short acronym of the quantity, to avoid typing long names repeatedly.</p><ul><li><code>n_bands</code>: number of bands</li><li><code>n_wann</code>: number of WFs</li><li><code>n_kpts</code>: number of kpoints</li><li><code>n_bvecs</code>: number of b-vectors</li><li><code>n_atoms</code>: number of atoms</li></ul><h3 id="Indices"><a class="docs-heading-anchor" href="#Indices">Indices</a><a id="Indices-1"></a><a class="docs-heading-anchor-permalink" href="#Indices" title="Permalink"></a></h3><p>Usually, the returned quantities are <code>Vector</code>s of some types (<code>Matrix{Float64}</code>, <code>Vector{Float64}</code>, etc), and the indices follow the order of</p><ol><li>kpoints</li><li>b-vectors (if needed)</li><li>bands</li><li>Wannier functions</li></ol><p>For instance, the energy eigenvalues <code>eigenvalues</code> is a length-<code>n_kpts</code> vector, with each element a length-<code>n_bands</code> vector of floats, i.e., <code>eigenvalues[ik][ib]</code> is the <code>ib</code>-th eigenvalue at <code>ik</code>-th kpoint.</p><p>Here are some examples of indexing the vectors:</p><ul><li><code>eigenvalues[ik][m]</code> for energy eigenvalues <span>$\varepsilon_{m \mathbf{k}}$</span></li><li><code>U[ik][m, n]</code> for the gauge matrix <span>$U_{mn \mathbf{k}}$</span></li><li><code>M[ik][ib][m, n]</code> for the overlap matrix <span>$M_{mn \mathbf{k}, \mathbf{k} + \mathbf{b}}$</span></li></ul><p>where</p><ul><li><code>ik</code>: index of kpoints</li><li><code>ib</code>: index of b-vectors</li><li><code>m</code>: index of bands</li><li><code>n</code>: index of Wannier functions</li></ul><h2 id="Functions"><a class="docs-heading-anchor" href="#Functions">Functions</a><a id="Functions-1"></a><a class="docs-heading-anchor-permalink" href="#Functions" title="Permalink"></a></h2><p>In most cases, there are some multiple dispatches for the same function. For instance, there are three functions for reading the <code>chk</code> file:</p><pre><code class="language-julia hljs">read_chk(filename::AbstractString)
read_chk(filename::AbstractString, ::FortranText)
read_chk(filename::AbstractString, ::FortranBinary)</code></pre><p>Why do we need several functions for reading the same format? The reasons are:</p><ul><li>Wannier90 is a Fortran code that accepts both Fortran text format and binary format (or called Fortran formatted and unformatted file, respectively). To avoid introducing lots of different function names for reading text or binary files, we use multiple dispatch to distinguish them: the type of the 2nd argument (<code>FortranText</code> or <code>FortranBinary</code>) is used to distinguish the file type we want to read.</li><li>However, asking the user to manually specify the file format is tedious, therefore, we provide a high-level user-friendly function (the 1st one), which<ul><li>automatically detects the file format and calls the corresponding low-level (2nd or 3rd) function</li><li>prints some information of key quantities of the file, e.g., number of kpoints, number of Wannier functions, etc., to give user a hint of what have been parsed</li><li>hides some irrelevant return values, e.g., the header (the 1st line) of the file, since it has been printed in the stdout</li></ul></li><li>The low-level functions parse everything in the file, while the high-level function aims at user ergonomics.</li></ul><p>Thus,</p><ul><li><p>In most cases using the high-level function is enough, e.g.,</p><pre><code class="language-julia-repl hljs">julia&gt; using WannierIO
julia&gt; A = read_amn(&quot;si2.amn&quot;)
┌ Info: Reading amn file
│ filename = &quot;si2.amn&quot;
│ header = &quot;Created on 9Sep2022 at 16:41: 5&quot;
│ n_kpts = 8
│ n_bands = 4
└ n_wann = 4
8-element Vector{Matrix{ComplexF64}}:
[...]</code></pre></li><li><p>Use the low-level functions if you</p><ul><li>want to get the header of the file (or quantities not returned by high-level function)</li><li>do not want stdout to be &quot;polluted&quot;</li></ul><pre><code class="language-julia-repl hljs">julia&gt; using WannierIO
julia&gt; A, header = read_amn(&quot;si2.amn&quot;, WannierIO.FortranText())
julia&gt; typeof(A)
Vector{Matrix{ComplexF64}} (alias for Array{Array{Complex{Float64}, 2}, 1})
julia&gt; header
&quot;Created on 9Sep2022 at 16:41: 5&quot;</code></pre></li></ul><p>Note that usually the high-level function directly returns the quantities, e.g., a single <code>A</code> to avoid the user unpacking return values; however, often the low-level functions return a <code>NamedTuple</code> of all the quantities, for the sake of clarity.</p><pre><code class="language-julia-repl hljs">julia&gt; amn = read_amn(&quot;si2.amn&quot;, WannierIO.FortranText())
julia&gt; typeof(amn)
NamedTuple{(:A, :header), Tuple{Vector{Matrix{ComplexF64}}, SubString{String}}}</code></pre><p>Of course, when using low-level functions you can also directly access the quantity without unpacking by</p><pre><code class="language-julia-repl hljs">julia&gt; A = read_amn(&quot;si2.amn&quot;, WannierIO.FortranText()).A</code></pre><p>When writing files, the user can specify whether to write in text or binary by a keyword argument <code>binary</code> of the high-level function</p><pre><code class="language-julia-repl hljs">julia&gt; write_amn(&quot;si2.amn&quot;, A; binary=true)</code></pre><p>The <code>binary</code> keyword argument avoids the user specifying the file type when calling the low-level functions, e.g.,</p><pre><code class="language-julia-repl hljs">julia&gt; write_amn(&quot;si2.amn&quot;, A, WannierIO.FortranBinaryStream())</code></pre></article><nav class="docs-footer"><a class="docs-footer-prevpage" href="../../">« Home</a><a class="docs-footer-nextpage" href="../util/">Utilities »</a><div class="flexbox-break"></div><p class="footer-message">Powered by <a href="https://github.com/JuliaDocs/Documenter.jl">Documenter.jl</a> and the <a href="https://julialang.org/">Julia Programming Language</a>.</p></nav></div><div class="modal" id="documenter-settings"><div class="modal-background"></div><div class="modal-card"><header class="modal-card-head"><p class="modal-card-title">Settings</p><button class="delete"></button></header><section class="modal-card-body"><p><label class="label">Theme</label><div class="select"><select id="documenter-themepicker"><option value="documenter-light">documenter-light</option><option value="documenter-dark">documenter-dark</option></select></div></p><hr/><p>This document was generated with <a href="https://github.com/JuliaDocs/Documenter.jl">Documenter.jl</a> version 0.27.25 on <span class="colophon-date" title="Tuesday 5 December 2023 14:27">Tuesday 5 December 2023</span>. Using Julia version 1.9.4.</p></section><footer class="modal-card-foot"></footer></div></div></div></body></html>
Loading

0 comments on commit bf9715f

Please sign in to comment.