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:
  • name (string) – The name of this cell.
  • elements (list) – List of cell elements (PolygonSet, CellReference, CellArray).
  • labels (list) – List of Label.
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 by gdspy.
  • deep_copy (bool) – If False, the new cell will contain only references to the existing elements. If True, 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 and CellArray 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

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 not None, 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 not None, defines from how many reference levels to retrieve polygons. References below this level will result in a bounding box. If by_spec is True 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 is True).

Return type:

list of array-like[N][2] or dictionary

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 to True, 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 to True, 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 not None, 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 not None, defines from how many reference levels to retrieve polygons. References below this level will result in a bounding box. If by_spec is True 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 is True).

Return type:

list of array-like[N][2] or dictionary

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

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 not None, 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 not None, defines from how many reference levels to retrieve polygons. References below this level will result in a bounding box. If by_spec is True 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 is True).

Return type:

list of array-like[N][2] or dictionary

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

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 of Cell) – 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

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 set unit=1.0e-6 (1 um) and precision=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 set unit=1.0e-6 (1 um) and precision=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 set unit=1.0e-6 (1 um) and precision=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 and hexdigest as defined in the hashlib module. If None, the default hashlib.sha1() is used.
Returns:

out – The hash corresponding to the library contents in hex format.

Return type:

string

Attributes

gdspy.current_library = <gdspy.GdsLibrary object>

Current GdsLibrary instance for automatic creation of GDSII files.

This variable can be freely overwritten by the user with a new instance of GdsLibrary.