API reference - Class TilingProcessorNotation used in Ruby API documentation 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 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("x1", rdb, output_cell, output_cat1)
tp.output("x2", rdb, output_cell, output_cat2)
tp.queue("_output(o1, a1 ^ b1)")
tp.queue("_output(o2, a2 ^ b2)")
tp.execute
This class has been introduced in version 0.23. Public constructors
Public methods
Detailed descriptionvoid createDescription: 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. [const] double dbuDescription: Gets the database unit under which the computations will be done 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. void destroyDescription: Explicitly destroy the object Explicitly destroy the object on C++ side if it was owned by the Ruby interpreter. Subsequent access to this object will throw an exception. If the object is not owned by Ruby, this method will do nothing. [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. 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. 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. 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. 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. 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. 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. 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. 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 if only regions and edges are used as input. The name specifies the variable under which the input can be used in the scripts. 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 if only regions and edges are used as input. The name specifies the variable under which the input can be used in the scripts. This variant allows to specify an additional transformation too. It has been introduced in version 0.23.2. 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 if only regions and edges are used as input. The name specifies the variable under which the input can be used in the scripts. 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 if only regions and edges are used as input. The name specifies the variable under which the input can be used in the scripts. This variant allows to specify an additional transformation too. It has been introduced in version 0.23.2. [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. [static] TilingProcessor newDescription: Creates a new object of this class 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
void output(string name,ReportDatabase rdb,unsigned int cell_id,unsigned int 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. void output(string name,Layout layout,unsigned int cell,const LayerInfo lp)Description: Specifies output to a layout layer
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. void output(string name,Layout layout,unsigned int cell,unsigned int layer_index)Description: Specifies output to a layout layer
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. void output(string name,Region region)Description: Specifies output to a Region object
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. void output(string name,Edges edges)Description: Specifies output to an Edges object
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. void output(string name,EdgePairs edge_pairs)Description: Specifies output to an EdgePairs object
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. 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. 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 densitity 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. 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. 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. [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. [const] unsigned int threadsDescription: Gets the number of threads to use void threads=(unsigned int n)Description: Specifies the number of threads to use 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. 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. 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. void tiles(unsigned int nw,unsigned int 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. 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. |