simetrix.Schematic¶

class simetrix.Schematic¶

Bases: object

Represents a schematic.

A schematic contains a collection of schematic objects, such as symbol instances. It also contains a set of properties along with a handle that is unique to the running application.

The following functions return Schematic objects:

Methods

`CheckStatus`(status)	Checks the status value and will throw a run-time exception if it is other than NOERR or NOCHANGE.
`annotations`([propertyName, propertyValue])	Returns schematic annotations with defined properties.
`closeSchematicTab`()	Closes the specified schematic.
`deleteProperty`(propertyName)	Deletes a schematic property.
`descendHierarchy`()	Analyses the hierarchy of schematic.
`elements`([propertyName, propertyValue])	Returns schematic `Element` objects of any type (instances, wires and annotations).
`getComponentValue`(address)	Special function to get a component value or parameter.
`getF11Lines`([mode])	Returns the lines in the schematic's F11 window.
`getInstancePinsAtPoint`(point)	Returns a list of Instance pins at the specified location.
`getModifiedStatus`()	Returns True if the schematic has been modified since it was opened or last saved.
`getOpenDisabledInstances`()	Returns list of open-circuit disabled instances.
`getReadOnlyStatus`()	Return True if the schematic is read-only.
`getShortedDisabledInstances`()	Returns list of short-circuit disabled instances.
`getTitleBlockInfo`()	Returns information about the selected title block object.
`hasProperty`(propertyName)	Returns True if the Schematic possesses the property with the given name.
`highlightedNets`()	Returns a list of netnames for wires that are highlighted.
`instances`([propertyName, propertyValue])	Returns a list of Element objects with `ElementType` = INSTANCE matching the supplied property name and property value.
`netNames`()	Returns a list of net names used in the schematic.
`netWires`(netName)	Returns wires connected to netName.
`netlist`([outfile, options])	Generates a netlist for a schematic.
`propertyValue`(propertyName)	Returns the value for the schematic property with the given propertyName.
`readF11AnalysisParameter`(analysisType, ...)	Reads a SIMetrix analysis parameter from the F11 window.
`readF11Options`()	Reads .options statements in F11 window.
`run`([parameters, analysisOverride, options])	Runs a simulation on the schematic.
`runSIMPLISMonteCarlo`()	Preliminary, this method is under development and will change in future versions.
`runSIMPLISMultiStep`()	Preliminary, this method is under development and will change in future versions.
`schematicProperties`([propertyName])	Returns a list of schematic Property objects.
`select`()	Select a schematic sheet, i.e. bring it in to focus.
`selectedAnnotations`([option])	Returns all selected annotation objects in the schematic.
`selectedElements`([options])	Returns schematic `Element` objects of any type (instances, wires and annotations) that are currently selected.
`selectedInstances`()	Returns a list of selected instances.
`selectedWires`([option])	Returns all selected wires in the schematic.
`setComponentValue`(address, value)	Special function to get a component value or parameter.
`setPropertyValue`(propertyName, propertyValue)	Sets a schematic property with the given name and value.
`wires`([propertyName, propertyValue])	Returns wires with defined properties.
`writeF11Analysis`(analysis[, status])	Writes a SIMetrix analysis line to the F11 window.
`writeF11Options`(options)	Write SIMetrix simulator options to the F11 window.

Attributes

`filedate`	Returns the schematic file date in the current locale format.
`filetime`	Returns the schematic file time in the current locale format.
`handle`	Returns the handle (or id) of the schematic.
`magnification`	Returns current magnification of displayed schematic as a real number.
`modified`	Returns True if the schematic has been modified.
`path`	Returns the full path of the schematic's file.
`readonly`	Returns True if the schematic is readonly otherwise False.
`reference`	Returns the hierarchical reference of the schematic or an empty string if the schematic is non-hierarchical or is the root of a schematic.
`rootpath`	If the current schematic is a child in a schematic, this will return the path of root schematic in the hierarchy.
`simulatorMode`	Returns current simulator mode of the schematic.
`userversion`	Returns the auto-incrementing user version number.
`valid`	Returns True if the Schematic object is valid.

static CheckStatus(status: SchematicStatus) → None¶: Checks the status value and will throw a run-time exception if it is other than NOERR or NOCHANGE.

annotations(propertyName: str = 'handle', propertyValue: str = None) → list[Element]¶

Returns schematic annotations with defined properties. Results are Results are Element objects objects. Similar to Schematic.elements() but only returns annotations whereas Schematic.elements() also returns wires and instances. Result filtered by propertyName and propertyValue. propertyName specifies a property name that all returned objects must possess. propertyValue is optional and defines a value for the property. If omitted or None, all objects possessing the property defined by propertyName will be returned. To get all annotation objects in the schematic, call this method with no arguments.

Parameters:

propertyName (str) – Name of property to search.
propertyName – Value of property to search.

Example

import simetrix as sx

schematic = sx.currentSchematic()

annotations = schematic.annotations()

if (len(annotations)==0) :
    print("No annotation objects found in the schematic")
else :
    print("Styles used by annotation objects")
    for el in annotations :
        print(el.propertyValue('StyleNormal'))

See also

Schematic.selectedAnnotations()
Schematic.selectedWires()
Schematic.wires()
Schematic.selectedInstances()
Schematic.instances()
Schematic.selectedElements()
Schematic.elements()

closeSchematicTab() → bool¶: Closes the specified schematic. The method will return True as long as the schematic object is valid, otherwise it will return False. The method will not throw and exception if the schematic object is invalid.

deleteProperty(propertyName: str) → SchematicStatus¶: Deletes a schematic property. Returns a status value indicating success or otherwise. Possible return values are: NOERR, NOPROPERTY, PROTECTED, NOSCHEMATIC and UNEXPECTED. This method will not throw an exception on error, but the Schematic.CheckStatus() method can be used to check the return status.

Note

The property referred to here is a property of the schematic as a whole not the more often used Element Property.

descendHierarchy() → list[DescendHierarchyItem]¶

Analyses the hierarchy of schematic. Returns a list of DescendHierarchyItem objects each describing a single schematic found in the hierarchy. The path to the schematic is available as well as a list of instance references that use the schematic.

Example

import simetrix as sx

schematic = sx.currentSchematic()

if schematic.valid :

    h = schematic.descendHierarchy()
    for item in h :
        print("Path=", item.path)
        print("References:")
        for ref in item.references :
            print("ref:", ref.ref)
            print("type:", ref.type)

else :
    print("There are no schematics open")

elements(propertyName: str = 'handle', propertyValue: str = None) → list[Element]¶

Returns schematic Element objects of any type (instances, wires and annotations). Result is filtered by arguments propertyName and propertyValue. propertyName specifies a property name that all returned objects must possess. The default property name ‘handle’ is possessed by all elements so the default behaviour of this method with no arguments is to return all elements in the schematic. The parameter propertyValue is also optional and defines a value for the property. If omitted or None, all objects possessing the property defined by propertyName will be returned.

Parameters:

propertyName (str) – Property name. The returned elements must possess this property. Note that property names are case-insensitive.
propertyValue (str) – Property value. If specified the returned elements propertyName must have this value. If this parameter is omitted or None, all elements that possess propertyName will be returned. Note that property values are case-insensitive.

Example

# Count wires and instances in circuit
import simetrix as sx

schematic_file = "%DOCSPATH%/SIMetrix/Examples-93/SIMetrix/General/AMP.sxsch"
schematic = sx.openSchematic(schematic_file)

# get all elements
elements = schematic.elements()

wireCount=0
instCount=0

for el in elements :
    if el.type==sx.ElementType.INSTANCE :
        instCount = instCount+1
    elif el.type==sx.ElementType.WIRE :
        wireCount = wireCount+1

print("Wire count:", wireCount)
print("Instance count:", instCount)

See also

Schematic.selectedAnnotations()
Schematic.annotations()
Schematic.selectedWires()
Schematic.wires()
Schematic.selectedInstances()
Schematic.instances()
Schematic.selectedElements()

property filedate: str¶: Returns the schematic file date in the current locale format.

property filetime: str¶: Returns the schematic file time in the current locale format.

getComponentValue(address: str) → SetComponentValueResult¶

Special function to get a component value or parameter. Same as SetComponentValue() except that it can only read values.

Parameters:: address (str) – Address of component whose value is required.

getF11Lines(mode: ModelParseMode = ModelParseMode.SPICE)¶

Returns the lines in the schematic’s F11 window. If mode is set to ModelParseMode.SPICE, the result is processed to remove inline comments and join ‘+’ continuation lines. If mode = ModelParseMode.NONE, the F11 window is returned unmodified.

Parameters:: mode (ModelParseMode) – Parse mode.

Example

import simetrix as sx

schem_file = "%DOCSPATH%/SIMetrix/Examples-93/SIMetrix/General/AMP.sxsch"
schem = sx.openSchematic(schem_file)

for l in schem.getF11Lines() :
    print(l)

See also

Schematic.writeF11Analysis()
Schematic.readF11Options()
Schematic.writeF11Options()
Schematic.readF11AnalysisParameter()

getInstancePinsAtPoint(point: list[int]) → list[InstancePin]¶

Returns a list of Instance pins at the specified location.

Parameters:: point (list[int]) – Integer pair defining X,Y location of pin.

Example

import simetrix as sx

schem_file = "%DOCSPATH%/SIMetrix/Examples-93/SIMetrix/General/AMP.sxsch"
schem = sx.openSchematic(schem_file)

pins = schem.getInstancePinsAtPoint([5040, 2520])

if len(pins)>0 :
    for p in pins :
        print(p.element.prop("REF").value, p.pin)
else :
    print("Nothing found at that location")

getModifiedStatus() → bool¶: Returns True if the schematic has been modified since it was opened or last saved. Otherwise returns False.

getOpenDisabledInstances() → list[Element]¶

Returns list of open-circuit disabled instances.

Example

import simetrix as sx

schem = sx.currentSchematic()

disabled_instances = schem.getOpenDisabledInstances()

if len(disabled_instances)==0 :
    print("There are no open circuit disabled instances")
else :
    print("The following instances are open-circuit disabled:")
    for di in disabled_instances :
        print(di.propertyValue("Ref"))

See also

Schematic.getShortedDisabledInstances()

getReadOnlyStatus() → bool¶: Return True if the schematic is read-only. Otherwise returns False.

getShortedDisabledInstances() → list[Element]¶

Returns list of short-circuit disabled instances.

Example

import simetrix as sx

schem = sx.currentSchematic()

disabled_instances = schem.getShortedDisabledInstances()

if len(disabled_instances)==0 :
    print("There are no short circuit disabled instances")
else :
    print("The following instances are short-circuit disabled:")
    for di in disabled_instances :
        print(di.propertyValue("Ref"))

See also

Schematic.getOpenDisabledInstances()

getTitleBlockInfo() → TitleBlockInfo¶: Returns information about the selected title block object. If no title block is selected, None is returned.

property handle: int¶: Returns the handle (or id) of the schematic. This can be used to pass to SIMetrix script language functions.

hasProperty(propertyName: str) → bool¶

Returns True if the Schematic possesses the property with the given name. Otherwise returns False.

Properties are compared using a case-insensitive comparison of their names.

Note

The property referred to here is a property of the schematic as a whole not the more often used Element Property.

Parameters:: propertyName (str) – Name of the property.

See also

Schematic.propertyValue()
Schematic.deleteProperty()
Schematic.schematicProperties()
Schematic.setPropertyValue()

highlightedNets() → list[str]¶

Returns a list of netnames for wires that are highlighted. Note that each netname is returned only once even if multiple wires carry that netname.

Example

import simetrix as sx

schem_file = "%DOCSPATH%/SIMetrix/Examples-93/SIMetrix/General/AMP.sxsch"
schem = sx.openSchematic(schem_file)

highlightedNets = schem.highlightedNets()

for n in highlightedNets :
    print(n)

See also

Schematic.netlist()
Schematic.netWires()
Schematic.netNames()

instances(propertyName: str = 'handle', propertyValue: str = None) → list[Element]¶

Returns a list of Element objects with ElementType = INSTANCE matching the supplied property name and property value. If no property value is supplied, all instances possesing the given property will be returned. The propertyName “handle” is always present on all instances, therefore a call to this method with no arguments will return all instances in the schematic.

Parameters:

propertyName (str) – Name of property to search.
propertyName – Value of property to search.

Example

# List reference designators of all instances
import simetrix as sx

schematic_file = "%DOCSPATH%/SIMetrix/Examples-93/SIMetrix/General/AMP.sxsch"
schematic = sx.openSchematic(schematic_file)

# returns all instances with a VALUE property
instances = schematic.instances('VALUE')

for el in instances :
    print(el.propertyValue('REF'))

See also

Schematic.selectedAnnotations()
Schematic.annotations()
Schematic.selectedWires()
Schematic.wires()
Schematic.selectedInstances()
Schematic.selectedElements()
Schematic.elements()

property magnification: float¶: Returns current magnification of displayed schematic as a real number.

property modified: bool¶

Returns True if the schematic has been modified. Note that schematics not open in the GUI can still be modified and this property will reflect that. In the following example, the schematic opened by openSchematic() is not open in the GUI but is being edited invisibly.

Example

import simetrix as sx

schematic_file = "%DOCSPATH%/SIMetrix/Examples-93/SIMetrix/General/AMP.sxsch"
schematic = sx.openSchematic(schematic_file)

if schematic.valid :
    # prints False
    print(schematic.modified)
    # Get Q4
    inst = schematic.instances("REF", "Q4")[0]
    # change value
    inst.setPropertyValue("VALUE", "Q2n2222")
    # This will print True
    print(schematic.modified)
    # print new value
    print(inst.propertyValue("VALUE"))

netNames() → list[str]¶

Returns a list of net names used in the schematic.

Note that this function requires that the schematic has been netlisted. This can be forced using Schematic.netlist() in the form:

schematic.netlist(None, ["nooutput", "nodescend"])

Example

import simetrix as sx

schem_file = "%DOCSPATH%/SIMetrix/Examples-93/SIMetrix/General/AMP.sxsch"
schem = sx.openSchematic(schem_file)
schem.netlist(None, ["nooutput", "nodescend"])

netNames = schem.netNames()

for n in netNames :
    print(n)

See also

Schematic.netlist()
Schematic.netWires()
Schematic.highlightedNets()

netWires(netName: str) → list[Element]¶

Returns wires connected to netName.

Note that this function requires that the schematic has been netlisted. This can be forced using Schematic.netlist() in the form:

schematic.netlist(None, ["nooutput", "nodescend"])

Note also that, for a child schematic in a hierarchy, a local netname is expected, that is without the path prefix (e.g. voutn not u1.voutn)

Parameters:: netName (str) – Name of net

Example

import simetrix as sx

schem_file = "%DOCSPATH%/SIMetrix/Examples-93/SIMetrix/General/AMP.sxsch"
schem = sx.openSchematic(schem_file)
schem.netlist(None, ["nooutput", "nodescend"])

netwires = schem.netWires("VOUT")

for w in netwires :
    print(w.type, w.handle)

See also

Schematic.netlist()
Schematic.netNames()
Schematic.highlightedNets()

netlist(outfile: str | None = '', options: list[str] = None) → NetlistReturn¶

Generates a netlist for a schematic. The netlist function also assigns names to schematic nets. If the schematic contains hierarchical blocks, their underlying schematics will also be netlisted and included in the main netlist as subcircuits.

The netlist itself is written to a file. Either a file name can be supplied or the function will create a temporary file located in the user’s temporary folder. The filename is returned by the function as the NetlistReturn.path property. The file will automatically be deleted when the application exits.

The netlist method will automatically detect the schematic simulator mode and create SIMetrix or SIMPLIS netlists accordingly.

This method will not throw an exception in the case of error including if the schematic is invalid. The Schematic.CheckStatus() method can be used to test the status property of the return value if desired.

Parameters:

outfile (str) – Netlist output path. If empty or omitted, a temporary file will be created and returned to the NetlistReturn.path.

options (list[str]) –

Array of option settings. Boolean options are in the form “name”; these are True if present False if not String options with a value are in the form “name=value”

Name	Type	Decsription
numbered	Boolean	If true, a SPICE 2 compatible netlist using node numbers is created
subckt	String	circuit is netlisted as subcircuit. In this case the netlist is enclosed with a .subckt control at the beginning and a .ends control at the end. Subckt terminals will be added for each module port symbol in the schematic. Subckt name set to value of option
nopinnames	Boolean	The pinnames specifier is not output for X devices. The pinnames specifier is proprietary to SIMetrix and is not supported by other simulators. Use this option if you are creating the netlist for another purpose e.g. to input to an LVS program.
noOutput	Boolean	No netlist output is generated. The net names attached to wires are updated
templates	String	Property names to be used as templates. A template is a string that specifies a format to be used for the netlist line for the device that owns it. By default the template property name is “TEMPLATE” in SIMetrix mode and “SIMPLIS_TEMPLATE in SIMPLIS mode. This can be overridden with this option. Multiple template property names may be specified by separating them with a pipe symbol (\|). See the description of the template property in Template property
sep	String	May be a single character or “none”. Default is “$”. To comply with SPICE syntax each device line starts with a letter that identifies the type of device. Usually this letter is determined by the MODEL property. If the component reference of the device does not begin with the correct letter it is prefixed with the correct letter followed by the character specified by this option.
wireTemplate	String	Format for bus wires. wire_template may contain the keywords %BUSNAME% and %WIRENUM%. These resolve to the bus name and wire number respectively. So a spec set to %BUSNAME%#%WIRENUM% would give the default, i.e. bus names like BUS1#2. A spec of %busname%[%wirenum%] would give bus names like BUS1[2].
dotEnd	Boolean	Forces .END to be placed at the end of the netlist
noDescend	Boolean	Netlister does not descend into hierarchy and processes items at the top level only
f11Top	Boolean	The contents of the F11 window are placed before the netlist lines generated by the schematic. Otherwise they are placed after the schematic netlist lines
nodemap	Boolean	Generates SIMPLIS .NODE_MAP statements for user named nets.
sort	Boolean	If specified, the netlist lines will be output in alphanumeric sorted order.
inhibitTemplateScripts	Boolean	Inhibits execution of template scripts

Examples

Use Schematic.CheckStatus() to test success.

import simetrix as sx

schematic = sx.currentSchematic()

nl = schematic.netlist()
# CheckStatus throws a run time exception if netlist fails
schematic.CheckStatus(nl.status)

f = open(nl.path, "r")
file_contents = f.read()
print(file_contents)

Test each status output and provide detailed error message on failure

import simetrix as sx

schematic = sx.currentSchematic()

nl = schematic.netlist()
if nl.status==sx.SchematicStatus.NOERR :
    f = open(nl.path, "r")
    file_contents = f.read()
    print(file_contents)
elif nl.status==sx.SchematicStatus.NOSCHEMATIC :
    print("There are no schematics open")
elif nl.status==sx.SchematicStatus.NETLISTERRORS :
    print("Netlist errors:", nl.netlistErrorMessage)
elif nl.status==sx.SchematicStatus.FILEOPENFAIL :
    print("File open failed", nl.fileforensic)
else :
    print("Unknown error")

See also

Schematic.netNames()
Schematic.netWires()
Schematic.highlightedNets()

property path: str¶: Returns the full path of the schematic’s file. Will return an empty string if the schematic does not have a path, i.e. it has not yet been saved.

propertyValue(propertyName: str) → str¶

Returns the value for the schematic property with the given propertyName.

Properties are compared using a case-insensitive comparison of their names.

Note

The property referred to here is a property of the schematic as a whole not the more often used Element Property.

Parameters:

propertyName (str) –

Name of the property. The following property names are built-in and have a special meaning as defined in the following table:

Name	Description
”Path”	Full path of schematic file. Use `Schematic.path` instead.
”RootPath”	Path of root of hierarchical schematic. Use `Schematic.rootpath` instead.
”Reference”	Hierarchical reference. Use `Schematic.reference` instead
”Readonly”	’TRUE’ if read only otherwise ‘FALSE’. Use `Schematic.readonly` instead.
”Magnification”	Current zoom level. Use `Schematic.magnification` instead.
”UserVersion”	User version. Use `Schematic.userversion` instead.
”GUID”	Unique ID.
”CreateProduct”	Name of product that created the schematic - e.g “SIMetrix/SIMPLIS”.
”Modified”	Schematic modified. Use `Schematic.modified` instead.

See also

Schematic.deleteProperty()
Schematic.schematicProperties()
Schematic.setPropertyValue()
Schematic.hasProperty()

readF11AnalysisParameter(analysisType: str, parameterName: str, nestLevel: int = -1)¶

Reads a SIMetrix analysis parameter from the F11 window.

Returns a pair with the first element the value of the parameter and the second a status value indicating whether the value is set, not set or invalid. Only parameter values explicitly set in the analysis statement are returned, that is the method does not know the default values for analysis parameters.

Parameters:

analysisType (str) – Analysis type to probe, one of .TRAN, .AC, .DC, .NOISE, .TF

parameterName (str) –

One of the names in the following table:

Parameter	Description	Used in Analyses
is_enabled	Is analysis enabled	All
stop_time	Stop time	Transient
time_step	Print step	Transient
start_time	Start data out time	Transient
max_time_step	Maximum time step	Transient
fast_time	Fast time	Transient
startup_time	Startup ramp time	Transient
uic	Boolean: Skip DC operating point	Transient
rtnstep	Real time noise time step	Transient
rtnmode	Integer: Real time noise mode	Transient
rtnstop	Real time noise stop time	Transient
snapstep	Vector: Snapshot step values	Transient
snapmode	Snapshot mode	Transient
snapshot	Vector: snapshot list values	Transient
pauseatend	Boolean: Pause at end of simulation	Transient
dec	Vector: decade sweep parameters	DC,AC,TF,Noise,Multistep
lin	Vector: linear sweep parameters	DC,AC,TF,Noise,Multistep
oct	Vector: ocal sweep parameters	DC,AC,TF,Noise,Multistep
list	Vector: Value list for list interval type	DC,AC,TF,Noise,Multistep
start_value	Start sweep value	DC,AC,TF,Noise,Multistep
stop_value	End sweep value	DC,AC,TF,Noise,Multistep
step_size	Sweep step size	DC,AC,TF,Noise,Multistep
num_points	Integer: Sweep number of points	DC,AC,TF,Noise,Multistep
device_name	String: Device reference for device sweep	DC,AC,TF,Noise,Multistep
parameter_name	String: Parameter name for parameter sweep	DC,AC,TF,Noise,Multistep
mode	String: Sweep or multistep mode	DC,AC,TF,Noise,Multistep
type	String: Interval type: dec, oct, lin, list	DC,AC,TF,Noise,Multistep
monte	Number of Monte Carlo trials	DC,AC,TF,Noise,Multistep
nomclog	Boolean: Monte Carlo log disabled	DC,AC,TF,Noise,Multistep
frequency	Fixed frequency for sweep modes	AC,TF,Noise,Multistep
output_node	String: Output node	Noise, TF
ref_node	String: Reference node	Noise, TF
source	String: Input source	Noise, TF
group_curves	Boolean: Group digital curves for multistep	Multistep
num_cores	Integer: Number of cores for multistep	Multistep
output_type	String: Voltage/current TF mode	TF
writedcop	Boolean: DCOP data written	AC,TF,Noise

nestLevel (int) – Multi step analysis level. 0 means the first level, that is the method will return information about the inner most multi-step mode. 1 means the next multi-step level etc. Omit or set to -1 to return parameter values for the main analysis

Example

import simetrix as sx

schem_file = "%DOCSPATH%/SIMetrix/Examples-93/SIMetrix/General/AMP.sxsch"
schem = sx.openSchematic(schem_file)
analyses = schem.readF11AnalysisParameter('.tran', 'stop_time')
print(analyses)
analyses = schem.readF11AnalysisParameter('.ac', 'is_enabled')
print(analyses)
analyses = schem.readF11AnalysisParameter('.ac', 'dec')
print(analyses)

See also

Schematic.getF11Lines()
Schematic.writeF11Analysis()
Schematic.readF11Options()
Schematic.writeF11Options()

readF11Options() → list[tuple[str, float | int | bool | str]]¶

Reads .options statements in F11 window. Returns a list of tuple pairs in form name = value where value can be a real, integer, boolean or string.

If there are multiple .options statements in the F11 window, the return value will including the settings in all of them.

Example

import simetrix as sx

schem_file = "%DOCSPATH%/SIMetrix/Examples-93/SIMetrix/General/AMP.sxsch"
schem = sx.openSchematic(schem_file)

print (schem.readF11Options())

See also

Schematic.getF11Lines()
Schematic.writeF11Analysis()
Schematic.writeF11Options()
Schematic.readF11AnalysisParameter()

property readonly: bool¶: Returns True if the schematic is readonly otherwise False.

property reference: str¶: Returns the hierarchical reference of the schematic or an empty string if the schematic is non-hierarchical or is the root of a schematic.

property rootpath: str¶: If the current schematic is a child in a schematic, this will return the path of root schematic in the hierarchy. If the schematic is not in a hierarchy or if the current schematic is the root, this property will return the path of the current schematic.

run(parameters: list[str] | None = None, analysisOverride: list[str] | None = None, options: list[str] | None = None) → Simulation¶

Runs a simulation on the schematic. The method supports both SIMetrix and SIMPLIS simulations and does not require the schematic to be explicitly netlisted; the run method handles the whole process.

Returns a Simulation object providing information on the success or otherwise of the simulation along with details of DataGroup objects that may be used to access the simulation’s data.

Parameters:

parameters (list[str]) –
List of parameter name=value pairs. These will override any existing parameter assignments with the same parameter name. Can be omitted, an empty list or None.

Example

Set parameters biasRes and rload. If biasRes and/or rload are already defined in the schematic, they will be overridden. If not those parameters will be added.
```
result = schematic.run(["biasRes=200", "rload=500"])
```
analysisOverride (list[str]) –
List of analysis specifications in “dot” form. For example, “.TRAN 1u 1m” or “.POP TRIG_GATE=X1.!D_CYCLE TRIG_COND=1_TO_0 MAX_PERIOD=100u”. If empty or None the analysis specifications defined in the schematic will be run. If one or more are present in this parameter, any analysis specs in the schematic will be ignored.

Example

Set analysis to “.ac dec 500 1k 100000000”. This will override all analyses defined in the schematic.
```
schematic.run(None, [".ac dec 500 1k 100000000"])
```
options (list[str]) –
List of options as defined by a .OPTIONS statement. Each option must be in one of these forms:
- name=value
- name
For the first case, if option name is already defined in the schematic, its value will be replaced with value. If name is not already present, it will be added.

The second case represents a method sometimes used to implement boolean options. For example the SIMetrix option NOOPITER and the SIMPLIS option POP_SHOWDATA use this method. If the name is present the value is TRUE and if not it is FALSE. Boolean options implemented this way can be added, i.e. set to TRUE, using this parameter but it is not possible to set to FALSE, an existing value (i.e defined in the netlist).

Examples

This is a SIMPLIS example but only the format of the analysis line and the option value presented are actually specific to SIMPLIS. The Python code will work with both SIMetrix and SIMPLIS.

import simetrix as sx
import simetrix.script.functions as sf

schematic = sx.currentSchematic()

if schematic.valid :
    result = schematic.run(["RLOAD=100"], [".TRAN 100m 40m"], ["PSP_NPT=10001"])
    if result.status==sx.RunStatus.success :
        print("success")

        print("Data available from groups:")
        for group in result.dataGroups :
            print (group.name)

    else :
        print(result.status)
        if (result.errorMessage) :
            # result.errorMessage will return a detailed error message in some
            # cases. Sometimes it is HTML formatted. The SIMetrix
            # message box function will display this correctly
            sf.MessageBox([result.errorMessage, "Failed"],["Ok", "Stop"])

else :
    print("There are no schematics open")

This is a SIMetrix example which is almost identical to the above SIMPLIS example except that the parameters, analysis definition and option values are different.

import simetrix as sx
import simetrix.script.functions as sf

schematic = sx.currentSchematic()

if schematic.valid :
    result = schematic.run(["rtail=100"], [".TRAN 0 20u"], ["TEMP=70"])
    if result.status==sx.RunStatus.success :
        print("success")

        print("Data available from groups:")
        for group in result.dataGroups :
            print (group.name)

    else :
        print(result.status)
        if (result.errorMessage) :
            # result.errorMessage will return a detailed error message in some
            # cases. Sometimes it is HTML formatted. The SIMetrix
            # message box function will display this correctly
            sf.MessageBox([result.errorMessage, "Failed"],["Ok", "Stop"])

else :
    print("There are no schematics open")

runSIMPLISMonteCarlo() → int¶

Preliminary, this method is under development and will change in future versions. Runs a SIMPLIS Monte Carlo analysis on the schematic. Returns 0 if successful otherwise a non-zero value will be returned.

Parameters:: parameters (list[str]) – List of parameter name=value pairs. These will override any existing parameter assignments with the same parameter name.

Example

import simetrix as sx

schematic = sx.openSchematic("simplis-mc.sxsch")

if schematic.valid :
    result = schematic.runSIMPLISMonteCarlo(["R2=2"])
    if result==0 :
        print("Run successful")
    else :
        print("Run failed")

else :
    print("There are no schematics open")

runSIMPLISMultiStep() → int¶

Preliminary, this method is under development and will change in future versions. Runs a SIMPLIS Multi step analysis on the schematic. Returns 0 if successful otherwise a non-zero value will be returned.

Parameters:: parameters (list[str]) – List of parameter name=value pairs. These will override any existing parameter assignments with the same parameter name.

Example

import simetrix as sx

schematic = sx.openSchematic("simplis-multi.sxsch")

if schematic.valid :
    result = schematic.runSIMPLISMultiStep(["R2=2"])
    if result==0 :
        print("Run successful")
    else :
        print("Run failed")

else :
    print("There are no schematics open")

schematicProperties(propertyName: str = None) → list[Property]¶

Returns a list of schematic Property objects. If propertyName is provided, either a single Property object with the given name will returned or an empty list will be returned if that property is not found. If no argument is provided, the method will return all the Schematic Property objects present.

Note

The property referred to here is a property of the schematic as a whole not the more often used Element Property.

Example

import simetrix as sx

schem_file = "%DOCSPATH%/SIMetrix/Examples-93/SIMetrix/General/AMP.sxsch"
schem = sx.openSchematic(schem_file)

props = schem.schematicProperties()

for p in props :
    print(p.name, p.value, p.protected)

See also

Schematic.propertyValue()
Schematic.deleteProperty()
Schematic.setPropertyValue()
Schematic.hasProperty()

select() → SchematicStatus¶

Select a schematic sheet, i.e. bring it in to focus. Returns a status value indicating success or otherwise. Possible return values are: NOERR, NOSCHEMATIC or UNEXPECTED. NOSCHEMATIC means that the Schematic object is invalid. This method will not throw an exception on error, but the Schematic.CheckStatus() method can be used to check the return status. Note that NOERR will be returned if the Schematic is valid but not open in the GUI.

Example

import simetrix as sx

schematic = sx.currentSchematic()

# Will throw a run time exception if schematic is invalid.
schematic.CheckStatus(schematic.select())

selectedAnnotations(option: SelectionOptions = SelectionOptions.FULL) → list[Element]¶

Returns all selected annotation objects in the schematic. If option = SelectionOptions.PARTIAL, all annotation objects including partially selected annotation objects will be returned. Typicaly a partially selected annotation objects has only one side or one corner selected. If option = SelectionOptions.FULL, the default value, only fully selected annotation objects will be returned.

Parameters:: option (SelectionOptions) – If SelectionOptions.PARTIAL both partially selected and fully selected annotations will be returned. If SelectionOptions.FULL only fully selected annotations will be returned.

See also

Schematic.annotations()
Schematic.selectedWires()
Schematic.wires()
Schematic.selectedInstances()
Schematic.instances()
Schematic.selectedElements()
Schematic.elements()

selectedElements(options: SelectionOptions = SelectionOptions.FULL) → list[Element]¶

Returns schematic Element objects of any type (instances, wires and annotations) that are currently selected.

Parameters:: options (SelectionOptions) – Set to SelectionOptions.PARTIAL to include items that are only partially selected. For example, wires selected at only one end or annotation objects only selected at one corner. Otherwise only items that are fully selected will returned.

Example

import simetrix as sx

schematic_file = "%DOCSPATH%/SIMetrix/Examples-93/SIMetrix/General/AMP.sxsch"
schematic = sx.openSchematic(schematic_file)

# returns all objects with a REF property
elements = schematic.selectedElements()

for el in elements :
    print(el.type)

See also

Schematic.selectedAnnotations()
Schematic.annotations()
Schematic.selectedWires()
Schematic.wires()
Schematic.selectedInstances()
Schematic.instances()
Schematic.elements()

selectedInstances() → list[Element]¶

Returns a list of selected instances.

Parameters:

propertyName (str) – Name of property to search.
propertyName – Value of property to search.

Example

# List reference designators of all selected instances
import simetrix as sx

schematic_file = "%DOCSPATH%/SIMetrix/Examples-93/SIMetrix/General/AMP.sxsch"
schematic = sx.openSchematic(schematic_file)

elements = schematic.selectedInstances()

for el in elements :
    print(el.propertyValue('REF'))

See also

Schematic.selectedAnnotations()
Schematic.annotations()
Schematic.selectedWires()
Schematic.wires()
Schematic.instances()
Schematic.selectedElements()
Schematic.elements()

selectedWires(option: SelectionOptions = SelectionOptions.FULL) → list[Element]¶

Returns all selected wires in the schematic. If option is SelectionOptions.PARTIAL, all wires including partially selected wires will be returned. A partially selected wire is a wire selected at only one end. If option is SelectionOptions.FULL, the default value, only fully selected wires, that is selected at both ends, will be returned.

Parameters:: option (SelectionOptions) – If SelectionOptions.PARTIAL both partially selected and fully selected wires will be returned. If SelectionOptions.FULL only fully selected wires will be returned.

Example

import simetrix as sx

schematic = sx.currentSchematic()

wires = schematic.selectedWires()

for el in wires :
    print(el.propertyValue('NetName'))

See also

Schematic.selectedAnnotations()
Schematic.annotations()
Schematic.wires()
Schematic.selectedInstances()
Schematic.instances()
Schematic.selectedElements()
Schematic.elements()

setComponentValue(address: str, value: str) → SetComponentValueResult¶

Special function to get a component value or parameter. It provides a way of setting or getting a value or parameter on a schematic using a single string to identify it. This is in contrast to the usual methods to retrieve values or set values that require a sequence of commands or functions.

Parameters:

address (str) – Address of component whose value is required.
value (str) – New value of item

setPropertyValue(propertyName: str, propertyValue: str) → SchematicStatus¶

Sets a schematic property with the given name and value. Returns a status value indicating success or otherwise. Possible return values are: NOERR, PROTECTED, NOSCHEMATIC and UNEXPECTED. This method will not throw an exception on error, but the Schematic.CheckStatus() method can be used to check the return status.

If a property already exists within this object with the same name as provided, the existing property is overwritten with the new property. Otherwise if no property exists with the provided name, a new property is added to the schematic.

Properties are compared using a case-insensitive comparison of their names.

Note

The property referred to here is a property of the schematic as a whole not the more often used Element Property.

Parameters:

name (str) – Name of the property.
value – Value of the property.

Example

import simetrix as sx

schematic = sx.currentSchematic()

schematic.setPropertyValue("newprop", "Hello World!")
print (schematic.propertyValue("newprop"))

See also

Schematic.propertyValue()
Schematic.deleteProperty()
Schematic.schematicProperties()
Schematic.hasProperty()

property simulatorMode: Simulator¶

Returns current simulator mode of the schematic.

Example

import simetrix as sx

schematic = sx.currentSchematic()

if schematic.valid :

    mode = schematic.simulatorMode
    if mode==sx.Simulator.SIMPLIS :
        print("Schematic is in SIMPLIS mode")
    elif mode==sx.Simulator.SIMETRIX :
        print("Schematic is in SIMetrix mode")
    else :
        print("Unexpected error")

else :
    print("There are no schematics open")

property userversion: int¶: Returns the auto-incrementing user version number. Each time the schematic is saved, this number increments.

property valid: bool¶: Returns True if the Schematic object is valid. That is a schematic with the stored id exists within the SIMetrix environment.

Note

If a Schematic object is created in the Python environment and it is valid at the time of creation, it will remain valid for the lifetime of the Python execution even if the schematic is subsequently closed in the GUI.

wires(propertyName: str = 'handle', propertyValue: str = None) → list[Element]¶

Returns wires with defined properties. Results are Element objects. Similar to Schematic.elements() but only returns wires whereas Schematic.elements() also returns annotations and instances. Result filtered by propertyName and propertyValue arguments. propertName specifies a property name that all returned objects must possess. propertyValue is optional and defines a value for the property. If omitted or None, all objects possessing the property defined by propertyName will be returned. As all wires have a ‘handle’ property, omitting propertyName will lead to all wires in the schematic being returned.

Parameters:

propertyName (str) – Name of property to search.
propertyName – Value of property to search.

Example

import simetrix as sx

schematic_file = "%DOCSPATH%/SIMetrix/Examples-93/SIMetrix/General/AMP.sxsch"
schematic = sx.openSchematic(schematic_file)

# returns all wires .
wires = schematic.wires()

for el in wires :
    print(el.propertyValue('NetName'))

See also

Schematic.selectedAnnotations()
Schematic.annotations()
Schematic.selectedWires()
Schematic.selectedInstances()
Schematic.instances()
Schematic.selectedElements()
Schematic.elements()

writeF11Analysis(analysis: str, status: AnalysisEnable = AnalysisEnable.NOCHANGE) → SchematicStatus¶

Writes a SIMetrix analysis line to the F11 window. Can also enable or disable an existing analysis line. This method works only with SIMetrix analysis lines, it does not handle SIMPLIS analysis lines.

Returns, SchematicStatus.NOERR (success), SchematicStatus.ERRORS (failed), SchematicStatus.NOSCHEMATIC (schematic invalid) or SchematicStatus.UNEXPECTED (unexpected error). This method will not throw an exception on error, but the Schematic.CheckStatus() method can be used to check the return status.

Parameters:

analysis (str) –
Analysis line. This will replace any existing line describing the same analysis type (.TRAN, .AC etc). If no such analysis is already present, one will be added.

If just the analysis command is present, e.g. “.TRAN”, any existing analysis of the same type already defined will remain unchanged except that it will be disabled or enabled according to the status argument. For example, the following will enable any existing .TRAN analysis if previously disabled:
```
status = schem.writeF11Analysis(".TRAN", sx.AnalysisEnable.ENABLE)
```
status (AnalysisEnable) – Enable/disable analysis. If omitted, set to None or set to AnalysisEnable.NOCHANGE, the analysis state will remain unchanged.

Example

import simetrix as sx

schem_file = "%DOCSPATH%/SIMetrix/Examples-93/SIMetrix/General/AMP.sxsch"
schem = sx.openSchematic(schem_file)

status = schem.writeF11Analysis(".TRAN 0 5u 1u 1n")

if status==sx.SchematicStatus.NOERR :
    # read back start time
    analyses = schem.readF11AnalysisParameter('.tran', 'start_time')
    print(analyses)
elif status==sx.SchematicStatus.NOSCHEMATIC :
    print("Cannot find schematic")

See also

Schematic.getF11Lines()
Schematic.readF11Options()
Schematic.writeF11Options()
Schematic.readF11AnalysisParameter()

writeF11Options(options: list[tuple[str, float | int | bool | str]]) → SchematicStatus¶

Write SIMetrix simulator options to the F11 window.

Returns SchematicStatus.NOERR (success), SchematicStatus.NOSCHEMATIC (schematic not valid) or SchematicStatus.UNEXPECTED (unexpected result).

Parameters:: options (list[ (str, float | int | bool | str)]) – List of pairs with first item the options name and second item the value which may be a real, integer, boolean or string.

Example

import simetrix as sx

schem_file = "%DOCSPATH%/SIMetrix/Examples-93/SIMetrix/General/AMP.sxsch"
schem = sx.openSchematic(schem_file)

schem.CheckStatus (schem.writeF11Options( [('reltol', 1e-4 ), ('method', 'gear' )]))

See also

Schematic.getF11Lines()
Schematic.writeF11Analysis()
Schematic.readF11Options()
Schematic.readF11AnalysisParameter()