simetrix.Element¶

class simetrix.Element¶

Bases: object

Represents any schematic object.

Schematic Element objects are objects that exist within a schematic. They have a unique to the schematic handle, along with a set of properties. Element objects reference all schematic objects:

Instances
Wires
Annotation objects

Methods

`addProperty`(property)	Sets the objects property with the value and attributes of a given `Property` object.
`bounds`([option])	Returns the bounds of an element.
`hasProperty`(propertyName)	Returns whether the object has a property with the given name.
`instanceNets`([option])	Returns a list of nets connected to the instance.
`instancePins`([option])	Returns a list of instance `Pin` objects for each of the pins of the instance.
`prop`(propertyName)	Get property of given name.
`properties`()	Returns the set of properties for this object.
`propertyNames`()	Returns a list of all property names for this object.
`propertyValue`(propertyName)	Returns the value for the property with the given name.
`setPropertyObject`(property)	Sets the objects property with the value and attributes of a given `Property` object.
`setPropertyValue`(propertyName, propertyValue)	Sets a property for this object with the given name and value.

Attributes

`handle`	Returns the object handle for use with with SIMetrix script functions.
`instancePosition`	Returns the location and orientation of the instance.
`isComponent`	Returns True if the element is a hierarchical component, otherwise returns False.
`schematic`	Get schematic associated with element.
`symbolName`	Returns the name of the symbol used by an instance.
`type`	Type of object, e.g., instance, wire or annotation.
`wirePoints`	Returns two element list containing the the absolute locations of the two end points of a wire.

addProperty(property: Property) → SchematicStatus¶

Sets the objects property with the value and attributes of a given Property object. If the Element does not possess the given property, the property will be added.

Returns a status value indicating the success of the operation. This method will not throw an exception if the schematic or element is not valid but will instead return a status value indicating the success or otherwise of the operation. Call Schematic.CheckStatus() to check the return value for errors.

This method is the same as Element.setPropertyObject() except that it will add a property that is not already present. Element.setPropertyObject() fails if the provided property is not present.

Parameters:: property (Property) – Property object to set.

See also

Element.addProperty()
Element.setPropertyValue()

bounds(option: list[BoundsOptions] = []) → Rect¶

Returns the bounds of an element. The function returns a Rect object which defines the area occupied by the element. The values are in “sheet units”. There are 120 sheet units per visible grid square at X 1 magnification. Values increase left to right and top to bottom.

The method works with all element types including wires.

Parameters:

option (list[BoundsOptions]) –

Zero, one or two element list with a combination of these values:

Value	Description
BoundsOptions.RELATIVE	Return bounds of element relative to the element’s origin point. Otherwise returned value is relative to the schematic’s origin point.
BoundsOptions.BODYONLY	Display bounds of graphics only excluding property text. Otherwise includes visible property text. Applicable to instances only.

Example

import simetrix as sx

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

inst = schem.instances('REF', 'Q2')

bounds = inst[0].bounds([sx.BoundsOptions.RELATIVE, sx.BoundsOptions.BODYONLY])

print(bounds.left, bounds.top, bounds.right, bounds.bottom)

property handle: str¶: Returns the object handle for use with with SIMetrix script functions.

hasProperty(propertyName: str) → bool¶

Returns whether the object has a property with the given name.

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

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

instanceNets(option: PathOptions = PathOptions.RELATIVE) → list[str]¶

Returns a list of nets connected to the instance.

Parameters:: option (PathOptions) – Valid values: PathOptions.ABSOLUTE and PathOptions.RELATIVE. If set to PathOptions.ABSOLUTE, method will returns the full hierarchical path of the net. Otherwise it will return the local path.

Example

import simetrix as sx

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

inst = schem.instances('REF', 'Q2')

nets = inst[0].instanceNets()

print(nets)

instancePins(option: LocationOptions = LocationOptions.ABSOLUTE) → list[Pin]¶

Returns a list of instance Pin objects for each of the pins of the instance.

Parameters:: option (LocationOptions) – May be LocationOptions.RELATIVE or LocationOptions.ABSOLUTE. If set to LocationOptions.RELATIVE the location of the pins reported will be relative to the instance origin. Otherwise the position reported will be an absolute schematic location.

Example

import simetrix as sx

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

inst = schem.instances('REF', 'Q2')

pins = inst[0].instancePins(sx.LocationOptions.RELATIVE)

for p in pins :
    print("name=", p.name, "x=", p.point.x, "y=", p.point.y)

property instancePosition: InstancePosition¶

Returns the location and orientation of the instance.

Example

import simetrix as sx

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

inst = schem.instances('REF', 'Q3')

pos = inst[0].instancePosition

print("x=", pos.point.x, "y=", pos.point.y, "orient=", pos.orient)

property isComponent: bool¶: Returns True if the element is a hierarchical component, otherwise returns False. A hierarchical component obtains its symbol from a schematic file instead of the local or global symbol library.

prop(propertyName: str) → Property¶

Get property of given name. Can also use property().

Parameters:: propertyName (str) – Name of property to retrieve.

Example

import simetrix as sx

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

inst = schem.instances('REF', 'Q2')

if len(inst)>0 :

    prop = inst[0].prop('value')

    print(prop.value)

else :
    print("Cannot find instance REF:Q2")

properties() → list[Property]¶

Returns the set of properties for this object.

Example

import simetrix as sx

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

# Get instances with Reference designator 'Q6'. (There would ordinarily be only one)
refs = schem.instances('Ref', 'Q6')

# Iterate through instances
for ref in refs :
   # Get all properties owned by instance
    props = ref.properties()
    for prop in props :
        # print name, value and whether or not visible
        print(prop.name, prop.value, "visible=", "YES" if prop.visible else "NO")

propertyNames() → list[str]¶

Returns a list of all property names for this object.

Example

import simetrix as sx

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

# Get instances with Reference designator 'Q6'. (There would ordinarily be only one)
refs = schem.instances('Ref', 'Q6')

# Iterate through instances - should be just one
for ref in refs :
    names = ref.propertyNames()
    for n in names :
        print(n)

propertyValue(propertyName: str) → str¶

Returns the value for the property with the given name. Note, property names are case-insensitive. Returns None if the element does not possess the given property.

A property value can also be obtained using the Element.prop() method. For example, the following lines are equivalent as long as the element ‘el’ possesses a ‘REF’ property:

el.prop('REF').value
el.propertyValue('REF')

However the above lines will behave differently if the ‘REF’ property is not present. The first line will throw a runtime error as an attempt was made to access a non-existent object. The second will return None.

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

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.elements('REF')

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

property schematic: Schematic¶: Get schematic associated with element.

setPropertyObject(property: Property) → SchematicStatus¶

Sets the objects property with the value and attributes of a given Property object. If the Element does not possess the given property, no change to the Element will be made.

Parameters:: property (Property) – Property object to set.

Example

import simetrix as sx

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

inst = schem.instances('REF', 'Q2')

# Change value property to 'q2n2222' and copy attribute flags from
# Ref property

if len(inst)>0 :
    # Get reference and value property
    propref = inst[0].prop('REF')
    prop = inst[0].prop('value')

    # Check properties are valid
    if propref.valid and prop.valid :

        # Get value
        prop = inst[0].prop('value')
        # Change value
        prop.value = 'q2n2222'
        # copy flags from Ref property
        prop.flags = propref.flags

        # set new property value and attributes
        status = inst[0].setPropertyObject(prop)
        print(status)

    else :
        print("Instance doesn't have that property")

else :
    print("Cannot find instance REF:Q2")