FEATURE: Added primitive instance collection support (#510)

Author: drewm102

doc/source/api/glossary.rst

@@ -62,6 +62,13 @@ Glossary
 		- :obj:`str`
 		- :class:`Layer <ansys.edb.core.layer.layer.Layer>`
 
+	NetLike
+
+		Any of the following data types that represent a net.
+
+		- :obj:`str`
+		- :class:`Layer <ansys.edb.core.net.net.Net>`
+
 
 	RoughnessModel
 

doc/source/api/primitive.rst

@@ -18,6 +18,7 @@ Classes
    polygon.Polygon
    rectangle.Rectangle
    text.Text
+   primitive_instance_collection.PrimitiveInstanceCollection
 
 Enums
 -----

pyproject.toml

@@ -25,7 +25,7 @@ classifiers = [
 
 
 dependencies = [
-    "ansys-api-edb==0.2.dev2",
+    "ansys-api-edb==0.2.dev3",
     "protobuf>=3.19.3,<5",
     "grpcio>=1.44.0",
     "Django>=4.2.16"

src/ansys/edb/core/inner/factory.py

@@ -56,6 +56,7 @@ def _initialize_primitive_type_creator_params_dict():
     from ansys.edb.core.primitive.path import Path
     from ansys.edb.core.primitive.polygon import Polygon
     from ansys.edb.core.primitive.primitive import PrimitiveType
+    from ansys.edb.core.primitive.primitive_instance_collection import PrimitiveInstanceCollection
     from ansys.edb.core.primitive.rectangle import Rectangle
     from ansys.edb.core.primitive.text import Text
 
@@ -67,6 +68,7 @@ def _initialize_primitive_type_creator_params_dict():
         PrimitiveType.POLYGON: _CreatorParams(Polygon),
         PrimitiveType.RECTANGLE: _CreatorParams(Rectangle),
         PrimitiveType.TEXT: _CreatorParams(Text),
+        PrimitiveType.PRIM_INST_COLLECTION: _CreatorParams(PrimitiveInstanceCollection),
     }
     return _primitive_type_creator_params_dict
 

src/ansys/edb/core/inner/parser.py

@@ -17,7 +17,7 @@
 
 def to_point_data(fn):
     """Decorate a function that returns a message to return it as a ``PointData`` object."""
-    return _wraps(fn, _to_point_data)
+    return _wraps(fn, msg_to_point_data)
 
 
 def to_point_data_list(fn):
@@ -42,7 +42,7 @@ def to_3_point3d_data(fn):
 
 def to_polygon_data(fn):
     """Decorate a function that returns a message to return it as a ``PolygonData`` object."""
-    return _wraps(fn, _to_polygon_data)
+    return _wraps(fn, msg_to_polygon_data)
 
 
 def to_polygon_data_list(fn):
@@ -107,7 +107,7 @@ def wrapper(*args, **kwargs):
         return wrapper_fn(fn)
 
 
-def _to_point_data(message):
+def msg_to_point_data(message):
     """Convert a ``PointMessage`` object to a ``PointData`` object.
 
     Parameters
@@ -135,7 +135,7 @@ def _to_point_data_pair(message):
     -------
     tuple[:class:`.PointData`, :class:`.PointData`]
     """
-    return _to_point_data(message.point_0), _to_point_data(message.point_1)
+    return msg_to_point_data(message.point_0), msg_to_point_data(message.point_1)
 
 
 def _to_point_data_list(message):
@@ -149,7 +149,7 @@ def _to_point_data_list(message):
     -------
     list[:class:`.PointData`]
     """
-    return [_to_point_data(m) for m in message]
+    return [msg_to_point_data(m) for m in message]
 
 
 def _to_3_point3d_data(message):
@@ -183,7 +183,7 @@ def _to_point3d_data(message):
     return Point3DData(Value(message.x), Value(message.y), Value(message.z))
 
 
-def _to_polygon_data(message):
+def msg_to_polygon_data(message):
     """Convert an arbitrary message to a ``PolygonData`` object if possible.
 
     Parameters
@@ -218,11 +218,11 @@ def _to_polygon_data_list(message):
     list[:class:`.PolygonData`]
     """
     if hasattr(message, "polygons"):
-        return [_to_polygon_data(m) for m in message.polygons]
+        return [msg_to_polygon_data(m) for m in message.polygons]
     elif hasattr(message, "points"):
-        return [_to_polygon_data(m) for m in message.points]
+        return [msg_to_polygon_data(m) for m in message.points]
     else:
-        return [_to_polygon_data(m) for m in message]
+        return [msg_to_polygon_data(m) for m in message]
 
 
 def _to_box(message):
@@ -237,7 +237,7 @@ def _to_box(message):
     tuple[:class:`.PointData`, :class:`.PointData`]
     """
     if hasattr(message, "lower_left") and hasattr(message, "upper_right"):
-        return _to_point_data(message.lower_left), _to_point_data(message.upper_right)
+        return msg_to_point_data(message.lower_left), msg_to_point_data(message.upper_right)
 
 
 def _to_circle(message):
@@ -254,7 +254,7 @@ def _to_circle(message):
     from ansys.edb.core.utility.value import Value
 
     if hasattr(message, "center") and hasattr(message, "radius"):
-        return _to_point_data(message.center), Value(message.radius)
+        return msg_to_point_data(message.center), Value(message.radius)
 
 
 def _to_rlc(message):

src/ansys/edb/core/inner/rpc_info.py

@@ -528,6 +528,7 @@ def invalidates_cache(self):
         "GetBoardBendDefs": _RpcInfo(read_no_cache=True),
         "StreamBoardBendDefs": _RpcInfo(read_no_cache=True),
         "GetLayoutInstance": _RpcInfo(cache=True),
+        "CompressPrimitives": _RpcInfo(buffer=True),
     },
     "ansys.api.edb.v1.LayoutComponentService": {
         "ExportLayoutComponent": _RpcInfo(write_no_cache_invalidation=True),
@@ -859,6 +860,13 @@ def invalidates_cache(self):
         "IsZonePrimitive": _RpcInfo(cache=True),
         "MakeZonePrimitive": _RpcInfo(buffer=True),
     },
+    "ansys.api.edb.v1.PrimitiveInstanceCollectionService": {
+        "GetGeometry": _RpcInfo(cache=True),
+        "SetGeometry": _RpcInfo(buffer=True),
+        "GetPositions": _RpcInfo(read_no_cache=True),
+        "GetInstantiatedGeometry": _RpcInfo(read_no_cache=True),
+        "Decompose": _RpcInfo(buffer=True),
+    },
     "ansys.api.edb.v1.RaptorXGeneralSettingsService": {
         "GetUseGoldEMSolver": _RpcInfo(cache=True),
         "SetUseGoldEMSolver": _RpcInfo(buffer=True),

src/ansys/edb/core/inner/utils.py

@@ -43,3 +43,13 @@ def add_msgs_to_items(edb_obj_collection_msg):
         for streamed_items in unary_streaming_rpc(request):
             add_msgs_to_items(streamed_items)
     return items
+
+
+def stream_items_from_server(parser, stream, chunk_items_att_name):
+    """Stream all items from the provided unary server stream and convert them to \
+    the corresponding pyedb-core data type using the provided parser."""
+    return [
+        parser(chunk_entry)
+        for chunk in stream
+        for chunk_entry in getattr(chunk, chunk_items_att_name)
+    ]

src/ansys/edb/core/layout/layout.py

@@ -533,3 +533,17 @@ def create_mesh_region(
                 num_y_partitions=num_y_partitions,
             )
         )
+
+    def compress_primitives(self):
+        """Compress :class:`primitives <.Primitive>` into \
+        :class:`primitive instance collections <.PrimitiveInstanceCollection>`.
+
+        Primitives whose only geometric difference is location will be compressed. \
+        For example, a 4x4 grid of rectangles with the same width and height will be \
+        compressed into one primitive instance collection.
+
+        .. note::
+           Only :class:`.Circle`, :class:`.Rectangle`, and :class:`.Polygon` primitives \
+           are supported in primitive instance collections.
+        """
+        self.__stub.CompressPrimitives(self.msg)

src/ansys/edb/core/primitive/primitive.py

@@ -22,6 +22,7 @@ class PrimitiveType(Enum):
     TEXT = primitive_pb2.TEXT
     PATH_3D = primitive_pb2.PATH_3D
     BOARD_BEND = primitive_pb2.BOARD_BEND
+    PRIM_INST_COLLECTION = primitive_pb2.PRIM_INST_COLLECTION
     INVALID_TYPE = primitive_pb2.INVALID_TYPE
 
 

src/ansys/edb/core/primitive/primitive_instance_collection.py

@@ -0,0 +1,118 @@
+"""Primitive Instance Collection."""
+from __future__ import annotations
+
+from typing import TYPE_CHECKING, List
+
+if TYPE_CHECKING:
+    from ansys.edb.core.geometry.polygon_data import PolygonData
+    from ansys.edb.core.geometry.point_data import PointData
+    from ansys.edb.core.typing import PointLike, LayerLike, NetLike
+    from ansys.edb.core.layout.layout import Layout
+
+from ansys.api.edb.v1.primitive_instance_collection_pb2 import (
+    PrimitiveInstanceCollectionDataMessage,
+)
+from ansys.api.edb.v1.primitive_instance_collection_pb2_grpc import (
+    PrimitiveInstanceCollectionServiceStub,
+)
+
+from ansys.edb.core.inner.layout_obj import LayoutObj
+import ansys.edb.core.inner.messages as messages
+from ansys.edb.core.inner.parser import msg_to_point_data, msg_to_polygon_data, to_polygon_data
+from ansys.edb.core.inner.utils import stream_items_from_server
+from ansys.edb.core.session import StubAccessor, StubType
+
+
+class PrimitiveInstanceCollection(LayoutObj):
+    """Efficiently represents large quantities of geometry as \
+    numerous instantiations of the same geometry at different locations."""
+
+    __stub: PrimitiveInstanceCollectionServiceStub = StubAccessor(
+        StubType.primitive_instance_collection
+    )
+
+    @staticmethod
+    def _point_request_iterator(points, starting_chunk):
+        chunk = starting_chunk
+        max_size = 8000
+        for point in points:
+            point_msg = messages.point_message(point)
+            if chunk.ByteSize() + point_msg.ByteSize() > max_size:
+                yield chunk
+                chunk = PrimitiveInstanceCollectionDataMessage()
+            chunk.points.points.append(point_msg)
+        yield chunk
+
+    @classmethod
+    def create(
+        cls,
+        layout: Layout,
+        net: NetLike,
+        layer: LayerLike,
+        geometry: PolygonData,
+        positions: List[PointLike],
+    ) -> PrimitiveInstanceCollection:
+        """Create a primitive instance collection containing the specified geometry instantiated \
+        at the provided locations. All geometry will be created on the specified layer and net.
+
+        Parameters
+        ----------
+        layout : .Layout
+            Layout to create the primitive instance collection in.
+        net : :term:`NetLike`
+            Net that the primitive instance collection geometry will exist on.
+        layer : :term:`LayerLike`
+            Layer that the primitive instance collection geometry will exist on.
+        geometry : .PolygonData
+            The geometry that will be instantiated.
+        positions : list of :term:`PointLike`
+            The points to instantiate the geometry at.
+
+        Returns
+        -------
+        .PrimitiveInstanceCollection
+        """
+        chunk = PrimitiveInstanceCollectionDataMessage(
+            lyt_or_prim_inst_col=layout.msg,
+            net=messages.net_ref_message(net),
+            layer=messages.layer_ref_message(layer),
+            geometry=messages.polygon_data_message(geometry),
+        )
+        return PrimitiveInstanceCollection(
+            cls.__stub.Create(cls._point_request_iterator(positions, chunk))
+        )
+
+    @property
+    @to_polygon_data
+    def geometry(self) -> PolygonData:
+        """:class:`.PolygonData`: The geometry that the primitive instance collection instantiates."""
+        return self.__stub.GetGeometry(self.msg)
+
+    @geometry.setter
+    def geometry(self, geometry: PolygonData):
+        self.__stub.SetGeometry(messages.polygon_data_property_message(self, geometry))
+
+    @property
+    def positions(self) -> List[PointData]:
+        """:obj:`list` of :class:`.PointData`: The positions geometry is instantiated at."""
+        return stream_items_from_server(
+            msg_to_point_data, self.__stub.GetPositions(self.msg), "points"
+        )
+
+    @positions.setter
+    def positions(self, positions: List[PointData]):
+        chunk = PrimitiveInstanceCollectionDataMessage(lyt_or_prim_inst_col=self.msg)
+        self.__stub.SetPositions(self._point_request_iterator(positions, chunk))
+
+    @property
+    def instantiated_geometry(self) -> List[PolygonData]:
+        """:obj:`list` of :class:`.PolygonData`: The geometry instantiated at each location in \
+        the primitive instance collection."""
+        return stream_items_from_server(
+            msg_to_polygon_data, self.__stub.GetInstantiatedGeometry(self.msg), "polygons"
+        )
+
+    def decompose(self):
+        """Decompose into individual :class:`primitives <.Primitive>`. A \
+        :class:`primitive <.Primitive>` will be created for each geometry instantiation."""
+        return self.__stub.Decompose(self.msg)