## Spice models

### What is spice model

A model in spice is really two things:

- the code that implements how to simulate the given thing (e.g. an npn transistor)
- a set of parameters to this model to get the behavior match a specific existing device type

The former, the code, is typically provided as part of the simulator software, at least for the most common, basic component types. The latter, model parameters, is specified by the user (normally acquired from the device vendor or constructed from the datasheet or measurements).

### How to specify the model

Concrete symbols are compile into abstract components; export_spice will write a spice instance line for each named component in the abstract model. Anything more complicated than passives and sources will need to have a spice model named in the instance line.

There are different strategies how this spice model name is generated.

#### sch-rnd's spice lib reference

If the symbol has a spice/model attribute, the value of this attribute is a model name. In sch-rnd reusable spice models are kept in the spice library, which is very much like the symbol or devmap library: a directory tree that holds spice models, one model per file, models identified by file name. Spice export files are self-contained and do not rely on external model files. This is achieved by sch-rnd copying the content of these spice model files from the library into the output file.

Furthermore there's a sheet-local library, just like with devmap (and optionally with symbols), so any spice model used by the sheet is also saved in the sheet so the sheet is self-contained (and portable) too.

The following rules apply to the model files in the sch-rnd spice library. One model file shall contain only one .model or one .subckt. The file name shall match the name of the .model or .subckt in the file. The name from spice/model is first searched in all sch-rnd spice libraries in a case sensitive manner without suffix; if not found, searched again with .mod suffix; if not found searched again with .prm suffix. The convention is to name .model files *.prm and .sibckt files *.mod.

Note: the model is copied only once (per unique model name) into the sheet-local spice lib and to the spice netlist export.

If spice/model_card is specifed, that overrides spice/model (so spice/model is ignored in that case).

#### symbol-embedded spice-card

Also called inline spice-card. The whole spice model is specified as a multiline string in the symbol attribute called spice/model_card. The model is named with an unique name and copied in the output spice netlist.

On the output spice netlist the model is created as many times as specified in different symbols.

If specified, overrides spice/model_card.

#### spice-level include

The above two resulted in both self-contained sheets and self-contained spice netlist exports. That is, if the sheet is shared, a different user on a different system could export the same spice netlist, without assuming any spice model library installed. If the exported spice netlist is shared, it can be ran through a spice implementation without depending on any external file (model library). The advantage of this is clearly portability, while the drawback is larger files and files that need update if the model is changed (fixed) in the spice lib.

A non-self-contained method is specifying the following two attributes for a symbol, without specifying spice/model_card or spice/model:

- spice/model_card_uname should contain the name of the model; export_spice will use this as the model reference from the generated component instance, without trying to do anything to make the model available in the file
- spice/model_include is a file name or path to the model file or model library file; a model library file contains multiple models. Export_spice will generate a single .INCLUDE line on top of the exported netlist per unique spice/model_include values.

Once the exported file is ran through a spice implementation, the spice software will employ its own search method for each .INCLUDE and load the referenced spice lib file from wherever.

This is the weakest method, if spice/model or spice/model_card is specified, that may modify spice/model_card_uname and will write a model into the output file.