GDSII Library¶
gdspy is a Python module that allows the creation of GDSII stream files.
Many features of the GDSII format are implemented, such as cell references and arrays, but the support for fonts is quite limited. Text is only available through polygonal objects.
Classes¶
Cell¶
-
class
gdspy.
Cell
(name, exclude_from_current=False)¶ Bases:
object
Collection of elements, both geometric objects and references to other cells.
Parameters: - name (string) – The name of the cell.
- exclude_from_current (bool) – If
True
, the cell will not be automatically included in the current library.
Variables: -
add
(element)¶ Add a new element or list of elements to this cell.
Parameters: element (object, list) – The element or list of elements to be inserted in this cell. Returns: out – This cell. Return type: Cell
-
area
(by_spec=False)¶ Calculate the total area of the elements on this cell, including cell references and arrays.
Parameters: by_spec (bool) – If True
, the return value is a dictionary with the areas of each individual pair (layer, datatype).Returns: out – Area of this cell. Return type: number, dictionary
-
copy
(name, exclude_from_current=False, deep_copy=False)¶ Creates a copy of this cell.
Parameters: - name (string) – The name of the cell.
- exclude_from_current (bool) – If
True
, the cell will not be included in the global list of cells maintained bygdspy
. - deep_copy (bool) – If
False
, the new cell will contain only references to the existing elements. IfTrue
, copies of all elements are also created.
Returns: out – The new copy of this cell.
Return type: Cell
-
elements
¶
-
flatten
(single_layer=None, single_datatype=None, single_texttype=None)¶ Flatten all
CellReference
andCellArray
elements in this cell into real polygons and labels, instead of references.Parameters: - single_layer (integer or None) – If not
None
, all polygons will be transferred to the layer indicated by this number. - single_datatype (integer or None) – If not
None
, all polygons will be transferred to the datatype indicated by this number. - single_datatype – If not
None
, all labels will be transferred to the texttype indicated by this number.
Returns: out – This cell.
Return type: Cell
- single_layer (integer or None) – If not
-
get_bounding_box
()¶ Returns the bounding box for this cell.
Returns: out – Bounding box of this cell [[x_min, y_min], [x_max, y_max]], or None
if the cell is empty.Return type: Numpy array[2,2] or None
-
get_datatypes
()¶ Returns a set of datatypes in this cell.
Returns: out – Set of the datatypes used in this cell. Return type: set
-
get_dependencies
(recursive=False)¶ Returns a list of the cells included in this cell as references.
Parameters: recursive (bool) – If True returns cascading dependencies. Returns: out – List of the cells referenced by this cell. Return type: set of Cell
-
get_labels
(depth=None)¶ Returns a list with a copy of the labels in this cell.
Parameters: depth (integer or None
) – If notNone
, defines from how many reference levels to retrieve labels from.Returns: out – List containing the labels in this cell and its references. Return type: list of Label
-
get_layers
()¶ Returns a set of layers in this cell.
Returns: out – Set of the layers used in this cell. Return type: set
-
get_polygons
(by_spec=False, depth=None)¶ Returns a list of polygons in this cell.
Parameters: - by_spec (bool) – If
True
, the return value is a dictionary with the polygons of each individual pair (layer, datatype). - depth (integer or
None
) – If notNone
, defines from how many reference levels to retrieve polygons. References below this level will result in a bounding box. Ifby_spec
isTrue
the key will be the name of this cell.
Returns: out – List containing the coordinates of the vertices of each polygon, or dictionary with the list of polygons (if
by_spec
isTrue
).Return type: list of array-like[N][2] or dictionary
- by_spec (bool) – If
-
labels
¶
-
name
¶
-
remove_labels
(test)¶ Remove labels from this cell.
The function or callable
test
is called for each label in the cell. If its return value evaluates toTrue
, the corresponding label is removed from the cell.Parameters: test (callable) – Test function to query whether a label should be removed. The function is called with the label as the only argument. Returns: out – This cell. Return type: Cell
Examples
Remove labels in layer 1:
>>> cell.remove_labels(lambda lbl: lbl.layer == 1)
-
remove_polygons
(test)¶ Remove polygons from this cell.
The function or callable
test
is called for each polygon in the cell. If its return value evaluates toTrue
, the corresponding polygon is removed from the cell.Parameters: test (callable) – Test function to query whether a polygon should be removed. The function is called with arguments: (points, layer, datatype)
Returns: out – This cell. Return type: Cell
Examples
Remove polygons in layer 1:
>>> cell.remove_polygons(lambda pts, layer, datatype: ... layer == 1)
Remove polygons with negative x coordinates:
>>> cell.remove_polygons(lambda pts, layer, datatype: ... any(pts[:, 0] < 0))
-
to_gds
(multiplier, timestamp=None)¶ Convert this cell to a GDSII structure.
Parameters: - multiplier (number) – A number that multiplies all dimensions written in the GDSII structure.
- timestamp (datetime object) – Sets the GDSII timestamp. If
None
, the current time is used.
Returns: out – The GDSII binary string that represents this cell.
Return type: string
CellReference¶
-
class
gdspy.
CellReference
(ref_cell, origin=(0, 0), rotation=None, magnification=None, x_reflection=False, ignore_missing=False)¶ Bases:
object
Simple reference to an existing cell.
Parameters: - ref_cell (
Cell
or string) – The referenced cell or its name. - origin (array-like[2]) – Position where the reference is inserted.
- rotation (number) – Angle of rotation of the reference (in degrees).
- magnification (number) – Magnification factor for the reference.
- x_reflection (bool) – If
True
the reference is reflected parallel to the x direction before being rotated. - ignore_missing (bool) – If
False
a warning is issued when the referenced cell is not found.
-
area
(by_spec=False)¶ Calculate the total area of the referenced cell with the magnification factor included.
Parameters: by_spec (bool) – If True
, the return value is a dictionary with the areas of each individual pair (layer, datatype).Returns: out – Area of this cell. Return type: number, dictionary
-
get_bounding_box
()¶ Returns the bounding box for this reference.
Returns: out – Bounding box of this cell [[x_min, y_min], [x_max, y_max]], or None
if the cell is empty.Return type: Numpy array[2,2] or None
-
get_labels
(depth=None)¶ Returns a list of labels created by this reference.
Parameters: depth (integer or None
) – If notNone
, defines from how many reference levels to retrieve labels from.Returns: out – List containing the labels in this cell and its references. Return type: list of Label
-
get_polygons
(by_spec=False, depth=None)¶ Returns a list of polygons created by this reference.
Parameters: - by_spec (bool) – If
True
, the return value is a dictionary with the polygons of each individual pair (layer, datatype). - depth (integer or
None
) – If notNone
, defines from how many reference levels to retrieve polygons. References below this level will result in a bounding box. Ifby_spec
isTrue
the key will be the name of the referenced cell.
Returns: out – List containing the coordinates of the vertices of each polygon, or dictionary with the list of polygons (if
by_spec
isTrue
).Return type: list of array-like[N][2] or dictionary
- by_spec (bool) – If
-
magnification
¶
-
origin
¶
-
ref_cell
¶
-
rotation
¶
-
to_gds
(multiplier)¶ Convert this object to a GDSII element.
Parameters: multiplier (number) – A number that multiplies all dimensions written in the GDSII element. Returns: out – The GDSII binary string that represents this object. Return type: string
-
translate
(dx, dy)¶ Move the reference from one place to another
Parameters: - dx (float) – distance to move in the x-direction
- dy (float) – distance to move in the y-direction
Returns: out – This object.
Return type: CellReference
-
x_reflection
¶
- ref_cell (
CellArray¶
-
class
gdspy.
CellArray
(ref_cell, columns, rows, spacing, origin=(0, 0), rotation=None, magnification=None, x_reflection=False, ignore_missing=False)¶ Bases:
object
Multiple references to an existing cell in an array format.
Parameters: - ref_cell (
Cell
or string) – The referenced cell or its name. - columns (positive integer) – Number of columns in the array.
- rows (positive integer) – Number of columns in the array.
- spacing (array-like[2]) – distances between adjacent columns and adjacent rows.
- origin (array-like[2]) – Position where the cell is inserted.
- rotation (number) – Angle of rotation of the reference (in degrees).
- magnification (number) – Magnification factor for the reference.
- x_reflection (bool) – If
True
, the reference is reflected parallel to the x direction before being rotated. - ignore_missing (bool) – If
False
a warning is issued when the referenced cell is not found.
-
area
(by_spec=False)¶ Calculate the total area of the cell array with the magnification factor included.
Parameters: by_spec (bool) – If True
, the return value is a dictionary with the areas of each individual pair (layer, datatype).Returns: out – Area of this cell. Return type: number, dictionary
-
columns
¶
-
get_bounding_box
()¶ Returns the bounding box for this reference.
Returns: out – Bounding box of this cell [[x_min, y_min], [x_max, y_max]], or None
if the cell is empty.Return type: Numpy array[2,2] or None
-
get_labels
(depth=None)¶ Returns a list of labels created by this reference.
Parameters: depth (integer or None
) – If notNone
, defines from how many reference levels to retrieve labels from.Returns: out – List containing the labels in this cell and its references. Return type: list of Label
-
get_polygons
(by_spec=False, depth=None)¶ Returns a list of polygons created by this reference.
Parameters: - by_spec (bool) – If
True
, the return value is a dictionary with the polygons of each individual pair (layer, datatype). - depth (integer or
None
) – If notNone
, defines from how many reference levels to retrieve polygons. References below this level will result in a bounding box. Ifby_spec
isTrue
the key will be name of the referenced cell.
Returns: out – List containing the coordinates of the vertices of each polygon, or dictionary with the list of polygons (if
by_spec
isTrue
).Return type: list of array-like[N][2] or dictionary
- by_spec (bool) – If
-
magnification
¶
-
origin
¶
-
ref_cell
¶
-
rotation
¶
-
rows
¶
-
spacing
¶
-
to_gds
(multiplier)¶ Convert this object to a GDSII element.
Parameters: multiplier (number) – A number that multiplies all dimensions written in the GDSII element. Returns: out – The GDSII binary string that represents this object. Return type: string
-
translate
(dx, dy)¶ Move the reference from one place to another
Parameters: - dx (float) – distance to move in the x-direction
- dy (float) – distance to move in the y-direction
Returns: out – This object.
Return type: CellArray
-
x_reflection
¶
- ref_cell (
GdsLibrary¶
-
class
gdspy.
GdsLibrary
(name='library', infile=None, unit=1e-06, precision=1e-09, **kwargs)¶ Bases:
object
GDSII library (file).
Represent a GDSII library containing a dictionary of cells.
Parameters: - name (string) – Name of the GDSII library. Ignored if a name is defined in infile.
- infile (file or string) – GDSII stream file (or path) to be imported. It must be opened for reading in binary format.
- kwargs (keyword arguments) – Arguments passed to read_gds.
Variables: - name (string) – Name of the GDSII library.
- cell_dict (dictionary) – Dictionary of cells in this library, indexed by name.
- unit (number) – Unit size for the objects in the library (in meters).
- precision (number) – Precision for the dimensions of the objects in the library (in meters).
-
add
(cell, overwrite_duplicate=False)¶ Add one or more cells to the library.
Parameters: - cell (
Cell
of list ofCell
) – Cells to be included in the library. - overwrite_duplicate (bool) – If True an existing cell with the same name in the library will be overwritten.
Returns: out – This object.
Return type: GdsLibrary
- cell (
-
extract
(cell)¶ Extract a cell from the this GDSII file and include it in the current global library, including referenced dependencies.
Parameters: cell ( Cell
or string) – Cell or name of the cell to be extracted from the imported file. Referenced cells will be automatically extracted as well.Returns: out – The extracted cell. Return type: Cell
-
read_gds
(infile, units='skip', rename={}, layers={}, datatypes={}, texttypes={})¶ Read a GDSII file into this library.
Parameters: - infile (file or string) – GDSII stream file (or path) to be imported. It must be opened for reading in binary format.
- units ({'convert', 'import', 'skip'}) – Controls how to scale and use the units in the imported
file.
'convert'
: the imported geometry is scaled to this library units.'import'
: the unit and precision in this library are replaced by those from the imported file.'skip'
: the imported geometry is not scaled and units are not replaced; the geometry is imported in the user units of the file. - rename (dictionary) – Dictionary used to rename the imported cells. Keys and values must be strings.
- layers (dictionary) – Dictionary used to convert the layers in the imported cells. Keys and values must be integers.
- datatypes (dictionary) – Dictionary used to convert the datatypes in the imported cells. Keys and values must be integers.
- texttypes (dictionary) – Dictionary used to convert the text types in the imported cells. Keys and values must be integers.
Returns: out – This object.
Return type: GdsLibrary
Notes
Not all features from the GDSII specification are currently supported. A warning will be produced if any unsupported features are found in the imported file.
-
top_level
()¶ Output the top level cells from the GDSII data.
Top level cells are those that are not referenced by any other cells.
Returns: out – List of top level cells. Return type: list
-
write_gds
(outfile, cells=None, timestamp=None)¶ Write the GDSII library to a file.
The dimensions actually written on the GDSII file will be the dimensions of the objects created times the ratio
unit/precision
. For example, if a circle with radius 1.5 is created and we setunit=1.0e-6
(1 um) andprecision=1.0e-9
(1 nm), the radius of the circle will be 1.5 um and the GDSII file will contain the dimension 1500 nm.Parameters: - outfile (file or string) – The file (or path) where the GDSII stream will be written. It must be opened for writing operations in binary format.
- cells (array-like) – The list of cells or cell names to be included in the
library. If
None
, all cells are used. - timestamp (datetime object) – Sets the GDSII timestamp. If
None
, the current time is used.
Notes
Only the specified cells are written. The user is responsible for ensuring all cell dependencies are satisfied.
GdsWriter¶
-
class
gdspy.
GdsWriter
(outfile, name='library', unit=1e-06, precision=1e-09, timestamp=None)¶ Bases:
object
GDSII strem library writer.
The dimensions actually written on the GDSII file will be the dimensions of the objects created times the ratio
unit/precision
. For example, if a circle with radius 1.5 is created and we setunit=1.0e-6
(1 um) andprecision=1.0e-9
(1 nm), the radius of the circle will be 1.5 um and the GDSII file will contain the dimension 1500 nm.Parameters: - outfile (file or string) – The file (or path) where the GDSII stream will be written. It must be opened for writing operations in binary format.
- name (string) – Name of the GDSII library (file).
- unit (number) – Unit size for the objects in the library (in meters).
- precision (number) – Precision for the dimensions of the objects in the library (in meters).
- timestamp (datetime object) – Sets the GDSII timestamp. If
None
, the current time is used.
Notes
This class can be used for incremental output of the geometry in case the complete layout is too large to be kept in memory all at once.
Examples
>>> writer = gdspy.GdsWriter('out-file.gds', unit=1.0e-6, ... precision=1.0e-9) >>> for i in range(10): ... cell = gdspy.Cell('C{}'.format(i), True) ... # Add the contents of this cell... ... writer.write_cell(cell) ... # Clear the memory: erase Cell objects and any other objects ... # that won't be needed. ... del cell >>> writer.close()
-
close
()¶ Finalize the GDSII stream library.
-
write_cell
(cell)¶ Write the specified cell to the file.
Parameters: cell ( Cell
) – Cell to be written.Notes
Only the specified cell is written. Dependencies must be manually included.
Returns: out – This object. Return type: GdsWriter
LayoutViewer¶
Functions¶
write_gds¶
-
gdspy.
write_gds
(outfile, cells=None, name='library', unit=1e-06, precision=1e-09)¶ Write the current GDSII library to a file.
The dimensions actually written on the GDSII file will be the dimensions of the objects created times the ratio
unit/precision
. For example, if a circle with radius 1.5 is created and we setunit=1.0e-6
(1 um) andprecision=1.0e-9
(1 nm), the radius of the circle will be 1.5 um and the GDSII file will contain the dimension 1500 nm.Parameters: - outfile (file or string) – The file (or path) where the GDSII stream will be written. It must be opened for writing operations in binary format.
- cells (array-like) – The list of cells or cell names to be included in the library.
If
None
, all cells are used. - name (string) – Name of the GDSII library.
- unit (number) – Unit size for the objects in the library (in meters).
- precision (number) – Precision for the dimensions of the objects in the library (in meters).
gdsii_hash¶
-
gdspy.
gdsii_hash
(filename, engine=None)¶ Calculate the a hash value for a GDSII file.
The hash is generated based only on the contents of the cells in the GDSII library, ignoring any timestamp records present in the file structure.
Parameters: - filename (string) – Full path to the GDSII file.
- engine (hashlib-like engine) – The engine that executes the hashing algorithm. It must provide
the methods
update
andhexdigest
as defined in the hashlib module. IfNone
, the defaulthashlib.sha1()
is used.
Returns: out – The hash corresponding to the library contents in hex format.
Return type: string