Issue 4884 unify hysteresis

CHANGELOG.md

@@ -6,18 +6,23 @@
 - Added a `Constant` symbol for named constants. This is a subclass of `Scalar` and is used to represent named constants such as the gas constant. This avoids constants being simplified out when constructing expressions. ([#5070](https://github.com/pybamm-team/PyBaMM/pull/5070))
 - Generalise `pybamm.DiscreteTimeSum` to allow it to be embedded in other expressions ([#5044](https://github.com/pybamm-team/PyBaMM/pull/5044))
 - Adds `all` key-value pair to `output_variables` sensitivity dictionaries, accessible through `solution[var].sensitivities['all']`. Aligns shape with conventional solution sensitivities object. ([#5067](https://github.com/pybamm-team/PyBaMM/pull/5067))
+- Added a new `BaseHysteresisOpenCircuitPotential` class that sets variables for the lithiation and delithiation OCP and the hysteresis voltage (`H = U_lith - U_delith`). Allow the initial hysteresis state to be a function of position through the electrode. Allow the hysteresis decay rates of the Axen and Wycisk models to be a function of stoichiometry and temperature. Added a heat source term in each active material phase `Q_hys = i_vol * (U - U_eq)` where `i_vol` is the volumetric interfacial current density, `U` is the OCP (i.e. includes hysteresis), and `U_eq` is the "equilibrium OCP". Renamed the open-circuit potential models to be more descriptive. The options "Axen" and "Wycisk" are now "one-state hysteresis" and "one-state differential capacity hysteresis". The old option names still work but will raise a warning. ([#4893](https://github.com/pybamm-team/PyBaMM/pull/4893))
 - Add support for `output_variables` to `pybamm.DiscreteTimeSum` and `pybamm.ExplicitTimeIntegral` expressions. ([#5071](https://github.com/pybamm-team/PyBaMM/pull/5071))
 
 ## Bug fixes
 
 - Fixed a bug that ignored the default duration of drive cycles for `CRate` steps and a bug that overwrote custom `period` arguments for drive cycles. ([#5090](https://github.com/pybamm-team/PyBaMM/pull/5090))
 - Converts sensitivities to numpy objects, fixing bug in `DiscreteTimeSum` sensitivity calculation ([#5037](https://github.com/pybamm-team/PyBaMM/pull/5037))
 - Raises error if `pybamm.Interpolant` given 1D x values that are not strictly increasing ([#5061](https://github.com/pybamm-team/PyBaMM/pull/5061))
+- Fixed a bug where simplifications cause heavisides to evaluate as booleans ([#4893](https://github.com/pybamm-team/PyBaMM/pull/4893))
+- Fixed a bug in the `WyciskOpenCircuitPotential` model where the differential capacity was not being evaluated correctly. ([#4893](https://github.com/pybamm-team/PyBaMM/pull/4893))
 
 ## Breaking changes
 
 - Removed the IREE code from the IDAKLU solver ([#5080](https://github.com/pybamm-team/PyBaMM/pull/5080))
 - Removed support for Python 3.9 ([#5052](https://github.com/pybamm-team/PyBaMM/pull/5052))
+- In OCP hysteresis models, users need to explicitly give the equilibrium, delithiation, and lithiation OCPs when using a hysteresis model. E.g., you must provide all three of "Negative electrode OCP [V]", "Negative electrode delithiation OCP [V]", and "Negative electrode lithiation OCP [V]". ([#4893](https://github.com/pybamm-team/PyBaMM/pull/4893))
+
 
 # [v25.6.0](https://github.com/pybamm-team/PyBaMM/tree/v25.6.0) - 2025-05-27
 

docs/Makefile

@@ -1,9 +1,10 @@
 # Minimal makefile for Sphinx documentation
 #
 
-# You can set these variables from the command line.
-SPHINXOPTS    = -j auto
-SPHINXBUILD   = sphinx-build
+# You can set these variables from the command line, and also
+# from the environment for the first two.
+SPHINXOPTS    ?=
+SPHINXBUILD   ?= sphinx-build
 SOURCEDIR     = .
 BUILDDIR      = _build
 
@@ -16,4 +17,4 @@ help:
 # Catch-all target: route all unknown targets to Sphinx using the new
 # "make mode" option.  $(O) is meant as a shortcut for $(SPHINXOPTS).
 %: Makefile
-    @$(SPHINXBUILD) -M $@ "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)
+	@$(SPHINXBUILD) -M $@ "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)

docs/source/api/models/submodels/interface/open_circuit_potential/base_ocp.rst

@@ -3,3 +3,6 @@ Base Open Circuit Potential
 
 .. autoclass:: pybamm.open_circuit_potential.BaseOpenCircuitPotential
     :members:
+
+.. autoclass:: pybamm.open_circuit_potential.BaseHysteresisOpenCircuitPotential
+    :members:

docs/source/api/models/submodels/interface/open_circuit_potential/index.rst

@@ -4,8 +4,8 @@ Open-circuit potential models
 .. toctree::
 
   base_ocp
-  current_sigmoid_ocp
   single_ocp
   msmr_ocp
-  wycisk_ocp
-  axen_ocp
+  one_state_hysteresis_ocp
+  one_state_differential_capacity_hysteresis_ocp
+  current_sigmoid_ocp

docs/source/api/models/submodels/interface/open_circuit_potential/one_state_differential_capacity_hysteresis_ocp.rst

@@ -0,0 +1,7 @@
+One State Differential Capacity Hysteresis Open Circuit Potential
+=================================================================
+
+.. autoclass:: pybamm.open_circuit_potential.OneStateDifferentialCapacityHysteresisOpenCircuitPotential
+    :members:
+
+.. footbibliography::

docs/source/api/models/submodels/interface/open_circuit_potential/one_state_hysteresis_ocp.rst

@@ -0,0 +1,7 @@
+One-state hysteresis open-circuit potential
+===========================================
+
+.. autoclass:: pybamm.open_circuit_potential.OneStateHysteresisOpenCircuitPotential
+    :members:
+
+.. footbibliography::

docs/source/examples/index.rst

@@ -62,12 +62,12 @@ The notebooks are organised into subfolders, and can be viewed in the galleries
     notebooks/models/compare-particle-diffusion-models.ipynb
     notebooks/models/composite_particle.ipynb
     notebooks/models/coupled-degradation.ipynb
-    notebooks/models/differential-capacity-hysteresis-state.ipynb
     notebooks/models/DFN-with-particle-size-distributions.ipynb
     notebooks/models/DFN.ipynb
     notebooks/models/electrode-state-of-health.ipynb
     notebooks/models/graded-electrodes.ipynb
     notebooks/models/half-cell.ipynb
+    notebooks/models/hysteresis-state-models.ipynb
     notebooks/models/jelly-roll-model.ipynb
     notebooks/models/latexify.ipynb
     notebooks/models/lead-acid.ipynb