# Terminology and standards

Battery models have lots of terminology that is often used to mean different things in different contexts. This page defines the terminology as used in this package (and generally in the PyBaMM ecocystem, though not always perfectly consistently). Additionally, there are several times where different standards can be used somewhat arbitrarily, so we outline what standards we use here.

## Terminology

| Name                 | Meaning                                                                                                                                                                                                                                                                     |
| -------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Anode                | The electrode with the lower open-circuit potential, usually graphite. In some definitions, which electrode is the "anode" switches based on whether the battery is charging or discharging. We always use "anode" to describe the "negative electrode"                     |
| Cathode              | The electrode with the higher open-circuit potential, e.g. NMC or LFP. See "anode" for details                                                                                                                                                                              |
| Capacity             | Can be used to mean either the total available capacity of an electrode or whole cell, denoted by capital $Q$, or the instantaneous capacity of the electrode or whole cell (i.e. integral of the current in Amps with respect to time in hours), denoted by lower case $q$ |
| Lithiation           | The amount of lithium intercalated an electrode relative to the minimum and maximum possible lithium content. Goes from 0 to 1                                                                                                                                              |
| Negative electrode   | Used interchangeably with "anode"                                                                                                                                                                                                                                           |
| Nominal capacity     | The rated capacity of the cell                                                                                                                                                                                                                                              |
| Positive electrode   | Used interchangeably with "cathode"                                                                                                                                                                                                                                         |
| Potential            | The electric potential of a single electrode relative to metallic lithium (0V)                                                                                                                                                                                              |
| Stoichiometry        | Used interchangeably with "lithiation"                                                                                                                                                                                                                                      |
| Theoretical capacity | The total capacity that can be extracted from the cell at open-circuit voltage (infinitely slow discharge) between voltage limits                                                                                                                                           |
| Voltage              | The difference between positive and negative electrode potentials                                                                                                                                                                                                           |

## Standards

### Direction of current

We have to make a choice about sign convention for the current. There is no right or wrong choice, but it is important to be consistent.
In PyBaMM, and therefore in this package, we follow the convention that a positive current (increasing capacity) means that the battery is discharging, and so a negative current (decreasing capacity) means that the battery is charging. The discharge capacity is given by
$$
q_{dchg}(t) = Q_0 + \int I(t) d\mathrm{t},
$$
where $Q_0$ is the starting capacity (equal to 0 if the cell is at 100% SOC and $Q_{cell}$ if the cell is at 0% SOC).
We also define the charging capacity
$$
q_{chg}(t) = -q_{dchg}(t),
$$
where we use lower case $q$ to indicate that this is a function of time (as opposed to capital $Q$ which is used to represent scalar properties of the electrodes or cell).

### Single electrode

For a single electrode, we say that the electrode is "charged" when its lithiation/stoichiometry/capacity increases. In terms of capacity, the instantaneous capacity of the electrode is defined by $q^{elec}(t)$. The mathematical definition of $q^{elec}$ depends on whether the electrode is the anode or cathode of a full cell (see below), but in general $q^{elec}$ is equal to $q_{chg}$ (or $q_{dchg}$) plus an offset.

We can think in terms of electrode lithiation/stoichiometry by defining
$$
\theta(t) = q^{elec}(t) / Q^{tot}, 
$$
where $Q^{tot}$ is the total capacity of the electrode (often just referred to as "the electrode capacity").

| Variable    | Meaning                                     |
| ----------- | ------------------------------------------- |
| $q^{elec}$  | Instantaneous capacity of an electrode      |
| $Q^{tot}$   | Total capacity of the electrode             |
| $\theta(t)$ | Instantaneous stoichiometry of an electrode |

### Whole cell

The negative and positive electrodes behave differently when put together in a full cell, which means we need to think carefully about what is happening to the lithiation of each electrode and its corresponding open-circuit potential.

During a discharge, the negative electrode lithiation decreases, which causes its open-circuit potential to increase. The positive electrode lithiation increases, which causes its open-circuit potential to decreases. Overall, the open-circuit voltage of the cell is given by
$$U = U_p - U_n,$$
which is monotonically decreasing since $U_p$ is decreasing and $U_n$ is increasing.

Defining min/max electrode capacities by $Q^{min/max}$, and electrode capacities at 0%/100% cell SOC by $Q^{0/100}$, we have the following relationships:

$$
\begin{align*}
Q_n^{min} &= Q_n^0,
\\
Q_n^{max} &= Q_n^{100},
\\
Q_p^{max} &= Q_p^0,
\\
Q_p^{min} &= Q_p^{100}.
\end{align*}
$$

The electrode instantaneous capacity is given by
$$q_n^{elec}(t) = Q_n^{100} - q_{dchg} $$
for the negative electrode and
$$q_p^{elec}(t) = Q_p^{100} + q_{dchg} $$
for the positive electrode.
For each electrode, $Q^{max} = Q^{min} + Q^{cell}$, where $Q^{cell}$ is the theoretical capacity of the cell (the capacity that can be extracted from the electrode between its voltage limits).

In terms of stoichiometries,
$$\theta_n^{elec}(t) = \theta_n^{100} - \frac{q_{chg}}{Q_n^{tot}}, $$
and
$$\theta_p^{elec}(t) = \theta_p^{100} + \frac{q_{chg}}{Q_p^{tot}}, $$

The cell's SOC is given by $z = q_{chg}/Q_{cell}$.

| Variable       | Meaning                                    |
| -------------- | ------------------------------------------ |
| $Q^{cell}$     | Useable capacity of the electrode           |
| $Q^{min}$      | Capacity at the lower voltage cut-off      |
| $Q^{max}$      | Capacity at the upper voltage cut-off      |
| $\theta^{min}$ | Stoichiometry at the lower voltage cut-off |
| $\theta^{max}$ | Stoichiometry at the upper voltage cut-off |

### Naming standards

- Historically, we have used "anode"/"negative electrode" and "cathode"/"positive electrode" interchangeably throughout PyBaMM projects. For consistency, always use "negative" and "positive" to refer to the electrodes, instead of "anode" and "cathode".
- The concept of "charge" and "discharge" can be confusing for an electrode since the two electrodes gain or lose lithium in opposite directions depending on whether they are the anode or cathode. To avoid confusion, we use "charge" and "discharge" to refer to the whole cell, and "lithiation" and "delithiation" to refer to the individual electrodes. During a whole-cell discharge, the negative electrode delithiates and the positive electrode lithiates. During a whole-cell charge, the negative electrode lithiates and the positive electrode delithiates.