1.3. pyopus.simulator.spectre — Cadence Spectre simulator support

SPECTRE batch mode interface (PyOPUS subsystem name: SPSI)

SPECTRE is simulator from Cadence. It is capable of modifying circuit, subcircuit and simulator parameters, but cannot change the topology without restarting and loading a new file.

SPECTRE is not capable of changing the circuit’s topology (system definition) without restarting the simulator and loading a new input file. It also cannot have a different set of save directives for every analysis.

The temperature parameter represents the circuit’s temperature in degrees centigrade (options temp=... simulator directive). Consequently the temp simulator option is not allowed to appear in the simulator options list.

Save statements are global in SPECTRE. Therefore they apply to all analyses in a file. If two analyses have different sets of save directives two separate input files are generated when saveSplit is set to True. Otherwise all save directives from all jobs in a file are merged together.

Nutmeg rawfile (binary) files are used for collecting the reults.

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

One result group always contains only one plot. See pyopus.simulator.rawfile module for the details on the result files.

pyopus.simulator.spectre.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 'x2.x1.m1'.
• ipath('x1', innerHierarchy=['m0', 'x0']) - instance m0 inside x0 inside x1. Returns 'x1.x0.m0'.
• ipath(['m1', 'm2'], ['x1', 'x2']) - instances ``m1 and m2 inside x1 inside x2. Returns ['x2.x1.m1', 'x2.x1.m2'].
• ipath(['xm1', 'xm2'], ['x1', 'x2'], 'm0') - instances named m0 inside paths x2.x1.xm1 and x2.x1.xm2. Returns ['x2.x1.xm1.m0', 'x2.x1.xm2.m0'].

pyopus.simulator.spectre.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).

pyopus.simulator.spectre.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 a 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.

pyopus.simulator.spectre.save_current(what, terminal=1)

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. terminal specifies the number of the terminal it which the current is saved.

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

Saves the properties given by the list of property names (params) of instances given by the devices list.

If params and the devices have n and m members, n*m save directives are returned describing all combinations of device name and property name.

pyopus.simulator.spectre.an_op(**kwargs)

Generates the SPECTRE simulator command that invokes an operating point analysis.

Passes any additional arguments to the dc simulator directive.

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

Generates the SPECTRE simulator command that invokes an operating point sweep (DC) analysis. See the SPECTRE manual for details on arguments.

Generates the SPECTRE simulator directive 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

name gives the name of the instance whose parameter is swept. Because SPECTRE knows no such thing as vector parameters, index should never be used.

If name is not given a sweep of a circuit parameter (defined with .param) is performed. The name of the parameter can be specified with the parameter argument. If parameter is temperature a sweep of the circuit’s temperature is performed.

If star, stop, sweep, points, and parameter are given, a common PyOPUS dc sweep is performed. Otherwise the parameters are passed to the dc simulator directive.

Passes any additional arguments to the dc simulator directive.

pyopus.simulator.spectre.an_ac(start=None, stop=None, sweep=None, points=None, **kwargs)

Generats the SPECTRE simulator command that invokes a small signal (AC) analysis. See the SPECTRE manual for details on arguments.

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

if start, stop, sweep, and points are given a common PyOPUS ac sweep is performed.

Passes any additional arguments to the ac simulator directive.

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

Generats the SPECTRE simulator command that invokes a transient analysis. See the SPECTRE manual for details on arguments.

If step and stop (optionally start, maxStep, and uic) are given a common PyOPUS transient analysis is performed. To force a spectre style analysis with only stop (and start), specify at least one SPECTRE-only transient analysis parameter default value (e.g. skipdc=no).

Passes any additional arguments to the tran simulator directive.

pyopus.simulator.spectre.an_noise(start=None, stop=None, sweep=None, points=None, input=None, outp=None, outn=None, ptsSum=1, **kwargs)

Generats the SPECTRE simulator command that invokes a small signal noise analysis. See the SPECTRE manual for details on arguments.

If start, stop, sweep, and points are given a common PyOPUS noise analysis is performed.

The ptsSum argument is ignored.

Passes any additional arguments to the noise simulator directive.

class pyopus.simulator.spectre.Spectre(binary=None, args=[], debug=0, saveSplit=False)

A class for interfacing with the SPECTRE simulator.

binary is the path to the SPECTRE simulator binary. If it is not given the SPECTRE_BINARY environmental variable is used as the path to the binary. If SPECTRE_BINARY is not set the binary is assumed to be named ‘spectre’ and located in the system PATH.

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
• 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.

Seting saveSplit to True splits a job group in multiple job groups with differing setws of save directives. Setting it to False (default) joins the save directives from all jobs in a job group.

cleanupResults(i)

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

collectResults(indices, runOK=None)

Collects the results produces by running jobs with indices given by the indices list. runOK specifies the status returned by the runJobGroup() method which produced the results.

If runOK is False the result groups of the jobs with indices given by indices are set to None.

A results group corresponding to some job is set to None if the .raw file is not successfully loaded.

getGenerators()

Returns a dictionary of functions that retrieve results from the active result group.

The following functions (dictionary key names) are available:

• v - a reference to the res_voltage() method
• i - a reference to the res_current() method
• p - a reference to the res_property() method
• ns - a reference to the res_noise() method
• scale - a reference to the res_scale() method
• ipath - a reference to the ipath() function

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 save directives

res_current(name, resIndex=0)

Retrieves the current flowing through instance name from the active result group.

res_noise(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 'gain' is given as reference the gain is returned.

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 noise spectra are in V^2/Hz, total spectra are in V/sqrt(Hz).

The spectrum is obtained from the active result.

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

Retrieves property named parameter belonging to instance named name. The property is retrieved from the active result.

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

res_scale(resIndex=0)

Retrieves the default scale of the active result.

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

Retrieves the voltage corresponding to node1 (voltage between nodes node1 and node2 if node2 is also given) from the active result.

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 in 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.scs 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 simulator directives.

Simulator options are set with the set simulator directive. Integer, real, and string simulator options are converted with the __str__() method before they are written to the file. Boolean options are converted to 0 or 1t 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 alter simulator directives.

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

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

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

All analyses write the results to a single binary .raw file.

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