add separate page on software comparison

MANIFEST.in

@@ -4,8 +4,5 @@
 prune build
 prune docs/_build
 prune docs/api
+prune docs/generated
 global-exclude *.pyc *.o
-
-# This subpackage is only used in development checkouts
-# and should not be included in built tarballs
-prune ebtelplusplus/_dev

docs/comparison.rst

@@ -0,0 +1,93 @@
+.. _ebtelplusplus-comparison:
+
+Why ebtelplusplus?
+======================
+
+For various historical reasons, there are multiple software implementations of the EBTEL model.
+There are currently *three* maintained implementations of the model as described below.
+Hereafter, "EBTEL" refers to the model generally while each software implementation is given
+its own unique name (e.g. ``ebtelplusplus``).
+This page briefly explains the differences between each implementation and the advantages of
+the ``ebtelplusplus`` implementation.
+
+The table below summarizes the comparison of the different EBTEL software implementations and the different features provided by each.
+
+.. list-table::
+   :header-rows: 1
+   :align: center
+
+   * - Feature
+     - Citation
+     - |EBTEL-IDL|_
+     - ``ebtel++``
+     - |EBTEL3-IDL|_
+   * - Decouple electrons and ions
+     - :cite:t:`barnes_inference_2016`
+     - :octicon:`x;1em;sd-text-danger`
+     - :octicon:`check;1em;sd-text-success`
+     - :octicon:`x;1em;sd-text-danger`
+   * - Adaptive time step
+     - :cite:t:`barnes_inference_2016`
+     - :octicon:`x;1em;sd-text-danger`
+     - :octicon:`check;1em;sd-text-success`
+     - :octicon:`check;1em;sd-text-success`
+   * - Area expansion
+     - :cite:t:`cargill_static_2022`
+     - :octicon:`check;1em;sd-text-success`
+     - :octicon:`check;1em;sd-text-success`
+     - :octicon:`x;1em;sd-text-danger`
+   * - Supersonic flows
+     - :cite:t:`rajhans_flows_2022`
+     - :octicon:`x;1em;sd-text-danger`
+     - :octicon:`x;1em;sd-text-danger`
+     - :octicon:`check;1em;sd-text-success`
+
+
+``EBTEL-IDL``
+-------------
+
+The original software implementation of EBTEL was in the Interactive Data Language (IDL) and
+was based off of the model presented in :cite:t:`klimchuk_highly_2008`.
+Subsequent improvements in :cite:t:`cargill_enthalpy-based_2012` were made to give better
+agreement with spatially-resolved hydrodynamic models.
+These improvements were also implemented in IDL.
+This version is sometimes referred to as "EBTEL2".
+:cite:t:`cargill_static_2022` extended the EBTEL model to include effects due to cross-sectional
+area expansion and implemented this in IDL as well.
+The IDL software implementation which includes all of these features is referred to as |EBTEL-IDL|_.
+
+``ebtelplusplus``
+-----------------
+
+:cite:t:`barnes_inference_2016` improved upon the implementation of :cite:t:`cargill_enthalpy-based_2012`
+by extending the treatment to the two-fluid hydrodynamic equations, allowing for differential heating
+between electrons and ions.
+They also introduced a slightly modified approach for calculating the the :math:`c_1`` parameter during
+the conductive cooling phase :cite:p:`{see Appendix A of}barnes_inference_2016`.
+Modifications to include area expansion in the manner of :cite:t:`cargill_static_2022` were subsequently added.
+Furthermore, the resulting equations are solved using a Runge-Kutta Cash-Karp integration method
+:cite:p:`{see section 16.2 of}press_numerical_1992` and an (optional) adaptive time-stepping technique
+to ensure the principal physical timescales are resolved at each phase of the loop evolution.
+The software implementation of this version of the model is referred to as ``ebtelplusplus`` (or ``ebtel++``).
+The majority of the software is implemented in C++ for computational efficiency and is wrapped in Python
+to enable easy installation and a user-friendly API.
+This is the implementation provided by this software package.
+``ebtelplusplus`` has been benchmarked against both |EBTEL-IDL|_ as well as more advanced field-aligned
+hydrodynamic models :cite:p:`barnes_inference_2016`.
+
+``EBTEL3-IDL``
+--------------
+
+:cite:t:`rajhans_flows_2022` built upon the model of :cite:t:`cargill_enthalpy-based_2012` and relaxed
+the assumption of subsonic flows in EBTEL.
+Additionally the Mach numbers and velocities produced are in better agreement with field-aligned
+hydrodynamic simulations.
+The IDL software implementation of this model is referred to as |EBTEL3-IDL|_.
+|EBTEL3-IDL|_ uses an adaptive time grid to ensure the appropriate timescales are resolved in the
+impulsive phase.
+
+
+.. |EBTEL-IDL| replace:: ``EBTEL-IDL``
+.. _EBTEL-IDL: https://github.com/rice-solar-physics/EBTEL
+.. |EBTEL3-IDL| replace:: ``EBTEL3-IDL``
+.. _EBTEL3-IDL: https://github.com/rice-solar-physics/EBTEL3

docs/conf.py

@@ -13,6 +13,7 @@
 from ebtelplusplus import __version__
 
 release = __version__
+is_development = '.dev' in __version__
 
 project = "ebtelplusplus"
 author = "Will Barnes"
@@ -37,6 +38,8 @@
     "sphinx_automodapi.automodapi",
     "sphinx_automodapi.smart_resolver",
     "sphinx_gallery.gen_gallery",
+    "sphinx_design",
+    "sphinx_copybutton",
 ]
 
 # Add any paths that contain templates here, relative to this directory.
@@ -102,6 +105,7 @@
 html_sidebars = {
     "bibliography*": [],
     "development*": [],
+    "comparison*": [],
 }
 # Render inheritance diagrams in SVG
 graphviz_output_format = "svg"

docs/development.rst

@@ -14,33 +14,48 @@ Next, clone your fork,
 
 .. code:: shell
 
-    $ git clone https://github.com/<your-user-name>/ebtelPlusPlus.git
+    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.
 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:
 
-* ``conda install -c conda-forge libboost-devel`` with `conda-forge <https://github.com/conda-forge/boost-feedstock>`__
-* ``brew install boost`` with `Homebrew <https://formulae.brew.sh/formula/boost>`__
-* ``sudo port install boost`` with `Macports <https://ports.macports.org/port/boost/>`__
-* ``sudo apt-get install libboost-all-dev`` on Debian Linux
-* `from source <https://www.boost.org/doc/>`__
+.. list-table::
+    :header-rows: 1
+
+    * - Source
+      - OS
+      - Command
+    * - `conda-forge <https://github.com/conda-forge/boost-feedstock>`__
+      - any
+      - ``conda install -c conda-forge libboost-devel``
+    * - `Homebrew <https://formulae.brew.sh/formula/boost>`__
+      - macOS
+      - ``brew install boost``
+    * - `Macports <https://ports.macports.org/port/boost/>`__
+      - macOS
+      - ``sudo port install boost``
+    * - `Chocolatey <https://community.chocolatey.org/packages/boost-msvc-14.3>`__
+      - Windows
+      - ``choco install boost-msvc-14.3``
 
 The reason that Boost is required is that ``ebtelplusplus`` uses the ``Boost.Numeric.Odeint`` package to solve the EBTEL equations.
 Once you have successfully installed Boost, you can install ``ebtelplusplus``,
 
 .. code:: shell
 
-    $ cd ebteplusplus
-    $ pip install -e .[dev]
+    cd ebteplusplus
+    pip install -e .[dev]
 
-This will compile the C++ code (using `pybind11 <https://pybind11.readthedocs.io/en/stable/index.html>`__ and `scikit-build-core <https://scikit-build-core.readthedocs.io/en/latest/>`__) and install the ``ebtelplusplus``, including all of the dependencies for testing and developing the package.
+This will compile the C++ code (using `pybind11 <https://pybind11.readthedocs.io/en/stable/index.html>`__ and
+`scikit-build-core <https://scikit-build-core.readthedocs.io/en/latest/>`__) and install the ``ebtelplusplus``
+package, including all of the dependencies for testing and developing the package.
 
 To verify that you have a working installation, you can run the test suite,
 
 .. code:: shell
 
-    $ pytest ebtelplusplus
+    pytest ebtelplusplus
 
 You are now ready to start contributing to or modifying ``ebtelplusplus``.
 Note that if you are modifying any of the simulation code, that is contained in ``ebtelplusplus/extern`` and is implemented in C++.

docs/index.rst

@@ -6,28 +6,29 @@ ebtelplusplus
    :hidden:
 
    generated/gallery/index
+   comparison
    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++.
-This code provides an enhanced description of plasma behavior above roughly 5 MK.
-If you are looking for the original IDL implementation, `repository for the original IDL code can be found here <https://github.com/rice-solar-physics/EBTEL>`__.
-
+``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.
-:cite:t:`barnes_inference_2016` improved upon this model by extending the treatment to the two-fluid hydrodynamic equations, allowing for differential heating between electrons and ions.
-This also introduced a slightly different model for calculating the the :math:`c_1`` parameter during conductive cooling :cite:p:`{see Appendix A of}barnes_inference_2016`.
 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`.
 
+.. note::
+
+   If you are looking for the original IDL implementation,
+   the repository for the original IDL code can be found `here <https://github.com/rice-solar-physics/EBTEL>`__.
+
 Installation
 ------------
 
 The easiest way to install ``ebtelplusplus`` is through ``pip``,
 
-.. code::
+.. code:: shell
 
    pip install ebtelplusplus
 
@@ -36,13 +37,10 @@ Note that it is not necessary to compile the code locally in order to use ``ebte
 If you are interested in modifying or contributing to ``ebtelplusplus``, see the :ref:`ebtelplusplus-development` page.
 Once you've successfully installed ``ebtelplusplus``, see the Example Gallery for examples of how to run a simulation.
 
-Why ``ebtelplusplus``?
-----------------------
-
 Citation
 --------
 
-If you use ``ebtelplusplus`` in any published work, please include the following citations:
+If you use ``ebtelplusplus`` in any published work, please include citations to the following papers:
 
 * :cite:t:`klimchuk_highly_2008`
 * :cite:t:`cargill_enthalpy-based_2012`
@@ -76,4 +74,4 @@ The citation for most current version on Zenodo is,
    }
 
 
-.. _Zenodo DOI: https://zenodo.org/records/12675374
+.. _Zenodo DOI: https://zenodo.org/records/12675374

docs/references.bib

@@ -74,3 +74,19 @@ @book{press_numerical_1992
   publisher = {Cambridge University Press},
   address = {Cambridge, UK ; New York}
 }
+
+@article{rajhans_flows_2022,
+  title = {Flows in {{Enthalpy-based Thermal Evolution}} of {{Loops}}},
+  author = {Rajhans, Abhishek and Tripathi, Durgesh and Bradshaw, Stephen J. and Kashyap, Vinay L. and Klimchuk, James A.},
+  year = {2022},
+  month = jan,
+  journal = {The Astrophysical Journal},
+  volume = {924},
+  number = {1},
+  pages = {13},
+  publisher = {American Astronomical Society},
+  issn = {0004-637X},
+  doi = {10.3847/1538-4357/ac3009},
+  urldate = {2022-02-03},
+  langid = {english}
+}

pyproject.toml

@@ -67,6 +67,7 @@ docs = [
   "sphinxcontrib-bibtex",
   "pydata-sphinx-theme",
   "sphinx-design",
+  "sphinx-copybutton",
   "sphinx-gallery",
   "matplotlib",
 ]