isotopes: add tau(Bo, dm_dt_over_m) formulae to Trivia (where Bo is the "Bolin number") (#1669)

Co-authored-by: Sylwester Arabas <[email protected]>

Author: AgnieszkaZaba

PySDM/physics/isotope_relaxation_timescale/__init__.py

@@ -5,5 +5,5 @@
 from PySDM.impl.null_physics_class import Null
 from .miyake_et_al_1968 import MiyakeEtAl1968
 from .bolin_1958 import Bolin1958
-from .zaba_et_al import ZabaEtAl
 from .jouzel_et_al_1975 import JouzelEtAl1975
+from .zaba_et_al import ZabaEtAl

PySDM/physics/isotope_relaxation_timescale/bolin_1958.py

@@ -1,5 +1,4 @@
-"""Timescale derived for tritium with assumption of zero ambient concentration - see text above
-Table 1 [Bolin 1958](https://digitallibrary.un.org/record/3892725)"""
+"""Bolin number"""
 
 import numpy as np
 
@@ -11,5 +10,5 @@ def __init__(self, const):
         assert np.isfinite(const.BOLIN_ISOTOPE_TIMESCALE_COEFF_C1)
 
     @staticmethod
-    def tau(const, dm_dt_over_m):
-        return 1 / (const.BOLIN_ISOTOPE_TIMESCALE_COEFF_C1 * dm_dt_over_m)
+    def bolin_number(const):
+        return const.BOLIN_ISOTOPE_TIMESCALE_COEFF_C1

PySDM/physics/trivia.py

@@ -161,3 +161,10 @@ def poissonian_avoidance_function(r, dt):
         process with a constant rate `r`
         """
         return np.exp(-r * dt)
+
+    @staticmethod
+    def tau(Bo, dm_dt_over_m):
+        """
+        see text above Table 1 [Bolin 1958](https://digitallibrary.un.org/record/3892725)
+        """
+        return 1 / Bo / dm_dt_over_m

docs/bibliography.json

@@ -682,10 +682,10 @@
   },
   "https://digitallibrary.un.org/record/3892725": {
     "usages": [
-      "PySDM/physics/isotope_relaxation_timescale/bolin_1958.py",
       "PySDM/physics/constants_defaults.py",
-      "examples/PySDM_examples/Bolin_1958/table_1.ipynb",
+      "PySDM/physics/trivia.py",
       "examples/PySDM_examples/Bolin_1958/__init__.py",
+      "examples/PySDM_examples/Bolin_1958/table_1.ipynb",
       "examples/PySDM_examples/Zaba_et_al/timescales_comparison.ipynb"
     ],
     "label": "Bolin 1958 (Proc. 2nd UN Intl Conf. Peaceful Uses of Atomic Energy)",

examples/PySDM_examples/Bolin_1958/table_1.ipynb

@@ -23,8 +23,8 @@
    "id": "5e4e58050cc01f64",
    "metadata": {
     "ExecuteTime": {
-     "end_time": "2025-06-27T18:55:07.411745Z",
-     "start_time": "2025-06-27T18:55:07.401377Z"
+     "end_time": "2025-08-12T13:56:32.855405Z",
+     "start_time": "2025-08-12T13:56:32.851730Z"
     }
    },
    "source": [
@@ -35,15 +35,15 @@
     "    pip_install_on_colab('PySDM-examples')"
    ],
    "outputs": [],
-   "execution_count": 5
+   "execution_count": 1
   },
   {
    "cell_type": "code",
    "id": "95f360dc62f373f9",
    "metadata": {
     "ExecuteTime": {
-     "end_time": "2025-06-27T18:55:08.148769Z",
-     "start_time": "2025-06-27T18:55:08.144342Z"
+     "end_time": "2025-08-12T13:56:35.553021Z",
+     "start_time": "2025-08-12T13:56:32.868658Z"
     }
    },
    "source": [
@@ -54,13 +54,13 @@
     "from IPython.display import display"
    ],
    "outputs": [],
-   "execution_count": 6
+   "execution_count": 2
   },
   {
    "metadata": {
     "ExecuteTime": {
-     "end_time": "2025-06-27T18:55:08.549521Z",
-     "start_time": "2025-06-27T18:55:08.517457Z"
+     "end_time": "2025-08-12T13:56:38.312522Z",
+     "start_time": "2025-08-12T13:56:35.612041Z"
     }
    },
    "cell_type": "code",
@@ -110,15 +110,15 @@
    ],
    "id": "4a8c2bd612c892f2",
    "outputs": [],
-   "execution_count": 7
+   "execution_count": 3
   },
   {
    "cell_type": "code",
    "id": "340812de267c4290",
    "metadata": {
     "ExecuteTime": {
-     "end_time": "2025-06-27T19:04:24.139475Z",
-     "start_time": "2025-06-27T19:04:24.120075Z"
+     "end_time": "2025-08-12T13:56:38.762219Z",
+     "start_time": "2025-08-12T13:56:38.345299Z"
     }
    },
    "source": [
@@ -141,7 +141,8 @@
     "    Fk=Fk,\n",
     "    Fd=Fd,\n",
     ")\n",
-    "adjustment_time = formulae.isotope_relaxation_timescale.tau(\n",
+    "adjustment_time = formulae.trivia.tau(\n",
+    "    Bo=formulae.isotope_relaxation_timescale.bolin_number(),\n",
     "    dm_dt_over_m=(\n",
     "        formulae.particle_shape_and_density.dm_dt_over_m(\n",
     "            radii,\n",
@@ -265,15 +266,15 @@
      "output_type": "display_data"
     }
    ],
-   "execution_count": 14
+   "execution_count": 4
   },
   {
    "cell_type": "code",
    "id": "0bef57bc-7e19-4a3f-8f77-6ec762e8f236",
    "metadata": {
     "ExecuteTime": {
-     "end_time": "2025-06-27T18:41:40.340143Z",
-     "start_time": "2025-06-03T21:24:22.478342Z"
+     "end_time": "2025-08-12T13:56:38.799723Z",
+     "start_time": "2025-08-12T13:56:38.798348Z"
     }
    },
    "source": [],

tests/unit_tests/physics/test_isotope_relaxation_timescale.py

@@ -58,18 +58,15 @@ def test_unit_and_magnitude(paper, iso):
         assert 0 * si.s < result.to_base_units() < 10 * si.s
 
 
-def test_bolin_tritium_formula_unit():
+def test_bolin_number_unit():
     with DimensionalAnalysis():
         # arrange
         si = constants_defaults.si
-        formulae = Formulae(
-            isotope_relaxation_timescale="Bolin1958",
-            constants={"BOLIN_ISOTOPE_TIMESCALE_COEFF_C1": 1 * si.dimensionless},
-        )
-        tau = formulae.isotope_relaxation_timescale.tau
+        sut = isotope_relaxation_timescale.bolin_1958.Bolin1958.bolin_number
+        formulae = Formulae()
 
         # act
-        sut = tau(dm_dt_over_m=1 / si.s)
+        value = sut(formulae.constants)
 
         # assert
-        assert sut.check("[time]")
+        assert value.check(si.dimensionless)

tests/unit_tests/physics/test_trivia.py

@@ -3,7 +3,7 @@
 import pytest
 from scipy.special import erfinv  # pylint: disable=no-name-in-module
 
-from PySDM import Formulae
+from PySDM import Formulae, physics
 from PySDM.physics.dimensional_analysis import DimensionalAnalysis
 from PySDM.physics import constants_defaults
 
@@ -113,3 +113,18 @@ def test_celsius_to_kelvin():
 
         # assert
         assert temperature_in_kelvin == temperature_in_celsius + 273.15
+
+    @staticmethod
+    @pytest.mark.parametrize(
+        "bolin_number, dm_dt_over_m, expected_tau",
+        ((1, 2, 0.5), (2, 1, 0.5), (2, 2, 0.25)),
+    )
+    def test_tau(bolin_number, dm_dt_over_m, expected_tau):
+        # arrange
+        sut = physics.trivia.Trivia.tau
+
+        # act
+        value = sut(Bo=bolin_number, dm_dt_over_m=dm_dt_over_m)
+
+        # assert
+        np.testing.assert_almost_equal(actual=value, desired=expected_tau)