Hysteresis-Based Conversion (DC/CD Thresholds) - Fixed User API

This fixed the version V0.4.0 by simply updating the USERAPI to now work with two thresholds (and integrate with the integrated-srcm-ssa package).

Hysteresis-Based Conversion (DC/CD Thresholds)

🏷️ Release Title

Hysteresis-Based Conversion (DC/CD Thresholds)

---

📝 Release Description

This release introduces a major improvement to the SRCM Engine conversion mechanism by replacing the single-threshold switching rule with a two-threshold hysteresis model.

🚀 Key Changes

🔁 Hysteresis-Based Regime Conversion

• Introduced:

  • DC_threshold — controls discrete → continuous conversion
  • CD_threshold — controls continuous → discrete conversion

• Eliminates rapid oscillations between regimes near threshold boundaries

• Provides more stable and physically realistic hybrid behaviour

---

⚙️ Updated Conversion API

• ConversionParams now requires:

  ConversionParams(
      DC_threshold=...,
      CD_threshold=...,
      rate=...,
  )

---

🧠 Improved Numerical Stability

• Reduced regime "chattering" in low-density regions
• More robust behaviour in spatially heterogeneous systems
• Better suitability for pattern formation and ecological models

---

🧪 Test Suite Updated

• All tests updated to reflect new conversion logic

• Added coverage for:

  • DC/CD masks
  • hysteresis deadband behaviour
  • propensity correctness

---

📚 Documentation Updated

• README updated to reflect new conversion model
• Examples now use DC_threshold and CD_threshold
• Clarified behaviour and motivation for hysteresis

---

⚠️ Breaking Changes

• Removed:

  ConversionParams(threshold=...)

• All code must now use:

  DC_threshold and CD_threshold

---

💡 Why This Matters

The introduction of hysteresis significantly improves the stability of hybrid simulations by preventing frequent switching between discrete and continuous regimes when particle numbers fluctuate near a boundary.

This brings SRCM Engine closer to both:

• physical realism
• numerical robustness

EXPERIMENTAL: Adding probabalistic mass conversion to the PDE, no longer a hard boolean.

Updated Continuous → Discrete (CD) Conversion Logic

The CD conversion logic in apply_event has been revised to relax the previous strict admissibility condition that prevented conversion when any PDE grid point in a compartment had concentration below $1/h$.

Previously, conversion required all fine-grid PDE cells within a compartment to satisfy

$$ u_i(t) \geq \frac{1}{h} $$

in order to safely remove one particle of mass uniformly across the compartment. This restriction was enforced through the sufficient_pde_concentration_mask.

New behaviour

Conversion events are now allowed whenever the stochastic event fires. The removal of PDE mass is handled dynamically inside apply_event.

Let

$$ Y_k(t) = \sum_{i=Pk}^{P(k+1)-1} u_i(t),dx $$

denote the integrated PDE mass in compartment $k$.

Two cases are considered:

---

1. Sub–unit mass: $Y_k(t) < 1$

If the compartment contains less than one particle of mass:

• All PDE mass in the compartment is cleared:

$$ u_i(t+\tau) = 0 $$

• A discrete particle is added probabilistically:

$$ X_k(t+\tau) = X_k(t) + 1 \quad \text{with probability } Y_k(t) $$

Otherwise no discrete particle is added.

---

2. At least one particle: $Y_k(t) \geq 1$

If the compartment contains at least one particle of mass:

Uniform removal attempt

If

$$ u_i(t) \geq \frac{1}{h} \quad \forall i $$

then one particle is removed uniformly from the PDE profile:

$$ u_i(t+\tau) = u_i(t) - \frac{1}{h} $$

and

$$ X_k(t+\tau) = X_k(t) + 1 $$

---

Redistribution removal

If uniform removal would make some cells negative, the algorithm removes one particle of mass using an equal redistribution scheme:

1. Cells that cannot support an equal mass share are set to zero.
2. The remaining mass to be removed is redistributed equally across the remaining active cells.
3. This process repeats until exactly one particle of mass has been removed.

This guarantees:

• exactly one unit of mass removed
• no negative PDE concentrations
• symmetric redistribution across the remaining PDE cells

---

Result

This update removes the need for the sufficient_pde_concentration_mask gating condition while preserving physical constraints on the PDE profile. Conversion events can now occur more naturally even when the fine-grid concentration profile is heterogeneous.

Allowed individual trajectory to be run and saved

v0.2.4

Updated version number

Allow python 3.11 to be used

v0.2.3

Allow python 3.11

Updated pyproject

This has an updated pyproject, correctly naming the version. I hope to use this release as the newest release in the integrated-srcm package.

Second stable release

This adds in as many thresholds as there are species, so we can have two thresholds for two species.

v0.1.0 – First stable SRCM engine release

First stable release of the SRCM engine.

• Known-good engine baseline
• Used by integrated-srcm-ssa
• Safe to pin as a dependency
• Development continues on stable_1