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:

Circuit

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:

DataSet

pyimpspec.circuit.registry.remove_elements(elements)

Remove a specific user-defined element from the registry.

Parameters:

elements (Union[Type[Element], List[Type[Element]]]) – The element(s) to remove.

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.

Parameters:

elements (Optional[Union[Type[Element], List[Type[Element]]]], optional) – Specific element class(es) to reset. If none are provided, then all the elements that are included by default in pyimpspec are reset.

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.

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(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:

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:
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:

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 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:

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

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:

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

Element

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:

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 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:

sympy.Expr

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:

sympy.Expr

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.

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(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:

ComplexImpedances

serialize(decimals=12)

Generate a circuit description code (CDC) that represents this circuit. This CDC is modified to also include the current version of the CDC syntax supported by pyimpspec.

Parameters:

decimals (int, optional) – The number of decimals to include for the current element parameter values and limits.

Return type:

str

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:

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 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:

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