masque/masque/pattern.py

1485 lines
55 KiB
Python
Raw Normal View History

2016-03-15 19:12:39 -07:00
"""
2023-09-17 21:33:22 -07:00
Object representing a one multi-layer lithographic layout.
A single level of hierarchical references is included.
2016-03-15 19:12:39 -07:00
"""
from typing import cast, Self, Any, TypeVar
from collections.abc import Sequence, Mapping, MutableMapping, Iterable, Callable
2016-03-15 19:12:39 -07:00
import copy
2023-04-12 13:56:50 -07:00
import logging
import functools
2020-09-18 19:46:57 -07:00
from itertools import chain
2023-04-12 13:56:50 -07:00
from collections import defaultdict
2016-03-15 19:12:39 -07:00
import numpy
from numpy import inf, pi, nan
from numpy.typing import NDArray, ArrayLike
2016-03-15 19:12:39 -07:00
# .visualize imports matplotlib and matplotlib.collections
2023-01-21 23:38:53 -08:00
from .ref import Ref
from .abstract import Abstract
2023-04-12 13:56:50 -07:00
from .shapes import Shape, Polygon, Path, DEFAULT_POLY_NUM_VERTICES
2018-08-30 23:06:31 -07:00
from .label import Label
from .utils import rotation_matrix_2d, annotations_t, layer_t, annotations_eq, annotations_lt, layer2key
from .utils import ports_eq, ports_lt
from .error import PatternError, PortError
2023-04-12 13:56:50 -07:00
from .traits import AnnotatableImpl, Scalable, Mirrorable, Rotatable, Positionable, Repeatable, Bounded
2023-01-19 22:20:16 -08:00
from .ports import Port, PortList
2016-03-15 19:12:39 -07:00
2023-04-12 13:56:50 -07:00
logger = logging.getLogger(__name__)
@functools.total_ordering
2023-01-25 23:19:25 -08:00
class Pattern(PortList, AnnotatableImpl, Mirrorable):
2016-03-15 19:12:39 -07:00
"""
2023-10-07 01:54:16 -07:00
2D layout consisting of some set of shapes, labels, and references to other
Pattern objects (via Ref). Shapes are assumed to inherit from `masque.shapes.Shape`
or provide equivalent functions.
`Pattern` also stores a dict of `Port`s, which can be used to "snap" together points.
See `Pattern.plug()` and `Pattern.place()`, as well as the helper classes
`builder.Builder`, `builder.Pather`, `builder.RenderPather`, and `ports.PortsList`.
For convenience, ports can be read out using square brackets:
- `pattern['A'] == Port((0, 0), 0)`
- `pattern[['A', 'B']] == {'A': Port((0, 0), 0), 'B': Port((0, 0), pi)}`
Examples: Making a Pattern
==========================
- `pat = Pattern()` just creates an empty pattern, with no geometry or ports
- To immediately set some of the pattern's contents,
```
pat = Pattern(
shapes={'layer1': [shape0, ...], 'layer2': [shape,...], ...},
labels={'layer1': [...], ...},
refs={'name1': [ref0, ...], 'name2': [ref, ...], ...},
ports={'in': Port(...), 'out': Port(...)},
)
```
- `Pattern.interface(other_pat, port_map=['A', 'B'])` makes a new
(empty) pattern, copies over ports 'A' and 'B' from `other_pat`, and
creates additional ports 'in_A' and 'in_B' facing in the opposite
directions. This can be used to build a device which can plug into
`other_pat` (using the 'in_*' ports) but which does not itself include
`other_pat` as a subcomponent.
Examples: Adding to a pattern
=============================
- `pat.plug(subdevice, {'A': 'C', 'B': 'B'}, map_out={'D': 'myport'})`
instantiates `subdevice` into `pat`, plugging ports 'A' and 'B'
of `pat` into ports 'C' and 'B' of `subdevice`. The connected ports
are removed and any unconnected ports from `subdevice` are added to
`pat`. Port 'D' of `subdevice` (unconnected) is renamed to 'myport'.
- `pat.plug(wire, {'myport': 'A'})` places port 'A' of `wire` at 'myport'
of `pat`. If `wire` has only two ports (e.g. 'A' and 'B'), since no `map_out`
argument is provided and the `inherit_name` argument is not explicitly
set to `False`, the unconnected port of `wire` is automatically renamed to
'myport'. This allows easy extension of existing ports without changing
their names or having to provide `map_out` each time `plug` is called.
- `pat.place(pad, offset=(10, 10), rotation=pi / 2, port_map={'A': 'gnd'})`
instantiates `pad` at the specified (x, y) offset and with the specified
rotation, adding its ports to those of `pat`. Port 'A' of `pad` is
renamed to 'gnd' so that further routing can use this signal or net name
rather than the port name on the original `pad` device.
2016-03-15 19:12:39 -07:00
"""
2023-01-23 22:27:26 -08:00
__slots__ = (
2023-01-24 23:25:10 -08:00
'shapes', 'labels', 'refs', '_ports',
2023-01-23 22:27:26 -08:00
# inherited
2023-11-18 12:28:51 -08:00
'_annotations',
2023-01-23 22:27:26 -08:00
)
2023-04-12 13:56:50 -07:00
shapes: defaultdict[layer_t, list[Shape]]
""" Stores of all shapes in this Pattern, indexed by layer.
Elements in this list are assumed to inherit from Shape or provide equivalent functions.
"""
2023-04-12 13:56:50 -07:00
labels: defaultdict[layer_t, list[Label]]
""" List of all labels in this Pattern. """
2023-04-12 13:56:50 -07:00
refs: defaultdict[str | None, list[Ref]]
2023-01-21 21:22:11 -08:00
""" List of all references to other patterns (`Ref`s) in this `Pattern`.
Multiple objects in this list may reference the same Pattern object
(i.e. multiple instances of the same object).
"""
2023-02-23 13:15:32 -08:00
_ports: dict[str, Port]
2023-01-19 22:20:16 -08:00
""" Uniquely-named ports which can be used to snap to other Pattern instances"""
2023-01-24 23:25:10 -08:00
@property
2023-02-23 13:15:32 -08:00
def ports(self) -> dict[str, Port]:
2023-01-24 23:25:10 -08:00
return self._ports
@ports.setter
2023-02-23 13:15:32 -08:00
def ports(self, value: dict[str, Port]) -> None:
2023-01-24 23:25:10 -08:00
self._ports = value
def __init__(
self,
*,
2023-04-12 13:56:50 -07:00
shapes: Mapping[layer_t, Sequence[Shape]] | None = None,
labels: Mapping[layer_t, Sequence[Label]] | None = None,
refs: Mapping[str | None, Sequence[Ref]] | None = None,
2023-02-23 13:15:32 -08:00
annotations: annotations_t | None = None,
ports: Mapping[str, 'Port'] | None = None
) -> None:
2016-03-15 19:12:39 -07:00
"""
Basic init; arguments get assigned to member variables.
2023-01-21 21:22:11 -08:00
Non-list inputs for shapes and refs get converted to lists.
2016-03-15 19:12:39 -07:00
Args:
shapes: Initial shapes in the Pattern
labels: Initial labels in the Pattern
2023-01-21 21:22:11 -08:00
refs: Initial refs in the Pattern
2023-01-19 22:20:16 -08:00
annotations: Initial annotations for the pattern
ports: Any ports in the pattern
2016-03-15 19:12:39 -07:00
"""
2023-04-12 13:56:50 -07:00
self.shapes = defaultdict(list)
self.labels = defaultdict(list)
self.refs = defaultdict(list)
if shapes:
for layer, sseq in shapes.items():
self.shapes[layer].extend(sseq)
if labels:
for layer, lseq in labels.items():
self.labels[layer].extend(lseq)
if refs:
for target, rseq in refs.items():
self.refs[target].extend(rseq)
2016-03-15 19:12:39 -07:00
2023-01-19 22:20:16 -08:00
if ports is not None:
2023-01-24 12:45:44 -08:00
self.ports = dict(copy.deepcopy(ports))
else:
self.ports = {}
2023-01-19 22:20:16 -08:00
self.annotations = annotations if annotations is not None else {}
2019-12-12 00:38:11 -08:00
2023-01-19 22:20:16 -08:00
def __repr__(self) -> str:
2023-04-12 13:56:50 -07:00
nshapes = sum(len(seq) for seq in self.shapes.values())
nrefs = sum(len(seq) for seq in self.refs.values())
nlabels = sum(len(seq) for seq in self.labels.values())
s = f'<Pattern: s{nshapes} r{nrefs} l{nlabels} ['
2023-01-19 22:20:16 -08:00
for name, port in self.ports.items():
s += f'\n\t{name}: {port}'
s += ']>'
return s
2023-01-13 20:33:14 -08:00
def __copy__(self) -> 'Pattern':
2023-04-12 13:56:50 -07:00
logger.warning('Making a shallow copy of a Pattern... old shapes are re-referenced!')
new = Pattern(
annotations=copy.deepcopy(self.annotations),
2023-01-19 22:20:16 -08:00
ports=copy.deepcopy(self.ports),
)
2023-04-12 13:56:50 -07:00
for target, rseq in self.refs.items():
new.refs[target].extend(rseq)
for layer, sseq in self.shapes.items():
new.shapes[layer].extend(sseq)
for layer, lseq in self.labels.items():
new.labels[layer].extend(lseq)
2016-03-15 19:12:39 -07:00
return new
2023-04-12 13:56:50 -07:00
# def __deepcopy__(self, memo: dict | None = None) -> 'Pattern':
# memo = {} if memo is None else memo
# new = Pattern(
# shapes=copy.deepcopy(self.shapes, memo),
# labels=copy.deepcopy(self.labels, memo),
# refs=copy.deepcopy(self.refs, memo),
# annotations=copy.deepcopy(self.annotations, memo),
# ports=copy.deepcopy(self.ports),
# )
# return new
def __lt__(self, other: 'Pattern') -> bool:
self_nonempty_targets = [target for target, reflist in self.refs.items() if reflist]
other_nonempty_targets = [target for target, reflist in self.refs.items() if reflist]
self_tgtkeys = tuple(sorted((target is None, target) for target in self_nonempty_targets))
other_tgtkeys = tuple(sorted((target is None, target) for target in other_nonempty_targets))
if self_tgtkeys != other_tgtkeys:
return self_tgtkeys < other_tgtkeys
for _, target in self_tgtkeys:
refs_ours = tuple(sorted(self.refs[target]))
refs_theirs = tuple(sorted(other.refs[target]))
if refs_ours != refs_theirs:
return refs_ours < refs_theirs
self_nonempty_layers = [ll for ll, elems in self.shapes.items() if elems]
other_nonempty_layers = [ll for ll, elems in self.shapes.items() if elems]
self_layerkeys = tuple(sorted(layer2key(ll) for ll in self_nonempty_layers))
other_layerkeys = tuple(sorted(layer2key(ll) for ll in other_nonempty_layers))
if self_layerkeys != other_layerkeys:
return self_layerkeys < other_layerkeys
for _, _, layer in self_layerkeys:
shapes_ours = tuple(sorted(self.shapes[layer]))
shapes_theirs = tuple(sorted(self.shapes[layer]))
if shapes_ours != shapes_theirs:
return shapes_ours < shapes_theirs
self_nonempty_txtlayers = [ll for ll, elems in self.labels.items() if elems]
other_nonempty_txtlayers = [ll for ll, elems in self.labels.items() if elems]
self_txtlayerkeys = tuple(sorted(layer2key(ll) for ll in self_nonempty_txtlayers))
other_txtlayerkeys = tuple(sorted(layer2key(ll) for ll in other_nonempty_txtlayers))
if self_txtlayerkeys != other_txtlayerkeys:
return self_txtlayerkeys < other_txtlayerkeys
for _, _, layer in self_layerkeys:
labels_ours = tuple(sorted(self.labels[layer]))
labels_theirs = tuple(sorted(self.labels[layer]))
if labels_ours != labels_theirs:
return labels_ours < labels_theirs
if not annotations_eq(self.annotations, other.annotations):
return annotations_lt(self.annotations, other.annotations)
if not ports_eq(self.ports, other.ports):
return ports_lt(self.ports, other.ports)
return False
def __eq__(self, other: Any) -> bool:
if type(self) is not type(other):
return False
self_nonempty_targets = [target for target, reflist in self.refs.items() if reflist]
other_nonempty_targets = [target for target, reflist in self.refs.items() if reflist]
self_tgtkeys = tuple(sorted((target is None, target) for target in self_nonempty_targets))
other_tgtkeys = tuple(sorted((target is None, target) for target in other_nonempty_targets))
if self_tgtkeys != other_tgtkeys:
return False
for _, target in self_tgtkeys:
refs_ours = tuple(sorted(self.refs[target]))
refs_theirs = tuple(sorted(other.refs[target]))
if refs_ours != refs_theirs:
return False
self_nonempty_layers = [ll for ll, elems in self.shapes.items() if elems]
other_nonempty_layers = [ll for ll, elems in self.shapes.items() if elems]
self_layerkeys = tuple(sorted(layer2key(ll) for ll in self_nonempty_layers))
other_layerkeys = tuple(sorted(layer2key(ll) for ll in other_nonempty_layers))
if self_layerkeys != other_layerkeys:
return False
for _, _, layer in self_layerkeys:
shapes_ours = tuple(sorted(self.shapes[layer]))
shapes_theirs = tuple(sorted(self.shapes[layer]))
if shapes_ours != shapes_theirs:
return False
self_nonempty_txtlayers = [ll for ll, elems in self.labels.items() if elems]
other_nonempty_txtlayers = [ll for ll, elems in self.labels.items() if elems]
self_txtlayerkeys = tuple(sorted(layer2key(ll) for ll in self_nonempty_txtlayers))
other_txtlayerkeys = tuple(sorted(layer2key(ll) for ll in other_nonempty_txtlayers))
if self_txtlayerkeys != other_txtlayerkeys:
return False
for _, _, layer in self_layerkeys:
labels_ours = tuple(sorted(self.labels[layer]))
labels_theirs = tuple(sorted(self.labels[layer]))
if labels_ours != labels_theirs:
return False
if not annotations_eq(self.annotations, other.annotations):
return False
2024-07-28 20:35:37 -07:00
if not ports_eq(self.ports, other.ports): # noqa: SIM103
return False
return True
def sort(self, sort_elements: bool = True) -> Self:
"""
Sort the element dicts (shapes, labels, refs) and (optionally) their contained lists.
This is primarily useful for making builds more reproducible.
Args:
sort_elements: Whether to sort all the shapes/labels/refs within each layer/target.
Returns:
self
"""
if sort_elements:
def maybe_sort(xx): # noqa:ANN001,ANN202
return sorted(xx)
else:
def maybe_sort(xx): # noqa:ANN001,ANN202
return xx
self.refs = defaultdict(list, sorted(
(tgt, maybe_sort(rrs)) for tgt, rrs in self.refs.items()
))
self.labels = defaultdict(list, sorted(
((layer, maybe_sort(lls)) for layer, lls in self.labels.items()),
key=lambda tt: layer2key(tt[0]),
))
self.shapes = defaultdict(list, sorted(
((layer, maybe_sort(sss)) for layer, sss in self.shapes.items()),
key=lambda tt: layer2key(tt[0]),
))
self.ports = dict(sorted(self.ports.items()))
self.annotations = dict(sorted(self.annotations.items()))
return self
2023-02-23 13:37:34 -08:00
def append(self, other_pattern: 'Pattern') -> Self:
2016-03-15 19:12:39 -07:00
"""
2023-01-21 21:22:11 -08:00
Appends all shapes, labels and refs from other_pattern to self's shapes,
2018-08-30 23:06:31 -07:00
labels, and supbatterns.
2016-03-15 19:12:39 -07:00
Args:
other_pattern: The Pattern to append
Returns:
self
2016-03-15 19:12:39 -07:00
"""
2023-04-12 13:56:50 -07:00
for target, rseq in other_pattern.refs.items():
self.refs[target].extend(rseq)
for layer, sseq in other_pattern.shapes.items():
self.shapes[layer].extend(sseq)
for layer, lseq in other_pattern.labels.items():
self.labels[layer].extend(lseq)
2023-01-21 23:38:53 -08:00
annotation_conflicts = set(self.annotations.keys()) & set(other_pattern.annotations.keys())
if annotation_conflicts:
raise PatternError(f'Annotation keys overlap: {annotation_conflicts}')
self.annotations.update(other_pattern.annotations)
port_conflicts = set(self.ports.keys()) & set(other_pattern.ports.keys())
if port_conflicts:
raise PatternError(f'Port names overlap: {port_conflicts}')
self.ports.update(other_pattern.ports)
2016-03-15 19:12:39 -07:00
return self
def subset(
self,
2023-04-12 13:56:50 -07:00
shapes: Callable[[layer_t, Shape], bool] | None = None,
labels: Callable[[layer_t, Label], bool] | None = None,
refs: Callable[[str | None, Ref], bool] | None = None,
2023-02-23 13:15:32 -08:00
annotations: Callable[[str, list[int | float | str]], bool] | None = None,
ports: Callable[[str, Port], bool] | None = None,
2023-01-19 22:20:16 -08:00
default_keep: bool = False
) -> 'Pattern':
2016-03-15 19:12:39 -07:00
"""
2018-08-30 23:06:31 -07:00
Returns a Pattern containing only the entities (e.g. shapes) for which the
given entity_func returns True.
2023-01-21 21:22:11 -08:00
Self is _not_ altered, but shapes, labels, and refs are _not_ copied, just referenced.
2016-03-15 19:12:39 -07:00
Args:
2023-04-12 13:56:50 -07:00
shapes: Given a layer and shape, returns a boolean denoting whether the shape is a
member of the subset.
labels: Given a layer and label, returns a boolean denoting whether the label is a
member of the subset.
refs: Given a target and ref, returns a boolean denoting if it is a member of the subset.
2023-01-19 22:20:16 -08:00
annotations: Given an annotation, returns a boolean denoting if it is a member of the subset.
ports: Given a port, returns a boolean denoting if it is a member of the subset.
default_keep: If `True`, keeps all elements of a given type if no function is supplied.
Default `False` (discards all elements).
Returns:
2023-01-21 21:22:11 -08:00
A Pattern containing all the shapes and refs for which the parameter
functions return True
2016-03-15 19:12:39 -07:00
"""
pat = Pattern()
2023-01-19 22:20:16 -08:00
if shapes is not None:
2023-04-12 13:56:50 -07:00
for layer in self.shapes:
pat.shapes[layer] = [ss for ss in self.shapes[layer] if shapes(layer, ss)]
2023-01-19 22:20:16 -08:00
elif default_keep:
pat.shapes = copy.copy(self.shapes)
if labels is not None:
2023-04-12 13:56:50 -07:00
for layer in self.labels:
pat.labels[layer] = [ll for ll in self.labels[layer] if labels(layer, ll)]
2023-01-19 22:20:16 -08:00
elif default_keep:
pat.labels = copy.copy(self.labels)
2023-01-21 21:22:11 -08:00
if refs is not None:
2023-04-12 13:56:50 -07:00
for target in self.refs:
pat.refs[target] = [rr for rr in self.refs[target] if refs(target, rr)]
2023-01-19 22:20:16 -08:00
elif default_keep:
2023-01-21 21:22:11 -08:00
pat.refs = copy.copy(self.refs)
2023-01-19 22:20:16 -08:00
if annotations is not None:
2023-01-21 23:38:53 -08:00
pat.annotations = {k: v for k, v in self.annotations.items() if annotations(k, v)}
2023-01-19 22:20:16 -08:00
elif default_keep:
pat.annotations = copy.copy(self.annotations)
if ports is not None:
2023-01-21 23:38:53 -08:00
pat.ports = {k: v for k, v in self.ports.items() if ports(k, v)}
2023-01-19 22:20:16 -08:00
elif default_keep:
pat.ports = copy.copy(self.ports)
return pat
def polygonize(
2023-02-23 13:37:34 -08:00
self,
2023-03-19 10:17:09 -07:00
num_vertices: int | None = DEFAULT_POLY_NUM_VERTICES,
2023-02-23 13:15:32 -08:00
max_arclen: float | None = None,
2023-02-23 13:37:34 -08:00
) -> Self:
2016-03-15 19:12:39 -07:00
"""
Calls `.to_polygons(...)` on all the shapes in this Pattern, replacing them with the returned polygons.
Arguments are passed directly to `shape.to_polygons(...)`.
2016-03-15 19:12:39 -07:00
Args:
2023-03-19 10:17:09 -07:00
num_vertices: Number of points to use for each polygon. Can be overridden by
2023-02-23 11:25:40 -08:00
`max_arclen` if that results in more points. Optional, defaults to shapes'
internal defaults.
2023-02-23 11:25:40 -08:00
max_arclen: Maximum arclength which can be approximated by a single line
2018-04-15 16:42:00 -07:00
segment. Optional, defaults to shapes' internal defaults.
Returns:
self
2016-03-15 19:12:39 -07:00
"""
2023-04-12 13:56:50 -07:00
for layer in self.shapes:
self.shapes[layer] = list(chain.from_iterable(
ss.to_polygons(num_vertices, max_arclen)
for ss in self.shapes[layer]
))
2016-03-15 19:12:39 -07:00
return self
def manhattanize(
2023-02-23 13:37:34 -08:00
self,
grid_x: ArrayLike,
grid_y: ArrayLike,
2023-02-23 13:37:34 -08:00
) -> Self:
2017-09-06 01:16:24 -07:00
"""
Calls `.polygonize()` on the pattern, then calls `.manhattanize()` on all the
2017-09-06 01:16:24 -07:00
resulting shapes, replacing them with the returned Manhattan polygons.
Args:
grid_x: List of allowed x-coordinates for the Manhattanized polygon edges.
grid_y: List of allowed y-coordinates for the Manhattanized polygon edges.
Returns:
self
2017-09-06 01:16:24 -07:00
"""
self.polygonize()
2023-04-12 13:56:50 -07:00
for layer in self.shapes:
self.shapes[layer] = list(chain.from_iterable(
2023-04-12 13:56:50 -07:00
ss.manhattanize(grid_x, grid_y)
for ss in self.shapes[layer]
))
2017-09-06 01:16:24 -07:00
return self
2023-02-23 13:15:32 -08:00
def as_polygons(self, library: Mapping[str, 'Pattern']) -> list[NDArray[numpy.float64]]:
2016-03-15 19:12:39 -07:00
"""
Represents the pattern as a list of polygons.
Deep-copies the pattern, then calls `.polygonize()` and `.flatten()` on the copy in order to
2016-03-15 19:12:39 -07:00
generate the list of polygons.
Returns:
A list of `(Ni, 2)` `numpy.ndarray`s specifying vertices of the polygons. Each ndarray
is of the form `[[x0, y0], [x1, y1],...]`.
2016-03-15 19:12:39 -07:00
"""
pat = self.deepcopy().polygonize().flatten(library=library)
2023-04-12 13:56:50 -07:00
polys = [
cast(Polygon, shape).vertices + cast(Polygon, shape).offset
for shape in chain_elements(pat.shapes)
]
return polys
2016-03-15 19:12:39 -07:00
2023-02-23 13:15:32 -08:00
def referenced_patterns(self) -> set[str | None]:
"""
Get all pattern namers referenced by this pattern. Non-recursive.
Returns:
A set of all pattern names referenced by this pattern.
"""
2023-04-12 13:56:50 -07:00
return set(self.refs.keys())
def get_bounds(
self,
2023-02-23 13:15:32 -08:00
library: Mapping[str, 'Pattern'] | None = None,
2023-01-26 23:47:16 -08:00
recurse: bool = True,
cache: MutableMapping[str, NDArray[numpy.float64] | None] | None = None,
2023-02-23 13:15:32 -08:00
) -> NDArray[numpy.float64] | None:
2016-03-15 19:12:39 -07:00
"""
Return a `numpy.ndarray` containing `[[x_min, y_min], [x_max, y_max]]`, corresponding to the
2016-03-15 19:12:39 -07:00
extent of the Pattern's contents in each dimension.
Returns `None` if the Pattern is empty.
2016-03-15 19:12:39 -07:00
2023-01-26 23:47:16 -08:00
Args:
2023-07-17 21:28:42 -07:00
library: If `recurse=True`, any referenced patterns are loaded from this library.
recurse: If `False`, do not evaluate the bounds of any refs (i.e. assume they are empty).
If `True`, evaluate the bounds of all refs and their conained geometry recursively.
Default `True`.
cache: Mapping of `{name: bounds}` for patterns for which the bounds have already been calculated.
Modified during the run (any referenced pattern's bounds are added).
2023-01-26 23:47:16 -08:00
Returns:
`[[x_min, y_min], [x_max, y_max]]` or `None`
2016-03-15 19:12:39 -07:00
"""
2020-09-18 19:46:57 -07:00
if self.is_empty():
2016-03-15 19:12:39 -07:00
return None
n_elems = sum(1 for _ in chain_elements(self.shapes, self.labels))
ebounds = numpy.full((n_elems, 2, 2), nan)
for ee, entry in enumerate(chain_elements(self.shapes, self.labels)):
maybe_ebounds = cast(Bounded, entry).get_bounds()
if maybe_ebounds is not None:
ebounds[ee] = maybe_ebounds
mask = ~numpy.isnan(ebounds[:, 0, 0])
if mask.any():
cbounds = numpy.vstack((
2023-04-14 22:27:44 -07:00
numpy.min(ebounds[mask, 0, :], axis=0),
numpy.max(ebounds[mask, 1, :], axis=0),
))
else:
cbounds = numpy.array((
(+inf, +inf),
(-inf, -inf),
))
2023-04-12 13:56:50 -07:00
if recurse and self.has_refs():
if library is None:
raise PatternError('Must provide a library to get_bounds() to resolve refs')
2023-04-12 18:21:37 -07:00
if cache is None:
cache = {}
2023-04-12 13:56:50 -07:00
for target, refs in self.refs.items():
if target is None:
continue
if not refs:
2023-01-26 23:47:16 -08:00
continue
2023-04-12 18:21:37 -07:00
if target in cache:
unrot_bounds = cache[target]
2023-04-12 21:41:18 -07:00
elif any(numpy.isclose(ref.rotation % (pi / 2), 0) for ref in refs):
2023-04-12 18:21:37 -07:00
unrot_bounds = library[target].get_bounds(library=library, recurse=recurse, cache=cache)
cache[target] = unrot_bounds
2023-04-12 13:56:50 -07:00
for ref in refs:
2023-04-12 18:43:44 -07:00
if numpy.isclose(ref.rotation % (pi / 2), 0):
2023-04-12 18:21:37 -07:00
if unrot_bounds is None:
bounds = None
else:
ubounds = unrot_bounds.copy()
if ref.mirrored:
2023-04-12 18:21:37 -07:00
ubounds[:, 1] *= -1
2023-04-12 22:40:08 -07:00
corners = (rotation_matrix_2d(ref.rotation) @ ubounds.T).T
2023-04-12 22:40:08 -07:00
bounds = numpy.vstack((numpy.min(corners, axis=0),
numpy.max(corners, axis=0))) * ref.scale + [ref.offset]
if ref.repetition is not None:
bounds += ref.repetition.get_bounds()
2023-04-12 19:31:17 -07:00
2023-04-12 18:21:37 -07:00
else:
# Non-manhattan rotation, have to figure out bounds by rotating the pattern
bounds = ref.get_bounds(library[target], library=library)
2023-04-12 13:56:50 -07:00
if bounds is None:
continue
2023-04-12 19:31:17 -07:00
cbounds[0] = numpy.minimum(cbounds[0], bounds[0])
cbounds[1] = numpy.maximum(cbounds[1], bounds[1])
2023-04-12 18:21:37 -07:00
2023-04-12 19:31:17 -07:00
if (cbounds[1] < cbounds[0]).any():
return None
2024-07-28 20:19:22 -07:00
return cbounds
2016-03-15 19:12:39 -07:00
def get_bounds_nonempty(
self,
2023-02-23 13:15:32 -08:00
library: Mapping[str, 'Pattern'] | None = None,
2023-01-26 23:47:16 -08:00
recurse: bool = True,
) -> NDArray[numpy.float64]:
2022-02-27 21:21:34 -08:00
"""
Convenience wrapper for `get_bounds()` which asserts that the Pattern as non-None bounds.
2023-01-26 23:47:16 -08:00
Args:
2023-07-17 21:28:42 -07:00
library: If `recurse=True`, any referenced patterns are loaded from this library.
recurse: If `False`, do not evaluate the bounds of any refs (i.e. assume they are empty).
If `True`, evaluate the bounds of all refs and their conained geometry recursively.
Default `True`.
cache: Mapping of `{name: bounds}` for patterns for which the bounds have already been calculated.
Modified during the run (any referenced pattern's bounds are added).
2023-01-26 23:47:16 -08:00
2022-02-27 21:21:34 -08:00
Returns:
`[[x_min, y_min], [x_max, y_max]]`
"""
2024-07-28 20:19:59 -07:00
bounds = self.get_bounds(library, recurse=recurse)
2023-01-23 22:27:26 -08:00
assert bounds is not None
2022-02-27 21:21:34 -08:00
return bounds
2023-02-23 13:37:34 -08:00
def translate_elements(self, offset: ArrayLike) -> Self:
2016-03-15 19:12:39 -07:00
"""
2023-01-24 23:25:10 -08:00
Translates all shapes, label, refs, and ports by the given offset.
2016-03-15 19:12:39 -07:00
Args:
offset: (x, y) to translate by
Returns:
self
2016-03-15 19:12:39 -07:00
"""
2023-04-12 13:56:50 -07:00
for entry in chain(chain_elements(self.shapes, self.labels, self.refs), self.ports.values()):
2023-01-19 22:20:16 -08:00
cast(Positionable, entry).translate(offset)
2016-03-15 19:12:39 -07:00
return self
2023-02-23 13:37:34 -08:00
def scale_elements(self, c: float) -> Self:
2016-03-15 19:12:39 -07:00
""""
2023-01-21 21:22:11 -08:00
Scales all shapes and refs by the given value.
2016-03-15 19:12:39 -07:00
Args:
c: factor to scale by
Returns:
self
2016-03-15 19:12:39 -07:00
"""
2023-04-12 13:56:50 -07:00
for entry in chain_elements(self.shapes, self.refs):
2023-01-19 22:20:16 -08:00
cast(Scalable, entry).scale_by(c)
2016-03-15 19:12:39 -07:00
return self
2023-02-23 13:37:34 -08:00
def scale_by(self, c: float) -> Self:
2016-03-15 19:12:39 -07:00
"""
Scale this Pattern by the given value
2023-01-24 23:25:10 -08:00
(all shapes and refs and their offsets are scaled,
as are all label and port offsets)
2016-03-15 19:12:39 -07:00
Args:
c: factor to scale by
Returns:
self
2016-03-15 19:12:39 -07:00
"""
2023-04-12 13:56:50 -07:00
for entry in chain_elements(self.shapes, self.refs):
2023-01-19 22:20:16 -08:00
cast(Positionable, entry).offset *= c
cast(Scalable, entry).scale_by(c)
rep = cast(Repeatable, entry).repetition
if rep:
rep.scale_by(c)
2023-04-12 13:56:50 -07:00
for label in chain_elements(self.labels):
2023-01-19 22:20:16 -08:00
cast(Positionable, label).offset *= c
rep = cast(Repeatable, label).repetition
if rep:
rep.scale_by(c)
for port in self.ports.values():
port.offset *= c
2016-03-15 19:12:39 -07:00
return self
2023-02-23 13:37:34 -08:00
def rotate_around(self, pivot: ArrayLike, rotation: float) -> Self:
2016-03-15 19:12:39 -07:00
"""
Rotate the Pattern around the a location.
Args:
pivot: (x, y) location to rotate around
rotation: Angle to rotate by (counter-clockwise, radians)
Returns:
self
2016-03-15 19:12:39 -07:00
"""
pivot = numpy.asarray(pivot, dtype=float)
2016-03-15 19:12:39 -07:00
self.translate_elements(-pivot)
self.rotate_elements(rotation)
self.rotate_element_centers(rotation)
self.translate_elements(+pivot)
return self
2023-02-23 13:37:34 -08:00
def rotate_element_centers(self, rotation: float) -> Self:
2016-03-15 19:12:39 -07:00
"""
2023-01-24 23:25:10 -08:00
Rotate the offsets of all shapes, labels, refs, and ports around (0, 0)
2016-03-15 19:12:39 -07:00
Args:
rotation: Angle to rotate by (counter-clockwise, radians)
Returns:
self
2016-03-15 19:12:39 -07:00
"""
2023-04-12 13:56:50 -07:00
for entry in chain(chain_elements(self.shapes, self.refs, self.labels), self.ports.values()):
2023-01-19 22:20:16 -08:00
old_offset = cast(Positionable, entry).offset
cast(Positionable, entry).offset = numpy.dot(rotation_matrix_2d(rotation), old_offset)
2016-03-15 19:12:39 -07:00
return self
2023-02-23 13:37:34 -08:00
def rotate_elements(self, rotation: float) -> Self:
2016-03-15 19:12:39 -07:00
"""
2023-01-24 23:25:10 -08:00
Rotate each shape, ref, and port around its origin (offset)
2016-03-15 19:12:39 -07:00
Args:
rotation: Angle to rotate by (counter-clockwise, radians)
Returns:
self
2016-03-15 19:12:39 -07:00
"""
2023-04-12 13:56:50 -07:00
for entry in chain(chain_elements(self.shapes, self.refs), self.ports.values()):
2020-11-09 22:04:04 -08:00
cast(Rotatable, entry).rotate(rotation)
2016-03-15 19:12:39 -07:00
return self
def mirror_element_centers(self, across_axis: int = 0) -> Self:
"""
2023-01-21 21:22:11 -08:00
Mirror the offsets of all shapes, labels, and refs across an axis
Args:
2023-01-24 23:25:10 -08:00
across_axis: Axis to mirror across
(0: mirror across x axis, 1: mirror across y axis)
Returns:
self
"""
2023-04-12 13:56:50 -07:00
for entry in chain(chain_elements(self.shapes, self.refs, self.labels), self.ports.values()):
2023-01-24 23:25:10 -08:00
cast(Positionable, entry).offset[across_axis - 1] *= -1
return self
def mirror_elements(self, across_axis: int = 0) -> Self:
"""
2023-01-24 23:25:10 -08:00
Mirror each shape, ref, and pattern across an axis, relative
to its offset
Args:
2023-01-24 23:25:10 -08:00
across_axis: Axis to mirror across
(0: mirror across x axis, 1: mirror across y axis)
Returns:
self
"""
2023-04-12 13:56:50 -07:00
for entry in chain(chain_elements(self.shapes, self.refs), self.ports.values()):
2023-01-24 23:25:10 -08:00
cast(Mirrorable, entry).mirror(across_axis)
return self
def mirror(self, across_axis: int = 0) -> Self:
"""
Mirror the Pattern across an axis
Args:
2023-01-24 23:25:10 -08:00
across_axis: Axis to mirror across
(0: mirror across x axis, 1: mirror across y axis)
Returns:
self
"""
2023-01-24 23:25:10 -08:00
self.mirror_elements(across_axis)
self.mirror_element_centers(across_axis)
return self
2023-02-23 13:37:34 -08:00
def copy(self) -> Self:
2016-03-15 19:12:39 -07:00
"""
2023-04-12 21:43:58 -07:00
Convenience method for `copy.deepcopy(pattern)` (same as `Pattern.deepcopy()`).
See also: `Pattern.deepcopy()`
Returns:
2023-04-12 21:43:58 -07:00
A deep copy of the current Pattern.
2016-03-15 19:12:39 -07:00
"""
2023-04-12 21:43:58 -07:00
return copy.deepcopy(self)
2016-03-15 19:12:39 -07:00
2023-02-23 13:37:34 -08:00
def deepcopy(self) -> Self:
"""
Convenience method for `copy.deepcopy(pattern)`
Returns:
A deep copy of the current Pattern.
"""
return copy.deepcopy(self)
2019-05-15 00:11:44 -07:00
def is_empty(self) -> bool:
"""
Returns:
2023-01-21 21:22:11 -08:00
True if the pattern is contains no shapes, labels, or refs.
2019-05-15 00:11:44 -07:00
"""
2023-04-12 13:56:50 -07:00
return not (self.has_refs() or self.has_shapes() or self.has_labels())
2019-05-15 00:11:44 -07:00
2023-04-12 13:56:50 -07:00
def has_refs(self) -> bool:
2023-07-17 21:28:42 -07:00
"""
Returns:
True if the pattern contains any refs.
"""
2023-04-12 13:56:50 -07:00
return any(True for _ in chain.from_iterable(self.refs.values()))
def has_shapes(self) -> bool:
2023-07-17 21:28:42 -07:00
"""
Returns:
True if the pattern contains any shapes.
"""
2023-04-12 13:56:50 -07:00
return any(True for _ in chain.from_iterable(self.shapes.values()))
def has_labels(self) -> bool:
2023-07-17 21:28:42 -07:00
"""
Returns:
True if the pattern contains any labels.
"""
2023-04-12 13:56:50 -07:00
return any(True for _ in chain.from_iterable(self.labels.values()))
2023-07-17 21:29:12 -07:00
def has_ports(self) -> bool:
"""
Returns:
True if the pattern contains any ports.
"""
return bool(self.ports)
def ref(self, target: str | Abstract | None, *args: Any, **kwargs: Any) -> Self:
"""
2023-01-21 21:22:11 -08:00
Convenience function which constructs a `Ref` object and adds it
to this pattern.
Args:
2023-04-12 13:56:50 -07:00
target: Target for the ref
2023-01-21 21:22:11 -08:00
*args: Passed to `Ref()`
**kwargs: Passed to `Ref()`
Returns:
self
"""
if isinstance(target, Abstract):
target = target.name
2023-04-12 13:56:50 -07:00
self.refs[target].append(Ref(*args, **kwargs))
return self
2023-04-12 13:56:50 -07:00
def polygon(self, layer: layer_t, *args: Any, **kwargs: Any) -> Self:
"""
Convenience function which constructs a `Polygon` object and adds it
to this pattern.
Args:
2023-04-12 13:56:50 -07:00
layer: Layer for the polygon
*args: Passed to `Polygon()`
**kwargs: Passed to `Polygon()`
Returns:
self
"""
2023-04-12 13:56:50 -07:00
self.shapes[layer].append(Polygon(*args, **kwargs))
return self
2023-04-12 13:56:50 -07:00
def rect(self, layer: layer_t, *args: Any, **kwargs: Any) -> Self:
2023-01-25 23:19:25 -08:00
"""
Convenience function which calls `Polygon.rect` to construct a
rectangle and adds it to this pattern.
Args:
2023-04-12 13:56:50 -07:00
layer: Layer for the rectangle
2023-01-25 23:19:25 -08:00
*args: Passed to `Polygon.rect()`
**kwargs: Passed to `Polygon.rect()`
Returns:
self
"""
2023-04-12 13:56:50 -07:00
self.shapes[layer].append(Polygon.rect(*args, **kwargs))
return self
def path(self, layer: layer_t, *args: Any, **kwargs: Any) -> Self:
"""
Convenience function which constructs a `Path` object and adds it
to this pattern.
Args:
layer: Layer for the path
*args: Passed to `Path()`
**kwargs: Passed to `Path()`
Returns:
self
"""
self.shapes[layer].append(Path(*args, **kwargs))
2023-01-25 23:19:25 -08:00
return self
2023-04-12 13:56:50 -07:00
def label(self, layer: layer_t, *args: Any, **kwargs: Any) -> Self:
"""
Convenience function which constructs a `Label` object
and adds it to this pattern.
Args:
2023-04-12 13:56:50 -07:00
layer: Layer for the label
*args: Passed to `Label()`
**kwargs: Passed to `Label()`
Returns:
self
"""
2023-04-12 13:56:50 -07:00
self.labels[layer].append(Label(*args, **kwargs))
return self
2023-06-02 21:15:16 -07:00
def prune_layers(self) -> Self:
"""
2023-10-12 23:40:24 -07:00
Remove empty layers (empty lists) in `self.shapes` and `self.labels`.
2023-06-02 21:15:16 -07:00
Returns:
self
"""
for layer in list(self.shapes):
if not self.shapes[layer]:
del self.shapes[layer]
for layer in list(self.labels):
if not self.labels[layer]:
del self.labels[layer]
return self
def prune_refs(self) -> Self:
"""
Remove empty ref lists in `self.refs`.
Returns:
self
"""
for target in list(self.refs):
if not self.refs[target]:
del self.refs[target]
return self
def flatten(
2023-02-23 13:37:34 -08:00
self,
library: Mapping[str, 'Pattern'],
2023-07-17 21:28:42 -07:00
flatten_ports: bool = False,
) -> 'Pattern':
2019-12-12 00:38:11 -08:00
"""
2023-01-21 21:22:11 -08:00
Removes all refs (recursively) and adds equivalent shapes.
2023-07-17 21:28:42 -07:00
Alters the current pattern in-place.
For a version which creates copies, see `Library.flatten`.
2019-12-12 00:38:11 -08:00
Args:
library: Source for referenced patterns.
2023-07-17 21:28:42 -07:00
flatten_ports: If `True`, keep ports from any referenced
patterns; otherwise discard them.
2019-12-12 00:38:11 -08:00
Returns:
self
2019-12-12 00:38:11 -08:00
"""
2024-07-28 20:19:43 -07:00
flattened: dict[str | None, Pattern | None] = {}
2019-12-12 00:38:11 -08:00
2023-02-23 13:15:32 -08:00
def flatten_single(name: str | None) -> None:
if name is None:
pat = self
else:
pat = library[name].deepcopy()
flattened[name] = None
2023-04-12 13:56:50 -07:00
for target, refs in pat.refs.items():
if target is None:
continue
2023-04-12 13:56:50 -07:00
if not refs:
continue
2016-03-15 19:12:39 -07:00
if target not in flattened:
flatten_single(target)
2023-02-09 16:38:33 -08:00
target_pat = flattened[target]
2023-04-12 13:56:50 -07:00
2023-02-09 16:38:33 -08:00
if target_pat is None:
raise PatternError(f'Circular reference in {name} to {target}')
2023-02-09 16:43:06 -08:00
if target_pat.is_empty(): # avoid some extra allocations
2023-02-09 16:38:33 -08:00
continue
2016-03-15 19:12:39 -07:00
2023-04-12 13:56:50 -07:00
for ref in refs:
p = ref.as_pattern(pattern=target_pat)
if not flatten_ports:
p.ports.clear()
pat.append(p)
2023-01-21 21:22:11 -08:00
pat.refs.clear()
flattened[name] = pat
2016-03-15 19:12:39 -07:00
flatten_single(None)
2016-03-15 19:12:39 -07:00
return self
def visualize(
2023-02-23 13:37:34 -08:00
self,
library: Mapping[str, 'Pattern'] | None = None,
offset: ArrayLike = (0., 0.),
line_color: str = 'k',
fill_color: str = 'none',
overdraw: bool = False,
) -> None:
2016-03-15 19:12:39 -07:00
"""
Draw a picture of the Pattern and wait for the user to inspect it
Imports `matplotlib`.
Note that this can be slow; it is often faster to export to GDSII and use
klayout or a different GDS viewer!
2016-03-15 19:12:39 -07:00
Args:
offset: Coordinates to offset by before drawing
line_color: Outlines are drawn with this color (passed to `matplotlib.collections.PolyCollection`)
fill_color: Interiors are drawn with this color (passed to `matplotlib.collections.PolyCollection`)
overdraw: Whether to create a new figure or draw on a pre-existing one
2016-03-15 19:12:39 -07:00
"""
2018-08-30 23:06:31 -07:00
# TODO: add text labels to visualize()
2023-10-07 01:52:40 -07:00
try:
from matplotlib import pyplot # type: ignore
import matplotlib.collections # type: ignore
2024-07-28 20:08:53 -07:00
except ImportError:
logger.exception('Pattern.visualize() depends on matplotlib!\n'
+ 'Make sure to install masque with the [visualize] option to pull in the needed dependencies.')
raise
2016-03-15 19:12:39 -07:00
2023-04-12 13:56:50 -07:00
if self.has_refs() and library is None:
2023-01-21 21:22:11 -08:00
raise PatternError('Must provide a library when visualizing a pattern with refs')
offset = numpy.asarray(offset, dtype=float)
2016-03-15 19:12:39 -07:00
if not overdraw:
figure = pyplot.figure()
pyplot.axis('equal')
else:
figure = pyplot.gcf()
axes = figure.gca()
polygons = []
2023-04-12 13:56:50 -07:00
for shape in chain.from_iterable(self.shapes.values()):
2016-03-15 19:12:39 -07:00
polygons += [offset + s.offset + s.vertices for s in shape.to_polygons()]
mpl_poly_collection = matplotlib.collections.PolyCollection(
polygons,
facecolors=fill_color,
edgecolors=line_color,
)
2016-03-15 19:12:39 -07:00
axes.add_collection(mpl_poly_collection)
pyplot.axis('equal')
2023-04-12 13:56:50 -07:00
for target, refs in self.refs.items():
if target is None:
continue
if not refs:
continue
assert library is not None
target_pat = library[target]
for ref in refs:
ref.as_pattern(target_pat).visualize(
library=library,
offset=offset,
overdraw=True,
line_color=line_color,
fill_color=fill_color,
)
2016-03-15 19:12:39 -07:00
if not overdraw:
2021-01-08 21:20:03 -08:00
pyplot.xlabel('x')
pyplot.ylabel('y')
2016-03-15 19:12:39 -07:00
pyplot.show()
2023-04-12 13:56:50 -07:00
# @overload
# def place(
# self,
# other: 'Pattern',
# *,
# offset: ArrayLike,
# rotation: float,
# pivot: ArrayLike,
# mirrored: bool,
# port_map: dict[str, str | None] | None,
# skip_port_check: bool,
# append: bool,
# ) -> Self:
# pass
#
# @overload
# def place(
# self,
# other: Abstract,
# *,
# offset: ArrayLike,
# rotation: float,
# pivot: ArrayLike,
# mirrored: bool,
# port_map: dict[str, str | None] | None,
# skip_port_check: bool,
# append: Literal[False],
# ) -> Self:
# pass
def place(
self,
other: 'Abstract | Pattern',
*,
offset: ArrayLike = (0, 0),
rotation: float = 0,
pivot: ArrayLike = (0, 0),
mirrored: bool = False,
port_map: dict[str, str | None] | None = None,
skip_port_check: bool = False,
append: bool = False,
) -> Self:
"""
Instantiate or append the pattern `other` into the current pattern, adding its
ports to those of the current pattern (but not connecting/removing any ports).
Mirroring is applied before rotation; translation (`offset`) is applied last.
Examples:
=========
- `my_pat.place(pad_pat, offset=(10, 10), rotation=pi / 2, port_map={'A': 'gnd'})`
instantiates `pad` at the specified (x, y) offset and with the specified
rotation, adding its ports to those of `my_pat`. Port 'A' of `pad` is
renamed to 'gnd' so that further routing can use this signal or net name
rather than the port name on the original `pad_pat` pattern.
Args:
other: An `Abstract` or `Pattern` describing the device to be instatiated.
offset: Offset at which to place the instance. Default (0, 0).
rotation: Rotation applied to the instance before placement. Default 0.
pivot: Rotation is applied around this pivot point (default (0, 0)).
Rotation is applied prior to translation (`offset`).
mirrored: Whether theinstance should be mirrored across the x axis.
Mirroring is applied before translation and rotation.
port_map: dict of `{'old_name': 'new_name'}` mappings, specifying
new names for ports in the instantiated pattern. New names can be
`None`, which will delete those ports.
skip_port_check: Can be used to skip the internal call to `check_ports`,
in case it has already been performed elsewhere.
append: If `True`, `other` is appended instead of being referenced.
Note that this does not flatten `other`, so its refs will still
be refs (now inside `self`).
Returns:
self
Raises:
`PortError` if any ports specified in `map_in` or `map_out` do not
exist in `self.ports` or `other.ports`.
`PortError` if there are any duplicate names after `map_in` and `map_out`
are applied.
"""
if port_map is None:
port_map = {}
if not skip_port_check:
self.check_ports(other.ports.keys(), map_in=None, map_out=port_map)
ports = {}
for name, port in other.ports.items():
new_name = port_map.get(name, name)
if new_name is None:
continue
ports[new_name] = port
for name, port in ports.items():
p = port.deepcopy()
if mirrored:
p.mirror()
p.rotate_around(pivot, rotation)
p.translate(offset)
self.ports[name] = p
if append:
if isinstance(other, Abstract):
raise PatternError('Must provide a full `Pattern` (not an `Abstract`) when appending!')
other_copy = other.deepcopy()
other_copy.ports.clear()
if mirrored:
other_copy.mirror()
other_copy.rotate_around(pivot, rotation)
other_copy.translate_elements(offset)
self.append(other_copy)
else:
assert not isinstance(other, Pattern)
ref = Ref(mirrored=mirrored)
ref.rotate_around(pivot, rotation)
ref.translate(offset)
self.refs[other.name].append(ref)
return self
# @overload
# def plug(
# self,
# other: Abstract,
# map_in: dict[str, str],
# map_out: dict[str, str | None] | None,
# *,
# mirrored: bool,
# inherit_name: bool,
# set_rotation: bool | None,
# append: Literal[False],
# ) -> Self:
# pass
#
# @overload
# def plug(
# self,
# other: 'Pattern',
# map_in: dict[str, str],
# map_out: dict[str, str | None] | None,
# *,
# mirrored: bool,
# inherit_name: bool,
# set_rotation: bool | None,
# append: bool,
# ) -> Self:
# pass
def plug(
self,
other: 'Abstract | Pattern',
map_in: dict[str, str],
map_out: dict[str, str | None] | None = None,
*,
mirrored: bool = False,
inherit_name: bool = True,
set_rotation: bool | None = None,
append: bool = False,
ok_connections: Iterable[tuple[str, str]] = (),
) -> Self:
"""
Instantiate or append a pattern into the current pattern, connecting
the ports specified by `map_in` and renaming the unconnected
ports specified by `map_out`.
Examples:
======list, ===
- `my_pat.plug(subdevice, {'A': 'C', 'B': 'B'}, map_out={'D': 'myport'})`
instantiates `subdevice` into `my_pat`, plugging ports 'A' and 'B'
of `my_pat` into ports 'C' and 'B' of `subdevice`. The connected ports
are removed and any unconnected ports from `subdevice` are added to
`my_pat`. Port 'D' of `subdevice` (unconnected) is renamed to 'myport'.
- `my_pat.plug(wire, {'myport': 'A'})` places port 'A' of `wire` at 'myport'
of `my_pat`.
If `wire` has only two ports (e.g. 'A' and 'B'), no `map_out` argument is
provided, and the `inherit_name` argument is not explicitly set to `False`,
the unconnected port of `wire` is automatically renamed to 'myport'. This
allows easy extension of existing ports without changing their names or
having to provide `map_out` each time `plug` is called.
Args:
other: A `Pattern` or `Abstract` describing the subdevice to be instatiated.
map_in: dict of `{'self_port': 'other_port'}` mappings, specifying
port connections between the current pattern and the subdevice.
map_out: dict of `{'old_name': 'new_name'}` mappings, specifying
new names for ports in `other`.
mirrored: Enables mirroring `other` across the x axis prior to connecting
any ports.
inherit_name: If `True`, and `map_in` specifies only a single port,
and `map_out` is `None`, and `other` has only two ports total,
then automatically renames the output port of `other` to the
name of the port from `self` that appears in `map_in`. This
makes it easy to extend a pattern with simple 2-port devices
(e.g. wires) without providing `map_out` each time `plug` is
called. See "Examples" above for more info. Default `True`.
set_rotation: If the necessary rotation cannot be determined from
the ports being connected (i.e. all pairs have at least one
port with `rotation=None`), `set_rotation` must be provided
to indicate how much `other` should be rotated. Otherwise,
`set_rotation` must remain `None`.
append: If `True`, `other` is appended instead of being referenced.
Note that this does not flatten `other`, so its refs will still
be refs (now inside `self`).
ok_connections: Set of "allowed" ptype combinations. Identical
ptypes are always allowed to connect, as is `'unk'` with
any other ptypte. Non-allowed ptype connections will emit a
warning. Order is ignored, i.e. `(a, b)` is equivalent to
`(b, a)`.
Returns:
self
Raises:
`PortError` if any ports specified in `map_in` or `map_out` do not
exist in `self.ports` or `other_names`.
`PortError` if there are any duplicate names after `map_in` and `map_out`
are applied.
`PortError` if the specified port mapping is not achieveable (the ports
do not line up)
"""
# If asked to inherit a name, check that all conditions are met
if (inherit_name
and not map_out
and len(map_in) == 1
and len(other.ports) == 2):
out_port_name = next(iter(set(other.ports.keys()) - set(map_in.values())))
map_out = {out_port_name: next(iter(map_in.keys()))}
if map_out is None:
map_out = {}
map_out = copy.deepcopy(map_out)
self.check_ports(other.ports.keys(), map_in, map_out)
translation, rotation, pivot = self.find_transform(
other,
map_in,
mirrored=mirrored,
set_rotation=set_rotation,
ok_connections=ok_connections,
)
# get rid of plugged ports
for ki, vi in map_in.items():
del self.ports[ki]
map_out[vi] = None
if isinstance(other, Pattern):
2024-06-03 16:54:15 -07:00
assert append, 'Got a name (not an abstract) but was asked to reference (not append)'
self.place(
other,
offset=translation,
rotation=rotation,
pivot=pivot,
mirrored=mirrored,
port_map=map_out,
skip_port_check=True,
append=append,
)
return self
@classmethod
def interface(
2024-07-28 19:44:04 -07:00
cls: type['Pattern'],
source: PortList | Mapping[str, Port],
*,
in_prefix: str = 'in_',
out_prefix: str = '',
port_map: dict[str, str] | Sequence[str] | None = None,
) -> 'Pattern':
"""
Generate an empty pattern with ports based on all or some of the ports
in the `source`. Do not include the source device istelf; instead use
it to define ports (the "interface") for the new device.
The ports specified by `port_map` (default: all ports) are copied to
new device, and additional (input) ports are created facing in the
opposite directions. The specified `in_prefix` and `out_prefix` are
prepended to the port names to differentiate them.
By default, the flipped ports are given an 'in_' prefix and unflipped
ports keep their original names, enabling intuitive construction of
a device that will "plug into" the current device; the 'in_*' ports
are used for plugging the devices together while the original port
names are used for building the new device.
Another use-case could be to build the new device using the 'in_'
ports, creating a new device which could be used in place of the
current device.
Args:
source: A collection of ports (e.g. Pattern, Builder, or dict)
from which to create the interface.
in_prefix: Prepended to port names for newly-created ports with
reversed directions compared to the current device.
out_prefix: Prepended to port names for ports which are directly
copied from the current device.
port_map: Specification for ports to copy into the new device:
- If `None`, all ports are copied.
- If a sequence, only the listed ports are copied
- If a mapping, the listed ports (keys) are copied and
renamed (to the values).
Returns:
The new empty pattern, with 2x as many ports as listed in port_map.
Raises:
`PortError` if `port_map` contains port names not present in the
current device.
`PortError` if applying the prefixes results in duplicate port
names.
"""
if isinstance(source, PortList):
orig_ports = source.ports
elif isinstance(source, dict):
orig_ports = source
else:
raise PatternError(f'Unable to get ports from {type(source)}: {source}')
if port_map:
if isinstance(port_map, dict):
missing_inkeys = set(port_map.keys()) - set(orig_ports.keys())
mapped_ports = {port_map[k]: v for k, v in orig_ports.items() if k in port_map}
else:
port_set = set(port_map)
missing_inkeys = port_set - set(orig_ports.keys())
mapped_ports = {k: v for k, v in orig_ports.items() if k in port_set}
if missing_inkeys:
raise PortError(f'`port_map` keys not present in source: {missing_inkeys}')
else:
mapped_ports = orig_ports
ports_in = {f'{in_prefix}{name}': port.deepcopy().rotate(pi)
for name, port in mapped_ports.items()}
ports_out = {f'{out_prefix}{name}': port.deepcopy()
for name, port in mapped_ports.items()}
duplicates = set(ports_out.keys()) & set(ports_in.keys())
if duplicates:
raise PortError(f'Duplicate keys after prefixing, try a different prefix: {duplicates}')
new = Pattern(ports={**ports_in, **ports_out})
return new
2023-04-12 13:56:50 -07:00
TT = TypeVar('TT')
def chain_elements(*args: Mapping[Any, Iterable[TT]]) -> Iterable[TT]:
2023-09-17 21:33:22 -07:00
"""
Iterate over each element in one or more {layer: elements} mappings.
Useful when you want to do some operation on all shapes and/or labels,
disregarding which layer they are on.
Args:
*args: One or more {layer: [element0, ...]} mappings.
Can also be applied to e.g. {target: [ref0, ...]} mappings.
Returns:
An iterable containing all elements, regardless of layer.
"""
2023-04-12 13:56:50 -07:00
return chain(*(chain.from_iterable(aa.values()) for aa in args))
def map_layers(
elements: Mapping[layer_t, Sequence[TT]],
2023-04-12 14:47:10 -07:00
map_layer: Callable[[layer_t], layer_t],
2023-04-12 13:56:50 -07:00
) -> defaultdict[layer_t, list[TT]]:
2023-09-17 21:33:22 -07:00
"""
Move all the elements from one layer onto a different layer.
Can also handle multiple such mappings simultaneously.
Args:
elements: Mapping of {old_layer: geometry_or_labels}.
map_layer: Callable which may be called with each layer present in `elements`,
and should return the new layer to which it will be mapped.
A simple example which maps `old_layer` to `new_layer` and leaves all others
as-is would look like `lambda layer: {old_layer: new_layer}.get(layer, layer)`
Returns:
Mapping of {new_layer: geometry_or_labels}
"""
2023-04-12 13:56:50 -07:00
new_elements: defaultdict[layer_t, list[TT]] = defaultdict(list)
for old_layer, seq in elements.items():
2023-04-12 14:47:10 -07:00
new_layer = map_layer(old_layer)
2023-04-12 13:56:50 -07:00
new_elements[new_layer].extend(seq)
return new_elements
def map_targets(
refs: Mapping[str | None, Sequence[Ref]],
2023-04-12 14:47:10 -07:00
map_target: Callable[[str | None], str | None],
2023-04-12 13:56:50 -07:00
) -> defaultdict[str | None, list[Ref]]:
2023-09-17 21:33:22 -07:00
"""
Change the target of all references to a given cell.
Can also handle multiple such mappings simultaneously.
Args:
refs: Mapping of {old_target: ref_objects}.
map_target: Callable which may be called with each target present in `refs`,
and should return the new target to which it will be mapped.
A simple example which maps `old_target` to `new_target` and leaves all others
as-is would look like `lambda target: {old_target: new_target}.get(target, target)`
Returns:
Mapping of {new_target: ref_objects}
"""
2023-04-12 13:56:50 -07:00
new_refs: defaultdict[str | None, list[Ref]] = defaultdict(list)
for old_target, seq in refs.items():
2023-04-12 14:47:10 -07:00
new_target = map_target(old_target)
2023-04-12 13:56:50 -07:00
new_refs[new_target].extend(seq)
return new_refs