API reference - Class LayerMap

Notation used in Ruby API documentation

Module: db

Description: An object representing an arbitrary mapping of physical layers to logical layers

"Physical" layers are stream layers or other separated layers in a CAD file. "Logical" layers are the layers present in a Layout object. Logical layers are represented by an integer index while physical layers are given by a layer and datatype number or name. A logical layer is created automatically in the layout on reading if it does not exist yet.

The mapping describes an association of a set of physical layers to a set of logical ones, where multiple physical layers can be mapped to a single logical one, which effectively merges the layers.

For each logical layer, a target layer can be specified. A target layer is the layer/datatype/name combination as which the logical layer appears in the layout. By using a target layer different from the source layer renaming a layer can be achieved while loading a layout. Another use case for that feature is to assign layer names to GDS layer/datatype combinations which are numerical only.

LayerMap objects are used in two ways: as input for the reader (inside a LoadLayoutOptions class) and as output from the reader (i.e. Layout::read method). For layer map objects used as input, the layer indexes (logical layers) can be consecutive numbers. They do not need to correspond with real layer indexes from a layout object. When used as output, the layer map's logical layers correspond to the layer indexes inside the layout that the layer map was used upon.

This is a sample how to use the LayerMap object. It maps all datatypes of layers 1, 2 and 3 to datatype 0 and assigns the names 'ONE', 'TWO' and 'THREE' to these layout layers:

lm = RBA::LayerMap::new
lm.map("1/0-255 : ONE (1/0)")
lm.map("2/0-255 : TWO (2/0)")
lm.map("3/0-255 : THREE (3/0)")

# read the layout using the layer map
lo = RBA::LoadLayoutOptions::new
lo.layer_map.assign(lm)
ly = RBA::Layout::new
ly.read("input.gds", lo)

1:n mapping is supported: a physical layer can be mapped to multiple logical layers using 'mmap' instead of 'map'. When using this variant, mapping acts additive. The following example will map layer 1, datatypes 0 to 255 to logical layer 0, and layer 1, datatype 17 to logical layers 0 plus 1:

lm = RBA::LayerMap::new
lm.map("1/0-255", 0)   # (can be 'mmap' too)
lm.mmap("1/17", 1)

'unmapping' allows removing a mapping. This allows creating 'holes' in mapping ranges. The following example maps layer 1, datatypes 0 to 16 and 18 to 255 to logical layer 0:

lm = RBA::LayerMap::new
lm.map("1/0-255", 0)
lm.unmap("1/17")

The LayerMap class has been introduced in version 0.18. Target layer have been introduced in version 0.20. 1:n mapping and unmapping has been introduced in version 0.27.

Public constructors

new LayerMap 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.
voidassign(const LayerMap other)Assigns another object to self
voidclearClears the map
[const]new LayerMap ptrdupCreates a copy of self
[const]boolis_mapped?(const LayerInfo layer)Check, if a given physical layer is mapped
[const]unsigned int[]logicals(const LayerInfo layer)Returns the logical layers for a given physical layer.n@param layer The physical layer specified with an LayerInfo object.
voidmap(const LayerInfo phys_layer,
unsigned int log_layer)
Maps a physical layer to a logical one
voidmap(const LayerInfo phys_layer,
unsigned int log_layer,
const LayerInfo target_layer)
Maps a physical layer to a logical one with a target layer
voidmap(const LayerInfo pl_start,
const LayerInfo pl_stop,
unsigned int log_layer)
Maps a physical layer interval to a logical one
voidmap(const LayerInfo pl_start,
const LayerInfo pl_stop,
unsigned int log_layer,
const LayerInfo layer_properties)
Maps a physical layer interval to a logical one with a target layer
voidmap(string map_expr,
int log_layer = -1)
Maps a physical layer given by a string to a logical one
[const]LayerInfomapping(unsigned int log_layer)Returns the mapped physical (or target if one is specified) layer for a given logical layer
[const]stringmapping_str(unsigned int log_layer)Returns the mapping string for a given logical layer
voidmmap(const LayerInfo phys_layer,
unsigned int log_layer)
Maps a physical layer to a logical one and adds to existing mappings
voidmmap(const LayerInfo phys_layer,
unsigned int log_layer,
const LayerInfo target_layer)
Maps a physical layer to a logical one, adds to existing mappings and specifies a target layer
voidmmap(const LayerInfo pl_start,
const LayerInfo pl_stop,
unsigned int log_layer)
Maps a physical layer from the given interval to a logical one and adds to existing mappings
voidmmap(const LayerInfo pl_start,
const LayerInfo pl_stop,
unsigned int log_layer,
const LayerInfo layer_properties)
Maps a physical layer from the given interval to a logical one, adds to existing mappings and specifies a target layer
voidmmap(string map_expr,
int log_layer = -1)
Maps a physical layer given by an expression to a logical one and adds to existing mappings
[const]stringto_stringConverts a layer mapping object to a string
voidunmap(const LayerInfo phys_layer)Unmaps the given layer
voidunmap(const LayerInfo pl_start,
const LayerInfo pl_stop)
Unmaps the layers from the given interval
voidunmap(string expr)Unmaps the layers from the given expression

Public static methods and constants

LayerMapfrom_string(string arg1)Creates a layer map from the given string

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
[const]intlogical(const LayerInfo layer)Use of this method is deprecated

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.

assign

Signature: void assign (const LayerMap other)

Description: Assigns another object to self

clear

Signature: void clear

Description: Clears the map

create

Signature: void create

Description: Ensures the C++ object is created

Use of this method is deprecated. Use _create instead

Use this method to ensure the C++ object is created, for example to ensure that resources are allocated. Usually C++ objects are created on demand and not necessarily when the script object is created.

destroy

Signature: void destroy

Description: Explicitly destroys the object

Use of this method is deprecated. Use _destroy instead

Explicitly destroys the object on C++ side if it was owned by the script interpreter. Subsequent access to this object will throw an exception. If the object is not owned by the script, this method will do nothing.

destroyed?

Signature: [const] bool destroyed?

Description: Returns a value indicating whether the object was already destroyed

Use of this method is deprecated. Use _destroyed? instead

This method returns true, if the object was destroyed, either explicitly or by the C++ side. The latter may happen, if the object is owned by a C++ object which got destroyed itself.

dup

Signature: [const] new LayerMap ptr dup

Description: Creates a copy of self

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

from_string

Signature: [static] LayerMap from_string (string arg1)

Description: Creates a layer map from the given string

The format of the string is that used in layer mapping files: one mapping entry per line, comments are allowed using '#' or '//'. The format of each line is that used in the 'map(string, index)' method.

This method has been introduced in version 0.23.

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.

is_mapped?

Signature: [const] bool is_mapped? (const LayerInfo layer)

Description: Check, if a given physical layer is mapped

layer:The physical layer specified with an LayerInfo object.
Returns:True, if the layer is mapped.

logical

Signature: [const] int logical (const LayerInfo layer)

Description: Returns the logical layer (the layer index in the layout object) for a given physical layer.n@param layer The physical layer specified with an LayerInfo object.

Returns:The logical layer index or -1 if the layer is not mapped.

Use of this method is deprecated

This method is deprecated with version 0.27 as in this version, layers can be mapped to multiple targets which this method can't capture. Use logicals instead.

logicals

Signature: [const] unsigned int[] logicals (const LayerInfo layer)

Description: Returns the logical layers for a given physical layer.n@param layer The physical layer specified with an LayerInfo object.

Returns:This list of logical layers this physical layer as mapped to or empty if there is no mapping.

This method has been introduced in version 0.27.

map

(1) Signature: void map (const LayerInfo phys_layer, unsigned int log_layer)

Description: Maps a physical layer to a logical one

phys_layer:The physical layer (a LayerInfo object).
log_layer:The logical layer to which the physical layer is mapped.

In general, there may be more than one physical layer mapped to one logical layer. This method will add the given physical layer to the mapping for the logical layer.

(2) Signature: void map (const LayerInfo phys_layer, unsigned int log_layer, const LayerInfo target_layer)

Description: Maps a physical layer to a logical one with a target layer

phys_layer:The physical layer (a LayerInfo object).
log_layer:The logical layer to which the physical layer is mapped.
target_layer:The properties of the layer that will be created unless it already exists.

In general, there may be more than one physical layer mapped to one logical layer. This method will add the given physical layer to the mapping for the logical layer.

This method has been added in version 0.20.

(3) Signature: void map (const LayerInfo pl_start, const LayerInfo pl_stop, unsigned int log_layer)

Description: Maps a physical layer interval to a logical one

pl_start:The first physical layer (a LayerInfo object).
pl_stop:The last physical layer (a LayerInfo object).
log_layer:The logical layer to which the physical layers are mapped.

This method maps an interval of layers l1..l2 and datatypes d1..d2 to the mapping for the given logical layer. l1 and d1 are given by the pl_start argument, while l2 and d2 are given by the pl_stop argument.

(4) Signature: void map (const LayerInfo pl_start, const LayerInfo pl_stop, unsigned int log_layer, const LayerInfo layer_properties)

Description: Maps a physical layer interval to a logical one with a target layer

pl_start:The first physical layer (a LayerInfo object).
pl_stop:The last physical layer (a LayerInfo object).
log_layer:The logical layer to which the physical layers are mapped.
target_layer:The properties of the layer that will be created unless it already exists.

This method maps an interval of layers l1..l2 and datatypes d1..d2 to the mapping for the given logical layer. l1 and d1 are given by the pl_start argument, while l2 and d2 are given by the pl_stop argument. This method has been added in version 0.20.

(5) Signature: void map (string map_expr, int log_layer = -1)

Description: Maps a physical layer given by a string to a logical one

map_expr:The string describing the physical layer to map.
log_layer:The logical layer to which the physical layers are mapped.

The string expression is constructed using the syntax: "list[/list][;..]" for layer/datatype pairs. "list" is a sequence of numbers, separated by comma values or a range separated by a hyphen. Examples are: "1/2", "1-5/0", "1,2,5/0", "1/5;5/6".

layer/datatype wildcards can be specified with "*". When "*" is used for the upper limit, it is equivalent to "all layer above". When used alone, it is equivalent to "all layers". Examples: "1 / *", "* / 10-*"

Named layers are specified simply by specifying the name, if necessary in single or double quotes (if the name begins with a digit or contains non-word characters). layer/datatype and name descriptions can be mixed, i.e. "AA;1/5" (meaning: name "AA" or layer 1/datatype 5).

A target layer can be specified with the ":<target>" notation, where target is a valid string for a LayerProperties() object.

A target can include relative layer/datatype specifications and wildcards. For example, "1-10/0: *+1/0" will add 1 to the original layer number. "1-10/0-50: * / *" will use the original layers.

If the logical layer is negative or omitted, the method will select the next available one.

Target mapping has been added in version 0.20. The logical layer is optional since version 0.28.

mapping

Signature: [const] LayerInfo mapping (unsigned int log_layer)

Description: Returns the mapped physical (or target if one is specified) layer for a given logical layer

log_layer:The logical layer for which the mapping is requested.
Returns:A LayerInfo object which is the physical layer mapped to the logical layer.

In general, there may be more than one physical layer mapped to one logical layer. This method will return a single one of them. It will return the one with the lowest layer and datatype.

mapping_str

Signature: [const] string mapping_str (unsigned int log_layer)

Description: Returns the mapping string for a given logical layer

log_layer:The logical layer for which the mapping is requested.
Returns:A string describing the mapping.

The mapping string is compatible with the string that the "map" method accepts.

mmap

(1) Signature: void mmap (const LayerInfo phys_layer, unsigned int log_layer)

Description: Maps a physical layer to a logical one and adds to existing mappings

This method acts like the corresponding 'map' method, but adds the logical layer to the receivers of the given physical one. Hence this method implements 1:n mapping capabilities. For backward compatibility, 'map' still substitutes mapping.

Multi-mapping has been added in version 0.27.

(2) Signature: void mmap (const LayerInfo phys_layer, unsigned int log_layer, const LayerInfo target_layer)

Description: Maps a physical layer to a logical one, adds to existing mappings and specifies a target layer

This method acts like the corresponding 'map' method, but adds the logical layer to the receivers of the given physical one. Hence this method implements 1:n mapping capabilities. For backward compatibility, 'map' still substitutes mapping.

Multi-mapping has been added in version 0.27.

(3) Signature: void mmap (const LayerInfo pl_start, const LayerInfo pl_stop, unsigned int log_layer)

Description: Maps a physical layer from the given interval to a logical one and adds to existing mappings

This method acts like the corresponding 'map' method, but adds the logical layer to the receivers of the given physical one. Hence this method implements 1:n mapping capabilities. For backward compatibility, 'map' still substitutes mapping.

Multi-mapping has been added in version 0.27.

(4) Signature: void mmap (const LayerInfo pl_start, const LayerInfo pl_stop, unsigned int log_layer, const LayerInfo layer_properties)

Description: Maps a physical layer from the given interval to a logical one, adds to existing mappings and specifies a target layer

This method acts like the corresponding 'map' method, but adds the logical layer to the receivers of the given physical one. Hence this method implements 1:n mapping capabilities. For backward compatibility, 'map' still substitutes mapping.

Multi-mapping has been added in version 0.27.

(5) Signature: void mmap (string map_expr, int log_layer = -1)

Description: Maps a physical layer given by an expression to a logical one and adds to existing mappings

This method acts like the corresponding 'map' method, but adds the logical layer to the receivers of the given physical one. Hence this method implements 1:n mapping capabilities. For backward compatibility, 'map' still substitutes mapping.

If the logical layer is negative or omitted, the method will select the next available one.

Multi-mapping has been added in version 0.27. The logical layer is optional since version 0.28.

new

Signature: [static] new LayerMap ptr new

Description: Creates a new object of this class

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

to_string

Signature: [const] string to_string

Description: Converts a layer mapping object to a string

This method is the inverse of the from_string method.

This method has been introduced in version 0.23.

unmap

(1) Signature: void unmap (const LayerInfo phys_layer)

Description: Unmaps the given layer

Unmapping will remove the specific layer from the mapping. This method allows generating 'mapping holes' by first mapping a range and then unmapping parts of it.

This method has been introduced in version 0.27.

(2) Signature: void unmap (const LayerInfo pl_start, const LayerInfo pl_stop)

Description: Unmaps the layers from the given interval

This method has been introduced in version 0.27.

(3) Signature: void unmap (string expr)

Description: Unmaps the layers from the given expression

This method has been introduced in version 0.27.