NSPICE(1ICD)

NAME
nspice, nspice_pp, nspice_bs - encapsulated spice simulator

SYNOPSIS
nspice cell commandfile

nspice_pp cell commandfile

nspice_bs cell

DESCRIPTION
Nspice is the encapsulated spice simulator that performs a spice(1ICD) analysis for a circuit cell that is present in the database, using a commandfile with spice and/or sls(1ICD) commands. Nspice consists of a unix shell-script that extracts a circuit cell from the database using xsls(1ICD), converts a commandfile with spice and/or sls commands to a spice commandfile using nspice_pp, runs spice, and finally executes nspice_bs to backsubstitute node numbers in the output file by their corresponding names as specified in the database. The output of nspice is found in a file called cell.ana.

nspice_pp
    Nspice_pp converts, for a particular cell (first program argument), a commandfile with spice and/or sls commands (second program argument) to a spice commandfile. In the inputfile nodes may be referred to by their names as specified in the database. The output of the program is sent to stdout. The conversion is executed by using information from a spice network description that is present in the file cell.spc. This file is typically extracted from the database using xsls with the options -Shlmbf. This will generate a file cell.spc with a full (hierarchical) description of the cell, including the appropriate transistor models, terminals for n-bulk and/or p-bulk connections, and a name translation table that translates node numbers into node names as used in the database. To reduce the number of nodes in the spice network description the use of the options -xy [ -z name ] is further recommended (see manual page of xsls ).

    All sls commands that are allowed with the sls simulator (see "sls: switch-level simulator user's manual") may be used in the commandfile of nspice_pp. However the ones that are translated into spice commands are the following: The set commands in the commandfile are translated into piecewise linear voltage sources that are connected to the relevant input nodes of the network. Sls plot commands are translated into ".print tran node1 node2 ..." cards. If option level=3 is specified, a transient analysis card will be placed in the outputfile that specifies a simulation from t=0 till t=t_end, where t_end is given by simperiod x sigunit or otherwise - if simperiod is not specified - by the time of the last input signal transition. The value of tstep in the .tran card should explicitly be defined in the commandfile (see below).

    The other information that is allowed in the commandfile should be specified in the following way:
    *%
     ... translation information ...
    *%
     ... direct spice commands ...
    *%
    The separators '*%' should be placed at the beginning of each line. The first part consists of translation information that is used to translate sls commands (if any) into spice commands. It may consist of zero or more of the following lines
    tstep	<real>
    tstart	<real>
    uic
    trise	<real>
    tfall	<real>
    vhigh	<real>
    vlow	<real>
    The field <real> denotes a specification of a real value. It may optionally have a scale factor 'G' (1e9), 'M' (1e6), 'k' (1e3), 'm' (1e-3), 'u' (1e-6), 'n' (1e-9), 'p' (1e-12) or 'f' (1e-15). The variable tstep specifies the value of tstep as used for transient analysis. This value should be specified when option level=3 is used with the sls commands (see above). The variable tstart optionally specifies the start time for the transient analysis card. If the keyword uic is used, this keyword will be added to the .tran card. The variables trise and tfall respectively specify the rise and fall time of the input signals (default trise = tfall = tstep). The variables vhigh and vlow respectively specify the voltages that correspond to the high state and the low state of the input signals (default vhigh = 5 and vlow = 0). For the x state a voltage of (vhigh + vlow) / 2 is used.

    In the second part of the spice information, direct spice commands may be specified. These commands are directly copied to the output, however with node names that are specified between quotes translated to their corresponding node numbers. E.g. .ic v("out")=5v might be translated into .ic v(12)=5v. If no sls commands are used, this part of the commandfile - beside the information that is extracted with xsls - will contain all the information that is necessary for the spice simulation.

    An example of a commandfile with only spice commands is given below:
    *%
    *%
    vphi1 "phi1" 0 pulse (5v 0v 29.4ns 0.6ns 0.6ns 29.4ns 60ns)
    vphi2 "phi2" 0 pulse (0v 5v 29.4ns 0.6ns 0.6ns 29.4ns 60ns)
    vvdd "vdd" 0 5v
    vin "in" 0 pulse (5v 0v 29.4ns 0.6ns)
    .tran 0.2n 120n
    .print tran v("phi1") v("phi2") v("1") v("2") v("3")
    .print tran v("4") v("in") v("out") v("out_inv")
    .options nomod
    .options limpts=601
    .options cptime=100
    .ic v("3")=0 v("out")=5
    *%

    An example of a commandfile with mixed sls and spice commands is as follows:
    set phi1 = (h*30 l*30)*~
    set phi2 = (l*30 h*30)*~
    set vdd  = h
    set vss  = l
    set in   = h*30 l
    option level = 3
    option simperiod = 120
    option sigunit = 1n
    option outacc  = 10p
    plot phi1 phi2 1 2 3 4 in out out_inv
    /*
    *%
    tstep 0.2n
    trise 0.6n
    tfall 0.6n
    *%
    .options nomod
    .options limpts=601
    .options cptime=100
    .ic v("3")=0 v("out")=5
    *%
    */
    (Note that the spice information is placed between sls comment signs ("/*" and "*/") so as to allow to use the same inputfile for an sls simulation.)

nspice_bs
    The program nspice_bs backsubstitutes node numbers by node names in a spice output file for a cell (specified as an argument). This is done according to a name translation table that should be present in a file called cell.spc. The name of the spice output must be cell.ana. Nspice_bs will only backsubstitute node numbers that are in the header of a transient analysis table.

The nspice unix-shell script has the following form:

 # xsls: always use options -Shlmbf;
 #       the use of options -xy [ -z name ] is recommended
 xsls -Shlmbf -xy $1
 nspice_pp $1 $2 >> $1.spc
 spice $1.spc > $1.ana
 if nspice_bs $1
 then
     exit 0
 else
     exit 1
 fi
 # eof

EXAMPLE
$ nspice latch latch.cmd

AUTHOR
A.J. van Genderen

FILES
commandfile    input file
cell.spc    generated input file for spice
cell.axa    temporary file
cell.ana    output file

SEE ALSO
sls(1ICD),
xsls(1ICD),
spice(1ICD),
simeye(1ICD),
user's guide for spice,
sls: switch-level simulator user's manual.

DIAGNOSTICS
Nspice_pp and nspice_bs send their diagnostics to stderr. Spice diagnostics are found in the output file cell.ana.