API reference - Class TilingProcessor

_const_cast

Signature: [const] TilingProcessor ptr _const_cast

Description: Returns a non-const reference to self.

Basically, this method allows turning a const object reference to a non-const one. This method is provided as last resort to remove the constness from an object. Usually there is a good reason for a const object reference, so using this method may have undesired side effects.

This method has been introduced in version 0.29.6.

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

assign

Signature: void assign (const TilingProcessor other)

Description: Assigns another object to self

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.

dup

Signature: [const] new TilingProcessor ptr dup

Description: Creates a copy of self

Python specific notes:
This method also implements '__copy__' and '__deepcopy__'.

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.

Caution: the Region object must stay valid during the lifetime of the tiling processor. Take care to store it in a variable to prevent early destruction of the Region object. Not doing so may crash the application.

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.

Caution: the Region object must stay valid during the lifetime of the tiling processor. Take care to store it in a variable to prevent early destruction of the Region object. Not doing so may crash the application.

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.

Caution: the Edges object must stay valid during the lifetime of the tiling processor. Take care to store it in a variable to prevent early destruction of the Edges object. Not doing so may crash the application.

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.

Caution: the Edges object must stay valid during the lifetime of the tiling processor. Take care to store it in a variable to prevent early destruction of the Edges object. Not doing so may crash the application.

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.

Caution: the EdgePairs object must stay valid during the lifetime of the tiling processor. Take care to store it in a variable to prevent early destruction of the EdgePairs object. Not doing so may crash the application.

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.

Caution: the EdgePairs object must stay valid during the lifetime of the tiling processor. Take care to store it in a variable to prevent early destruction of the EdgePairs object. Not doing so may crash the application.

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.

Caution: the Texts object must stay valid during the lifetime of the tiling processor. Take care to store it in a variable to prevent early destruction of the Texts object. Not doing so may crash the application.

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.

Caution: the Texts object must stay valid during the lifetime of the tiling processor. Take care to store it in a variable to prevent early destruction of the Texts object. Not doing so may crash the application.

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

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

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

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

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

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

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.