1.5. pyopus.simulator.hspice — HSPICE simulator support

HSPICE interface (PyOPUS subsystem name: HSSI)

HSPICE is a batch mode simulator. It is capable of changing the circuit’s topology and its parameters between consecutive simulations without the need to restart the simulator with a new input file. HSPICE is completely input-file driven and presents no command prompt to the user.

Save directives do not apply to the AC analysis because the HSPICE .probe simulator directive works only for real values.

The temperature parameter has special meaning and represents the circuit’s temperature in degrees centigrade.

Analysis command generators return a tuple with teh following members:

0. analysis type ('dc', 'ac', 'tran', 'noise')
1. analysis results file ending ('sw', 'ac', 'tr')
2. analysis directive text

A job sequence in HSPICE is internally list of lists where the inner lists contain the indices of jobs belonging to one job group. The user is, however, presented with only one job group containing all job indices ordered in the manner the jobs will later be simulated (flat job sequence).

Job sequence optimization minimizes the number of topology changes between consecutive jobs. Internally this is represented in the job sequence by job groups where all jobs in a group share the same circuit topology.

One result group can consist of multiple plots resulting from multiple invocations of the same analysis (resulting from a parametric sweep). See pyopus.simulator.hspicefile module for the details on the result files.

Repeated analyses with a parameter sweep and the collection of .measure directive results are currently not supported.

pyopus.simulator.hspice.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 teh 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 HSPICE 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'.

HSPICE hierarchical paths begin with the outermost instance followed by its subinstances. A dot (.) is used as the separator between instances in the hierarchy. So x2.x1.m1 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.hspice.save_all()

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

pyopus.simulator.hspice.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.

pyopus.simulator.hspice.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.

pyopus.simulator.hspice.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 HSPICE devices have no vector properties.

pyopus.simulator.hspice.an_op()

Generates the HSPICE simulator directive that invokes the operating point analysis.

This is achieved with a trick - performing a DC sweep of a parameter named dummy__ across only one point. The dummy__ parameter is added to the simulator input file automatically.

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

Generates the HSPICE 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
• '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. Because HSPICE can sweep only independent voltage and current sources, these two element types are the only ones allowed. Due to this the only allowed value for parameter is dc.

Because HSPICE 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.

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

Generats the HSPICE simulator directive 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

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

Generats the HSPICE simulator directive that invokes the transient analysis. The range of the time sweep is given by start and stop. step is the intiial time step.

HSPICE does not support an upper limit on the time step. Therefore the maxStep argument is ignored.

If the uic flag is set to True the initial conditions given by .ic simulator directives are used as the first point of the transient analysis instead of the operating point analysis results.

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

Generats the HSPICE simulator directive 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.

ptsSum is supported by HSPICE but the results go to a text file and are not collected after the analysis. If it wasn’t ignored we would specify it as the third argument to .noise.

A HSPICE noise analysis is an addition to the AC analysis.

class pyopus.simulator.hspice.HSpice(binary=None, args=[], debug=0)

A class for interfacing with the HSPICE batch mode simulator.

binary is the path to the HSPICE simulator binary. If it is not given the HSPICE_BINARY environmental variable is used as the path to the HSPICE simulator binary. If HSPICE_BINARY 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 (.lis file) 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.

cleanupResults(i)

Removes all result files that were produced during the simulation of the i-th job group. Because the user is always presented with only one job group, 0 is the only allowed value of i.

Simulator input files are left untouched.

classmethod findSimulator()

Finds the simulator. Location is defined by the HSPICE_BINARY 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.

Because the user is always presented with only one job group, only 0 is allowed for the value of i.

jobGroupCount()

Returns the number of job groups.

optimizedJobSequence()

Returns the optimized internal job sequence. It has as many job groups as there are different circuit topologies (lists of system description modules) in the job list. Jobs in one job group share the same circuit topology. They are ordered by their indices with lowest job index listed as the first in the group.

Also stores the flat job sequence in the flatJobSequence member. A flat job sequence is a list of jobs appearing in the order in which they will be simulated. In this case the flat job sequence is actually the flattened version of the optimized internal job sequence.

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 HSpiceSimulationResults. If the run failed or the results file cannot be read the None is returned.

runFile(fileName)

Runs the simulator on the main simulator 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. Because the user is always presented with only one job group, 0 is the only allowed value of i.

If a fresh job list is detected a new topology file is created by invoking the writeTopology() method. Next the analysis library file and the main simulator input file are created by the writeFile() method.

The cleanupResults() method removes any old results produced by previous runs of the jobs.

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 jobs that were simulated. status is the status returned by the runFile() method.

unoptimizedJobSequence()

Returns the unoptimized internal 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 every one of them holding one job.

Also stores the flat job sequence in the flatJobSequence member. A flat job sequence is a list of jobs appearing in the order in which they will be simulated. In this case the flat job list is [0, 1, ..., n-1]. The flast job sequence is the first and only job group which is presented to the user.

writeFile(i)

Prepares the simulator input file for running the i-th job group. Because there is only one job group in HSPICE 0 is the only allowed value of i.

Generates files

• simulatorID_analysis.lib - lists all analyses, one library section per analysis
• simulatorID.sp - the main simulator input file

These files must be generated every time new input parameter values are set with the setInputParaneters() method.

The simulatorID_analysis.lib file is a library file with sections named anFileEndingIndex where FileEnding is the one returned by analysis command generators and Index is the consecutive index of the analysis of that type.

Every section has in simulatorID_analysis.lib consists of

• Simulator options (.options simulator directive).
• The value of the temperature parameter in form of a .temp simulator directive.
• .options post=1 which forces writing the results in binary output files.
• The valus of parameters in the form of .param dirrectives. The parameters specified in the corresponding job description take precedence over input parameter values.
• Save directives (.probe simulator directive). If at least one save directive is specified, the all() directive is not used, and the analysis is not an AC analysis the .options probe=1 directive is added. This instructs the simulator to save only those results that are specified with save directives.

The simulatorID.sp file invokes individual jobs. The first job starts with a .title simulator directive giving the job name as the title. All other jobs start with an .alter directive giving their corresponding job names.

Every .title/.alter directive is followed by .del lib and .lib directives that include a section of the topology file and the section of the the simulatorID_analysis.lib file that correspond to the job.

All output files with simulation results are files with endings comprising

• the file ending returned by the analysis command generator and
• the consecutive index of the analysis.

All output files are in HSPICE binary file format.

The function returns the name of the main simulator input file.

writeTopology()

Creates the topology file. The file is named simulatorID_topology.lib and is a library file with one section corresponding to the circuit description of one group of jobs with a common circuit definition.

Sections of the library are named topIndex where Index is the index of the group of jobs in the job list.

Every section consists of .include and .lib simulator directives corresponding to system description modules given in the job description.

The topology file does not depend on the input parameter values. Therefore it is created only once for every job list that is supplied with the setJobList() method.

class pyopus.simulator.hspice.HSpiceSimulationResults(rawData, path2num={}, params={}, variables={}, results={})

Objects of this class hold HSPICE simulation results along with the data from the corresponding .pa# file.

date()

Return the date of the results.

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.

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

The spectrum is returned for the resIndex-th sweep point.

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

Retrieves property named parameter belonging to instance named name. index must always be None because HSPICE does not support vector properties.

The property is retrieved for resIndex-th sweep point.

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

scale(vecName=None, resIndex=0)

If vecName is specified returns the scale corresponding to the specified vector in the resIndex-th sweep point. For HSPICE this is always the default scale.

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

scaleName(vecName=None, resIndex=0)

If vecName is specified returns the name of the scale vector corresponding to the specified vector of the resIndex-th sweep point. For HSPICE this is always the default scale.

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

shorten(path)

Returns the shortened name of an instance based on the subcircuit number listed in the corresponding .pa# file.

If the full instance path is x1.xm1.m0 and x1.xm1. is subcircuit number 5, then the shortened name is 5:m0.

Shortened names are used for accessing noise contributions.

sweepValues()

Return the values of the swept parameter.

sweptParameter()

Return the name of the swept parameter.

title()

Return the title of the results.

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 sweep point.

vector(name, resIndex=0)

Returns vector named name for resIndex-th sweep point.

vectorNames(resIndex=0)

Returns the names of available vectors.