1.2. pyopus.simulator.spiceopus — SPICE OPUS simulator support

SPICE OPUS batch mode interface (PyOPUS subsystem name: SOSI)

SPICE OPUS is a free Berkeley SPICE3-based simulator. It is capable of interactive operation but this module uses it in batch mode. This means that none of the advanced interactive features of SPICE OPUS are used.

SPICE OPUS in batch mode is not capable of changing the circuit’s parameters or its topology (system definition) without restarting the simulator and loading a new input file.

An exception to this is the temperature parameter which represents the circuit’s temperature in degrees centigrade (.option temp=... simulator directive) and can be changed without restarting the simulator. Consequently the temp simulator option is not allowed to appear in the simulator options list.

All simulator options (.option directive) can be changed interactively without the need to restart the simulator and load a new input file. This leaves very little space for job list optimization. Nevertheles there are still some advantages to be gained from an optimized job list.

A job sequence in SPICE OPUS is a list of lists containing the indices of jobs belonging to individual job groups.

One result group can consist of multiple plots. See pyopus.simulator.rawfile module for the details on the result files and plots in SPICE OPUS.

class pyopus.simulator.spiceopus.SpiceOpus(binary=None, args=[], debug=0, timeout=None)

A class for interfacing with the SPICE OPUS simulator in batch mode.

binary is the path to the SPICE OPUS simulator binary. If it is not given the OPUSHOME environmental variable is used as the path to the SPICE OPUS installation. The simulator is assumed to be in OPUSHOME/bin. If OPUSHOME is not defined the binary is assumed to be in the current working directory.

args apecifies a list of additional arguments passed to the simulator binary at startup.

If debug is greater than 0 debug messages are printed at the standard output. If it is above 1 a part of the simulator output is also printed. If debug is above 2 full simulator output is printed.

The save directives from the simulator job description are evaluated in an environment where the following objects are available:

• all - a reference to the save_all() function

• v - a reference to the save_voltage() function

• i - a reference to the save_current() function

• p - a reference to the save_property() function

• ipath - a reference to the ipath() function

Similarly the environment for evaluating the analysis command given in the job description consists of the following objects:

• op - a reference to the an_op() function

• dc - a reference to the an_dc() function

• tf - a reference to the an_tf() function

• ac - a reference to the an_ac() function

• tran - a reference to the an_tran() function

• noise - a reference to the an_noise() function

• ipath - a reference to the ipath() function

• param - a dictionary containing the members of the params entry in the simulator job description together with the parameters from the dictionary passed at the last call to the setInputParameters() method. The parameters values given in the job description take precedence over the values passed to the setInputParameters() method.

cleanupResults(i)

Removes all result files that were produced during the simulation of the i-th job group. Simulator input files are left untouched.

classmethod findSimulator()

Finds the simulator. Location is defined by the OPUSHOME environmental variable. If the binary is not found there the system path is used.

jobGroup(i)

Returns a list of job indices corresponding to the jobs in i-th job group.

jobGroupCount()

Returns the number of job groups.

optimizedJobSequence()

Returns the optimized job sequence.

Jobs in a job group have:

• identical circuit definition,

• identical simulator parameter values (excluding temperature which is actually a simulator option),

• identical simulator option lists, but not neccessarily identical option values.

In other words: job group members are job indices of jobs that differ only in simulator option values.

readResults(jobIndex, runOK=None)

Read results of a job with given jobIndex.

runOK specifies the status returned by the runJobGroup() method which produced the results. If not specified the run status stored by the simulator is used.

Returns an object of the class SpiceOpusSimulationResults. If the run failed or the results file cannot be read the None is returned.

runFile(fileName)

Runs the simulator on the input file given by fileName.

Returns True if the simulation finished successfully. This does not mean that any results were produced. It only means that the return code from the simuator was 0 (OK).

runJobGroup(i)

Runs the i-th job group.

First calls the writeFile() method followed by the cleanupResults() method that removes any old results produced by previous runs of the jobs in i-th job group. Finally the runFile() method is invoked. Its return value is stored in the lastRunStatus member.

The function returns a tuple (jobIndices, status) where jobIndices is a list of job indices corresponding to the i-th job group. status is the status returned by the runFile() method.

unoptimizedJobSequence()

Returns the unoptimized job sequence. If there are n jobs the job list the following list of lists is returned: [[0], [1], ..., [n-1]]. This means we have n job groups with one job per job group.

writeFile(i)

Prepares the simulator input file for running the i-th job group.

The file is named simulatorID.group_i.cir where i is the index of the job group.

All output files with simulation results are .raw files in binary format.

System description modules are converted to .include and .lib simulator directives.

Simulator options are set with the set simulator command. Integer, real, and string simulator options are converted with the __str__() method before they are written to the file. Boolean options are converted to set or unset commands depending on whether they are True or False.

The parameters set with the last call to setInputParameters() method are joined with the parameters in the job description. The values from the job description take precedence over the values specified with the setInputParameters() method. All parameters are written to the input file in form of .param simulator directives.

The temperature parameter is treated differently. It is written to the input file in form if a set simulator command preceding its corresponding analysis command.

Save directives are written as a series of save simulator commands.

Every analysis command is evaluated in its corresponding environment taking into account the parameter values passed to the setInputParameters() method.

Every analysis is followed by a write command that stores the results in a file named simulatorID.job_j.jobName.raw where j denotes the job index from which the analysis was generated. jobName is the name member of the job description.

The function returns the name of the simulator input file it generated.

class pyopus.simulator.spiceopus.SpiceOpusSimulationResults(rawData, params={}, variables={}, results={})

Objects of this class hold SPICE OPUS simulation results.

date(resIndex)

Return the date of the resIndex-th plot.

driverTable()

Returns a dictionary of available driver functions for accessing simulation results.

i(name, resIndex=0)

Retrieves the current flowing through instance name from the resIndex-th plot.

Equivalent to SPICE OPUS expression i(name) (also name#branch).

name(resIndex)

Return the name of the resIndex-th plot.

ns(reference, name=None, contrib=None, resIndex=0)

Retrieves the noise spectrum density of contribution contrib of instance name to the input/output noise spectrum density. reference can be 'input' or 'output'.

If name and contrib are not given the output or the equivalent input noise spectrum density is returned (depending on the value of reference).

Partial and total noise spectra are returned as squared noise (in V^2/Hz or A^2/Hz).

The spectrum is obtained from the resIndex-th plot.

p(name, parameter, index=None, resIndex=0)

Retrieves the index-th component of property named parameter belonging to instance named name. If the property is not a vector, index can be ommitted. The property is retrieved from resIndex-th plot.

Note that this works only of the property was saved with a corresponding save directive.

Equivalent to SPICE OPUS expression @name[parameter] (or @name[parameter][index]).

scale(vecName=None, resIndex=0)

If vecName is specified returns the scale corresponding to the specified vector in the resIndex-th plot. Usually this is the default scale.

If vecName is not specified returns the default scale of the resIndex-th plot.

scaleName(vecName=None, resIndex=0)

If vecName is specified returns the name of the scale vector corresponding to the specified vector in the resIndex-th plot. Usually this is the default scale.

If vecName is not specified returns the name of the vector holding the default scale of the resIndex-th plot.

title(resIndex)

Return the title of the resIndex-th plot.

v(node1, node2=None, resIndex=0)

Retrieves the voltage corresponding to node1 (voltage between nodes node1 and node2 if node2 is also given) from the resIndex-th plot.

Equivalent to SPICE OPUS expression v(node1) (or v(node1,node2)).

Also used for retrieving results of tf analysis. Set node1 to input_impedance, output_impedance, or transfer_function.

vector(name, resIndex=0)

Returns vector named name from resIndex-th plot.

vectorNames(resIndex=0)

Returns the names of available vectors.

pyopus.simulator.spiceopus.an_ac(start, stop, sweep, points)

Generates the SPICE OPUS simulator command that invokes the small signal (AC) analysis. The range of the frequency sweep is given by start and stop. sweep is one of

• 'lin' - linear sweep with the number of points given by points

• 'dec' - logarithmic sweep with points per decade (scale range of 1..10) given by points

• 'oct' - logarithmic sweep with points per octave (scale range of 1..2) given by points

Equivalent of SPICE OPUS ac sweep points start stop simulator command.

pyopus.simulator.spiceopus.an_dc(start, stop, sweep, points, name, parameter, index=None)

Generates the SPICE OPUS simulator command that invokes the operating point sweep (DC) analysis. start and stop give the intial and the final value of the swept parameter.

sweep can be one of

• 'lin' - linear sweep with the number of points given by points

• 'dec' - logarithmic sweep with points per decade (scale range of 1..10) given by points

• 'oct' - logarithmic sweep with points per octave (scale range of 1..2) given by points

name gives the name of the instance whose parameter is swept. If the parameter is a vector parameter index gives the integer index (zero based) of the vector’s component that will be swept.

Equivalent of SPICE OPUS dc @name[param][index] start stop sweep points simulator command.

pyopus.simulator.spiceopus.an_noise(start, stop, sweep, points, input, outp=None, outn=None, outcur=None, ptsSum=1)

Generates the SPICE OPUS simulator command that invokes the small signal noise analysis. The range of the frequency sweep is given by start and stop. sweep* is one of

• 'lin' - linear sweep with the number of points given by points

• 'dec' - logarithmic sweep with points per decade (scale range of 1..10) given by points

• 'oct' - logarithmic sweep with points per octave (scale range of 1..2) given by points

input is the name of the independent voltage/current source with ac parameter set to 1 that is used for calculating the input referred noise. outp and outn give the voltage that is used as the output voltage. If only outp is given the output voltage is the voltage at node outp. If outn is also given, the output voltage is the voltage between nodes outp and outn. If outcur is given the current flowing through the voltage source with that name is considered to be the output. ptsSum gives the number of points per summary (integrated noise) vector.

Equivalent of SPICE OPUS noise outspec input sweep points start stop ptsSum simulator command.

pyopus.simulator.spiceopus.an_op()

Generates the SPICE OPUS simulator command that invokes the operating point analysis.

Equivalent of SPICE OPUS op simulator command.

pyopus.simulator.spiceopus.an_tf(src, outp=None, outn=None, outcur=None)

Generates the SPICE OPUS simulator command that invokes the small signal (TF) analysis.

input is the name of the independent voltage/current source that generates the input signal. outp and outn give the voltage that is used as the output voltage. If only outp is given the output voltage is the voltage at node outp. If outn is also given, the output voltage is the voltage between nodes outp and outn. If outcur is given the current flowing through the voltage source with that name is considered to be the output.

pyopus.simulator.spiceopus.an_tran(step, stop, start=0.0, maxStep=None, uic=False)

Generates the SPICE OPUS simulator command that invokes the transient analysis. The range of the time sweep is given by start and stop. step is the intiial time step. The upper limit on the time step is given by maxStep. If the uic flag is set to True the initial conditions given by .ic simulator directives and initial conditions specified as instance parameters (e.g. ic parameter of capacitor) are used as the first point of the transient analysis instead of the operating point analysis results.

If uic is True and maxStep is not given, the default value maxStep is step.

Equivalent of SPICE OPUS tran step stop start maxStep [uic] simulator command.

pyopus.simulator.spiceopus.ipath(input, outerHierarchy=None, innerHierarchy=None, objectType='inst')

Constructs a hierarchical path for the instance with name given by input. The object is located within outerHierarchy (a list of instances with innermost instance listed first). innerHierarchy a list of names specifying the instance hierarchy inner to the input instance. The innermost instance name is listed first. If outerHierarchy is not given input is assumed to be the outermost element in the hierarchy. Similarly if innerHierarchy is not given input is assumed to be the innermost element in the hierarchy.

Returns a string representing a hierarchical path.

If input is a list the return value is also a list representing hierarchical paths corresponding to elements in input.

innerHierarchy and outerHierarchy can also be ordinary strings (equivalent to a list with only one string as a member).

The objectType argument is for compatibility with other simulators. Because SPICE OPUS treats the hierarchical paths of all objects in the same way, the return value does not depend on objectType. The available values of objectType are 'inst', 'mod', and 'node'.

SPICE OPUS hierarchical paths begin with the innermost instance followed by its enclosing instances. Colon (:) is used as the separator between instances in the hierarchy. So m1:x1:x2 is an instance named m1 that is a part of x1 (inside x1) which in turn is a part of x2 (inside x2).

Some examples:

• ipath('m1', ['x1', 'x2']) - instance named m1 inside x1 inside x2. Returns 'm1:x1:x2'.

• ipath('x1', innerHierarchy=['m0', 'x0']) - instance m0 inside x0 inside x1. Returns 'm0:x0:x1'.

• ipath(['m1', 'm2'], ['x1', 'x2']) - instances ``m1 and m2 inside x1 inside x2. Returns ['m1:x1:x2', 'm2:x1:x2'].

• ipath(['xm1', 'xm2'], ['x1', 'x2'], 'm0') - instances named m0 inside paths xm1:x1:x2 and xm2:x1:x2. Returns ['m0:xm1:x1:x2', 'm0:xm2:x1:x2'].

pyopus.simulator.spiceopus.save_all()

Returns a save directive that saves all results the simulator normally saves in its output (in SPICE OPUS these are all node voltages and all currents flowing through voltage sources and inductances).

Equivalent of SPICE OPUS save all simulator command.

pyopus.simulator.spiceopus.save_current(what)

If what si a string it returns a save directive that instructs the simulator to save the current flowing through instance names *what in simulator output. If what is a list of strings multiple save diretives are returned instructing the simulator to save the currents flowing through instances with names given by the what list.

Equivalent of SPICE OPUS save i(what) simulator command.

pyopus.simulator.spiceopus.save_property(devices, params, indices=None)

Saves the properties given by the list of property names in params of instances with names given by the devices list. Also capable of handling properties that are vectors (although currently SPICE OPUS devices have no such properties). The indices of vector components that need to be saved is given by the indices list.

If params, devices, and indices have n, m, and o memebrs, n*m*o save directives are are returned describing all combinations of device name, property name, and index.

If indices is not given, save directives for scalar device properties are returned. Currently SPICE OPUS devices have no vector properties.

Equvalent of SPICE OPUS save @device[property] (or in case the property is a vector save @device[property][index]) simulator command.

pyopus.simulator.spiceopus.save_voltage(what)

If what is a string it returns a save directive that instructs the simulator to save the voltage of node named what in simulator output. If what is a list of strings multiple save directives are returned instructing the simulator to save the voltages of nodes with names given by the what list.

Equivalent of SPICE OPUS save v(what) simulator command.