1.4. pyopus.simulator.xyce — Xyce simulator support

** Xyce interface (PyOPUS subsystem name: XYSI)**

Xyce is a free simulator written from scratch at Sandia National Laboratories.

Xyce can run only one analysis per simulator invocation. The save directive philosopy is radically different from that of the other simulators supported by PyOpus. We try hard to make this interface similar to thos of other simulators, but one can only do so much.

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

The Xyce interface does no joblist optimization because there can be none due to the way Xyce is designed.

Furthermore, Xyce noise analysis cannot store results in rawfile format. Therefore csv format is used which is less efficient. It is read with the datatable Python package. If datatable is not available Pandas is used which is somewhat slower. You can check if datatable is used by looking at pyopus.simulator.xyce.datatable. If it is not None datatable is used for loading csv files.

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

A class for interfacing with the Ngspice simulator in batch mode.

binary is the path to the Xyce simulator binary. If it is not given the XYCEPATH environmental variable is used as the path to the Ngspice binary. If XYCEPATH 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.

By default the Xyce interface is configured to save all voltages. Contrary to other Spice simulators, currents of indipendent voltagfe sources are not saved by the default. Similarly noise analysis saves only the output and the equivalebnt output noise. To save noise contributions one must specify corresponding save directives.

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

• ns - a reference to the save_ns() 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. Simulator input files are left untouched.

classmethod findSimulator()

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

Because Xyce does not support multiple analyses in one file there is nothing to optimize.

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

setJobList(jobList, optimize=True)

Sets jobList to be the job list for batch simulation. If the options, params, saves, or variables member is missing in any of the jobs, an empty dictionary/list is added to that job.

The job list is marked as fresh meaning that a new set of simulator input files needs to be created. Files are created the first time a job group is run.

If optimize is True the optimized job sequence is computed by calling the optimizedJobSequence() method. If optimize is True an unoptimized job sequence is produced by calling the unoptimizedJobSequence() 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 .options simulator command.

Save directives are dumped into a .print simulator command.

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

The results are stored 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.xyce.XyceSimulationResults(rawData, params={}, variables={}, results={})

Objects of this class hold Xyce 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 Xyce output variable i(name).

il(name, lead, resIndex=0)

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

Equivalent to Xyce output variable ilead(name).

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 Xyce output variable expression n(device) (or n(device:param)).

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

vector_(name, resIndex=0)

Returns vector named name from resIndex-th plot.

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

Generates the Xyce 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 Xyce .ac simulator command.

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

Generates the Xyce 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 points is an integer specifying the number of points

• 'dec' - logarithmic sweep with points per decade points is an integer specifying the number of points per decade

• 'oct' - logarithmic sweep with points per octave points is an integer specifying the number of points per octave

• 'list' - sweep a list of values points is a list specifying the points

name gives the name of the instance whose parameter is swept. For sweeping voltage and current sources parameter does not have to be given.

index is not supported by Xyce.

Equivalent of Xyce .dc simulator command.

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

Generates the Xyce 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 is not supported by Xyce and is ignored.

Equivalent of Xyce .noise simulator command.

pyopus.simulator.xyce.an_op()

Generates the Ngspice simulator command that invokes the operating point analysis.

Performs a single point dc sweep of a voltage source named dummy___ added by PyOpus.

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

Generates the Xyce 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 Xyce .tran simulator command.

pyopus.simulator.xyce.ipath(inputobj, 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 inputobj 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).

Xyce handles hierarchical paths identically for instances, models, and nodes. Therefore the objectType argument is ignored.

All Xyce hierarchical paths begin with the outermost instance followed by its children. Instances along a hierarchical path are separated with a colon (:). So x2:x1:10 is a node named 10 that is a part of x1 (inside x1) which in turn is a part of x2 (inside x2). The same applies to instance and model names.

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 xm1:x1:x2 and xm2:x1:x2. Returns ['x2:x1:xm1:m0', 'x2:x1:xm2:m0'].

pyopus.simulator.xyce.save_all()

Returns a save directive that saves all the voltages the simulator computes.

Equivalent of Xyce v(*) output variable.

pyopus.simulator.xyce.save_current(what, lead=None)

If what is 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.

If lead is given it must be a one letter string. It specifies the lead through which the current is measured. lead can also be a list in which case currents through all listed leads are saved.

Equivalent of Xyce save i(what) output variable (if lead is not given). If lead is given it is the equivalent of i<lead>(what) output variable.

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

Saves the internal variables of devices given by devices and parameters params both arguments can either be a string or a list. If params is not given the device names are used as parameter names.

indices is not supported because Xyce variables are all scalars.

If devices and/or params is a list all combinations of devices and parameters are generated.

Run Xyce netlist with Xyce -namesfile <filename> <netlist> to get the list of available internal variables.

Equvalent of Xyce n(device:param) output variable or n(device) if params is not given.

pyopus.simulator.xyce.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 Xyce v(what) output variable.