Add a topic guide on deriving the ebtel++ equations (#111)

* refactor result return type * add linux boost install instructions * minor touchups * add derivation topic guide;revamp landing page * add reference to derivation page * touchup topic guide
rice-solar-physics · Sep 17, 2024 · ab8a68d · ab8a68d
1 parent fa19fd3
commit ab8a68d
Show file tree

Hide file tree

Showing 14 changed files with 509 additions and 100 deletions.
diff --git a/docs/conf.py b/docs/conf.py
@@ -92,6 +92,7 @@
 html_theme = "pydata_sphinx_theme"
 
 html_theme_options = {
+    "show_nav_level": 2,
     "logo": {
         "text": f"ebtelplusplus {version}",
     },
@@ -119,7 +120,6 @@
 html_sidebars = {
     "bibliography*": [],
     "development*": [],
-    "comparison*": [],
 }
 # Render inheritance diagrams in SVG
 graphviz_output_format = "svg"

diff --git a/docs/development.rst b/docs/development.rst
@@ -16,7 +16,7 @@ Next, clone your fork,
 
     git clone https://github.com/<your-user-name>/ebtelPlusPlus.git
 
-Because ``ebtelplusplus`` implements the actual simulation code in C++ and thus is not a pure Python package, installation of this package requires first compiling the C++ and building the needed binaries.
+Because ``ebtelplusplus`` implements the actual simulation code in C++ and thus is not a pure Python package, installation of this package requires first compiling the C++ code and building the needed binaries.
 To do this, you will first need to have the `Boost <http://www.boost.org/>`__ package installed (at least v1.53).
 There are various ways to install this package, including:
 
@@ -29,6 +29,12 @@ There are various ways to install this package, including:
     * - `conda-forge <https://github.com/conda-forge/boost-feedstock>`__
       - any
       - ``conda install -c conda-forge libboost-devel``
+    * - APT
+      - Linux (Debian-based)
+      - ``apt install libboost-all-dev``
+    * - YUM
+      - Linux (RHEL)
+      - ``yum install boost-devel``
     * - `Homebrew <https://formulae.brew.sh/formula/boost>`__
       - macOS
       - ``brew install boost``

diff --git a/docs/index.rst b/docs/index.rst
@@ -6,23 +6,63 @@ ebtelplusplus
    :hidden:
 
    generated/gallery/index
-   comparison
+   topic_guides/index
    development
    reference
    bibliography
 
-``ebtelplusplus`` (or ``ebtel++``) is a two-fluid version of the original enthalpy-based thermal evolution of loops (EBTEL) model implemented in C++ and wrapped in Python.
-The EBTEL model, originally developed by :cite:t:`klimchuk_highly_2008`, efficiently computes spatially-averaged, time-dependent plasma parameters ( e.g. temperature,  pressure, density) of dynamically-heated coronal loops.
-It is often desirable to compute solutions for a large number of coronal loops, but the spatial and temporal scales needed to solve the full 1D-hydrodynamic equations lead to long compute times for even 1D hydrodynamic codes.
-EBTEL computes quick and accurate solutions for spatially-averaged quantities, allowing efficient insight into how these monolithic structures evolve.
-EBTEL also calculates the differential emission measure (DEM) for both the transition region and the corona.
-Details regarding this formulation can be found in :cite:t:`klimchuk_highly_2008`.
+``ebtelplusplus`` (or ``ebtel++``) is an implementation of the enthalpy-based thermal evolution of loops (EBTEL) model implemented in C++ and wrapped in Python.
+
+.. grid:: 1 2 2 2
+    :gutter: 2
+
+    .. grid-item-card:: Examples
+        :link: generated/gallery
+        :text-align: center
+
+        :material-outlined:`palette;8em;sd-text-secondary`
+
+        Examples of how to set up a simulation
+
+    .. grid-item-card:: Topic Guides
+        :link: ebtelplusplus-topic-guide
+        :link-type: ref
+        :text-align: center
+
+        :material-outlined:`school;8em;sd-text-secondary`
+
+        Detailed explanations about the EBTEL model
+
+    .. grid-item-card:: Contributing
+        :link: ebtelplusplus-development
+        :link-type: ref
+        :text-align: center
+
+        :material-outlined:`code;8em;sd-text-secondary`
+
+        Instructions for how to contribute to `ebtelplusplus`
+
+    .. grid-item-card:: Reference
+        :link: ebtelplusplus-reference
+        :link-type: ref
+        :text-align: center
+
+        :material-outlined:`menu_book;8em;sd-text-secondary`
+
+        Technical description of the inputs, outputs, and behavior of each component of ebteplusplus
 
 .. note::
 
    If you are looking for the original IDL implementation,
    the repository for that code can be found `here <https://github.com/rice-solar-physics/EBTEL>`__.
 
+The EBTEL model, originally developed by :cite:t:`klimchuk_highly_2008`, efficiently computes spatially-averaged, time-dependent plasma parameters ( e.g. temperature,  pressure, density) of dynamically-heated coronal loops.
+It is often desirable to compute solutions for a large number of coronal loops, but the spatial and temporal scales needed to solve the full 1D-hydrodynamic equations lead to long compute times for even 1D hydrodynamic codes.
+EBTEL computes quick and accurate solutions for spatially-averaged quantities, allowing efficient insight into how these monolithic structures evolve.
+EBTEL also calculates the differential emission measure (DEM) for both the transition region and the corona.
+Details regarding this formulation can be found in :cite:t:`klimchuk_highly_2008`.
+For a more detailed overview of the model, see :ref:`ebtelplusplus-topic-guide-derivation`.
+
 Installation
 ------------
 
@@ -40,38 +80,18 @@ Once you've successfully installed ``ebtelplusplus``, see the Example Gallery fo
 Citation
 --------
 
-If you use ``ebtelplusplus`` in any published work, please include citations to the following papers:
+If you use ``ebtelplusplus`` in any published work, we ask that you please include citations to the following papers:
 
 * :cite:t:`klimchuk_highly_2008`
 * :cite:t:`cargill_enthalpy-based_2012`
 * :cite:t:`cargill_enthalpy-based_2012-1`
 * :cite:t:`barnes_inference_2016`
 
+If you make use of the variable abundance feature in the radiative losses, please also cite :cite:t:`reep_modeling_2024`.
 Additionally, please add the following line within your methods, conclusion or acknowledgements sections:
 
 *This research used version X.Y.Z (software citation) of the ebtelplusplus open source software package.*
 
 The software citation should be the specific `Zenodo DOI`_ for the version used within your work.
-The citation for most current version on Zenodo is,
-
-.. code:: bibtex
-
-   @software{Barnes2024,
-      author       = {Barnes, Will and
-                      Klimchuk, James and
-                      Cargill, Peter and
-                      Bradshaw, Stephen and
-                      Reep, Jeffrey and
-                      Schonfeld, Samuel and
-                      Collazzo, Rowan},
-      title        = {rice-solar-physics/ebtelPlusPlus: v0.2},
-      month        = jul,
-      year         = 2024,
-      publisher    = {Zenodo},
-      version      = {v0.2},
-      doi          = {10.5281/zenodo.12675386},
-      url          = {https://doi.org/10.5281/zenodo.12675386}
-   }
-
 
 .. _Zenodo DOI: https://zenodo.org/records/12675374
diff --git a/docs/reference.rst b/docs/reference.rst
@@ -3,6 +3,16 @@
 API Reference
 =============
 
+ebtelplusplus
+-------------
+
 .. automodapi:: ebtelplusplus
+    :no-heading:
+    :no-main-docstr:
+    :no-inheritance-diagram:
+
+ebtelplusplus.models
+--------------------
 
 .. automodapi:: ebtelplusplus.models
+    :no-heading:
diff --git a/docs/references.bib b/docs/references.bib
@@ -106,3 +106,17 @@ @article{reep_modeling_2024
   annotation = {ADS Bibcode: 2024ApJ...970L..41R}
 }
 
+@article{reep_geometric_2022,
+  title = {Geometric {{Assumptions}} in {{Hydrodynamic Modeling}} of {{Coronal}} and {{Flaring Loops}}},
+  author = {Reep, Jeffrey W. and {Ugarte-Urra}, Ignacio and Warren, Harry P. and Barnes, Will T.},
+  year = {2022},
+  month = jul,
+  journal = {The Astrophysical Journal},
+  volume = {933},
+  pages = {106},
+  issn = {0004-637X},
+  doi = {10.3847/1538-4357/ac7398},
+  urldate = {2023-08-29},
+  annotation = {ADS Bibcode: 2022ApJ...933..106R}
+}
+
diff --git a/docs/comparison.rst → docs/topic_guides/comparison.rst b/docs/comparison.rst → docs/topic_guides/comparison.rst
@@ -1,4 +1,4 @@
-.. _ebtelplusplus-comparison:
+.. _ebtelplusplus-topic-guide-comparison:
 
 Why ebtelplusplus?
 ======================