API reference - Class TilingProcessor

Notation used in Ruby API documentation

Module: db

Description: A processor for layout which distributes tasks over tiles

The tiling processor executes one or several scripts on one or multiple layouts providing a tiling scheme. In that scheme, the processor divides the original layout into rectangular tiles and executes the scripts on each tile separately. The tiling processor allows one to specify multiple, independent scripts which are run separately on each tile. It can make use of multi-core CPU's by supporting multiple threads running the tasks in parallel (with respect to tiles and scripts).

Tiling a optional - if no tiles are specified, the tiling processing basically operates flat and parallelization extends to the scripts only.

Tiles can be overlapping to gather input from neighboring tiles into the current tile. In order to provide that feature, a border can be specified which gives the amount by which the search region is extended beyond the border of the tile. To specify the border, use the TilingProcessor#tile_border method.

The basis of the tiling processor are Region objects and expressions. Expressions are a built-in simple language to form simple scripts. Expressions allow access to the objects and methods built into KLayout. Each script can consist of multiple operations. Scripts are specified using TilingProcessor#queue.

Input is provided to the script through variables holding a Region object each. From outside the tiling processor, input is specified with the TilingProcessor#input method. This method is given a name and a RecursiveShapeIterator object which delivers the data for the input. On the script side, a Region object is provided through a variable named like the first argument of the "input" method.

Inside the script the following functions are provided:

Output can be obtained from the tiling processor by registering a receiver with a channel. A channel is basically a name. Inside the script, the name describes a variable which can be used as the first argument of the "_output" function to identify the channel. A channel is registers using the TilingProcessor#output method. Beside the name, a receiver must be specified. A receiver is either another layout (a cell of that), a report database or a custom receiver implemented through the TileOutputReceiver class.

The "_output" function expects two or three parameters: one channel id (the variable that was defined by the name given in the output method call) and an object to output (a Region, Edges, EdgePairs or a geometrical primitive such as Polygon or Box). In addition, a boolean argument can be given indicating whether clipping at the tile shall be applied. If clipping is requested (the default), the shapes will be clipped at the tile's box.

The tiling can be specified either through a tile size, a tile number or both. If a tile size is specified with the TilingProcessor#tile_size method, the tiling processor will compute the number of tiles required. If the tile count is given (through TilingProcessor#tiles), the tile size will be computed. If both are given, the tiling array is fixed and the array is centered around the original layout's center. If the tiling origin is given as well, the tiling processor will use the given array without any modifications.

Once the tiling processor has been set up, the operation can be launched using TilingProcessor#execute.

This is some sample code. It performs two XOR operations between two layouts and delivers the results to a report database:

ly1 = ... # first layout
ly2 = ... # second layout

rdb = RBA::ReportDatabase::new("xor")
output_cell = rdb.create_cell(ly1.top_cell.name)
output_cat1 = rbd.create_category("XOR 1-10")
output_cat2 = rbd.create_category("XOR 2-11")

tp = RBA::TilingProcessor::new
tp.input("a1", ly1, ly1.top_cell.cell_index, RBA::LayerInfo::new(1, 0))
tp.input("a2", ly1, ly1.top_cell.cell_index, RBA::LayerInfo::new(2, 0))
tp.input("b1", ly2, ly2.top_cell.cell_index, RBA::LayerInfo::new(11, 0))
tp.input("b2", ly2, ly2.top_cell.cell_index, RBA::LayerInfo::new(12, 0))
tp.output("o1", rdb, output_cell, output_cat1)
tp.output("o2", rdb, output_cell, output_cat2)
tp.queue("_output(o1, a1 ^ b1)")
tp.queue("_output(o2, a2 ^ b2)")
tp.tile_size(50.0, 50.0)
tp.execute("Job description")

This class has been introduced in version 0.23.

Public constructors

new TilingProcessor 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.
[const]doubledbuGets the database unit under which the computations will be done
voiddbu=(double u)Sets the database unit under which the computations will be done
voidexecute(string desc)Runs the job
voidframe=(const DBox frame)Sets the layout frame
voidinput(string name,
const RecursiveShapeIterator iter)
Specifies input for the tiling processor
voidinput(string name,
const RecursiveShapeIterator iter,
const ICplxTrans trans)
Specifies input for the tiling processor
voidinput(string name,
const Layout layout,
unsigned int cell_index,
const LayerInfo lp)
Specifies input for the tiling processor
voidinput(string name,
const Layout layout,
unsigned int cell_index,
unsigned int layer)
Specifies input for the tiling processor
voidinput(string name,
const Layout layout,
unsigned int cell_index,
const LayerInfo lp,
const ICplxTrans trans)
Specifies input for the tiling processor
voidinput(string name,
const Layout layout,
unsigned int cell_index,
unsigned int layer,
const ICplxTrans trans)
Specifies input for the tiling processor
voidinput(string name,
const Region region)
Specifies input for the tiling processor
voidinput(string name,
const Region region,
const ICplxTrans trans)
Specifies input for the tiling processor
voidinput(string name,
const Edges edges)
Specifies input for the tiling processor
voidinput(string name,
const Edges edges,
const ICplxTrans trans)
Specifies input for the tiling processor
voidinput(string name,
const EdgePairs edge_pairs)
Specifies input for the tiling processor
voidinput(string name,
const EdgePairs edge_pairs,
const ICplxTrans trans)
Specifies input for the tiling processor
voidinput(string name,
const Texts texts)
Specifies input for the tiling processor
voidinput(string name,
const Texts texts,
const ICplxTrans trans)
Specifies input for the tiling processor
voidoutput(string name,
TileOutputReceiver ptr rec)
Specifies output for the tiling processor
voidoutput(string name,
Layout layout,
unsigned int cell,
const LayerInfo lp)
Specifies output to a layout layer
voidoutput(string name,
Layout layout,
unsigned int cell,
unsigned int layer_index)
Specifies output to a layout layer
voidoutput(string name,
Region region)
Specifies output to a Region object
voidoutput(string name,
Edges edges)
Specifies output to an Edges object
voidoutput(string name,
EdgePairs edge_pairs)
Specifies output to an EdgePairs object
voidoutput(string name,
Texts texts)
Specifies output to an Texts object
voidoutput(string name,
double ptr sum)
Specifies output to single value
voidoutput(string name,
ReportDatabase rdb,
unsigned long cell_id,
unsigned long category_id)
Specifies output to a report database
voidoutput(string name,
Image ptr image)
Specifies output to an image
voidqueue(string script)Queues a script for parallel execution
voidscale_to_dbu=(bool en)Enables or disabled automatic scaling to database unit
[const]boolscale_to_dbu?Gets a valid indicating whether automatic scaling to database unit is enabled
[const]unsigned longthreadsGets the number of threads to use
voidthreads=(unsigned long n)Specifies the number of threads to use
voidtile_border(double bx,
double by)
Sets the tile border
voidtile_origin(double xo,
double yo)
Sets the tile origin
voidtile_size(double w,
double h)
Sets the tile size
voidtiles(unsigned long nw,
unsigned long nh)
Sets the tile count
voidvar(string name,
variant value)
Defines a variable for the tiling processor script

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.

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.

dbu

Signature: [const] double dbu

Description: Gets the database unit under which the computations will be done

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

dbu=

Signature: void dbu= (double u)

Description: Sets the database unit under which the computations will be done

All data used within the scripts will be brought to that database unit. If none is given it will be the database unit of the first layout given or 1nm if no layout is specified.

Python specific notes:
The object exposes a writable attribute 'dbu'. 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.

execute

Signature: void execute (string desc)

Description: Runs the job

This method will initiate execution of the queued scripts, once for every tile. The desc is a text shown in the progress bar for example.

frame=

Signature: void frame= (const DBox frame)

Description: Sets the layout frame

The layout frame is the box (in micron units) taken into account for computing the tiles if the tile counts are not given. If the layout frame is not set or set to an empty box, the processor will try to derive the frame from the given inputs.

This method has been introduced in version 0.25.

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

input

(1) Signature: void input (string name, const RecursiveShapeIterator iter)

Description: Specifies input for the tiling processor

This method will establish an input channel for the processor. This version receives input from a recursive shape iterator, hence from a hierarchy of shapes from a layout.

The name specifies the variable under which the input can be used in the scripts.

(2) Signature: void input (string name, const RecursiveShapeIterator iter, const ICplxTrans trans)

Description: Specifies input for the tiling processor

This method will establish an input channel for the processor. This version receives input from a recursive shape iterator, hence from a hierarchy of shapes from a layout. In addition, a transformation can be specified which will be applied to the shapes before they are used.

The name specifies the variable under which the input can be used in the scripts.

(3) Signature: void input (string name, const Layout layout, unsigned int cell_index, const LayerInfo lp)

Description: Specifies input for the tiling processor

This method will establish an input channel for the processor. This version receives input from a layout and the hierarchy below the cell with the given cell index. "lp" is a LayerInfo object specifying the input layer.

The name specifies the variable under which the input can be used in the scripts.

(4) Signature: void input (string name, const Layout layout, unsigned int cell_index, unsigned int layer)

Description: Specifies input for the tiling processor

This method will establish an input channel for the processor. This version receives input from a layout and the hierarchy below the cell with the given cell index. "layer" is the layer index of the input layer.

The name specifies the variable under which the input can be used in the scripts.

(5) Signature: void input (string name, const Layout layout, unsigned int cell_index, const LayerInfo lp, const ICplxTrans trans)

Description: Specifies input for the tiling processor

This method will establish an input channel for the processor. This version receives input from a layout and the hierarchy below the cell with the given cell index. "lp" is a LayerInfo object specifying the input layer. In addition, a transformation can be specified which will be applied to the shapes before they are used.

The name specifies the variable under which the input can be used in the scripts.

(6) Signature: void input (string name, const Layout layout, unsigned int cell_index, unsigned int layer, const ICplxTrans trans)

Description: Specifies input for the tiling processor

This method will establish an input channel for the processor. This version receives input from a layout and the hierarchy below the cell with the given cell index. "layer" is the layer index of the input layer. In addition, a transformation can be specified which will be applied to the shapes before they are used.

The name specifies the variable under which the input can be used in the scripts.

(7) Signature: void input (string name, const Region region)

Description: Specifies input for the tiling processor

This method will establish an input channel for the processor. This version receives input from a Region object. Regions don't always come with a database unit, hence a database unit should be specified with the dbu= method unless a layout object is specified as input too.

The name specifies the variable under which the input can be used in the scripts.

(8) Signature: void input (string name, const Region region, const ICplxTrans trans)

Description: Specifies input for the tiling processor

This method will establish an input channel for the processor. This version receives input from a Region object. Regions don't always come with a database unit, hence a database unit should be specified with the dbu= method unless a layout object is specified as input too.

The name specifies the variable under which the input can be used in the scripts. This variant allows one to specify an additional transformation too. It has been introduced in version 0.23.2.

(9) Signature: void input (string name, const Edges edges)

Description: Specifies input for the tiling processor

This method will establish an input channel for the processor. This version receives input from an Edges object. Edge collections don't always come with a database unit, hence a database unit should be specified with the dbu= method unless a layout object is specified as input too.

The name specifies the variable under which the input can be used in the scripts.

(10) Signature: void input (string name, const Edges edges, const ICplxTrans trans)

Description: Specifies input for the tiling processor

This method will establish an input channel for the processor. This version receives input from an Edges object. Edge collections don't always come with a database unit, hence a database unit should be specified with the dbu= method unless a layout object is specified as input too.

The name specifies the variable under which the input can be used in the scripts. This variant allows one to specify an additional transformation too. It has been introduced in version 0.23.2.

(11) Signature: void input (string name, const EdgePairs edge_pairs)

Description: Specifies input for the tiling processor

This method will establish an input channel for the processor. This version receives input from an EdgePairs object. Edge pair collections don't always come with a database unit, hence a database unit should be specified with the dbu= method unless a layout object is specified as input too.

The name specifies the variable under which the input can be used in the scripts. This variant has been introduced in version 0.27.

(12) Signature: void input (string name, const EdgePairs edge_pairs, const ICplxTrans trans)

Description: Specifies input for the tiling processor

This method will establish an input channel for the processor. This version receives input from an EdgePairs object. Edge pair collections don't always come with a database unit, hence a database unit should be specified with the dbu= method unless a layout object is specified as input too.

The name specifies the variable under which the input can be used in the scripts. This variant has been introduced in version 0.27.

(13) Signature: void input (string name, const Texts texts)

Description: Specifies input for the tiling processor

This method will establish an input channel for the processor. This version receives input from an Texts object. Text collections don't always come with a database unit, hence a database unit should be specified with the dbu= method unless a layout object is specified as input too.

The name specifies the variable under which the input can be used in the scripts. This variant has been introduced in version 0.27.

(14) Signature: void input (string name, const Texts texts, const ICplxTrans trans)

Description: Specifies input for the tiling processor

This method will establish an input channel for the processor. This version receives input from an Texts object. Text collections don't always come with a database unit, hence a database unit should be specified with the dbu= method unless a layout object is specified as input too.

The name specifies the variable under which the input can be used in the scripts. This variant has been introduced in version 0.27.

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.

new

Signature: [static] new TilingProcessor ptr new

Description: Creates a new object of this class

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

output

(1) Signature: void output (string name, TileOutputReceiver ptr rec)

Description: Specifies output for the tiling processor

This method will establish an output channel for the processor. For that it registers an output receiver which will receive data from the scripts. The scripts call the _output function to deliver data. "name" will be name of the variable which must be passed to the first argument of the _output function in order to address this channel.

Please note that the tiling processor will destroy the receiver object when it is freed itself. Hence if you need to address the receiver object later, make sure that the processor is still alive, i.e. by assigning the object to a variable.

The following code uses the output receiver. It takes the shapes of a layer from a layout, computes the area of each tile and outputs the area to the custom receiver:

layout = ... # the layout
cell = ... # the top cell's index
layout = ... # the input layer

class MyReceiver < RBA::TileOutputReceiver
  def put(ix, iy, tile, obj, dbu, clip)
    puts "got area for tile #{ix+1},#{iy+1}: #{obj.to_s}"
  end
end

tp = RBA::TilingProcessor::new

# register the custom receiver
tp.output("my_receiver", MyReceiver::new)
tp.input("the_input", layout.begin_shapes(cell, layer))
tp.tile_size(100, 100)  # 100x100 um tile size
# The script clips the input at the tile and computes the (merged) area:
tp.queue("_output(my_receiver, (the_input & _tile).area)")
tp.execute("Job description")

(2) Signature: void output (string name, Layout layout, unsigned int cell, const LayerInfo lp)

Description: Specifies output to a layout layer

name:The name of the channel
layout:The layout to which the data is sent
cell:The index of the cell to which the data is sent
lp:The layer specification where the output will be sent to

This method will establish an output channel to a layer in a layout. The output sent to that channel will be put into the specified layer and cell. In this version, the layer is specified through a LayerInfo object, i.e. layer and datatype number. If no such layer exists, it will be created.

The name is the name which must be used in the _output function of the scripts in order to address that channel.

(3) Signature: void output (string name, Layout layout, unsigned int cell, unsigned int layer_index)

Description: Specifies output to a layout layer

name:The name of the channel
layout:The layout to which the data is sent
cell:The index of the cell to which the data is sent
layer_index:The layer index where the output will be sent to

This method will establish an output channel to a layer in a layout. The output sent to that channel will be put into the specified layer and cell. In this version, the layer is specified through a layer index, hence it must be created before.

The name is the name which must be used in the _output function of the scripts in order to address that channel.

(4) Signature: void output (string name, Region region)

Description: Specifies output to a Region object

name:The name of the channel
region:The Region object to which the data is sent

This method will establish an output channel to a Region object. The output sent to that channel will be put into the specified region.

The name is the name which must be used in the _output function of the scripts in order to address that channel. Edges sent to this channel are discarded. Edge pairs are converted to polygons.

(5) Signature: void output (string name, Edges edges)

Description: Specifies output to an Edges object

name:The name of the channel
edges:The Edges object to which the data is sent

This method will establish an output channel to an Edges object. The output sent to that channel will be put into the specified edge collection. 'Solid' objects such as polygons will be converted to edges by resolving their hulls into edges. Edge pairs are resolved into single edges.

The name is the name which must be used in the _output function of the scripts in order to address that channel.

(6) Signature: void output (string name, EdgePairs edge_pairs)

Description: Specifies output to an EdgePairs object

name:The name of the channel
edge_pairs:The EdgePairs object to which the data is sent

This method will establish an output channel to an EdgePairs object. The output sent to that channel will be put into the specified edge pair collection. Only EdgePair objects are accepted. Other objects are discarded.

The name is the name which must be used in the _output function of the scripts in order to address that channel.

(7) Signature: void output (string name, Texts texts)

Description: Specifies output to an Texts object

name:The name of the channel
texts:The Texts object to which the data is sent

This method will establish an output channel to an Texts object. The output sent to that channel will be put into the specified edge pair collection. Only Text objects are accepted. Other objects are discarded.

The name is the name which must be used in the _output function of the scripts in order to address that channel.

This variant has been introduced in version 0.27.

(8) Signature: void output (string name, double ptr sum)

Description: Specifies output to single value

This method will establish an output channel which sums up float data delivered by calling the _output function. In order to specify the target for the data, a Value object must be provided for the "sum" parameter.

The name is the name which must be used in the _output function of the scripts in order to address that channel.

(9) Signature: void output (string name, ReportDatabase rdb, unsigned long cell_id, unsigned long category_id)

Description: Specifies output to a report database

This method will establish an output channel for the processor. The output sent to that channel will be put into the report database given by the "rdb" parameter. "cell_id" specifies the cell and "category_id" the category to use.

The name is the name which must be used in the _output function of the scripts in order to address that channel.

(10) Signature: void output (string name, Image ptr image)

Description: Specifies output to an image

This method will establish an output channel which delivers float data to image data. The image is a monochrome image where each pixel corresponds to a single tile. This method for example is useful to collect density information into an image. The image is configured such that each pixel covers one tile.

The name is the name which must be used in the _output function of the scripts in order to address that channel.

queue

Signature: void queue (string script)

Description: Queues a script for parallel execution

With this method, scripts are registered that are executed in parallel on each tile. The scripts have "Expressions" syntax and can make use of several predefined variables and functions. See the TilingProcessor class description for details.

scale_to_dbu=

Signature: void scale_to_dbu= (bool en)

Description: Enables or disabled automatic scaling to database unit

If automatic scaling to database unit is enabled, the input is automatically scaled to the database unit set inside the tile processor. This is the default.

This method has been introduced in version 0.23.2.

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

scale_to_dbu?

Signature: [const] bool scale_to_dbu?

Description: Gets a valid indicating whether automatic scaling to database unit is enabled

This method has been introduced in version 0.23.2.

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

threads

Signature: [const] unsigned long threads

Description: Gets the number of threads to use

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

threads=

Signature: void threads= (unsigned long n)

Description: Specifies the number of threads to use

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

tile_border

Signature: void tile_border (double bx, double by)

Description: Sets the tile border

Specifies the tile border. The border is a margin that is considered when fetching shapes. By specifying a border you can fetch shapes into the tile's data which are outside the tile but still must be considered in the computations (i.e. because they might grow into the tile).

The tile border is given in micron.

tile_origin

Signature: void tile_origin (double xo, double yo)

Description: Sets the tile origin

Specifies the origin (lower left corner) of the tile field. If no origin is specified, the tiles are centered to the layout's bounding box. Giving the origin together with the tile count and dimensions gives full control over the tile array.

The tile origin is given in micron.

tile_size

Signature: void tile_size (double w, double h)

Description: Sets the tile size

Specifies the size of the tiles to be used. If no tile size is specified, tiling won't be used and all computations will be done on the whole layout.

The tile size is given in micron.

tiles

Signature: void tiles (unsigned long nw, unsigned long nh)

Description: Sets the tile count

Specifies the number of tiles to be used. If no tile number is specified, the number of tiles required is computed from the layout's dimensions and the tile size. If a number is given, but no tile size, the tile size will be computed from the layout's dimensions.

var

Signature: void var (string name, variant value)

Description: Defines a variable for the tiling processor script

The name specifies the variable under which the value can be used in the scripts.