Issue 3530 custom termination

CHANGELOG.md

@@ -2,10 +2,12 @@
 
 ## Features
 
+- Added method to get QuickPlot axes by variable ([#3596](https://github.com/pybamm-team/PyBaMM/pull/3596))
+- Added custom experiment terminations ([#3596](https://github.com/pybamm-team/PyBaMM/pull/3596))
+- Mechanical parameters are now a function of stoichiometry and temperature ([#3576](https://github.com/pybamm-team/PyBaMM/pull/3576))
 - Added a new unary operator, `EvaluateAt`, that evaluates a spatial variable at a given position ([#3573](https://github.com/pybamm-team/PyBaMM/pull/3573))
 - Added a method, `insert_reference_electrode`, to `pybamm.lithium_ion.BaseModel` that insert a reference electrode to measure the electrolyte potential at a given position in space and adds new variables that mimic a 3E cell setup. ([#3573](https://github.com/pybamm-team/PyBaMM/pull/3573))
 - Serialisation added so models can be written to/read from JSON ([#3397](https://github.com/pybamm-team/PyBaMM/pull/3397))
-- Mechanical parameters are now a function of stoichiometry and temperature ([#3576](https://github.com/pybamm-team/PyBaMM/pull/3576))
 
 ## Bug fixes
 

docs/conf.py

@@ -76,6 +76,7 @@
 
 doctest_global_setup = """
 from docs import *
+import pybamm
 """
 
 # Add any paths that contain templates here, relative to this directory.

docs/source/api/experiment/experiment_steps.rst

@@ -18,3 +18,28 @@ directly:
 
 .. autoclass:: pybamm.step._Step
     :members:
+
+Step terminations
+-----------------
+
+Standard step termination events are implemented by the following classes, which are
+called when the termination is specified by a specific string. These classes can be
+either be called directly or via the string format specified in the class docstring
+
+.. autoclass:: pybamm.step.CrateTermination
+    :members:
+
+.. autoclass:: pybamm.step.CurrentTermination
+    :members:
+
+.. autoclass:: pybamm.step.VoltageTermination
+    :members:
+
+The following classes can be used to define custom terminations for an experiment
+step:
+
+.. autoclass:: pybamm.step.BaseTermination
+    :members:
+
+.. autoclass:: pybamm.step.CustomTermination
+    :members:

docs/source/api/plotting/quick_plot.rst

@@ -7,3 +7,6 @@ Quick Plot
   :members:
 
 .. autofunction:: pybamm.dynamic_plot
+
+.. autoclass:: pybamm.QuickPlotAxes
+  :members:

docs/source/examples/index.rst

@@ -85,6 +85,17 @@ The notebooks are organised into subfolders, and can be viewed in the galleries
     notebooks/parameterization/parameter-values.ipynb
     notebooks/parameterization/parameterization.ipynb
 
+.. nbgallery::
+    :caption: Simulations and Experiments
+    :glob:
+
+    notebooks/simulation_and_experiments/callbacks.ipynb
+    notebooks/simulation_and_experiments/custom-experiments.ipynb
+    notebooks/simulation_and_experiments/experiments-start-time.ipynb
+    notebooks/simulation_and_experiments/rpt-experiment.ipynb
+    notebooks/simulation_and_experiments/simulating-long-experiments.ipynb
+    notebooks/simulation_and_experiments/simulation-class.ipynb
+
 .. nbgallery::
     :caption: Plotting
     :glob:
@@ -111,11 +122,6 @@ The notebooks are organised into subfolders, and can be viewed in the galleries
     :glob:
 
     notebooks/batch_study.ipynb
-    notebooks/callbacks.ipynb
     notebooks/change-settings.ipynb
     notebooks/initialize-model-with-solution.ipynb
-    notebooks/rpt-experiment.ipynb
-    notebooks/simulating-long-experiments.ipynb
-    notebooks/simulation-class.ipynb
     notebooks/solution-data-and-processed-variables.ipynb
-    notebooks/experiments-start-time.ipynb

docs/source/examples/notebooks/getting_started/tutorial-1-how-to-run-a-model.ipynb

@@ -205,7 +205,7 @@
    "name": "python",
    "nbconvert_exporter": "python",
    "pygments_lexer": "ipython3",
-   "version": "3.9.0"
+   "version": "3.11.3"
   }
  },
  "nbformat": 4,

pybamm/__init__.py

@@ -228,12 +228,13 @@
 #
 from .experiment.experiment import Experiment
 from . import experiment
+from .experiment import step
 
 
 #
 # Plotting
 #
-from .plotting.quick_plot import QuickPlot, close_plots
+from .plotting.quick_plot import QuickPlot, close_plots, QuickPlotAxes
 from .plotting.plot import plot
 from .plotting.plot2D import plot2D
 from .plotting.plot_voltage_components import plot_voltage_components

pybamm/citations.py

@@ -21,7 +21,6 @@ class Citations:
 
     Examples
     --------
-    >>> import pybamm
     >>> pybamm.citations.register("Sulzer2021")
     >>> pybamm.citations.register("@misc{Newton1687, title={Mathematical...}}")
     >>> pybamm.print_citations("citations.txt")

pybamm/experiment/experiment.py

@@ -3,7 +3,7 @@
 #
 
 import pybamm
-from pybamm.step._steps_util import (
+from .step._steps_util import (
     _convert_time_to_seconds,
     _convert_temperature_to_kelvin,
 )

pybamm/step/__init__.py → pybamm/experiment/step/__init__.py

@@ -1,2 +1,3 @@
 from .steps import *
 from .steps import _Step
+from .step_termination import *

pybamm/step/_steps_util.py → pybamm/experiment/step/_steps_util.py

@@ -4,6 +4,7 @@
 import pybamm
 import numpy as np
 from datetime import datetime
+from .step_termination import _read_termination
 
 _examples = """
 
@@ -136,8 +137,10 @@ def __init__(
             termination = [termination]
         self.termination = []
         for term in termination:
-            typ, value = _convert_electric(term)
-            self.termination.append({"type": typ, "value": value})
+            if isinstance(term, str):
+                term = _convert_electric(term)
+            term = _read_termination(term)
+            self.termination.append(term)
 
         self.temperature = _convert_temperature_to_kelvin(temperature)
 
@@ -193,10 +196,7 @@ def to_dict(self):
         }
 
     def __eq__(self, other):
-        return (
-            isinstance(other, _Step)
-            and self.hash_args == other.hash_args
-        )
+        return isinstance(other, _Step) and self.hash_args == other.hash_args
 
     def __hash__(self):
         return hash(self.basic_repr())

pybamm/experiment/step/step_termination.py

@@ -0,0 +1,164 @@
+import pybamm
+import numpy as np
+
+
+class BaseTermination:
+    """
+    Base class for a termination event for an experiment step. To create a custom
+    termination, a class must implement `get_event` to return a :class:`pybamm.Event`
+    corresponding to the desired termination. In most cases the class
+    :class:`pybamm.step.CustomTermination` can be used to assist with this.
+
+    Parameters
+    ----------
+    value : float
+        The value at which the event is triggered
+    """
+
+    def __init__(self, value):
+        self.value = value
+
+    def get_event(self, variables, step_value):
+        """
+        Return a :class:`pybamm.Event` object corresponding to the termination event
+
+        Parameters
+        ----------
+        variables : dict
+            Dictionary of model variables, to be used for selecting the variable(s) that
+            determine the event
+        step_value : float or :class:`pybamm.Symbol`
+            Value of the step for which this is a termination event, to be used in some
+            cases to determine the sign of the event.
+        """
+        raise NotImplementedError
+
+    def __eq__(self, other):
+        # objects are equal if they have the same type and value
+        if isinstance(other, self.__class__):
+            return self.value == other.value
+        else:
+            return False
+
+
+class CrateTermination(BaseTermination):
+    """
+    Termination based on C-rate, created when a string termination of the C-rate type
+    (e.g. "C/10") is provided
+    """
+
+    def get_event(self, variables, step_value):
+        """
+        See :meth:`BaseTermination.get_event`
+        """
+        event = pybamm.Event(
+            "C-rate cut-off [experiment]",
+            abs(variables["C-rate"]) - self.value,
+        )
+        return event
+
+
+class CurrentTermination(BaseTermination):
+    """
+    Termination based on current, created when a string termination of the current type
+    (e.g. "1A") is provided
+    """
+
+    def get_event(self, variables, step_value):
+        """
+        See :meth:`BaseTermination.get_event`
+        """
+        event = pybamm.Event(
+            "Current cut-off [A] [experiment]",
+            abs(variables["Current [A]"]) - self.value,
+        )
+        return event
+
+
+class VoltageTermination(BaseTermination):
+    """
+    Termination based on voltage, created when a string termination of the voltage type
+    (e.g. "4.2V") is provided
+    """
+
+    def get_event(self, variables, step_value):
+        """
+        See :meth:`BaseTermination.get_event`
+        """
+        # The voltage event should be positive at the start of charge/
+        # discharge. We use the sign of the current or power input to
+        # figure out whether the voltage event is greater than the starting
+        # voltage (charge) or less (discharge) and set the sign of the
+        # event accordingly
+        if isinstance(step_value, pybamm.Symbol):
+            inpt = {"start time": 0}
+            init_curr = step_value.evaluate(t=0, inputs=inpt).flatten()[0]
+        else:
+            init_curr = step_value
+        sign = np.sign(init_curr)
+        if sign > 0:
+            name = "Discharge"
+        else:
+            name = "Charge"
+        if sign != 0:
+            # Event should be positive at initial conditions for both
+            # charge and discharge
+            event = pybamm.Event(
+                f"{name} voltage cut-off [V] [experiment]",
+                sign * (variables["Battery voltage [V]"] - self.value),
+            )
+            return event
+
+
+class CustomTermination(BaseTermination):
+    """
+    Define a custom termination event using a function. This can be used to create an
+    event based on any variable in the model.
+
+    Parameters
+    ----------
+    name : str
+        Name of the event
+    event_function : callable
+        A function that takes in a dictionary of variables and evaluates the event
+        value. Must be positive before the event is triggered and zero when the
+        event is triggered.
+
+    Example
+    -------
+    Add a cut-off based on negative electrode stoichiometry. The event will trigger
+    when the negative electrode stoichiometry reaches 10%.
+
+    >>> def neg_stoich_cutoff(variables):
+    ...    return variables["Negative electrode stoichiometry"] - 0.1
+
+    >>> neg_stoich_termination = pybamm.step.CustomTermination(
+    ...    name="Negative stoichiometry cut-off", event_function=neg_stoich_cutoff
+    ... )
+    """
+
+    def __init__(self, name, event_function):
+        if not name.endswith(" [experiment]"):
+            name += " [experiment]"
+        self.name = name
+        self.event_function = event_function
+
+    def get_event(self, variables, step_value):
+        """
+        See :meth:`BaseTermination.get_event`
+        """
+        return pybamm.Event(self.name, self.event_function(variables))
+
+
+def _read_termination(termination):
+    if isinstance(termination, tuple):
+        typ, value = termination
+    else:
+        return termination
+
+    termination_class = {
+        "current": CurrentTermination,
+        "voltage": VoltageTermination,
+        "C-rate": CrateTermination,
+    }[typ]
+    return termination_class(value)

pybamm/expression_tree/symbol.py

@@ -423,7 +423,12 @@ def set_id(self):
         need to hash once.
         """
         self._id = hash(
-            (self.__class__, self.name, *tuple([child.id for child in self.children]), *tuple([(k, tuple(v)) for k, v in self.domains.items() if v != []]))
+            (
+                self.__class__,
+                self.name,
+                *tuple([child.id for child in self.children]),
+                *tuple([(k, tuple(v)) for k, v in self.domains.items() if v != []]),
+            )
         )
 
     @property
@@ -532,7 +537,6 @@ def pre_order(self):
         Examples
         --------
 
-        >>> import pybamm
         >>> a = pybamm.Symbol('a')
         >>> b = pybamm.Symbol('b')
         >>> for node in (a*b).pre_order():

pybamm/models/full_battery_models/equivalent_circuit/thevenin.py

@@ -52,7 +52,6 @@ class Thevenin(pybamm.BaseModel):
 
     Examples
     --------
-    >>> import pybamm
     >>> model = pybamm.equivalent_circuit.Thevenin()
     >>> model.name
     'Thevenin Equivalent Circuit Model'

pybamm/models/full_battery_models/lithium_ion/dfn.py

@@ -13,7 +13,6 @@ class DFN(BaseModel):
 
     Examples
     --------
-    >>> import pybamm
     >>> model = pybamm.lithium_ion.DFN()
     >>> model.name
     'Doyle-Fuller-Newman model'

pybamm/models/full_battery_models/lithium_ion/mpm.py

@@ -13,7 +13,6 @@ class MPM(SPM):
 
     Examples
     --------
-    >>> import pybamm
     >>> model = pybamm.lithium_ion.MPM()
     >>> model.name
     'Many-Particle Model'

pybamm/models/full_battery_models/lithium_ion/spm.py

@@ -13,7 +13,6 @@ class SPM(BaseModel):
 
     Examples
     --------
-    >>> import pybamm
     >>> model = pybamm.lithium_ion.SPM()
     >>> model.name
     'Single Particle Model'

pybamm/models/full_battery_models/lithium_ion/spme.py

@@ -14,7 +14,6 @@ class SPMe(SPM):
 
     Examples
     --------
-    >>> import pybamm
     >>> model = pybamm.lithium_ion.SPMe()
     >>> model.name
     'Single Particle Model with electrolyte'