Features
Introduction
This page describes the implementation-specific features of MacSpice, further information is available in the MacSpice Userguide and Release Notes. Broadly speaking, MacSpice is compatible with the original Berkeley Spice 3f4 as described in the Spice 3f4 Userguide. If you want to learn Spice from scratch, refer to the Tutorials page.
Colour PostScript Hardcopy
To make the hardcopy command produce colour PostScript use:
set hcopydevtype=postscript
set hcopypscolor
The variables 'hcopyheight' and 'hcopywidth' can be used to set the image height and width in points. For more details, refer to the Plot Colour Schemes section of the MacSpice 3f5 Examples webpage.
Command Line Editing
The MacSpice console has command and file completion, and command-line editing keystrokes. Users who switch between MacSpice and Un*x systems should feel at home.
| CTL-A | move cursor to start of line |
| CTL-B or left-arrow | move cursor back one char |
| CTL-D | delete forward from insertion point |
| CTL-D at end of line | prints a list of possible completions |
| CTL-F or right-arrow | move cursor forward one character |
| CTL-H | delete back from insertion point |
| CTL-K | delete from cursor to end of line |
| CTL-N or down-arrow | scroll down through history stack |
| CTL-P or up-arrow | scroll up through history stack |
| CTL-U | delete entire line |
| ESC or TAB | automatically types the completion as far as possible |
Text outside the editable region can be selected and copied, but not changed. The variable 'ignoreeof' is now set by default because otherwise it is rather too easy to type CTL-D at the command prompt and lose everything. To get a list of all commands type a space followed by CTL-D at the prompt.
If the command contains history references, typing TAB (or ESC) will expand these.
Convergence Aids
The simulator options 'gminsteps' and 'srcsteps' control the way MacSpice searches for the DC operating point. Setting one or both of these to the value 1 will cause MacSpice to use an adaptive step-size algorithm.
During a transient analysis Spice increases the timestep when the going is good, and cuts it back when things get tough. In particular, if the ratio of 'Rejected timepoints' to 'Accepted timepoints' displayed by the command rusage all exceeds about 10% the simulation will be extremely inefficient. Using the command:
set debug = timestep
will make MacSpice print its reasons for making substantial reductions in the timestep during the run.
The local truncation error estimation in the original Berkeley 3f5 release is fundamentally flawed. The algorithm has been re-developed for MacSpice and the default value for TRTOL is now 1.
MacSpice has a nodesets command that saves the state of its current analysis as a file of nodeset commands suitable for inclusion in a netlist. This is useful in cases where the operating point is difficult to find.
After a convergence failure, the command dump will display the node voltages and branch currents calculated by the final two interation and indicate the one(s) that failed to meet the convergence criteria.
Cursor Measurements
When the cursor is positioned over a graph in a window, a helptag displays the corresponding values. Dragging allows measurements of changes. Double-clicking transfers the displayed value to the command line.
DC Transfer Function
In addition to voltage and current sources, the DC Transfer Function can can sweep the value of resistors and/or circuit temperature ('temp').
Graphs
The base pen-thickness used to display graphs is selected automatically and
depends on the fontsize selected. The command 'set pensize = N' where 1<=N<=10
is measured in points, overides this behaviour. Default behaviour is
restored by 'set pensize = 0'.
Edit Command
The MacSpice edit command uses Apple Events to invoke a helper application and supports the ODB Editor Suite. It is strongly recommended that an ODB-compliant editor is used with MacSpice. If your favourite editor is not one of these, consider switching to the excellent TextWrangler (freeware) or BBedit (there is a freeware 'Lite' version of BBedit for systems earlier than MacOS X 10.3.5). ODB allows tigher integration between MacSpice and the editor. For example, MacSpice to pre-type an appropriate 'source' command in response to editor activity. If this is not required, it can be cleared by typing CTL-U (see above).
The default is set to TextWrangler by this line
set editor = '!Rch'
in the 'Library:MacSpice:lib:scripts:spinit' file. Users change this default by specifying an alternative creator code either in the spinit file, or by setting the 'editor' variable. This table gives the creator codes for some popular editors that support ODB:
| Editor | Creator Code | Licence | Publisher |
|---|---|---|---|
| TextWrangler | !Rch | Freeware | Bare Bares Software |
| Smultron | SMUL | Open Source | Peter Borg |
| AlphaX | ALFA | Commercial | Alpha Cabal |
| BBedit | R*ch | Commercial | Bare Bares Software |
| SubEthaEdit | Hdra | Commercial | Coding Monkeys |
| TextMate | TxMt | Commercial | Macromates |
File Names and Paths
MacSpice uses the MacOS Hierarchical File System (HFS) to refer to pathnames and files and as a
result ':' is the path separator. An HFS path that begins with a colon is a relative path, in
MacSpice it is relative to the current directory which can be inspected and/or set with the 'cd'
command. HFS paths differ from other operating systems in the number of separators needed to refer
to objects higher up in the directory hierarchy. For instance, under Unix, you would use
'../../filename' to get to a file two levels above the current directory; in HFS you
need three separators (i.e., ':::FileName' )
HFS paths that do not begin with the path separator ':' are absolute. The first element is the volume name, e.g.
| HFS: | Macintosh HD:folder:subfolder:filename |
| Unix: | /Volumes/Macintosh HD/folder/subfolder/filename |
An HFS specification that containins no colons refers to a file in the current directory.
MacSpice treats the single character '#' as a pseudo-filename signalling that a file, or folder, is to be selected using a Navigation Services dialog box. When this mechanism is used to open files, they can be sorted by date or name and you have instant access to recently opened files or 'Favourites'. Drag a folder or file from the Finder into Navigation Services and it will open and reset the default to that location.
A standard installation of MacSpice searches for files in two places which are specified in the list $sourcepath
MacSpice 1 -> echo $sourcepath[1]
:
MacSpice 2 -> echo $sourcepath[2]
Macintosh HD:Users:RLM:Library:MacSpice:lib:scripts:
The set command can be used to change the sourcepath list, e.g.
MacSpice 3 -> set sourcepath = ( $sourcepath 'Secondary:test:' )
MacSpice 4 -> echo $sourcepath[3]
Secondary:test:
Spaces and strange characters in pathnames need quote protection. Bash(1) style single-, double- and backslash-quoting can be used as required.
Use cd to check the current
directory (initially set to the '~:Documents:MacSpice:' directory that was created
when MacSpice was first run, but can be altered using the defaults(1) command), i.e.
MacSpice 5 -> cd
Current directory is: Macintosh HD:Users:cdhw:Documents:MacSpice:
To change the current directory to /Volumes/MP1/CAO/SPICE/cir/ type
MacSpice 6 -> cd MP1:CAO:SPICE:cir:
and note the command completion described above. For a more Mac-like experience, type
MacSpice 7 -> cd #
which will allow selection of a folder using a standard navigation dialog.
File Types and Formats
MacSpice creates and opens various file types with creator code 'RTSP':
| Icon | Type | Extension | Open action | Notes |
|---|---|---|---|---|
 |
TEXT | .cir .net .src .sp3 |
MacSpice -> source filename | MacSpice Source File Mac '\r' line breaks. |
 |
RAWT | .rawt | MacSpice -> load filename | MacSpice Text Rawfile. Mac '\r' line breaks. |
 |
RAWB | .rawb | MacSpice -> load filename | MacSpice Binary Rawfile. Unix '\n' line breaks. |
Many freeware applications can be used to manipulate the creator and type codes (e.g. FileType).
The format of the rawfiles created by the write command is specified by the filetype variable. In addition to the standard 'ascii' and 'binary' values, MacSpice defines the filetype 'tabbed'. This is a tab-delimited format intended to facilitate import of results into other data-analysis applications. MacSpice also defines filetypes 'mac_ascii' and 'mac_tabbed' which have lines terminated by '\r' (carriage return) instead of '\n' (line-feed).
Binary rawfiles written by MacSpice (v2.9p14 onwards) include a flag with the value 'big_endian' or 'little_endian' to indicate how the binary data is to be interpreted when it is loaded. If this flag is missing, MacSpice assumes the data is native to the platform on which it is running.
Memory Conservation
Many of the memory leaks that affected Spice 3f4 have been cured in MacSpice. I've paid particular attention to the frontend, for example the script:
let j = 0
while j < 10000
let j = j +1
end
repeat 10000
define f(a,b) 100*b+321*a
let k = f(j,j+4)
undefine f
end
unlet j k
does not leak. This property allows industrial-strength optimisation problems to be tackled.
The MacSpice command 'delcirc', which has the same syntax as setcirc, can be used to delete a loaded circuit and recover its memory.
The memory usage indicated by rusage excludes the amounts required to create and maintain windows (which use a different allocator). Commands like destroy, delcirc, unlet, etc. can be used to recover memory. Graphs make their own copy of their data at the time they are created. If you destroy vectors that are owned by a suspended simulation - don't 'resume' it, use 'delcirc' to get rid of the thing.
Save
The standard save command has been enhanced by defining new qualifiers 'alli' and 'allv'.
| save all | Voltage nodes and voltage source branch currents, but not semiconductor internal nodes |
| save allv | Voltage nodes, including semiconductor internal nodes, and source branch currents |
| save alli | Terminal currents for all semiconductor devices |
The default behaviour is equivalent to 'save all'.
Spice 2 'POLY' Sources
Spice 2 poly sources in the netlist are converted to the Spice 3 (usually B) equivalents. The results should be inspected using the listing command.
Updates
When running on Mac OS X 10.3 or later, MacSpice is able to check for new versions and update itself. The update information comes via a type of RSS feed known as an Appcast. Users have a chance to inspect release notes before deciding whether they want to update. The checks can be performed on request, by using the 'Check for Updates...' menu item, or automatically roughly once a week. Automatic updates can be switched on or off using the defaults(1) command from the terminal. For example,
macos% defaults write CDHW.MacSpice SUCheckAtStartup -boolean yes
enables automatic checking, and setting the value to 'no' disables it.
Vectors
Expressions like 'let foo[2] = 99' work in MacSpice 3f5 and incorporate index range checking. It also has a semicolon operator to facilitate construction of vectors and n-dimensional matrices. For example, typing the commands:
| 'let foo = ((11;12);(21;22))' | creates a 2×2 matrix, |
| 'let bar = (foo;(31;32))' | creates a 3×2 matrix, |
| 'let baz = (1;(3,4);5)' | creates a complex vector with 3 elements. |
The ; must be protected with ()'s otherwise it will be treated as a command separator by the parser.