API reference - Class DeviceClass

Notation used in Ruby API documentation

Module: db

Description: A class describing a specific type of device.

Device class objects live in the context of a Netlist object. After a device class is created, it must be added to the netlist using Netlist#add. The netlist will own the device class object. When the netlist is destroyed, the device class object will become invalid.

The DeviceClass class is the base class for other device classes.

This class has been added in version 0.26. In version 0.27.3, the 'GenericDeviceClass' has been integrated with DeviceClass and the device class was made writeable in most respects. This enables manipulating built-in device classes.

Public constructors

new DeviceClass ptrnewCreates a new object of this class

Public methods

void_createEnsures the C++ object is created
void_destroyExplicitly destroys the object
[const]bool_destroyed?Returns a value indicating whether the object was already destroyed
[const]bool_is_const_object?Returns a value indicating whether the reference is a const reference
void_manageMarks the object as managed by the script side.
void_unmanageMarks the object as no longer owned by the script side.
voidadd_parameter(DeviceParameterDefinition ptr parameter_def)Adds the given parameter definition to the device class
voidadd_terminal(DeviceTerminalDefinition ptr terminal_def)Adds the given terminal definition to the device class
voidassign(const DeviceClass other)Assigns another object to self
voidclear_equivalent_terminal_idsClears all equivalent terminal ids
voidclear_parametersClears the list of parameters
voidclear_terminalsClears the list of terminals
GenericDeviceCombiner ptrcombinerGets a device combiner or nil if none is registered.
voidcombiner=(GenericDeviceCombiner ptr combiner)Specifies a device combiner (parallel or serial device combination).
[const]stringdescriptionGets the description text of the device class.
voiddescription=(string description)Sets the description of the device class.
[const]new DeviceClass ptrdupCreates a copy of self
voidenable_parameter(unsigned long parameter_id,
bool enable)
Enables or disables a parameter.
voidenable_parameter(string parameter_name,
bool enable)
Enables or disables a parameter.
EqualDeviceParameters ptrequal_parametersGets the device parameter comparer for netlist verification or nil if no comparer is registered.
voidequal_parameters=(EqualDeviceParameters ptr comparer)Specifies a device parameter comparer for netlist verification.
voidequivalent_terminal_id(unsigned long original_id,
unsigned long equivalent_id)
Specifies a terminal to be equivalent to another.
[const]boolhas_parameter?(string name)Returns true, if the device class has a parameter with the given name.
[const]boolhas_terminal?(string name)Returns true, if the device class has a terminal with the given name.
[const]unsigned longidGets the unique ID of the device class
[const]stringnameGets the name of the device class.
voidname=(string name)Sets the name of the device class.
Netlist ptrnetlistGets the netlist the device class lives in.
[const]const DeviceParameterDefinition ptrparameter_definition(unsigned long parameter_id)Gets the parameter definition object for a given ID.
[const]const DeviceParameterDefinition ptrparameter_definition(string parameter_name)Gets the parameter definition object for a given ID.
[const]DeviceParameterDefinition[]parameter_definitionsGets the list of parameter definitions of the device.
[const]unsigned longparameter_id(string name)Returns the parameter ID of the parameter with the given name.
voidstrict=(bool s)Sets a value indicating whether this class performs strict terminal mapping
[const]boolstrict?Gets a value indicating whether this class performs strict terminal mapping
voidsupports_parallel_combination=(bool f)Specifies whether the device supports parallel device combination.
voidsupports_serial_combination=(bool f)Specifies whether the device supports serial device combination.
[const]const DeviceTerminalDefinition ptrterminal_definition(unsigned long terminal_id)Gets the terminal definition object for a given ID.
[const]DeviceTerminalDefinition[]terminal_definitionsGets the list of terminal definitions of the device.
[const]unsigned longterminal_id(string name)Returns the terminal ID of the terminal with the given name.

Deprecated methods (protected, public, static, non-static and constructors)

voidcreateUse of this method is deprecated. Use _create instead
voiddestroyUse of this method is deprecated. Use _destroy instead
[const]booldestroyed?Use of this method is deprecated. Use _destroyed? instead
[const]boolis_const_object?Use of this method is deprecated. Use _is_const_object? instead

Detailed description

_create

Signature: void _create

Description: Ensures the C++ object is created

Use this method to ensure the C++ object is created, for example to ensure that resources are allocated. Usually C++ objects are created on demand and not necessarily when the script object is created.

_destroy

Signature: void _destroy

Description: Explicitly destroys the object

Explicitly destroys the object on C++ side if it was owned by the script interpreter. Subsequent access to this object will throw an exception. If the object is not owned by the script, this method will do nothing.

_destroyed?

Signature: [const] bool _destroyed?

Description: Returns a value indicating whether the object was already destroyed

This method returns true, if the object was destroyed, either explicitly or by the C++ side. The latter may happen, if the object is owned by a C++ object which got destroyed itself.

_is_const_object?

Signature: [const] bool _is_const_object?

Description: Returns a value indicating whether the reference is a const reference

This method returns true, if self is a const reference. In that case, only const methods may be called on self.

_manage

Signature: void _manage

Description: Marks the object as managed by the script side.

After calling this method on an object, the script side will be responsible for the management of the object. This method may be called if an object is returned from a C++ function and the object is known not to be owned by any C++ instance. If necessary, the script side may delete the object if the script's reference is no longer required.

Usually it's not required to call this method. It has been introduced in version 0.24.

_unmanage

Signature: void _unmanage

Description: Marks the object as no longer owned by the script side.

Calling this method will make this object no longer owned by the script's memory management. Instead, the object must be managed in some other way. Usually this method may be called if it is known that some C++ object holds and manages this object. Technically speaking, this method will turn the script's reference into a weak reference. After the script engine decides to delete the reference, the object itself will still exist. If the object is not managed otherwise, memory leaks will occur.

Usually it's not required to call this method. It has been introduced in version 0.24.

add_parameter

Signature: void add_parameter (DeviceParameterDefinition ptr parameter_def)

Description: Adds the given parameter definition to the device class

This method will define a new parameter. The new parameter is added at the end of existing parameters. The parameter definition object passed as the argument is modified to contain the new ID of the parameter. The parameter is copied into the device class. Modifying the parameter object later does not have the effect of changing the parameter definition.

This method has been moved from 'GenericDeviceClass' to 'DeviceClass' in version 0.27.3.

add_terminal

Signature: void add_terminal (DeviceTerminalDefinition ptr terminal_def)

Description: Adds the given terminal definition to the device class

This method will define a new terminal. The new terminal is added at the end of existing terminals. The terminal definition object passed as the argument is modified to contain the new ID of the terminal.

The terminal is copied into the device class. Modifying the terminal object later does not have the effect of changing the terminal definition.

This method has been moved from 'GenericDeviceClass' to 'DeviceClass' in version 0.27.3.

assign

Signature: void assign (const DeviceClass other)

Description: Assigns another object to self

clear_equivalent_terminal_ids

Signature: void clear_equivalent_terminal_ids

Description: Clears all equivalent terminal ids

This method has been added in version 0.27.3.

clear_parameters

Signature: void clear_parameters

Description: Clears the list of parameters

This method has been added in version 0.27.3.

clear_terminals

Signature: void clear_terminals

Description: Clears the list of terminals

This method has been moved from 'GenericDeviceClass' to 'DeviceClass' in version 0.27.3.

combiner

Signature: GenericDeviceCombiner ptr combiner

Description: Gets a device combiner or nil if none is registered.

This method has been added in version 0.27.3.

Python specific notes:
The object exposes a readable attribute 'combiner'. This is the getter.

combiner=

Signature: void combiner= (GenericDeviceCombiner ptr combiner)

Description: Specifies a device combiner (parallel or serial device combination).

You can assign nil for the combiner to remove it.

In special cases, you can even implement a custom combiner by deriving your own comparer from the GenericDeviceCombiner class.

This method has been added in version 0.27.3.

Python specific notes:
The object exposes a writable attribute 'combiner'. This is the setter.

create

Signature: void create

Description: Ensures the C++ object is created

Use of this method is deprecated. Use _create instead

Use this method to ensure the C++ object is created, for example to ensure that resources are allocated. Usually C++ objects are created on demand and not necessarily when the script object is created.

description

Signature: [const] string description

Description: Gets the description text of the device class.

Python specific notes:
The object exposes a readable attribute 'description'. This is the getter.

description=

Signature: void description= (string description)

Description: Sets the description of the device class.

Python specific notes:
The object exposes a writable attribute 'description'. This is the setter.

destroy

Signature: void destroy

Description: Explicitly destroys the object

Use of this method is deprecated. Use _destroy instead

Explicitly destroys the object on C++ side if it was owned by the script interpreter. Subsequent access to this object will throw an exception. If the object is not owned by the script, this method will do nothing.

destroyed?

Signature: [const] bool destroyed?

Description: Returns a value indicating whether the object was already destroyed

Use of this method is deprecated. Use _destroyed? instead

This method returns true, if the object was destroyed, either explicitly or by the C++ side. The latter may happen, if the object is owned by a C++ object which got destroyed itself.

dup

Signature: [const] new DeviceClass ptr dup

Description: Creates a copy of self

enable_parameter

(1) Signature: void enable_parameter (unsigned long parameter_id, bool enable)

Description: Enables or disables a parameter.

Some parameters are 'secondary' parameters which are extracted but not handled in device compare and are not shown in the netlist browser. For example, the 'W' parameter of the resistor is such a secondary parameter. This method allows turning a parameter in a primary one ('enable') or into a secondary one ('disable').

This method has been introduced in version 0.27.3.

(2) Signature: void enable_parameter (string parameter_name, bool enable)

Description: Enables or disables a parameter.

Some parameters are 'secondary' parameters which are extracted but not handled in device compare and are not shown in the netlist browser. For example, the 'W' parameter of the resistor is such a secondary parameter. This method allows turning a parameter in a primary one ('enable') or into a secondary one ('disable').

This version accepts a parameter name.

This method has been introduced in version 0.27.3.

equal_parameters

Signature: EqualDeviceParameters ptr equal_parameters

Description: Gets the device parameter comparer for netlist verification or nil if no comparer is registered.

See equal_parameters= for the setter.

This method has been moved from 'GenericDeviceClass' to 'DeviceClass' in version 0.27.3.

Python specific notes:
The object exposes a readable attribute 'equal_parameters'. This is the getter.

equal_parameters=

Signature: void equal_parameters= (EqualDeviceParameters ptr comparer)

Description: Specifies a device parameter comparer for netlist verification.

By default, all devices are compared with all parameters. If you want to select only certain parameters for comparison or use a fuzzy compare criterion, use an EqualDeviceParameters object and assign it to the device class of one netlist. You can also chain multiple EqualDeviceParameters objects with the '+' operator for specifying multiple parameters in the equality check.

You can assign nil for the parameter comparer to remove it.

In special cases, you can even implement a custom compare scheme by deriving your own comparer from the GenericDeviceParameterCompare class.

This method has been moved from 'GenericDeviceClass' to 'DeviceClass' in version 0.27.3.

Python specific notes:
The object exposes a writable attribute 'equal_parameters'. This is the setter.

equivalent_terminal_id

Signature: void equivalent_terminal_id (unsigned long original_id, unsigned long equivalent_id)

Description: Specifies a terminal to be equivalent to another.

Use this method to specify two terminals to be exchangeable. For example to make S and D of a MOS transistor equivalent, call this method with S and D terminal IDs. In netlist matching, S will be translated to D and thus made equivalent to D.

Note that terminal equivalence is not effective if the device class operates in strict mode (see DeviceClass#strict=).

This method has been moved from 'GenericDeviceClass' to 'DeviceClass' in version 0.27.3.

has_parameter?

Signature: [const] bool has_parameter? (string name)

Description: Returns true, if the device class has a parameter with the given name.

has_terminal?

Signature: [const] bool has_terminal? (string name)

Description: Returns true, if the device class has a terminal with the given name.

id

Signature: [const] unsigned long id

Description: Gets the unique ID of the device class

The ID is a unique integer that identifies the device class. Use the ID to check for object identity - i.e. to determine whether two devices share the same device class.

is_const_object?

Signature: [const] bool is_const_object?

Description: Returns a value indicating whether the reference is a const reference

Use of this method is deprecated. Use _is_const_object? instead

This method returns true, if self is a const reference. In that case, only const methods may be called on self.

name

Signature: [const] string name

Description: Gets the name of the device class.

Python specific notes:
The object exposes a readable attribute 'name'. This is the getter.

name=

Signature: void name= (string name)

Description: Sets the name of the device class.

Python specific notes:
The object exposes a writable attribute 'name'. This is the setter.

netlist

Signature: Netlist ptr netlist

Description: Gets the netlist the device class lives in.

new

Signature: [static] new DeviceClass ptr new

Description: Creates a new object of this class

Python specific notes:
This method is the default initializer of the object

parameter_definition

(1) Signature: [const] const DeviceParameterDefinition ptr parameter_definition (unsigned long parameter_id)

Description: Gets the parameter definition object for a given ID.

Parameter definition IDs are used in some places to reference a specific parameter of a device. This method obtains the corresponding definition object.

(2) Signature: [const] const DeviceParameterDefinition ptr parameter_definition (string parameter_name)

Description: Gets the parameter definition object for a given ID.

Parameter definition IDs are used in some places to reference a specific parameter of a device. This method obtains the corresponding definition object. This version accepts a parameter name.

This method has been introduced in version 0.27.3.

parameter_definitions

Signature: [const] DeviceParameterDefinition[] parameter_definitions

Description: Gets the list of parameter definitions of the device.

See the DeviceParameterDefinition class description for details.

parameter_id

Signature: [const] unsigned long parameter_id (string name)

Description: Returns the parameter ID of the parameter with the given name.

An exception is thrown if there is no parameter with the given name. Use has_parameter to check whether the name is a valid parameter name.

strict=

Signature: void strict= (bool s)

Description: Sets a value indicating whether this class performs strict terminal mapping

Classes with this flag set never allow terminal swapping, even if the device symmetry supports that. If two classes are involved in a netlist compare, terminal swapping will be disabled if one of the classes is in strict mode.

By default, device classes are not strict and terminal swapping is allowed as far as the device symmetry supports that.

Python specific notes:
The object exposes a writable attribute 'strict'. This is the setter.

strict?

Signature: [const] bool strict?

Description: Gets a value indicating whether this class performs strict terminal mapping

See strict= for details about this attribute.

Python specific notes:
The object exposes a readable attribute 'strict'. This is the getter.

supports_parallel_combination=

Signature: void supports_parallel_combination= (bool f)

Description: Specifies whether the device supports parallel device combination.

Parallel device combination means that all terminals of two combination candidates are connected to the same nets. If the device does not support this combination mode, this predicate can be set to false. This will make the device extractor skip the combination test in parallel mode and improve performance somewhat.

This method has been moved from 'GenericDeviceClass' to 'DeviceClass' in version 0.27.3.

Python specific notes:
The object exposes a writable attribute 'supports_parallel_combination'. This is the setter.

supports_serial_combination=

Signature: void supports_serial_combination= (bool f)

Description: Specifies whether the device supports serial device combination.

Serial device combination means that the devices are connected by internal nodes. If the device does not support this combination mode, this predicate can be set to false. This will make the device extractor skip the combination test in serial mode and improve performance somewhat.

This method has been moved from 'GenericDeviceClass' to 'DeviceClass' in version 0.27.3.

Python specific notes:
The object exposes a writable attribute 'supports_serial_combination'. This is the setter.

terminal_definition

Signature: [const] const DeviceTerminalDefinition ptr terminal_definition (unsigned long terminal_id)

Description: Gets the terminal definition object for a given ID.

Terminal definition IDs are used in some places to reference a specific terminal of a device. This method obtains the corresponding definition object.

terminal_definitions

Signature: [const] DeviceTerminalDefinition[] terminal_definitions

Description: Gets the list of terminal definitions of the device.

See the DeviceTerminalDefinition class description for details.

terminal_id

Signature: [const] unsigned long terminal_id (string name)

Description: Returns the terminal ID of the terminal with the given name.

An exception is thrown if there is no terminal with the given name. Use has_terminal to check whether the name is a valid terminal name.