## Spice pin numbers

### What is a spice pin number

At the very end of the process, export_spice takes each component in the abstract model, iterates over all ports of the given component and sorts them by their pin number. The result should be a continous array numbered from 1 (else an error is generated). Then it iterates over this sorted array to export the net name each port is connected to.

For export_spice the pin number of a port is one of these (it will use the first it finds):

- display/name (this is what's displayed on the drawing normally)
- display/pinnum
- name
- pinnum

One step back, target_spice generates display/name by choosing the first existing attribute for a port from these attributes:

- spice/pinnum
- pinnum
- name (the port's name as a final fallback)

Thus the default approach to manage spice node (connection) ordering in generated (component) instance lines is to specify spice/pinnum as an integer from 1 up, for each terminal of a symbol. There are multiple ways to achieve this, each explained below.

Note: other workflows may have different pin numbers for the same ports, for example pcb/pinnum for the PCB workflow. It's typically the target_* plugin (configured in the current view) that dispatches the value of a workflow specific pinnum into display/name.

### Different approaches to set spice pin number

#### Implicit from terminal name

For the simple symbols like non-polarized two-terminal passives, such as resistors or coils, terminal names are typically "1" and "2". If nothing else is set, this becomes display/name and acts perfectly as spice pin number.

#### Hardwired in the terminal spice/pinnum

Some symbols represent simple, common components that have well established model pinout in spice. For example BJT or FET transistors, diodes. These symbols should have spice/pinnum set in their terminals, with attribute priority set to 31050.

This low priority lets other mechanisms (such as devmap or portmap) to override the builtin pin number, in case a macromodel (subckt) is chosen with non-standard pinout.

#### Symbol attribute: spice/portmap

It is possible to use a generic symbol (such as an opamp) with a custom model (e.g. a macromodel subckt) that uses a non-standard pinout, as long as the number of terminals matches the number of ports of the model. The custom spice pinout can be specified using the normal portmap mechanism via the array type symbol attribute spice/portmap.

#### From devmap

A devmap typically overwrites the portmap attribute of the component. It is possible to include spice/pinnum in the devmap, preferrably together with the symbol attribute spice/model the pinout is for. This method works for highly specialized custom parts that will always have the same model for simulation.

### Slotting and unslotting

#### Shared ports on slotted symbols

For example take the opamp symbol from the stock library: it has two inputs, one output and two power terminals. These five terminals match the five ports a typical spice opamp macromodel would expect.

But when it comes to slotting, there is a problem with the power pins. Take a dual opamp, say lm358: that will be two symbols placed with the same name (say U15). When exported in a workflow that supports slotted components (e.g. target_pcb), the abstract model will contain a single U15 with 8 ports: two times the two input ports, two output ports and one pair of power ports, shared by both slots. When exporting this to spice, the output is two components with different names. Each component will have exactly 5 ports, just like the symbol.

But because on the physical device the power ports are shared between the two slots, most schematics will connect only one positive and one negative supply terminal, leaving the other two unconnected. When exporting to target_pcb, this is masked by the fact the per slot power ports are merged. But with target_spice there is no such merging as there would be two separate components, each having the exact connections the corresponding symbol had.

To solve this problem, target_spice offers a terminal attribute called spice/shared. When this attribute exists, it is copied to the port in the abstract model; then if the port has this attribute, all ports in all slots of the same slotted device will share connections. That is, if a power terminal is connected on only one slot of a symbol, and the power terminal is spice/shared, the same numbered terminals on all other slots of the same named symbol will share connections.

Since the attribute name is prefixed with spice/, it's only for target_spice, other workflows will ignore this terminal attribute.

#### Unslotting

Sometimes a dual opamp is drawn not as a slotted symbol using two single opamp symnbols, but as a single monolithic symbol that has 8 terminals. For the PCB workflow the slotted and the monolithic approaches will yeild the same result, but monoliths need extra steps for the spice workflow, because spice typically expects each slot to be a separate compontnent. There are two ways handling this situation.

The spice way is to create a device-specific, monolithic macromodel: a subckt that has 8 ports and wires them to two instances of the original single-slot opamp model.

The sch-rnd way is converting to a hierarchic project, create a "device" sheet that represents the monolithic symbol. In this sheet there should be 8 sheet ports wired to two single-slot opamps. Attributes like spice/model and spice/pinnums are present only on the "device" sheet, the monolithic symbol on the parent sheet will emit an X spice instance calling the subckt that's generated from the "device" sheet.

Example project provided in 60_spice_unslot.