def test_r_average(self):
a = pybamm.Scalar(1)
average_a = pybamm.r_average(a)
self.assertEqual(average_a.id, a.id)
average_broad_a = pybamm.r_average(
pybamm.PrimaryBroadcast(a, ["negative particle"]))
self.assertEqual(average_broad_a.evaluate(), np.array([1]))
for domain in [["negative particle"], ["positive particle"]]:
a = pybamm.Symbol("a", domain=domain)
r = pybamm.SpatialVariable("r", domain)
av_a = pybamm.r_average(a)
self.assertIsInstance(av_a, pybamm.Division)
self.assertIsInstance(av_a.children[0], pybamm.Integral)
self.assertEqual(av_a.children[0].integration_variable[0].domain,
r.domain)
# electrode domains go to current collector when averaged
self.assertEqual(av_a.domain, [])
# r-average of symbol that evaluates on edges raises error
symbol_on_edges = pybamm.PrimaryBroadcastToEdges(1, "domain")
with self.assertRaisesRegex(
ValueError,
"Can't take the r-average of a symbol that evaluates on edges"
):
pybamm.r_average(symbol_on_edges)
def test_r_average(self):
a = pybamm.Scalar(1)
average_a = pybamm.r_average(a)
self.assertEqual(average_a.id, a.id)
average_broad_a = pybamm.r_average(
pybamm.Broadcast(a, ["negative particle"]))
self.assertEqual(average_broad_a.evaluate(), np.array([1]))
for domain in [["negative particle"], ["positive particle"]]:
a = pybamm.Symbol("a", domain=domain)
r = pybamm.SpatialVariable("r", domain)
av_a = pybamm.r_average(a)
self.assertIsInstance(av_a, pybamm.Division)
self.assertIsInstance(av_a.children[0], pybamm.Integral)
self.assertEqual(av_a.children[0].integration_variable[0].domain,
r.domain)
# electrode domains go to current collector when averaged
self.assertEqual(av_a.domain, [])
a = pybamm.Symbol("a", domain="bad domain")
with self.assertRaises(pybamm.DomainError):
pybamm.x_average(a)
def r_average(symbol):
"""convenience function for creating an average in the r-direction
Parameters
----------
symbol : :class:`pybamm.Symbol`
The function to be averaged
Returns
-------
:class:`Symbol`
the new averaged symbol
"""
# Can't take average if the symbol evaluates on edges
if symbol.evaluates_on_edges("primary"):
raise ValueError(
"Can't take the r-average of a symbol that evaluates on edges")
# Otherwise, if symbol doesn't have a particle domain,
# its r-averaged value is itself
elif symbol.domain not in [
["positive particle"],
["negative particle"],
["working particle"],
]:
new_symbol = symbol.new_copy()
new_symbol.parent = None
return new_symbol
# If symbol is a secondary broadcast onto "negative electrode" or
# "positive electrode", take the r-average of the child then broadcast back
elif isinstance(
symbol,
pybamm.SecondaryBroadcast) and symbol.domains["secondary"] in [[
"positive electrode"
], ["negative electrode"], ["working electrode"]]:
child = symbol.orphans[0]
child_av = pybamm.r_average(child)
return pybamm.PrimaryBroadcast(child_av, symbol.domains["secondary"])
# If symbol is a Broadcast onto a particle domain, its average value is its child
elif isinstance(symbol, pybamm.PrimaryBroadcast) and symbol.domain in [
["positive particle"],
["negative particle"],
["working particle"],
]:
return symbol.orphans[0]
else:
r = pybamm.SpatialVariable("r", symbol.domain)
v = pybamm.FullBroadcast(pybamm.Scalar(1), symbol.domain,
symbol.auxiliary_domains)
return Integral(symbol, r) / Integral(v, r)
def _get_standard_concentration_variables(self, c_s, c_s_xav):
c_s_surf = pybamm.surf(c_s)
c_s_surf_av = pybamm.x_average(c_s_surf)
geo_param = pybamm.geometric_parameters
if self.domain == "Negative":
c_scale = self.param.c_n_max
active_volume = geo_param.a_n_dim * geo_param.R_n / 3
elif self.domain == "Positive":
c_scale = self.param.c_p_max
active_volume = geo_param.a_p_dim * geo_param.R_p / 3
c_s_r_av = pybamm.r_average(c_s_xav)
c_s_r_av_vol = active_volume * c_s_r_av
variables = {
self.domain + " particle concentration":
c_s,
self.domain + " particle concentration [mol.m-3]":
c_s * c_scale,
"X-averaged " + self.domain.lower() + " particle concentration":
c_s_xav,
"X-averaged " + self.domain.lower() + " particle concentration [mol.m-3]":
c_s_xav * c_scale,
self.domain + " particle surface concentration":
c_s_surf,
self.domain + " particle surface concentration [mol.m-3]":
c_scale * c_s_surf,
"X-averaged " + self.domain.lower() + " particle surface concentration":
c_s_surf_av,
"X-averaged " + self.domain.lower() + " particle surface concentration [mol.m-3]":
c_scale * c_s_surf_av,
self.domain + " electrode active volume fraction":
active_volume,
self.domain + " electrode volume-averaged concentration":
c_s_r_av_vol,
self.domain + " electrode " + "volume-averaged concentration [mol.m-3]":
c_s_r_av_vol * c_scale,
self.domain + " electrode average extent of lithiation":
c_s_r_av,
}
return variables
def _get_standard_concentration_variables(
self, c_s, c_s_xav=None, c_s_rav=None, c_s_av=None, c_s_surf=None
):
"""
All particle submodels must provide the particle concentration as an argument
to this method. Some submodels solve for quantities other than the concentration
itself, for example the 'FickianSingleParticle' models solves for the x-averaged
concentration. In such cases the variables being solved for (set in
'get_fundamental_variables') must also be passed as keyword arguments. If not
passed as keyword arguments, the various average concentrations and surface
concentration are computed automatically from the particle concentration.
"""
# Get surface concentration if not provided as fundamental variable to
# solve for
c_s_surf = c_s_surf or pybamm.surf(c_s)
c_s_surf_av = pybamm.x_average(c_s_surf)
if self.domain == "Negative":
c_scale = self.param.c_n_max
elif self.domain == "Positive":
c_scale = self.param.c_p_max
# Get average concentration(s) if not provided as fundamental variable to
# solve for
c_s_xav = c_s_xav or pybamm.x_average(c_s)
c_s_rav = c_s_rav or pybamm.r_average(c_s)
c_s_av = c_s_av or pybamm.r_average(c_s_xav)
variables = {
self.domain + " particle concentration": c_s,
self.domain + " particle concentration [mol.m-3]": c_s * c_scale,
self.domain + " particle concentration [mol.m-3]": c_s * c_scale,
"X-averaged " + self.domain.lower() + " particle concentration": c_s_xav,
"X-averaged "
+ self.domain.lower()
+ " particle concentration [mol.m-3]": c_s_xav * c_scale,
"R-averaged " + self.domain.lower() + " particle concentration": c_s_rav,
"R-averaged "
+ self.domain.lower()
+ " particle concentration [mol.m-3]": c_s_rav * c_scale,
"Average " + self.domain.lower() + " particle concentration": c_s_av,
"Average "
+ self.domain.lower()
+ " particle concentration [mol.m-3]": c_s_av * c_scale,
self.domain + " particle surface concentration": c_s_surf,
self.domain
+ " particle surface concentration [mol.m-3]": c_scale * c_s_surf,
"X-averaged "
+ self.domain.lower()
+ " particle surface concentration": c_s_surf_av,
"X-averaged "
+ self.domain.lower()
+ " particle surface concentration [mol.m-3]": c_scale * c_s_surf_av,
self.domain + " electrode extent of lithiation": c_s_rav,
"X-averaged "
+ self.domain.lower()
+ " electrode extent of lithiation": c_s_av,
"Minimum "
+ self.domain.lower()
+ " particle concentration": pybamm.min(c_s),
"Maximum "
+ self.domain.lower()
+ " particle concentration": pybamm.max(c_s),
"Minimum "
+ self.domain.lower()
+ " particle concentration [mol.m-3]": pybamm.min(c_s) * c_scale,
"Maximum "
+ self.domain.lower()
+ " particle concentration [mol.m-3]": pybamm.max(c_s) * c_scale,
"Minimum "
+ self.domain.lower()
+ " particle surface concentration": pybamm.min(c_s_surf),
"Maximum "
+ self.domain.lower()
+ " particle surface concentration": pybamm.max(c_s_surf),
"Minimum "
+ self.domain.lower()
+ " particle surface concentration [mol.m-3]": pybamm.min(c_s_surf)
* c_scale,
"Maximum "
+ self.domain.lower()
+ " particle surface concentration [mol.m-3]": pybamm.max(c_s_surf)
* c_scale,
}
return variables
def __init__(self, name="Doyle-Fuller-Newman half cell model", options=None):
super().__init__({}, name)
pybamm.citations.register("Marquis2019")
# `param` is a class containing all the relevant parameters and functions for
# this model. These are purely symbolic at this stage, and will be set by the
# `ParameterValues` class when the model is processed.
param = self.param
options = options or {"working electrode": None}
if options["working electrode"] not in ["negative", "positive"]:
raise ValueError(
"The option 'working electrode' should be either 'positive'"
" or 'negative'"
)
self.options.update(options)
working_electrode = options["working electrode"]
if working_electrode == "negative":
R_w_typ = param.R_n_typ
else:
R_w_typ = param.R_p_typ
# Set default length scales
self.length_scales = {
"working electrode": param.L_x,
"separator": param.L_x,
"working particle": R_w_typ,
"current collector y": param.L_z,
"current collector z": param.L_z,
}
######################
# Variables
######################
# Variables that depend on time only are created without a domain
Q = pybamm.Variable("Discharge capacity [A.h]")
# Define some useful scalings
pot = param.potential_scale
i_typ = param.current_scale
# Variables that vary spatially are created with a domain.
c_e_s = pybamm.Variable(
"Separator electrolyte concentration", domain="separator"
)
c_e_w = pybamm.Variable(
"Working electrolyte concentration", domain="working electrode"
)
c_e = pybamm.concatenation(c_e_s, c_e_w)
c_s_w = pybamm.Variable(
"Working particle concentration",
domain="working particle",
auxiliary_domains={"secondary": "working electrode"},
)
phi_s_w = pybamm.Variable(
"Working electrode potential", domain="working electrode"
)
phi_e_s = pybamm.Variable("Separator electrolyte potential", domain="separator")
phi_e_w = pybamm.Variable(
"Working electrolyte potential", domain="working electrode"
)
phi_e = pybamm.concatenation(phi_e_s, phi_e_w)
# Constant temperature
T = param.T_init
######################
# Other set-up
######################
# Current density
i_cell = param.current_with_time
# Define particle surface concentration
# Surf takes the surface value of a variable, i.e. its boundary value on the
# right side. This is also accessible via `boundary_value(x, "right")`, with
# "left" providing the boundary value of the left side
c_s_surf_w = pybamm.surf(c_s_w)
# Define parameters. We need to assemble them differently depending on the
# working electrode
if working_electrode == "negative":
# Porosity and Tortuosity
# Primary broadcasts are used to broadcast scalar quantities across a domain
# into a vector of the right shape, for multiplying with other vectors
eps_s = pybamm.PrimaryBroadcast(
pybamm.Parameter("Separator porosity"), "separator"
)
eps_w = pybamm.PrimaryBroadcast(
pybamm.Parameter("Negative electrode porosity"), "working electrode"
)
b_e_s = param.b_e_s
b_e_w = param.b_e_n
# Interfacial reactions
j0_w = param.j0_n(c_e_w, c_s_surf_w, T) / param.C_r_n
U_w = param.U_n
ne_w = param.ne_n
# Particle diffusion parameters
D_w = param.D_n
C_w = param.C_n
a_R_w = param.a_R_n
gamma_w = pybamm.Scalar(1)
c_w_init = param.c_n_init
# Electrode equation parameters
eps_s_w = pybamm.Parameter(
"Negative electrode active material volume fraction"
)
b_s_w = param.b_s_n
sigma_w = param.sigma_n
# Other parameters (for outputs)
c_w_max = param.c_n_max
U_ref = param.U_n_ref
phi_s_w_ref = pybamm.Scalar(0)
L_w = param.L_n
else:
# Porosity and Tortuosity
eps_s = pybamm.PrimaryBroadcast(
pybamm.Parameter("Separator porosity"), "separator"
)
eps_w = pybamm.PrimaryBroadcast(
pybamm.Parameter("Positive electrode porosity"), "working electrode"
)
b_e_s = param.b_e_s
b_e_w = param.b_e_p
# Interfacial reactions
j0_w = param.gamma_p * param.j0_p(c_e_w, c_s_surf_w, T) / param.C_r_p
U_w = param.U_p
ne_w = param.ne_p
# Particle diffusion parameters
D_w = param.D_p
C_w = param.C_p
a_R_w = param.a_R_p
gamma_w = param.gamma_p
c_w_init = param.c_p_init
# Electrode equation parameters
eps_s_w = pybamm.Parameter(
"Positive electrode active material volume fraction"
)
b_s_w = param.b_s_p
sigma_w = param.sigma_p
# Other parameters (for outputs)
c_w_max = param.c_p_max
U_ref = param.U_p_ref
phi_s_w_ref = param.U_p_ref - param.U_n_ref
L_w = param.L_p
eps = pybamm.concatenation(eps_s, eps_w)
tor = pybamm.concatenation(eps_s ** b_e_s, eps_w ** b_e_w)
j_w = (
2 * j0_w * pybamm.sinh(ne_w / 2 * (phi_s_w - phi_e_w - U_w(c_s_surf_w, T)))
)
j_s = pybamm.PrimaryBroadcast(0, "separator")
j = pybamm.concatenation(j_s, j_w)
######################
# State of Charge
######################
I = param.dimensional_current_with_time
# The `rhs` dictionary contains differential equations, with the key being the
# variable in the d/dt
self.rhs[Q] = I * param.timescale / 3600
# Initial conditions must be provided for the ODEs
self.initial_conditions[Q] = pybamm.Scalar(0)
######################
# Particles
######################
# The div and grad operators will be converted to the appropriate matrix
# multiplication at the discretisation stage
N_s_w = -D_w(c_s_w, T) * pybamm.grad(c_s_w)
self.rhs[c_s_w] = -(1 / C_w) * pybamm.div(N_s_w)
# Boundary conditions must be provided for equations with spatial
# derivatives
self.boundary_conditions[c_s_w] = {
"left": (pybamm.Scalar(0), "Neumann"),
"right": (
-C_w * j_w / a_R_w / gamma_w / D_w(c_s_surf_w, T),
"Neumann",
),
}
# c_w_init can in general be a function of x
# Note the broadcasting, for domains
x_w = pybamm.PrimaryBroadcast(half_cell_spatial_vars.x_w, "working particle")
self.initial_conditions[c_s_w] = c_w_init(x_w)
# Events specify points at which a solution should terminate
self.events += [
pybamm.Event(
"Minimum working particle surface concentration",
pybamm.min(c_s_surf_w) - 0.01,
),
pybamm.Event(
"Maximum working particle surface concentration",
(1 - 0.01) - pybamm.max(c_s_surf_w),
),
]
######################
# Current in the solid
######################
sigma_eff_w = sigma_w * eps_s_w ** b_s_w
i_s_w = -sigma_eff_w * pybamm.grad(phi_s_w)
self.boundary_conditions[phi_s_w] = {
"left": (pybamm.Scalar(0), "Neumann"),
"right": (
i_cell / pybamm.boundary_value(-sigma_eff_w, "right"),
"Neumann",
),
}
self.algebraic[phi_s_w] = pybamm.div(i_s_w) + j_w
# Initial conditions must also be provided for algebraic equations, as an
# initial guess for a root-finding algorithm which calculates consistent
# initial conditions
self.initial_conditions[phi_s_w] = U_w(c_w_init(1), param.T_init)
######################
# Electrolyte concentration
######################
N_e = -tor * param.D_e(c_e, T) * pybamm.grad(c_e)
self.rhs[c_e] = (1 / eps) * (
-pybamm.div(N_e) / param.C_e
+ (1 - param.t_plus(c_e, T)) * j / param.gamma_e
)
dce_dx = (
-(1 - param.t_plus(c_e, T))
* i_cell
* param.C_e
/ (tor * param.gamma_e * param.D_e(c_e, T))
)
self.boundary_conditions[c_e] = {
"left": (pybamm.boundary_value(dce_dx, "left"), "Neumann"),
"right": (pybamm.Scalar(0), "Neumann"),
}
self.initial_conditions[c_e] = param.c_e_init
self.events.append(
pybamm.Event(
"Zero electrolyte concentration cut-off", pybamm.min(c_e) - 0.002
)
)
######################
# Current in the electrolyte
######################
i_e = (param.kappa_e(c_e, T) * tor * param.gamma_e / param.C_e) * (
param.chi(c_e, T) * pybamm.grad(c_e) / c_e - pybamm.grad(phi_e)
)
self.algebraic[phi_e] = pybamm.div(i_e) - j
ref_potential = param.U_n_ref / pot
self.boundary_conditions[phi_e] = {
"left": (ref_potential, "Dirichlet"),
"right": (pybamm.Scalar(0), "Neumann"),
}
self.initial_conditions[phi_e] = ref_potential
######################
# (Some) variables
######################
L_Li = pybamm.Parameter("Lithium counter electrode thickness [m]")
sigma_Li = pybamm.Parameter("Lithium counter electrode conductivity [S.m-1]")
j_Li = pybamm.Parameter(
"Lithium counter electrode exchange-current density [A.m-2]"
)
vdrop_cell = pybamm.boundary_value(phi_s_w, "right") - ref_potential
vdrop_Li = -(
2 * pybamm.arcsinh(i_cell * i_typ / j_Li)
+ L_Li * i_typ * i_cell / (sigma_Li * pot)
)
voltage = vdrop_cell + vdrop_Li
c_e_total = pybamm.x_average(eps * c_e)
c_s_surf_w_av = pybamm.x_average(c_s_surf_w)
c_s_rav = pybamm.r_average(c_s_w)
c_s_vol_av = pybamm.x_average(eps_s_w * c_s_rav)
# The `variables` dictionary contains all variables that might be useful for
# visualising the solution of the model
self.variables = {
"Time [s]": param.timescale * pybamm.t,
"Working particle surface concentration": c_s_surf_w,
"X-averaged working particle surface concentration": c_s_surf_w_av,
"Working particle concentration": c_s_w,
"Working particle surface concentration [mol.m-3]": c_w_max * c_s_surf_w,
"X-averaged working particle surface concentration "
"[mol.m-3]": c_w_max * c_s_surf_w_av,
"Working particle concentration [mol.m-3]": c_w_max * c_s_w,
"Total lithium in working electrode": c_s_vol_av,
"Total lithium in working electrode [mol]": c_s_vol_av
* c_w_max
* L_w
* param.A_cc,
"Electrolyte concentration": c_e,
"Electrolyte concentration [mol.m-3]": param.c_e_typ * c_e,
"Total electrolyte concentration": c_e_total,
"Total electrolyte concentration [mol]": c_e_total
* param.c_e_typ
* L_w
* param.L_s
* param.A_cc,
"Current [A]": I,
"Working electrode potential": phi_s_w,
"Working electrode potential [V]": phi_s_w_ref + pot * phi_s_w,
"Working electrode open circuit potential": U_w(c_s_surf_w, T),
"Working electrode open circuit potential [V]": U_ref
+ pot * U_w(c_s_surf_w, T),
"Electrolyte potential": phi_e,
"Electrolyte potential [V]": -param.U_n_ref + pot * phi_e,
"Voltage drop in the cell": vdrop_cell,
"Voltage drop in the cell [V]": phi_s_w_ref
+ param.U_n_ref
+ pot * vdrop_cell,
"Terminal voltage": voltage,
"Terminal voltage [V]": phi_s_w_ref + param.U_n_ref + pot * voltage,
}
