API reference - Class Device

Notation used in Ruby API documentation

Module: db

Description: A device inside a circuit.

Class hierarchy: Device » NetlistObject

Device object represent atomic devices such as resistors, diodes or transistors. The Device class represents a particular device with specific parameters. The type of device is represented by a DeviceClass object. Device objects live in Circuit objects, the device class objects live in the Netlist object.

Devices connect to nets through terminals. Terminals are described by a terminal ID which is essentially the zero-based index of the terminal. Terminal definitions can be obtained from the device class using the DeviceClass#terminal_definitions method.

Devices connect to nets through the Device#connect_terminal method. Device terminals can be disconnected using Device#disconnect_terminal.

Device objects are created inside a circuit with Circuit#create_device.

This class has been added in version 0.26.

Public methods

void_assign(const Device other)Assigns another object to self
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]new Device ptr_dupCreates a copy of self
[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.
[const]const Circuit ptrcircuitGets the circuit the device lives in.
Circuit ptrcircuitGets the circuit the device lives in (non-const version).
voidconnect_terminal(unsigned long terminal_id,
Net ptr net)
Connects the given terminal to the specified net.
voidconnect_terminal(string terminal_name,
Net ptr net)
Connects the given terminal to the specified net.
[const]const DeviceAbstract ptrdevice_abstractGets the device abstract for this device instance.
[const]const DeviceClass ptrdevice_classGets the device class the device belongs to.
voiddisconnect_terminal(unsigned long terminal_id)Disconnects the given terminal from any net.
voiddisconnect_terminal(string terminal_name)Disconnects the given terminal from any net.
[const,iter]DeviceAbstractRefeach_combined_abstractIterates over the combined device specifications.
[const,iter]DeviceReconnectedTerminaleach_reconnected_terminal_for(unsigned long terminal_id)Iterates over the reconnected terminal specifications for a given outer terminal.
[const]stringexpanded_nameGets the expanded name of the device.
[const]unsigned longidGets the device ID.
[const]boolis_combined_device?Returns true, if the device is a combined device.
[const]stringnameGets the name of the device.
voidname=(string name)Sets the name of the device.
[const]const Net ptrnet_for_terminal(unsigned long terminal_id)Gets the net connected to the specified terminal.
Net ptrnet_for_terminal(unsigned long terminal_id)Gets the net connected to the specified terminal (non-const version).
[const]const Net ptrnet_for_terminal(string terminal_name)Gets the net connected to the specified terminal.
const Net ptrnet_for_terminal(string terminal_name)Gets the net connected to the specified terminal (non-const version).
[const]doubleparameter(unsigned long param_id)Gets the parameter value for the given parameter ID.
[const]doubleparameter(string param_name)Gets the parameter value for the given parameter name.
voidset_parameter(unsigned long param_id,
double value)
Sets the parameter value for the given parameter ID.
voidset_parameter(string param_name,
double value)
Sets the parameter value for the given parameter name.
[const]DCplxTranstransGets the location of the device.
voidtrans=(const DCplxTrans t)Sets the location of the device.

Detailed description

_assign

Signature: void _assign (const Device other)

Description: Assigns another object to self

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

_dup

Signature: [const] new Device ptr _dup

Description: Creates a copy of self

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

circuit

(1) Signature: [const] const Circuit ptr circuit

Description: Gets the circuit the device lives in.

(2) Signature: Circuit ptr circuit

Description: Gets the circuit the device lives in (non-const version).

This constness variant has been introduced in version 0.26.8

connect_terminal

(1) Signature: void connect_terminal (unsigned long terminal_id, Net ptr net)

Description: Connects the given terminal to the specified net.

(2) Signature: void connect_terminal (string terminal_name, Net ptr net)

Description: Connects the given terminal to the specified net.

This version accepts a terminal name. If the name is not a valid terminal name, an exception is raised. If the terminal has been connected to a global net, it will be disconnected from there.

device_abstract

Signature: [const] const DeviceAbstract ptr device_abstract

Description: Gets the device abstract for this device instance.

See DeviceAbstract for more details.

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

device_class

Signature: [const] const DeviceClass ptr device_class

Description: Gets the device class the device belongs to.

disconnect_terminal

(1) Signature: void disconnect_terminal (unsigned long terminal_id)

Description: Disconnects the given terminal from any net.

If the terminal has been connected to a global, this connection will be disconnected too.

(2) Signature: void disconnect_terminal (string terminal_name)

Description: Disconnects the given terminal from any net.

This version accepts a terminal name. If the name is not a valid terminal name, an exception is raised.

each_combined_abstract

Signature: [const,iter] DeviceAbstractRef each_combined_abstract

Description: Iterates over the combined device specifications.

This feature applies to combined devices. This iterator will deliver all device abstracts present in addition to the default device abstract.

each_reconnected_terminal_for

Signature: [const,iter] DeviceReconnectedTerminal each_reconnected_terminal_for (unsigned long terminal_id)

Description: Iterates over the reconnected terminal specifications for a given outer terminal.

This feature applies to combined devices. This iterator will deliver all device-to-abstract terminal reroutings.

expanded_name

Signature: [const] string expanded_name

Description: Gets the expanded name of the device.

The expanded name takes the name of the device. If the name is empty, the numeric ID will be used to build a name.

id

Signature: [const] unsigned long id

Description: Gets the device ID.

The ID is a unique integer which identifies the device. It can be used to retrieve the device from the circuit using Circuit#device_by_id. When assigned, the device ID is not 0.

is_combined_device?

Signature: [const] bool is_combined_device?

Description: Returns true, if the device is a combined device.

Combined devices feature multiple device abstracts and device-to-abstract terminal connections. See each_reconnected_terminal and each_combined_abstract for more details.

name

Signature: [const] string name

Description: Gets the name of the device.

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.

Device names are used to name a device inside a netlist file. Device names should be unique within a circuit.

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

net_for_terminal

(1) Signature: [const] const Net ptr net_for_terminal (unsigned long terminal_id)

Description: Gets the net connected to the specified terminal.

If the terminal is not connected, nil is returned for the net.

(2) Signature: Net ptr net_for_terminal (unsigned long terminal_id)

Description: Gets the net connected to the specified terminal (non-const version).

If the terminal is not connected, nil is returned for the net.

This constness variant has been introduced in version 0.26.8

(3) Signature: [const] const Net ptr net_for_terminal (string terminal_name)

Description: Gets the net connected to the specified terminal.

If the terminal is not connected, nil is returned for the net.

This convenience method has been introduced in version 0.27.3.

(4) Signature: const Net ptr net_for_terminal (string terminal_name)

Description: Gets the net connected to the specified terminal (non-const version).

If the terminal is not connected, nil is returned for the net.

This convenience method has been introduced in version 0.27.3.

parameter

(1) Signature: [const] double parameter (unsigned long param_id)

Description: Gets the parameter value for the given parameter ID.

(2) Signature: [const] double parameter (string param_name)

Description: Gets the parameter value for the given parameter name.

If the parameter name is not valid, an exception is thrown.

set_parameter

(1) Signature: void set_parameter (unsigned long param_id, double value)

Description: Sets the parameter value for the given parameter ID.

(2) Signature: void set_parameter (string param_name, double value)

Description: Sets the parameter value for the given parameter name.

If the parameter name is not valid, an exception is thrown.

trans

Signature: [const] DCplxTrans trans

Description: Gets the location of the device.

See trans= for details about this method.

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

trans=

Signature: void trans= (const DCplxTrans t)

Description: Sets the location of the device.

The device location is essentially describing the position of the device. The position is typically the center of some recognition shape. In this case the transformation is a plain displacement to the center of this shape.

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