Equivalent circuits
A collection of functions and classes for creating equivalent circuits and user-defined elements.
Functions
- pyimpspec.get_elements(default_only=False, private=False)
Returns a dictionary that maps element symbols to their corresponding classes.
- Parameters:
default_only (bool, optional) – Return only the elements that are included by default in pyimpspec (i.e., exclude user-defined elements).
private (bool, optional) – Include elements that have been marked as private.
- Return type:
Dict[str, Type[
Element
]]
- pyimpspec.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:
- pyimpspec.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
- pyimpspec.simulate_spectrum(circuit, frequencies=None, label='')
Simulate the impedance spectrum generated by a circuit in a certain frequency range.
- Parameters:
circuit (
Circuit
) – The circuit to use when calculating impedances at various frequencies.frequencies (Optional[
Frequencies
], optional) – Excitation frequencies in hertz. If no frequencies are provided, then a frequency range of 10 mHz to 100 kHz with 10 points per decade will be used.label (str, optional) – The label for the DataSet that is returned.
- Return type:
- pyimpspec.circuit.registry.remove_elements(elements)
Remove a specific user-defined element from the registry.
- pyimpspec.circuit.registry.reset(elements=True, default_parameters=True)
Remove all user-defined elements from the registry.
- Parameters:
elements (bool, optional) – If true, then remove any user-defined elements.
default_parameters (bool, optional) – If true, reset the default parameters of all elements.
- pyimpspec.circuit.registry.reset_default_parameter_values(elements=None)
Reset the default values for parameters of one or more elements.
Base classes
- class pyimpspec.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(recursive=True)
Get the connections in this connection.
- Parameters:
recursive (bool, optional) – If True and this Connection contains other Connection instances, then all nested Connect instances are returned. If False, then only the Connection instances within the top level of this Connection are returned.
- 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.
- get_elements(recursive=True)
Get the elements in this connection.
- Parameters:
recursive (bool, optional) – If True and this Connection contains other Connection instances, then all nested elements are returned. If False, then only the Element instances within the top level of this Connection are returned.
- Return type:
List[Element]
- get_impedances(frequencies)
Calculate the impedance of this connection at multiple frequencies.
- Parameters:
frequencies (
Frequencies
) – The excitation frequencies in hertz.- Return type:
- 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, canvas=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.canvas (Optional[Union[str, Axes]], optional) – The canvas that the _schemdraw.Drawing class should use.
- Return type:
- 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:
- class pyimpspec.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:
- 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:
- class pyimpspec.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 theregister_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:
- 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.
- classmethod set_default_values(*args, **kwargs)
Set the default values for this element’s 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)).
- 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:
- set_label(label)
Set the label assigned to a specific instance of the element.
- Parameters:
label (str) – The new label.
- Return type:
- set_lower_limits(*args, **kwargs)
Set lower limits for parameters. Lower limits are used during circuit fitting.
- 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:
- set_upper_limits(*args, **kwargs)
Set upper limits for parameters. Upper limits are used during circuit fitting.
- 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:
- 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:
- 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:
Connection classes
- class pyimpspec.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:
- class pyimpspec.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:
Circuit classes
- class pyimpspec.Circuit(elements)
A class that represents an equivalent circuit.
- Parameters:
elements (Union[List[Element], Element, Series, Parallel]) – The elements of the circuit.
- 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(recursive=True)
Get the connections in this circuit.
- Parameters:
recursive (bool, optional) – If True and this Circuit contains nested Connection instances, then all of them are returned. If False, then only the top-level Connection is returned.
- 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.
- get_elements(recursive=True)
Get the elements in this circuit.
- Parameters:
recursive (bool, optional) – If True and there are Element instances nested within Connection instances, then all Element instances are returned. If False, then only the Element instances within the top-level Connection are returned.
- Return type:
List[Element]
- get_impedances(frequencies)
Calculate the impedance of this circuit at multiple frequencies.
- Parameters:
frequencies (
Frequencies
) – The excitation frequencies in hertz.- Return type:
- 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, canvas=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.canvas (Optional[Union[str, Axes]], optional) – The canvas that the _schemdraw.Drawing class should use.
- Return type:
- 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:
- class pyimpspec.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:
- series()
Create a series connection.
- Return type:
- 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 pyimpspec.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 pyimpspec.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 pyimpspec.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 pyimpspec.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 pyimpspec.circuit.elements.GerischerAlternative(**kwargs)
Gerischer, alt.
Symbol: Ga
The impedance associated with an electroactive species that is created by a reaction in the electrolyte solution (alternative form).
\(Z = \frac{R}{\left(j 2 \pi f \tau + 1\right)^{n}}\)
- Parameters:
R (float = 1 ohm) – Resistance
tau (float = 1 s) – Time constant
n (float = 0.5, fixed)
- class pyimpspec.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 pyimpspec.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 pyimpspec.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 pyimpspec.circuit.elements.KramersKronigAdmittanceRC(**kwargs)
‘Series RC’ element
Symbol: Ky
Series RC element with a fixed time constant that is used in linear Kramers-Kronig tests on admittance data.
\(Z = 1 \frac{1}{2 \pi C f \frac{1}{2 \pi f \tau - j}}\)
- Parameters:
C (float = 1 F) – Capacitance
tau (float = 1 s, fixed) – Time constant
- class pyimpspec.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 on impedance data.
\(Z = \frac{R}{j 2 \pi f \tau + 1}\)
- Parameters:
R (float = 1 ohm) – Resistance
tau (float = 1 s, fixed) – Time constant
- class pyimpspec.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 pyimpspec.circuit.elements.Resistor(**kwargs)
Symbol: R
An ideal resistor.
\(Z = R\)
- Parameters:
R (float = 1e+03 ohm) – Resistance
- class pyimpspec.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 pyimpspec.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 \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 \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 \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 \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 \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 pyimpspec.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 \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 \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 pyimpspec.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 \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 \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 pyimpspec.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 pyimpspec.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 \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 \frac{1}{n}} \frac{1}{\left(L^{2} R_{i} Y\right)^{1 \frac{1}{n}}}}\right)^{\frac{n}{2}} \left(\left(j 2 \pi f \frac{1}{\frac{1}{\left(R_{ct} Y\right)^{1 \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 pyimpspec.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 pyimpspec.circuit.elements.Warburg(semi-infinite)
Symbol: W
Semi-infinite Warburg diffusion.
\(Z = \frac{1}{Y \left(2 j \pi f\right)^{n}}\)
where \(Y = \frac{1}{\sigma\sqrt{2}}\) and \(\sigma\) is the Warburg coefficient in ohm/s^(1/2) when \(n=0.5\).
- Parameters:
Y (float = 0.001 S*s^n) – ‘Admittance’
n (float = 0.5, fixed) – Phase angle in -pi/2 radians
- class pyimpspec.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 pyimpspec.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
- class pyimpspec.circuit.elements.ZARC(**kwargs)
Symbol: Zarc
Parallel connection of a resistor and a constant phase element with the time constant as a parameter.
\(Z = \frac{R}{\left(2 j \pi f \tau\right)^{n} + 1}\)
- Parameters:
R (float = 1e+03 ohm) – Resistance
tau (float = 1 s) – Time constant
n (float = 0.95) – Dispersion parameter
Element registration classes
- class pyimpspec.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 pyimpspec.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 pyimpspec.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 pyimpspec.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.