Experiment step functions#

The following functions can be used to define steps in an experiment. Note that the drive cycle must start at t=0

pybamm.step.string(text, **kwargs)#

Create a step from a string.

Parameters:

  • text (str) – The string to parse. Each operating condition should be of the form “Do this for this long” or “Do this until this happens”. For example, “Charge at 1 C for 1 hour”, or “Charge at 1 C until 4.2 V”, or “Charge at 1 C for 1 hour or until 4.2 V”. The instructions can be of the form “(Dis)charge at x A/C/W”, “Rest”, or “Hold at x V until y A”. The running time should be a time in seconds, minutes or hours, e.g. “10 seconds”, “3 minutes” or “1 hour”. The stopping conditions should be a circuit state, e.g. “1 A”, “C/50” or “3 V”.

  • **kwargs – Any other keyword arguments are passed to the step class

Returns:

A step parsed from the string.

Return type:

pybamm.step.BaseStep

pybamm.step.current(value, **kwargs)#

Current-controlled step, see pybamm.step.Current.

pybamm.step.voltage(*args, **kwargs)#

Voltage-controlled step, see pybamm.step.Voltage.

pybamm.step.power(value, **kwargs)#

Power-controlled step, see pybamm.step.Power.

pybamm.step.resistance(value, **kwargs)#

Resistance-controlled step, see pybamm.step.Resistance.

These functions return the following step class, which is not intended to be used directly:

class pybamm.step.BaseStep(value, duration=None, termination=None, period=None, temperature=None, tags=None, start_time=None, description=None, direction=None)#

Class representing one step in an experiment. All experiment steps are functions that return an instance of this class. This class is not intended to be used directly, but can be subtyped to create a custom experiment step.

Parameters:

  • value (float) – The value of the step, corresponding to the type of step. Can be a number, a 2-tuple (for cccv_ode), a 2-column array (for drive cycles), or a 1-argument function of t

  • duration (float, optional) – The duration of the step in seconds.

  • termination (str or list, optional) – A string or list of strings indicating the condition(s) that will terminate the step. If a list, the step will terminate when any of the conditions are met.

  • period (float or string, optional) – The period of the step. If a float, the value is in seconds. If a string, the value should be a valid time string, e.g. “1 hour”.

  • temperature (float or string, optional) – The temperature of the step. If a float, the value is in Kelvin. If a string, the value should be a valid temperature string, e.g. “25 oC”.

  • tags (str or list, optional) – A string or list of strings indicating the tags associated with the step.

  • start_time (str or datetime, optional) – The start time of the step.

  • description (str, optional) – A description of the step.

  • direction (str, optional) – The direction of the step, e.g. “Charge” or “Discharge” or “Rest”.

basic_repr()#

Return a basic representation of the step, only with type, value, termination and temperature, which are the variables involved in processing the model. Also used for hashing.

copy()#

Return a copy of the step.

Returns:

A copy of the step.

Return type:

pybamm.Step

default_duration(value)#

Default duration for the step is one day (24 hours) or the duration of the drive cycle

record_tags(value, duration, termination, period, temperature, tags, start_time, description, direction)#

Record all the args for repr and hash

setup_timestepping(solver, tf, t_interp=None)#

Setup timestepping for the model.

Parameters:

  • solver (:class`pybamm.BaseSolver`) – The solver

  • tf (float) – The final time

  • t_interp (np.array | None) – The time points at which to interpolate the solution

to_dict()#

Convert the step to a dictionary.

Returns:

A dictionary containing the step information.

Return type:

dict

value_based_charge_or_discharge()#

Determine whether the step is a charge or discharge step based on the value of the step

Custom steps#

Custom steps can be defined using either explicit or implicit control:

class pybamm.step.CustomStepExplicit(current_value_function, **kwargs)#

Custom step class where the current value is explicitly given as a function of other variables. When using this class, the user must be careful not to create an expression that depends on the current itself, as this will lead to a circular dependency. For example, in some models, the voltage is an explicit function of the current, so the user should not create a step that depends on the voltage. An expression that works for one model may not work for another.

Parameters:

  • current_value_function (callable) – A function that takes in a dictionary of variables and returns the current value.

  • duration (float, optional) – The duration of the step in seconds.

  • termination (str or list, optional) – A string or list of strings indicating the condition(s) that will terminate the step. If a list, the step will terminate when any of the conditions are met.

  • period (float or string, optional) – The period of the step. If a float, the value is in seconds. If a string, the value should be a valid time string, e.g. “1 hour”.

  • temperature (float or string, optional) – The temperature of the step. If a float, the value is in Kelvin. If a string, the value should be a valid temperature string, e.g. “25 oC”.

  • tags (str or list, optional) – A string or list of strings indicating the tags associated with the step.

  • start_time (str or datetime, optional) – The start time of the step.

  • description (str, optional) – A description of the step.

  • direction (str, optional) – The direction of the step, e.g. “Charge” or “Discharge” or “Rest”.

Examples

Control the current to always be equal to a target power divided by voltage (this is one way to implement a power control step):

>>> def current_function(variables):
...     P = 4
...     V = variables["Voltage [V]"]
...     return P / V

Create the step with a 2.5 V termination condition:

>>> step = pybamm.step.CustomStepExplicit(current_function, termination="2.5V")

Extends: pybamm.experiment.step.base_step.BaseStepExplicit

copy()#

Return a copy of the step.

Returns:

A copy of the step.

Return type:

pybamm.Step

class pybamm.step.CustomStepImplicit(current_rhs_function, control='algebraic', **kwargs)#

Custom step, see pybamm.step.BaseStep for arguments.

Parameters:

  • current_rhs_function (callable) – A function that takes in a dictionary of variables and returns the equation controlling the current.

  • control (str, optional) –

    Whether the control is algebraic or differential. Default is algebraic, in which case the equation is

    \[0 = f(\text{{variables}})\]

    where \(f\) is the current_rhs_function.

    If control is “differential”, the equation is

    \[\frac{dI}{dt} = f(\text{{variables}})\]

  • duration (float, optional) – The duration of the step in seconds.

  • termination (str or list, optional) – A string or list of strings indicating the condition(s) that will terminate the step. If a list, the step will terminate when any of the conditions are met.

  • period (float or string, optional) – The period of the step. If a float, the value is in seconds. If a string, the value should be a valid time string, e.g. “1 hour”.

  • temperature (float or string, optional) – The temperature of the step. If a float, the value is in Kelvin. If a string, the value should be a valid temperature string, e.g. “25 oC”.

  • tags (str or list, optional) – A string or list of strings indicating the tags associated with the step.

  • start_time (str or datetime, optional) – The start time of the step.

  • description (str, optional) – A description of the step.

  • direction (str, optional) – The direction of the step, e.g. “Charge” or “Discharge” or “Rest”.

Examples

Control the current so that the voltage is constant (without using the built-in voltage control):

>>> def voltage_control(variables):
...     V = variables["Voltage [V]"]
...     return V - 4.2

Create the step with a duration of 1h. In this case we don’t need to specify that the control is algebraic, as this is the default.

>>> step = pybamm.step.CustomStepImplicit(voltage_control, duration=3600)

Alternatively, control the current by a differential equation to achieve a target power:

>>> def power_control(variables):
...     V = variables["Voltage [V]"]
...     # Large time constant to avoid large overshoot. The user should be careful
...     # to choose a time constant that is appropriate for the model being used,
...     # as well as choosing the appropriate sign for the time constant.
...     K_V = 100
...     return K_V * (V - 4.2)

Create the step with a 2.5 V termination condition. Now we need to specify that the control is differential.

>>> step = pybamm.step.CustomStepImplicit(
...     power_control, termination="2.5V", control="differential"
... )

Extends: pybamm.experiment.step.base_step.BaseStepImplicit

copy()#

Return a copy of the step.

Returns:

A copy of the step.

Return type:

pybamm.Step

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

class pybamm.step.CrateTermination(value)#

Termination based on C-rate, created when a string termination of the C-rate type (e.g. “C/10”) is provided

Extends: pybamm.experiment.step.step_termination.BaseTermination

get_event(variables, step)#

See BaseTermination.get_event()

class pybamm.step.CurrentTermination(value)#

Termination based on current, created when a string termination of the current type (e.g. “1A”) is provided

Extends: pybamm.experiment.step.step_termination.BaseTermination

get_event(variables, step)#

See BaseTermination.get_event()

class pybamm.step.VoltageTermination(value)#

Termination based on voltage, created when a string termination of the voltage type (e.g. “4.2V”) is provided

Extends: pybamm.experiment.step.step_termination.BaseTermination

get_event(variables, step)#

See BaseTermination.get_event()

The following classes can be used to define custom terminations for an experiment step:

class pybamm.step.BaseTermination(value)#

Base class for a termination event for an experiment step. To create a custom termination, a class must implement get_event to return a pybamm.Event corresponding to the desired termination. In most cases the class pybamm.step.CustomTermination can be used to assist with this.

Parameters:

value (float) – The value at which the event is triggered

get_event(variables, step)#

Return a 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 (pybamm.step.BaseStep) – Step for which this is a termination event, to be used in some cases to determine the sign of the event.

class pybamm.step.CustomTermination(name, event_function)#

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
... )

Extends: pybamm.experiment.step.step_termination.BaseTermination

get_event(variables, step)#

See BaseTermination.get_event()