API reference - Class LayoutToNetlist

BNH_Disconnected

Signature: [static,const] BuildNetHierarchyMode BNH_Disconnected

Description: This constant tells build_net and build_all_nets to produce local nets without connections to subcircuits (used for the "hier_mode" parameter).

BNH_Flatten

Signature: [static,const] BuildNetHierarchyMode BNH_Flatten

Description: This constant tells build_net and build_all_nets to flatten the nets (used for the "hier_mode" parameter).

BNH_SubcircuitCells

Signature: [static,const] BuildNetHierarchyMode BNH_SubcircuitCells

Description: This constant tells build_net and build_all_nets to produce a hierarchy of subcircuit cells per net (used for the "hier_mode" parameter).

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

antenna_check

Signature: Region antenna_check (const Region gate, const Region metal, double ratio, variant[] diodes = [])

Description: Runs an antenna check on the extracted clusters

The antenna check will traverse all clusters and run an antenna check for all root clusters. The antenna ratio is defined by the total area of all "metal" shapes divided by the total area of all "gate" shapes on the cluster. Of all clusters where the antenna ratio is larger than the limit ratio all metal shapes are copied to the output region as error markers.

The simple call is:

l2n = ... # a LayoutToNetlist object
l2n.extract_netlist
# check for antenna ratio 10.0 of metal vs. poly:
errors = l2n.antenna(poly, metal, 10.0)

You can include diodes which rectify the antenna effect. Provide recognition layers for theses diodes and include them in the connections. Then specify the diode layers in the antenna call:

...
# include diode_layer1:
errors = l2n.antenna(poly, metal, 10.0, [ diode_layer1 ])
# include diode_layer1 and diode_layer2:errors = l2n.antenna(poly, metal, 10.0, [ diode_layer1, diode_layer2 ])

Diodes can be configured to partially reduce the antenna effect depending on their area. This will make the diode_layer1 increase the ratio by 50.0 per square micrometer area of the diode:

...
# diode_layer1 increases the ratio by 50 per sqaure micrometer area:
errors = l2n.antenna(poly, metal, 10.0 [ [ diode_layer, 50.0 ] ])

Signature: Region antenna_check (const Region gate, double gate_perimeter_factor, const Region metal, double metal_perimeter_factor, double ratio, variant[] diodes = [])

Description: Runs an antenna check on the extracted clusters taking the perimeter into account

This version of the antenna_check method allows taking the perimeter of gate or metal into account. The effective area is computed using:

Aeff = A + P * t

Here Aeff is the area used in the check, A is the polygon area, P the perimeter and t the perimeter factor. This formula applies to gate polygon area/perimeter with 'gate_perimeter_factor' for t and metal polygon area/perimeter with 'metal_perimeter_factor'. The perimeter_factor has the dimension of micrometers and can be thought of as the width of the material. Essentially the side walls of the material are taking into account for the surface area as well.

This variant has been introduced in version 0.26.6.

Signature: Region antenna_check (const Region gate, double gate_area_factor, double gate_perimeter_factor, const Region metal, double metal_area_factor, double metal_perimeter_factor, double ratio, variant[] diodes = [])

Description: Runs an antenna check on the extracted clusters taking the perimeter into account and providing an area factor

This (most generic) version of the antenna_check method allows taking the perimeter of gate or metal into account and also provides a scaling factor for the area part. The effective area is computed using:

Aeff = A * f + P * t

Here f is the area factor and t the perimeter factor. A is the polygon area and P the polygon perimeter. A use case for this variant is to set the area factor to zero. This way, only perimeter contributions are considered.

This variant has been introduced in version 0.26.6.

area_ratio

Signature: [const] double area_ratio

Description: Gets the area_ratio parameter for the hierarchical network processor

See area_ratio= for details about this attribute.

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

area_ratio=

Signature: void area_ratio= (double r)

Description: Sets the area_ratio parameter for the hierarchical network processor

This parameter controls splitting of large polygons in order to reduce the error made by the bounding box approximation.

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

build_all_nets

Signature: [const] void build_all_nets (const CellMapping cmap, Layout target, map<unsigned int,const Region ptr> lmap, variant net_cell_name_prefix = nil, variant netname_prop = nil, BuildNetHierarchyMode hier_mode = BNH_Flatten, variant circuit_cell_name_prefix = nil, variant device_cell_name_prefix = nil)

Description: Builds a full hierarchical representation of the nets

This method copies all nets into cells corresponding to the circuits. It uses the 'cmap' object to determine the target cell (create it with "cell_mapping_into" or "const_cell_mapping_into"). If no mapping is provided for a specific circuit cell, the nets are copied into the next mapped parent as many times as the circuit cell appears there (circuit flattening).

The method has three net annotation modes:

• No annotation (net_cell_name_prefix == nil and netname_prop == nil): the shapes will be put into the target cell simply.
• Net name property (net_cell_name_prefix == nil and netname_prop != nil): the shapes will be annotated with a property named with netname_prop and containing the net name string.
• Individual subcells per net (net_cell_name_prefix != 0): for each net, a subcell is created and the net shapes will be put there (name of the subcell = net_cell_name_prefix + net name). (this mode can be combined with netname_prop too).

In addition, net hierarchy is covered in three ways:

• No connection indicated (hier_mode == BNH_Disconnected: the net shapes are simply put into their respective circuits. The connections are not indicated.
• Subnet hierarchy (hier_mode == BNH_SubcircuitCells): for each root net, a full hierarchy is built to accommodate the subnets (see build_net in recursive mode).
• Flat (hier_mode == BNH_Flatten): each net is flattened and put into the circuit it belongs to.

If a device cell name prefix is given, cells will be produced for each device abstract using a name like device_cell_name_prefix + device name. Otherwise the device shapes are treated as part of the net.

build_net

Signature: [const] void build_net (const Net net, Layout target, Cell target_cell, map<unsigned int,const Region ptr> lmap, variant netname_prop = nil, BuildNetHierarchyMode hier_mode = BNH_Flatten, variant circuit_cell_name_prefix = nil, variant device_cell_name_prefix = nil)

Description: Builds a net representation in the given layout and cell

This method puts the shapes of a net into the given target cell using a variety of options to represent the net name and the hierarchy of the net.

If the netname_prop name is not nil, a property with the given name is created and assigned the net name.

Net hierarchy is covered in three ways:

• No connection indicated (hier_mode == BNH_Disconnected: the net shapes are simply put into their respective circuits. The connections are not indicated.
• Subnet hierarchy (hier_mode == BNH_SubcircuitCells): for each root net, a full hierarchy is built to accommodate the subnets (see build_net in recursive mode).
• Flat (hier_mode == BNH_Flatten): each net is flattened and put into the circuit it belongs to.

build_nets

Signature: [const] void build_nets (const Net ptr[] nets, const CellMapping cmap, Layout target, map<unsigned int,const Region ptr> lmap, variant net_cell_name_prefix = nil, variant netname_prop = nil, BuildNetHierarchyMode hier_mode = BNH_Flatten, variant circuit_cell_name_prefix = nil, variant device_cell_name_prefix = nil)

Description: Like build_all_nets, but with the ability to select some nets.

cell_mapping_into

Signature: CellMapping cell_mapping_into (Layout layout, Cell cell, bool with_device_cells = false)

Description: Creates a cell mapping for copying shapes from the internal layout to the given target layout.

If 'with_device_cells' is true, cells will be produced for devices. These are cells not corresponding to circuits, so they are disabled normally. Use this option, if you want to access device terminal shapes per device.

CAUTION: this function may create new cells in 'layout'. Use const_cell_mapping_into if you want to use the target layout's hierarchy and not modify it.

Signature: CellMapping cell_mapping_into (Layout layout, Cell cell, const Net ptr[] nets, bool with_device_cells = false)

Description: Creates a cell mapping for copying shapes from the internal layout to the given target layout.

This version will only create cells which are required to represent the nets from the 'nets' argument.

If 'with_device_cells' is true, cells will be produced for devices. These are cells not corresponding to circuits, so they are disabled normally. Use this option, if you want to access device terminal shapes per device.

CAUTION: this function may create new cells in 'layout'. Use const_cell_mapping_into if you want to use the target layout's hierarchy and not modify it.

connect

Signature: void connect (const Region l)

Description: Defines an intra-layer connection for the given layer.

The layer is either an original layer created with make_layer and it's variants or a derived layer. Certain limitations apply. It's safe to use boolean operations for deriving layers. Other operations are applicable as long as they are capable of delivering hierarchical layers.

Signature: void connect (const Region a, const Region b)

Description: Defines an inter-layer connection for the given layers.

The conditions mentioned with intra-layer connect apply for this method too.

connect_global

Signature: void connect_global (const Region l, string global_net_name)

Description: Defines a connection of the given layer with a global net.

This method returns the ID of the global net. Use global_net_name to get the name back from the ID.

const_cell_mapping_into

Signature: CellMapping const_cell_mapping_into (const Layout layout, const Cell cell)

Description: Creates a cell mapping for copying shapes from the internal layout to the given target layout.

This version will not create new cells in the target layout. If the required cells do not exist there yet, flatting will happen.

create

Signature: void create

Description: Ensures the C++ object is created

Use of this method is deprecated. Use _create instead

description

Signature: [const] string description

Description: Gets the description of the database

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

description=

Signature: void description= (string arg1)

Description: Sets the description of the database

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

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

device_scaling

Signature: [const] double device_scaling

Description: Gets the device scaling factor

See device_scaling= for details about this attribute.

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

device_scaling=

Signature: void device_scaling= (double f)

Description: Sets the device scaling factor

This factor will scale the physical properties of the extracted devices accordingly. The scale factor applies an isotropic shrink (<1) or expansion (>1).

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

dss

Signature: DeepShapeStore dss

Description: Gets a reference to the internal DSS object.

extract_devices

Signature: void extract_devices (DeviceExtractorBase extractor, map<string,Region ptr> layers)

Description: Extracts devices

See the class description for more details. This method will run device extraction for the given extractor. The layer map is specific for the extractor and uses the region objects derived with make_layer and it's variants.

In addition, derived regions can be passed too. Certain limitations apply. It's safe to use boolean operations for deriving layers. Other operations are applicable as long as they are capable of delivering hierarchical layers.

If errors occur, the device extractor will contain theses errors.

extract_netlist

Signature: void extract_netlist (string join_net_names = "", bool include_floating_subcircuits = false)

Description: Runs the netlist extraction

'join_net_names' is a glob expression for labels. Nets on top level carrying the same label which matches this glob expression will be connected implicitly even if there is no physical connection. This feature is useful to simulate a connection which will be made later when integrating the component.

Valid glob expressions are:

• "" no implicit connections.
• "*" to make all labels candidates for implicit connections.
• "VDD" to make all 'VDD'' nets candidates for implicit connections.
• "VDD" to make all 'VDD'+suffix nets candidates for implicit connections.
• "{VDD,VSS}" to all VDD and VSS nets candidates for implicit connections.

Label matching is case sensitive.

With 'include_floating_subcircuits' set to true, subcircuits with no connection to their parent circuit are still included in the circuit as floating subcircuits. Specifically on flattening this means that these subcircuits are property propagated to their parent instead of appearing as additional top circuits.

See the class description for more details.

The 'include_floating_subcircuits' argument has been introduced in version 0.26.2.

Signature: void extract_netlist (string join_net_names, map<string,string> join_net_names_per_cell, bool include_floating_subcircuits = false)

Description: Runs the netlist extraction

This method runs the netlist extraction like the two-parameter version. In addition to the latter, this method can be given a per-cell net label joining specification in 'join_net_names_per_cell'. The keys of this array are cell names or cell names or cell name match expressions (glob style). The values are label match expressions.

If not an empty string, the 'join_net_names' label match expression is applied to the top cell. For all non-top cells the per-cell label match expression is applied and determines what labels are joined into single nets. As the keys of 'join_net_names_per_cell' are glob expressions, a single cell may fall into more than one category. In this case, the label match pattern are combined. In any case, the 'join_net_names' has priority for the top cell.

This variant of 'extract_netlist' has been introduced in version 0.26.2.

filename

Signature: [const] string filename

Description: Gets the file name of the database

The filename is the name under which the database is stored or empty if it is not associated with a file.

generator

Signature: [const] string generator

Description: Gets the generator string.

The generator is the script that created this database.

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

generator=

Signature: void generator= (string generator)

Description: Sets the generator string.

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

global_net_name

Signature: [const] string global_net_name (unsigned long global_net_id)

Description: Gets the global net name for the given global net ID.

internal_layout

Signature: Layout ptr internal_layout

Description: Gets the internal layout

Usually it should not be required to obtain the internal layout. If you need to do so, make sure not to modify the layout as the functionality of the netlist extractor depends on it.

internal_top_cell

Signature: Cell ptr internal_top_cell

Description: Gets the internal top cell

Usually it should not be required to obtain the internal cell. If you need to do so, make sure not to modify the cell as the functionality of the netlist extractor depends on it.

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

is_persisted?

Signature: [const] bool is_persisted? (const Region layer)

Description: Returns true, if the given layer is a persisted region.

Persisted layers are kept inside the LayoutToNetlist object and are not released if their object is destroyed. Named layers are persisted, unnamed layers are not. Only persisted, named layers can be put into connect.

keep_dss

Signature: void keep_dss

Description: Resumes ownership over the DSS object if created with an external one.

layer_by_index

Signature: new Region ptr layer_by_index (unsigned int index)

Description: Gets a layer object for the given index.

Only named layers can be retrieved with this method. The returned object is a copy which represents the named layer.

layer_by_name

Signature: new Region ptr layer_by_name (string name)

Description: Gets a layer object for the given name.

The returned object is a copy which represents the named layer.

layer_name

Signature: [const] string layer_name (const Region l)

Description: Gets the name of the given layer

Signature: [const] string layer_name (unsigned int l)

Description: Gets the name of the given layer (by index)

layer_names

Signature: [const] string[] layer_names

Description: Returns a list of names of the layer kept inside the LayoutToNetlist object.

layer_of

Signature: [const] unsigned int layer_of (const Region l)

Description: Gets the internal layer for a given extraction layer

This method is required to derive the internal layer index - for example for investigating the cluster tree.

make_layer

Signature: new Region ptr make_layer (string name = )

Description: Creates a new, empty hierarchical region

The name is optional. If given, the layer will already be named accordingly (see register).

Signature: new Region ptr make_layer (unsigned int layer_index, string name = )

Description: Creates a new hierarchical region reprfesenting an original layer

'layer_index' is the layer index of the desired layer in the original layout. This variant produces polygons and takes texts for net name annotation. A variant not taking texts is make_polygon_layer. A Variant only taking texts is make_text_layer.

The name is optional. If given, the layer will already be named accordingly (see register).

make_polygon_layer

Signature: new Region ptr make_polygon_layer (unsigned int layer_index, string name = )

Description: Creates a new region representing an original layer taking polygons and texts

See make_layer for details.

The name is optional. If given, the layer will already be named accordingly (see register).

make_text_layer

Signature: new Region ptr make_text_layer (unsigned int layer_index, string name = )

Description: Creates a new region representing an original layer taking texts only

See make_layer for details.

The name is optional. If given, the layer will already be named accordingly (see register).

max_vertex_count

Signature: [const] unsigned long max_vertex_count

Description:

See max_vertex_count= for details about this attribute.

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

max_vertex_count=

Signature: void max_vertex_count= (unsigned long n)

Description: Sets the max_vertex_count parameter for the hierarchical network processor

This parameter controls splitting of large polygons in order to enhance performance for very big polygons.

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

name

Signature: [const] string name

Description: Gets the name of the database

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

name=

Signature: void name= (string arg1)

Description: Sets the name of the database

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

netlist

Signature: [const] Netlist ptr netlist

Description: gets the netlist extracted (0 if no extraction happened yet)

new

Signature: [static] new LayoutToNetlist ptr new (const RecursiveShapeIterator iter)

Description: Creates a new extractor connected to an original layout

This constructor will attach the extractor to an original layout through the shape iterator.

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

Signature: [static] new LayoutToNetlist ptr new

Description: Creates a new and empty extractor object

The main objective for this constructor is to create an object suitable for reading an annotated netlist.

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

Signature: [static] new LayoutToNetlist ptr new (DeepShapeStore ptr dss)

Description: Creates a new extractor object reusing an existing DeepShapeStore object

This constructor can be used if there is a DSS object already from which the shapes can be taken. This version can only be used with register to add layers (regions) inside the 'dss' object.

The make_... methods will not create new layers as there is no particular place defined where to create the layers.

The extractor will not take ownership of the dss object unless you call keep_dss.

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

Signature: [static] new LayoutToNetlist ptr new (DeepShapeStore ptr dss, unsigned int layout_index)

Description: Creates a new extractor object reusing an existing DeepShapeStore object

This constructor can be used if there is a DSS object already from which the shapes can be taken. NOTE: in this case, the make_... functions will create new layers inside this DSS. To register existing layers (regions) use register.

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

Signature: [static] new LayoutToNetlist ptr new (string topcell_name, double dbu)

Description: Creates a new extractor object with a flat DSS

This constructor will create an extractor for flat extraction. Layers registered with register will be flattened. New layers created with make_... will be flat layers.

The database unit is mandatory because the physical parameter extraction for devices requires this unit for translation of layout to physical dimensions.

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

original_file

Signature: [const] string original_file

Description: Gets the original file name of the database

The original filename is the layout file from which the netlist DB was created.

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

original_file=

Signature: void original_file= (string arg1)

Description: Sets the original file name of the database

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

probe_net

Signature: Net ptr probe_net (const Region of_layer, const DPoint point)

Description: Finds the net by probing a specific location on the given layer

This method will find a net looking at the given layer at the specific position. It will traverse the hierarchy below if no shape in the requested layer is found in the specified location. The function will report the topmost net from far above the hierarchy of circuits as possible.

If no net is found at all, 0 is returned.

It is recommended to use probe on the netlist right after extraction. Optimization functions such as Netlist#purge will remove parts of the net which means shape to net probing may no longer work for these nets.

This variant accepts a micrometer-unit location. The location is given in the coordinate space of the initial cell.

Signature: Net ptr probe_net (const Region of_layer, const Point point)

Description: Finds the net by probing a specific location on the given layer

See the description of the other probe_net variant. This variant accepts a database-unit location. The location is given in the coordinate space of the initial cell.

read

Signature: void read (string path)

Description: Reads the extracted netlist from the file.

This method employs the native format of KLayout.

read_l2n

Signature: void read_l2n (string path)

Description: Reads the extracted netlist from the file.

This method employs the native format of KLayout.

register

Signature: void register (const Region l, string n)

Description: Names the given layer

'l' must be a hierarchical region derived with make_layer, make_text_layer or make_polygon_layer or a region derived from those by boolean operations or other hierarchical operations.

Naming a layer allows the system to indicate the layer in various contexts, i.e. when writing the data to a file. Named layers are also persisted inside the LayoutToNetlist object. They are not discarded when the Region object is destroyed.

If required, the system will assign a name automatically.

shapes_of_net

Signature: [const] new Region ptr shapes_of_net (const Net net, const Region of_layer, bool recursive)

Description: Returns all shapes of a specific net and layer.

If 'recursive'' is true, the returned region will contain the shapes of all subcircuits too.

Signature: [const] void shapes_of_net (const Net net, const Region of_layer, bool recursive, Shapes to, unsigned long propid = 0)

Description: Sends all shapes of a specific net and layer to the given Shapes container.

If 'recursive'' is true, the returned region will contain the shapes of all subcircuits too. "prop_id" is an optional properties ID. If given, this property set will be attached to the shapes.

threads

Signature: [const] int threads

Description: Gets the number of threads to use for operations which support multiple threads

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

threads=

Signature: void threads= (int n)

Description: Sets the number of threads to use for operations which support multiple threads

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

write

Signature: void write (string path, bool short_format = false)

Description: Writes the extracted netlist to a file.

This method employs the native format of KLayout.

write_l2n

Signature: void write_l2n (string path, bool short_format = false)

Description: Writes the extracted netlist to a file.

This method employs the native format of KLayout.