gdsfactory¶

You can import gdsfactory.as gf.

functions: - import_gds(): returns a Component from a GDS

classes:

- Component
- Port
- TECH

modules:

- c: components
- routing

gdsfactory¶

You can import gdsfactory.as gf.

functions: - import_gds(): returns a Component from a GDS

classes:

- Component
- Port
- TECH

modules:

- c: components
- routing

gdsfactory.add_labels¶

Add Label to each component port.

get_input_label_text_dash¶

def get_input_label_text_dash(port: Port,
                              gc: ComponentReference | Component,
                              gc_index: int | None = None,
                              component_name: str | None = None,
                              prefix: str = "",
                              suffix: str = "") -> str

Returns text with GratingName-ComponentName-PortName.

get_input_label_text_dash_loopback¶

def get_input_label_text_dash_loopback(port: Port,
                                       gc: ComponentReference | Component,
                                       gc_index: int | None = None,
                                       component_name: str | None = None,
                                       prefix: str = "") -> str

Returns text with GratingName-ComponentName-Loopback.

get_input_label_text¶

def get_input_label_text(port: Port,
                         gc: ComponentReference | Component,
                         gc_index: int | None = None,
                         component_name: str | None = None,
                         component_prefix: str = "",
                         prefix: str = "opt",
                         suffix: str = "") -> str

Returns text string for an optical port based on grating coupler.

{label_prefix}{polarization}{wavelength_nm}_({prefix}{component_name})

Arguments:

• port - to label.
• gc - grating coupler component or reference.
• gc_index - grating_coupler index, which grating_coupler we are labelling.
• component_name - optional name.
• component_prefix - component prefix.
• prefix - prefix to add to the label.

get_input_label¶

def get_input_label(
        port: Port,
        gc: ComponentReference,
        gc_index: int | None = None,
        gc_port_name: str = "o1",
        layer_label: LayerSpec = "LABEL",
        component_name: str | None = None,
        get_input_label_text_function=get_input_label_text) -> Label

Returns a label with component info for a given grating coupler.

Test equipment to extract grating coupler coordinates and match it to the component.

Arguments:

• port - port to label.
• gc - grating coupler reference.
• gc_index - grating coupler index.
• gc_port_name - name of grating coupler port.
• layer_label - layer of the label.
• component_name - for the label.
• get_input_label_text_function - function to get input label.

get_input_label_electrical¶

def get_input_label_electrical(port: Port,
                               gc_index: int = 0,
                               component_name: str | None = None,
                               layer_label: LayerSpec = "LABEL",
                               gc: ComponentReference | None = None) -> Label

Returns a label to test component info for a given electrical port.

This is the label used by T&M to extract grating coupler coordinates and match it to the component.

Arguments:

• port - to label.
• gc_index - index of the label.
• component_name - Optional component_name.
• layer_label - for label.
• gc - ignored.

add_labels¶

def add_labels(component: Component,
               get_label_function: Callable = get_input_label_electrical,
               layer_label: LayerSpec = "LABEL",
               gc: Component | None = None,
               **kwargs) -> Component

Returns component with labels on ports.

Arguments:

• component - to add labels to.

• get_label_function - function to get label.

• layer_label - layer_label.

• gc - Optional grating coupler.

  keyword Args:

• layer - port GDS layer.

• prefix - with in port name.

• suffix - select ports with port name suffix.

• orientation - in degrees.

• width - for ports to add label.

• layers_excluded - List of layers to exclude.

• port_type - optical, electrical, ...

• clockwise - if True, sort ports clockwise, False: counter-clockwise.

Returns:

original component with labels.

add_siepic_labels¶

def add_siepic_labels(component: Component,
                      model: str = "auto",
                      library: str = "auto",
                      label_layer: LayerSpec = "DEVREC",
                      spice_params: dict | list | str | None = None,
                      label_spacing: float = 0.2) -> Component

Adds labels and returns the same component.

Arguments:

• component - component.
• model - Lumerical Interconnect model. ‘auto’ attempts to extract this from the cross_section.
• library - Lumerical Interconnect library. ‘auto’ attempts to extract this from the cross_section.
• label_layer - layer for writing SiEPIC labels.
• spice_params - spice parameters (in microns). Either pass in a dict with parameter, value pairs, or pass a list of values to extract from component info.
• label_spacing - separation distance between labels in um.

add_labels_to_ports¶

def add_labels_to_ports(component: Component,
                        label_layer: LayerSpec = "LABEL",
                        port_type: str | None = None,
                        **kwargs) -> Component

Add labels to component ports.

Arguments:

• component - to add labels.

• label_layer - layer spec for the label.

• port_type - to select ports.

  keyword Args:

• layer - select ports with GDS layer.

• prefix - select ports with prefix in port name.

• suffix - select ports with port name suffix.

• orientation - select ports with orientation in degrees.

• width - select ports with port width.

• layers_excluded - List of layers to exclude.

• port_type - select ports with port_type (optical, electrical, vertical_te).

• clockwise - if True, sort ports clockwise, False: counter-clockwise.

add_labels_to_ports_x_y¶

def add_labels_to_ports_x_y(component: Component,
                            label_layer: LayerSpec = "LABEL",
                            port_type: str | None = None,
                            **kwargs) -> Component

Add labels to component ports. Prepends -x-y coordinates

Arguments:

• component - to add labels.

• label_layer - layer spec for the label.

• port_type - to select ports.

  keyword Args:

• layer - select ports with GDS layer.

• prefix - select ports with prefix in port name.

• suffix - select ports with port name suffix.

• orientation - select ports with orientation in degrees.

• width - select ports with port width.

• layers_excluded - List of layers to exclude.

• port_type - select ports with port_type (optical, electrical, vertical_te).

• clockwise - if True, sort ports clockwise, False: counter-clockwise.

get_labels¶

def get_labels(component: ComponentOrReference,
               get_label_function: Callable = get_input_label_electrical,
               layer_label: LayerSpec = "LABEL",
               gc: Component | None = None,
               component_name: str | None = None,
               **kwargs) -> list[Label]

Returns component labels on ports.

Arguments:

• component - to add labels to.

• get_label_function - function to get label.

• layer_label - layer_label.

• gc - Optional grating coupler.

• component_name - optional component name.

  keyword Args:

• layer - port GDS layer.

• prefix - look for prefix in port name.

• suffix - select ports with port name suffix.

• orientation - in degrees.

• width - for ports to add label.

• layers_excluded - List of layers to exclude.

• port_type - optical, electrical, ...

• clockwise - if True, sort ports clockwise, False: counter-clockwise.

Returns:

list of component labels.

gdsfactory.path¶

You can define a path with a list of points combined with a cross-section.

A path can be extruded using any CrossSection returning a Component The CrossSection defines the layer numbers, widths and offsets

Adapted from PHIDL https://github.com/amccaugh/phidl/ by Adam McCaughan

Path Objects¶

class Path(_GeometryHelper)

Path object for smooth Paths. You can extrude a Path with a CrossSection to create a Component.

Arguments:

• path - array-like[N][2], Path, or list of Paths. Points or Paths to append() initially.

__init__¶

def __init__(path=None) -> None

Creates an empty path.

__repr__¶

def __repr__() -> str

Returns path points.

__len__¶

def __len__() -> int

Returns path points.

__iadd__¶

def __iadd__(path_or_points) -> Path

Adds points to current path.

__add__¶

def __add__(path) -> Path

Returns new path concatenating current and new path.

bbox¶

@property
def bbox()

Returns the bounding box of the Path.

append¶

def append(path)

Attach Path to the end of this Path.

The input path automatically rotates and translates such that it continues smoothly from the previous segment.

Arguments:

path : Path, array-like[N][2], or list of Paths The input path that will be appended.

offset¶

def offset(offset: float | Callable[..., float] = 0)

Offsets Path so that it follows the Path centerline plus an offset.

The offset can either be a fixed value, or a function of the form my_offset(t) where t goes from 0->1

Arguments:

• offset - int or float, callable. Magnitude of the offset

move¶

def move(origin=(0, 0), destination=None, axis=None)

Moves the Path from the origin point to the destination.

Both origin and destination can be 1x2 array-like or a Port.

Arguments:

origin : array-like[2], Port Origin point of the move. destination : array-like[2], Port Destination point of the move. axis : {‘x’, ‘y’} Direction of move.

rotate¶

def rotate(angle: float = 45, center: Float2 | None = (0, 0))

Rotates all Polygons in the Component around the specified center point.

If no center point specified will rotate around (0,0).

Arguments:

• angle - Angle to rotate the Component in degrees.
• center - array-like[2] or None. component of the Component.

mirror¶

def mirror(p1: Float2 = (0, 1), p2: Float2 = (0, 0))

Mirrors the Path across the line formed between the two specified points.

points may be input as either single points [1,2] or array-like[N][2], and will return in kind.

Arguments:

• p1 - First point of the line.
• p2 - Second point of the line.

length¶

def length() -> float

Return cumulative length.

curvature¶

def curvature()

Calculates Path curvature.

The curvature is numerically computed so areas where the curvature jumps instantaneously (such as between an arc and a straight segment) will be slightly interpolated, and sudden changes in point density along the curve can cause discontinuities.

Returns:

s : array-like[N] The arc-length of the Path K : array-like[N] The curvature of the Path

hash_geometry¶

def hash_geometry(precision: float = 1e-4) -> str

Computes an SHA1 hash of the points in the Path and the start_angle and end_angle.

Arguments:

• precision - Rounding precision for the the objects in the Component. For instance, a precision of 1e-2 will round a point at (0.124, 1.748) to (0.12, 1.75)

Returns:

str Hash result in the form of an SHA1 hex digest string.

.. code::

hash( hash(First layer information: [layer1, datatype1]), hash(Polygon 1 on layer 1 points: [(x1,y1),(x2,y2),(x3,y3)] ), hash(Polygon 2 on layer 1 points: [(x1,y1),(x2,y2),(x3,y3),(x4,y4)] ), hash(Polygon 3 on layer 1 points: [(x1,y1),(x2,y2),(x3,y3)] ), hash(Second layer information: [layer2, datatype2]), hash(Polygon 1 on layer 2 points: [(x1,y1),(x2,y2),(x3,y3),(x4,y4)] ), hash(Polygon 2 on layer 2 points: [(x1,y1),(x2,y2),(x3,y3)] ), )

__get_validators__¶

@classmethod
def __get_validators__(cls)

For pydantic.

plot¶

def plot() -> None

Plot path in matplotlib.

.. plot:: :include-source:

import gdsfactory as gf

p = gf.path.euler(radius=10)
p.plot()

extrude¶

def extrude(cross_section: CrossSectionSpec | None = None,
            layer: LayerSpec | None = None,
            width: float | None = None,
            widths: Float2 | None = None,
            simplify: float | None = None,
            shear_angle_start: float | None = None,
            shear_angle_end: float | None = None) -> Component

Returns Component by extruding a Path with a CrossSection.

A path can be extruded using any CrossSection returning a Component The CrossSection defines the layer numbers, widths and offsets.

Arguments:

• p - a path is a list of points (arc, straight, euler).

• cross_section - to extrude.

• layer - optional layer.

• width - optional width in um.

• widths - tuple of starting and end width for a linear taper.

• simplify - Tolerance value for the simplification algorithm. All points that can be removed without changing the resulting polygon by more than the value listed here will be removed.

• shear_angle_start - an optional angle to shear the starting face by (in degrees).

• shear_angle_end - an optional angle to shear the ending face by (in degrees).

  .. plot:: :include-source:

  import gdsfactory as gf

  p = gf.path.euler(radius=10) c = p.extrude(layer=(1, 0), width=0.5) c.plot()

copy¶

def copy()

Returns a copy of the Path.

transition_exponential¶

def transition_exponential(y1, y2, exp=0.5)

Returns the function for an exponential transition.

Arguments:

• y1 - start width in um.
• y2 - end width in um.
• exp - exponent.

transition_adiabatic¶

def transition_adiabatic(w1: float,
                         w2: float,
                         neff_w,
                         wavelength: float = 1.55,
                         alpha: float = 1,
                         max_length: float = 200,
                         num_points_ODE: int = 2000)

Returns the points for an optimal adiabatic transition for well-guided modes.

Arguments:

• w1 - start width in um.
• w2 - end width in um.
• neff_w - a callable that returns the effective index as a function of width By default, use a compact model of neff(y) for fundamental 1550 nm TE mode of 220nm-thick core with 3.45 index, fully clad with 1.44 index. Many coefficients are needed to capture the behaviour.
• wavelength - wavelength, in same units as widths
• alpha - parameter that scales the rate of width change
  • closer to 0 means longer and more adiabatic;
  • 1 is the intuitive limit beyond which higher order modes are excited;
  • [2] reports good performance up to 1.4 for fundamental TE in SOI (for multiple core thicknesses)
• max_length - maximum length in um.
• num_points_ODE - number of samplings points for the ODE solve.

References:

[1] Burns, W. K., et al. “Optical waveguide parabolic coupling horns.” Appl. Phys. Lett., vol. 30, no. 1, 1 Jan. 1977, pp. 28-30, doi:10.1063/1.89199. [2] Fu, Yunfei, et al. “Efficient adiabatic silicon-on-insulator waveguide taper.” Photonics Res., vol. 2, no. 3, 1 June 2014, pp. A41-A44, doi:10.1364/PRJ.2.000A41.

transition¶

def transition(cross_section1: CrossSection,
               cross_section2: CrossSection,
               width_type: WidthTypes = "sine",
               **kwargs) -> Transition

Returns a smoothly-transitioning between two CrossSections.

Only cross-sectional elements that have the name (as in X.add(..., name = ‘wg’) ) parameter specified in both input CrosSections will be created. Port names will be cloned from the input CrossSections in reverse.

Arguments:

• cross_section1 - First CrossSection.
• cross_section2 - Second CrossSection.
• width_type - sine or linear. Sets the type of width transition used if any widths are different between the two input CrossSections.

along_path¶

@cell
def along_path(p: Path, component: ComponentSpec, spacing: float,
               padding: float) -> Component

Returns Component containing many copies of component along p.

Places as many copies of component along each segment of p as possible under the given constraints. spacing is always followed precisely, but actual padding may exceed the provided value to place components evenly.

Arguments:

• p - Path to place components along.
• component - Component to repeat along the path. The unrotated version of this object should be oriented for placement on a horizontal line.
• spacing - distance between component placements.
• padding - minimum distance from the path start to the first component.

extrude¶

@cell
def extrude(p: Path,
            cross_section: CrossSectionSpec | None = None,
            layer: LayerSpec | None = None,
            width: float | None = None,
            widths: Float2 | None = None,
            simplify: float | None = None,
            shear_angle_start: float | None = None,
            shear_angle_end: float | None = None) -> Component

Returns Component extruding a Path with a cross_section.

A path can be extruded using any CrossSection returning a Component The CrossSection defines the layer numbers, widths and offsets

Arguments:

• p - a path is a list of points (arc, straight, euler).
• cross_section - to extrude.
• layer - optional layer to extrude.
• width - optional width to extrude.
• widths - tuple of starting and end width.
• simplify - Tolerance value for the simplification algorithm. All points that can be removed without changing the resulting. polygon by more than the value listed here will be removed.
• shear_angle_start - an optional angle to shear the starting face by (in degrees).
• shear_angle_end - an optional angle to shear the ending face by (in degrees).

arc¶

def arc(radius: float = 10.0,
        angle: float = 90,
        npoints: int | None = None,
        start_angle: float | None = -90) -> Path

Returns a radial arc.

Arguments:

• radius - minimum radius of curvature.

• angle - total angle of the curve.

• npoints - Number of points used per 360 degrees. Defaults to pdk.bend_points_distance.

• start_angle - initial angle of the curve for drawing, default -90 degrees.

  .. plot:: :include-source:

  import gdsfactory as gf

  p = gf.path.arc(radius=10, angle=45) p.plot()

euler¶

def euler(radius: float = 10,
          angle: float = 90,
          p: float = 0.5,
          use_eff: bool = False,
          npoints: int | None = None) -> Path

Returns an euler bend that adiabatically transitions from straight to curved.

radius is the minimum radius of curvature of the bend. However, if use_eff is set to True, radius corresponds to the effective radius of curvature (making the curve a drop-in replacement for an arc). If p < 1.0, will create a “partial euler” curve as described in Vogelbacher et. al. Vogelbacher et al. (2019)

Arguments:

• radius - minimum radius of curvature.

• angle - total angle of the curve.

• p - Proportion of the curve that is an Euler curve.

• use_eff - If False: radius is the minimum radius of curvature of the bend. If True: The curve will be scaled such that the endpoints match an arc. with parameters radius and angle.

• npoints - Number of points used per 360 degrees.

  .. plot:: :include-source:

  import gdsfactory as gf

  p = gf.path.euler(radius=10, angle=45, p=1, use_eff=True, npoints=720) p.plot()

straight¶

def straight(length: float = 10.0, npoints: int = 2) -> Path

Returns a straight path.

For transitions you should increase have at least 100 points

Arguments:

• length - of straight.
• npoints - number of points.

spiral_archimedean¶

def spiral_archimedean(min_bend_radius: float, separation: float,
                       number_of_loops: float, npoints: int) -> Path

Returns an Archimedean spiral.

Arguments:

• radius - Inner radius of the spiral.

• separation - Separation between the loops in um.

• number_of_loops - number of loops.

• npoints - number of Points.

  .. plot:: :include-source:

  import gdsfactory as gf

  p = gf.path.spiral_archimedean(min_bend_radius=5, separation=2, number_of_loops=3, npoints=200) p.plot()

smooth¶

def smooth(points: Coordinates,
           radius: float = 4.0,
           bend: PathFactory = euler,
           **kwargs) -> Path

Returns a smooth Path from a series of waypoints.

Arguments:

• points - array-like[N][2] List of waypoints for the path to follow.

• radius - radius of curvature, passed to bend.

• bend - bend function that returns a path that round corners.

• npoints - Number of points used per 360 degrees for the bend.

• kwargs - Extra keyword arguments that will be passed to bend.

  .. plot:: :include-source:

  import gdsfactory as gf

  p = gf.path.smooth(([0, 0], [0, 10], [10, 10])) p.plot()

gdsfactory.pdk¶

PDK stores layers, cross_sections, cell functions ...

evanescent_coupler_sample¶

def evanescent_coupler_sample() -> None

Evanescent coupler example.

Arguments:

• coupler_length - length of coupling (min: 0.0, max: 200.0, um).

extract_args_from_docstring¶

def extract_args_from_docstring(docstring: str) -> dict[str, Any] | None

This function extracts settings from a function’s docstring for uPDK format.

Arguments:

• docstring - The function from which to extract YAML in the docstring.

Returns:

• settings dict - The extracted YAML data as a dictionary.

GdsWriteSettings Objects¶

class GdsWriteSettings(BaseModel)

Settings to use when writing to GDS.

CellDecoratorSettings Objects¶

class CellDecoratorSettings(BaseModel)

Settings for cell_without_validator decorator function in gdsfactory.cell.

Pdk Objects¶

class Pdk(BaseModel)

Store layers, cross_sections, cell functions, simulation_settings ...

only one Pdk can be active at a given time.

Arguments:

• name - PDK name.
• cross_sections - dict of cross_sections factories.
• cells - dict of parametric cells that return Components.
• symbols - dict of symbols names to functions. default_symbol_factory:
• base_pdk - a pdk to copy from and extend.
• default_decorator - decorate all cells, if not otherwise defined on the cell.
• layers - maps name to gdslayer/datatype. For example dict(si=(1, 0), sin=(34, 0)).
• layer_stack - maps name to layer numbers, thickness, zmin, sidewall_angle. if can also contain material properties (refractive index, nonlinear coefficient, sheet resistance ...).
• layer_views - includes layer name to color, opacity and pattern.
• layer_transitions - transitions between different cross_sections.
• sparameters_path - to store Sparameters simulations.
• modes_path - to store Sparameters simulations.
• interconnect_cml_path - path to interconnect CML (optional).
• warn_off_grid_ports - raises warning when extruding paths with offgrid ports.
• constants - dict of constants for the PDK.
• materials_index - material spec names to material spec, which can be:
• string - material name.
• float - refractive index. float, float: refractive index real and imaginary part.
• function - function of wavelength.
• routing_strategies - functions enabled to route.
• gds_write_settings - to write GDSII files.
• oasis_settings - to write OASIS files.
• cell_decorator_settings - settings for cell_without_validator decorator function in gdsfactory.cell.
• bend_points_distance - default points distance for bends in um.

grid_size¶

@property
def grid_size()

The minimum unit resolvable on the layout grid, relative to the unit.

validate_layers¶

def validate_layers(layers_required: list[Layer] | None = None)

Raises ValueError if layers_required are not in Pdk.

activate¶

def activate() -> None

Set current pdk to the active pdk (if not already active).

register_cells¶

def register_cells(**kwargs) -> None

Register cell factories.

register_cross_sections¶

def register_cross_sections(**kwargs) -> None

Register cross_sections factories.

register_cells_yaml¶

def register_cells_yaml(dirpath: PathType | None = None,
                        update: bool = False,
                        **kwargs) -> None

Load *.pic.yml YAML files and register them as cells.

Arguments:

• dirpath - directory to recursive search for YAML cells.
• update - does not raise ValueError if cell already registered.

Arguments:

• cell_name - cell function. To update cells dict.

remove_cell¶

def remove_cell(name: str)

Removes cell from a PDK.

get_cell¶

def get_cell(cell: CellSpec, **kwargs) -> ComponentFactory

Returns ComponentFactory from a cell spec.

get_component¶

def get_component(component: ComponentSpec, **kwargs) -> Component

Returns component from a component spec.

get_symbol¶

def get_symbol(component: ComponentSpec, **kwargs) -> Component

Returns a component’s symbol from a component spec.

get_cross_section¶

def get_cross_section(cross_section: CrossSectionSpec,
                      **kwargs) -> CrossSection | Transition

Returns cross_section from a cross_section spec.

get_layer¶

def get_layer(layer: LayerSpec) -> Layer

Returns layer from a layer spec.

to_updk¶

def to_updk() -> str

Export to uPDK YAML definition.

get_constant¶

def get_constant(constant_name: Any) -> Any

If constant_name is a string returns a the value from the dict.

get_routing_strategies¶

def get_routing_strategies() -> dict[str, Callable]

Gets a dictionary of named routing functions available to the PDK, if defined, or gdsfactory defaults otherwise.

gdsfactory.serialization¶

Serialize component settings into YAML or strings.

DEFAULT_SERIALIZATION_MAX_DIGITS¶

By default, the maximum number of digits retained when serializing float-like arrays

clean_value_json¶

def clean_value_json(
        value: Any) -> str | int | float | dict | list | bool | None

Return JSON serializable object.

clean_value_name¶

def clean_value_name(value: Any) -> str

Returns a string representation of an object.

gdsfactory.cell¶

Cell decorator for functions that return a Component.

clear_cache¶

def clear_cache() -> None

Clears Component CACHE.

Settings Objects¶

class Settings(BaseModel)

info¶

derived properties (length, resistance)

cell_without_validator¶

def cell_without_validator(func: _F) -> _F

Decorator for Component functions.

Similar to cell decorator, this one does not validate_arguments using type annotations

I recommend using cell instead

cell¶

def cell(func: _F) -> _F

Decorator for Component functions.

Wraps cell_without_validator Validates type annotations with pydantic.

Implements a cache so that if a component has already been build it will return the component from the cache directly. This avoids creating two exact Components that have the same name.

When decorate your functions with cell you get:

• cache: avoids creating duplicated Components.
• name: names Components uniquely name based on parameters.
• metadata: adds Component.metadata with default, changed and full Args.

Note the cell decorator does not take any arguments. Keyword Args are applied the resulting Component.

Arguments:

• autoname bool - True renames Component based on args and kwargs. True by default.

• name str - Optional name.

• cache bool - returns Component from the CACHE if it already exists. Avoids having duplicated cells with the same name. If False overrides CACHE creates a new Component.

• flatten bool - False by default. True flattens component hierarchy.

• info - updates Component.info dict.

• prefix str - name_prefix, defaults to function name.

• max_name_length int - truncates name beyond some characters with a hash.

• decorator Callable - function to apply to Component.

  A decorator is a function that runs over a function, so when you do.

  .. code::

  import gdsfactory as gf

  gf.cell def mzi_with_bend(): c = gf.Component() mzi = c << gf.components.mzi() bend = c << gf.components.bend_euler() return c

  it’s equivalent to

  .. code::

  def mzi_with_bend(): c = gf.Component() mzi = c << gf.components.mzi() bend = c << gf.components.bend_euler(radius=radius) return c

  mzi_with_bend_decorated = gf.cell(mzi_with_bend)

declarative_cell¶

def declarative_cell(cls: type[Any]) -> Callable[..., Component]

Decorator to turn a dataclass into a cell. Work in progress.

wg¶

@cell
def wg(length: int = 3, layer: tuple[int, int] = (1, 0)) -> Component

Dummy component for testing.

wg2¶

@cell
def wg2(wg1=wg)

Dummy component for testing.

demo¶

@cell
def demo(length: int = 3, wg_width: float = 0.5) -> Component

Demo Dummy cell.

gdsfactory.component¶

Component is a canvas for geometry.

Adapted from PHIDL https://github.com/amccaugh/phidl/ by Adam McCaughan

valid_plotters¶

qt and holoviews are deprecated

Component Objects¶

class Component(_GeometryHelper)

A Component is an empty canvas where you add polygons, references and ports (to connect to other components).

• stores settings that you use to build the component
• stores info that you want to use
• can return ports by type (optical, electrical ...)
• can return netlist for circuit simulation
• can write to GDS, OASIS
• can show in KLayout, matplotlib, 3D
• can return copy, mirror, flattened (no references)

Arguments:

• name - component_name. Use cell decorator for auto-naming.

• with_uuid - adds unique identifier.

  Properties:

• info - dictionary that includes

  • derived properties
  • external metadata (test_protocol, docs, ...)
  • simulation_settings
  • function_name
  • name: for the component

  settings:

• full - full settings passed to the function to create component.

• changed - changed settings.

• default - default component settings.

• child - dict info from the children, if any.

__init__¶

def __init__(name: str = "Unnamed", with_uuid: bool = False) -> None

Initialize the Component object.

__iter__¶

def __iter__()

You can iterate over polygons, paths, labels and references.

get_polygon_bbox¶

def get_polygon_bbox(default: float = 0.0,
                     top: float | None = None,
                     bottom: float | None = None,
                     right: float | None = None,
                     left: float | None = None) -> shapely.Polygon

Returns shapely Polygon with bounding box.

Arguments:

• default - default padding in um.
• top - north padding in um.
• bottom - south padding in um.
• right - east padding in um.
• left - west padding in um.

get_polygons¶

def get_polygons(
    by_spec: bool | tuple[int, int] = False,
    depth: int | None = None,
    include_paths: bool = True,
    as_array: bool = True,
    as_shapely: bool = False,
    as_shapely_merged: bool = False
) -> list[Polygon] | dict[tuple[int, int], list[Polygon]]

Return a list of polygons in this cell.

Arguments:

• by_spec - bool or layer If True, the return value is a dictionary with the polygons of each individual pair (layer, datatype), which are used as keys. If set to a tuple of (layer, datatype), only polygons with that specification are returned.

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

• include_paths - If True, polygonal representation of paths are also included in the result.

• as_array - when as_array=false, return the Polygon objects instead. polygon objects have more information (especially when by_spec=False) and are faster to retrieve.

• as_shapely - returns shapely polygons.

• as_shapely_merged - returns a shapely polygonize.

  Returns

• out - list of array-like[N][2] or dictionary List containing the coordinates of the vertices of each polygon, or dictionary with with the list of polygons (if by_spec is True).

Notes:

Instances of FlexPath and RobustPath are also included in the result by computing their polygonal boundary.

get_dependencies¶

def get_dependencies(recursive: bool = False) -> list[Component]

Return a list of Components referenced by this Component.

Arguments:

• recursive - If True returns dependencies recursively.

__getitem__¶

def __getitem__(key) -> Port

Access reference ports.

__lshift__¶

def __lshift__(element) -> ComponentReference

Convenience operator equivalent to add_ref().

unlock¶

def unlock() -> None

Only do this if you know what you are doing.

lock¶

def lock() -> None

Makes sure components can’t add new elements or move existing ones.

Components lock automatically when going into the CACHE to ensure one component does not change others

__setitem__¶

def __setitem__(key, element)

Allow adding polygons and cell references.

like D[‘arc3’] = pg.arc()

Arguments:

• key - Alias name.
• element - Object that will be accessible by alias name.

__get_validators__¶

@classmethod
def __get_validators__(cls)

Get validators for the Component object.

validate¶

@classmethod
def validate(cls, v, _info)

Pydantic assumes component is valid if the following are true.

• name characters < pdk.cell_decorator_settings.max_name_length
• is not empty (has references or polygons)

add_label¶

def add_label(text: str = "hello",
              position: tuple[float, float] = (0.0, 0.0),
              magnification: float = 1.0,
              rotation: float = 0,
              anchor: str = "o",
              layer: LayerSpec = "TEXT",
              x_reflection: bool = False) -> Label

Adds Label to the Component.

Arguments:

• text - Label text.
• position - x-, y-coordinates of the Label location.
• magnification - Magnification factor for the Label text.
• rotation - Angle rotation of the Label text.
• anchor - {‘n’, ‘e’, ‘s’, ‘w’, ‘o’, ‘ne’, ‘nw’, ...} Position of the anchor relative to the text.
• layer - Specific layer(s) to put Label on.
• x_reflection - True reflects across the horizontal axis before rotation.

bbox¶

@property
def bbox()

Returns the bounding box of the ComponentReference.

ports_layer¶

@property
def ports_layer() -> dict[str, str]

Returns a mapping from layer0_layer1_E0: portName.

port_by_orientation_cw¶

def port_by_orientation_cw(key: str, **kwargs)

Returns port by indexing them clockwise.

port_by_orientation_ccw¶

def port_by_orientation_ccw(key: str, **kwargs)

Returns port by indexing them clockwise.

get_ports_xsize¶

def get_ports_xsize(**kwargs) -> float

Returns xdistance from east to west ports.

Arguments:

• layer - port GDS layer.
• prefix - with in port name.
• orientation - in degrees.
• width - port width.
• layers_excluded - List of layers to exclude.
• port_type - optical, electrical, ...

get_ports_ysize¶

def get_ports_ysize(**kwargs) -> float

Returns ydistance from east to west ports.

Arguments:

• layer - port GDS layer.
• prefix - with in port name.
• orientation - in degrees.
• width - port width (um).
• layers_excluded - List of layers to exclude.
• port_type - optical, electrical, ...

plot_netlist¶

def plot_netlist(with_labels: bool = True,
                 font_weight: str = "normal",
                 **kwargs)

Plots a netlist graph with networkx.

Arguments:

• with_labels - add label to each node.
• font_weight - normal, bold.
• **kwargs - keyword arguments for the get_netlist function

plot_netlist_flat¶

def plot_netlist_flat(with_labels: bool = True,
                      font_weight: str = "normal",
                      **kwargs)

Plots a netlist graph with networkx.

Arguments:

• flat - if true, will plot the flat netlist
• with_labels - add label to each node.
• font_weight - normal, bold.
• **kwargs - keyword arguments for the get_netlist function

write_netlist¶

def write_netlist(filepath: str) -> None

Write netlist in YAML.

write_netlist_dot¶

def write_netlist_dot(filepath: str | None = None) -> None

Write netlist graph in DOT format.

get_netlist¶

def get_netlist(**kwargs) -> dict[str, Any]

From Component returns instances, connections and placements dict.

Arguments:

• component - to extract netlist.
• full_settings - True returns all, false changed settings.
• tolerance - tolerance in nm to consider two ports connected.
• exclude_port_types - optional list of port types to exclude from netlisting.
• get_instance_name - function to get instance name.
• allow_multiple - False to raise an error if more than two ports share the same connection. if True, will return key: [value] pairs with [value] a list of all connected instances.

Returns:

Netlist dict (instances, connections, placements, ports)

• instances - Dict of instance name and settings.
• connections - Dict of Instance1Name,portName: Instance2Name,portName.
• placements - Dict of instance names and placements (x, y, rotation).
• ports - Dict portName: ComponentName,port.
• name - name of component.

get_netlist_recursive¶

def get_netlist_recursive(**kwargs) -> dict[str, DictConfig]

Returns recursive netlist for a component and subcomponents.

Arguments:

• component - to extract netlist.
• component_suffix - suffix to append to each component name. useful if to save and reload a back-annotated netlist.
• get_netlist_func - function to extract individual netlists.
• full_settings - True returns all, false changed settings.
• tolerance - tolerance in nm to consider two ports connected.
• exclude_port_types - optional list of port types to exclude from netlisting.
• get_instance_name - function to get instance name.
• allow_multiple - False to raise an error if more than two ports share the same connection. if True, will return key: [value] pairs with [value] a list of all connected instances.

Returns:

Dictionary of netlists, keyed by the name of each component.

get_netlist_flat¶

def get_netlist_flat(**kwargs) -> dict[str, DictConfig]

Returns a netlist where all subinstances are exposed and independently named.

Arguments:

• component - to extract netlist.
• component_suffix - suffix to append to each component name. useful if to save and reload a back-annotated netlist.
• get_netlist_func - function to extract individual netlists.
• full_settings - True returns all, false changed settings.
• tolerance - tolerance in nm to consider two ports connected.
• exclude_port_types - optional list of port types to exclude from netlisting.
• get_instance_name - function to get instance name.
• allow_multiple - False to raise an error if more than two ports share the same connection. if True, will return key: [value] pairs with [value] a list of all connected instances.

Returns:

Dictionary of netlists, keyed by the name of each component.

assert_ports_on_grid¶

def assert_ports_on_grid(nm: int = 1) -> None

Asserts that all ports are on grid.

get_ports¶

def get_ports(depth=None)

Returns copies of all the ports of the Component, rotated and translated so that they’re in their top-level position.

The Ports returned are copies of the originals, but each copy has the same uid as the original so that they can be traced back to the original if needed.

Arguments:

depth : int or None If not None, defines from how many reference levels to retrieve Ports from.

Returns:

port_list : list of Port List of all Ports in the Component.

get_ports_dict¶

def get_ports_dict(**kwargs) -> dict[str, Port]

Returns a dict of ports.

Arguments:

• layer - port GDS layer.
• prefix - select ports with prefix in port name.
• suffix - select ports with port name suffix.
• orientation - select ports with orientation in degrees.
• width - select ports with port width.
• layers_excluded - List of layers to exclude.
• port_type - select ports with port_type (optical, electrical, vertical_te).
• clockwise - if True, sort ports clockwise, False: counter-clockwise.

get_ports_list¶

def get_ports_list(**kwargs) -> list[Port]

Returns list of ports.

Arguments:

• layer - select ports with GDS layer.
• prefix - select ports with prefix in port name.
• suffix - select ports with port name suffix.
• orientation - select ports with orientation in degrees.
• orientation - select ports with orientation in degrees.
• width - select ports with port width.
• layers_excluded - List of layers to exclude.
• port_type - select ports with port_type (optical, electrical, vertical_te).
• clockwise - if True, sort ports clockwise, False: counter-clockwise.

ref¶

def ref(position: Coordinate = (0, 0),
        port_id: str | None = None,
        rotation: float = 0,
        h_mirror: bool = False,
        v_mirror: bool = False) -> ComponentReference

Returns Component reference.

Arguments:

• position - x, y position.
• port_id - name of the port.
• rotation - in degrees.
• h_mirror - horizontal mirror using y axis (x, 1) (1, 0). This is the most common mirror.
• v_mirror - vertical mirror using x axis (1, y) (0, y).

ref_center¶

def ref_center(position=(0, 0))

Returns a reference of the component centered at (x=0, y=0).

__repr__¶

def __repr__() -> str

Return a string representation of the object.

pprint¶

def pprint() -> None

Prints component info.

pprint_ports¶

def pprint_ports() -> None

Prints ports in a rich table.

metadata_child¶

@property
def metadata_child() -> dict

Returns metadata from child if any, Otherwise returns component own.

metadata Great to access the children metadata at the bottom of the hierarchy.

add_port¶

def add_port(name: str | object | None = None,
             center: tuple[float, float] | None = None,
             width: float | None = None,
             orientation: float | None = None,
             port: Port | None = None,
             layer: LayerSpec | None = None,
             port_type: str | None = None,
             cross_section: CrossSectionSpec | None = None,
             shear_angle: float | None = None) -> Port

Add port to component.

You can copy an existing port like add_port(port = existing_port) or create a new port add_port(myname, mycenter, mywidth, myorientation). You can also copy an existing port with a new name add_port(port = existing_port, name = new_name)

Arguments:

• name - port name.
• center - x, y.
• width - in um.
• orientation - in deg.
• port - optional port.
• layer - port layer.
• port_type - optical, electrical, vertical_dc, vertical_te, vertical_tm. Defaults to optical.
• cross_section - port cross_section.
• shear_angle - an optional angle to shear port face in degrees.

add_ports¶

def add_ports(ports: Iterable[Port] | dict[str, Port],
              prefix: str = "",
              suffix: str = "",
              **kwargs) -> None

Add a list or dict of ports.

you can include a prefix to add to the new port names to avoid name conflicts.

Arguments:

• ports - list or dict of ports.
• prefix - to prepend to each port name.
• suffix - to append to each port name.

remove_layers¶

def remove_layers(layers: list[LayerSpec],
                  include_labels: bool = True,
                  invert_selection: bool = False,
                  recursive: bool = True) -> Component

Remove a list of layers and returns the same Component.

Arguments:

• layers - list of layers to remove.
• include_labels - remove labels on those layers.
• invert_selection - removes all layers except layers specified.
• recursive - operate on the cells included in this cell.

extract¶

def extract(layers: list[tuple[int, int] | str]) -> Component

Extract polygons from a Component and returns a new Component.

add_polygon¶

def add_polygon(
        points,
        layer: str | int | tuple[int, int] | np.nan = np.nan) -> Polygon

Adds a Polygon to the Component.

Arguments:

• points - Coordinates of the vertices of the Polygon.
• layer - layer spec to add polygon on.

add_ref_container¶

def add_ref_container(component: Component) -> ComponentReference

Add reference, ports and copy_child_info.

copy_child_info¶

def copy_child_info(component: Component) -> None

Copy and settings info from child component into parent.

Parent components can access child cells settings.

size_info¶

@property
def size_info() -> SizeInfo

Size info of the component.

is_unlocked¶

def is_unlocked() -> None

Raises error if Component is locked.

add¶

def add(element) -> None

Add a new element or list of elements to this Component.

Arguments:

• element - Polygon, ComponentReference or iterable The element or iterable of elements to be inserted in this cell.

Raises:

• MutabilityError - if component is locked.

add_array¶

def add_array(component: Component,
              columns: int = 2,
              rows: int = 2,
              spacing: tuple[float, float] = (100, 100),
              alias: str | None = None) -> ComponentReference

Creates a ComponentReference reference to a Component.

Arguments:

• component - The referenced component.

• columns - Number of columns in the array.

• rows - Number of rows in the array.

• spacing - array-like[2] of int or float. Distance between adjacent columns and adjacent rows.

• alias - str or None. Alias of the referenced Component.

  Returns

• a - ComponentReference containing references to the Component.

distribute¶

def distribute(elements="all",
               direction="x",
               spacing=100,
               separation=True,
               edge="center")

Distributes the specified elements in the Component.

Arguments:

elements : array-like of objects or ‘all’ Elements to distribute. direction : {‘x’, ‘y’} Direction of distribution; either a line in the x-direction or y-direction. spacing : int or float Distance between elements. separation : bool If True, guarantees elements are separated with a fixed spacing between; if False, elements are spaced evenly along a grid. edge : {‘x’, ‘xmin’, ‘xmax’, ‘y’, ‘ymin’, ‘ymax’} Which edge to perform the distribution along (unused if separation == True)

align¶

def align(elements="all", alignment="ymax")

Align elements in the Component.

Arguments:

elements : array-like of objects, or ‘all’ Elements in the Component to align. alignment : {‘x’, ‘y’, ‘xmin’, ‘xmax’, ‘ymin’, ‘ymax’} Which edge to align along (e.g. ‘ymax’ will move the elements such that all of their topmost points are aligned).

flatten¶

def flatten(single_layer: LayerSpec | None = None)

Returns a flattened copy of the component.

Flattens the hierarchy of the Component such that there are no longer any references to other Components. All polygons and labels from underlying references are copied and placed in the top-level Component. If single_layer is specified, all polygons are moved to that layer.

Arguments:

• single_layer - move all polygons are moved to the specified (optional).

flatten_reference¶

def flatten_reference(ref: ComponentReference) -> None

From existing cell replaces reference with a flatten reference which has the transformations already applied.

Transformed reference keeps the original name.

Arguments:

• ref - the reference to flatten into a new cell.

flatten_invalid_refs¶

def flatten_invalid_refs(grid_size: float | None = None,
                         updated_components=None,
                         traversed_components=None) -> Component

Returns new component with flattened references.

add_ref¶

def add_ref(component: Component,
            alias: str | None = None,
            **kwargs) -> ComponentReference

Add ComponentReference to the current Component.

Arguments:

• component - Component.
• alias - named_references.

Arguments:

• columns - Number of columns in the array.
• rows - Number of rows in the array.
• spacing - Distances between adjacent columns and adjacent rows.
• origin - array-like[2] of int or float Position where the cell is inserted. rotation : int or float Angle of rotation of the reference (in degrees). magnification : int or float Magnification factor for the reference. x_reflection : bool If True, the reference is reflected parallel to the x direction before being rotated. name : str (optional) A name for the reference (if provided).

layers¶

@property
def layers() -> set[tuple[int, int]]

Returns a set of the Layers in the Component.

get_layers¶

def get_layers() -> set[tuple[int, int]]

Return a set of (layer, datatype).

.. code ::

import gdsfactory as gf
gf.components.straight().get_layers() == {(1, 0), (111, 0)}

get_layer_names¶

def get_layer_names() -> list[tuple[int, int]]

Return layer names used in the design.

.. code ::

import gdsfactory as gf
gf.components.straight().get_names() == ['WG']

_repr_html_¶

def _repr_html_()

Show geometry in KLayout and in matplotlib for Jupyter Notebooks.

add_pins_triangle¶

def add_pins_triangle(port_marker_layer: Layer = (1, 10),
                      layer_label: Layer = (1, 10),
                      make_copy: bool = True) -> Component

Returns component with triangular pins.

plot_widget¶

def plot_widget(show_ports: bool = True,
                port_marker_layer: Layer = (1, 10)) -> None

Returns ipython widget for klayout visualization.

Arguments:

• show_ports - shows component with port markers and labels.
• port_marker_layer - for the ports.

plot_klayout¶

def plot_klayout(show_ports: bool = True,
                 port_marker_layer: Layer = (1, 10),
                 show_labels: bool = False)

Returns klayout image.

If it fails to import klayout defaults to matplotlib.

Arguments:

• show_ports - shows component with port markers and labels.
• port_marker_layer - for the ports.
• show_labels - shows labels.

plot_kweb¶

def plot_kweb()

Shows current gds in kweb.

plot_matplotlib¶

def plot_matplotlib(**kwargs) -> None

Plot component using matplotlib.

Arguments:

• show_ports - Sets whether ports are drawn.
• show_subports - Sets whether subports (ports that belong to references) are drawn.
• label_aliases - Sets whether aliases are labeled with a text name.
• new_window - If True, each call to quickplot() will generate a separate window.
• blocking - If True, calling quickplot() will pause execution of (“block”) the remainder of the python code until the quickplot() window is closed. If False, the window will be opened and code will continue to run.
• zoom_factor - Sets the scaling factor when zooming the quickplot window with the mousewheel/trackpad.
• interactive_zoom - Enables using mousewheel/trackpad to zoom.
• fontsize - for labels.
• layers_excluded - list of layers to exclude.
• layer_views - layer_views colors loaded from Klayout.
• min_aspect - minimum aspect ratio.

plot¶

def plot(plotter: str | None = None, **kwargs)

Returns component plot using klayout, matplotlib, holoviews or qt.

We recommend using klayout.

Arguments:

• plotter - plot backend (‘matplotlib’, ‘widget’, ‘klayout’, ‘kweb’).

show¶

def show(show_ports: bool = False,
         show_subports: bool = False,
         port_marker_layer: Layer = (1, 10),
         **kwargs) -> None

Show component in KLayout.

returns a copy of the Component, so the original component remains intact. with pins markers on each port show_ports = True, and optionally also the ports from the references (show_subports=True)

Arguments:

• show_ports - shows component with port markers and labels.
• show_subports - add ports markers and labels to references.
• port_marker_layer - for the ports.

Arguments:

• gdspath - GDS file path to write to.
• gdsdir - directory for the GDS file. Defaults to /tmp/.
• unit - unit size for objects in library. 1um by default.
• precision - for object dimensions in the library (m). 1nm by default.
• timestamp - Defaults to 2019-10-25. If None uses current time.

write_gds¶

def write_gds(gdspath: PathType | None = None,
              gdsdir: PathType | None = None,
              **kwargs) -> Path

Write component to GDS and returns gdspath.

Arguments:

• gdspath - GDS file path to write to.
• gdsdir - directory for the GDS file. Defaults to /tmp/randomFile/gdsfactory.

Arguments:

• unit - unit size for objects in library. 1um by default.
• precision - for dimensions in the library (m). 1nm by default.
• logging - disable GDS path logging, for example for showing it in KLayout.
• on_duplicate_cell - specify how to resolve duplicate-named cells. Choose one of the following:
• "warn" default - overwrite all duplicate cells with one of the duplicates (arbitrarily).
• "error" - throw a ValueError when attempting to write a gds with duplicate cells.
• "overwrite" - overwrite all duplicate cells with one of the duplicates, without warning.
• on_uncached_component - Literal[“warn”, “error”] = “warn”
• flatten_invalid_refs - flattens component references which have invalid transformations.
• max_points - Maximal number of vertices per polygon. Polygons with more vertices that this are automatically fractured.
• with_metadata - writes metadata in YAML format.
• with_netlist - writes a netlist in JSON format.
• netlist_function - function to generate the netlist.

write_oas¶

def write_oas(gdspath: PathType | None = None,
              gdsdir: PathType | None = None,
              **kwargs) -> Path

Write component to GDS and returns gdspath.

Arguments:

• gdspath - GDS file path to write to.
• gdsdir - directory for the GDS file. Defaults to /tmp/randomFile/gdsfactory.

Arguments:

• unit - unit size for objects in library. 1um by default.
• precision - for dimensions in the library (m). 1nm by default.
• logging - disable GDS path logging, for example for showing it in KLayout.
• on_duplicate_cell - specify how to resolve duplicate-named cells. Choose one of the following:
• "warn" default - overwrite all duplicate cells with one of the duplicates (arbitrarily).
• "error" - throw a ValueError when attempting to write a gds with duplicate cells.
• "overwrite" - overwrite all duplicate cells with one of the duplicates, without warning.
• None - do not try to resolve (at your own risk!)
• on_uncached_component - Literal[“warn”, “error”] = “warn”
• flatten_invalid_refs - flattens component references which have invalid transformations.
• compression_level - Level of compression for cells (between 0 and 9). Setting to 0 will disable cell compression, 1 gives the best speed and 9, the best compression.
• detect_rectangles - Store rectangles in compressed format.
• detect_trapezoids - Store trapezoids in compressed format.
• circle_tolerance - Tolerance for detecting circles. If less or equal to 0, no detection is performed. Circles are stored in compressed format. validation (“crc32”, “checksum32”, None) – type of validation to include in the saved file.
• standard_properties - Store standard OASIS properties in the file.

write_gds_with_metadata¶

def write_gds_with_metadata(*args, **kwargs) -> Path

Write component in GDS and metadata (component settings) in YAML.

to_dict¶

def to_dict(ignore_components_prefix: list[str] | None = None,
            ignore_functions_prefix: list[str] | None = None,
            with_cells: bool = False,
            with_ports: bool = True) -> dict[str, Any]

Returns Dict representation of a component.

Arguments:

• ignore_components_prefix - for components to ignore when exporting.
• ignore_functions_prefix - for functions to ignore when exporting.
• with_cells - write cells recursively.
• with_ports - write port information dict.

to_yaml¶

def to_yaml(**kwargs) -> str

Write Dict representation of a component in YAML format.

Arguments:

• ignore_components_prefix - for components to ignore when exporting.
• ignore_functions_prefix - for functions to ignore when exporting.
• with_cells - write cells recursively.
• with_ports - write port information.

auto_rename_ports¶

def auto_rename_ports(**kwargs) -> None

Rename ports by orientation NSEW (north, south, east, west).

Arguments:

• function - to rename ports.

• select_ports_optical - to select optical ports.

• select_ports_electrical - to select electrical ports.

• prefix_optical - prefix.

• prefix_electrical - prefix.

  .. code::

  3 4 |__| 2 -| |- 5 | | 1 -|______|- 6 | | 8 7

auto_rename_ports_orientation¶

def auto_rename_ports_orientation(**kwargs) -> None

Rename ports by orientation NSEW (north, south, east, west).

Arguments:

• function - to rename ports.

• select_ports_optical - to select ports. select_ports_electrical: prefix_optical: prefix_electrical:

  .. code::

  N0 N1 || W1 -| |- E1 | | W0 -|____|- E0 | | S0 S1

move¶

def move(origin: Float2 = (0, 0),
         destination: Float2 | None = None,
         axis: Axis | None = None) -> Component

Returns new Component with a moved reference to the original.

component.

Arguments:

• origin - of component.
• destination - x, y.
• axis - x or y.

mirror¶

def mirror(p1: Float2 = (0, 1), p2: Float2 = (0, 0), **kwargs) -> Component

Returns new Component with a mirrored reference.

Arguments:

• p1 - first point to define mirror axis.
• p2 - second point to define mirror axis.

rotate¶

def rotate(angle: float = 90, **kwargs) -> Component

Returns new component with a rotated reference to the original.

Arguments:

• angle - in degrees.

add_padding¶

def add_padding(**kwargs) -> Component

Returns same component with padding.

Arguments:

• component - for padding.
• layers - list of layers. suffix for name.
• default - default padding (50um).
• top - north padding.
• bottom - south padding.
• right - east padding.
• left - west padding.

absorb¶

def absorb(reference) -> Component

Absorbs polygons from ComponentReference into Component.

Destroys the reference in the process but keeping the polygon geometry.

Arguments:

• reference - ComponentReference to be absorbed into the Component.

remove¶

def remove(items)

Removes items from a Component, which can include Ports, PolygonSets CellReferences, ComponentReferences and Labels.

Arguments:

• items - list of Items to be removed from the Component.

hash_geometry¶

def hash_geometry(precision: float = 1e-4) -> str

Returns an SHA1 hash of the geometry in the Component.

For each layer, each polygon is individually hashed and then the polygon hashes are sorted, to ensure the hash stays constant regardless of the ordering the polygons. Similarly, the layers are sorted by (layer, datatype).

Arguments:

• precision - Rounding precision for the the objects in the Component. For instance, a precision of 1e-2 will round a point at (0.124, 1.748) to (0.12, 1.75).

get_labels¶

def get_labels(apply_repetitions=True,
               depth: int | None = None,
               layer=None) -> list[Label]

Return labels.

Arguments:

apply_repetitions:.

• depth - None returns all labels and 0 top level.
• layer - layerspec.

remove_labels¶

def remove_labels() -> None

Remove labels.

get_info¶

def get_info()

Gathers the .info dictionaries from every sub-Component and returns them in a list.

Arguments:

• depth - int or None If not None, defines from how many reference levels to retrieve Ports from.

Returns:

list of dictionaries List of the “.info” property dictionaries from all sub-Components

remap_layers¶

def remap_layers(layermap,
                 include_labels: bool = True,
                 include_paths: bool = True) -> Component

Returns a copy of the component with remapped layers.

Arguments:

• layermap - Dictionary of values in format {layer_from : layer_to}.
• include_labels - Selects whether to move Labels along with polygons.
• include_paths - Selects whether to move Paths along with polygons.

to_3d¶

def to_3d(layer_views: LayerViews | None = None,
          layer_stack: LayerStack | None = None,
          exclude_layers: tuple[Layer, ...] | None = None)

Return Component 3D trimesh Scene.

Arguments:

• component - to extrude in 3D.
• layer_views - layer colors from Klayout Layer Properties file. Defaults to active PDK.layer_views.
• layer_stack - contains thickness and zmin for each layer. Defaults to active PDK.layer_stack.
• exclude_layers - layers to exclude.

to_np¶

def to_np(nm_per_pixel: int = 20,
          layers: Layers = ((1, 0), ),
          values: tuple[float, ...] | None = None,
          pad_width: int = 1) -> np.ndarray

Returns a pixelated numpy array from Component polygons.

Arguments:

• component - Component.
• nm_per_pixel - you can go from 20 (coarse) to 4 (fine).
• layers - to convert. Order matters (latter overwrite former).
• values - associated to each layer (defaults to 1).
• pad_width - padding pixels around the image.

write_stl¶

def write_stl(filepath: str,
              layer_stack: LayerStack | None = None,
              exclude_layers: tuple[Layer, ...] | None = None,
              use_layer_name: bool = False,
              hull_invalid_polygons: bool = True,
              scale: float | None = None) -> None

Write a Component to STL for 3D printing.

Arguments:

• filepath - to write STL to.
• layer_stack - contains thickness and zmin for each layer.
• exclude_layers - layers to exclude.
• use_layer_name - If True, uses LayerLevel names in output filenames rather than gds_layer and gds_datatype.
• hull_invalid_polygons - If True, replaces invalid polygons (determined by shapely.Polygon.is_valid) with its convex hull.
• scale - Optional factor by which to scale meshes before writing.

write_gerber¶

def write_gerber(dirpath, layermap_to_gerber_layer, options) -> None

Arguments:

• dirpath - directory to write gerber files to.
• layermap_to_gerber_layer - dictionary of layermap to gerber layer.
• options - dictionary of options for gerber export.
• header - List[str] | None = None
• mode - Literal[“mm”, “in”] = “mm”
• resolution - float = 1e-6
• int_size - int = 4

to_gmsh¶

def to_gmsh(type: str,
            layer_stack: LayerStack,
            z: float | None = None,
            xsection_bounds=None,
            wafer_padding: float = 0.0,
            wafer_layer: Layer = (99999, 0),
            *args,
            **kwargs)

Returns a gmsh mesh of the component for finite element simulation.

Arguments:

• type - one of “xy”, “uz”, or “3D”. Determines the type of mesh to return.
• layer_stack - LayerStack object containing layer information.
• z - used to define z-slice for xy meshing.
• xsection_bounds - used to define in-plane line for uz meshing.
• wafer_padding - padding beyond bbox to add to WAFER layers.
• wafer_layer - layer to use for WAFER padding.

Arguments:

Arguments for the target meshing function in gplugins.gmsh

offset¶

def offset(distance: float = 0.1,
           use_union: bool = True,
           precision: float = 1e-4,
           join: str = "miter",
           tolerance: int = 2,
           layer: LayerSpec = "WG") -> Component

Returns new Component with polygons eroded or dilated by an offset.

Arguments:

• distance - Distance to offset polygons. Positive values expand, negative shrink.
• use_union - If True, use union of all polygons to offset. If False, offset
• precision - Desired precision for rounding vertex coordinates.
• join - {‘miter’, ‘bevel’, ‘round’} Type of join used to create polygon offset
• tolerance - For miter joints, this number must be at least 2 represents the maximal distance in multiples of offset between new vertices and their original position before beveling to avoid spikes at acute joints. For round joints, it indicates the curvature resolution in number of points per full circle.
• layer - Specific layer to put polygon geometry on.

copy¶

def copy(D: Component,
         references=None,
         ports=None,
         polygons=None,
         paths=None,
         name=None,
         labels=None) -> Component

Returns a Component copy.

Arguments:

• D - component to copy.

recurse_structures¶

def recurse_structures(
        component: Component,
        ignore_components_prefix: list[str] | None = None,
        ignore_functions_prefix: list[str] | None = None) -> dict[str, Any]

Recurse component and components references recursively.

Arguments:

• component - component to recurse.
• ignore_components_prefix - list of prefix to ignore.
• ignore_functions_prefix - list of prefix to ignore.

flatten_invalid_refs_recursive¶

def flatten_invalid_refs_recursive(component: Component,
                                   grid_size: float | None = None,
                                   updated_components=None,
                                   traversed_components=None) -> Component

Recursively flattens component references which have invalid transformations (i.e. non-90 deg rotations or sub-grid translations) returns a copy if any subcells have been modified.

WARNING: this function will produce same-name copies of cells. It is strictly meant to be used on write of the GDS file and should not be mixed with other cells, or you will likely experience issues with duplicate cells

Arguments:

• component - the component to fix (in place).
• grid_size - the GDS grid size, in um, defaults to active PDK.get_grid_size() any translations with higher resolution than this are considered invalid.
• updated_components - dict of components transformed. Should always be None, except for recursive.
• traversed_components - the set of component names which have been traversed. Should always be None, except for recursive invocations.

gdsfactory.route_info¶

route_info¶

def route_info(cs_type: str,
               length: float,
               length_eff: float | None = None,
               taper: bool = False,
               **kwargs) -> dict[str, float | str]

Returns route info dict for pathlength analysis.

Arguments:

• cs_type - cross section type.
• length - length.
• length_eff - effective length (i.e. an equivalent straight length of a bend).
• taper - True if this component is a taper.
• kwargs - other attributes to track.

Returns:

A dictionary of routing attributes.

route_info_from_cs¶

def route_info_from_cs(cs: CrossSectionSpec,
                       length: float,
                       length_eff: float | None = None,
                       **kwargs) -> dict[str, float | str]

Returns route info dict for pathlength analysis.

Arguments:

• cs - cross section object or spec.
• length - length.
• length_eff - effective length (i.e. an equivalent straight length of a bend).
• kwargs - other attributes to track.

Returns:

A dictionary of routing attributes.

gdsfactory.pack¶

pack a list of components into as few components as possible.

Adapted from PHIDL https://github.com/amccaugh/phidl/ by Adam McCaughan

pack¶

@validate_call
def pack(component_list: list[ComponentSpec],
         spacing: float = 10.0,
         aspect_ratio: Float2 = (1.0, 1.0),
         max_size: tuple[float | None, float | None] = (None, None),
         sort_by_area: bool = True,
         density: float = 1.1,
         precision: float = 1e-2,
         text: ComponentSpec | None = None,
         text_prefix: str = "",
         text_mirror: bool = False,
         text_rotation: int = 0,
         text_offsets: tuple[Float2, ...] = ((0, 0), ),
         text_anchors: tuple[Anchor, ...] = ("cc", ),
         name_prefix: str | None = None,
         rotation: int = 0,
         h_mirror: bool = False,
         v_mirror: bool = False,
         add_ports_prefix: bool = True,
         add_ports_suffix: bool = False) -> list[Component]

Pack a list of components into as few Components as possible.

Arguments:

• component_list - list or tuple.

• spacing - Minimum distance between adjacent shapes.

• aspect_ratio - (width, height) ratio of the rectangular bin.

• max_size - Limits the size into which the shapes will be packed.

• sort_by_area - Pre-sorts the shapes by area.

• density - Values closer to 1 pack tighter but require more computation.

• precision - Desired precision for rounding vertex coordinates.

• text - Optional function to add text labels.

• text_prefix - for labels. For example. ‘A’ will produce ‘A1’, ‘A2’, ...

• text_mirror - if True mirrors text.

• text_rotation - Optional text rotation.

• text_offsets - relative to component size info anchor. Defaults to center.

• text_anchors - relative to component (ce cw nc ne nw sc se sw center cc).

• name_prefix - for each packed component (avoids the Unnamed cells warning). Note that the suffix contains a uuid so the name will not be deterministic.

• rotation - optional component rotation in degrees.

• h_mirror - horizontal mirror in y axis (x, 1) (1, 0). This is the most common.

• v_mirror - vertical mirror using x axis (1, y) (0, y).

• add_ports_prefix - adds port names with prefix.

• add_ports_suffix - adds port names with suffix.

  .. plot:: :include-source:

  import gdsfactory as gf from functools import partial

  components = [gf.components.triangle(x=i) for i in range(1, 10)] c = gf.pack( components, spacing=20.0, max_size=(100, 100), text=partial(gf.components.text, justify=“center”), text_prefix=“R”, name_prefix=“demo”, text_anchors=[“nc”], text_offsets=[(-10, 0)], v_mirror=True, ) c[0].plot()

test_pack¶

def test_pack() -> None

Test packing function.

test_pack_with_settings¶

def test_pack_with_settings() -> None

Test packing function with custom settings.

gdsfactory.geometry.boolean_polygons¶

boolean_polygons¶

def boolean_polygons(operand1: ComponentReference | Component | gdstk.Polygon,
                     operand2: ComponentReference | Component | gdstk.Polygon,
                     operation: str,
                     output_layer: LayerSpec = (0, 0),
                     precision: float = 1e-3) -> list[gdstk.Polygon]

Perform a boolean operation and return the list of resulting Polygons. See gdstk docs for details.

Arguments:

• operand1 - polygon set A.

• operand2 - polygon set B.

• operation - the name of the operation to perform, i.e. “or”, “and”, “not”, or “xor”.

• output_layer - the layer to assign the resulting polygons.

• precision - the precision used for the operation, in microns.

• Returns - a list of gdstk Polygons on the specified output layer.

gdsfactory.geometry.maskprep¶

get_polygons_over_under¶

def get_polygons_over_under(component: ComponentOrReference,
                            layers: LayerSpecs,
                            distances: Floats,
                            use_union: bool = True,
                            precision: float = 1e-4,
                            join: str = "miter",
                            tolerance: int = 2) -> list[gdstk.Polygon]

Returns list polygons dilated and eroded by an offset. Cleans min width gap and acute angle DRC errors equal to distances.

Arguments:

• component - Component containing polygons to offset.
• layers - list of layers to remove min gap errors.
• distances - Distance to offset polygons. By expanding and shrinking it merges polygons. If you want to fix min gaps of 0.5 use 0.5.
• precision - Desired precision for rounding vertex coordinates.
• join - {‘miter’, ‘bevel’, ‘round’} Type of join used to create polygon offset
• tolerance - For miter joints, this number must be at least 2 represents the maximal distance in multiples of offset between new vertices and their original position before beveling to avoid spikes at acute joints. For round joints, it indicates the curvature resolution in number of points per full circle.
• layer - Specific layer to put polygon geometry on.

Returns:

Component containing a polygon(s) with the specified offset applied.

over_under¶

@gf.cell
def over_under(component: ComponentSpec,
               layers: LayerSpecs,
               remove_original: bool = False,
               **kwargs) -> Component

Returns cleaned component.

Arguments:

component:

• layers - list of layers.
• remove_original - remove original layers.

gdsfactory.geometry.fillet¶

fillet¶

def fillet(operand: ComponentReference | Component | gdstk.Polygon
           | list[gdstk.Polygon],
           radius: float | list[float],
           tolerance: float = 0.01) -> list[gdstk.Polygon]

Perform a fillet operation and return the list of resulting Polygons.

Arguments:

• operand - polygon, list of Polygons, Component, or ComponentReference.

• radius - Fillet radius. You can also define a value for each vertex.

• tolerance - for calculating the polygonal approximation of the filleted corners.

  .. plot:: :include-source:

  import gdstk import gdsfactory as gf

  points = [(0, 0), (1.2, 0), (1.2, 0.3), (1, 0.3), (1.5, 1), (0, 1.5)] p0 = gdstk.Polygon(points, datatype=1) p1 = gdstk.Polygon(points, datatype=1) p1 = gf.geometry.fillet(p1, radius=1.0)

  c = gf.Component(“demo”) c.add_polygon(p0, layer=(1, 0)) c.add_polygon(p1, layer=(2, 0)) c.plot_matplotlib() c.show()

gdsfactory.geometry¶

Geometric operations: Booleans, DRC checks.

gdsfactory.geometry.layer_priority¶

layer_priority¶

@gf.cell
def layer_priority(component: ComponentSpec,
                   layer_high_order: LayerSpec,
                   layer_low_order: LayerSpec,
                   remove_high_order: bool = False,
                   **kwargs) -> gf.Component

Returns new component after removing one layer from another.

Arguments:

• component - spec.
• layer_high_order - layer used to etch.
• layer_low_order - layer etched into.
• remove_high_order - whether to also remove the high order layer polygons. Useful if the higher order layer is purely logical.
• kwargs - keyword arguments for boolean difference operation.

gdsfactory.geometry.fill_klayout¶

Dummy fill to keep density constant using klayout.

fill¶

def fill(gdspath,
         layer_to_fill: LayerSpec,
         layer_to_fill_margin: float = 0,
         layers_to_avoid: tuple[LayerSpec, float] | None = None,
         cell_name: str | None = None,
         fill_cell_name: str = "fill_cell",
         create_new_fill_cell: bool = False,
         include_original: bool = False,
         fill_layers: LayerSpecs | None = None,
         fill_size: tuple[float, float] = (10, 10),
         fill_spacing: tuple[float, float] = (20, 20),
         fill_name: str | None = None,
         gdspath_out: PathType | None = None) -> None

Write gds file with fill.

Arguments:

• gdspath - GDS input.
• layer_to_fill - Layer that defines the region to fill.
• layer_to_fill_margin - in um.
• layers_to_avoid - Layer to avoid to margin (((1, 0), 3.5), (LAYER.SLAB, 2)).
• cell_name - Optional cell to fill. Defaults to top cell.
• fill_cell_name - Optional cell name to use as fill.
• create_new_fill_cell - creates new fill cell, otherwise uses fill_cell_name from gdspath.
• include_original - True include original gdspath. False returns only fill.
• fill_layers - if create_new_fill_cell=True, defines new fill layers.
• fill_size - if create_new_fill_cell=True, defines new fill size.
• fill_spacing - fill pitch in x and y.
• fill_name - name of the cell containing all fill cells. Defaults to Cell_fill.
• gdspath_out - Optional GDS output. Defaults to input.

gdsfactory.geometry.maskprep_flat¶

gdsfactory.geometry.functions¶

area¶

def area(pts: ndarray) -> float64

Returns the area.

manhattan_direction¶

def manhattan_direction(p0, p1, tol=1e-5)

Returns manhattan direction between 2 points.

curvature¶

def curvature(points: ndarray, t: ndarray) -> ndarray

Args are the points and the tangents at each point.

points : numpy.array shape (n, 2) t: numpy.array of size n

Returns:

The curvature at each point.

Computes the curvature at every point excluding the first and last point.

For a planar curve parametrized as P(t) = (x(t), y(t)), the curvature is given by (x’ y’’ - x’’ y’ ) / (x’ **2 + y’ 2)(3/2)

path_length¶

def path_length(points: ndarray) -> float64

Returns: The path length.

Arguments:

• points - With shape (N, 2) representing N points with coordinates x, y.

snap_angle¶

def snap_angle(a: float64) -> int

Returns angle snapped along manhattan angle (0, 90, 180, 270).

a: angle in deg Return angle snapped along manhattan angle

angles_rad¶

def angles_rad(pts: ndarray) -> ndarray

Returns the angles (radians) of the connection between each point and the next.

angles_deg¶

def angles_deg(pts: ndarray) -> ndarray

Returns the angles (degrees) of the connection between each point and the next.

extrude_path¶

def extrude_path(points: ndarray,
                 width: float,
                 with_manhattan_facing_angles: bool = True,
                 spike_length: float64 | int | float = 0,
                 start_angle: int | None = None,
                 end_angle: int | None = None,
                 grid: float | None = None) -> ndarray

Deprecated. Use gdsfactory.path.Path.extrude() instead.

Extrude a path of width along a curve defined by points.

Arguments:

• points - numpy 2D array of shape (N, 2).
• width - of the path to extrude.
• with_manhattan_facing_angles - snaps to manhattan angles.
• spike_length - in um.
• start_angle - in degrees.
• end_angle - in degrees.
• grid - in um.

Returns:

numpy 2D array of shape (2*N, 2).

polygon_grow¶

def polygon_grow(polygon: ndarray, offset: float) -> ndarray

Returns a grown closed shaped polygon by an offset.

gdsfactory.geometry.trim¶

Trim component.

Adapted from PHIDL https://github.com/amccaugh/phidl/ by Adam McCaughan

trim¶

@gf.cell
def trim(component: Component,
         domain: list[tuple[float, float]],
         precision: float = 1e-4,
         return_ports: bool | None = False) -> Component

Trim a component by another geometry, preserving the component’s layers and ports.

Useful to get a smaller component from a larger one for simulation.

Arguments:

• component - Component(/Reference).

• domain - list of array-like[N][2] representing the boundary of the component to keep.

• precision - float Desired precision for rounding vertex coordinates.

• return_ports - whether to return the included ports or not. Ports are always renamed to avoid inheritance conflicts.

• Returns - New component with layers (and possibly ports) of the component restricted to the domain.

  .. plot:: :include-source:

  import gdsfactory as gf c = gf.components.straight_pin(length=10, taper=None) trimmed_c = gf.geometry.trim(component=c, domain=[[0, -5], [0, 5], [5, 5], [5, -5]]) trimmed_c.plot_matplotlib()

gdsfactory.geometry.boolean_klayout¶

boolean_klayout¶

@gf.cell
def boolean_klayout(gdspath1: ComponentOrPath,
                    gdspath2: ComponentOrPath,
                    layer1: tuple[int, int] = (1, 0),
                    layer2: tuple[int, int] = (1, 0),
                    layer3: tuple[int, int] = (2, 0),
                    operation: str = "xor") -> Component

Returns a boolean operation between two components Uses KLayout python API.

Arguments:

• gdspath1 - path to GDS or Component.
• gdspath2 - path to GDS or Component.
• layer1 - tuple for gdspath1.
• layer2 - tuple for gdspath2.
• layer3 - for the result of the operation.

gdsfactory.geometry.boolean¶

Based on phidl.geometry.

boolean¶

@gf.cell
def boolean(A: ComponentOrReference | tuple[ComponentOrReference, ...],
            B: ComponentOrReference | tuple[ComponentOrReference, ...],
            operation: str,
            precision: float = 1e-4,
            layer: LayerSpec = (1, 0)) -> Component

Performs boolean operations between 2 Component/Reference/list objects.

operation should be one of {‘not’, ‘and’, ‘or’, ‘xor’, ‘A-B’, ‘B-A’, ‘A+B’}. Note that ‘A+B’ is equivalent to ‘or’, ‘A-B’ is equivalent to ‘not’, and ‘B-A’ is equivalent to ‘not’ with the operands switched

You can also use gdsfactory.drc.boolean_klayout

Arguments:

• A - Component(/Reference) or list of Component(/References).

• B - Component(/Reference) or list of Component(/References).

• operation - {‘not’, ‘and’, ‘or’, ‘xor’, ‘A-B’, ‘B-A’, ‘A+B’}.

• precision - float Desired precision for rounding vertex coordinates.

• layer - Specific layer to put polygon geometry on.

• Returns - Component with polygon(s) of the boolean operations between the 2 input Components performed.

  Notes¶

  • ‘A+B’ is equivalent to ‘or’.
  • ‘A-B’ is equivalent to ‘not’.
  • ‘B-A’ is equivalent to ‘not’ with the operands switched.

  .. plot:: :include-source:

  import gdsfactory as gf

  c1 = gf.components.circle(radius=10).ref() c2 = gf.components.circle(radius=9).ref() c2.movex(5)

  c = gf.geometry.boolean(c1, c2, operation=“xor”) c.plot_matplotlib()

gdsfactory.geometry.fill_tiled¶

gdsfactory.geometry.offset¶

Based on phidl.geometry.

offset¶

@gf.cell
def offset(elements: Component,
           distance: float = 0.1,
           use_union: bool = True,
           precision: float = 1e-4,
           join: str = "miter",
           tolerance: int = 2,
           layer: LayerSpec = "WG") -> Component

Returns new Component with polygons eroded or dilated by an offset.

Arguments:

• elements - Component(/Reference), list of Component(/Reference), or Polygon Polygons to offset or Component containing polygons to offset.
• distance - Distance to offset polygons. Positive values expand, negative shrink.
• use_union - If True, use union of all polygons to offset. If False, offset
• precision - Desired precision for rounding vertex coordinates.
• join - {‘miter’, ‘bevel’, ‘round’} Type of join used to create polygon offset
• tolerance - For miter joints, this number must be at least 2 represents the maximal distance in multiples of offset between new vertices and their original position before beveling to avoid spikes at acute joints. For round joints, it indicates the curvature resolution in number of points per full circle.
• layer - Specific layer to put polygon geometry on.

Returns:

Component containing a polygon(s) with the specified offset applied.

.. plot:: :include-source:

import gdsfactory as gf c = gf.Component() layer_slab = (2, 0) c1 = gf.components.coupler_ring( cladding_layers=[layer_slab], cladding_offsets=[0.5] ) d = 0.8 c2 = gf.geometry.offset(c1, distance=+d, layer=layer_slab) c3 = gf.geometry.offset(c2, distance=-d, layer=layer_slab)

c << c1.extract(layers=(“WG”,)) c << c3 c.plot_matplotlib()

gdsfactory.geometry.union¶

union¶

@gf.cell
def union(component: Component,
          by_layer: bool = False,
          precision: float = 1e-4,
          join_first: bool = True,
          layer: Layer = (1, 0)) -> Component

Returns new Component with inverted union of Component polygons.

based on phidl.geometry.union

Arguments:

• component - Component(/Reference), list of Component(/Reference), or Polygon A containing the polygons to perform union and inversion on.

• by_Layer - performs the union operation layer-wise so each layer can be individually combined.

• precision - Desired precision for rounding vertex coordinates.

• join_first - before offsetting to avoid unnecessary joins in adjacent polygons.

• layer - Specific layer to put polygon geometry on.

  .. plot:: :include-source:

  import gdsfactory as gf c = gf.Component() c << gf.components.ellipse(radii=(6, 6)) c << gf.components.ellipse(radii=(10, 4)) c2 = gf.geometry.union(c, join_first=False)

gdsfactory.geometry.outline¶

outline¶

@gf.cell
def outline(elements,
            distance=1,
            precision: float = 1e-3,
            join: str = "miter",
            tolerance: int = 2,
            join_first: bool = True,
            open_ports: bool | float = False,
            layer=0) -> Component

Returns Component containing the outlined polygon(s).

Creates an outline around all the polygons passed in the elements argument. elements may be a Component, Polygon, or list of Components.

Arguments:

• elements - Component(/Reference), list of Component(/Reference), or Polygon Polygons to outline or Component containing polygons to outline.
• distance - int or float Distance to offset polygons. Positive values expand, negative shrink.
• precision - float Desired precision for rounding vertex coordinates.
• join - {‘miter’, ‘bevel’, ‘round’} Type of join used to create the offset polygon.
• tolerance - int or float For miter joints, this number must be at least 2 and it represents the maximal distance in multiples of offset between new vertices and their original position before beveling to avoid spikes at acute joints. For round joints, it indicates the curvature resolution in number of points per full circle.
• open_ports - bool or float If not False, holes will be cut in the outline such that the Ports are not covered. If True, the holes will have the same width as the Ports. If a float, the holes will be be widened by that value (useful for fully clearing the outline around the Ports for positive-tone processes
• layer - int, array-like[2], or set Specific layer(s) to put polygon geometry on.).

gdsfactory.geometry.xor_diff¶

xor_diff¶

@gf.cell
def xor_diff(A, B, precision: float = 1e-4) -> Component

Given two Components A and B, performs the layer-by-layer XOR difference between A and B and returns polygons representing the differences between A and B.

gdsfactory wrapper for phidl.geometry.xor_diff

Arguments:

• A - Component(/Reference) or list of Component(/References).

• B - Component(/Reference) or list of Component(/References).

• precision - Desired precision for rounding vertex coordinates.

  Returns

• Component - containing a polygon(s) defined by the XOR difference result between A and B.

gdsfactory.geometry.invert¶

Based on phidl.geometry.

invert¶

@gf.cell
def invert(elements,
           border: float = 10.0,
           precision: float = 1e-4,
           layer: LayerSpec = (1, 0)) -> Component

Creates an inverted version of the input shapes with an additional border around the edges.

Arguments:

elements : Component(/Reference), list of Component(/Reference), or Polygon A Component containing the polygons to invert.

• border - Size of the border around the inverted shape (border value is the distance from the edges of the boundary box defining the inverted shape to the border, and is applied to all 4 sides of the shape).

• precision - Desired precision for rounding vertex coordinates.

• layer - Specific layer(s) to put polygon geometry on.

  Returns

• D - A Component containing the inverted version of the input shape(s) and the corresponding border(s).

  .. plot:: :include-source:

  import gdsfactory as gf

  e1 = gf.components.ellipse(radii=(6, 6)) c = gf.geometry.invert(e1) c.plot_matplotlib()

gdsfactory.geometry.manhattanize¶

manhattanize_polygon¶

def manhattanize_polygon(p: Polygon, target_step: float = 0.05) -> Polygon

Return a Manhattanized version of the input polygon (where non-x and non-y parallel segments are decomposed into a staircase of small x and y-parallel segments)

Implemented in pure Python, and hence only suited to small polygons.

Arguments:

• p - input polygon.
• target_step - target staircase step size.

Returns:

manhattanized polygon

.. plot:: :include-source:

import gdsfactory as gf c = gf.Component()

poly = gdstk.rectangle((-2, -2), (2, 2)) poly.rotate(np.pi / 4) poly.scale(1, 0.5) init_poly = c.add_polygon(poly, layer=1) final_poly = gf.geometry.manhattanize_polygon(poly) c.add_polygon(final_poly, layer=2) c.plot_matplotlib()

gdsfactory.polygon¶

Polygon

Adapted from PHIDL https://github.com/amccaugh/phidl/ by Adam McCaughan

Polygon Objects¶

class Polygon(gdstk.Polygon, _GeometryHelper)

Polygonal geometric object.

Arguments:

• points - array-like[N][2] Coordinates of the vertices of the Polygon.
• gds_layer - int GDSII layer of the Polygon.
• gds_datatype - int GDSII datatype of the Polygon.

__repr__¶

def __repr__() -> str

Returns path points.

bbox¶

@property
def bbox()

Returns the bounding box of the Polygon.

rotate¶

def rotate(angle: float = 45, center: tuple[float, float] = (0, 0)) -> Polygon

Rotates a Polygon by the specified angle.

Arguments:

• angle - Angle to rotate the Polygon in degrees.
• center - Midpoint of the Polygon.

move¶

def move(origin: tuple[float, float] = (0, 0),
         destination: tuple[float, float] | None = None,
         axis: str | None = None) -> Polygon

Moves elements of the Device from the origin point to the destination. Both origin and destination can be 1x2 array-like, Port, or a key corresponding to one of the Ports in this device.

Arguments:

• origin - Origin point of the move. destination : Destination point of the move.
• axis - {‘x’, ‘y’} Direction of move.

mirror¶

def mirror(p1=(0, 1), p2=(0, 0)) -> Polygon

Mirrors a Polygon across the line formed between the two specified points. points may be input as either single points [1,2] or array-like[N][2], and will return in kind.

Arguments:

• p1 - First point of the line.
• p2 - Second point of the line.

simplify¶

def simplify(tolerance: float = 1e-3) -> Polygon

Removes points from the polygon but does not change the polygon shape by more than tolerance from the original. Uses the Ramer-Douglas-Peucker algorithm.

Arguments:

• tolerance - float Tolerance value for the simplification algorithm. All points that can be removed without changing the resulting polygon by more than the value listed here will be removed. Also known as epsilon here https://en.wikipedia.org/wiki/Ramer–Douglas–Peucker_algorithm

snap¶

def snap(nm: int = 1) -> sp.Polygon

Returns new polygon snap points to grid

gdsfactory.font¶

Support for font rendering in GDS files.

Adapted from PHIDL https://github.com/amccaugh/phidl/ by Adam McCaughan

gdsfactory.get_factories¶

get_cells¶

def get_cells(modules, verbose: bool = False) -> dict[str, ComponentFactory]

Returns PCells (component functions) from a module or list of modules.

Arguments:

• modules - module or iterable of modules.
• verbose - prints in case any errors occur.

gdsfactory.get_netlist_flat¶

get_netlist_flat¶

def get_netlist_flat(component: Component, **kwargs) -> dict[str, Any]

Parses a recursive netlist for a component as if it was a single netlist with its lowest-level instances.

Procedure:

• Recursively parse the recursive dict to generate a unique list of all instances even if they are reused Each entry is formatted as [(netlist, instance),...], and defines a unique flat_name = {top}{hierarchy_delimiter}{instance}{hierarchy_delimiter}{instance}{hierarchy_delimiter}...
• Populate the flat netlist dict with similar entries as regular gdsfactory netlists:
• instances: component, info, and settings from the original netlist, but keyed with flat_name
• placements: For instance corresponding to each flat_name, accumulate placements across the hierarchy
• ports and connections: each unique port of each flat_name instance is uniquely named as flat_name,port_name for each flat_name,port_name, starting at lowest hierarchy level:
• list connections at that level (finding the proper other flat_name,port_name if non-leaf level)
• if possible, maps the port to a port of that instance’s netlist, and repeat at a higher level
• if the top level is reached, assign that flat_name,port_name to a top-level component port instead the returned ports dict has top level component portname: flat_name,port_name mappings the returned connections dict is sorted and flattened into a minimal (flat_name,port_name)_1: [(flat_name,port_name)] key: value pairs If allow_multiple flag in get_netlist is True, the values will be lists (to support multiple connections)
• name: top_level_component name

Arguments:

• component - to extract flat netlist.

Arguments:

• component_suffix - suffix to append to each component name. useful if to save and reload a back-annotated netlist.
• get_netlist_func - function to extract individual netlists.
• full_settings - True returns all, false changed settings.
• tolerance - tolerance in nm to consider two ports connected.
• exclude_port_types - optional list of port types to exclude from netlisting.
• get_instance_name - function to get instance name.

Returns:

• instances - Dict of instance name and settings.
• connections - Dict of Instance1Name,portName: Instance2Name,portName.
• placements - Dict of instance names and placements (x, y, rotation).
• port - Dict portName: ComponentName,port.
• name - name of component.
• warnings - warning messages (disconnected pins).

gdsfactory.port¶

We use Ports to connect Components with other Components.

we follow start from the bottom left and name the ports counter-clock-wise

.. code::

     3   4
     |___|_
 2 -|      |- 5
    |      |
 1 -|______|- 6
     |   |
     8   7

You can also rename them with W,E,S,N prefix (west, east, south, north).

.. code::

         N0  N1
         |___|_
    W1 -|      |- E1
        |      |
    W0 -|______|- E0
         |   |
        S0   S1

Adapted from PHIDL https://github.com/amccaugh/phidl/ by Adam McCaughan

Port Objects¶

class Port()

Ports are useful to connect Components with each other.

Arguments:

• name - we name ports clock-wise starting from bottom left.
• center - (x, y) port center coordinate.
• width - of the port in um.
• orientation - in degrees (0: east, 90: north, 180: west, 270: south).
• parent - parent component (component to which this port belong to).
• layer - layer tuple.
• port_type - str (optical, electrical, vertical_te, vertical_tm).
• parent - Component that port belongs to.
• cross_section - cross_section spec.
• shear_angle - an optional angle to shear port face in degrees.

__init__¶

def __init__(name: str,
             orientation: float | None,
             center: tuple[float, float],
             width: float | None = None,
             layer: tuple[int, int] | None = None,
             port_type: str = "optical",
             parent: Component | None = None,
             cross_section: CrossSection | None = None,
             shear_angle: float | None = None) -> None

Initializes Port object.

__repr__¶

def __repr__() -> str

Return a string representation of the object.

__get_validators__¶

@classmethod
def __get_validators__(cls)

Get validators.

validate¶

@classmethod
def validate(cls, v, _info)

For pydantic assumes Port is valid if has a name and a valid type.

move_polar_copy¶

def move_polar_copy(d: float, angle: float) -> Port

Returns a copy of the port with a distance (d) in um and angle (deg).

move_copy¶

def move_copy(x, y=None) -> Port

Returns a copy of the port moved by a vector or given x and y.

flip¶

def flip(**kwargs) -> Port

Flips port.

endpoints¶

@property
def endpoints() -> None

Returns the endpoints of the Port.

endpoints¶

@endpoints.setter
def endpoints(points: Float2) -> None

Sets the endpoints of a Port.

normal¶

@property
def normal() -> ndarray

Returns a vector normal to the Port.

x¶

@property
def x() -> float

Returns the x-coordinate of the Port center.

y¶

@property
def y() -> float

Returns the y-coordinate of the Port center.

rotate¶

def rotate(angle: float = 45, center: Float2 | None = None) -> Port

Rotates a Port around the specified center point, if no centerpoint specified will rotate around (0,0).

Arguments:

• angle - Angle to rotate the Port in degrees.
• center - array-like[2] or None center of the Port.

copy¶

def copy(name: str | None = None) -> Port

Returns a copy of the port.

Arguments:

• name - optional new name.

get_extended_center¶

def get_extended_center(length: float = 1.0) -> ndarray

Returns an extended port center.

snap_to_grid¶

def snap_to_grid(nm: int = 1) -> None

Snap port center to nm grid.

assert_on_grid¶

def assert_on_grid(nm: int = 1) -> None

Ensures ports edges are on grid to avoid snap_to_grid errors.

assert_manhattan¶

def assert_manhattan(nm: int = 1) -> None

Ensures port has a valid manhattan orientation (0, 90, 180, 270).

port_array¶

def port_array(center: tuple[float, float] = (0.0, 0.0),
               width: float = 0.5,
               orientation: float = 0,
               pitch: tuple[float, float] = (10.0, 0.0),
               n: int = 2,
               **kwargs) -> list[Port]

Returns a list of ports placed in an array.

Arguments:

• center - center point of the port.
• width - port width.
• orientation - angle in degrees.
• pitch - period of the port array.
• n - number of ports in the array.

read_port_markers¶

def read_port_markers(
    component: object, layers: LayerSpecs = ("PORT", )) -> Component

Returns extracted polygons from component layers.

Arguments:

• component - Component to extract markers.
• layers - GDS layer specs.

csv2port¶

def csv2port(csvpath) -> dict[str, Port]

Reads ports from a CSV file and returns a Dict.

sort_ports_clockwise¶

def sort_ports_clockwise(ports: dict[str, Port]) -> dict[str, Port]

Sort and return ports in the clockwise direction.

.. code::

    3   4
    |___|_
2 -|      |- 5
   |      |
1 -|______|- 6
    |   |
    8   7

sort_ports_counter_clockwise¶

def sort_ports_counter_clockwise(ports: dict[str, Port]) -> dict[str, Port]

Sort and return ports in the counter-clockwise direction.

.. code::

    4   3
    |___|_
5 -|      |- 2
   |      |
6 -|______|- 1
    |   |
    7   8

select_ports¶

def select_ports(ports: dict[str, Port],
                 layer: tuple[int, int] | None = None,
                 prefix: str | None = None,
                 suffix: str | None = None,
                 orientation: int | None = None,
                 width: float | None = None,
                 layers_excluded: tuple[tuple[int, int], ...] | None = None,
                 port_type: str | None = None,
                 names: list[str] | None = None,
                 clockwise: bool = True) -> dict[str, Port]

Returns a dict of ports from a dict of ports.

Arguments:

• ports - Dict[str, Port] a port dict {port name: port}.
• layer - select ports with port GDS layer.
• prefix - select ports with port name prefix.
• suffix - select ports with port name suffix.
• orientation - select ports with orientation in degrees.
• width - select ports with port width.
• layers_excluded - List of layers to exclude.
• port_type - select ports with port type (optical, electrical, vertical_te).
• clockwise - if True, sort ports clockwise, False: counter-clockwise.

Returns:

Dict containing the selected ports {port name: port}.

rename_ports_by_orientation¶

def rename_ports_by_orientation(component: Component,
                                layers_excluded: LayerSpec | None = None,
                                select_ports: Callable = select_ports,
                                function=_rename_ports_facing_side,
                                prefix: str = "o",
                                **kwargs) -> Component

Returns Component with port names based on port orientation (E, N, W, S).

Arguments:

• component - to rename ports.

• layers_excluded - to exclude.

• select_ports - function to select_ports.

• function - to rename ports.

• prefix - to add on each port name.

• kwargs - select_ports settings.

  .. code::

  N0 N1 || W1 -| |- E1 | | W0 -|____|- E0 | | S0 S1

auto_rename_ports¶

def auto_rename_ports(component: Component,
                      function=_rename_ports_clockwise,
                      select_ports_optical: Callable
                      | None = select_ports_optical,
                      select_ports_electrical: Callable
                      | None = select_ports_electrical,
                      select_ports_placement: Callable
                      | None = select_ports_placement,
                      prefix: str = "",
                      prefix_optical: str = "o",
                      prefix_electrical: str = "e",
                      prefix_placement: str = "p",
                      port_type: str | None = None,
                      **kwargs) -> Component

Adds prefix for optical and electrical.

Arguments:

• component - to auto_rename_ports.
• function - to rename ports.
• select_ports_optical - to select optical ports.
• select_ports_electrical - to select electrical ports.
• select_ports_placement - to select placement ports.
• prefix_optical - prefix of optical ports.
• prefix_electrical - prefix of electrical ports.
• prefix_placement - prefix of electrical ports.
• port_type - select ports with port type (optical, electrical, vertical_te).

Arguments:

• prefix - select ports with port name prefix.
• suffix - select ports with port name suffix.
• orientation - select ports with orientation in degrees.
• width - select ports with port width.
• layers_excluded - List of layers to exclude.
• clockwise - if True, sort ports clockwise, False: counter-clockwise.

map_ports_layer_to_orientation¶

def map_ports_layer_to_orientation(
        ports: dict[str, Port],
        function=_rename_ports_facing_side) -> dict[str, str]

Returns component or reference port mapping.

.. code::

     N0  N1
     |___|_
W1 -|      |- E1
    |      |
W0 -|______|- E0
     |   |
    S0   S1

map_ports_to_orientation_cw¶

def map_ports_to_orientation_cw(ports: dict[str, Port],
                                function=_rename_ports_facing_side,
                                **kwargs) -> dict[str, str]

Returns component or reference port mapping clockwise.

Arguments:

• ports - dict of ports.

• function - to rename ports.

• kwargs - for the function to rename ports.

  .. code::

  N0 N1 || W1 -| |- E1 | | W0 -|____|- E0 | | S0 S1

auto_rename_ports_layer_orientation¶

def auto_rename_ports_layer_orientation(component: Component,
                                        function=_rename_ports_facing_side,
                                        prefix: str = "") -> None

Renames port names with layer_orientation (1_0_W0).

port orientation (E, N, W, S) numbering is clockwise

.. code::

     N0  N1
     |___|_
W1 -|      |- E1
    |      |
W0 -|______|- E0
     |   |
    S0   S1

gdsfactory.difftest_git¶

gdsdiff_git¶

def gdsdiff_git(path: str = "",
                curr_file: str = "",
                old_file: str = "",
                old_hex: str = "",
                old_mode: str = "",
                new_file: str = "",
                new_hex: str = "",
                new_mode: str = "") -> None

Show diffs for two files when running git diff.

Arguments:

• path - script to run path.
• curr_file - current GDS file.
• old_file - old GDS.
• old_hex - ignore.
• old_mode - ignore.
• new_file - new GDS file.
• new_hex - ignore.
• new_mode - ignore.

gdsfactory.read.from_gdspaths¶

from_gdspaths¶

def from_gdspaths(cells: tuple[ComponentOrPath, ...]) -> Component

Combine all GDS files or gf.components into a gf.component.

Arguments:

• cells - List of gdspaths or Components.

from_gdsdir¶

def from_gdsdir(dirpath: PathType) -> Component

Merges GDS cells from a directory into a single Component.

gdsfactory.read.labels¶

read_labels_yaml¶

def read_labels_yaml(csvpath: PathType,
                     prefix: str | None = None) -> dict[str, DictConfig]

Read labels from csvfile in YAML format.

add_port_markers¶

def add_port_markers(gdspath,
                     csvpath,
                     marker_size: int = 20,
                     marker_layer: LayerSpec = (203, 0))

Add port markers from port info extracted from a gdspath and csvpath.

gdsfactory.read.import_gds¶

import_gds¶

@cell
def import_gds(gdspath: str | Path,
               cellname: str | None = None,
               gdsdir: str | Path | None = None,
               read_metadata: bool = False,
               keep_name_short: bool = False,
               unique_names: bool = True,
               **kwargs) -> Component

Returns a Component from a GDS file.

appends $ with a number to the name if the cell name is on CACHE

Arguments:

• gdspath - path of GDS file.
• cellname - cell of the name to import. None imports top cell.
• gdsdir - optional GDS directory.
• read_metadata - loads metadata (ports, settings) if it exists in YAML format.
• keep_name_short - appends a hash to a shortened component name.
• unique_names - appends $ with a number to the name if the cell name is on CACHE. This avoids name collisions when importing multiple times the same cell name.
• kwargs - extra to add to component.info (polarization, wavelength ...).

gdsfactory.read.from_phidl¶

from_gdstk¶

@cache
def from_gdstk(cell: gdstk.Cell, **kwargs) -> Component

Returns gdsfactory Component from a gdstk cell.

Arguments:

• cell - gdstk cell.

Arguments:

• cellname - cell of the name to import (None) imports top cell.
• snap_to_grid_nm - snap to different nm grid (does not snap if False).
• gdsdir - optional GDS directory.
• read_metadata - loads metadata if it exists.
• hashed_name - appends a hash to a shortened component name.
• kwargs - extra to add to component.info (polarization, wavelength ...).

from_phidl¶

@cache
def from_phidl(component, port_layer: Layer = (1, 0), **kwargs) -> Component

Returns gdsfactory Component from a phidl Device or function.

Arguments:

• component - phidl component.
• port_layer - to add to component ports.

Arguments:

• cellname - cell of the name to import (None) imports top cell.
• snap_to_grid_nm - snap to different nm grid (does not snap if False).
• gdsdir - optional GDS directory.
• read_metadata - loads metadata if it exists.
• hashed_name - appends a hash to a shortened component name.
• kwargs - extra to add to component.info (polarization, wavelength ...).

gdsfactory.read¶

gdsfactory.read.from_dphox¶

from_dphox¶

@cell_without_validator
def from_dphox(device, foundry) -> Component

Returns Gdsfactory Component from a dphox Device.

Note that you need to install dphox pip install dphox

https://dphox.readthedocs.io/en/latest/index.html

Arguments:

• device - Dphox device.
• foundry - Dphox foundry object.

gdsfactory.read.from_yaml_template¶

split_default_settings_from_yaml¶

def split_default_settings_from_yaml(
        yaml_lines: Iterable[str]) -> tuple[str, str]

Separates out the ‘default_settings’ block from the rest of the file body. Note: ‘default settings’ MUST be at the TOP of the file.

Arguments:

• yaml_lines - the lines of text in the yaml file.

Returns:

a tuple of (main file contents), (setting block), both as multi-line strings.

cell_from_yaml_template¶

def cell_from_yaml_template(
        filename: str | IO[Any] | pathlib.Path,
        name: str,
        routing_strategy: dict[str, Callable] | None = None) -> Callable

Gets a PIC factory function from a yaml definition, which can optionally be a jinja template.

Arguments:

• filename - the filepath of the pic yaml template.
• name - the name of the component to create.
• routing_strategy - a dictionary of routing functions.

Returns:

a factory function for the component.

yaml_cell¶

def yaml_cell(yaml_definition, name: str,
              routing_strategy) -> Callable[..., Component]

The “cell” decorator equivalent for yaml files. Generates a proper cell function for yaml-defined circuits.

Arguments:

• yaml_definition - the filename to the pic yaml definition.
• name - the name of the pic to create.
• routing_strategy - a dictionary of routing strategies to use for pic generation.

Returns:

a dynamically-generated function for the yaml file.

gdsfactory.read.from_np¶

Read component from a numpy.ndarray.

compute_area_signed¶

def compute_area_signed(pr) -> float

Return the signed area enclosed by a ring using the linear time.

algorithm at http://www.cgafaq.info/wiki/Polygon_Area. A value >= 0 indicates a counter-clockwise oriented ring.

from_np¶

@cell_without_validator
def from_np(ndarray: np.ndarray,
            nm_per_pixel: int = 20,
            layer: tuple[int, int] = (1, 0),
            threshold: float = 0.99,
            invert: bool = True) -> Component

Returns Component from a np.ndarray.

Extracts contours skimage.measure.find_contours using threshold.

Arguments:

• ndarray - 2D ndarray representing the device layout.
• nm_per_pixel - scale_factor.
• layer - layer tuple to output gds.
• threshold - value along which to find contours in the array.
• invert - invert the mask.

from_image¶

@cell_without_validator
def from_image(image_path: str, **kwargs) -> Component

Returns Component from a png image.

Arguments:

• image_path - png file path.

Arguments:

• nm_per_pixel - scale_factor.
• layer - layer tuple to output gds.
• threshold - value along which to find contours in the array.

gdsfactory.read.from_yaml¶

Returns Component from YAML syntax.

name: myComponent settings: length: 3

info: description: just a demo polarization: TE ...

instances: mzi: component: mzi_phase_shifter settings: delta_length: ${settings.length} length_x: 50

pads:
    component: pad_array
    settings:
        n: 2
        port_names:
            - e4

placements: mzi: x: 0 pads: y: 200 x: mzi,cc ports: o1: mzi,o1 o2: mzi,o2

routes: electrical: links: mzi,etop_e1: pads,e4_0 mzi,etop_e2: pads,e4_1

    settings:
        layer: [31, 0]
        width: 10
        radius: 10

place¶

def place(placements_conf: dict[str, dict[str, int | float | str]],
          connections_by_transformed_inst: dict[str, dict[str, str]],
          instances: dict[str, ComponentReference],
          encountered_insts: list[str],
          instance_name: str | None = None,
          all_remaining_insts: list[str] | None = None) -> None

Place instance_name based on placements_conf config.

Arguments:

• placements_conf - Dict of instance_name to placement (x, y, rotation ...).
• connections_by_transformed_inst - Dict of connection attributes. keyed by the name of the instance which should be transformed.
• instances - Dict of references.
• encountered_insts - list of encountered_instances.
• instance_name - instance_name to place.
• all_remaining_insts - list of all the remaining instances to place instances pop from this instance as they are placed.

transform_connections_dict¶

def transform_connections_dict(
        connections_conf: dict[str, str]) -> dict[str, dict]

Returns Dict with source_instance_name key and connection properties.

make_connection¶

def make_connection(instance_src_name: str, port_src_name: str,
                    instance_dst_name: str, port_dst_name: str,
                    instances: dict[str, ComponentReference]) -> None

Connect instance_src_name,port to instance_dst_name,port.

Arguments:

• instance_src_name - source instance name.
• port_src_name - from instance_src_name.
• instance_dst_name - destination instance name.
• port_dst_name - from instance_dst_name.
• instances - dict of instances.

cell_from_yaml¶

def cell_from_yaml(yaml_str: str | pathlib.Path | IO[Any] | dict[str, Any]
                   | DictConfig,
                   routing_strategy: dict[str, Callable] | None = None,
                   label_instance_function: Callable = add_instance_label,
                   name: str | None = None,
                   prefix: str | None = None,
                   **kwargs) -> Callable

Returns Component factory from YAML string or file.

YAML includes instances, placements, routes, ports and connections.

Arguments:

• yaml - YAML string or file.

• routing_strategy - for each route.

• label_instance_function - to label each instance.

• name - Optional name.

• prefix - name prefix.

• kwargs - function settings for creating YAML PCells.

  .. code::

  valid variables:

• name - Optional Component name

• settings - Optional variables

• pdk - overrides

• info - Optional component info

• description - just a demo

• polarization - TE ... instances: name:

• component - (ComponentSpec) settings (Optional)

• length - 10 ... placements:

• x - float, str | None str can be instanceName,portName

• y - float, str | None

• rotation - float | None

• mirror - bool, float | None float is x mirror axis

• port - str | None port anchor

• connections Optional - between instances

• ports Optional - ports to expose

• routes Optional - bundles of routes routeName:

• library - optical links:

• instance1,port1 - instance2,port2

  .. code::

  settings:

• length_mmi - 5

  instances: mmi_bot:

• component - mmi1x2 settings:

• width_mmi - 4.5

• length_mmi - 10 mmi_top:

• component - mmi1x2 settings:

• width_mmi - 4.5

• length_mmi - ${settings.length_mmi}

  placements: mmi_top:

• port - o1

• x - 0

• y - 0 mmi_bot:

• port - o1

• x - mmi_top,o2

• y - mmi_top,o2

• dx - 30

• dy - -30 routes: optical:

• library - optical links:

• mmi_top,o3 - mmi_bot,o1

from_yaml¶

def from_yaml(yaml_str: str | pathlib.Path | IO[Any] | dict[str, Any]
              | DictConfig,
              routing_strategy: dict[str, Callable] | None = None,
              label_instance_function: Callable = add_instance_label,
              name: str | None = None,
              prefix: str | None = None,
              **kwargs) -> Component

Returns Component from YAML string or file.

YAML includes instances, placements, routes, ports and connections.

Arguments:

• yaml - YAML string or file.

• routing_strategy - for each route.

• label_instance_function - to label each instance.

• name - Optional name.

• prefix - name prefix.

• kwargs - function settings for creating YAML PCells.

  .. code::

  valid variables:

• name - Optional Component name

• settings - Optional variables

• pdk - overrides

• info - Optional component info

• description - just a demo

• polarization - TE ... instances: name:

• component - (ComponentSpec) settings (Optional)

• length - 10 ... placements:

• x - float, str | None str can be instanceName,portName

• y - float, str | None

• rotation - float | None

• mirror - bool, float | None float is x mirror axis

• port - str | None port anchor

• connections Optional - between instances

• ports Optional - ports to expose

• routes Optional - bundles of routes routeName:

• library - optical links:

• instance1,port1 - instance2,port2

  .. code::

  settings:

• length_mmi - 5

  instances: mmi_bot:

• component - mmi1x2 settings:

• width_mmi - 4.5

• length_mmi - 10 mmi_top:

• component - mmi1x2 settings:

• width_mmi - 4.5

• length_mmi - ${settings.length_mmi}

  placements: mmi_top:

• port - o1

• x - 0

• y - 0 mmi_bot:

• port - o1

• x - mmi_top,o2

• y - mmi_top,o2

• dx - 30

• dy - -30 routes: optical:

• library - optical links:

• mmi_top,o3 - mmi_bot,o1

gdsfactory.read.from_updk¶

Read uPDK YAML definition and returns a gdsfactory script.

https://openepda.org/index.html

from_updk¶

def from_updk(filepath: PathType,
              filepath_out: PathType | None = None,
              layer_bbox: tuple[int, int] = (68, 0),
              layer_bbmetal: tuple[int, int] | None = None,
              layer_label: tuple[int, int] | None = None,
              layer_pin_label: tuple[int, int] | None = None,
              layer_pin: tuple[int, int] | None = None,
              optical_xsections: list[str] | None = None,
              electrical_xsections: list[str] | None = None,
              layers_text: list[LayerSpec] | None = None,
              text_size: float = 2.0,
              activate_pdk: bool = False,
              read_xsections: bool = True,
              prefix: str = "",
              suffix: str = "") -> str

Read uPDK definition and returns a gdsfactory script.

Arguments:

• filepath - uPDK filepath definition.
• filepath_out - optional filepath to save script. if None only returns script and does not save it.
• layer_bbox - layer to draw bounding boxes.
• layer_bbmetal - layer to draw bounding boxes for metal.
• optical_xsections - Optional list of names of xsections that will add optical ports.
• electrical_xsections - Optional list of names of xsections that will add electrical ports.
• layers_text - Optional list of layers to add text labels.
• text_size - text size for labels.
• activate_pdk - if True, activate the pdk after writing the script.
• read_xsections - if True, read xsections from uPDK.
• prefix - optional prefix to add to the script.
• suffix - optional suffix to add to the script.

gdsfactory.export.to_gerber¶

Based on Gerber file spec: https://www.ucamco.com/files/downloads/file_en/456/gerber-layer-format-specification-revision-2022-02_en.pdf

See Also:

• https://github.com/opiopan/pcb-tools-extension
• https://github.com/jamesbowman/cuflow/blob/master/gerber.py

to_gerber¶

def to_gerber(
    component: Component,
    dirpath: Path,
    layermap_to_gerber_layer: dict[tuple[int, int], GerberLayer],
    options: GerberOptions = Field(default_factory=dict)
) -> None

Writes each layer to a different Gerber file.

Arguments:

• component - to export.
• dirpath - directory path.
• layermap_to_gerber_layer - map of GDS layer to GerberLayer.
• options - to save.
• header - List[str] | None = None
• mode - Literal[“mm”, “in”] = “mm”
• resolution - float = 1e-6
• int_size - int = 4

gdsfactory.export¶

gdsfactory.export.to_np¶

to_np¶

def to_np(component: Component,
          nm_per_pixel: int = 20,
          layers: Layers = ((1, 0), ),
          values: Floats | None = None,
          pad_width: int = 1) -> np.ndarray

Returns a pixelated numpy array from Component polygons.

Arguments:

• component - Component.
• nm_per_pixel - you can go from 20 (coarse) to 4 (fine).
• layers - to convert. Order matters (latter overwrite former).
• values - associated to each layer (defaults to 1).
• pad_width - padding pixels around the image.

gdsfactory.export.to_stl¶

to_stl¶

def to_stl(component: Component,
           filepath: str,
           layer_stack: LayerStack | None = None,
           exclude_layers: tuple[Layer, ...] | None = None,
           use_layer_name: bool = False,
           hull_invalid_polygons: bool = True,
           scale: float | None = None) -> None

Exports a Component into STL.

Arguments:

• component - to export.
• filepath - filepath prefix to write STL to. Each file will have each exported layer as suffix.
• layer_stack - contains thickness and zmin for each layer.
• exclude_layers - layers to exclude.
• use_layer_name - If True, uses LayerLevel names in output filenames rather than gds_layer and gds_datatype.
• hull_invalid_polygons - If True, replaces invalid polygons (determined by shapely.Polygon.is_valid) with its convex hull.
• scale - Optional factor by which to scale meshes before writing.

gdsfactory.export.to_3d¶

to_3d¶

def to_3d(component: Component,
          layer_views: LayerViews | None = None,
          layer_stack: LayerStack | None = None,
          exclude_layers: tuple[Layer, ...] | None = None)

Return Component 3D trimesh Scene.

Arguments:

• component - to extrude in 3D.
• layer_views - layer colors from Klayout Layer Properties file. Defaults to active PDK.layer_views.
• layer_stack - contains thickness and zmin for each layer. Defaults to active PDK.layer_stack.
• exclude_layers - layers to exclude.

gdsfactory.add_keepout¶

add_keepout¶

@cell
def add_keepout(component: Component,
                target_layers: Layers,
                keepout_layers: Layers,
                margin: float = 2.0) -> Component

Adds keepout after looking up all polygons in a cell.

You can also use add_padding for rectangular keepout.

Arguments:

• component - to add keepout.
• target_layers - list of layers to read.
• keepout_layers - list of layers to add keepout.
• margin - offset from target to keepout_layers.

gdsfactory.typings¶

In programming, a factory is a function that returns an object.

Functions are easy to understand because they have clear inputs and outputs. Most gdsfactory functions take some inputs and return a Component object. Some of these inputs parameters are also functions.

• Component: Object with.
  • name.
  • references: to other components (x, y, rotation).
  • polygons in different layers.
  • ports dict.
• Route: dataclass with 3 attributes.
  • references: list of references (straights, bends and tapers).
  • ports: dict(input=PortIn, output=PortOut).
  • length: how long is this route?

Factories:

• ComponentFactory: function that returns a Component.
• RouteFactory: function that returns a Route.

Specs:

• ComponentSpec: Component, function, string or dict (component=mzi, settings=dict(delta_length=20)).
• LayerSpec: (3, 0), 3 (assumes 0 as datatype) or string.

Step Objects¶

@dataclasses.dataclass
class Step()

Manhattan Step.

Arguments:

• x - absolute.
• y - absolute.
• dx - x-displacement.
• dy - y-displacement.

StepAllAngle Objects¶

@dataclasses.dataclass
class StepAllAngle()

separation¶

All angle Ste.

Arguments:

• x - absolute.
• y - absolute.
• dx - x-displacement.
• dy - y-displacement.
• exit_angle - in degrees.
• cross_section - spec.
• connector - define transition.
• separation - in um.

Layer¶

Tuple of integer (layer, datatype)

LayerSpec¶

tuple of integers (layer, datatype), a integer (layer, 0) or a string (layer_name)

ComponentSpec¶

PCell function, function name, dict or Component

CellSpec¶

PCell function, function name or dict

CrossSectionSpec¶

cross_section function, function name or dict

NetlistModel Objects¶

class NetlistModel(BaseModel)

Netlist defined component.

Arguments:

• instances - dict of instances (name, settings, component).
• placements - dict of placements.
• connections - dict of connections.
• routes - dict of routes.
• name - component name.
• info - information (polarization, wavelength ...).
• settings - input variables.
• ports - exposed component ports.

TypedArray Objects¶

class TypedArray(np.ndarray)

based on https://github.com/samuelcolvin/pydantic/issues/380.

gdsfactory.get_netlist¶

Extract netlist from component port connectivity.

Assumes two ports are connected when they have same width, x, y

.. code:: yaml

connections:
    - coupler,N0:bendLeft,W0
    - coupler,N1:bendRight,N0
    - bednLeft,N0:straight,W0
    - bendRight,N0:straight,E0

ports:
    - coupler,E0
    - coupler,W0

get_instance_name_from_alias¶

def get_instance_name_from_alias(component: Component,
                                 reference: ComponentReference) -> str

Returns the instance name from the label.

If no label returns to instanceName_x_y.

Arguments:

• component - with labels.
• reference - reference that needs naming.

get_instance_name_from_label¶

def get_instance_name_from_label(
        component: Component,
        reference: ComponentReference,
        layer_label: LayerSpec = "LABEL_INSTANCE") -> str

Returns the instance name from the label.

If no label returns to instanceName_x_y.

Arguments:

• component - with labels.
• reference - reference that needs naming.
• layer_label - ignores layer_label[1].

get_netlist_yaml¶

def get_netlist_yaml(component: Component,
                     full_settings: bool = False,
                     tolerance: int = 5,
                     exclude_port_types: list | None = None,
                     **kwargs) -> str

Returns instances, connections and placements yaml string content.

get_netlist¶

def get_netlist(
        component: Component,
        full_settings: bool = False,
        tolerance: int = 5,
        exclude_port_types: list[str] | tuple[str] | None = ("placement", ),
        get_instance_name: Callable[..., str] = get_instance_name_from_alias,
        allow_multiple: bool = False) -> dict[str, Any]

From Component returns instances, connections and placements dict.

Does two sweeps over the connections:

1. first tries to connect everything assuming perfect connections at each port.
2. Then gathers ports which did not perfectly connect to anything and tries to find imperfect connections, by grouping ports on a coarse grid.

warnings collected during netlisting are reported back into the netlist. These include warnings about mismatched port widths, orientations, shear angles, excessive offsets, etc. You can also configure warning types which should throw an error when encountered by modifying DEFAULT_CRITICAL_CONNECTION_ERROR_TYPES. Validators, which will produce warnings for each port type, can be overridden with DEFAULT_CONNECTION_VALIDATORS A key difference in this algorithm is that we group each port type independently. This allows us to use different logic to determine i.e. if an electrical port is properly connected vs an optical port. In this function, the core logic is the same, but we employ extra validation for optical ports. snap_to_grid() allows a value of 0, which will return the original value, is more efficient when the value is 1, and will throw a more descriptive error when the value is <0 the default value of tolerance is 5nm because it should allow better performance with the two-grid-sweep approach.

Arguments:

• component - to extract netlist.
• full_settings - True returns all, false changed settings.
• tolerance - tolerance in nm to consider two ports connected.
• exclude_port_types - optional list of port types to exclude from netlisting.
• get_instance_name - function to get instance name.
• allow_multiple - False to raise an error if more than two ports share the same connection. if True, will return key: [value] pairs with [value] a list of all connected instances.

Returns:

• instances - Dict of instance name and settings.
• connections - Dict of Instance1Name,portName: Instance2Name,portName.
• placements - Dict of instance names and placements (x, y, rotation).
• port - Dict portName: ComponentName,port.
• name - name of component.
• warnings - warning messages (disconnected pins).

get_netlist_recursive¶

def get_netlist_recursive(component: Component,
                          component_suffix: str = "",
                          get_netlist_func: Callable = get_netlist,
                          get_instance_name: Callable[
                              ..., str] = get_instance_name_from_alias,
                          **kwargs) -> dict[str, Any]

Returns recursive netlist for a component and subcomponents.

Arguments:

• component - to extract netlist.
• component_suffix - suffix to append to each component name. useful if to save and reload a back-annotated netlist.
• get_netlist_func - function to extract individual netlists.

Arguments:

• full_settings - True returns all, false changed settings.
• tolerance - tolerance in nm to consider two ports connected.
• exclude_port_types - optional list of port types to exclude from netlisting.
• get_instance_name - function to get instance name.

Returns:

Dictionary of netlists, keyed by the name of each component.

gdsfactory.decorators¶

is_valid_transformation¶

def is_valid_transformation(ref: ComponentReference,
                            grid_size: float | None = None) -> bool

Returns True if the component has valid transformations.

Arguments:

• component - the component reference to check.
• grid_size - the GDS grid size, in um, defaults to active PDK.get_grid_size() any translations with higher resolution than this are considered invalid.

has_valid_transformations¶

def has_valid_transformations(component: Component) -> bool

Returns True if the component has valid transformations.

flatten_invalid_refs¶

def flatten_invalid_refs(component: Component, grid_size: float | None = None)

Flattens component references which have invalid transformations.

(i.e. non-90 deg rotations or sub-grid translations).

This is an in-place operation, so you should use it as a decorator. flattens only individual references with invalid transformations.

Deprecated Use Component.write_gds(flatten_invalid_refs=True)

Arguments:

• component - the component to fix (in place).
• grid_size - the GDS grid size, in um, defaults to active PDK.get_grid_size() any translations with higher resolution than this are considered invalid.

gdsfactory.component_layout¶

Helper functions for layout.

Adapted from PHIDL https://github.com/amccaugh/phidl/ by Adam McCaughan

get_polygons¶

def get_polygons(
    instance,
    by_spec: bool | tuple[int, int] = False,
    depth: int | None = None,
    include_paths: bool = True,
    as_array: bool = True,
    as_shapely: bool = False,
    as_shapely_merged: bool = False
) -> list[Polygon] | dict[tuple[int, int], list[Polygon]]

Return a list of polygons in this cell.

Arguments:

• by_spec - bool or layer If True, the return value is a dictionary with the polygons of each individual pair (layer, datatype), which are used as keys. If set to a tuple of (layer, datatype), only polygons with that specification are returned.

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

• include_paths - If True, polygonal representation of paths are also included in the result.

• as_array - when as_array=false, return the Polygon objects instead. polygon objects have more information (especially when by_spec=False) and are faster to retrieve.

• as_shapely - returns shapely polygons.

  Returns

• out - list of array-like[N][2] or dictionary List containing the coordinates of the vertices of each polygon, or dictionary with with the list of polygons (if by_spec is True).

Notes:

Instances of FlexPath and RobustPath are also included in the result by computing their polygonal boundary.

_GeometryHelper Objects¶

class _GeometryHelper()

Helper class for a class with functions move() and the property bbox.

It uses that function+property to enable you to do things like check what the center of the bounding box is (self.center), and also to do things like move the bounding box such that its maximum x value is 5.2 (self.xmax = 5.2).

center¶

@property
def center()

Returns the center of the bounding box.

center¶

@center.setter
def center(destination) -> None

Sets the center of the bounding box.

Arguments:

destination : array-like[2] Coordinates of the new bounding box center.

x¶

@property
def x()

Returns the x-coordinate of the center of the bounding box.

x¶

@x.setter
def x(destination) -> None

Sets the x-coordinate of the center of the bounding box.

Arguments:

destination : int or float x-coordinate of the bbox center.

y¶

@property
def y()

Returns the y-coordinate of the center of the bounding box.

y¶

@y.setter
def y(destination) -> None

Sets the y-coordinate of the center of the bounding box.

Arguments:

destination : int or float y-coordinate of the bbox center.

xmax¶

@property
def xmax()

Returns the maximum x-value of the bounding box.

xmax¶

@xmax.setter
def xmax(destination) -> None

Sets the x-coordinate of the maximum edge of the bounding box.

Arguments:

destination : int or float x-coordinate of the maximum edge of the bbox.

ymax¶

@property
def ymax()

Returns the maximum y-value of the bounding box.

ymax¶

@ymax.setter
def ymax(destination) -> None

Sets the y-coordinate of the maximum edge of the bounding box.

Arguments:

destination : int or float y-coordinate of the maximum edge of the bbox.

xmin¶

@property
def xmin()

Returns the minimum x-value of the bounding box.

xmin¶

@xmin.setter
def xmin(destination) -> None

Sets the x-coordinate of the minimum edge of the bounding box.

Arguments:

destination : int or float x-coordinate of the minimum edge of the bbox.

ymin¶

@property
def ymin()

Returns the minimum y-value of the bounding box.

ymin¶

@ymin.setter
def ymin(destination) -> None

Sets the y-coordinate of the minimum edge of the bounding box.

Arguments:

destination : int or float y-coordinate of the minimum edge of the bbox.

size¶

@property
def size()

Returns the (x, y) size of the bounding box.

xsize¶

@property
def xsize()

Returns the horizontal size of the bounding box.

ysize¶

@property
def ysize()

Returns the vertical size of the bounding box.

movex¶

def movex(origin=0, destination=None)

Moves an object by a specified x-distance.

Arguments:

• origin - array-like[2], Port, or key Origin point of the move.
• destination - array-like[2], Port, key, or None Destination point of the move.

movey¶

def movey(origin=0, destination=None)

Moves an object by a specified y-distance.

Arguments:

origin : array-like[2], Port, or key Origin point of the move. destination : array-like[2], Port, or key Destination point of the move.

__add__¶

def __add__(element) -> Group

Adds an element to a Group.

Arguments:

• element - Component, ComponentReference, Port, Polygon, Label, or Group to add.

Group Objects¶

class Group(_GeometryHelper)

Group objects together so you can manipulate them as a single object (move/rotate/mirror).

__init__¶

def __init__(*args) -> None

Initialize Group.

__repr__¶

def __repr__() -> str

Prints the number of elements in the Group.

__len__¶

def __len__() -> float

Returns the number of elements in the Group.

__iadd__¶

def __iadd__(element) -> Group

Adds an element to the Group.

Arguments:

• element - Component, ComponentReference, Port, Polygon, Label, or Group to add.

bbox¶

@property
def bbox()

Returns the bounding boxes of the Group.

add¶

def add(element) -> Group

Adds an element to the Group.

Arguments:

• element - Component, ComponentReference, Port, Polygon, Label, or Group to add.

rotate¶

def rotate(angle: float = 45, center=(0, 0)) -> Group

Rotates all elements in a Group around the specified centerpoint.

Arguments:

angle : int or float Angle to rotate the Group in degrees. center : array-like[2] or None center of the Group.

move¶

def move(origin=(0, 0), destination=None, axis=None) -> Group

Moves the Group from the origin point to the destination.

Both origin and destination can be 1x2 array-like, Port, or a key corresponding to one of the Ports in this Group.

Arguments:

origin : array-like[2], Port, or key Origin point of the move. destination : array-like[2], Port, or key Destination point of the move. axis : {‘x’, ‘y’} Direction of the move.

mirror¶

def mirror(p1=(0, 1), p2=(0, 0)) -> Group

Mirrors a Group across the line formed between the two specified points.

points may be input as either single points [1,2] or array-like[N][2], and will return in kind.

Arguments:

p1 : array-like[N][2] First point of the line. p2 : array-like[N][2] Second point of the line.

distribute¶

def distribute(direction="x",
               spacing=100,
               separation=True,
               edge="center") -> Group

Distributes the elements in the Group.

Arguments:

direction : {‘x’, ‘y’} Direction of distribution; either a line in the x-direction or y-direction. spacing : int or float Distance between elements. separation : bool If True, guarantees elements are separated with a fixed spacing between; if False, elements are spaced evenly along a grid. edge : {‘x’, ‘xmin’, ‘xmax’, ‘y’, ‘ymin’, ‘ymax’} Which edge to perform the distribution along (unused if separation == True)

align¶

def align(alignment="ymax") -> Group

Aligns the elements in the Group.

Arguments:

alignment : {‘x’, ‘y’, ‘xmin’, ‘xmax’, ‘ymin’, ‘ymax’} Which edge to align along (e.g. ‘ymax’ will align move the elements such that all of their topmost points are aligned)

gdsfactory.add_padding¶

get_padding_points¶

def get_padding_points(component: Component,
                       default: float = 50.0,
                       top: float | None = None,
                       bottom: float | None = None,
                       right: float | None = None,
                       left: float | None = None) -> list[float]

Returns padding points for a component outline.

Arguments:

• component - to add padding.
• default - default padding in um.
• top - north padding in um.
• bottom - south padding in um.
• right - east padding in um.
• left - west padding in um.

add_padding¶

def add_padding(component: ComponentSpec = "mmi2x2",
                layers: tuple[LayerSpec, ...] = ("PADDING", ),
                **kwargs) -> Component

Adds padding layers to component. Returns same component.

Arguments:

• component - to add padding.

• layers - list of layers.

  keyword Args:

• default - default padding.

• top - north padding in um.

• bottom - south padding in um.

• right - east padding in um.

• left - west padding in um.

add_padding_container¶

@cell
def add_padding_container(component: ComponentSpec,
                          layers: tuple[LayerSpec, ...] = ("PADDING", ),
                          **kwargs) -> Component

Returns new component with padding added.

Arguments:

• component - to add padding.
• layers - list of layers.

Arguments:

• default - default padding in um.
• top - north padding in um.
• bottom - south padding in um.
• right - east padding in um.
• left - west padding in um.

add_padding_to_size¶

def add_padding_to_size(component: ComponentSpec,
                        layers: tuple[LayerSpec, ...] = ("PADDING", ),
                        xsize: float | None = None,
                        ysize: float | None = None,
                        left: float = 0,
                        bottom: float = 0) -> Component

Returns component with padding layers on each side.

New size is multiple of grid size.

Arguments:

• component - to add padding.
• layers - list of layers.
• xsize - x size to fill up in um.
• ysize - y size to fill up in um.
• left - left padding in um to fill up in um.
• bottom - bottom padding in um to fill up in um.

add_padding_to_size_container¶

@cell
def add_padding_to_size_container(component: ComponentSpec,
                                  layers: tuple[LayerSpec,
                                                ...] = ("PADDING", ),
                                  xsize: float | None = None,
                                  ysize: float | None = None,
                                  left: float = 0,
                                  bottom: float = 0) -> Component

Returns new component with padding layers on each side. New size is.

multiple of grid size.

Arguments:

• component - to add padding.
• layers - list of layers.
• xsize - x size to fill up in um.
• ysize - y size to fill up in um.
• left - left padding in um to fill up in um.
• bottom - bottom padding in um to fill up in um.

gdsfactory.pixelate¶

pixelate_path¶

def pixelate_path(pts: Coordinates,
                  pixel_size: float = 0.55,
                  snap_res: float = 0.05,
                  middle_offset: float = 0.5,
                  theta_start: float = 0,
                  theta_end: float = 90) -> Coordinates

From a path add one pixel per point on the path.

Arguments:

• pts - points.
• pixel_size - in um.
• snap_res - snap resolution.
• middle_offset - in um.
• theta_start - in degrees.
• theta_end - in degrees.

pixelate¶

def pixelate(pts, N=100, margin=0.4, **kwargs)

Pixelate shape defined by points Return rectangles [Rect1, Rect2, ...] ready to go in the quad tree.

gdsfactory.show¶

show¶

def show(component: Component | str | pathlib.Path,
         technology: str | None = None,
         **kwargs) -> None

Write GDS and show Component in KLayout.

Arguments:

• component - Component or GDS path.
• technology - Name of KLayout technology to load when displaying component.

Arguments:

• gdspath - GDS file path to write to.
• gdsdir - directory for the GDS file. Defaults to /tmp/.
• unit - unit size for objects in library. 1um by default.
• precision - for object dimensions in the library (m). 1nm by default.
• timestamp - Defaults to 2019-10-25. If None uses current time.

gdsfactory.cross_section¶

You can define a path as list of points.

To create a component you need to extrude the path with a cross-section.

Section Objects¶

class Section(BaseModel)

CrossSection to extrude a path with a waveguide.

Arguments:

• width - of the section (um) or parameterized function from 0 to 1. the width at t==0 is the width at the beginning of the Path. the width at t==1 is the width at the end.

• offset - center offset (um) or function parameterized function from 0 to 1. the offset at t==0 is the offset at the beginning of the Path. the offset at t==1 is the offset at the end.

• insets - distance (um) in x to inset section relative to end of the Path (i.e. (start inset, stop_inset)).

• layer - layer spec. If None does not draw the main section.

• port_names - Optional port names.

• port_types - optical, electrical, ...

• name - Optional Section name.

• hidden - hide layer.

• simplify - Optional Tolerance value for the simplification algorithm. All points that can be removed without changing the resulting. polygon by more than the value listed here will be removed.

  .. code::

  0 offset |<-------------->| | _____ | | | | |layer| | |_____| | <----> width

ComponentAlongPath Objects¶

class ComponentAlongPath(BaseModel)

A ComponentAlongPath object to place along an extruded path.

Arguments:

• component - Component to repeat along the path. The unrotated version of this object should be oriented for placement on a horizontal line.
• spacing - distance between component placements
• padding - minimum distance from the path start to the first component.
• y_offset - offset in y direction (um).

CrossSection Objects¶

class CrossSection(BaseModel)

Waveguide information to extrude a path.

cladding_layers follow path shape, while bbox_layers are rectangular.

Arguments:

• layer - main Section layer. Main section name = ‘_default’. If None does not draw the main section.

• width - main Section width (um) or function parameterized from 0 to 1. the width at t==0 is the width at the beginning of the Path. the width at t==1 is the width at the end.

• offset - main Section center offset (um) or function from 0 to 1. the offset at t==0 is the offset at the beginning of the Path. the offset at t==1 is the offset at the end.

• radius - main Section bend radius (um).

• simplify - main Section Optional Tolerance value for the simplification algorithm.

• width_wide - wide waveguides width (um) for low loss routing.

• auto_widen - taper to wide waveguides for low loss routing.

• auto_widen_minimum_length - minimum straight length for auto_widen.

• taper_length - taper_length for auto_widen.

• bbox_layers - list of layers for rectangular bounding box.

• bbox_offsets - list of bounding box offsets.

• cladding_layers - list of layers to extrude.

• cladding_offsets - list of offset from main Section edge.

• cladding_simplify - Optional Tolerance value for the simplification algorithm. All points that can be removed without changing the resulting. polygon by more than the value listed here will be removed.

• sections - list of Sections(width, offset, layer, ports).

• port_names - for input and output (‘o1’, ‘o2’).

• port_types - for input and output: electrical, optical, vertical_te ...

• gap - edge to edge waveguide spacing for routing.

• min_length - defaults to 1nm = 10e-3um for routing.

• start_straight_length - straight length at the beginning of the route.

• end_straight_length - end length at the beginning of the route.

• snap_to_grid - Optional snap points to grid when extruding paths (um).

• decorator - function when extruding component. For example add_pins.

• add_pins - Optional function to add pins.

• add_bbox - Optional function to add bounding box.

• info - dict with extra settings or useful information.

• name - cross_section name.

• mirror - if True, reflects the offsets.

• vias - list of ComponentAlongPaths(component, spacing, padding, offset).

  Properties:

• aliases - dict of cross_section aliases.

copy¶

def copy(**kwargs)

Returns a CrossSection copy.

add_bbox_layers¶

def add_bbox_layers(component,
                    top: float | None = None,
                    bottom: float | None = None,
                    right: float | None = None,
                    left: float | None = None)

Add bounding box layers to a component.

Arguments:

• component - to add layers.
• top - top padding.
• bottom - bottom padding.
• right - right padding.
• left - left padding.

get_xmin_xmax¶

def get_xmin_xmax()

Returns the min and max extent of the cross_section across all sections.

Transition Objects¶

class Transition(CrossSection)

Waveguide information to extrude a path between two CrossSection.

cladding_layers follow path shape, while bbox_layers are rectangular.

Arguments:

• cross_section1 - input cross_section.
• cross_section2 - output cross_section.
• width_type - sine or linear. Sets the type of width transition used if any widths are different between the two input CrossSections.
• sections - list of Sections(width, offset, layer, ports).
• layer - main Section layer. Main section name = ‘_default’.
• width - main Section width (um) or function parameterized from 0 to 1. the width at t==0 is the width at the beginning of the Path. the width at t==1 is the width at the end.
• snap_to_grid - Optional snap points to grid when extruding paths (um).
• radius - main Section bend radius (um).
• width_wide - wide waveguides width (um) for low loss routing.
• auto_widen - taper to wide waveguides for low loss routing.
• auto_widen_minimum_length - minimum straight length for auto_widen.
• taper_length - taper_length for auto_widen.
• bbox_layers - list of layers for rectangular bounding box.
• bbox_offsets - list of bounding box offsets.
• cladding_layers - list of layers to extrude.
• cladding_offsets - list of offset from main Section edge.
• cladding_simplify - Optional Tolerance value for the simplification algorithm. All points that can be removed without changing the resulting. polygon by more than the value listed here will be removed.
• sections - list of Sections(width, offset, layer, ports).
• port_names - for input and output (‘o1’, ‘o2’).
• port_types - for input and output: electrical, optical, vertical_te ...
• gap - edge to edge waveguide spacing for routing.
• min_length - defaults to 1nm = 10e-3um for routing.
• start_straight_length - straight length at the beginning of the route.
• end_straight_length - end length at the beginning of the route.
• snap_to_grid - Optional snap points to grid when extruding paths (um).
• decorator - function when extruding component. For example add_pins.
• add_pins - Optional function to add pins.
• add_bbox - Optional function to add bounding box.
• info - dict with extra settings or useful information.
• name - cross_section name.
• mirror - if True, reflects the offsets.

xsection¶

def xsection(func: _F) -> _F

Decorator for CrossSection functions

Validates type annotations with pydantic.

.. plot:: :include-source:

import gdsfactory as gf

@gf.cross_section.xsection
def xs_sc(width=0.5, **kwargs):
    xs = gf.cross_section.cross_section(width=width, **kwargs)
    return xs

p = gf.path.arc(radius=10, angle=45)
c = p.extrude(xs_sc)
c.plot()

cross_section¶

@xsection
def cross_section(width: Callable | float = 0.5,
                  offset: float | Callable = 0,
                  layer: LayerSpec | None = "WG",
                  width_wide: float | None = None,
                  auto_widen: bool = False,
                  auto_widen_minimum_length: float = 200.0,
                  taper_length: float = 10.0,
                  radius: float | None = 10.0,
                  sections: tuple[Section, ...] | None = None,
                  port_names: tuple[str, str] = ("o1", "o2"),
                  port_types: tuple[str, str] = ("optical", "optical"),
                  gap: float = 3.0,
                  min_length: float = 10e-3,
                  start_straight_length: float = 10e-3,
                  end_straight_length: float = 10e-3,
                  snap_to_grid: float | None = None,
                  bbox_layers: list[LayerSpec] | None = None,
                  bbox_offsets: list[float] | None = None,
                  cladding_layers: LayerSpecs | None = None,
                  cladding_offsets: Floats | None = None,
                  cladding_simplify: Floats | None = cladding_simplify_optical,
                  info: dict[str, Any] | None = None,
                  decorator: Callable | None = None,
                  add_pins: Callable | None = None,
                  add_bbox: Callable | None = None,
                  mirror: bool = False,
                  name: str | None = None) -> CrossSection

Return CrossSection.

Arguments:

• width - main Section width (um) or function parameterized from 0 to 1. the width at t==0 is the width at the beginning of the Path. the width at t==1 is the width at the end.

• offset - main Section center offset (um) or function from 0 to 1. the offset at t==0 is the offset at the beginning of the Path. the offset at t==1 is the offset at the end.

• layer - main section layer.

• width_wide - wide waveguides width (um) for low loss routing.

• auto_widen - taper to wide waveguides for low loss routing.

• auto_widen_minimum_length - minimum straight length for auto_widen.

• taper_length - taper_length for auto_widen.

• radius - bend radius (um).

• sections - list of Sections(width, offset, layer, ports).

• port_names - for input and output (‘o1’, ‘o2’).

• port_types - for input and output: electrical, optical, vertical_te ...

• gap - edge to edge waveguide gap for routing.

• min_length - defaults to 1nm = 10e-3um for routing.

• start_straight_length - straight length at the beginning of the route.

• end_straight_length - end length at the beginning of the route.

• snap_to_grid - can snap points to grid when extruding the path.

• bbox_layers - list of layers for rectangular bounding box.

• bbox_offsets - list of bounding box offsets.

• cladding_layers - list of layers to extrude.

• cladding_offsets - list of offset from main Section edge.

• cladding_simplify - Optional Tolerance value for the simplification algorithm. All points that can be removed without changing the resulting. polygon by more than the value listed here will be removed.

• info - settings info.

• decorator - function to run when converting path to component.

• add_pins - optional function to add pins to component.

• add_bbox - optional function to add bounding box to component.

• mirror - if True, reflects the offsets.

• name - cross_section name.

  .. plot:: :include-source:

  import gdsfactory as gf

  xs = gf.cross_section.cross_section(width=0.5, offset=0, layer=‘WG’) p = gf.path.arc(radius=10, angle=45) c = p.extrude(xs) c.plot()

slot¶

@xsection
def slot(width: float = 0.5,
         layer: LayerSpec = "WG",
         slot_width: float = 0.04,
         **kwargs) -> CrossSection

Return CrossSection Slot (with an etched region in the center).

Arguments:

• width - main Section width (um) or function parameterized from 0 to 1. the width at t==0 is the width at the beginning of the Path. the width at t==1 is the width at the end.
• layer - main section layer.
• slot_width - in um.

Arguments:

• offset - main Section center offset (um) or function from 0 to 1. the offset at t==0 is the offset at the beginning of the Path. the offset at t==1 is the offset at the end.

• width_wide - wide waveguides width (um) for low loss routing.

• auto_widen - taper to wide waveguides for low loss routing.

• auto_widen_minimum_length - minimum straight length for auto_widen.

• taper_length - taper_length for auto_widen.

• radius - bend radius (um).

• sections - list of Sections(width, offset, layer, ports).

• port_names - for input and output (‘o1’, ‘o2’).

• port_types - for input and output: electrical, optical, vertical_te ...

• min_length - defaults to 1nm = 10e-3um for routing.

• start_straight_length - straight length at the beginning of the route.

• end_straight_length - end length at the beginning of the route.

• snap_to_grid - can snap points to grid when extruding the path.

• bbox_layers - list of layers for rectangular bounding box.

• bbox_offsets - list of bounding box offsets.

• cladding_layers - list of layers to extrude.

• cladding_offsets - list of offset from main Section edge.

• cladding_simplify - Optional Tolerance value for the simplification algorithm. All points that can be removed without changing the resulting. polygon by more than the value listed here will be removed.

• info - settings info.

• decorator - function to run when converting path to component.

• add_pins - optional function to add pins to component.

• add_bbox - optional function to add bounding box to component.

  .. plot:: :include-source:

  import gdsfactory as gf

  xs = gf.cross_section.slot(width=0.5, slot_width=0.05, layer=‘WG’) p = gf.path.arc(radius=10, angle=45) c = p.extrude(xs) c.plot()

rib_with_trenches¶

@xsection
def rib_with_trenches(width: float = 0.5,
                      width_trench: float = 2.0,
                      width_slab: float = 7.0,
                      simplify_slab: float | None = None,
                      layer: LayerSpec | None = "WG",
                      layer_trench: LayerSpec = "DEEP_ETCH",
                      wg_marking_layer: LayerSpec | None = None,
                      **kwargs) -> CrossSection

Return CrossSection of rib waveguide defined by trenches.

Arguments:

• width - main Section width (um) or function parameterized from 0 to 1. the width at t==0 is the width at the beginning of the Path. the width at t==1 is the width at the end.

• width_trench - in um.

• width_slab - in um.

• layer - ridge layer. None adds only ridge.

• layer_trench - layer to etch trenches.

• wg_marking_layer - layer to draw over the actual waveguide. This can be useful for booleans, routing, placement ...

• kwargs - cross_section settings.

  .. code::

  ---

  | | | | || ||

  ---

  <-------> | width_trench | <----------------------------------------> width_slab

  .. plot:: :include-source:

  import gdsfactory as gf

  xs = gf.cross_section.rib_with_trenches(width=0.5) p = gf.path.arc(radius=10, angle=45) c = p.extrude(xs) c.plot()

l_with_trenches¶

@xsection
def l_with_trenches(width: float = 0.5,
                    width_trench: float = 2.0,
                    width_slab: float = 7.0,
                    layer: LayerSpec | None = "WG",
                    layer_trench: LayerSpec = "DEEP_ETCH",
                    mirror: bool = False,
                    wg_marking_layer: LayerSpec | None = None,
                    **kwargs) -> CrossSection

Return CrossSection of l waveguide defined by trenches.

Arguments: