I am a netlist creation tool that gets passed to context callers by Netlist. You never construct this directly; leave it to Netlist.__call__.

There is exactly one instance of me for an entire circuit. Call it to add a line to my internal list of Ngspice instance lines. You can use any Ngspice reference designator (either with the number specified or automatic numbering) as a method call instead of supplying it as the first argument. The method name will be passed on to the call as the equivalent of the first argument. For example, these two are equivalent on an instance f:

 f('r', 1, 2, 1000)
 f.R(1, 2, 1000)

Note that reference designators are forced to uppercase, as is the first token of any non-comment, non-title line.

You do not need to precede "PARAM", "MODEL", and "SUBCKT" with a dot. This means you can call them by method name, e.g., f.MODEL(...).

If you want your top-level circuit (not subcircuits) to have alterable parameters, use the result of my av method as the device value or device or model parameter value. You can access a list of specifications for all the alterables you define that way. It contains instances of AV with all the info needed to do the alteration after the circuit file has been sourced.

Method	__init__	`Elements(n, startNum)`
Class Method	uic	Undocumented
Class Method	reset	Undocumented
Method	get	Obtains the pingspice simulation option of the specified name by looking in the following places, in order:
Method	set	Sets the simulation-wide option specified by name to value.
Method	__getattr__	Convenience method for calling me with the reference designator as the method name.
Method	processParamAVs	I call this repeatedly during circuit production, each time with a dict of params and a reference designator refDes for a device, model, or voltage/current source.
Method	processArgs	Called by `__call__` and `fixDeferredAVs` to process positional arguments of a call to my instance.
Method	makeLine	Makes a line of text to be included in the netlist to specify a device with reference designator refDes.
Method	__call__	My main API interface.
Method	fixDeferredAVs	Fixes any lines with deferred AV processing.
Method	raw	Adds a line of raw text to the netlist. You can specify a string proto with substitution args, or just the string as you want it.
Method	dashBlock	Call this and then do more stuff with me in context, and all the netlist lines generated in that context will have a dashed comment header and footer above and below.
Method	otherSets	See `NodeTracker.otherSets`.
Method	observe	Constructs a `set` that has nodes automatically added to it as I connect them anywhere. Returns the ID of the new set.
Method	registerSubcircuit	Call to register the subcircuit with the specified unique name, recording its observer set ID and the list of nodes with which it was constructed.
Method	iNode	Automatically generates and returns N intermediate node names for making connections related to the specified node.
Method	vexpr	Returns a 'V(x)' or 'V(x,y)' expression, depending on whether one or two nodes are supplied. More importantly, registers the nodes with my `NodeTracker`.
Method	vav	Constructs an `AV` object with name and a supplied AV object, or args for obtaining one from `av`, that acts as a voltage source.
Method	ve	Constructs a behavioral voltage source at the node name with voltage determined by the expression supplied in the arg(s) following as a string or proto/args combo.
Method	ground	Ties the specified node to ground through a zero-ohm resistor.
Method	sca	Adds a high-value resistance between nodes n1 and n2 to aid SPICE convergence. If n2 is unspecified, it will be 0 (ground).
Method	sca6	Adds a 1M resistance between nodes n1 and n2 to aid SPICE convergence. If n2 is unspecified, it will be 0 (ground).
Method	_getDefault	Called by `processParamAVs` and `processArgs` to get the default value of the supplied `AV` object av.
Method	_useParens	Returns `True` if the supplied reference designator is for an element that has its parameters wrapped in parentheses.
Method	_fixRefDes	Called by `__call__` to add a unique identifying number to the elementary letter of a reference designator if it doesn't already have a number.

Inherited from AV_Maker:

Method

Call this to set a device value, or device or parameter value, to an alterable value you will later identify by its name, the first (and possibly only) argument.

def __init__(self, n, startNum):

overrides pingspice.circuit.av.AV_Maker.__init__

Elements(n, startNum)

@classmethod
def uic(cls, yes=None):

Undocumented

@classmethod
def reset(cls):

Undocumented

def get(self, obj, name, *args):

Obtains the pingspice simulation option of the specified name by looking in the following places, in order:

The instance variables of the supplied object obj (typically a Subcircuit instance), where the user has defined a local option for that object only.
My Netlist object n, where the user has defined a global option for the entire simulation.
The class (not instance!) variables of the supplied object obj, defining a default option for all instances of the same type as the object.
A default value that may be supplied as a third argument.
The defaults for PS_Options.

If name isn't recognized as a simulation option, raises an exception.

A Note about Subcircuits

You can only specify a value or parameter to be alterable in the main circuit, because the Ngspice alter and altermod commands don't work for subcircuit parameters and because we're just not going to mess around with finding devices inside subcircuit definitions when we don't even know the subcircuit reference designator yet.

If you want stuff inside a subcircuit to be alterable during parameter extraction, make it depend on nodes in the main circuit that depend on something alterable there. Floating voltages with fake resistors attached and nothing else are your friend in such cases.

But that doesn't mean you can't take the Python code used to generate an Ngspice netlist for parameter extraction when it comes time to implement a subcircuit using those parameters. An AV instance found in a subcircuit will resolve to its default value after all mods have been performed.

This lets you implement the same Python code in a subcircuit using the now-known parameters you found via analysis.param. The known parameter values will be set as the AV objects' defaults, and the circuit file will generated with those hard-coded numbers in the subcircuit definition.

def processArgs(self, refDes, args, params):

Called by __call__ and fixDeferredAVs to process positional arguments of a call to my instance.

Forces param names to lowercase. Deals with f.MODEL calls. Adds any AV objects to my AV_Manager avm, replacing it in the args or params with its default value. If it has no default, replaces it with a placeholder code so it's added later when fixDeferredAVs gets called.

MODEL calls are a special case: Ngspice expects exactly two positional arguments, the model name and the model type. You can call the circuit generation tool with the prefix of the model name as the first of argument, but a numerical suffix will be appended to make sure it's unique throughout the entire circuit. Or you can call it with just a single argument and a unique model name will be inserted as the first of two arguments in the updated args, with an assigned prefix as well.

Returns True followed by the model name (None if this was not a MODEL call), the updated args, and params--if there was no dependence on an orphan AV. Otherwise returns False followed by the model name (or None), the deferred AV ID, and then None.

def makeLine(self, refDes, args, params, nodes=False):

Makes a line of text to be included in the netlist to specify a device with reference designator refDes.

Additional arguments are a sequence args of positional arguments that will follow the reference designator, separated by spaces, and a dict params of name=value parameters. Any parameter with a value of None will be omitted.

def __call__(self, *args, **params):

My main API interface.

Call this method (i.e., my instance with no method name) with one or more arguments and possibly some parameters as well. Learn this method well! You'll be using it constantly.

The first argument is the reference designator for an Ngspice element. The next arguments, if any, are additional fields that will be separated by spaces on the line. If you arrive at this call the usual way, by calling a derived attribute of me with the reference designator as the method name (i.e., f.R(1, 2, 1000), then I will have inserted the reference designator as the first arg myself (f('R', 1, 2, 1000)).

If the reference designator has a unique identifying number, it will be used as-is in the netlist. Otherwise, I will uniquify it. See _fixRefDes.

With a few exceptions described in the next paragraph, any parameters supplied as keywords will be appended to the line after the fields in name=value format. In at least one special case (.model), the parameters will be wrapped in parentheses. Since you cannot use "lambda" as a keyword, just be sure to pass it as "LAMBDA."

Any parameter with the value of None is ignored. There are three special parameters that I use for simulation-friendly behavior of capacitors and inductors, which aren't appended to the line if they are used for those devices:

v0: For a capacitor ('C' call), sets an initial voltage. An 'A' device of 'capacitor' model type is used instead of a 'C' SPICE primitive.
i0: For an inductor ('L' call), sets an initial current. An 'A' device of 'inductor' model type is used instead of an 'L' SPICE primitive.
ts: For an inductor ('L' call), sets a simulation time step. Specifying this causes 'R' and 'C' SPICE primitives to be included in parallel with the inductance to help ensure convergence. Just enough parallel capacitance is added to limit unit voltage rise time to the specified simulation step time ts if there is a discontinuous change in current, along with just enough parallel resistance to keep LC at critical damping, so there isn't any ringing.

Returns the model name (made unique with a numerical suffix) if this is a MODEL call, i.e., f.model or f.MODEL. Otherwise, returns the reference designator for the component created. (The only time one won't be created, other than a MODEL call, is if you call this with no args or params, which will just add a blank line to the netlist and return None.)

def fixDeferredAVs(self):

Fixes any lines with deferred AV processing.

A Netlist instance calls this after its context ends. See Netlist.__call__.

def raw(self, proto, *args, **kw):

Adds a line of raw text to the netlist. You can specify a string proto with substitution args, or just the string as you want it.

Parameters k Set to an integer to insert the line into my lines list at an index rather than appending it.

@contextmanager
def dashBlock(self, proto, *args):

Call this and then do more stuff with me in context, and all the netlist lines generated in that context will have a dashed comment header and footer above and below.

def otherSets(self, ID):

See NodeTracker.otherSets.

def observe(self, ID=None, nest=False):

Constructs a set that has nodes automatically added to it as I connect them anywhere. Returns the ID of the new set.

Call again with the set ID to have it ignored and no longer added to. That call will return with the completed set.

Ssee NodeTracker.observe.

def registerSubcircuit(self, name, ID, nodes):

Call to register the subcircuit with the specified unique name, recording its observer set ID and the list of nodes with which it was constructed.

If there is already a subcircuit registered with the same name, an exception is raised.

See Also NodeTracker.registerSubcircuit.

def iNode(self, node=None, N=1):

Automatically generates and returns N intermediate node names for making connections related to the specified node.

You can specify a prefix for the node that doesn't actually appear in the netlist. The node keyword is simply a basis for your new node name, preceding it with an underscore.

If N is 1 or unspecified, just a single node name will be returned as a string. Otherwise, the node names will be returned as a sequence of strings.

def vexpr(self, *nodes):

Returns a 'V(x)' or 'V(x,y)' expression, depending on whether one or two nodes are supplied. More importantly, registers the nodes with my NodeTracker.

def vav(self, name, *args):

Constructs an AV object with name and a supplied AV object, or args for obtaining one from av, that acts as a voltage source.

This is a combination of AV object constuctor and DC voltage source maker, for alterable parameters that Ngspice can reference in its voltage, current, resistance, etc. expressions. It puts a DC voltage source at a non-numbered node name whose value is entirely determined by that AV object (or V expression), with a convergence-aiding resistance to ground.

If you supply an AV object as an argument, then that will be used without making another one. In that case, there will definitely be an alter/altermod call for this AV object even if it isn't a parameter.

Use this to conveniently create voltage sources for SPICE expressions.

Returns a reference to the AV object.

def ve(self, name, *args):

Constructs a behavioral voltage source at the node name with voltage determined by the expression supplied in the arg(s) following as a string or proto/args combo.

Connects a convergence-aiding resistance to ground across the voltage source.

Use this to conveniently create voltage sources for other SPICE expressions.

Returns the reference designator of the DC voltage source.

def ground(self, node):

Ties the specified node to ground through a zero-ohm resistor.

def sca(self, n1, n2=0, R=1000000000.0):

Adds a high-value resistance between nodes n1 and n2 to aid SPICE convergence. If n2 is unspecified, it will be 0 (ground).

The default resistance is 1G, but you can specify something different, or call sca6 for a 1M resistance instead.

def sca6(self, n1, n2=0):

Adds a 1M resistance between nodes n1 and n2 to aid SPICE convergence. If n2 is unspecified, it will be 0 (ground).

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

pingspice.circuit.elements.Elements(AV_Maker) class documentation

A Note about Subcircuits

`pingspice.circuit.elements.Elements(AV_Maker)` class documentation