Merge pull request #411 from matt-frey/manual

Update the manual
EPIC-model · Nov 7, 2022 · d195164 · d195164
2 parents e36e8e0 + 3c855f1
commit d195164
Show file tree

Hide file tree

Showing 8 changed files with 97 additions and 34 deletions.
diff --git a/docs/Gemfile b/docs/Gemfile
@@ -19,6 +19,12 @@ group :jekyll_plugins do
   gem "jekyll-feed", "~> 0.12"
 end
 
+# 25 March 2022
+# https://github.com/asciidoctor/asciidoctor-mathematical
+# sudo apt-get install cmake
+# sudo apt-get install bison flex libffi-dev libxml2-dev libgdk-pixbuf2.0-dev libcairo2-dev libpango1.0-dev fonts-lyx
+gem "asciidoctor-mathematical"
+
 # Windows and JRuby does not include zoneinfo files, so bundle the tzinfo-data gem
 # and associated library.
 platforms :mingw, :x64_mingw, :mswin, :jruby do

diff --git a/docs/generate_manual.sh b/docs/generate_manual.sh
@@ -10,6 +10,6 @@ asciidoctor intro.adoc --destination-dir=../html
 
 # 22 March 2022
 # https://discuss.asciidoctor.org/Diagrams-referenced-by-URL-in-PDF-td4623.html
-asciidoctor-pdf -a allow-uri-read intro.adoc --destination-dir=../pdf
+asciidoctor-pdf -r asciidoctor-mathematical -a allow-uri-read intro.adoc --destination-dir=../pdf
 
 sed -i "s:$version:@VERSION@:g" intro.adoc
diff --git a/docs/html/intro.html b/docs/html/intro.html
@@ -554,7 +554,7 @@ <h3 id="sec-installation-configuring">1.3. Configuring</h3>
 <div class="content">
 <pre class="highlight"><code class="language-bash" data-lang="bash">$ mkdir build
 $ cd build
-$ ../configure ..</code></pre>
+$ ../configure</code></pre>
 </div>
 </div>
 <div class="paragraph">
@@ -652,7 +652,19 @@ <h2 id="_conventions_and_units">2. Conventions and Units</h2>
 <div class="sect1">
 <h2 id="_model">3. Model</h2>
 <div class="sectionbody">
-
+<div class="stemblock">
+<div class="content">
+\[\begin{align}
+    \label{eq:progu}
+    &amp; \frac{\mathrm{D}\boldsymbol{u}}{\mathrm{D} t}+2\Omega\,\hat{\boldsymbol{e}}_z\times\boldsymbol{u}
+        = -\frac{\nabla p}{\rho_0}+b\,\hat{\boldsymbol{e}}_z \,, \\
+    \label{eq:progb}
+    &amp; \frac{\mathrm{D} b_l}{\mathrm{D} t} = 0 \,, \\
+    \label{eq:progq}
+    &amp; \frac{\mathrm{D} q}{\mathrm{D} t} = 0 \,,
+\end{align}\]
+</div>
+</div>
 </div>
 </div>
 <div class="sect1">
@@ -663,8 +675,8 @@ <h3 id="_configuration_file">4.1. Configuration File</h3>
 <table class="tableblock frame-all grid-all stretch">
 <caption class="title">Table 2. EPIC input options and their default values.</caption>
 <colgroup>
-<col style="width: 22.2222%;">
 <col style="width: 11.1111%;">
+<col style="width: 22.2222%;">
 <col style="width: 66.6667%;">
 </colgroup>
 <thead>
@@ -678,7 +690,7 @@ <h3 id="_configuration_file">4.1. Configuration File</h3>
 <tr>
 <td class="tableblock halign-left valign-top"><p class="tableblock">field_file</p></td>
 <td class="tableblock halign-left valign-top"><p class="tableblock">n/a</p></td>
-<td class="tableblock halign-left valign-top"><p class="tableblock">NetCDF Input field file</p></td>
+<td class="tableblock halign-left valign-top"><p class="tableblock">NetCDF input field file</p></td>
 </tr>
 <tr>
 <td class="tableblock halign-left valign-top"><p class="tableblock">field_tol</p></td>
@@ -752,12 +764,12 @@ <h3 id="_configuration_file">4.1. Configuration File</h3>
 </tr>
 <tr>
 <td class="tableblock halign-left valign-top"><p class="tableblock">parcel%min_vratio</p></td>
-<td class="tableblock halign-left valign-top"><p class="tableblock">40</p></td>
+<td class="tableblock halign-left valign-top"><p class="tableblock">40 (2D) or 68 (3D)</p></td>
 <td class="tableblock halign-left valign-top"><p class="tableblock">Minimum ratio of grid cell volume / parcel volume</p></td>
 </tr>
 <tr>
 <td class="tableblock halign-left valign-top"><p class="tableblock">parcel%max_vratio</p></td>
-<td class="tableblock halign-left valign-top"><p class="tableblock">2.89</p></td>
+<td class="tableblock halign-left valign-top"><p class="tableblock">2.89 (2D) or 4.913 (3D)</p></td>
 <td class="tableblock halign-left valign-top"><p class="tableblock">Maximum ratio of grid cell volume / parcel volume</p></td>
 </tr>
 <tr>
@@ -816,7 +828,24 @@ <h2 id="_output">5. Output</h2>
 <div class="sect1">
 <h2 id="_citation">6. Citation</h2>
 <div class="sectionbody">
-
+<div class="paragraph">
+<p>Please cite the two-dimensional EPIC model using</p>
+</div>
+<div class="listingblock">
+<div class="content">
+<pre class="highlight"><code>@article{Frey2022,
+    title = {EPIC: The Elliptical Parcel-In-Cell method},
+    journal = {Journal of Computational Physics: X},
+    volume = {14},
+    pages = {100109},
+    year = {2022},
+    issn = {2590-0552},
+    doi = {https://doi.org/10.1016/j.jcpx.2022.100109},
+    url = {https://www.sciencedirect.com/science/article/pii/S2590055222000051},
+    author = {Matthias Frey and David Dritschel and Steven B\"oing}
+}</code></pre>
+</div>
+</div>
 </div>
 </div>
 </div>

diff --git a/docs/manual/citation.adoc b/docs/manual/citation.adoc
@@ -1 +1,15 @@
 == Citation
+Please cite the two-dimensional EPIC model using
+```
+@article{Frey2022,
+    title = {EPIC: The Elliptical Parcel-In-Cell method},
+    journal = {Journal of Computational Physics: X},
+    volume = {14},
+    pages = {100109},
+    year = {2022},
+    issn = {2590-0552},
+    doi = {https://doi.org/10.1016/j.jcpx.2022.100109},
+    url = {https://www.sciencedirect.com/science/article/pii/S2590055222000051},
+    author = {Matthias Frey and David Dritschel and Steven B\"oing}
+}
+```
diff --git a/docs/manual/input.adoc b/docs/manual/input.adoc
@@ -4,36 +4,36 @@
 
 
 .EPIC input options and their default values.
-[cols="2,1,6"]
+[cols="1,2,6"]
 |===
-|Parameter                  |Default    |Description
+|Parameter                  |Default                |Description
 
-|field_file                 |n/a        |NetCDF Input field file
-|field_tol                  |1.0d-10    |Tolerance for parcel generation from field file
+|field_file                 |n/a                    |NetCDF input field file
+|field_tol                  |1.0d-10                |Tolerance for parcel generation from field file
 
-|output%field_freq          |1          |Write after these many seconds to the field NetCDF file
-|output%parcel_freq         |1          |Write after these many seconds to the parcel NetCDF file
-|output%parcel_stats_freq   |1          |Write after these many seconds to parcel stats NetCDF file
-|output%field_stats_freq    |1          |Write after these many seconds to the field stats NetCDF file
-|output%write_fields        |.true.     |Enable / disable field dump
-|output%write_parcels       |.true.     |Enable / disable parcel dump
-|output%write_parcel_stats  |.true.     |Enable / disable parcel statistics
-|output%write_field_stats   |.true.     |Enable / disable field statistics
-|output%overwrite           |.false.    |Replace existing NetCDF files
-|output%basename            |n/a        |NetCDF output base name
+|output%field_freq          |1                      |Write after these many seconds to the field NetCDF file
+|output%parcel_freq         |1                      |Write after these many seconds to the parcel NetCDF file
+|output%parcel_stats_freq   |1                      |Write after these many seconds to parcel stats NetCDF file
+|output%field_stats_freq    |1                      |Write after these many seconds to the field stats NetCDF file
+|output%write_fields        |.true.                 |Enable / disable field dump
+|output%write_parcels       |.true.                 |Enable / disable parcel dump
+|output%write_parcel_stats  |.true.                 |Enable / disable parcel statistics
+|output%write_field_stats   |.true.                 |Enable / disable field statistics
+|output%overwrite           |.false.                |Replace existing NetCDF files
+|output%basename            |n/a                    |NetCDF output base name
 
-|parcel%size_factor         |1          |Factor to increase max. number of parcels
-|parcel%n_per_cell          |9          |Initial number of parcels per cell
-|parcel%lambda_max          |4          |Maximum parcel aspect ratio
-|parcel%min_vratio          |40         |Minimum ratio of grid cell volume / parcel volume
-|parcel%max_vratio          |2.89       |Maximum ratio of grid cell volume / parcel volume
-|parcel%correction_iters    |2          |How many parcel correction iterations
-|parcel%gradient_pref       |1.8        |Gradient correction prefactor
-|parcel%max_compression     |0.5        |Gradient correction maximum compression
+|parcel%size_factor         |1                      |Factor to increase max. number of parcels
+|parcel%n_per_cell          |9                      |Initial number of parcels per cell
+|parcel%lambda_max          |4                      |Maximum parcel aspect ratio
+|parcel%min_vratio          |40 (2D) or 68 (3D)     |Minimum ratio of grid cell volume / parcel volume
+|parcel%max_vratio          |2.89 (2D) or 4.913 (3D)|Maximum ratio of grid cell volume / parcel volume
+|parcel%correction_iters    |2                      |How many parcel correction iterations
+|parcel%gradient_pref       |1.8                    |Gradient correction prefactor
+|parcel%max_compression     |0.5                    |Gradient correction maximum compression
 
-|time%limit                 |0.0        |Time limit (s)
-|time%alpha                 |0.2        |Scaling factor for the strain and buoyancy gradient time step
-|time%precise_stop          |.false.    |Stop exactly at the time limit
+|time%limit                 |0.0                    |Time limit (s)
+|time%alpha                 |0.2                    |Scaling factor for the strain and buoyancy gradient time step
+|time%precise_stop          |.false.                |Stop exactly at the time limit
 
 |===
 

diff --git a/docs/manual/installation.adoc b/docs/manual/installation.adoc
@@ -45,7 +45,7 @@ in your terminal. You then create a build directory and configure EPIC
 ----
 $ mkdir build
 $ cd build
-$ ../configure ..
+$ ../configure
 ----
 The most important configure options are given in <<tab_configure_options>>. You can also append the flag `--help`
 to see all available options.

diff --git a/docs/manual/intro.adoc b/docs/manual/intro.adoc
@@ -3,6 +3,7 @@ Matthias Frey (Univ. of St Andrews); David G. Dritschel (Univ. of St Andrews); S
 v@VERSION@
 :version-label: Version
 :page-layout: default
+:stem: latexmath
 :toc: left
 :sectnums:
 

diff --git a/docs/manual/model.adoc b/docs/manual/model.adoc
@@ -1 +1,14 @@
+:stem: latexmath
 == Model
+[stem]
+++++
+\begin{align}
+    \label{eq:progu}
+    & \frac{\mathrm{D}\boldsymbol{u}}{\mathrm{D} t}+2\Omega\,\hat{\boldsymbol{e}}_z\times\boldsymbol{u}
+        = -\frac{\nabla p}{\rho_0}+b\,\hat{\boldsymbol{e}}_z \,, \\
+    \label{eq:progb}
+    & \frac{\mathrm{D} b_l}{\mathrm{D} t} = 0 \,, \\
+    \label{eq:progq}
+    & \frac{\mathrm{D} q}{\mathrm{D} t} = 0 \,,
+\end{align}
+++++