ThymeDoc.tioga
Sweetsun Chen, April 26, 1986 9:32:49 pm PST
Bertrand Serlet July 26, 1986 0:36:54 am PDT
THYMEDOC
CEDAR 6.0 — FOR INTERNAL XEROX USE ONLY
ThymeDoc
A circuit simulator in Cedar.
Sweetsun Chen
© Copyright 1985 Xerox Corporation. All rights reserved.
Abstract: Thyme is a circuit simulator originally written in the Alto environment in 1982, and ported to Cedar in 1984. This documentation only dicusses the special features of its Cedar version.
Created by: Neil Welhelm
Maintained by: SChen.pa & DAToolsImplementors^.pa
Keywords: Circuit Simulation, Graph, Timing Diagrams.
XEROX   Xerox Corporation
    Palo Alto Research Center
    3333 Coyote Hill Road
    Palo Alto, California 94304

For Internal Xerox Use Only
1. Getting started
1.1. Load and Run
1. Thyme.df
BringOver necessary files using the following command in the CommandTool:
% BringOver -p /DATools/DATools6.0/Top/Thyme.df
2. UserProfile
Thyme currently expects 8 bits per point on your color monitor. To set your color monitor properly (once and for all), just put the following lines in your user profile if they are not there yet:
ColorDisplay.Side: left -- or right, if you like.
ColorDisplay.BitsPerPoint: 8
ColorDisplay.Type: 640x480 -- or 1024x768, depending on your monitor.
3. Load and run
Type
% thyme <return>
in the CommandTool (after bringing over), and a Thyme viewer will be created. Give it your input file name (say, CmosInverter, which should have been brought over with Thyme.df) and click Run on the Thyme viewer to start the simulation.
You may simulate another circuit using the same viewer when the previous run is completed. Just change the input file name to another and click Run. Typing thyme <return> in the CommandTool again will create another instance of Thyme, which may be used to simulate other circuits concurrently.
1.2. Documentations
1.2.1. ThymeManual - [DATools]<DATools6.0>Thyme>ThymeManual.tioga
This is the users manual for Thyme written by Rich Barth. It introduces the use of Thyme and how it works. Both Alto Thyme and Cedar Thyme users will find it useful.
1.2.2. ThymeDoc - [DATools]<DATools6.0>Thyme>ThymeDoc.tioga
This is a supplement to ThymeManual for users running Thyme in Cedar. It describes features of Cedar Thyme not covered by the ThymeManual.
1.2.3. GraphDoc - [DATools]<DATools6.0>Graph>GraphDoc.tioga
This is the documentation on the Graph package associated with Thyme. The first section in GraphDoc.tioga is a tutorial, which can help the user get acquainted with the Graph package in a short time.
2. Viewers
The Cedar Thyme may create two types of viewers. The one created after you type
% thyme <return>
in the CommandTool is the Thyme viewer. The PLOT or RUN statement in the input file may create another type of viewers, called Graph viewers.
2.1. Thyme viewer
The Thyme viewer is initially created in the iconic state and looks like five basic circuit elements connected together. Once opened, it will show three regions under the white on black caption bar, as described below.
2.1.1. The menus
There are initially five menus shown in this region, namely, Stop, Dump Run, New and TypeScriptMenus. The last menu, TypeScriptMenus, may create (or destroy) six more menus beneath these five menus. The six additional menus deal with the typescript. They are: Save, Reset, Find, Word, Def, and FindError.
2.1.1.1. The Stop menu
The Stop menu will abort the simulation without saving anything. Since this is somewhat destructive, the button is "guarded" by a short line segment, indicating that this button needs confirmation to take effect. If you want to stop the simulation, you should first click at it so that the little guard disappears; if you click at it again while the guard has not reappeared, this will serve as a confirmation to stop it.
2.1.1.2. The Dump menu
The Dump menu may abort the simulation but also save the calculation that has been done so far, to be used as the initial condition of some later simulations. (See ThymeManual for more details about the IC command.)
2.1.1.3. The Run menu
The Run menu simply starts the simulation.
2.1.1.4. The New menu
The New menu may create another instance of the Thyme viewer, which may be used to simulate another circuit concurrently -- or appear to do so.
2.1.1.5. The TypeScriptMenus menu
The TypeScriptMenus menu is a toggle, which may create (or destroy) six menus beneath these five menus.
2.1.1.6. The Save and Reset menus
The Save and Reset menu buttons will save or reset the typescript viewer and its backing file, Thyme.log.
2.1.1.7. The Find, Word, and Def menus
The Find, Word, and Def menu buttons are similar to the ones in a Tioga viewer, which may search texts, words, or definitions in three different "search directions" depending on which mouse button is clicked. Clicking with the shift key held down means that you don't care about the case of characters.
2.1.1.8. The FindError menu
Similar to the above three searching buttons, the FindError button searches for error messages.
2.1.2. The middle region:
There are four text lines in this region. They have to do with the working directory, the input file, the output file, and the progress of simulation, respectively.
The first line shows your working directory.
The second line shows your input file name. You may specify your input file name here. It is assuming an extension of ".thy" and the highest version, so you may omit the extension and the version number if that's the case.
The extension may not be omitted when the version of the file is specified.
The third line shows your output file name(s) automatically once a simulation is started.
The last line indicates the progress of the simulation. There is always a cursor sized pattern in the blank region after the label Progress. The patterns are similiar to those employed by the Alto Thyme, except that, when Thyme is in idle state, an anchor is shown; and when Thyme is parsing the input file, an eyeball is shown.
If you want to see the detailed time/step information, let the details button be turned on (white letters on black blackground). You may turn it on or off by clicking at the details button.
In principle, the simulation should take less time when it's turned off, but the difference should be very little.
If you are not interested to see input statements echoed in the typescript when Thyme is reading the input, you can turn the EchoInput switch off (to black letters on white background).
2.1.3. The typescript:
This area is a typescript for messages sent out by Thyme. The texts are automatically stored in the file called "Thyme.log".
You may clear the typescript by the Reset menu button if you are not interested in what has been shown in it any more. You may save the typescript by clicking the Save button; but remember to rename this version of Thyme.log to a different name, otherwise later versions of Thyme.log may overwrite it.
2.2. The Graph viewer
2.2.1. Creating graphs by RUN or PLOT statements
The RUN statement and the PLOT statement(s) will create graphs for you. The Graph viewers so created are related to the Thyme viewer until the simulation is finished or aborted, so they may not be destroyed during the simulation.
The graph created by the RUN statement is capable of displaying any node voltages or branch currents at your request, although initially it only shows the first six items it finds in your circuit.
The graph(s) created by the PLOT statement(s) in your input file only shows those items listed in the statement. And you could not change them during the simulation.
2.2.2. Reviewing and editing graphs
The graphs created by previous simulations may be reviewed by the "graph" command in a CommandTool, or the Get or Merge menus on a Graph viewer. The graphs may be edited or using the facilities provided by the Graph package. Clicking the Interpress menu on a Graph viewer can create an interpress master for the graph.
There are nine menu buttons and some keyboard commands available on the Graph viewer for the convenience of examining or altering the graphs. In addition, each Graph viewer can create a graph "controller", with other convenient facilities.
2.2.3. Tutorial for the Graph package
For more details about the Graph package, please see GraphDoc.tioga, which should have been brought over with Thyme.df to your disk. The first section in it is a tutorial. It is expected that by following the steps in the tutorial, the user may easily get familiar with the Graph package in a short time.
3. Differences of Cedar Thyme from its Alto version
3.1.1. Multiprocessing
Being in Cedar, we enjoy the convenience of running more than one programs at a time. It is therefore possible for you to see more than one graphs for a simulation (and if you like, run more than one simulations) and work on other things at the same time.
3.1.2. The concurrent/post processor
Thyme has been modified such that all simulation data (i.e., the voltages of every nodes, and the currents of every branches) may be saved automatically, if the "Save All" switch is turned on. With the use of the Graph package, the user can examine or manipulate any of these data interactively during or after the simulation.
3.1.3. Library models and functions
We don't have to specify any of the the following library statements at the beginning of the input file, for they are included by default.
library[MosModels];
library[StdFunctions];
library[Level2Model];
For those modeling wizards: the library statement still works to include any special models of your own.
3.1.4. RUN statement:
The RUN statement has some new functionalities. Similar to a PLOT statement, 1) the RUN statement automatically creates a "master graph" saving all node voltages and branch currents; 2) we may put some text enclosed by double quotes to specify a title for the master graph.
In addition to those listed in ThymeManual, the RUN statement accepts some other parameters as listed below. The effect of the MaxIter is changed a little.
3.1.4.1. ShowRetreat
Default FALSE. Iff true, all "retreat" messages will be displayed on the typescript. This should be of no interest to most users. For details, see the integration procedure in spSolve.mesa.
3.1.4.2. SaveAllData
Default TRUE. Iff true, all node voltages and branch currents will be saved in the master graph.
3.1.4.3. tUnit, iUnit, and vUnit
Setting the units for time, current and voltage. The defaults are nsec, mA and Volt. They affect the data saved in the master graph only, without affecting graphs created by the PLOT statement.
3.1.4.4. yMin and yMax
Suggested minimum and maximum limits for the y axis of the master graph. But when auto-bounds is TRUE for the graph (which is the case unless user changes it), the graph may still adjust itself ignoring these values.
3.1.4.5. MaxIter:
The paragraph in ThymeManual about MAXITER should be modified to read:
MAXITER ← 20 Sets the maximum of iterations the Gauss Sidel procedure will go through before it complains that the iteration count has been exceeed. For Alto Thyme, this parameter may be specified to be 0 up to 32767; and for Cedar Thyme, it may be 0 up to 2147483647 (=LAST[INT]). If you specified a value greater than 32767 for this parameter with Alto Thyme, it may not work.
When this limit is exceeded, Thyme will give you a message telling you so, but still try to go on, until it converges or exceeds the actual limit of iterations. For Alto Thyme, the actual limit of iterations that may be performed is twice this parameter's value. For Cedar Thyme, it is the minimum of twice this parameter's value and 2147483647. If the solution has not converged when this actual limit of iteration count is reached, the signal "solveError" will be raised with the message "GS did not converge", and Thyme will fall into the debugger.
3.1.5. programmable interface:
Following is a simple example of the codes to invoke a simulation in batch mode programmably.
OPEN spGlobals;
handle: Handle ← MakeThymeViewers[];
BatchRun[handle, , "InputFile.thy"];
-- When wDir is not provided, default is FileNames.CurrentWorkingDirectory[].
Note:
1. During a simulation a Thyme viewer is guarded from being destroyed, i.e., handle.outer.inhibitDestroy is TRUE.
2. If a Thyme viewer is destroyed before or after a simulation, most of the pointer fields (e.g., outer) in the ThymeToolRec pointed to by the Thyme Handle associated with the viewer are nil'd. Thus if you find, say, handle.outer is NIL, then the Thyme viewer must have been destroyed.
4. CommandTool commands
4.1. Command syntax
This package registers a command, "Thyme", in the CommandTool to start instance(s) of circuit simulations. The command syntax is simply:
% Thyme {files}
where {files} := one or more instances of [switches] {filePattern}, where switches are optional (see 4.2. below), and filePattern may contain "wild" characters (see 4.3. below).
Note that ".thy" is automatically appended if omitted in filePattern.
4.2. Switches:
The meaningful switches are:
-h or -H => (Highest version only. Default TRUE)
Only the highest version of circuit description files (.thy files) whose names match the filepattern are processed.
-a or, -A => (All versions. Default FALSE)
All versions of .thy files that agree with the filepattern are processed.
-# => (The max number of .thy files to open is #. Default 12)
Sets the limit of the number of circuits to be simulated to #, where # is a number.
A switch affects all files opened thereafter until overridden by a different switch. Illegal switches are ignored.
4.3. Examples:
% Thyme foo*
Simulate all .thy files with file names matching the pattern "foo*.thy". For each file matching this pattern that has more than one versions, only the latest version is opened unless the a switch is used. (See example below.)
% Thyme foo.thy -a cmos*
Simulate the latest version of foo.thy; then simulate all versions of files with names matching "cmos*.thy" .
5. Users distribution lists
Thyme users are welcome to add themselves to ThymeUsers^.pa and DAToolsUsers^.pa to receive update information about Thyme and other DATools.
We would like to make Thyme as useful and friendly as possible. Please send any comments or complaints me.