===== Import and export: Spice =====

Spice is a family of circuit simulators approximately as old as analog
circuit simulation. Most electrical circuit models may be understood as fully analog,
and in this sense, Spice is capable of simulating most circuit models.

However, for histroric reasons, multiple Spice simulators exist. Some are
ancestors of Spice3 (1989), the first version written in C, some have been
reimplemented from scratch. Spice simulators have in common that they are all
different and mutually incompatible. For example, each one defines its own
input language, a dialect of a netlist format named after the Simulator. Gnucap
supports Spice by means of language plugin. An example supporting a dialect
very close to Spice2 is included with the main package, with some quirks to
handle commercial aberrations.

In the past decades, the common primary representation form for analog circuits
has moved on from "Spice netlists" or "decks" (from "deck of punch cards") to
a graphical representation, schematic drawings. Spice netlists do not
incorporate graphical aspects of a circuit drawing, and hence circuit schematic
editors never support Spice directly. The purpose of this page is to show that
a schematic editor or EDA tool supporting an [[.|interchange format]] would
also satisfy the needs of Spice users with little extra work.

This dismisses the claim that tools cannot move forward when targetting Spice users.

===== State of the Art =====

Today (most, free) schematic editors represent circuit user data as drawings,
and often, the relevant circuit is stored implicitly between the lines.
Typical tools incorporate a device database in a custom implentation defined
manner. Sometimes, this database may be maintained or partly extended by the
user inclined to dive into implementation details.

For Spice users need a Spice representation of their circuit, a drawing must be
exported to a spice deck. To this end, a tool has to provide a three-step
mechanism, sometimes dubbed "spice netlisting". This netlisting is a one-way
street that heavily relies on the device database and application specifics.

First, the netlister infers the circuit from the drawing. Where connectivity is
encoded in the geometry, the geometry must be (re)constructed to infer
connections. Sometimes labels or other means of implementation defined metadata
gives rise to connections.

Second, once a circuit has been established, nets are identified to connect
instances. The representation of the instances relevant for Spice are created
in a the chosen dialect, or according to the data.

Some schematic editors add preprocessing, such as ordering or model order
reduction into the second stage. This is not advisable. Circuit manipulation
should be decoupled from a specific tool, and simulation features belong into
the simulator.

===== Circuits to Spice =====

We suggest that circuit schematic editors either store user data (i.e.
circuits) in an appropriate format. If they do not, an export function into
such a format is needed. A schematic stored in Verilog is a circuit, and hence
this example is centered around preparing a circuit represented in Verilog for
simulation with a specific Spice simulator.

==== library mode ====

Example. The circuit may contain a line like

    diode #(.area(1e-3), .model("mydio")) d1(.c(net1), .a(net2));

where the desired output in a Spice deck may be

    Dd1 net2 net1 mydio area=1e-3

Another Spice simulator may need

    Dd1 (net2, net1) mydio area=1e-3

Yet another requires

   mydio Dd1 (net2 net1) area=1e-3.

This translation may be obtained by supplying a device library for each Spice dialect.
A device library is a file with one entry per device. A file "ngspice.v" could contain

   (* ngspice="D%label %a %k %model area=%area" *)
   module diode (a, k);
		inout electrical a, k;
		parameter string model = "ddefault";
		parameter real area = 1;
   endmodule;

==== Inline overrides ====

Sometimes it is desirable to inline raw Spice directly into a circuit. This
is possible as soon as a schematic editor supports attributes.

    (* ngspice="Dmydiode %a %c mydio 1e-3 user_defined_extras" *)
    otherdiode #(.area(1e-3)) d1(.c(net1), .a(net2));

Which would be dumped for ngSpice as

    Dd1 net2 net1 mydio area=1e-3 user_defined_extras

Note that the additional "ngspice" attribute won't render the circuit unusable for a
simulator that understands Verilog natively.


==== Extras ====

Most Spice simulators lack the capability to map device instances to prototypes in a meaningful or practical way.

Using standard Verilog syntax on the schematic end, and Spice representation on the device instance end will bring in convenient features such as (but not limited to) overloading, generation, net resolution and generation.

Overloading example. A short transmission line is a small resistor
   
   (*spice="R%label %t1 %t2 e1-9*)
   module trln(t1, t2);
      parameter real L = 1 from [0,1e-9];
   endmodule
   (*spice="T%label %t1 %t2 rlcline L=%L*)
   module trln(t1, t2);
      parameter real L = 1 from (1e-9, inf);
   endmodule  

===== Roadmap =====

A translation file such as "ngspice.v" is needed for each intended simulator.
This file should be provided and maintained by the respective simulator developers.

Where developers lag behind, the translation file(s) could be supplied by
schematic editor suppliers.

As a stopgap, a Spice user may be able to use inline overrides, prepare their
own library, or even bundle them with their schematic, if simulation with Spice
is intended.

Eager Spice simulator developpers should consider reading the circuit directly.
This makes the translation library unnecessary. An ordinary device library will do.

===== Examples =====

There's an early [[https://codeberg.org/qucs/gui/src/branch/develop/examples/helloworld|hello-world]] example for ngspice included with
the Qucs GUI.