From f81716967ece1f0945e98be80fb86f25b3c15781 Mon Sep 17 00:00:00 2001 From: Will Barnes Date: Tue, 27 Aug 2024 17:56:12 -0400 Subject: [PATCH] add separate page on software comparison --- MANIFEST.in | 5 +-- docs/comparison.rst | 93 ++++++++++++++++++++++++++++++++++++++++++++ docs/conf.py | 4 ++ docs/development.rst | 35 ++++++++++++----- docs/index.rst | 22 +++++------ docs/references.bib | 16 ++++++++ pyproject.toml | 1 + 7 files changed, 150 insertions(+), 26 deletions(-) create mode 100644 docs/comparison.rst diff --git a/MANIFEST.in b/MANIFEST.in index 1ca1343..d40abc6 100644 --- a/MANIFEST.in +++ b/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 diff --git a/docs/comparison.rst b/docs/comparison.rst new file mode 100644 index 0000000..6cbff79 --- /dev/null +++ b/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 diff --git a/docs/conf.py b/docs/conf.py index 38ee497..2632d82 100644 --- a/docs/conf.py +++ b/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" diff --git a/docs/development.rst b/docs/development.rst index b7b6f36..e71dac7 100644 --- a/docs/development.rst +++ b/docs/development.rst @@ -14,33 +14,48 @@ Next, clone your fork, .. code:: shell - $ git clone https://github.com//ebtelPlusPlus.git + git clone https://github.com//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 `__ 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 `__ -* ``brew install boost`` with `Homebrew `__ -* ``sudo port install boost`` with `Macports `__ -* ``sudo apt-get install libboost-all-dev`` on Debian Linux -* `from source `__ +.. list-table:: + :header-rows: 1 + + * - Source + - OS + - Command + * - `conda-forge `__ + - any + - ``conda install -c conda-forge libboost-devel`` + * - `Homebrew `__ + - macOS + - ``brew install boost`` + * - `Macports `__ + - macOS + - ``sudo port install boost`` + * - `Chocolatey `__ + - 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 `__ and `scikit-build-core `__) and install the ``ebtelplusplus``, including all of the dependencies for testing and developing the package. +This will compile the C++ code (using `pybind11 `__ and +`scikit-build-core `__) 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++. diff --git a/docs/index.rst b/docs/index.rst index ed01fa7..d63ea38 100644 --- a/docs/index.rst +++ b/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 `__. - +``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 `__. + 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 \ No newline at end of file +.. _Zenodo DOI: https://zenodo.org/records/12675374 diff --git a/docs/references.bib b/docs/references.bib index 7e06cb1..133329f 100644 --- a/docs/references.bib +++ b/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} +} diff --git a/pyproject.toml b/pyproject.toml index 610c345..f33ec2f 100644 --- a/pyproject.toml +++ b/pyproject.toml @@ -67,6 +67,7 @@ docs = [ "sphinxcontrib-bibtex", "pydata-sphinx-theme", "sphinx-design", + "sphinx-copybutton", "sphinx-gallery", "matplotlib", ]