Minor updates (#120)

wtbarnes · web-flow · commit ec699ea0010f · 2025-03-18T10:04:16.000-04:00
* pypi badge

* enable nitpicky

* refactor high-level and heating event interfaces

* add cron workflow
diff --git a/.github/workflows/scheduled_builds.yml b/.github/workflows/scheduled_builds.yml
@@ -0,0 +1,20 @@
+name: Scheduled builds
+
+on:
+  # Allow manual runs through the web UI
+  workflow_dispatch:
+  schedule:
+    #        ┌───────── minute (0 - 59)
+    #        │ ┌───────── hour (0 - 23)
+    #        │ │  ┌───────── day of the month (1 - 31)
+    #        │ │  │ ┌───────── month (1 - 12 or JAN-DEC)
+    #        │ │  │ │ ┌───────── day of the week (0 - 6 or SUN-SAT)
+    - cron: '0 12 * * 1'  # Every Mon at 12:00 UTC
+
+jobs:
+  dispatch_workflows:
+    runs-on: ubuntu-latest
+    steps:
+      - run: gh workflow run ci.yml --repo rice-solar-physics/ebtelplusplus --ref main
+    env:
+      GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
diff --git a/README.md b/README.md
@@ -4,6 +4,7 @@
 [![Documentation Status](https://readthedocs.org/projects/ebtelplusplus/badge/?version=latest)](https://ebtelplusplus.readthedocs.io/en/latest/?badge=latest)
 [![codecov](https://codecov.io/gh/rice-solar-physics/ebtelplusplus/branch/main/graph/badge.svg?token=8G5H9T5AAH)](https://codecov.io/gh/rice-solar-physics/ebtelplusplus)
 [![DOI](https://zenodo.org/badge/DOI/10.5281/zenodo.12675386.svg)](https://doi.org/10.5281/zenodo.12675386)
+[![PyPI](https://img.shields.io/pypi/v/ebtelplusplus.svg)](https://pypi.org/project/ebtelplusplus)
 
 `ebtelplusplus` is an implementation of the enthalpy-based thermal evolution of loops (EBTEL) model for doing
 efficient hydrodynamics of dynamically-heated solar coronal loops.
@@ -37,7 +38,7 @@ heating = HeatingModel(
     partition=1,
     events=[TriangularHeatingEvent(0*u.s, 200*u.s, 0.1*u.Unit('erg cm-3 s-1'))]
 )
-results = ebtelplusplus.run(2*u.h, 40*u.Mm, heating)
+results = ebtelplusplus.run(2*u.h, 40*u.Mm, heating=heating)
 ```
 
 ## Citation
diff --git a/docs/conf.py b/docs/conf.py
@@ -70,6 +70,17 @@
 # Treat everything in single ` as a Python reference.
 default_role = 'py:obj'
 
+# Enable nitpicky mode, which forces links to be non-broken
+nitpicky = True
+# This is not used. See docs/nitpick-exceptions file for the actual listing.
+nitpick_ignore = []
+for line in open('nitpick-exceptions'):
+    if line.strip() == "" or line.startswith("#"):
+        continue
+    dtype, target = line.split(None, 1)
+    target = target.strip()
+    nitpick_ignore.append((dtype, target))
+
 # -- Options for intersphinx extension ---------------------------------------
 
 # Example configuration for intersphinx: refer to the Python standard library.
diff --git a/docs/index.rst b/docs/index.rst
@@ -40,7 +40,7 @@ ebtelplusplus
 
         :material-outlined:`code;8em;sd-text-secondary`
 
-        Instructions for how to contribute to `ebtelplusplus`
+        Instructions for how to contribute to ``ebtelplusplus``
 
     .. grid-item-card:: Reference
         :link: ebtelplusplus-reference
diff --git a/docs/nitpick-exceptions b/docs/nitpick-exceptions
@@ -0,0 +1,23 @@
+# Prevents sphinx nitpicky mode picking up on optional
+# (see https://github.com/sphinx-doc/sphinx/issues/6861)
+# Even if it was "fixed", still broken
+py:class optional
+# See https://github.com/numpy/numpy/issues/10039
+py:obj numpy.datetime64
+# There's no specific file or function classes to link to
+py:class any type
+py:class array-like
+py:class file object
+py:class function
+py:class path-like
+py:class str-like
+py:class time-like
+py:obj function
+py:obj iterable
+# Units
+py:class Unit
+py:class Unit('1 / cm3')
+py:class Unit('erg')
+py:class Unit('Angstrom')
+py:class Unit('1 / cm5')
+py:class Unit('K')
diff --git a/docs/topic_guides/derivation.rst b/docs/topic_guides/derivation.rst
@@ -4,7 +4,7 @@ Deriving the EBTEL Equations
 ============================
 
 This page will briefly summarize the derivation of the version of the EBTEL
-model used in `ebtelplusplus` which includes cross-sectional area expansion
+model used in ``ebtelplusplus`` which includes cross-sectional area expansion
 and two-fluid effects.
 For a more detailed explanation of the EBTEL model, including the physical
 motivation behind the assumptions, see :cite:t:`klimchuk_highly_2008`.
diff --git a/ebtelplusplus/high_level.py b/ebtelplusplus/high_level.py
@@ -15,7 +15,7 @@
 
 
 @u.quantity_input
-def run(total_time: u.s, loop_length: u.cm, heating=None, physics=None, solver=None, dem=None):
+def run(total_time: u.s, loop_length: u.cm, *, heating=None, physics=None, solver=None, dem=None):
     """
     Run an ebtelplusplus simulation
 
diff --git a/ebtelplusplus/models.py b/ebtelplusplus/models.py
@@ -171,14 +171,14 @@ class HeatingEvent:
 
     Parameters
     ----------
-    rise_start: `~astropy.units.Quantity`
+    start: `~astropy.units.Quantity`
         Time at which the heating event starts
-    rise_end: `~astropy.units.Quantity`
-        Time at which the rise phase stops (and the constant phase starts)
-    decay_start: `~astropy.units.Quantity`
-        Time at which the decay phase starts (and the constant phase stops)
+    duration: `~astropy.units.Quantity`
+        Total duration of the heating event
+    duration_rise: `~astropy.units.Quantity`
+        Duration of the linear rise phase of the event
     decay_end: `~astropy.units.Quantity`
-        Time at which the decay phase and the event ends
+        Duration of the linear decay phase of the event
     rate: `~astropy.units.Quantity`
         The maximum heating rate of the event
 
@@ -189,11 +189,12 @@ class HeatingEvent:
     """
 
     @u.quantity_input
-    def __init__(self, rise_start: u.s, rise_end: u.s, decay_start: u.s, decay_end: u.s, rate: u.Unit('erg cm-3 s-1')):
-        self.rise_start = rise_start
-        self.rise_end = rise_end
-        self.decay_start = decay_start
-        self.decay_end = decay_end
+    def __init__(self, start: u.s, duration: u.s, duration_rise: u.s, duration_decay: u.s, rate: u.Unit('erg cm-3 s-1')):
+        self.rise_start = start
+        self.rise_end = self.rise_start + duration_rise
+        duration_constant = duration - duration_rise - duration_decay
+        self.decay_start = self.rise_end + duration_constant
+        self.decay_end = self.decay_start + duration_decay
         self.rate = rate
 
     def to_dict(self):
@@ -213,20 +214,20 @@ class TriangularHeatingEvent(HeatingEvent):
 
     Parameters
     ----------
-    rise_start: `~astropy.units.Quantity`
+    start: `~astropy.units.Quantity`
         Time at which the heating event starts
     duration: `~astropy.units.Quantity`
         Total duration of the event
     rate: `~astropy.units.Quantity`
         The maximum heating rate of the event
     """
 
-    def __init__(self, rise_start, duration, rate):
+    def __init__(self, start, duration, rate):
         super().__init__(
-            rise_start,
-            rise_start+duration/2,
-            rise_start+duration/2,
-            rise_start+duration,
+            start,
+            duration,
+            duration/2,
+            duration/2,
             rate,
         )
 
@@ -237,20 +238,20 @@ class SquareHeatingEvent(HeatingEvent):
 
     Parameters
     ----------
-    rise_start: `~astropy.units.Quantity`
+    start: `~astropy.units.Quantity`
         Time at which the heating event starts
     duration: `~astropy.units.Quantity`
         Total duration of the event
     rate: `~astropy.units.Quantity`
         The maximum heating rate of the event
     """
 
-    def __init__(self, rise_start, duration, rate):
+    def __init__(self, start, duration, rate):
         super().__init__(
-            rise_start,
-            rise_start,
-            rise_start+duration,
-            rise_start+duration,
+            start,
+            duration,
+            0*u.s,
+            0*u.s,
             rate,
         )
 
diff --git a/ebtelplusplus/tests/test_compare_hydrad.py b/ebtelplusplus/tests/test_compare_hydrad.py
@@ -47,7 +47,7 @@ def test_compare_hydrad_single_event_peak_values(tau, heating_type, solver_model
                                  force_single_fluid=force_single_fluid)
     r_ebtel = ebtelplusplus.run(5e3*u.s,
                                 40*u.Mm,
-                                heating_model,
+                                heating=heating_model,
                                 physics=physics_model,
                                 solver=solver_model,)
     r_hydrad = read_hydrad_test_data(tau.to_value('s'), heating_type)
diff --git a/ebtelplusplus/tests/test_compare_idl.py b/ebtelplusplus/tests/test_compare_idl.py
@@ -53,7 +53,7 @@ def test_compare_idl_single_event(physics_model,
     loop_length = 40 * u.Mm
     r_cpp = ebtelplusplus.run(total_time,
                               loop_length,
-                              heating_model,
+                              heating=heating_model,
                               physics=physics_model,
                               solver=solver_model)
 
@@ -89,7 +89,7 @@ def test_compare_idl_area_expansion(
     loop_length = 40 * u.Mm
     r_cpp = ebtelplusplus.run(total_time,
                               loop_length,
-                              heating_model,
+                              heating=heating_model,
                               physics=physics_model,
                               solver=solver_model)
     r_idl = read_idl_test_data(f'idl_area_expansion_{A_c=}_{A_0=}_{A_tr=}.txt', ebtel_idl_path, r_cpp.inputs)
diff --git a/ebtelplusplus/tests/test_rad_loss.py b/ebtelplusplus/tests/test_rad_loss.py
@@ -17,7 +17,7 @@ def test_rad_loss_options(radiation):
         background=1e-6*u.Unit('erg cm-3 s-1'),
         events=[TriangularHeatingEvent(0.0*u.s, 200*u.s, 0.1*u.Unit('erg cm-3 s-1'))]
     )
-    results = ebtelplusplus.run(5e3*u.s, 40*u.Mm, heating, physics=physics)
+    results = ebtelplusplus.run(5e3*u.s, 40*u.Mm, heating=heating, physics=physics)
     quantities = [
         'electron_temperature',
         'ion_temperature',
diff --git a/ebtelplusplus/tests/test_single_fluid.py b/ebtelplusplus/tests/test_single_fluid.py
@@ -17,13 +17,13 @@ def physics_model():
 
 
 @pytest.mark.parametrize('event', [
-    HeatingEvent(0*u.s, 250*u.s, 1000*u.s, 2000*u.s, 0.005*u.Unit('erg cm-3 s-1')),  # gentle case
-    HeatingEvent(0*u.s, 100*u.s, 100*u.s, 200*u.s, 0.1*u.Unit('erg cm-3 s-1')),  # more impulsive case
+    HeatingEvent(0*u.s, 2000*u.s, 250*u.s, 1000*u.s, 0.005*u.Unit('erg cm-3 s-1')),  # gentle case
+    HeatingEvent(0*u.s, 200*u.s, 100*u.s, 100*u.s,  0.1*u.Unit('erg cm-3 s-1')),  # more impulsive case
 ])
 def test_single_fluid_gentle(physics_model, event):
     heating = HeatingModel(background=1e-6*u.Unit('erg cm-3 s-1'),
                            partition=0.5,
                            events=[event])
-    results = ebtelplusplus.run(5e3*u.s, 40*u.Mm, heating, physics=physics_model)
+    results = ebtelplusplus.run(5e3*u.s, 40*u.Mm, heating=heating, physics=physics_model)
     assert u.allclose(results.electron_temperature, results.ion_temperature, rtol=1e-10)
     assert u.allclose(results.electron_pressure, results.ion_pressure, rtol=1e-10)
diff --git a/ebtelplusplus/tests/test_solver.py b/ebtelplusplus/tests/test_solver.py
@@ -41,7 +41,7 @@ def heating_model():
     return HeatingModel(
         background=1e-6*u.Unit('erg cm-3 s-1'),
         partition=1.0,
-        events=[TriangularHeatingEvent(rise_start=0.0*u.s,
+        events=[TriangularHeatingEvent(start=0.0*u.s,
                                        duration=200*u.s,
                                        rate=0.1*u.Unit('erg cm-3 s-1'))]
     )
@@ -51,7 +51,7 @@ def heating_model():
 def adaptive_results(physics_model, adaptive_solver, heating_model):
     return ebtelplusplus.run(5e3*u.s,
                              40*u.Mm,
-                             heating_model,
+                             heating=heating_model,
                              physics=physics_model,
                              solver=adaptive_solver)
 
@@ -60,7 +60,7 @@ def adaptive_results(physics_model, adaptive_solver, heating_model):
 def static_results(physics_model, static_solver, heating_model):
     return ebtelplusplus.run(5e3*u.s,
                              40*u.Mm,
-                             heating_model,
+                             heating=heating_model,
                              physics=physics_model,
                              solver=static_solver)
 
@@ -92,7 +92,7 @@ def test_quantities_equal_adaptive_static(adaptive_results, static_results, name
 ])
 def test_insufficient_heating(bad_heating, static_solver,):
     with pytest.raises(RuntimeError):
-        _ = ebtelplusplus.run(5e3*u.s, 40*u.Mm, bad_heating, solver=static_solver)
+        _ = ebtelplusplus.run(5e3*u.s, 40*u.Mm, heating=bad_heating, solver=static_solver)
 
 
 @pytest.mark.parametrize('use_adaptive_solver', [True, False])
@@ -104,7 +104,7 @@ def test_NaNs_in_solver(use_adaptive_solver):
         events=[TriangularHeatingEvent(0.0*u.s, 200*u.s, -10*u.Unit('erg cm-3 s-1'))]
     )
     with pytest.raises(RuntimeError):
-        _ = ebtelplusplus.run(5e3*u.s, 40*u.Mm, heating, solver=solver)
+        _ = ebtelplusplus.run(5e3*u.s, 40*u.Mm, heating=heating, solver=solver)
 
 
 @pytest.mark.parametrize(('A_c', 'A_0', 'A_tr'), [
@@ -123,7 +123,7 @@ def test_area_expansion(A_c, A_0, A_tr, adaptive_solver, heating_model):
     )
     results = ebtelplusplus.run(5e3*u.s,
                                 40*u.Mm,
-                                heating_model,
+                                heating=heating_model,
                                 physics=physics,
                                 solver=adaptive_solver)
     vars = [
diff --git a/examples/area_expansion.py b/examples/area_expansion.py
@@ -16,7 +16,7 @@
 quantity_support()
 
 ##############################################################################
-# In `ebtelplusplus`, cross-sectional area expansion is defined through two ratios:
+# In ``ebtelplusplus``, cross-sectional area expansion is defined through two ratios:
 # the ratio between the cross-sectional area averaged over the transition
 # region (TR) to the cross-sectional area averaged over the corona
 # (:math:`A_{TR}/A_C`) and the ratio between the cross-sectional area at the
@@ -59,9 +59,9 @@
 
 loop_length = 45 * u.Mm
 total_time = 5500 * u.s
-r_no_expansion = ebtelplusplus.run(total_time, loop_length, heating, physics=no_expansion)
-r_gradual_expansion = ebtelplusplus.run(total_time, loop_length, heating, physics=gradual_expansion)
-r_coronal_expansion = ebtelplusplus.run(total_time, loop_length, heating, physics=coronal_expansion)
+r_no_expansion = ebtelplusplus.run(total_time, loop_length, heating=heating, physics=no_expansion)
+r_gradual_expansion = ebtelplusplus.run(total_time, loop_length, heating=heating, physics=gradual_expansion)
+r_coronal_expansion = ebtelplusplus.run(total_time, loop_length, heating=heating, physics=coronal_expansion)
 
 ##############################################################################
 # Finally, let's visualize our results in the manner of Figure 7 of
diff --git a/examples/electron_single_event.py b/examples/electron_single_event.py
@@ -39,7 +39,7 @@
 # want to compute the DEM
 result = ebtelplusplus.run(5e3*u.s,
                            40*u.Mm,
-                           heating,
+                           heating=heating,
                            dem=DemModel(calculate_dem=True))
 
 ##################################################
diff --git a/examples/ion_multi_event.py b/examples/ion_multi_event.py
@@ -45,7 +45,7 @@
 # want to compute the DEM
 result = ebtelplusplus.run(3*u.h,
                            40*u.Mm,
-                           heating,
+                           heating=heating,
                            dem=DemModel(calculate_dem=True))
 
 ##################################################
diff --git a/examples/single_trapezoid_event.py b/examples/single_trapezoid_event.py
@@ -24,9 +24,9 @@
 # and then decays linearly to the background rate
 # over the course of 1000 s.
 event = HeatingEvent(0*u.s,
+                     2000*u.s,
                      250*u.s,
                      1000*u.s,
-                     2000*u.s,
                      0.005*u.Unit('erg cm-3 s-1'))
 
 ##################################################
@@ -47,7 +47,7 @@
 # want to compute the DEM
 result = ebtelplusplus.run(5e3*u.s,
                            40*u.Mm,
-                           heating,
+                           heating=heating,
                            physics=physics,
                            dem=DemModel(calculate_dem=True))
 
