A more realistic inductor, with effective series resistance, core saturation, and self-resonance from interwinding capacitance:

                                            +---+
       +-------------------------------+----| C |--------------------+
       |                               |    +---+                    |
       |                               |          +----+             |
       |                               +----------| Rp |-------------+
       |                                          +----+             |
       |                                                             |
       |  +----+        +----+       +-------+          +-----+      |
   a --+--| Rs |-- 11 --| L0 |--+--->|+ Vs1 -|>-- 13 -->|+ F -|>--+--+-- b
          +----+        +----+  |    +-------+          +-----+   |
                                |       |                  x      |
         +-------- 12 ----------+       |                  |      |
         |                              |                  |      |
       +----+            +-----<--------+                  |      |
       | R0 |            |         f(I)            1:1     |      |
       +----+            x                 +----->---------+      |
         |           +------+              |                      |
         +--- 14 ---x|+     |          +-------+                  |
         |           |  B:V |>-- 21 -->|+ Vs2 -|--+               |
       +----+    +--x|-     |          +-------+  | 22            |
       | C0 |    |   +------+                     |               |
       +----+    |                                |               |
         |       |                                |               |
         +-------+--------------------------------|---------------+
                                                  |
                     .............................|.....
                     :                            |    :
                +---------+-------+-------+-------+    :
                |    :    |       |       |       |    :
             +----+  : +----+  +----+  +----+  +----+  :
             | L1 |  : | R1 |  | R2 |  | R3 |  | R4 |  :
             +----+  : +----+  +----+  +----+  +----+  :
                |    :    |       |       |       |    :
                | 23 :    |       | 31    | 32    | 33 :
                |    :    |       |       |       |    :
                |    :    |    +----+  +----+  +----+  :
                |    :    |    | C1 |  | C2 |  | L2 |  :
                |    :    |    +----+  +----+  +----+  :
                |    :    |       |       |       |    :
                +---------+-------+-------+-------+-------- Rz --- 0
                     :                                 :
                     ...................................
   R0 and C0 may be omitted and B:V+ input connected directly to
   node 12.

Note: R0 and C0 form an LPF with a time constant of ts, which may help convergence. But the author is not yet certain whether it's really that realistic or helpful to include. Low-pass filting here delays and limits high-frequency responsiveness to the effect of core saturation, which may or may not be true to the underlying physics of magnetic dipoles in ferrous material. To omit and have the + input of B:V connected directly to node 12, set my no_lpf attribute True.

Note: Components R1-4, C1-2, and L2, inside the dotted box, are for modeling high-frequency core loss per Edward Herbert's "Core Loss Modeling" presentations. It may be possible to determine their values, along with mu and the exponent for expr_V13, by making this a ParameterFinder and comparing actual measurements of sample devices to simulations with ADE. Probably not trivial, so this remains a big TODO for now.

In addition to inductance L, also defines series resistance R, a defined self-resonant frequency fsr, and core saturation with inductance at Idc dropping to 90% its zero-current value.

The inductor retains 90% of its zero-current (maximum) inductance when there is Idc Amps of DC current flowing through it. Set Idc to None to have no inductor core saturation.

Core saturation is modeled in accordance with Ben-yaakov and Peretz, "Simulation bits: a SPICE behavioral model of non-linear inductors," IEEE Power Electronics Society Newsletter (Q4 2003). When the DC current reaches Idc, the effective inductance drops to 90% its full zero-bias amount. L0 implements the miminum fully-saturated inductance, when the coil is effectively just an air-core inductor.

The function for the behavioral voltage source B:V is:

   1 + 1/9*(|I|/Idc)^3

This coil is simulation-friendly: If the pingspice simulation parameter ts is defined, the coil will have a default self-resonant frequency of 2/ts, in the absence of a defined fsr or if that is less than fsr.

Note: The parallel (inter-winding capacitance) C and its damping resistance Rp are connected across the air-core fully-saturated equivalent inductance L0. This isn't exactly accurate, as the capacitance resonates with the much larger overall inductance. But having the capacitance across the overall inductance causes oscillations due to the behavioral sources. The capacitance is adjusted (made larger) to account for this.

TODO: Make this a ParameterFinder with c and the exponent determined via paramfinding on sample device measurements with a pulse input, and (non-trivial!) maybe include hysteresis in the B:V with its two unknown hysteresis parameters as well.

Instance Variable	R	Effective series resistance (ESR), Ohms. (Default is zero, but that's not realistic.)
Instance Variable	fsr	Self-resonant frequency, Hz.
Instance Variable	Q	The quality factor of the inductance in parallel with its winding capacitance. (Default is 50. Toroidal iron-powder power inductors have a Q of around 30-35.)
Instance Variable	Idc	DC current at which inductance drops to 90% of its zero-current value.
Instance Variable	mu	The initial (zero-current) relative permeability of the core. This is used to calculate the lower limit of inductance. Real-world values range from 20-130, with higher values resulting in lower fully saturated inductance values, since at that point the core adds nothing to the air-core inductance. Default is 50, which is mid-range for iron but low for Ferrite.
Instance Variable	pdiss	Set `True` if a 'pdiss' (power dissipation) node is desired. Setting this with no non-zero R defined raises an exception. The 'pdiss' node will come after the second inductor node.
Instance Variable	ic	Initial transient analysis current, Amps. (Default is `None`, to use SPICE-computed initial conditions.)
Instance Variable	no_lpf	Set `True` to omit the RC lowpass filtering in the current loop that simulates inductor saturation. The author is not yet certain whether it's really that realistic or helpful, though it is presently the default. (The default value of no_lpf is `False`.)
Method	expr_V13	Returns a B-source expression for the voltage at node n1:
Method	setup	Subcircuit definition.

Inherited from NodeStuff (via Subcircuit):

Instance Variable	shunts	A dict of current sensing V elements with the pairs of nodes they connect.
Class Variable	debug	A `Bag` that gets set `True` for all instances to log info about each `setup` call.
Class Method	autoName	Undocumented
Method	setupResults	Undocumented
Method	fill	Undocumented
Method	nodeCheck	Call with the circuit building tool f and a sequence of nodes provided to this `Include` or `Subcircuit`.
Method	rawNetlist	Get lines of a raw netlist from a search hierarchy of possible sources.
Method	shunt	Call to insert a current-measuring shunt and add an entry to my `Elements` baton's dict of shunts.
Method	raw	See `Elements.raw`.
Method	iNode	See `Elements.iNode`.
Method	ground	See `Elements.ground`.
Method	sca	See `Elements.sca`.
Method	sca6	See `Elements.sca6`.
Class Method	_libDir	Undocumented
Method	_strippedLines	Undocumented
Method	_call_setup	Calls my `setup` method (almost always your override of that method, actually) and processes any return value.

Inherited from NodeStuff (via Subcircuit):

Instance Variable	shunts	A dict of current sensing V elements with the pairs of nodes they connect.
Class Variable	debug	A `Bag` that gets set `True` for all instances to log info about each `setup` call.
Class Method	autoName	Undocumented
Method	setupResults	Undocumented
Method	fill	Undocumented
Method	nodeCheck	Call with the circuit building tool f and a sequence of nodes provided to this `Include` or `Subcircuit`.
Method	rawNetlist	Get lines of a raw netlist from a search hierarchy of possible sources.
Method	shunt	Call to insert a current-measuring shunt and add an entry to my `Elements` baton's dict of shunts.
Method	raw	See `Elements.raw`.
Method	iNode	See `Elements.iNode`.
Method	ground	See `Elements.ground`.
Method	sca	See `Elements.sca`.
Method	sca6	See `Elements.sca6`.
Class Method	_libDir	Undocumented
Method	_strippedLines	Undocumented
Method	_call_setup	Calls my `setup` method (almost always your override of that method, actually) and processes any return value.

R =

Effective series resistance (ESR), Ohms. (Default is zero, but that's not realistic.)

fsr =

Self-resonant frequency, Hz.

Q =

The quality factor of the inductance in parallel with its winding capacitance. (Default is 50. Toroidal iron-powder power inductors have a Q of around 30-35.)

Idc =

DC current at which inductance drops to 90% of its zero-current value.

mu =

The initial (zero-current) relative permeability of the core. This is used to calculate the lower limit of inductance. Real-world values range from 20-130, with higher values resulting in lower fully saturated inductance values, since at that point the core adds nothing to the air-core inductance. Default is 50, which is mid-range for iron but low for Ferrite.

pdiss =

Set True if a 'pdiss' (power dissipation) node is desired. Setting this with no non-zero R defined raises an exception. The 'pdiss' node will come after the second inductor node.

ic =

Initial transient analysis current, Amps. (Default is None, to use SPICE-computed initial conditions.)

no_lpf =

Set True to omit the RC lowpass filtering in the current loop that simulates inductor saturation. The author is not yet certain whether it's really that realistic or helpful, though it is presently the default. (The default value of no_lpf is False.)

def expr_V13(self, n1):

Returns a B-source expression for the voltage at node n1:

   V = V(n1, 'b') * (1 + 1/9*(|I(Vs1)|/Idc)^3)

def setup(self, f):

overrides pingspice.circuit.netlist.Subcircuit.setup

Subcircuit definition.

Why use f? Because it's short and a conveniently typed letter on the keyboard.

Override this if your subclass does not reference a param.ParameterFinder subclass via the Finder class attribute. As with Include.setup, your override method can return a dict of attribute names and values to set in my instance.

API Documentation for pingspice, generated by pydoctor at 2021-09-18 08:41:11.

pingspice.lib.passive.Coil(Subcircuit) class documentation

`pingspice.lib.passive.Coil(Subcircuit)` class documentation