spicelib Usage
==========================================
* scons download (or scons download[_vendor])
* scons unpack (or scons unpack[_vendor])
* scons create (or scons create[_vendor])
* scons test (scons test[_vendor][_libraryname])


Building and testing a spice model library
==========================================

0. Preface
1. Downloading the models
2. Unpacking the models
3. Apply fixes and patches to the models and store them
4. Create model index files
5. Test the models
6. Use the models with gEDA
7. Maintaining models


0. Preface
==============================

Getting, testing and maintaining spice models can be a very time
consuming task. This is a proposal on how to automate or speedup some
of the steps.

The second problem is that distributing models may not be allowed.
(copyright notices on the vendor pages).

Thus I propose to distribute the building rules and not the model
files itself. This building rules may be stored in and SCM tool
somewhere in the web.
Note: This is the way openSUSE distributes proprietary font packages, ...

Most of the steps below may be part of a SCons config file, others can
be done with scripting.

Note: This project now uses SCons (http://www.scons.org) instead of
Make.

1. Download spice models
==============================

The models can be downloaded with a download utility like wget, curl
or something similar using a script language like python, ...

Each vendor needs an extra set of download instructions. The
downloaded files are stored in a specified directory structure:

  download/[vendor]/[files]

Downloading is splitted from all tasks below. Thus you can apply the
steps below again and again.


2. Unpacking the models
==============================

Most vendors provide there models as .zip archives with different
directory structure. In this step the models gets unpacked.

In this step all files gets a md5 checksum. The checksum files are
stored in:

  model_checksums/[vendor_category].md5sum

This checksum may help to track changes in the model files when
maintaining the model library. You'll easily be able to find the
changed files of a .zip file.


3. Fix models and store them in the library
============================================

The model files from the vendors needs to be fixed and the fixed files
needs to be stored in an usable directory structure. Possible fixes
are:

  * missing trailing newlines at model files
  * add headlines, ...
  * fix broken models
    * missing connections
    * syntax errors
  * change model names to get a uniq namespace

The fixed model files are stored in a new directory structure:

  model_library/[vendor]/[section]/[modelfiles]

I'm storing checksums of that created lib, too:

  model_checksums/[vendor_category_lib].md5sum


4. Create model index files
==============================

The index files contains the information how to use the models and how
to combine them with gEDA symbols. The information is stored in an
.ini-style file format that can be easily written with scripts and with
an editor. The index files are stored in:

  indexfiles/[vendor_section].index

The index file has a GLOBAL section with various attributes:

  [GLOBAL]
  MODELDIR=model_library/nxp/bipolar/
  TESTDIR=model_tests/nxp/bipolar/

And symbol definitions:

  [2PA1576Q_NXP00001]
  symbol=pnp.sym
  value=Q2PA1576Q
  modelname=Q2PA1576Q
  file=2PA1576Q.prm
  refdes=Q?
  pinseq_c=1
  pinseq_b=2
  pinseq_e=3
  pinnr_c=C
  pinnr_b=B
  pinnr_e=E
  footprint=none
  test_refdes=Q1
  model_status_good=ngspice_23
  model_status_broken=gnucap_0.35

The section has a "name" part and a "uniq number" part. Thus all
generated symbols will be uniq. (important for gschem, ...)

"symbol" contains a pointer to the symbol template file to use.

"value" to "footprint" are variables that will replace placeholders
in the symbol template files.

"test_refdes" is currently required for testing.

The "model_status_good" is an optional, manual rating of a model. It's
value is a list of all simulators that have been tested.  With
"model_status_bad" bad models can be marked.


5. Testing the models
=======================

It's important to get tested models. The tests are applied by a
library testing script. The script:

  * walks through all symbol definitions in a given index file
  * generates a test schematic
  * creates a netlist using gnetlist
  * runs the circuit simulator
  * reads the simulation results and creats plots
  * combines the plots to a html file
  * gives some messages about the success/failure of the simulation.

With these steps the whole tool chain is tested for every model.

A human tester can watch the simulation result with a browser and
doublecheck the simulation results. This results can also provide
a quick view for the users of that model.
The test result can be written to the model_status in the index file.

If the simulation fails, then either the description in the index file
is wrong or there's something wrong with the model.

If the model is wrong you can either write a patch, fix it with a
script in the config file or just mark the model as broken.


6. Use the models with gEDA
=================================

The new components can be used with gEDA after connecting it with a
small script and the component-library-command backend.

Only few lines are required in share/gEDA/scheme/geda-clib.scm:
-------
; add a library with the command backend
; Syntax:
; (component-library-command "[listcommand]" "[getcommand]" "[name]")
;
(component-library-command
 "/home/werner/oss/geda/spicelib/scripts/gedaparts nxp_bipolar.index"
 "/home/werner/oss/geda/spicelib/scripts/gedaparts nxp_bipolar.index"
 "NXP_bipolar_transistors")
--------


7. Maintaining the Models
==============================

Maintaining means that you walk throught all the steps in a fast way.

If the downloaded model archive is identical (checksum) to that you've
already used, your done.

If the archive is different but contains 95% of identical files, then
you only need to check the modified and the new models.