[MRG]: feat: KD add remaining extracted non-model code (#1188)

* feat: KD add remaining extracted non-model code

I believe this adds the last of the code that is extracted from #1168
that is *not* the actual Duecker model itself, but instead code changes
that are used by the default model. These functions are not currently
tested at all, and I have not added tests for them for similar reasons
to
#1185 (comment)

After this, we should be able to make a PR that adds the actual Duecker
model itself. However, there will be additional work for that step: we
need to update `hnn_io.read_network_configuration` and the equivalent
`...write...` such that they support the Duecker model.

Continuing the pattern, this is based on top of #1187.

* maint: apply suggested renames

* ref: rename zero_val

* test: conductance-distance func tests

These tests were written by Claude-AI. Perfect use case for AI to fill
in boring boilerplate.

---------

Co-authored-by: katduecker <katharina.duecker@gmail.com>

Author: asoplata

hnn_core/cells_default.py

@@ -192,7 +192,7 @@ def _cell_L5Pyr(override_params, pos=(0.0, 0.0, 0), gid=0.0):
 
         if sec_name != "soma":
             sections[sec_name].mechs["ar"]["gbar_ar"] = partial(
-                _exp_g_at_dist, zero_val=1e-6, exp_term=3e-3, offset=0.0
+                _exp_g_at_dist, gbar_at_zero=1e-6, exp_term=3e-3, offset=0.0
             )
 
     cell_tree = {
@@ -303,23 +303,24 @@ def _get_mechanisms(p_all, cell_type, section_names, mechanisms):
     return mech_props
 
 
-def _exp_g_at_dist(x, zero_val, exp_term, offset):
+def _exp_g_at_dist(x, gbar_at_zero, exp_term, offset, slope=1):
     """Compute exponential distance-dependent ionic conductance.
 
     Parameters
     ----------
     x : float | int
         Distance from soma
-    zero_val : float | int
+    gbar_at_zero : float | int
         Value of function when x = 0
     exp_term : float | int
         Multiplier of x in the exponent
-    offset: float |int
+    offset : float | int
         Offset value added to output
-
+    slope : int | float, default=1
+        Slope of the exponential component
     """
-
-    return zero_val * np.exp(exp_term * x) + offset
+    gbar = gbar_at_zero * (slope * np.exp(exp_term * x) + offset)
+    return gbar
 
 
 def basket(cell_name, pos=(0, 0, 0), gid=None):
@@ -390,7 +391,9 @@ def pyramidal(cell_name, pos=(0, 0, 0), override_params=None, gid=None):
         raise ValueError(f"Unknown pyramidal cell type: {cell_name}")
 
 
-def _linear_g_at_dist(x, gsoma, gdend, xkink):
+def _linear_g_at_dist(
+    x, gsoma, gdend, xkink, hotzone_factor=1, hotzone_boundaries=[0, 0]
+):
     """Compute linear distance-dependent ionic conductance.
 
     Parameters
@@ -403,13 +406,22 @@ def _linear_g_at_dist(x, gsoma, gdend, xkink):
         Dendritic conductance
     xkink : float | int
         Plateau value where conductance is fixed at gdend.
+    hotzone_factor: int | float, default=1
+        Increase in conducivity that creates a hotzone.
+    hotzone_boundaries : [float, float]
+        Start and end of hotzone if hotzone_factor > 1. Units are the same as that of
+        `x`.
 
     Notes
     -----
     Linearly scales conductance along dendrite.
     Returns gdend when x > xkink.
     """
-    return gsoma + np.min([xkink, x]) * (gdend - gsoma) / xkink
+    gbar = gsoma + np.min([xkink, x]) * (gdend - gsoma) / xkink
+    if hotzone_boundaries[0] < x < hotzone_boundaries[1]:
+        gbar *= hotzone_factor
+
+    return gbar
 
 
 def pyramidal_ca(cell_name, pos, override_params=None, gid=None):
@@ -430,7 +442,7 @@ def pyramidal_ca(cell_name, pos, override_params=None, gid=None):
     )
     gbar_k = partial(
         _exp_g_at_dist,
-        zero_val=override_params["L5Pyr_soma_gkbar_hh2"],
+        gbar_at_zero=override_params["L5Pyr_soma_gkbar_hh2"],
         exp_term=-0.006,
         offset=1e-4,
     )

hnn_core/gui/gui.py

@@ -2915,7 +2915,7 @@ def _update_L5_biophysics_cell_params(net, cell_param_key, param_list):
     mechs_params["cat"] = {"gbar_cat": param_list[18].value}
     mechs_params["ar"] = {
         "gbar_ar": partial(
-            _exp_g_at_dist, zero_val=param_list[19].value, exp_term=3e-3, offset=0.0
+            _exp_g_at_dist, gbar_at_zero=param_list[19].value, exp_term=3e-3, offset=0.0
         )
     }
 

hnn_core/tests/test_cells_default.py

@@ -3,7 +3,7 @@
 from neuron import h
 import numpy as np
 
-from hnn_core.cells_default import pyramidal, basket
+from hnn_core.cells_default import pyramidal, basket, _exp_g_at_dist, _linear_g_at_dist
 from hnn_core.network_builder import load_custom_mechanisms
 
 
@@ -84,3 +84,157 @@ def test_cells_default():
 
     with pytest.raises(ValueError, match="Unknown basket cell type"):
         basket(cell_name="blah")
+
+
+def test_exp_g_at_dist():
+    """Test exponential distance-dependent conductance function."""
+    # Test at x=0 with default slope
+    gbar = _exp_g_at_dist(x=0, gbar_at_zero=1e-6, exp_term=3e-3, offset=0.0)
+    expected = 1e-6 * (1 * np.exp(0) + 0.0)  # 1e-6 * 1 = 1e-6
+    assert np.isclose(gbar, expected)
+
+    # Test at x=0 with non-default slope and offset
+    gbar = _exp_g_at_dist(x=0, gbar_at_zero=2e-6, exp_term=3e-3, offset=0.5, slope=2)
+    expected = 2e-6 * (2 * np.exp(0) + 0.5)  # 2e-6 * 2.5 = 5e-6
+    assert np.isclose(gbar, expected)
+
+    # Test at positive distance
+    x = 100
+    gbar = _exp_g_at_dist(x=x, gbar_at_zero=1e-6, exp_term=3e-3, offset=0.0)
+    expected = 1e-6 * (1 * np.exp(3e-3 * x) + 0.0)
+    assert np.isclose(gbar, expected)
+
+    # Test with negative exp_term (decay)
+    x = 100
+    gbar = _exp_g_at_dist(x=x, gbar_at_zero=0.06, exp_term=-0.006, offset=1e-4, slope=1)
+    expected = 0.06 * (1 * np.exp(-0.006 * x) + 1e-4)
+    assert np.isclose(gbar, expected)
+
+    # Test with array input
+    x_array = np.array([0, 50, 100, 200])
+    gbar_array = _exp_g_at_dist(
+        x=x_array, gbar_at_zero=1e-6, exp_term=3e-3, offset=0.0, slope=1
+    )
+    expected_array = 1e-6 * (np.exp(3e-3 * x_array) + 0.0)
+    assert np.allclose(gbar_array, expected_array)
+
+    # Test that function is monotonically increasing with positive exp_term
+    x_values = np.linspace(0, 100, 10)
+    gbar_values = _exp_g_at_dist(
+        x=x_values, gbar_at_zero=1e-6, exp_term=3e-3, offset=0.0, slope=1
+    )
+    assert np.all(np.diff(gbar_values) > 0)
+
+    # Test that function is monotonically decreasing with negative exp_term
+    x_values = np.linspace(0, 100, 10)
+    gbar_values = _exp_g_at_dist(
+        x=x_values, gbar_at_zero=1.0, exp_term=-0.01, offset=0.0, slope=1
+    )
+    assert np.all(np.diff(gbar_values) < 0)
+
+
+def test_linear_g_at_dist():
+    """Test linear distance-dependent conductance function."""
+    # Test at x=0 (should return gsoma)
+    gbar = _linear_g_at_dist(x=0, gsoma=10.0, gdend=40.0, xkink=1501)
+    assert np.isclose(gbar, 10.0)
+
+    # Test at x < xkink (linear interpolation)
+    x = 750  # halfway to xkink
+    gbar = _linear_g_at_dist(x=x, gsoma=10.0, gdend=40.0, xkink=1501)
+    expected = 10.0 + 750 * (40.0 - 10.0) / 1501
+    assert np.isclose(gbar, expected)
+
+    # Test at x = xkink (should return gdend)
+    gbar = _linear_g_at_dist(x=1501, gsoma=10.0, gdend=40.0, xkink=1501)
+    assert np.isclose(gbar, 40.0)
+
+    # Test at x > xkink (should still return gdend)
+    gbar = _linear_g_at_dist(x=2000, gsoma=10.0, gdend=40.0, xkink=1501)
+    assert np.isclose(gbar, 40.0)
+
+    # Test with hotzone (x inside hotzone boundaries)
+    x = 500
+    gbar = _linear_g_at_dist(
+        x=x,
+        gsoma=10.0,
+        gdend=40.0,
+        xkink=1501,
+        hotzone_factor=2.0,
+        hotzone_boundaries=[400, 600],
+    )
+    expected_base = 10.0 + 500 * (40.0 - 10.0) / 1501
+    expected = expected_base * 2.0
+    assert np.isclose(gbar, expected)
+
+    # Test outside hotzone (x before hotzone)
+    x = 300
+    gbar = _linear_g_at_dist(
+        x=x,
+        gsoma=10.0,
+        gdend=40.0,
+        xkink=1501,
+        hotzone_factor=2.0,
+        hotzone_boundaries=[400, 600],
+    )
+    expected = 10.0 + 300 * (40.0 - 10.0) / 1501
+    assert np.isclose(gbar, expected)
+
+    # Test outside hotzone (x after hotzone)
+    x = 700
+    gbar = _linear_g_at_dist(
+        x=x,
+        gsoma=10.0,
+        gdend=40.0,
+        xkink=1501,
+        hotzone_factor=2.0,
+        hotzone_boundaries=[400, 600],
+    )
+    expected = 10.0 + 700 * (40.0 - 10.0) / 1501
+    assert np.isclose(gbar, expected)
+
+    # Test at hotzone boundary (exactly at start, should not apply factor)
+    x = 400
+    gbar = _linear_g_at_dist(
+        x=x,
+        gsoma=10.0,
+        gdend=40.0,
+        xkink=1501,
+        hotzone_factor=2.0,
+        hotzone_boundaries=[400, 600],
+    )
+    expected = 10.0 + 400 * (40.0 - 10.0) / 1501
+    assert np.isclose(gbar, expected)
+
+    # Test at hotzone boundary (exactly at end, should not apply factor)
+    x = 600
+    gbar = _linear_g_at_dist(
+        x=x,
+        gsoma=10.0,
+        gdend=40.0,
+        xkink=1501,
+        hotzone_factor=2.0,
+        hotzone_boundaries=[400, 600],
+    )
+    expected = 10.0 + 600 * (40.0 - 10.0) / 1501
+    assert np.isclose(gbar, expected)
+
+    # Test with hotzone_factor = 1 (no effect)
+    x = 500
+    gbar = _linear_g_at_dist(
+        x=x,
+        gsoma=10.0,
+        gdend=40.0,
+        xkink=1501,
+        hotzone_factor=1.0,
+        hotzone_boundaries=[400, 600],
+    )
+    expected = 10.0 + 500 * (40.0 - 10.0) / 1501
+    assert np.isclose(gbar, expected)
+
+    # Test decreasing conductance (gdend < gsoma)
+    x = 500
+    gbar = _linear_g_at_dist(x=x, gsoma=40.0, gdend=10.0, xkink=1000)
+    expected = 40.0 + 500 * (10.0 - 40.0) / 1000
+    assert np.isclose(gbar, expected)
+    assert gbar < 40.0  # Should be less than gsoma