Inter-Office Memorandum
To  Thyme Interest  Date July 11, 1983
From Rick Barth  Location Palo Alto
Subject Thyme Manual  Organization PARC/IDL
Filed on: [Cherry]<Thyme>Top>ThymeManual.tioga, .press
Thyme Manual
Introduction
This is the manual for Thyme as available for Alto/Mesa 6.1 during July, 1983. Thyme is a circuit simulation system to help you predict the time domain response of an MOS integrated circuit. There are a number of tools that assist you in preparing Thyme input and analyzing Thyme output. The circuit extractor, which is a component of Chipmonk, lets you create Thyme input files from existing layout. PlotScreen allows Thyme output to be displayed on a color display. PlotPress converts Thyme output into press files suitable for printing on Lilac. Thyme is already capable of handling simulations with hundreds of nodes and components. In future versions, it will be converted to run in the Cedar programming environment, where it will provide much better output analysis capabilities.
Thyme and initial drafts of portions of this document were written by Neil Wilhelm. Further maintenance and enhancement has been done by Rick Barth and Sweetsun Chen.
Thyme is solely a time domain circuit simulator. It has far fewer capabilites than other circuit simulators, most notably Spice, but it is much easier to use for the particular task for which it was designed. In particular Thyme will handle larger circuits, has a more powerful circuit specification language, and produces output which is easier to analyze. Thyme is quite easy to maintain compared to Spice. Last but not least it runs on machines that are widely available within our design environment, namely D machines.
How To Get Started
Installation
The following installation procedure assumes that you have a vanilla Mesa 6 Alto partition with a reasonable amount of disk space available. The additional files beyond those which are left on a newly erased disk which you must have include RunMesa.run and Mesa.image. It is also a good idea to have XDebug.image on your disk and have the debugger installed so that if you run into problems the Thyme maintenance people have some hope of helping you. In Palo Alto the local directory which contains these files is [Ivy]<Mesa>.
To install Thyme on your machine retrieve [Cherry]<Thyme>Top>ThymeGet.cm and invoke it as a command file by typing @ThymeGet to the Alto Executive. This will retrieve the following files:
ThymeForm.thy A working input file to start editing with.
Extract.chipbcd A version of the extractor that is compatible with the current Thyme.
Thyme.bcd The simulator itself.
Thyme.errors Contains the text of the error messages Thyme generates .
ThymeBasics.thy Links the simulator to the model and function definitions.
MosModels.thybcd Contains the transistor model code.
StdFunctions.thybcd Contains the waveform generation code.
PlotPress.bcd Converts the .plot files generated by Thyme into .press files suitable for tranmission to Lilac.
PlotScreen.bcd Replots the first page of a .plot file on the screen.
Helvetica8.ks Font used to print characters on the plot.
If you start up Thyme and it simply hangs there with a cursor that is a circle with an arrow in it then you are probably missing the font file. The plotting software is starting at Helvetica8.ks, looking it up in the file directory, discovering it is not there, changing the font filename to Helvetica9.ks, looking for it, not finding it, etc. etc. until the string overflows or your patience runs out, whichever occurs first.
You must also retrieve the correct process definition file for the type of simulation you intend to do. These files are stored in the subdirectory [Cherry]<Thyme>ProcessDefs>. The filename depends on the type of process you are using, the minimum feature size in microns, and the temperature at which you intend to do your simulation.
See the section about circuit design pragmatics later in this document for a detailed discussion of how to choose the correct temperature. If you are learning how to do circuit simulation and know the process type and minimum feature size just use the highest temperature data available for your simulations rather than plunging off into a morass of detail that need not concern you right now. For example if you are using an NMOS process with a 4m feature size then you should retrieve the file [Cherry]<Thyme>ProcessDefs>NMos4.0u75.thy.
Note that the character in the filename is a "u" not a "m".
Process definition filenames have the form <process type>|<feature size>|<temperature>.thy.
Preparing Input
Thyme input may be generated in two ways. One is to sit down with your favorite text editor and type it in. The other is to lay out your circuit using Chipmonk and then apply the circuit extractor to your layout. In this section we will assume that you are doing the former, how to make Thyme work in the latter case we will handle subsequently. This section is an overview. As such much of the detail has been suppressed. Don't treat it as the gospel truth. That's saved for later.
The basic format of a Thyme file is:
library statements
circuit definition
output control
run control
and here is an example of one:
1 library[MosModels];
2 library[StdFunctions];
3 circuit={
4 !ThymeBasics.thy
5 !Nmos4.0u75.thy
6 in:node; out:node; Vdd:node;
7 powerSupply: voltage[Vdd, Gnd]= 5.0;
8 ?:capacitor[out,Gnd] = 0.01pF;
9 ?:Dep[out,out,Vdd | L ← 4, W ← 2];
10 ?:Enh[in,Gnd,out];
11 ?:RectWave[in|period← 4us, width ← 2us, tRise ← 0.1us, tFall ← 0.1us, tDelay ← 2us];
12 };
13 plot["Nmos Inverter (4 micron, 75 C)", :0.1us, -1, 6, in, out];
14 run[TMAX ← 10us];
Note that the line numbers appear here purely for expository purposes and are referred to below in parantheses.
The library statements (1-2) cause Thyme to load the model and function code. These statements must always appear and it is unlikely you will ever want to change them. If you think you do details are available further on in this document.
The circuit definition part (3-12) contains two references to other files which are to be included as if their contents were present in this file. The first one (4) defines the interface for the model code which was loaded in the library statements and the second one (5) tells the model code which particular process you are using. Again these statements always appear and it is unlikely you will change them except for the choice of the second filename. The rest of the circuit definition part (6-12) defines a simple inverter circuit that has a rectangular wave as input and a single capacitor as the output load.
All the statements defining the circuit have the form name:type;, where a name is an alpha followed by a sequence of alphnumerics and type is a name previously defined or a built in type. If you don't care to give a name to a particular instance then you may put a "?" in place of the name, Thyme will generate a name for you. If you want to use funny kinds of names that include characters such as ";" then you must surround the name with "$". A type must be defined before it is used; otherwise order does not matter.
A circuit is a collection of nodes, branches, and subcircuit instantiations. First the nodes are defined (6) and then the branches (7-8) and subcircuits (9-11) are instantiated using the nodes previously defined. Node definitions have the form:
<node names>: node
There is one predefined node, Gnd, the ground node. All voltages are referenced to it. Branch instantiations have the form:
<name>: <branch type>[<node name>, <node name>] = <expression>
Branches may be one of the following built in types: RESISTOR, CAPACITOR, INDUCTOR, VOLTAGE, and CURRENT. Each of these expects a numeric value to be following the "=" in units of volts, amps, ohms, farads, or henries. The left node name of a branch is considered to be the positive terminal of the branch.
All numbers read by Thyme are real although fixed point representations will be accepted and converted. Thyme has a primitive understanding of units of measurement. A unit may be specified with any number; it must immediately follow the number with no intervening spaces. Acceptable units are "A," "F," "H," "s," and "V," for amperes, farads, henries, seconds, and volts. Scaling factors may be prefixed onto a unit; the available ones are "M," "K" or "k," "m," "u," "n," and "p," which stand for mega-, kilo-, milli-, micro-, nano-, and pico- respectively, e.g. pF (8) stands for picofarads.
A subcircuit is another collection of nodes, branches and subcircuit instantiations. For the simple circuit we are dealing with here we do not need to know how to define our own subcircuits but we do need to know how to instantiate subcircuits since that is how transistors are implemented. Subcircuit instantiations have the form:
<name>: <circuit name>[<node names>|<actual paramter list>]
The circuits being instantiated here are a depletion transistor (9), an enhancement transistor (10), and a rectangular waveform generator (11). Transistors have their nodes in the order gate, source, drain. The actual parameters for a transistor are "L" and "W" which define the channel length and width respectively.
The plot statment (13) is the output control part of the input file. It tells Thyme to label a plot with "Nmos Inverter (4 micron, 75 C)", scale the x axis so that a one on the axis is equal to 0.1 microsecond, set the y axis min to -1 volt and max to 6 volts, and finally to plot the voltage on nodes "in" and "out".
The run statement (14) is the run control part of the input file. It causes Thyme to actually begin simulation, starting at time=0 and continuing until time is greater than or equal to TMAX, here ten microseconds.
Running It
Assume that you have prepared your input file as described in the previous section and that you have called it "Foo.thy". This section describes how to run Thyme, control it during execution and print your results.
The format of the command line to start Thyme looks like:
Thyme <file name>.<extension> <switches>
Currently the <switches> field, which is optional, may only be /c, which is the default and causes the color display to be used, or /-c to indicate that no color display is available. If you wish Thyme to read its input from "Foo.thy" then "Foo" for <file name>.<extension> is sufficient. If you have a file named "Foo.baz" where "baz" is not "thy" then the <extension> must be explicitly stated. If you do not specify a file name on the command line or if Thyme cannot find the file it will prompt you for a file name.
After Thyme has successfully opened the input file it will echo the input to the display as it is read while displaying the word "Thyme" in the cursor. If no error is detected during input then Thyme sets the cursor to a bomb and flattens the circuit so that each component is instantiated. Then the cursor changes to an exploded bomb and a few legality checks are performed on the exploded circuit. Finally the cursor will be set to a clock with one hand and the simulation will begin. Each time the solution of the circuit is advanced by one time step the hand on the clock will spin 90 degrees.
While the clock hand is spinning the keyboard is also being sampled at a low frequency. So, if you hold down Control, Left Shift, and some other key, Thyme will take the actions listed in the table below:
Key Action

Q Terminates the simulation and forces a dump file to be made.
T Terminates the simulation.
H Toggles the "hold" bit: if the "hold" bit is set, Thyme pauses when the
 simulation is over. The state of the hold bit is displayed by video reversing
 the cursor.
D Toggles the color display on and off.

Because the keyboard is being examined about once each second, you will have to hold the key down at least that long.
The listing of your input file is placed in mesa.typescript. Another file, <input file name>.log, is produced. This file contains any syntax or semantic errors that Thyme may have detected, as well as miscellaneous run-time information. The plot output will be placed in <input file name>.plot and any print output you may have requested will be placed in <input file name>.out<n>, where <n> is the number of the print statement.
Making Pictures
To convert your Foo.plot file into Foo.press type PlotPress Foo to the exec. Naturally Foo.press may be sent to your favorite printer using Empress. If you generated a color display while the simulation was running then you must send the .press file to a color printer such as Lilac, and if you generated a black and white display you should send the resultant press file to a black and white printer.
You can also put the first plot in a .plot file back up on the screen by typing PlotScreen Foo to the exec. Unfortunately there is no way to display more than the first plot.
If you are using Lilac as your printer then you should beware that it will not print more than 4 pages reliably and the first page invariably has registration problems. Plan accordingly.
If you are reading this document for the first time and have not yet run Thyme you should do so now before you read the rest of this.
Thyme and the Circuit Extractor
Suppose that you have laid out a circuit and would like to simulate it using Thyme. The first thing you do is run the circuit extractor which will produce a file say Foo.thy. This section explains what you need to do to provide the additional input Thyme requires to do a simulation.
The circuit extractor produces a file which describes the circuit in terms of the amount of area and periphery each of the interconnect layers contributes to each electrical node and the size and connection of each of the transistors. The interconnect size must be transformed into resistive-capactive networks which approximate the DC and AC loading the interconnect places on the circuit. The transistor sizes must be transformed into the parameters required by the transistor model code. This is done by a collection of circuits found in each of the process definition files.
If you were to lay out the inverter circuit used in the first example and extract it, the resulting file would look something like the following:
1 -- N o d e s
2
3 INPUT:node; ?:Stray[INPUT|aP�];
4 -- Vdd:node; ?:Stray[Vdd|aD�,pD�];
5 -- Gnd:node; ?:Stray[Gnd|aD�,pD�]
6 OUTPUT:node; ?:Stray[OUTPUT|aM�,aP�,aD�,pD�];
7
8 -- T r a n s i s t o r s
9
10 Q1:DTran[OUTPUT,OUTPUT,Vdd];
11 Q2:ETran[INPUT,Gnd,OUTPUT];
The file which you must edit to run the circuit simulation using the extracted circuit should look like the following:
1 library[MosModels];
2 library[StdFunctions];
3 circuit={
4 Vdd:node;
5 powerSupply: voltage[Vdd, Gnd]= 5.0;
6 !ThymeBasics.thy
7 !Nmos4.0u75.thy
8 !Foo.thy
9 ?:capacitor[OUTPUT,Gnd] = 0.01pF;
10 ?:RectWave[in|period← 4us, width ← 2us, tRise ← 0.1us, tFall ← 0.1us, tDelay ← 2us];
11 };
12 plot["Nmos Inverter (4 micron, 75 C)", :0.1us, -1, 6, in, out];
13 run[tMax ← 10us];
The output capacitor still appears to model portions of the circuit which do not appear in the extracted description. The only real difference here is that the nodes and transistors of the circuit are no longer typed in but are included by line (8).
Circuit Specification
Suppose that you have a collection of circuits that you need to put into your simulation that are all essentially the same except for component values. An easy way to accomplish that task is to define your own circuit. The following skeleton shows how such circuits may be defined and then used.
1 circuit[<parameter definition list>] = {
2 <node names>: node;
3 <name>: circuit[<connection name list>|<parameter definition list>] = {
4 <node names>: node;
5 <name>: resistor[<node name>, <node name>] = <expression>;
6 };
7 <name>: resistor[<node name>, <node name>] = <expression>;
8 <name>: <circuit name>[<node names>|<actual parameter list>]
9 }
A subcircuit is defined in statements (3-6). The node names used in the definition of the resistor (5) may be from the node statment within the subcircuit (4) or from the connection name list that appears in the subcircuit definition statment (3). Variables used in the expression which computes the value of the resistor (5) may come from any of the parameter definition lists (1) or (3). The node names which appear in the first node statement (2) may be used in the instantiation of the subcircuit in statement (8).
Elements of lists are separated by commas. A parameter definition is either <name> or <name> ← <expression>, which gives the parameter a default value. An actual parameter has the form <name> ← <expression>; the order of appearance of the actual parameters does not matter. The usual rules and operators apply to <expressions>.
The example below defines a circuit which one can use to test the response of a two stage RC model of a diffusion line to a step input.
circuit[width ← 2, len ← 100, lambda ← 2.5] = {
diffusion: circuit[in, out|w, l, rho ← 35, cap ← 20e-5pF] = {
r: resistor[in, out] = rho*l/w;
c: capacitor[out, Gnd] = cap*l*w*lambda^2};
input, middle, output: node;
step: voltage[input, Gnd] = 5;
section1: diffusion[input, middle|l ← len/2, w ← width];
section2: diffusion[middle, output|l ← len/2, w ← width]}
Two of the parameters of the circuit diffusion have default values, the sheet resistivity, rho, and the area capacitance, cap.
More About Output Control
Output control is made up of <print specifications> and <plot specifications> which tell Thyme what sort of output to produce. The maximum number of <print specification>'s or <plot specification>'s is ten and they may be freely mingled. The file names of the output files specified by the <print specification>'s are generated by <input file name>.out<number> with the first one in sequence being numbered zero. The first <plot specification> determines what will appear on your computer's display; all the plots will have the same aspect ratio and format.
The formats for the <print specification> and <plot specification> are:
print[<time scale> <path name><selector><scale>, <path name><selector><scale>, ...]
plot[<title> <time scale> <minimum>, <maximum>, <path name><selector><scale>, ...]

A <path name> consists of <circuit instance name>/<circuit instance name>/.../<node or branch instance name>. The possible <selector> characters are:

 Selector Selection
  node or branch voltage
 ' derivative of node voltage
 ^ branch current (flows from the positive to the negative terminal)
 @ branch value
A <scale> factor has the form ":<number>" when present; a <time scale> factor has the form ":<number>,". The value printed or plotted is the selected value divided by the scale factor. The <minimum> and <maximum> are numeric constants which define the limits of the graph. The optional <title> allows you to put some additional descriptive information on a graph. Its format is "<string>," where <string> is as defined in Mesa.
Referring to the RC example one might use the <plot specification>
plot["RC", :10ns, 0, 5, middle, output, section1/r, section1/r^:1mA]
This will plot the voltages at the nodes middle and output, the voltage across the first resistor, and the current through that resistor. The current has been scaled so that it will show up on a scale of zero through five. The string "RC" will be added to the heading of the graph.
More About Run Control
The basic function of run control is to indicate the length of time for which the simulation is to be run. The format of the run statement is:
 run[<actual parameter list>]
The only allowed <expressions> are numeric constants. The parameter tMax determines the length of the simulation. More complex run control could consist of:
 ic[<path name> ← <number>, ...];
 checkpoint[<number>];
 run[<actual parameter list>];
 dump
Here the ic statement is used to establish desired initial conditions; one may set the initial voltage on a node or the initial current through an inductor. Elements not specified default to zero. Thyme normally will begin a simulation with all node voltages and inductor currents set to zero. One may also include an assignment of the form "* ← <number>" which will initialize all nodes to the given value. The dump statement tells Thyme to produce a file, in the format of an ic statement, containing the time, the node voltages, and the inductor currents when the simulation stopped. The name of this file is <input file name>.dump. Finally, the checkpoint statement will make Thyme produce periodic dump files so that you can restart your simulation if your computer fails; the <number> specifies the period in minutes.
Syntax and Semantics
This section is the reference manual for Thyme. It describes all of the input syntax in a terse, precise manner followed by extended discussions of the semantics of each syntatic element.
Input File Syntax
Include Files
Another file may be included by means of the construct !<complete file name>. This may appear anywhere a space would, and should be followed by a space. Note that include file names must be complete with extensions. The contents of the file will be textually inserted in place of the construct.
Syntax Notation
item | item = choose one
?item = zero or one item
SMALL CAPS or puncuation other than bold ()?| = terminals
item s ... = zero or more items, separated by s; s may be one of ",", "/", or ";"
::= = keyword on left hand side is defined by the expression on the right hand side
Grammar
InputFile ::= LibraryStatements MainCircuit ?/ ?+ OutputControl RunControl
LibraryStatements ::= LIBRARY[FileName]; ...
FileName ::= Standard Alto file system name, prefix only, extension "thybcd" is assumed.
MainCircuit ::= MainCircuit Head = {CircuitBody}
MainCircuit Head ::= CIRCUIT ?([ ?(| ?FormalParameters) ])
CircuitBody ::= Declaration; ...
Declaration ::= NodeDefinition | CircuitDefinition | Name : Instance
NodeDefinition ::= NameList : NODE
CircuitDefinition ::= Name : CircuitHead = {CircuitBody}
CircuitHead ::= CIRCUIT ?([ ?NameList ?(| ?FormalParameters) ]) ?(ASSERTS [ Expression, ... ])
FormalParameters ::= ParameterDefinition, ...
ParameterDefinition ::= Name | Name ← Expression
Instance ::= BranchInstance | CircuitInstance | ModelInstance
BranchInstance ::= BranchHead[Name, Name] BranchValue
BranchHead ::= ?Condition BranchType
Condition ::= (Expression) =>
BranchType ::= RESISTOR | CAPACITOR | INDUCTOR | VOLTAGE | CURRENT
BranchValue ::= = Expression | ← Name ParametricHead | ← Name [ Number ]
CircuitInstance ::= ?Condition Name ParametricHead
ModelInstance ::= MODEL ← Name ParametricHead
ParametricHead ::= ?([ ?NameList ?(| ActualParameters) ])
ActualParameters ::= Name ← Expression, ...
Expression ::= Conjunction | Expression | Conjuction
Conjuction ::= Relational | Conjunction & Relational
Relational ::= Sum | Sum RelOp Sum
RelOp ::= < | <= | > | >= | = | #
Sum ::= Term | Sum + Term | Sum - Term
Term ::= Power | Term*Power | Term/Power
Power ::= Unary | Unary^Unary
Unary ::= Factor | UnaryOp Unary
UnaryOp ::= - | @ | / | ~ | \ | ^ | |
Factor ::= (Expression) | Name | Number
NameList ::= Name, ...
Name ::= StdName | Funny Name
StdName ::= Letter (Letter | Digit) ...
Funny Name ::= $ (AnyCharButDollar) ... $
Letter ::= one of a-z | one of A-Z
Number ::= Sign Mantissa ?Exponent ?ScaleUnit
ScaleUnit ::= ( M | K | k | m | u | n | p ) ( A | F | H | s | V)
Sign ::= ?( + | -)
Mantissa ::= ?Integer . Integer | Integer ?.
Exponent ::= (e | E) Sign Integer
Integer ::= Digit ...
Digit ::= 0 | 1 | 2 | 3 | 4 | 5 | 6 | 7 | 8 | 9
OutputControl ::= ( PrintSpec | PlotSpec); ...
PrintSpec ::= PRINT [ TimeScale ( PathName ?Selector ?Scale ), ... ]
PlotSpec ::= PLOT[ ?(String,) TimeScale Number, Number, ( PathName ?Selector ?Scale ), ... ]
TimeScale ::= : Number,
PathName ::= Name/... Name
Selector ::= ' | ^ | @
Scale ::= : Number
String ::= " (AnyCharButDoubleQuote) ... "
RunControl ::= ( RunSpec | ICSpec | CheckSpec | DUMP ); ...
RunSpec ::= RUN [ RunParm, ... ]
RunParm ::= BoolRunParm | NumberRunParm
BoolRunParm ::= BoolRunParmName ← (TRUE | FALSE )
BoolRunParmName ::= PRINTITER | PRINTSTEP | RUNGEKUTTA | PRINTALL
NumberRunParm ::= NumberRunParmName ← Number
NumberRunParmName ::= MAXITER | INITSTEP | SQUISH | TOL | DT | TMAX
| TMIN | AMITER | AMUP | INTTOL | AMDOWN | VMIN | VMAX | DVDTMAX
| DVDTFAC | TBREAK | RKERR | AMERR | AMDELAY | FLOOR | MINRATIO
| RKFAC | RETRATIO
ICSpec ::= IC [ ?(Number,) ((PathName | * ) ← Number), ... ]
CheckSpec ::= CHECKPOINT[ Number ]
Basic Elements
Names and Numbers
Names are lexically scoped. Each time a subcircuit is exploded its actual parameters are evaluated. The expressions which compute the actual parameters may only have names defined as parameters for the subcircuit being instantiated on the left hand side of the assignment. Any name within the current lexical scope may be used on the right hand side. This means that the value of a parameter cannot change within its scope. All keywords are parsed independent of capitalization. All user defined names are case dependent.
All numbers are IEEE standard 32 bit floating point numbers. Fixed point numbers are converted to floating point upon input. Whenever a number appears it may be followed by a scale factor selected from the set M, K, k, m, u, n, p which stand for mega, kilo, milli, micro, nano, and pico respectively. The scale factor may be followed by a unit selected from the set A, F, H, s, V which stand for amperes, farads, henries, seconds, and volts. The unit is ignored by Thyme and there is no check to ensure that the unit matches the type of the object whose value is being set.
Expressions
Expressions are all evaluated using 32 bit IEEE standard operations. Expressions are parsed into a tree which is then evaluated using a recursive descent algorithm. If division by zero, overflow, underflow, fixed point overflow, or any other error is detected during any operation an error message will be generated. Whenever a function is referred to in the following descriptions it is from the standard floating point library. The available operations include:
+, -, *, / The operation is performed. If "-" is used as a unary operation then the operand is negated with a unary negate. If "/" is used as a unary operation then Sqrt is called.
<, <=, >, >=, =, # If the relational expression is true then the result is 1.0, otherwise the result is 0.0.
& If the product of the two operands is not 0.0 then the result is 1.0, otherwise the result is 0.0.
| If this operator is used in a binary operation then if either of the operands is not equal to 0.0 then the result is 1.0, otherwise the result is 0.0. When it is used as a unary operator RoundLI is called.
^ For binary operations if the exponent is less then 100.0 and the first operand is an integer then the power is computed by repeated multiplication. Otherwise the power is computed using the Power function. If this operator is used as a unary operation then e is raised to the specified power using the Exp function.
@ ABS is called.
\ Ln is called.
~ If the operand is not 0.0 then the result is 0.0, otherwise it is 1.0.
Max Returns the larger of the two operands.
Min Returns the smaller of the two operands.
When a name is part of an expression the current value of that name is loaded when the evaluation procedure encounters it. If no value has been assigned to the name but a default has been provided then the default will be used. If no default has been provided and no value has been assigned then an error message will be generated.
Circuit Description
Node
NodeName, ... : NODE
Defines each of the names listed as separate vertices in the graph which represents the circuit.
Branch
BranchType [LeftNodeName, RightNodeName]
= Expression
← FunctionName [ NodeName, ... | Parameter ← Expression, ... ]
← ModelName [ ResultIndex ]
There are three types of branch instantiations. All of them take a BranchType, which must be one of RESISTOR, CAPACITOR, INDUCTOR, VOLTAGE, or CURRENT, and two node names. The node names determine which vertices the arc representing this branch will terminate on in the graph which represents the circuit. The LeftNodeName is considered to be the positive terminal of the branch.
The first type of branch instantiation equates a constant value with the branch. The second type defines a call to the function FunctionName. FunctionName must have been previously defined by a module loaded by a LIBRARY statement. During the solution process the value of a branch defined in this way depends upon the Mesa code implementing the function. The third type of branch instantiation causes Thyme to set the value of the branch to the component of the result vector of the model, ModelName, selected by ResultIndex. See the section about Libraries, Functions, and Models for more information.
Short circuited branches are not instantiated.
Circuit
CircuitName : CIRCUIT [ NodeName, ... | Parameter ← Expression, ...] ASSERTS [Expression, ...] = { CircuitBody }
Defines a circuit with name CircuitName, formal node names NodeName, ..., formal parameters Parameter ← Expression, ..., and with a graph defined by CircuitBody. Assigning an expression to a formal parameter is optional. If an expression appears it becomes the default value.
InstanceName : CircuitName [ NodeName, ... | Parameter ← Expression, ...]
Instantiates the circuit CircuitName, giving it the name InstanceName, using the actual node names NodeName, ... and the actual parameters Parameter ← Expression, ... . The node actual and formals are positionally matched. The parameter actual and formals are matched by the parameter name.
Each of the expressions in the list following ASSERTS are evaluated and if any return zero then an error message is generated.
Conditional Instantiation
( Expression ) => Branch
Circuit Instance
If the expression does not equal 0.0 then the Branch or Circuit Instance is instantiated, otherwise it is not. This allows a specific number of instances of a subcircuit to be instantiated by recursively subtracting one from the number of instances to be generated and using that to control further instantiations.
Libraries, Functions, and Models
Thyme does not contain any code within it that defines how MOS devices or function generators work. Instead Mesa code that is external to it must be written to implement these capabilities. There are two types of external code, functions and models. Both functions and models have a vector of voltages and static parameters passed to them. Functions are also passed the current simulated time. Functions return only one result which is stored as some branch value. Models may return arbitrarily many results which are also stored as branch values but these results must be independent of time.
Library
LIBRARY[FileName]
Causes Thyme to look for the file FileName.thybcd and load it. If the file cannot be found, there is a start fault, unbound procedure, control fault or version mismatch then an error message will be issued and the statement will be ignored.
The file which is loaded must match the version of spModelDefs that Thyme was compiled with.
Model
ModelName: MODEL ← ModelType [ NodeName, ... | Parameter ← Expression, ...]
Defines a model with name ModelName. ModelType must be a name which was previously defined by a module that was loaded with the LIBRARY statement. When the model code associated with ModelType is called during simulation two vectors will be passed to it. One will contain the voltage on all the nodes defined by NodeName, ..., the other will contain the list of values computed by Parameter ← Expression, ... when the circuit was exploded. The result of the model evaluation will be loaded into the branch values (see Branch). The number of NodeNames must match the number of nodes requested by the model code when it registered itself.
Control Language
Each of the IC, PRINT, and PLOT statements must be able to select a particular branch or node. This is done with path names. A path name is simply a list of circuit instance names, separated by slashes, that trace a path through the instantiation tree, finally terminating with the branch or node name of interest.
Initial Condition
IC [ InitialTime, PathName ← Number, ... ]
All variables are zeroed before the initial conditions given in the IC statment are applied. This means it is unlikely that you will want to have more than one IC statement in your simulation. PathName must terminate with the name of a node or an inductor branch. The voltage of a node or the current through the inductor will be set to the number given. If PathName is simply a "*" then all nodes are set to the number given. InitialTime is optional. If given it sets the starting time of the simulation.
Print and Plot
PRINT [ :TimeScale, PathName Selector : Scale, ... ]
PLOT [ " Title String ", :TimeScale, YMin, YMax, PathName Selector : Scale, ... ]
There may be a total of 10 PRINT and PLOT statements. The first PLOT statement determines what will appear on the display while the simulation is running. The file names of the output files specified by the PRINT statements are generated by input file name.outnumber with the first one in sequence being numbered zero. All the plots will have the same aspect ratio and format.
The TimeScale that is associated with the PRINT statement divides the simulated time before printing of the time occurs on each output line.
The PLOT statement allows some arbitrary descriptive information to be put onto the plot via the Title String. The TimeScale divides the horizontal axis values by the given amount. YMin and YMax are numeric constants that set the vertical axis minimum and maximum in volts.
Both the PRINT and PLOT statements take a list of path names that may each have a Selector and/or a Scale appended to them. The Selector determines what kind of value is printed or plotted given a selected node or branch. The Scale determines the factor that the value is divided by before output actually occurs. The legal Selector characters are:
nothing node or branch voltage
' derivative of node voltage
^ branch current (flows from the positive to the negative terminal)
@ branch value
Run
RUN [ NumberParm ← Number, BoolParm ← Bool, ... ]
All of the parameters are read and then the simulation proceeds. The boolean parameters all default to FALSE. They include:
PRINTITER When true the number of Gauss Sidel iterations required to advance to the current time step is printed in every print output file.
PRINTSTEP When true every step causes print and plot output to occur. When false output occurs at a rate depending upon the value of DT.
RUNGEKUTTA When true forces the integration method to always be Runge Kutta rather than switching to Adams Moulton.
PRINTALL When true causes the node equasions to be printed before the Gauss Sidel iterations begin. On each iteration causes the simulated time and iteration count to be printed. For each node considered in each iteration the node name is printed. If the node is being integrated then the previous derivative of the voltage, the new derivative of the voltage, and the total capacitance on the node is printed. If the node is attached to a voltage supply and this node is being used to set that supply's current then the old current through the supply and the new current through the supply are printed. If the node is neither being integrated nor being used to set a voltage supply current then the old voltage and the new voltage are printed.
The numeric parameters with their defaults are:
MAXITER ← 20 Sets the maximum of iterations the Gauss Sidel procedure will go through before it complains that the iteration count has been exceeed. If the solution does not converge before twice this parameter's count of iterations have been performed then the Mesa signal solveError is raised with the message GS did not converge and Thyme falls into the debugger.
INITSTEP ← 0.1 If there is no voltage change occuring when simulation begins or if the voltage change is so small that the integration step size would be large then the initial integration step size is set using this parameter.
SQUISH This parameter is a synonym for INITSTEP. Setting it changes the same Mesa variable as setting INITSTEP.
TOL ← 0.001 During Gauss Sidel iteration a node is considered to be converged if it is being integrated and the tolerance set by this parameter is greater than or equal to the ratio of the difference between the old voltage derivative and the new voltage derivative and the maximum of the old voltage derivative and the new voltage derivative. If the node is setting the current through a voltage supply then the node is considered to be converged if the tolerance is greater than or equal to the ratio of the difference between the old supply current and the new supply current and the maximum of the old supply current and the new supply current. If the node is neither being integrated nor being used to set a voltage supply current then the node is considered to be converged if the tolerance is greater than or equal to the ratio of the difference between the old node voltage and the new node voltage and the maximum of the old node voltage and the new node voltage.
DT ← TMAX/200 Determines the rate at which the solution will be sampled. It must be small enough that the shortest event will be seen. The integration time step will never be longer than this parameter. It sets the approximate printing and plotting intervals.
TMAX ← 0.0 Sets the minimum simulated time that the simulation will terminate at. Because discrete steps are taken the actual termination time may be slightly greater than the value of this parameter.
TMIN ← 0.0 Sets the time that simulation will begin at.
AMITER ← 2 Controls the number of times that the corrector will be applied during Adams Moulton integration.
AMUP ← 1.25 If a ratio computed by Adams Moulton integration is greater than this parameter and Adams Moulton integration has been running at least the number of steps set by AMDELAY then the step size will be multiplied by the square root of the square root of the ratio. The ratio is computed by taking the ratio of the integration tolerance set by INTTOL and the error computed by multiplying AMERR by the ratio of the change in voltage and the maximum of the new and old voltages.
INTTOL ← 0.001 Used to decide if the integration error is reasonable. If this parameter is less than the error computed as described in the AMUP description then the error is considered to be too large, the step size is reduced and the solution process starts over at the last good point. Also used to compute the initial step size.
AMDOWN ← 0.8 Not currently used.
VMIN ← -100.0 Before the solution is advanced to the next time point a check is made to ensure that no node's voltage has gone below VMIN, nor above VMAX, nor that the first derivative of any node has gone above DVDTMAX. If any of these conditions hold then Thyme falls into the debugger.
VMAX ← 100.0 See above.
DVDTMAX ← 1.0E13 See above.
DVDTFAC ← 5.0 This parameter is multiplied by the integration tolerance to develop a factor that decides if a node is quiescent. If the factor times the maximum current through any branch into a node is greater than the net current into the node then the node is marked.
TBREAK ← 0.0 Sets a time at which the solution procedure will go into an infinite loop. This is useful so that the debugger can be invoked at some particular simulated time.
RKERR ← 0.01 During Runge Kutta integration this parameter multiplies the ratio of the difference of the new voltage and the old voltage and the maximum of the new voltage and the old voltage before the ratio is compared to the integration tolerance.
AMERR ← 0.01 Same as RKERR but for Adams Moulton integration.
AMDELAY ← 5 Minimum number of good steps that must be taken by Adams Moulton integration before the step size may be made larger.
FLOOR ← 0.01 The voltage on a node must be greater than this parameter before it will be checked against the integration tolerance.
MINRATIO ← 0.8 If an integration attempt does not succeed then the step size must be reduced by multiplying it by a number less than or equal to this parameter.
RKFAC ← 1.0 When the integration method is Runge Kutta and the step size is reduced the square root of the raw ratio computed by the integration routine is multiplied by this parameter before being used to reduce the step size.
RETRATIO ← 0.5 When a model or function routine raises the signal Retreat then the step size is multiplied by this parameter before the solution process is restarted.
Many of the parameters are intended for wizards only. With the exception of TMAX and TMIN there should normally be no need to change any of them.
CheckPoint
CHECKPOINT[ Number ]
Every Number of minutes write a checkpoint file with the name Foo.dump, where Foo is the input file name, which contains an IC statement with the current simulation time, the voltage on each of the nodes, and the current through each of the inductors. Modifying your input file to include the .dump file where an IC statement would normally go will allow you to restart a simulation.
Dump
DUMP
If this statement is placed after a RUN statement then a checkpoint file will be made for the state of the simulation when it terminated.
Instrumentation
The "/" and "+" that appear in the first rule of the grammar are meant for debugging by wizards. The slash causes the circuit tree which is built up by the input phase to be dumped. The plus sign causes the exploded circuit to be dumped.
Circuit Topology Limitations
A legal circuit must meet the constraints listed below to ensure the integrity of the circuit equations.
1. Each node must have a DC path to the distinguished node, Gnd (the reference point). A capacitor will of course interrupt a DC path.
2. Loops of voltage sources or voltage sources and inductors are not allowed.
3. At least one branch connected to a node must be something other than a current source or an inductor.
Standard Support Files
The support files need to be understood by the more than casual user. This section explains the contents of those files in some detail.
ThymeBasics.thy
This file is the interface between the Thyme input file which the user writes and the Mesa code which models active devices such as transistors and diodes and provides time dependent voltage functions that act as the stimulus to the circuit. The active device models will not be explained because they are very complex. The notes on their use through the process files is the only explanation which is unique to Thyme. This explanation is provided in the next section.
There are four circuits which provide time dependent voltage sources. Each of these takes one node, output, as the actual node to which the voltage will be applied. Pulse and RectWave generate periodic waveforms. OneShot generates a single pulse, i.e. two transitions. Step generates a single transition. There are a number of parameters which are used to control these circuits. The following list explains each of these parameters. Not all of the parameters are used in each of the circuits. Every circuit has the notion of active and inactive periods of time. All of them allow the voltage levels for the active and inactive periods to be set independently. All of them are considered to be inactive at time 0.
amplitude Used by Pulse to add to the offset to set the voltage level produced during the active period.
offset Used by Pulse to set the voltage level used during the inactive period.
OnLevel, OffLevel Used by RectWave, OneShot, and Step to establish the active and inactive voltage levels respectively.
period Used by Pulse and RectWave to set the sum of the time of the active and inactive periods.
width Used by Pulse, RectWave, and OneShot to establish the active period. Note that the time that the output spends actually at the active level depends upon the rise and fall times, i.e. the rise and fall times are taken from the time during which the output is active.
tRise Used by Pulse, RectWave, OneShot, and Step to set the transition time from the inactive level to the active level.
tFall Used by Pulse, RectWave, and OneShot to set the transition time from the active level to the inactive level.
tDelay Used by Pulse, RectWave, OneShot, and Step to delay the beginning of whatever voltage generation the circuit is to perform. The output of the voltage supply will remain at the inactive level until the time specified by tDelay has expired.
The voltage sources have assertions which check that the width is less than the period and the sum of the rise and fall times are less than the pulse width.
Process Files
As we recall from the introduction each of the process files has a name of the form:
<process type>|<feature size>|<temperature>.thy
Where process type may be NMOS or CMOS, feature size may be 4.0u or 2.0u and temperature may be one of 25, 50 or 75 (in degrees centigrade). All the process files are stored on [Cherry]<Thyme>ProcessDefs>. The files which are actually available right now are:
CMOS2.0u25.thy - This is for an experimental 2.0m CMOS process.
NMOS4.0u25.thy - These files are for the standard NMOS process.
NMOS4.0u50.thy
NMOS4.0u75.thy
Within each of these files are a number of circuits that specify the electrical properties of each process. Both the active device parameters and the parasitic parameters are included.
NMOS has two active device types, enhancement and depletion N channel transistors. These are modeled by the circuits ETran and DTran respectively. Both the transistor circuits take the gate, source, and drain as node formals and have the length, L, and width, W, of the channel, as well as the source extension, sourceExtension, and the drain extension, drainExtension, as parameters. The bulk is assumed to be tied to ground.
There are several circuits used to model parasitic effects. WireCap models the capacitance from poly, 1rst layer metal, or 2nd layer metal to bulk by converting the area and perimeter into a fixed capacitor. Note that this does not take into account the difference in capacitance due to stacking of layers, e.g. if 1rst layer metal runs on top of poly the capacitance from 1rst layer metal to bulk will decrease due to the increased space between the metal and the bulk and if the poly and metal run parallel for a reasonable distance there will be a capacitor coupling the two lines together. DifCap models the capacitance and leakage of diffusion runs. WireRes produces a resistor to model the resistance of 2nd layer metal, 1rst layer metal, poly, or diffusion for those situations where the RC delay of a circuit is important.
Do not use the resistor models gratuitously since introducing nodes into your simulation with time constants greatly different from the time constants generated by the transistor - parasitic capacitance interactions will slow down Thyme substantially and can cause it to become numerically unstable.
ConRes is intended to model the resistance of a number of parallel contacts connecting two layers together. It may not be important for the 4m processes unless you stitch through contacts a lot but will become more important with the more advanced processes because the contact resistance increases with scaling instead of decreasing.
CMOS also has two active device types, enhancement N channel and enhancement P channel transistors. These are modeled by the circuits NETran and PETran respectively. These transistor circuits take the gate, source, and drain nodes as formals, just as the NMOS transistors do, but in addition take the bulk node. Presumably you will always connect the bulk of the N channel devices to ground and the bulk of the P channel devices to Vdd so perhaps we will change the circuit definitions to do this for you. Currently no parasitics are available for CMOS.
Circuit Design Pragmatics
Process Dependence
Talk about how much variation in performance one can expect because of manufacturing variations. Discuss how yield varies with die size.
Temperature Dependence
Talk about how to chose the simulation temperature given theta(j) and the expected ambient. Put a few typical values for theta(j) and expected ambients in an example. Give a simple rule for the effect that temperature has on performance.
To Layout or To Simulate, That is the Question
Talk about design methodology of laying out first versus simulating first. Give an example.
Transistor Sizing
Talk about rules of thumb for sizing transistors. Include some typical sizing charts for 4m NMOS.
Parasitic Load Calculation
Show how to estimate it. Discuss things to watch out for such as bootstrap node loadings, dynamic node leakage.
Electromigration
If you try to put too much current through a wire on one of the layers of your integrated circuit the wire will disintegrate where the line has the highest current density. This can be because you have put so much current through the wire that resistive heating has boiled off the film from which your wire was constructed. This sort of failure will occur soon after you turn the power on and so will be relatively easy to detect. It is unlikely to occur unless you severely exceed the maximum voltage or current for which the circuit was designed. A more insidious type of failure is caused by electromigration. Electromigration is a mass transport phenomenum that is caused by the average electron wind. Since it is the average current that is important lines which carry alternating current signals will not be affected by reasonable amounts of current. Current design rules call for a maximum of 1.5ma/m of metal line width for both first and second level metal. If you exceed this rating then your circuit will fail, some day, where some day is much sooner than you might expect but long after you have tested your circuit to the point that you believe that it is reliable.
Internals
The Organization of Thyme
Thyme is made up of nine implementation modules and two global definitions modules which tie the whole thing together. These are:
spGlobals
spModelDefs
spGlobalsImpl
spInput
spBomb
spExpressions
spAnalysis
spSolve
spOutput
spMain
The divisions are historical in derivation, but there is usually some method to the madness. Each of these modules is described briefly below. Additional modules implement the various voltage sources and transistor models; but these are not part of Thyme itself.
spGlobals
This is the global definitions module. Essentially all of Thyme's data structures are defined here, sometimes even if they are not global. This also has, of course, all the public procedures that the various modules export. These are ordered by the implementation module, so that it is easy to figure out who implements what.
spModelDefs
This is a small definitions model which defines the interface between Thyme and the external modules which implement the desired functions and models. The bcd's which provide the implementations must have names of the form foo.thybcd.
spGlobalsImpl
The scanner, the allocators, and some miscellaneous service routines are implemented by this module. These services could probably have been gotten from someplace else.
spErrors
All error handling is done here. It opens the error message file on demand and logs the error. See the file thyme.errors for an example of the error file format.
spInput
The syntax analysis for circuit specifications is done in this module. It builds the symbol table (kept as a linear list) and a structure from which the exploder can instantiate the circuit.
spBomb
This module explodes the circuit, taking the intermediate structures made by spInput and producing the structures which are recognized by the rest of Thyme. It augments the symbol table so that individual instances of nodes and branches can be reached by path names.
spExpressions
This parses arithmetic expressions and produces trees from which the expressions can be evaluated. It also handles the evaluations. Thyme uses its own APL-like single character codes for the basic mathematical functions (a unary "/' means square root). The best (and the absolute) description for the character-function corrrespondence is this module's source.
spAnalysis
The topology of the exploded circuit must be checked to make sure that none of the constraints imposed by the circuit equations are violated. In addition, some links must be filled in to calculate the currents through voltage sources.
spSolve
This module contains all the numerical stuff. There is an extensive list of parameters which control it, and it takes care of parsing these as well; that is, it parses the parameters of the "run' command.
spOutput
The "print' and "plot' commands are parsed and executed in this module. This is the only connection to the plotting software.
spMain
This is the main program. It recognizes the top-level commands (e.g. "library,' "circuit,' "run'), and directs their interpretation. It also handles the keyboard commands and the automatic checkpointing.
At present there are two modules which implement the standard functions and models: their source names are spFunctions and spModels. As the names imply, spFunctions supplies all the signal sources, which are implemented as functions, while spModels has the code for the transistor models. Their bcd's are renamed to stdfunctions.thybcd and mosmodels.thybcd respectively.
Thyme's Circuit Equations
Thyme is based on Kirchoff's Current Law, which says that the sum of the currents flowing into a node must equal zero. For each node, then, there is a sum of terms, one for each branch connected to the node. The terms are of five kinds, corresponding to the five basic circuit elements that are the basis of Thyme. If we are summing the current at node n, we have five cases, in which iB is the current flowing into node n from node m through branch B.
Resistor. iB = (vm  vn)/RB.
Capacitor. iB = (v m  v n)CB. Note that Thyme does not differentiate the capacitance as one might expect from the underlying physics, that is i = q = (Cv) = Cv + C v. This is because device models define the "capacitance' to be C = dq/dv, so that i = dq/dt = Cdv/dt. One can construct an exact model for a time-varying capacitor using two branches in parallel, one a capacitor to get the term Cv ' and the other a resistor to get the C 'v term; the value of the resistor would be 1/C '. In general, a node connected to a capacitor will be integrated.
Inductor. i B = (vm  vn)/LB. The voltage difference vm  vn is integrated to compute the current through the inductor. Time varying inductors are illegal in the current implementation, but one could change this.
Voltage source. iB = IBmn = IBnm. The positive direction of current flow is from the positive terminal to the negative terminal. One terminal of a voltage source must be used to compute the current flowing through the source. This is figured out during the topological analysis; the curPtr field of a node record points to the the voltage source whose current is to be determined, and the voltage at this node is computed by adding the source's voltage to or subtracting it from the node voltage at the other terminal. Voltage source values are numerically differentiated if needed.
Current source. iB = IBmn = IBnm. The positive direction of current flow is from the positive terminal to the negative terminal.