mirror of
https://github.com/KLayout/klayout.git
synced 2026-09-07 03:21:34 +02:00
CellMapping: documentation, some convenience bindings
This commit is contained in:
Matthias Koefferlein
@@ -36,9 +36,98 @@ static db::cell_index_type drop_cell_const ()
|
||||
return db::DropCell;
|
||||
}
|
||||
|
||||
static void create_single_mapping (db::CellMapping *cm, db::Cell &a, const db::Cell &b)
|
||||
{
|
||||
tl_assert (a.layout () != 0);
|
||||
tl_assert (b.layout () != 0);
|
||||
cm->create_single_mapping (*a.layout (), a.cell_index (), *b.layout(), b.cell_index ());
|
||||
}
|
||||
|
||||
static std::vector<db::cell_index_type> create_single_mapping_full (db::CellMapping *cm, db::Cell &a, const db::Cell &b)
|
||||
{
|
||||
tl_assert (a.layout () != 0);
|
||||
tl_assert (b.layout () != 0);
|
||||
return cm->create_single_mapping_full (*a.layout (), a.cell_index (), *b.layout(), b.cell_index ());
|
||||
}
|
||||
|
||||
static std::vector<db::cell_index_type> create_multi_mapping_gen (db::CellMapping *cm, const std::vector<db::Cell *> &a, const std::vector<const db::Cell *> &b, bool full)
|
||||
{
|
||||
db::Layout *lya = 0;
|
||||
const db::Layout *lyb = 0;
|
||||
std::vector<db::cell_index_type> cia, cib;
|
||||
|
||||
for (auto i = a.begin (); i != a.end (); ++i) {
|
||||
tl_assert (*i != 0);
|
||||
tl_assert ((*i)->layout () != 0);
|
||||
cia.push_back ((*i)->cell_index ());
|
||||
if (lya == 0) {
|
||||
lya = (*i)->layout ();
|
||||
} else if (lya != (*i)->layout ()) {
|
||||
throw tl::Exception (tl::to_string (tr ("First cell array contains cells from different layouts")));
|
||||
}
|
||||
}
|
||||
|
||||
for (auto i = b.begin (); i != b.end (); ++i) {
|
||||
tl_assert (*i != 0);
|
||||
tl_assert ((*i)->layout () != 0);
|
||||
cib.push_back ((*i)->cell_index ());
|
||||
if (lyb == 0) {
|
||||
lyb = (*i)->layout ();
|
||||
} else if (lyb != (*i)->layout ()) {
|
||||
throw tl::Exception (tl::to_string (tr ("Second cell array contains cells from different layouts")));
|
||||
}
|
||||
}
|
||||
|
||||
if (full) {
|
||||
return cm->create_multi_mapping_full (*lya, cia, *lyb, cib);
|
||||
} else {
|
||||
cm->create_multi_mapping (*lya, cia, *lyb, cib);
|
||||
return std::vector<db::cell_index_type> ();
|
||||
}
|
||||
}
|
||||
|
||||
static std::vector<db::cell_index_type> create_multi_mapping_full (db::CellMapping *cm, const std::vector<db::Cell *> &a, const std::vector<const db::Cell *> &b)
|
||||
{
|
||||
return create_multi_mapping_gen (cm, a, b, true);
|
||||
}
|
||||
|
||||
static void create_multi_mapping (db::CellMapping *cm, const std::vector<db::Cell *> &a, const std::vector<const db::Cell *> &b)
|
||||
{
|
||||
create_multi_mapping_gen (cm, a, b, false);
|
||||
}
|
||||
|
||||
static void create_from_geometry (db::CellMapping *cm, db::Cell &a, const db::Cell &b)
|
||||
{
|
||||
tl_assert (a.layout () != 0);
|
||||
tl_assert (b.layout () != 0);
|
||||
return cm->create_from_geometry (*a.layout (), a.cell_index (), *b.layout(), b.cell_index ());
|
||||
}
|
||||
|
||||
static std::vector<db::cell_index_type> create_from_geometry_full (db::CellMapping *cm, db::Cell &a, const db::Cell &b)
|
||||
{
|
||||
tl_assert (a.layout () != 0);
|
||||
tl_assert (b.layout () != 0);
|
||||
return cm->create_from_geometry_full (*a.layout (), a.cell_index (), *b.layout(), b.cell_index ());
|
||||
}
|
||||
|
||||
static void create_from_names (db::CellMapping *cm, db::Cell &a, const db::Cell &b)
|
||||
{
|
||||
tl_assert (a.layout () != 0);
|
||||
tl_assert (b.layout () != 0);
|
||||
return cm->create_from_names (*a.layout (), a.cell_index (), *b.layout(), b.cell_index ());
|
||||
}
|
||||
|
||||
static std::vector<db::cell_index_type> create_from_names_full (db::CellMapping *cm, db::Cell &a, const db::Cell &b)
|
||||
{
|
||||
tl_assert (a.layout () != 0);
|
||||
tl_assert (b.layout () != 0);
|
||||
return cm->create_from_names_full (*a.layout (), a.cell_index (), *b.layout(), b.cell_index ());
|
||||
}
|
||||
|
||||
|
||||
Class<db::CellMapping> decl_CellMapping ("db", "CellMapping",
|
||||
gsi::method ("DropCell", &drop_cell_const,
|
||||
"@brief A constant indicating the reques to drop a cell\n"
|
||||
"@brief A constant indicating the request to drop a cell\n"
|
||||
"\n"
|
||||
"If used as a pseudo-target for the cell mapping, this index indicates "
|
||||
"that the cell shall be dropped rather than created on the target side "
|
||||
@@ -65,9 +154,19 @@ Class<db::CellMapping> decl_CellMapping ("db", "CellMapping",
|
||||
"\n"
|
||||
"This method has been introduced in version 0.23."
|
||||
) +
|
||||
gsi::method ("for_single_cell_full", &db::CellMapping::create_single_mapping_full, gsi::arg ("layout_a"), gsi::arg ("cell_index_a"), gsi::arg ("layout_b"), gsi::arg ("cell_index_b"),
|
||||
gsi::method_ext ("for_single_cell", &create_single_mapping, gsi::arg ("cell_a"), gsi::arg ("cell_b"),
|
||||
"@brief Initializes the cell mapping for top-level identity\n"
|
||||
"\n"
|
||||
"@param cell_a The target cell.\n"
|
||||
"@param cell_b The source cell.\n"
|
||||
"@return A list of indexes of cells created.\n"
|
||||
"\n"
|
||||
"This is a convenience version which uses cell references instead of layout/cell index combinations. "
|
||||
"It has been introduced in version 0.28."
|
||||
) +
|
||||
gsi::method ("for_single_cell_full", &db::CellMapping::create_single_mapping_full, gsi::arg ("layout_a"), gsi::arg ("cell_index_a"), gsi::arg ("layout_b"), gsi::arg ("cell_index_b"),
|
||||
"@brief Initializes the cell mapping for top-level identity in full mapping mode\n"
|
||||
"\n"
|
||||
"@param layout_a The target layout.\n"
|
||||
"@param cell_index_a The index of the target cell.\n"
|
||||
"@param layout_b The source layout.\n"
|
||||
@@ -80,6 +179,16 @@ Class<db::CellMapping> decl_CellMapping ("db", "CellMapping",
|
||||
"\n"
|
||||
"This method has been introduced in version 0.23."
|
||||
) +
|
||||
gsi::method_ext ("for_single_cell_full", &create_single_mapping_full, gsi::arg ("cell_a"), gsi::arg ("cell_b"),
|
||||
"@brief Initializes the cell mapping for top-level identity in full mapping mode\n"
|
||||
"\n"
|
||||
"@param cell_a The target cell.\n"
|
||||
"@param cell_b The source cell.\n"
|
||||
"@return A list of indexes of cells created.\n"
|
||||
"\n"
|
||||
"This is a convenience version which uses cell references instead of layout/cell index combinations. "
|
||||
"It has been introduced in version 0.28."
|
||||
) +
|
||||
gsi::method ("for_multi_cells", &db::CellMapping::create_multi_mapping, gsi::arg ("layout_a"), gsi::arg ("cell_indexes_a"), gsi::arg ("layout_b"), gsi::arg ("cell_indexes_b"),
|
||||
"@brief Initializes the cell mapping for top-level identity\n"
|
||||
"\n"
|
||||
@@ -97,9 +206,19 @@ Class<db::CellMapping> decl_CellMapping ("db", "CellMapping",
|
||||
"\n"
|
||||
"This method has been introduced in version 0.27."
|
||||
) +
|
||||
gsi::method ("for_multi_cells_full", &db::CellMapping::create_multi_mapping_full, gsi::arg ("layout_a"), gsi::arg ("cell_indexes_a"), gsi::arg ("layout_b"), gsi::arg ("cell_indexes_b"),
|
||||
gsi::method_ext ("for_multi_cells", &create_multi_mapping, gsi::arg ("cell_a"), gsi::arg ("cell_b"),
|
||||
"@brief Initializes the cell mapping for top-level identity\n"
|
||||
"\n"
|
||||
"@param cell_a A list of target cells.\n"
|
||||
"@param cell_b A list of source cells.\n"
|
||||
"@return A list of indexes of cells created.\n"
|
||||
"\n"
|
||||
"This is a convenience version which uses cell references instead of layout/cell index combinations. "
|
||||
"It has been introduced in version 0.28."
|
||||
) +
|
||||
gsi::method ("for_multi_cells_full", &db::CellMapping::create_multi_mapping_full, gsi::arg ("layout_a"), gsi::arg ("cell_indexes_a"), gsi::arg ("layout_b"), gsi::arg ("cell_indexes_b"),
|
||||
"@brief Initializes the cell mapping for top-level identity in full mapping mode\n"
|
||||
"\n"
|
||||
"@param layout_a The target layout.\n"
|
||||
"@param cell_indexes_a A list of cell indexes for the target cells.\n"
|
||||
"@param layout_b The source layout.\n"
|
||||
@@ -112,6 +231,16 @@ Class<db::CellMapping> decl_CellMapping ("db", "CellMapping",
|
||||
"\n"
|
||||
"This method has been introduced in version 0.27."
|
||||
) +
|
||||
gsi::method_ext ("for_multi_cells_full", &create_multi_mapping_full, gsi::arg ("cell_a"), gsi::arg ("cell_b"),
|
||||
"@brief Initializes the cell mapping for top-level identity in full mapping mode\n"
|
||||
"\n"
|
||||
"@param cell_a A list of target cells.\n"
|
||||
"@param cell_b A list of source cells.\n"
|
||||
"@return A list of indexes of cells created.\n"
|
||||
"\n"
|
||||
"This is a convenience version which uses cell references instead of layout/cell index combinations. "
|
||||
"It has been introduced in version 0.28."
|
||||
) +
|
||||
gsi::method ("from_geometry_full", &db::CellMapping::create_from_geometry_full, gsi::arg ("layout_a"), gsi::arg ("cell_index_a"), gsi::arg ("layout_b"), gsi::arg ("cell_index_b"),
|
||||
"@brief Initializes the cell mapping using the geometrical identity in full mapping mode\n"
|
||||
"\n"
|
||||
@@ -132,6 +261,16 @@ Class<db::CellMapping> decl_CellMapping ("db", "CellMapping",
|
||||
"\n"
|
||||
"This method has been introduced in version 0.23."
|
||||
) +
|
||||
gsi::method_ext ("from_geometry_full", &create_from_geometry_full, gsi::arg ("cell_a"), gsi::arg ("cell_b"),
|
||||
"@brief Initializes the cell mapping using the geometrical identity in full mapping mode\n"
|
||||
"\n"
|
||||
"@param cell_a The target cell.\n"
|
||||
"@param cell_b The source cell.\n"
|
||||
"@return A list of indexes of cells created.\n"
|
||||
"\n"
|
||||
"This is a convenience version which uses cell references instead of layout/cell index combinations. "
|
||||
"It has been introduced in version 0.28."
|
||||
) +
|
||||
gsi::method ("from_geometry", &db::CellMapping::create_from_geometry, gsi::arg ("layout_a"), gsi::arg ("cell_index_a"), gsi::arg ("layout_b"), gsi::arg ("cell_index_b"),
|
||||
"@brief Initializes the cell mapping using the geometrical identity\n"
|
||||
"\n"
|
||||
@@ -147,6 +286,16 @@ Class<db::CellMapping> decl_CellMapping ("db", "CellMapping",
|
||||
"\n"
|
||||
"This method has been introduced in version 0.23."
|
||||
) +
|
||||
gsi::method_ext ("from_geometry", &create_from_geometry, gsi::arg ("cell_a"), gsi::arg ("cell_b"),
|
||||
"@brief Initializes the cell mapping using the geometrical identity\n"
|
||||
"\n"
|
||||
"@param cell_a The target cell.\n"
|
||||
"@param cell_b The source cell.\n"
|
||||
"@return A list of indexes of cells created.\n"
|
||||
"\n"
|
||||
"This is a convenience version which uses cell references instead of layout/cell index combinations. "
|
||||
"It has been introduced in version 0.28."
|
||||
) +
|
||||
gsi::method ("from_names", &db::CellMapping::create_from_names, gsi::arg ("layout_a"), gsi::arg ("cell_index_a"), gsi::arg ("layout_b"), gsi::arg ("cell_index_b"),
|
||||
"@brief Initializes the cell mapping using the name identity\n"
|
||||
"\n"
|
||||
@@ -161,6 +310,16 @@ Class<db::CellMapping> decl_CellMapping ("db", "CellMapping",
|
||||
"\n"
|
||||
"This method has been introduced in version 0.23."
|
||||
) +
|
||||
gsi::method_ext ("from_names", &create_from_names, gsi::arg ("cell_a"), gsi::arg ("cell_b"),
|
||||
"@brief Initializes the cell mapping using the name identity\n"
|
||||
"\n"
|
||||
"@param cell_a The target cell.\n"
|
||||
"@param cell_b The source cell.\n"
|
||||
"@return A list of indexes of cells created.\n"
|
||||
"\n"
|
||||
"This is a convenience version which uses cell references instead of layout/cell index combinations. "
|
||||
"It has been introduced in version 0.28."
|
||||
) +
|
||||
gsi::method ("from_names_full", &db::CellMapping::create_from_names_full, gsi::arg ("layout_a"), gsi::arg ("cell_index_a"), gsi::arg ("layout_b"), gsi::arg ("cell_index_b"),
|
||||
"@brief Initializes the cell mapping using the name identity in full mapping mode\n"
|
||||
"\n"
|
||||
@@ -180,7 +339,17 @@ Class<db::CellMapping> decl_CellMapping ("db", "CellMapping",
|
||||
"\n"
|
||||
"This method has been introduced in version 0.23."
|
||||
) +
|
||||
gsi::method ("clear", &db::CellMapping::clear,
|
||||
gsi::method_ext ("from_names_full", &create_from_names_full, gsi::arg ("cell_a"), gsi::arg ("cell_b"),
|
||||
"@brief Initializes the cell mapping using the name identity in full mapping mode\n"
|
||||
"\n"
|
||||
"@param cell_a The target cell.\n"
|
||||
"@param cell_b The source cell.\n"
|
||||
"@return A list of indexes of cells created.\n"
|
||||
"\n"
|
||||
"This is a convenience version which uses cell references instead of layout/cell index combinations. "
|
||||
"It has been introduced in version 0.28."
|
||||
) +
|
||||
gsi::method ("clear", &db::CellMapping::clear,
|
||||
"@brief Clears the mapping.\n"
|
||||
"\n"
|
||||
"This method has been introduced in version 0.23."
|
||||
@@ -208,7 +377,6 @@ Class<db::CellMapping> decl_CellMapping ("db", "CellMapping",
|
||||
gsi::method ("has_mapping?", &db::CellMapping::has_mapping, gsi::arg ("cell_index_b"),
|
||||
"@brief Returns as value indicating whether a cell of layout_b has a mapping to a layout_a cell.\n"
|
||||
"\n"
|
||||
"\n"
|
||||
"@param cell_index_b The index of the cell in layout_b whose mapping is requested.\n"
|
||||
"@return true, if the cell has a mapping\n"
|
||||
"\n"
|
||||
@@ -231,15 +399,27 @@ Class<db::CellMapping> decl_CellMapping ("db", "CellMapping",
|
||||
"the mapping of cells of a source layout B to a target layout A. The cell mapping object "
|
||||
"is basically a table associating a cell in layout B with a cell in layout A.\n"
|
||||
"\n"
|
||||
"The cell mapping is of particular interest for providing the cell mapping recipe in "
|
||||
"\\Cell#copy_tree_shapes or \\Cell#move_tree_shapes.\n"
|
||||
"\n"
|
||||
"The mapping object is used to create and hold that table. There are three basic modes in which "
|
||||
"a table can be generated:\n"
|
||||
"\n"
|
||||
"@ul\n"
|
||||
" @li Top-level identity @/li\n"
|
||||
" @li Geometrical identity @/li\n"
|
||||
" @li Name identity @/li\n"
|
||||
" @li Top-level identity (\\for_single_cell and \\for_single_cell_full) @/li\n"
|
||||
" @li Top-level identify for multiple cells (\\for_multi_cells_full and \\for_multi_cells_full) @/li\n"
|
||||
" @li Geometrical identity (\\from_geometry and \\from_geometry_full)@/li\n"
|
||||
" @li Name identity (\\from_names and \\from_names_full) @/li\n"
|
||||
"@/ul\n"
|
||||
"\n"
|
||||
"'full' refers to the way cells are treated which are not mentioned. In the 'full' versions, "
|
||||
"cells for which no mapping is established explicitly - specifically all child cells in top-level identity modes - "
|
||||
"are created in the target layout and instantiated according to their source layout hierarchy. Then, these new "
|
||||
"cells become targets of the respective source cells. "
|
||||
"In the plain version (without 'full' cells), no additional cells are created. For the case of \\Layout#copy_tree_shapes "
|
||||
"cells not explicitly mapped are flattened. Hence for example, \\for_single_cell will flatten all children of the source cell during "
|
||||
"\\Layout#copy_tree_shapes or \\Layout#move_tree_shapes.\n"
|
||||
"\n"
|
||||
"Top-level identity means that only one cell (the top cell) is regarded identical. All child cells are "
|
||||
"not considered identical. In full mode (see below), this will create a new, identical cell tree "
|
||||
"below the top cell in layout A.\n"
|
||||
@@ -264,10 +444,42 @@ Class<db::CellMapping> decl_CellMapping ("db", "CellMapping",
|
||||
"\\from_names_full or \\from_geometry_full. These versions will create new cells and their corresponding "
|
||||
"instances in the target layout if no suitable target cell is found.\n"
|
||||
"\n"
|
||||
"CellMapping objects play a role mainly in the hierarchical copy or move operations of \\Layout. "
|
||||
"However, use is not restricted to these applications.\n"
|
||||
"This is a simple example for a cell mapping preserving the hierarchy of the source cell and creating "
|
||||
"a hierarchy copy in the top cell of the target layout ('hierarchical merge'):\n"
|
||||
"\n"
|
||||
"Here is one example for using \\CellMapping. It extracts cells 'A', 'B' and 'C' from one layout "
|
||||
"@code\n"
|
||||
"cell_names = [ \"A\", \"B\", \"C\" ]\n"
|
||||
"\n"
|
||||
"source = RBA::Layout::new\n"
|
||||
"source.read(\"input.gds\")\n"
|
||||
"\n"
|
||||
"target = RBA::Layout::new\n"
|
||||
"target_top = target.create_cell(\"IMPORTED\")\n"
|
||||
"\n"
|
||||
"cm = RBA::CellMapping::new\n"
|
||||
"# Copies the source layout hierarchy into the target top cell:\n"
|
||||
"cm.for_single_cell_full(target_top, source.top_cell)\n"
|
||||
"target.copy_tree_shapes(source, cm)\n"
|
||||
"@/code\n"
|
||||
"\n"
|
||||
"Without 'full', the effect is move-with-flattening (note we're using 'move' in this example):\n"
|
||||
"\n"
|
||||
"@code\n"
|
||||
"cell_names = [ \"A\", \"B\", \"C\" ]\n"
|
||||
"\n"
|
||||
"source = RBA::Layout::new\n"
|
||||
"source.read(\"input.gds\")\n"
|
||||
"\n"
|
||||
"target = RBA::Layout::new\n"
|
||||
"target_top = target.create_cell(\"IMPORTED\")\n"
|
||||
"\n"
|
||||
"cm = RBA::CellMapping::new\n"
|
||||
"# Flattens the source layout hierarchy into the target top cell:\n"
|
||||
"cm.for_single_cell(target_top, source.top_cell)\n"
|
||||
"target.move_tree_shapes(source, cm)\n"
|
||||
"@/code\n"
|
||||
"\n"
|
||||
"This is another example for using \\CellMapping in multiple top cell identity mode. It extracts cells 'A', 'B' and 'C' from one layout "
|
||||
"and copies them to another. It will also copy all shapes and all child cells. Child cells which are "
|
||||
"shared between the three initial cells will be shared in the target layout too.\n"
|
||||
"\n"
|
||||
@@ -279,11 +491,11 @@ Class<db::CellMapping> decl_CellMapping ("db", "CellMapping",
|
||||
"\n"
|
||||
"target = RBA::Layout::new\n"
|
||||
"\n"
|
||||
"source_cells = cell_names.collect { |n| source.cell_by_name(n).cell_index }\n"
|
||||
"target_cells = cell_names.collect { |n| target.create_cell(n).cell_index }\n"
|
||||
"source_cells = cell_names.collect { |n| source.cell_by_name(n) }\n"
|
||||
"target_cells = cell_names.collect { |n| target.create_cell(n) }\n"
|
||||
"\n"
|
||||
"cm = RBA::CellMapping::new\n"
|
||||
"cm.for_multi_cells_full(source, source_cells, target, target_cells)\n"
|
||||
"cm.for_multi_cells_full(target_cells, source_cells)\n"
|
||||
"target.copy_tree_shapes(source, cm)\n"
|
||||
"@/code\n"
|
||||
);
|
||||
|
||||
Reference in New Issue
Block a user