Equivalent circuits

Functions

deareis.parse_cdc(cdc)

Generate a Circuit instance from a string that contains a circuit description code (CDC).

Parameters:

cdc (str) – A circuit description code (CDC) corresponding to an equivalent circuit.

Return type:

Circuit

deareis.register_element(definition, **kwargs)

Register a circuit element so that it is supported by the parse_cdc and get_elements functions. The class definition (symbol, name, etc.) must be provided as keyword arguments.

Parameters:

• definition (ElementDefinition) – An ElementDefinition instance that defines a class, which inherits from the Element class and implements a method called _impedance that takes a float value (i.e., the excitation frequency in hertz) and returns a complex value.

• **kwargs –

Base classes

class deareis.Connection(elements)

Parameters:

elements (List[Element | Connection]) –

append(element_or_connection)

Append an element/connection to this connection.

Parameters:

element_or_connection (Union[Element, Connection]) –

clear()

Remove all elements and/or connections from this connection.

contains(element_or_connection, top_level=False)

Check if this connection contains a specific Element or Connection instance.

Parameters:

• element_or_connection (Union[Element, Connection]) – The Element or Connection instance to check for.

• top_level (bool, optional) – Whether to only check in the current Connection instance instead of also checking in any nested Connection instances.

Return type:

bool

count()

Get the number of elements and/or connections in this connection.

Return type:

int

extend(elements_or_connections)

Extend this connection with a list of elements and/or connections.

Parameters:

elements_or_connections (List[Union[Element, Connection]]) –

generate_element_identifiers(running)

Generate a mapping of elements to their corresponding integer identifiers.

Parameters:

running (bool) – If true, then the identifiers are simply a running count from 0 to N. Primarily intended for use within pyimpspec. If false, then the identifiers represent what number instance of a particular element type an element is (e.g., the second resistor of three resistors would have 2 as its identifier). Primarily intended for use in anything that most users would see (e.g., circuit diagrams and parameter tables).

Return type:

Dict[Element, int]

get_connections(flattened=True)

Get the connections in this connection.

Parameters:

flattened (bool, optional) – Whether or not the connections should be returned as a list of all connections or as a list connections that may also contain more connections.

Return type:

List[Connection]

get_element_name(element, identifiers=None)

Get the name of the element with consideration for any overriding label assigned to the element or the type-specific count in the context of this connection.

Parameters:

• element (Element) – The element whose name should be returned.

• identifiers (Optional[Dict[Element, int]], optional) – The identifiers to use when determining the name of the provided element.

Return type:

str

get_elements(flattened=True)

Get the elements in this circuit.

Parameters:

flattened (bool, optional) – Whether or not the elements should be returned as a list of only elements or as a list of connections containing elements.

Return type:

List[Union[Element, Connection]]

get_impedances(frequencies)

Calculate the impedance of this connection at multiple frequencies.

Parameters:

frequencies (Frequencies) – The excitation frequencies in hertz.

Return type:

ComplexImpedances

index(element_or_connection, start=0, end=-1)

Get the index of an element/connection in this connection.

Parameters:

• element_or_connection (Union[Element, Connection]) –

• start (int, optional) –

• end (int, optional) –

Return type:

int

insert(i, element_or_connection)

Insert an element/connection into position i of this connection.

Parameters:

• i (int) –

• element_or_connection (Union[Element, Connection]) –

pop(i)

Pop the element/connection at position i in this connection.

Parameters:

i (int) –

Return type:

Union[Element, Connection]

remove(element_or_connection)

Remove a specific element/connection from this connection.

Parameters:

element_or_connection (Union[Element, Connection]) –

to_circuitikz(node_width=3.0, node_height=1.5, left_terminal_label='', right_terminal_label='', hide_labels=False, running=False, custom_labels=None)

Get the LaTeX source needed to draw a circuit diagram for this circuit using the CircuiTikZ package.

Parameters:

• node_width (float, optional) – The width of each node.

• node_height (float, optional) – The height of each node.

• left_terminal_label (str, optional) – The label assigned to the terminal representing the working and working sense electrodes.

• right_terminal_label (str, optional) – The label assigned to the terminal representing the counter and reference electrodes.

• hide_labels (bool, optional) – Whether or not to hide element and terminal labels.

• running (bool, optional) – Whether or not to use running counts as the lower indices of elements.

• custom_labels (Optional[Dict[Element, str]], optional) – A mapping of elements to their custom labels that are used instead of the automatically generated labels. The labels can make use of LaTeX’s math mode.

Return type:

str

to_drawing(node_height=1.5, left_terminal_label='', right_terminal_label='', hide_labels=False, running=False, custom_labels=None)

Get a schemdraw.Drawing object for drawing a circuit diagram using, e.g., the matplotlib backend.

Parameters:

• node_height (float, optional) – The height of each node.

• left_terminal_label (str, optional) – The label assigned to the terminal representing the working and working sense electrodes.

• right_terminal_label (str, optional) – The label assigned to the terminal representing the counter and reference electrodes.

• hide_labels (bool, optional) – Whether or not to hide element and terminal labels.

• running (bool, optional) – Whether or not to use running counts as the lower indices of elements.

• custom_labels (Optional[Dict[Element, str]], optional) – A mapping of elements to their custom labels that are used instead of the automatically generated labels. The labels can make use of LaTeX’s math mode.

Return type:

schemdraw.Drawing

to_latex()

Get the equation for the impedance of this connection as a LaTeX-compatible string.

Return type:

str

abstract to_string(decimals=-1)

Generate the circuit description code for this connection.

Parameters:

decimals (int, optional) – The number of decimals used in numeric values.

Return type:

str

abstract to_sympy(substitute=False, identifiers=None)

Get the sympy.Expr object for the impedance of this connection.

Parameters:

• substitute (bool, optional) – Substitute the numeric values for the variables.

• identifiers (Optional[Dict[Element, int]], optional) – A mapping of elements to their identifiers.

Return type:

sympy.Expr

class deareis.Container(**kwargs)

A subclass of Element that adds support for subcircuits.

generate_element_identifiers(running)

Generate a mapping of elements to their corresponding integer identifiers.

Parameters:

running (bool) – If true, then the identifiers are simply a running count from 0 to N. Primarily intended for use within pyimpspec. If false, then the identifiers represent what number instance of a particular element type an element is (e.g., the second resistor of three resistors would have 2 as its identifier). Primarily intended for use in anything that most users would see (e.g., circuit diagrams and parameter tables).

Return type:

Dict[Element, int]

classmethod get_default_subcircuit(key)

Get the default value for a specific subcircuit.

Parameters:

key (str) – A key corresponding to a subcircuit.

Return type:

float

classmethod get_default_subcircuits(*args, **kwargs)

Get the default values for this element’s parameters as a dictionary.

Return type:

Dict[str, Optional[Connection]]

get_subcircuit(key)

Get the current subcircuit matching the given key.

Parameters:

key (str) – A key corresponding to a subcircuit.

Return type:

Optional[Connection]

classmethod get_subcircuit_description(key)

Get the description for a specific subcircuit.

Parameters:

key (str) – String key for a subcircuit.

Return type:

str

classmethod get_subcircuit_descriptions(*args, **kwargs)

Get a dictionary that maps subcircuit keys to their corresponding descriptions.

Parameters:

• *args – String keys corresponding to subcircuits.

• **kwargs – String keys corresponding to subcircuits. The values can be anything.

Return type:

Dict[str, str]

get_subcircuits(*args, **kwargs)

Get a dictionary that maps subcircuit keys to their current values.

Parameters:

• *args – String keys corresponding to subcircuits.

• **kwargs – String keys corresponding to subcircuits. The values can be anything.

Return type:

Dict[str, Optional[Connection]]

classmethod get_unit(key)

Get the unit for a specific parameter or subcircuit.

Parameters:

key (str) – String key for a parameter or subcircuit.

Return type:

str

classmethod get_units(*args, **kwargs)

Get a dictionary that maps parameter and/or subcircuit keys to their corresponding units.

Parameters:

• *args – String keys corresponding to parameters and/or subcircuits.

• **kwargs – String keys corresponding to parameters and/or subcircuits. The values can be anything.

Return type:

Dict[str, str]

set_subcircuits(*args, **kwargs)

Set values for subcircuits.

Parameters:

• *args – Pairs of string keys and numeric values corresponding to subcircuits(e.g., set_subcircuits(“X”, None, “Y”, Series([Resistor()]), “Z”, Series([]))).

• **kwargs – String keys and numeric values corresponding to parameters (e.g., set_values(R=None, Y=Series([Resistor()]), Z=Series([]))).

Return type:

Element

to_string(decimals=-1)

Generates a string representation of the element.

Parameters:

decimals (int, optional) – The number of decimals used when formatting the current value and the limits for the element’s parameters. -1 corresponds to no values being included in the output.

Return type:

str

to_sympy(substitute=False, identifiers=None)

Get the SymPy expression for the impedance of this element.

Parameters:

• substitute (bool, optional) – Substitute the numeric values for the variables.

• identifiers (Optional[Dict[Element, int]], optional) – A mapping of elements to their identifiers.

Return type:

sympy.Expr

class deareis.Element(**kwargs)

The base class for circuit elements. Classes implementing circuit elements should extend this base class and implement the _impedance method (note the underscore). The docstring for the class is generated when the class is registered via the register_element() function.

are_fixed(*args, **kwargs)

Get a dictionary that maps parameter keys to whether or not those parameters currently have fixed values.

Parameters:

• *args – String keys corresponding to parameters.

• **kwargs – String keys corresponding to parameters. The values can be anything.

Return type:

Dict[str, bool]

classmethod are_fixed_by_default(*args, **kwargs)

Get a dictionary that maps parameter keys to whether or not those parameters have fixed values by default.

Parameters:

• *args – String keys corresponding to parameters.

• **kwargs – String keys corresponding to parameters. The values can be anything.

Return type:

Dict[str, bool]

classmethod get_default_lower_limit(key)

Get the default lower limit for a specific parameter.

Parameters:

key (str) – A key corresponding to a parameter.

Return type:

float

classmethod get_default_lower_limits(*args, **kwargs)

Get a dictionary that maps parameter keys to their default lower limits.

Parameters:

• *args – String keys corresponding to parameters.

• **kwargs – String keys corresponding to parameters. The values can be anything.

Return type:

Dict[str, float]

classmethod get_default_upper_limit(key)

Get the default upper limit for a specific parameter.

Parameters:

key (str) – A key corresponding to a parameter.

Return type:

float

classmethod get_default_upper_limits(*args, **kwargs)

Get a dictionary that maps parameter keys to their default upper limits.

Parameters:

• *args – String keys corresponding to parameters.

• **kwargs – String keys corresponding to parameters. The values can be anything.

Return type:

Dict[str, float]

classmethod get_default_value(key)

Get the default value for a specific parameter.

Parameters:

key (str) – A key corresponding to a parameter.

Return type:

float

classmethod get_default_values(*args, **kwargs)

Get the default values for this element’s parameters as a dictionary.

Return type:

Dict[str, float]

classmethod get_description()

Get a brief description of this element.

Return type:

str

classmethod get_extended_description()

Get an extended description of this element.

Return type:

str

get_impedances(frequencies)

Calculate the impedance of this element at multiple frequencies.

Parameters:

frequencies (Frequencies) – The excitation frequencies in hertz.

Return type:

ComplexImpedances

get_label()

Get the label assigned to a specific instance of the element.

Return type:

str

get_lower_limit(key)

Get the current lower limit for a specific parameter.

Parameters:

key (str) – A key corresponding to a parameter.

Return type:

float

get_lower_limits(*args, **kwargs)

Get a dictionary that maps parameter keys to their current lower limits.

Parameters:

• *args – String keys corresponding to parameters.

• **kwargs – String keys corresponding to parameters. The values can be anything.

Return type:

Dict[str, float]

get_name()

Get the display name for this element, which consists of the element’s symbol and its optional label.

Return type:

str

classmethod get_symbol()

Get the symbol for this element. The symbol is used to represent this type of element in a circuit description code.

Return type:

str

classmethod get_unit(key)

Get the unit for a specific parameter.

Parameters:

key (str) – String key for a parameter.

Return type:

str

classmethod get_units(*args, **kwargs)

Get a dictionary that maps parameter keys to their corresponding units.

Parameters:

• *args – String keys corresponding to parameters.

• **kwargs – String keys corresponding to parameters. The values can be anything.

Return type:

Dict[str, str]

get_upper_limit(key)

Get the current upper limit for a specific parameter.

Parameters:

key (str) – A key corresponding to a parameter.

Return type:

float

get_upper_limits(*args, **kwargs)

Get a dictionary that maps parameter keys to their current upper limits.

Parameters:

• *args – String keys corresponding to parameters.

• **kwargs – String keys corresponding to parameters. The values can be anything.

Return type:

Dict[str, float]

get_value(key)

Get the current value for a specific parameter.

Parameters:

key (str) – A key corresponding to a parameter.

Return type:

float

classmethod get_value_description(key)

Get the description for a specific parameter.

Parameters:

key (str) – String key for a parameter.

Return type:

str

classmethod get_value_descriptions(*args, **kwargs)

Get a dictionary that maps parameter keys to their corresponding descriptions.

Parameters:

• *args – String keys corresponding to parameters.

• **kwargs – String keys corresponding to parameters. The values can be anything.

Return type:

Dict[str, str]

get_values(*args, **kwargs)

Get a dictionary that maps parameter keys to their current values.

Parameters:

• *args – String keys corresponding to parameters.

• **kwargs – String keys corresponding to parameters. The values can be anything.

Return type:

Dict[str, float]

is_fixed(key)

Get whether or not a specific parameter currently has a fixed value.

Parameters:

key (str) – A key corresponding to a parameter.

Return type:

bool

classmethod is_fixed_by_default(key)

Get whether or not a specific parameter has a fixed value by default.

Parameters:

key (str) – A key corresponding to a parameter.

Return type:

bool

reset_parameter(key)

Resets the value, lower limit, upper limit, and fixed state of one parameter.

Parameters:

key (str) – A string key corresponding to a parameter.

reset_parameters(*args, **kwargs)

Resets the value, lower limit, upper limit, and fixed state of one or more parameters.

Parameters:

• *args – One or more string keys corresponding to parameters.

• **kwargs – String keys corresponding to parameters. The values can be anything.

set_fixed(*args, **kwargs)

Set parameters to have fixed values.

Parameters:

• *args – Pairs of string keys and boolean values corresponding to parameters (e.g., set_fixed(“R”, True, “Y”, False)).

• **kwargs – String keys and boolean values corresponding to parameters (e.g., set_fixed(R=True, Y=False)).

Return type:

Element

set_label(label)

Set the label assigned to a specific instance of the element.

Parameters:

label (str) – The new label.

Return type:

Element

set_lower_limits(*args, **kwargs)

Set lower limits for parameters.

Parameters:

• *args – Pairs of string keys and numeric values corresponding to parameters (e.g., set_lower_limits(“R”, 1.0, “Y”, 1e-9)).

• **kwargs – String keys and numeric values corresponding to parameters (e.g., set_lower_limits(R=1.0, Y=1e-9))..

Return type:

Element

set_upper_limits(*args, **kwargs)

Set upper limits for parameters.

Parameters:

• *args – Pairs of string keys and numeric values corresponding to parameters (e.g., set_upper_limits(“R”, 1.0, “Y”, 1e-9)).

• **kwargs – String keys and numeric values corresponding to parameters (e.g., set_upper_limits(R=1.0, Y=1e-9)).

Return type:

Element

set_values(*args, **kwargs)

Set values for parameters.

Parameters:

• *args – Pairs of string keys and numeric values corresponding to parameters (e.g., set_values(“R”, 1.0, “Y”, 1e-9)).

• **kwargs – String keys and numeric values corresponding to parameters (e.g., set_values(R=1.0, Y=1e-9)).

Return type:

Element

to_latex()

Get the equation for the impedance of this element as a LaTeX-compatible string.

Return type:

str

to_string(decimals=-1)

Generates a string representation of the element.

Parameters:

decimals (int, optional) – The number of decimals used when formatting the current value and the limits for the element’s parameters. -1 corresponds to no values being included in the output.

Return type:

str

to_sympy(substitute=False, identifier=-1)

Get the sympy.Expr object for the impedance of this element.

Parameters:

• substitute (bool, optional) – Substitute the numeric values for the variables.

• identifier (int, optional) – The identifier of the element.

Return type:

sympy.Expr

Connection classes

class deareis.Parallel(elements)

Elements connected in parallel.

Parameters:

elements (List[Union[Element, Connection]]) – List of elements (and connections) that are connected in parallel.

to_string(decimals=-1)

Generate the circuit description code for this connection.

Parameters:

decimals (int, optional) – The number of decimals used in numeric values.

Return type:

str

to_sympy(substitute=False, identifiers=None)

Get the sympy.Expr object for the impedance of this connection.

Parameters:

• substitute (bool, optional) – Substitute the numeric values for the variables.

• identifiers (Optional[Dict[Element, int]], optional) – A mapping of elements to their identifiers.

Return type:

sympy.Expr

class deareis.Series(elements)

Elements connected in series.

Parameters:

elements (List[Union[Element, Connection]]) – List of elements (and connections) that are connected in series.

to_string(decimals=-1)

Generate the circuit description code for this connection.

Parameters:

decimals (int, optional) – The number of decimals used in numeric values.

Return type:

str

to_sympy(substitute=False, identifiers=None)

Get the sympy.Expr object for the impedance of this connection.

Parameters:

• substitute (bool, optional) – Substitute the numeric values for the variables.

• identifiers (Optional[Dict[Element, int]], optional) – A mapping of elements to their identifiers.

Return type:

sympy.Expr

Circuit classes

class deareis.Circuit(elements)

A class that represents an equivalent circuit.

Parameters:

elements (Series) – The elements of the circuit wrapped in a Series connection.

generate_element_identifiers(running)

Generate a mapping of elements to their corresponding integer identifiers.

Parameters:

running (bool) – If true, then the identifiers are simply a running count from 0 to N. Primarily intended for use within pyimpspec. If false, then the identifiers represent what number instance of a particular element type an element is (e.g., the second resistor of three resistors would have 2 as its identifier). Primarily intended for use in anything that most users would see (e.g., circuit diagrams and parameter tables).

Return type:

Dict[Element, int]

get_connections(flattened=True)

Get the connections in this circuit.

Parameters:

flattened (bool, optional) – Whether or not the connections should be returned as a list of all connections or as a list connections that may also contain more connections.

Return type:

List[Connection]

get_element_name(element, identifiers=None)

Get the name of the element with consideration for any overriding label assigned to the element or the type-specific count in the context of this circuit.

Parameters:

• element (Element) – The element whose name should be returned.

• identifiers (Optional[Dict[Element, int]], optional) – The identifiers to use when determining the name of the provided element.

Return type:

str

get_elements(flattened=True)

Get the elements in this circuit.

Parameters:

flattened (bool, optional) – Whether or not the elements should be returned as a list of only elements or as a list of connections containing elements.

Return type:

List[Union[Element, Connection]]

get_impedances(frequencies)

Calculate the impedance of this circuit at multiple frequencies.

Parameters:

frequencies (Frequencies) – The excitation frequencies in hertz.

Return type:

ComplexImpedances

to_circuitikz(node_width=3.0, node_height=1.5, left_terminal_label='', right_terminal_label='', hide_labels=False, running=False, custom_labels=None)

Get the LaTeX source needed to draw a circuit diagram for this circuit using the CircuiTikZ package.

Parameters:

• node_width (float, optional) – The width of each node.

• node_height (float, optional) – The height of each node.

• left_terminal_label (str, optional) – The label assigned to the terminal representing the working and working sense electrodes.

• right_terminal_label (str, optional) – The label assigned to the terminal representing the counter and reference electrodes.

• hide_labels (bool, optional) – Whether or not to hide element and terminal labels.

• running (bool, optional) – Whether or not to use running counts as the lower indices of elements.

• custom_labels (Optional[Dict[Element, str]], optional) – A mapping of elements to their custom labels that are used instead of the automatically generated labels. The labels can make use of LaTeX’s math mode.

Return type:

str

to_drawing(node_height=1.5, left_terminal_label='', right_terminal_label='', hide_labels=False, running=False, custom_labels=None)

Get a schemdraw.Drawing object for drawing a circuit diagram using, e.g., the matplotlib backend.

Parameters:

• node_height (float, optional) – The height of each node.

• left_terminal_label (str, optional) – The label assigned to the terminal representing the working and working sense electrodes.

• right_terminal_label (str, optional) – The label assigned to the terminal representing the counter and reference electrodes.

• hide_labels (bool, optional) – Whether or not to hide element and terminal labels.

• running (bool, optional) – Whether or not to use running counts as the lower indices of elements.

• custom_labels (Optional[Dict[Element, str]], optional) – A mapping of elements to their custom labels that are used instead of the automatically generated labels. The labels can make use of LaTeX’s math mode.

Return type:

schemdraw.Drawing

to_latex()

Get the LaTeX math expression corresponding to this circuit’s impedance.

Return type:

str

to_string(decimals=-1)

Generate the circuit description code (CDC) that represents this circuit.

Parameters:

decimals (int, optional) – The number of decimals to include for the current element parameter values and limits. -1 means that the CDC is generated using the basic syntax, which omits element labels, parameter values, and parameter limits.

Return type:

str

to_sympy(substitute=False)

Get the sympy.Expr object corresponding to this circuit’s impedance.

Parameters:

substitute (bool, optional) – Whether or not the variables should be substituted with the current values.

Return type:

sympy.Expr

class deareis.CircuitBuilder(parallel=False)

A class for building circuits using context managers.

Parameters:

parallel (bool = False) – Whether or not this context/connection is a parallel connection.

add(element)

Add an element to the current context (i.e., connection).

Parameters:

element (Element) – The element to add to the current series or parallel connection.

parallel()

Create a parallel connection.

Return type:

CircuitBuilder

series()

Create a series connection.

Return type:

CircuitBuilder

to_circuit()

Generate a circuit.

Return type:

Circuit

to_string(decimals=-1)

Generate a circuit description code.

Parameters:

decimals (int = -1) – The number of decimals to include for the current element parameter values and limits. -1 means that the CDC is generated using the basic syntax, which omits element labels, parameter values, and parameter limits.

Return type:

str

Element classes

class deareis.api.circuit.elements.Capacitor(**kwargs)

Symbol: C

An ideal capacitor.

\(Z = \frac{1}{2 j \pi C f}\)

Parameters:

C (float = 1e-06 F) – Capacitance

class deareis.api.circuit.elements.ConstantPhaseElement(**kwargs)

Constant phase element

Symbol: Q

Can be used to model, e.g., non-ideal capacitance.

\(Z = \frac{1}{Y \left(2 j \pi f\right)^{n}}\)

Parameters:

• Y (float = 1e-06 S*s^n) – ‘Admittance’

• n (float = 0.95) – Phase angle in -pi/2 radians

class deareis.api.circuit.elements.DeLevieFiniteLength(**kwargs)

de Levie

Symbol: Ls

Can be used to model porous electrodes.

\(Z = \frac{\sqrt{R_{i} R_{r}} \coth{\left(d \sqrt{\frac{R_{i}}{R_{r}}} \sqrt{Y \left(2 j \pi f\right)^{n} + 1} \right)}}{\sqrt{Y \left(2 j \pi f\right)^{n} + 1}}\)

Parameters:

• R_i (float = 10 ohm/cm) – Ionic resistance

• R_r (float = 1 ohm*cm) – Faradaic reaction resistance

• Y (float = 0.01 S*s^n/cm) – ‘Admittance’

• n (float = 0.8) – Phase angle in -pi/2 radians

• d (float = 0.2 cm) – Electrode thickness

class deareis.api.circuit.elements.Gerischer(**kwargs)

Symbol: G

The impedance associated with an electroactive species that is created by a reaction in the electrolyte solution.

\(Z = \frac{1}{Y \left(j 2 \pi f + k\right)^{n}}\)

Parameters:

• Y (float = 1 S*s^n) – ‘Admittance’

• k (float = 1 s^-1) – ‘Rate constant’

• n (float = 0.5, fixed) –

class deareis.api.circuit.elements.HavriliakNegami(**kwargs)

Havriliak-Negami

Symbol: H

Havriliak-Negami, Cole-Davidson (a = 1), Cole-Cole (b = 1), or Debye (a = b = 1) relaxation.

\(Z = \frac{\left(\left(j 2 \pi f \tau\right)^{a} + 1\right)^{b}}{2 j \pi dC f}\)

Parameters:

• dC (float = 1e-06 F) – Difference in capacitance

• tau (float = 1 s) – Time constant

• a (float = 0.9) – Asymmetry exponent

• b (float = 0.9) – Broadness exponent

class deareis.api.circuit.elements.HavriliakNegamiAlternative(**kwargs)

Havriliak-Negami, alt.

Symbol: Ha

Havriliak-Negami relaxation (alternative form).

\(Z = \frac{R}{\left(\left(j 2 \pi f \tau\right)^{a} + 1\right)^{b}}\)

Parameters:

• R (float = 1 ohm) – Resistance

• tau (float = 1 s) – Time constant

• a (float = 0.7) – Asymmetry exponent

• b (float = 0.8) – Broadness exponent

class deareis.api.circuit.elements.Inductor(**kwargs)

Ideal inductor

Symbol: L

An ideal inductor.

\(Z = j 2 \pi f L\)

Parameters:

L (float = 1e-06 H) – Inductance

class deareis.api.circuit.elements.KramersKronigRC(**kwargs)

‘Parallel RC’ element

Symbol: K

Parallel RC element with a fixed time constant that is used in linear Kramers-Kronig tests.

\(Z = \frac{R}{j 2 \pi f \tau + 1}\)

Parameters:

• R (float = 1 ohm) – Resistance

• tau (float = 1 s, fixed) – Time constant

class deareis.api.circuit.elements.ModifiedInductor(**kwargs)

Modified inductor

Symbol: La

Can be used to model non-ideal inductance.

\(Z = L \left(j 2 \pi f\right)^{n}\)

Parameters:

• L (float = 1e-06 H*s^(n-1)) – ‘Inductance’

• n (float = 0.95) – Phase angle in pi/2 radians

class deareis.api.circuit.elements.Resistor(**kwargs)

Symbol: R

An ideal resistor.

\(Z = R\)

Parameters:

R (float = 1e+03 ohm) – Resistance

class deareis.api.circuit.elements.TransmissionLineModel(**kwargs)

Transmission line model, general

Symbol: Tlm

A general model for a transmission line. The units of the subcircuits’ parameters vary depending on the connections. Note the pore length parameter, L, for this element and how it may affect the aforementioned units. The equation that is used depends on the configuration of subcircuits that have been chosen. See DOI:10.1039/B001708F for more information about this element.

Parameters:

• L (float = 1 m, fixed) – Pore length

• X_1 (Optional[Connection] = [R]) – The impedance of the liquid phase (i.e., ionic conductivity in the pore)

• X_2 (Optional[Connection] = []) – The impedance of the solid phase (i.e., electronic conductivity of the film)

• Z_A (Optional[Connection] = None) – The impedance at the outer boundary of the porous electrode (i.e., at the electrolyte-film interface outside of the pore)

• Z_B (Optional[Connection] = None) – The impedance at the inner boundary of the porous electrode (i.e., at the electrolyte-substrate interface in the pore)

• Zeta (Optional[Connection] = [Q]) – The interfacial impedance (i.e., at the electrolyte-film interface of the pore wall)

class deareis.api.circuit.elements.TransmissionLineModelBlockingCPE(**kwargs)

Blocking porous electrode, CPE

Symbol: Tlmbq

Transmission line, blocking porous electrode with reflective inner boundary. Model (d) in DOI:10.1039/B001708F.

\(Z = \frac{R_{i} \left(1 + \frac{\left(j 2 \pi f \frac{1}{\frac{1}{\left(L^{2} R_{i} Y\right)^{1 \cdot \frac{1}{n}}}}\right)^{\frac{n}{2}} \coth{\left(\left(j 2 \pi f \frac{1}{\frac{1}{\left(L^{2} R_{i} Y\right)^{1 \cdot \frac{1}{n}}}}\right)^{\frac{n}{2}} \right)}}{R_{i} Y_{B} \left(j 2 \pi f\right)^{n_{B}}}\right)}{\left(j 2 \pi f \frac{1}{\frac{1}{\left(L^{2} R_{i} Y\right)^{1 \cdot \frac{1}{n}}}}\right)^{\frac{n}{2}} \coth{\left(\left(j 2 \pi f \frac{1}{\frac{1}{\left(L^{2} R_{i} Y\right)^{1 \cdot \frac{1}{n}}}}\right)^{\frac{n}{2}} \right)} + \frac{\left(j 2 \pi f \frac{1}{\frac{1}{\left(L^{2} R_{i} Y\right)^{1 \cdot \frac{1}{n}}}}\right)^{n}}{R_{i} Y_{B} \left(j 2 \pi f\right)^{n_{B}}}}\)

Parameters:

• R_i (float = 1 ohm/m) – Ionic resistance

• Y (float = 0.005 S*s^n/m) – Interfacial ‘admittance’

• n (float = 0.8) – Phase angle in -pi/2 radians (interface)

• Y_B (float = 0.01 S*s^n/m) – Inner boundary ‘admittance’

• n_B (float = 0.7) – Phase angle in -pi/2 radians (inner boundary)

• L (float = 1 m, fixed) – Pore length

class deareis.api.circuit.elements.TransmissionLineModelBlockingOpen(**kwargs)

Blocking porous electrode, open

Symbol: Tlmbo

Transmission line, blocking porous electrode with perfectly reflective inner boundary. Model (b) in DOI:10.1039/B001708F.

\(Z = R_{i} \left(j 2 \pi f \frac{1}{\frac{1}{\left(L^{2} R_{i} Y\right)^{1 \cdot \frac{1}{n}}}}\right)^{\frac{\left(-1\right) n}{2}} \coth{\left(\left(j 2 \pi f \frac{1}{\frac{1}{\left(L^{2} R_{i} Y\right)^{1 \cdot \frac{1}{n}}}}\right)^{\frac{n}{2}} \right)}\)

Parameters:

• R_i (float = 1 ohm/m) – Ionic resistance

• Y (float = 0.005 S*s^n/m) – Interfacial ‘admittance’

• n (float = 0.8) – Phase angle in -pi/2 radians (interface)

• L (float = 1 m, fixed) – Pore length

class deareis.api.circuit.elements.TransmissionLineModelBlockingShort(**kwargs)

Blocking porous electrode, short

Symbol: Tlmbs

Transmission line, blocking porous electrode with absorbing inner boundary. Model (d) in DOI:10.1039/B001708F with a shorted Z_B (i.e., Z_B == 0).

\(Z = \frac{R_{i}}{\left(j 2 \pi f \frac{1}{\frac{1}{\left(L^{2} R_{i} Y\right)^{1 \cdot \frac{1}{n}}}}\right)^{\frac{n}{2}} \coth{\left(\left(j 2 \pi f \frac{1}{\frac{1}{\left(L^{2} R_{i} Y\right)^{1 \cdot \frac{1}{n}}}}\right)^{\frac{n}{2}} \right)}}\)

Parameters:

• R_i (float = 1 ohm/m) – Ionic resistance

• Y (float = 0.005 S*s^n/m) – Interfacial ‘admittance’

• n (float = 0.8) – Phase angle in -pi/2 radians (interface)

• L (float = 1 m, fixed) – Pore length

class deareis.api.circuit.elements.TransmissionLineModelNonblockingCPE(**kwargs)

Non-blocking porous electrode, CPE

Symbol: Tlmnq

Transmission line, non-blocking porous electrode with reflective inner boundary. Model (g) in DOI:10.1039/B001708F.

\(Z = \frac{R_{ct} \left(R_{B} \coth{\left(\frac{L}{\sqrt{\frac{R_{ct}}{R_{i} \left(R_{ct} Y \left(j 2 \pi f\right)^{n} + 1\right)}}} \right)} + R_{i} \sqrt{\frac{R_{ct}}{R_{i} \left(R_{ct} Y \left(j 2 \pi f\right)^{n} + 1\right)}} \left(R_{B} Y_{B} \left(j 2 \pi f\right)^{n_{B}} + 1\right)\right)}{R_{B} \sqrt{\frac{R_{ct}}{R_{i} \left(R_{ct} Y \left(j 2 \pi f\right)^{n} + 1\right)}} \left(R_{ct} Y \left(j 2 \pi f\right)^{n} + 1\right) + R_{ct} \left(R_{B} Y_{B} \left(j 2 \pi f\right)^{n_{B}} + 1\right) \coth{\left(\frac{L}{\sqrt{\frac{R_{ct}}{R_{i} \left(R_{ct} Y \left(j 2 \pi f\right)^{n} + 1\right)}}} \right)}}\)

Parameters:

• R_i (float = 1 ohm/m) – Ionic resistance

• R_ct (float = 3 ohm*m) – Interfacial charge transfer resistance

• Y (float = 0.005 S*s^n/m) – Interfacial ‘admittance’

• n (float = 0.8) – Phase angle in -pi/2 radians (interface)

• R_B (float = 5 ohm*m) – Inner boundary charge transfer resistance

• Y_B (float = 0.1 S*s^n/m) – Inner boundary ‘admittance’

• n_B (float = 0.7) – Phase angle in -pi/2 radians (inner boundary)

• L (float = 1 m, fixed) – Pore length

class deareis.api.circuit.elements.TransmissionLineModelNonblockingOpen(**kwargs)

Non-blocking porous electrode, open

Symbol: Tlmno

Transmission line, non-blocking porous electrode with perfectly reflective inner boundary. Also known as ‘Bisquert, open’. Model (f) in DOI:10.1039/B001708F with corrected form from DOI:10.1021/jp993148h.

\(Z = \left(\frac{R_{ct} R_{i}}{\left(j 2 \pi f \frac{1}{\frac{1}{\left(R_{ct} Y\right)^{1 \cdot \frac{1}{n}}}}\right)^{n} + 1}\right)^{1 \cdot \frac{1}{2}} \coth{\left(\left(\frac{1}{\left(\frac{R_{ct} Y}{L}\right)^{1 \cdot \frac{1}{n}} \frac{1}{\left(L^{2} R_{i} Y\right)^{1 \cdot \frac{1}{n}}}}\right)^{\frac{n}{2}} \left(\left(j 2 \pi f \frac{1}{\frac{1}{\left(R_{ct} Y\right)^{1 \cdot \frac{1}{n}}}}\right)^{n} + 1\right)^{1 \cdot \frac{1}{2}} \right)}\)

Parameters:

• R_i (float = 1 ohm/m) – Ionic resistance

• R_ct (float = 3 ohm*m) – Interfacial charge transfer resistance

• Y (float = 0.005 S*s^n/m) – Interfacial ‘admittance’

• n (float = 0.8) – Phase angle in -pi/2 radians (interface)

• L (float = 1 m, fixed) – Pore length

class deareis.api.circuit.elements.TransmissionLineModelNonblockingShort(**kwargs)

Non-blocking porous electrode, short

Symbol: Tlmns

Transmission line, non-blocking porous electrode with absorbing inner boundary. Also known as ‘Bisquert, short’. Model (g) in DOI:10.1039/B001708F with a shorted Z_B (i.e., Z_B == 0).

\(Z = R_{i} \sqrt{\frac{R_{ct}}{R_{i} \left(R_{ct} Y \left(j 2 \pi f\right)^{n} + 1\right)}} \tanh{\left(\frac{L}{\sqrt{\frac{R_{ct}}{R_{i} \left(R_{ct} Y \left(j 2 \pi f\right)^{n} + 1\right)}}} \right)}\)

Parameters:

• R_i (float = 1 ohm/m) – Ionic resistance

• R_ct (float = 3 ohm*m) – Interfacial charge transfer resistance

• Y (float = 0.005 S*s^n/m) – Interfacial ‘admittance’

• n (float = 0.8) – Phase angle in -pi/2 radians (interface)

• L (float = 1 m, fixed) – Pore length

class deareis.api.circuit.elements.Warburg(semi-infinite)

Symbol: W

Semi-infinite Warburg diffusion.

\(Z = \frac{1}{Y \sqrt{2 j \pi f}}\)

where \(Y = \frac{1}{\sigma\sqrt{2}}\) and \(\sigma\) is the Warburg coefficient in ohm/s^(1/2).

Parameters:

Y (float = 0.001 S*s^(1/2)) – ‘Admittance’

class deareis.api.circuit.elements.WarburgOpen(**kwargs)

Warburg (finite length, reflective boundary)

Symbol: Wo

Finite length diffusion with reflective boundary.

\(Z = \frac{\coth{\left(\left(B j 2 \pi f\right)^{n} \right)}}{\left(Y j 2 \pi f\right)^{n}}\)

where

• \(Y = \frac{1}{\sigma\sqrt{2}}\) and \(\sigma\) is the Warburg coefficient in ohm/s^(1/2)

• \(B = \frac{\delta}{\sqrt{D}}\), \(\delta\) is the diffusion layer thickness, and \(D\) is the diffusion coefficient

Re(Z) approaches \(\frac{(B/Y)^n}{3}\) and Im(Z) exhibits capacitive-like behavior as the frequency approaches 0 Hz.

Parameters:

• Y (float = 1 S) – ‘Admittance’

• B (float = 1 s^n) – ‘Time constant’

• n (float = 0.5, fixed) – Phase angle in -pi/2 radians

class deareis.api.circuit.elements.WarburgShort(**kwargs)

Warburg (finite length, transmissive boundary)

Symbol: Ws

Finite length diffusion with transmissive boundary.

\(Z = \frac{\tanh{\left(\left(B j 2 \pi f\right)^{n} \right)}}{\left(Y j 2 \pi f\right)^{n}}\)

where

• \(Y = \frac{1}{\sigma\sqrt{2}}\) and \(\sigma\) is the Warburg coefficient in ohm/s^(1/2)

• \(B = \frac{\delta}{\sqrt{D}}\), \(\delta\) is the diffusion layer thickness, and \(D\) is the diffusion coefficient

Re(Z) and Im(Z) approach \((\frac{B}{Y})^n\) and 0, respectively, as the frequency approaches 0 Hz.

Parameters:

• Y (float = 1 S) – ‘Admittance’

• B (float = 1 s^n) – ‘Time constant’

• n (float = 0.5, fixed) – Phase angle in -pi/2 radians

Element registration classes

class deareis.ContainerDefinition(Class, symbol, name, description, equation, parameters, subcircuits)

A class that defines a new circuit element and its parameters. The information contained in this object is also used to automatically generate a docstring for the circuit element’s class.

Parameters:

• Class (Type[Element]) – The class representing the circuit element.

• symbol (str) – The symbol that can be used to represent the circuit element in a circuit description code (CDC).

• name (str) – The name of the circuit element.

• description (str) – The description of the element. A placeholder, |equation|, for the automatically formatted equation can be included in the description in case the intention is to have more text below the equation. Otherwise the formatted equation will be added to the end of the description. Another placeholder, |no-equation|, can be included (e.g., at the end) in case the automatically formatted equation should be excluded for some reason (e.g., it would be too large to be properly displayed).

• equation (str) – The equation (assume an implicit “Z = “ on the left-hand side) for the circuit element’s impedance. The string must be compatible with SymPy’s sympify function. For example, “(2*pi*f*C*I)^-1” for a capacitor is valid and will show up in the generated docstring as \(Z = \frac{1}{j 2 \pi f C}\). This is also used to verify that the circuit element’s _impedance method outputs the same answer as the circuit element’s impedance equation.

• parameters (List[ParameterDefinition]) – A list of objects that define the circuit element’s parameter(s).

• subcircuits (List[SubcircuitDefinition]) –

subcircuits: List[SubcircuitDefinition]

A list of objects that define the circuit element’s parameter(s) that are subcircuits.

class deareis.ElementDefinition(Class, symbol, name, description, equation, parameters)

A class that defines a new circuit element and its parameters. The information contained in this object is also used to automatically generate a docstring for the circuit element’s class.

Parameters:

• Class (Type[Element]) – The class representing the circuit element.

• symbol (str) – The symbol that can be used to represent the circuit element in a circuit description code (CDC).

• name (str) – The name of the circuit element.

• description (str) – The description of the element. A placeholder, |equation|, for the automatically formatted equation can be included in the description in case the intention is to have more text below the equation. Otherwise the formatted equation will be added to the end of the description. Another placeholder, |no-equation|, can be included (e.g., at the end) in case the automatically formatted equation should be excluded for some reason (e.g., it would be too large to be properly displayed).

• equation (str) – The equation (assume an implicit “Z = “ on the left-hand side) for the circuit element’s impedance. The string must be compatible with SymPy’s sympify function. For example, “(2*pi*f*C*I)^-1” for a capacitor is valid and will show up in the generated docstring as \(Z = \frac{1}{j 2 \pi f C}\). This is also used to verify that the circuit element’s _impedance method outputs the same answer as the circuit element’s impedance equation.

• parameters (List[ParameterDefinition]) – A list of objects that define the circuit element’s parameter(s).

class deareis.ParameterDefinition(symbol, unit, description, value, lower_limit, upper_limit, fixed)

A circuit element’s parameter.

Parameters:

• symbol (str) – The symbol/name of the parameter that can be used when, e.g., obtaining the value for a specific parameter via Element.get_value(symbol). Required to be a non-empty string.

• unit (str) – The parameter’s unit (ohm*cm, F/cm, H, etc.). Can be an empty string.

• description (str) – A description of the parameter. Can be an empty string.

• value (float) – The default value for the parameter.

• lower_limit (float) – The lower limit of what this parameter’s value can be during circuit fitting. A value of -numpy.inf means that there is no lower limit.

• upper_limit (float) – The upper limit of what this parameter’s value can be during circuit fitting. A value of numpy.inf means that there is no upper limit.

• fixed (bool) – If true, then this parameter’s value will not change during circuit fitting.

class deareis.SubcircuitDefinition(symbol, unit, description, value)

A container element’s subcircuit.

Parameters:

• symbol (str) – The symbol/name of the subcircuit that can be used when, e.g., obtaining a specific subcircuit belonging to a container element. Required to be a non-empty string.

• unit (str) – The unit of the subcircuit’s impedance.

• description (str) – A description of the subcircuit. Can be an empty string.

• value (Optional[Connection]) – The default value for the parameter. Can be a connection such as Series or Parallel, or None.