API reference - Class Netlist

Notation used in Ruby API documentation

Module: db

Description: The netlist top-level class

A netlist is a hierarchical structure of circuits. At least one circuit is the top-level circuit, other circuits may be referenced as subcircuits. Circuits are created with create_circuit and are represented by objects of the Circuit class.

Beside circuits, the netlist manages device classes. Device classes describe specific types of devices. Device classes are represented by objects of the DeviceClass class and are created using create_device_class.

The netlist class has been introduced with version 0.26.

Public constructors

new Netlist 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(Circuit ptr circuit)Adds the circuit to the netlist
voidadd(DeviceClass ptr device_class)Adds the device class to the netlist
voidassign(const Netlist other)Assigns another object to self
voidblank_circuit(string pattern)Blanks circuits matching a certain pattern
voidcase_sensitive=(bool cs)Sets a value indicating whether the netlist names are case sensitive
Circuit ptrcircuit_by_cell_index(unsigned int cell_index)Gets the circuit object for a given cell index.
[const]const Circuit ptrcircuit_by_cell_index(unsigned int cell_index)Gets the circuit object for a given cell index (const version).
Circuit ptrcircuit_by_name(string name)Gets the circuit object for a given name.
[const]const Circuit ptrcircuit_by_name(string name)Gets the circuit object for a given name (const version).
Circuit ptr[]circuits_by_name(string name_pattern)Gets the circuit objects for a given name filter.
[const]const Circuit ptr[]circuits_by_name(string name_pattern)Gets the circuit objects for a given name filter (const version).
voidcombine_devicesCombines devices where possible
DeviceClass ptrdevice_class_by_name(string name)Gets the device class for a given name.
[const]const DeviceClass ptrdevice_class_by_name(string name)Gets the device class for a given name (const version).
[const]new Netlist ptrdupCreates a copy of self
[iter]Circuiteach_circuitIterates over the circuits of the netlist
[const,iter]Circuiteach_circuitIterates over the circuits of the netlist (const version)
[iter]Circuiteach_circuit_bottom_upIterates over the circuits bottom-up
[const,iter]Circuiteach_circuit_bottom_upIterates over the circuits bottom-up (const version)
[iter]Circuiteach_circuit_top_downIterates over the circuits top-down
[const,iter]Circuiteach_circuit_top_downIterates over the circuits top-down (const version)
[iter]DeviceClasseach_device_classIterates over the device classes of the netlist
[const,iter]DeviceClasseach_device_classIterates over the device classes of the netlist (const version)
voidflattenFlattens all circuits of the netlist
voidflatten_circuit(Circuit ptr circuit)Flattens a subcircuit
voidflatten_circuit(string pattern)Flattens circuits matching a certain pattern
voidflatten_circuits(Circuit ptr[] arg1)Flattens all given circuits of the netlist
voidfrom_s(string str)Reads the netlist from a string representation.
[const]boolis_case_sensitive?Returns a value indicating whether the netlist names are case sensitive
voidmake_top_level_pinsCreates pins for top-level circuits.
voidpurgePurge unused nets, circuits and subcircuits.
voidpurge_circuit(Circuit ptr circuit)Removes the given circuit object and all child circuits which are not used otherwise from the netlist
voidpurge_netsPurges floating nets.
voidread(string file,
NetlistReader ptr reader)
Writes the netlist to the given file using the given reader object to parse the file
voidremove(Circuit ptr circuit)Removes the given circuit object from the netlist
voidremove(DeviceClass ptr device_class)Removes the given device class object from the netlist
voidsimplifyConvenience method that combines the simplification.
[const]stringto_sConverts the netlist to a string representation.
[const]unsigned longtop_circuit_countGets the number of top circuits.
[const]voidwrite(string file,
NetlistWriter ptr writer,
string description = )
Writes the netlist to the given file using the given writer object to format the file

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

(1) Signature: void add (Circuit ptr circuit)

Description: Adds the circuit to the netlist

This method will add the given circuit object to the netlist. After the circuit has been added, it will be owned by the netlist.

(2) Signature: void add (DeviceClass ptr device_class)

Description: Adds the device class to the netlist

This method will add the given device class object to the netlist. After the device class has been added, it will be owned by the netlist.

assign

Signature: void assign (const Netlist other)

Description: Assigns another object to self

blank_circuit

Signature: void blank_circuit (string pattern)

Description: Blanks circuits matching a certain pattern

This method will erase everything from inside the circuits matching the given pattern. It will only leave pins which are not connected to any net. Hence, this method forms 'abstract' or black-box circuits which can be instantiated through subcircuits like the former ones, but are empty shells. The name pattern is a glob expression. For example, 'blank_circuit("np*")' will blank out all circuits with names starting with 'np'.

For more details see Circuit#blank which is the corresponding method on the actual object.

case_sensitive=

Signature: void case_sensitive= (bool cs)

Description: Sets a value indicating whether the netlist names are case sensitive

This method has been added in version 0.27.3.

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

circuit_by_cell_index

(1) Signature: Circuit ptr circuit_by_cell_index (unsigned int cell_index)

Description: Gets the circuit object for a given cell index.

If the cell index is not valid or no circuit is registered with this index, nil is returned.

(2) Signature: [const] const Circuit ptr circuit_by_cell_index (unsigned int cell_index)

Description: Gets the circuit object for a given cell index (const version).

If the cell index is not valid or no circuit is registered with this index, nil is returned.

This constness variant has been introduced in version 0.26.8

circuit_by_name

(1) Signature: Circuit ptr circuit_by_name (string name)

Description: Gets the circuit object for a given name.

If the name is not a valid circuit name, nil is returned.

(2) Signature: [const] const Circuit ptr circuit_by_name (string name)

Description: Gets the circuit object for a given name (const version).

If the name is not a valid circuit name, nil is returned.

This constness variant has been introduced in version 0.26.8

circuits_by_name

(1) Signature: Circuit ptr[] circuits_by_name (string name_pattern)

Description: Gets the circuit objects for a given name filter.

The name filter is a glob pattern. This method will return all Circuit objects matching the glob pattern.

This method has been introduced in version 0.26.4.

(2) Signature: [const] const Circuit ptr[] circuits_by_name (string name_pattern)

Description: Gets the circuit objects for a given name filter (const version).

The name filter is a glob pattern. This method will return all Circuit objects matching the glob pattern.

This constness variant has been introduced in version 0.26.8

combine_devices

Signature: void combine_devices

Description: Combines devices where possible

This method will combine devices that can be combined according to their device classes 'combine_devices' method. For example, serial or parallel resistors can be combined into a single resistor.

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.

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.

device_class_by_name

(1) Signature: DeviceClass ptr device_class_by_name (string name)

Description: Gets the device class for a given name.

If the name is not a valid device class name, nil is returned.

(2) Signature: [const] const DeviceClass ptr device_class_by_name (string name)

Description: Gets the device class for a given name (const version).

If the name is not a valid device class name, nil is returned.

This constness variant has been introduced in version 0.26.8

dup

Signature: [const] new Netlist ptr dup

Description: Creates a copy of self

Python specific notes:
This method also implements '__copy__'

each_circuit

(1) Signature: [iter] Circuit each_circuit

Description: Iterates over the circuits of the netlist

(2) Signature: [const,iter] Circuit each_circuit

Description: Iterates over the circuits of the netlist (const version)

This constness variant has been introduced in version 0.26.8

each_circuit_bottom_up

(1) Signature: [iter] Circuit each_circuit_bottom_up

Description: Iterates over the circuits bottom-up

Iterating bottom-up means the parent circuits come after the child circuits. This is the basically the reverse order as delivered by each_circuit_top_down.

(2) Signature: [const,iter] Circuit each_circuit_bottom_up

Description: Iterates over the circuits bottom-up (const version)

Iterating bottom-up means the parent circuits come after the child circuits. This is the basically the reverse order as delivered by each_circuit_top_down.

This constness variant has been introduced in version 0.26.8

each_circuit_top_down

(1) Signature: [iter] Circuit each_circuit_top_down

Description: Iterates over the circuits top-down

Iterating top-down means the parent circuits come before the child circuits. The first top_circuit_count circuits are top circuits - i.e. those which are not referenced by other circuits.

(2) Signature: [const,iter] Circuit each_circuit_top_down

Description: Iterates over the circuits top-down (const version)

Iterating top-down means the parent circuits come before the child circuits. The first top_circuit_count circuits are top circuits - i.e. those which are not referenced by other circuits.

This constness variant has been introduced in version 0.26.8

each_device_class

(1) Signature: [iter] DeviceClass each_device_class

Description: Iterates over the device classes of the netlist

(2) Signature: [const,iter] DeviceClass each_device_class

Description: Iterates over the device classes of the netlist (const version)

This constness variant has been introduced in version 0.26.8

flatten

Signature: void flatten

Description: Flattens all circuits of the netlist

After calling this method, only the top circuits will remain.

flatten_circuit

(1) Signature: void flatten_circuit (Circuit ptr circuit)

Description: Flattens a subcircuit

This method will substitute all instances (subcircuits) of the given circuit by it's contents. After this, the circuit is removed.

(2) Signature: void flatten_circuit (string pattern)

Description: Flattens circuits matching a certain pattern

This method will substitute all instances (subcircuits) of all circuits with names matching the given name pattern. The name pattern is a glob expression. For example, 'flatten_circuit("np*")' will flatten all circuits with names starting with 'np'.

flatten_circuits

Signature: void flatten_circuits (Circuit ptr[] arg1)

Description: Flattens all given circuits of the netlist

This method is equivalent to calling flatten_circuit for all given circuits, but more efficient.

This method has been introduced in version 0.26.1

from_s

Signature: void from_s (string str)

Description: Reads the netlist from a string representation.

This method is intended for test purposes mainly. It turns a string returned by to_s back into a netlist. Note that the device classes must be created before as they are not persisted inside the string.

is_case_sensitive?

Signature: [const] bool is_case_sensitive?

Description: Returns a value indicating whether the netlist names are case sensitive

This method has been added in version 0.27.3.

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.

make_top_level_pins

Signature: void make_top_level_pins

Description: Creates pins for top-level circuits.

This method will turn all named nets of top-level circuits (such that are not referenced by subcircuits) into pins. This method can be used before purge to avoid that purge will remove nets which are directly connecting to subcircuits.

new

Signature: [static] new Netlist ptr new

Description: Creates a new object of this class

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

purge

Signature: void purge

Description: Purge unused nets, circuits and subcircuits.

This method will purge all nets which return floating == true. Circuits which don't have any nets (or only floating ones) and removed. Their subcircuits are disconnected. This method respects the Circuit#dont_purge attribute and will never delete circuits with this flag set.

purge_circuit

Signature: void purge_circuit (Circuit ptr circuit)

Description: Removes the given circuit object and all child circuits which are not used otherwise from the netlist

After the circuit has been removed, the object becomes invalid and cannot be used further. A circuit with references (see has_refs?) should not be removed as the subcircuits calling it would afterwards point to nothing.

purge_nets

Signature: void purge_nets

Description: Purges floating nets.

Floating nets can be created as effect of reconnections of devices or pins. This method will eliminate all nets that make less than two connections.

read

Signature: void read (string file, NetlistReader ptr reader)

Description: Writes the netlist to the given file using the given reader object to parse the file

See NetlistSpiceReader for an example for a parser.

remove

(1) Signature: void remove (Circuit ptr circuit)

Description: Removes the given circuit object from the netlist

After the circuit has been removed, the object becomes invalid and cannot be used further. A circuit with references (see has_refs?) should not be removed as the subcircuits calling it would afterwards point to nothing.

(2) Signature: void remove (DeviceClass ptr device_class)

Description: Removes the given device class object from the netlist

After the object has been removed, it becomes invalid and cannot be used further. Use this method with care as it may corrupt the internal structure of the netlist. Only use this method when device refers to this device class.

simplify

Signature: void simplify

Description: Convenience method that combines the simplification.

This method is a convenience method that runs make_top_level_pins, purge, combine_devices and purge_nets.

to_s

Signature: [const] string to_s

Description: Converts the netlist to a string representation.

This method is intended for test purposes mainly.

Python specific notes:
This method is also available as 'str(object)'

top_circuit_count

Signature: [const] unsigned long top_circuit_count

Description: Gets the number of top circuits.

Top circuits are those which are not referenced by other circuits via subcircuits. A well-formed netlist has a single top circuit.

write

Signature: [const] void write (string file, NetlistWriter ptr writer, string description = )

Description: Writes the netlist to the given file using the given writer object to format the file

See NetlistSpiceWriter for an example for a formatter. The description is an arbitrary text which will be put into the file somewhere at the beginning.