FEATURE: Fixed up utility doc

Author: chenchienjacklin

doc/source/api/utility.rst

@@ -20,3 +20,15 @@ Classes
    transform.Transform
    transform3d.Transform3D
    value.Value
+
+
+Enums
+-----
+
+.. autosummary::
+   :toctree: _autosummary
+
+   heat_sink.HeatSinkFinOrientation
+   hfss_extent_info.HFSSExtentInfoType
+   hfss_extent_info.OpenRegionType
+   layer_map.LayerMapUniqueDirection

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

@@ -12,7 +12,7 @@
 from ansys.edb.core.primitive.primitive import Primitive
 from ansys.edb.core.session import StubAccessor, StubType
 from ansys.edb.core.simulation_setup.simulation_setup import SimulationSetup
-from ansys.edb.core.utility.hfss_extent_info import HfssExtentInfo
+from ansys.edb.core.utility.hfss_extent_info import HfssExtentInfo, HFSSExtentInfoType, OpenRegionType
 from ansys.edb.core.utility.temperature_settings import TemperatureSettings
 from ansys.edb.core.utility.value import Value
 
@@ -93,11 +93,11 @@ def primitive_helper(msg):
     },
     "HfssExtentsType": {
         "msg": _translate_hfss_extents_enums,
-        "val": HfssExtentInfo.HFSSExtentInfoType,
+        "val": HFSSExtentInfoType,
     },
     "HfssExtentsOpenRegionType": {
         "msg": _translate_hfss_extents_enums,
-        "val": HfssExtentInfo.OpenRegionType,
+        "val": OpenRegionType,
     },
 }
 

src/ansys/edb/core/utility/conversions.py

@@ -1,20 +1,27 @@
 """This module performs conversions from arbitrary user input to explicit types."""
+from __future__ import annotations
+
+from typing import TYPE_CHECKING
+
+if TYPE_CHECKING:
+    from ansys.edb.core.typing import ValueLike, PointLike, Point3DLike
+
 from ansys.api.edb.v1.edb_messages_pb2 import ValueMessage
 
 from ansys.edb.core.geometry import point3d_data, point_data
 from ansys.edb.core.utility import value
 
 
-def to_value(val):
-    """Take a value implicitly convertible to a ``Value``type and return as a ``Value`` type.
+def to_value(val: ValueLike) -> value.Value:
+    """Take a value implicitly convertible to a :class:`.Value` type and return as a :class:`.Value` type.
 
     Parameters
     ----------
-    val : ansys.edb.core.typing.ValueLike
+    val : :term:`ValueLike`
 
     Returns
     -------
-    :class:`.Value`
+    .Value
     """
     if isinstance(val, value.Value):
         return val
@@ -26,16 +33,16 @@ def to_value(val):
         )
 
 
-def to_point(val):
-    """Take a value implicitly convertible to a ``PointData`` type and return as a ``PointData`` type.
+def to_point(val: PointLike) -> point_data.PointData:
+    """Take a value implicitly convertible to a :class:`.PointData` type and return as a :class:`.PointData` type.
 
     Parameters
     ----------
-    val : ansys.edb.core.typing.PointLike
+    val : :term:`Point2DLike`
 
     Returns
     -------
-    :class:`.PointData`
+    .PointData
     """
     if isinstance(val, point_data.PointData):
         return val
@@ -50,17 +57,16 @@ def to_point(val):
     )
 
 
-def to_point3d(val):
-    """Convert a value to a ``Point3DData`` object.
+def to_point3d(val: Point3DLike) -> point3d_data.Point3DData:
+    """Take a value implicitly convertible to a :class:`.Point3DData` type and return as a :class:`.Point3DData` type.
 
     Parameters
     ----------
-    val : Point3DData, tuple[:term:`ValueLike`,:term:`ValueLike`,:term:`ValueLike`]
-        Value to convert.
+    val : :term:`Point3DLike`
 
     Returns
     -------
-    :class:`.Point3DData`
+    .Point3DData
     """
     if isinstance(val, point3d_data.Point3DData):
         return val

src/ansys/edb/core/utility/heat_sink.py

@@ -1,4 +1,10 @@
 """Heat sink."""
+from __future__ import annotations
+
+from typing import TYPE_CHECKING
+
+if TYPE_CHECKING:
+    from ansys.edb.core.typing import ValueLike
 
 from enum import Enum
 
@@ -16,7 +22,7 @@ class HeatSinkFinOrientation(Enum):
 
 
 class HeatSink:
-    """Represents a heat sink.
+    """Represents a heat sink, a three-dimensional modeling component that can exchange radiation with other objects in the model.
 
     Attributes
     ----------
@@ -28,20 +34,33 @@ class HeatSink:
             Base elevation of the the heat sink.
         fin_height : :term:`ValueLike`
             Fin height of the heat sink.
-        fin_orientation : HeatSinkFinOrientation
+        fin_orientation : .HeatSinkFinOrientation
             Fin orientation of the heat sink if it is not set to the X axis.
-
     """
 
     def __init__(
         self,
-        fin_thickness=0,
-        fin_spacing=0,
-        fin_base_height=0,
-        fin_height=0,
-        fin_orientation=HeatSinkFinOrientation.X_ORIENTED,
+        fin_thickness: ValueLike = 0,
+        fin_spacing: ValueLike = 0,
+        fin_base_height: ValueLike = 0,
+        fin_height: ValueLike = 0,
+        fin_orientation: HeatSinkFinOrientation = HeatSinkFinOrientation.X_ORIENTED,
     ):
-        """Initialize a heat sink object using given values."""
+        """Initialize a heat sink object using given values.
+        
+        Parameters
+        ----------
+        fin_thickness : :term:`ValueLike`
+            Fin thickness of the heat sink.
+        fin_spacing : :term:`ValueLike`
+            Fin spacing of the heat sink.
+        fin_base_height : :term:`ValueLike`
+            Base elevation of the the heat sink.
+        fin_height : :term:`ValueLike`
+            Fin height of the heat sink.
+        fin_orientation : .HeatSinkFinOrientation
+            Fin orientation of the heat sink if it is not set to the X axis.
+        """
         self.fin_thickness = conversions.to_value(fin_thickness)
         self.fin_spacing = conversions.to_value(fin_spacing)
         self.fin_base_height = conversions.to_value(fin_base_height)

src/ansys/edb/core/utility/hfss_extent_info.py

@@ -1,4 +1,11 @@
 """HFSS extent information."""
+from __future__ import annotations
+
+from typing import TYPE_CHECKING, Tuple
+
+if TYPE_CHECKING:
+    from ansys.edb.core.typing import ValueLike
+    from ansys.edb.core.primitive.primitive import Primitive
 
 from enum import Enum
 
@@ -8,128 +15,131 @@
 from ansys.edb.core.utility.value import Value
 
 
+class HFSSExtentInfoType(Enum):
+    """Provides an enum representing available HFSS extent information types."""
+
+    BOUNDING_BOX = edb_defs_pb2.HFSS_EXTENT_BOUNDING_BOX
+    CONFORMING = edb_defs_pb2.HFSS_EXTENT_CONFIRMING
+    CONVEX_HUL = edb_defs_pb2.HFSS_EXTENT_CONVEX_HULL
+    POLYGON = edb_defs_pb2.HFSS_EXTENT_POLYGON
+
+class OpenRegionType(Enum):
+    """Provides an enum representing open region types."""
+
+    RADIATION = edb_defs_pb2.HFSS_EXTENT_RADIATION
+    PML = edb_defs_pb2.HFSS_EXTENT_PML
+
+
 class HfssExtentInfo:
     """Provides HFSS extent information.
 
     Attributes
     ----------
-        use_open_region: bool
+        use_open_region : bool, default: ``True``
             Whether an open region is used.
-        extent_type: HfssExtentInfo.HFSSExtentInfoType
+        extent_type : HFSSExtentInfoType, default: BOUNDING_BOX
             Extent type.
-        open_region_type: HfssExtentInfo.OpenRegionType
+        open_region_type : OpenRegionType, default: RADIATION
             Open region type.
-        base_polygon: Primitive
+        base_polygon : .Primitive, default: None
             Polygon to use if the extent is the ``Polygon`` type.
-        dielectric_extent_type: HfssExtentInfo.HFSSExtentInfoType
+        dielectric_extent_type : HFSSExtentInfoType, default: BOUNDING_BOX
             Dielectric extent type.
-        dielectric_base_polygon : :class:`.Primitive`
-            Polygon to use if dielectric extent is is the ``Polygon`` type.
-        dielectric: (float, bool)
-            Dielectric extent size. The first parameter is the value, and the second parameter \
-            indicates if the value is a multiple.
-        honor_user_dielectric: bool
-            Whether to honor a user-defined dielectric primitive when calculating a dielectric extent.
-        airbox_truncate_at_ground: bool
+        dielectric_base_polygon : .Primitive, default: None
+            Polygon to use if dielectric extent is the ``Polygon`` type.
+        dielectric : (float, bool), default: (0, True)
+            Dielectric extent size. The first parameter is the value.
+            The second parameter is a Boolean indicating if the value is a multiple.
+        honor_user_dielectric : bool, default: ``True``
+            Whether to honor a user-defined dielectric primitive when calculating the dielectric
+            extent.
+        airbox_truncate_at_ground : bool, default: ``False``
             Whether to truncate the airbox at the ground layers.
-        airbox_horizontal: (float, bool)
-            Airbox horizontal extent size. The first parameter is the value, and the second parameter \
-            indicates if the value is a multiple.
-        airbox_vertical_positive: (float, bool)
-            Airbox positive vertical extent size. The first parameter is the value, and the second parameter \
-            indicates if the value is a multiple.
-        airbox_vertical_negative: (float, bool)
-            Airbox negative vertical extent size. The first parameter is the value, and the second parameter \
-            indicates if the value is a multiple.
-        sync_airbox_vertical_extent: bool
+        airbox_horizontal : (float, bool), default: (0.15, True)
+            Airbox horizontal extent size. The first parameter is the value.
+            The second parameter is a Boolean indicating if the value is a multiple.
+        airbox_vertical_positive : (float, bool), default: (0.15, True)
+            Airbox positive vertical extent size. The first parameter is the value.
+            The second parameter is a Boolean indicating if the value is a multiple.
+        airbox_vertical_negative : (float, bool), default: (0.15, True)
+            Airbox negative vertical extent size. The first parameter is the value.
+            The second parameter is a Boolean indicating if the value is a multiple.
+        sync_airbox_vertical_extent : bool, default: ``True``
             Whether to synchronize the airbox positive and negative vertical extent.
-        is_pml_visible: bool
-            Whether to check to see if the PML boxes are to rendered.
-        operating_frequency : :class:`.Value`
+        is_pml_visible : bool, default: ``False``
+            Whether to check to see if PML boxes are to be rendered.
+        operating_frequency : :term:`ValueLike`, default: ``5GHz``
             PML operating frequency.
-        radiation_level : :class:`.Value`
+        radiation_level : .Value, default: 0
             PML radiation level for calculating the thickness of the boundary.
-        user_xy_data_extent_for_vertical_expansion: bool
+        user_xy_data_extent_for_vertical_expansion : bool, default: ``True``
             Whether to retain the old behavior for the vertical expansion of the airbox.
-            If ``True``, the vertical extent is calculated from the XY data extent.
+            The default is ``True``, in which case the vertical extent is calculated from
+            the XY data extent.
     """
 
-    class HFSSExtentInfoType(Enum):
-        """Provides an enum representing available HFSS extent information types."""
-
-        BOUNDING_BOX = edb_defs_pb2.HFSS_EXTENT_BOUNDING_BOX
-        CONFORMING = edb_defs_pb2.HFSS_EXTENT_CONFIRMING
-        CONVEX_HUL = edb_defs_pb2.HFSS_EXTENT_CONVEX_HULL
-        POLYGON = edb_defs_pb2.HFSS_EXTENT_POLYGON
-
-    class OpenRegionType(Enum):
-        """Provides an enum representing open region types."""
-
-        RADIATION = edb_defs_pb2.HFSS_EXTENT_RADIATION
-        PML = edb_defs_pb2.HFSS_EXTENT_PML
-
     def __init__(
         self,
-        use_open_region=True,
-        extent_type=HFSSExtentInfoType.BOUNDING_BOX,
-        open_region_type=OpenRegionType.RADIATION,
-        base_polygon=None,
-        dielectric_extent_type=HFSSExtentInfoType.BOUNDING_BOX,
-        dielectric_base_polygon=None,
-        dielectric=(0, True),
-        honor_user_dielectric=True,
-        airbox_truncate_at_ground=False,
-        airbox_horizontal=(0.15, True),
-        airbox_vertical_positive=(0.15, True),
-        airbox_vertical_negative=(0.15, True),
-        sync_airbox_vertical_extent=True,
-        is_pml_visible=False,
-        operating_frequency="5GHz",
-        radiation_level=Value(0),
-        user_xy_data_extent_for_vertical_expansion=True,
+        use_open_region: bool = True,
+        extent_type: HFSSExtentInfoType = HFSSExtentInfoType.BOUNDING_BOX,
+        open_region_type: OpenRegionType = OpenRegionType.RADIATION,
+        base_polygon: Primitive = None,
+        dielectric_extent_type: HFSSExtentInfoType = HFSSExtentInfoType.BOUNDING_BOX,
+        dielectric_base_polygon: Primitive = None,
+        dielectric: Tuple[float, bool] =(0, True),
+        honor_user_dielectric: bool = True,
+        airbox_truncate_at_ground: bool = False,
+        airbox_horizontal: Tuple[float, bool] = (0.15, True),
+        airbox_vertical_positive: Tuple[float, bool] = (0.15, True),
+        airbox_vertical_negative: Tuple[float, bool] = (0.15, True),
+        sync_airbox_vertical_extent: bool = True,
+        is_pml_visible: bool = False,
+        operating_frequency: ValueLike = "5GHz",
+        radiation_level: Value = Value(0),
+        user_xy_data_extent_for_vertical_expansion: bool = True,
     ):
         """Create an HFSS extent information object.
 
         Parameters
         ----------
-        use_open_region: bool, default: True
+        use_open_region : bool, default: ``True``
             Whether an open region is used.
-        extent_type: HfssExtentInfo.HFSSExtentInfoType, default: BOUNDING_BOX
+        extent_type : HFSSExtentInfoType, default: BOUNDING_BOX
             Extent type.
-        open_region_type: HfssExtentInfo.OpenRegionType, default: RADIATION
+        open_region_type: OpenRegionType, default: RADIATION
             Open region type.
-        base_polygon: Primitive, default: None
+        base_polygon : .Primitive, default: None
             Polygon to use if the extent is the ``Polygon`` type.
-        dielectric_extent_type: HfssExtentInfo.HFSSExtentInfoType, default: BOUNDING_BOX
+        dielectric_extent_type : HFSSExtentInfoType, default: BOUNDING_BOX
             Dielectric extent type.
-        dielectric_base_polygon : :class:`.Primitive`, default: None
+        dielectric_base_polygon : .Primitive, default: None
             Polygon to use if dielectric extent is the ``Polygon`` type.
-        dielectric: (float, bool), default: (0, True)
+        dielectric : (float, bool), default: (0, True)
             Dielectric extent size. The first parameter is the value.
             The second parameter is a Boolean indicating if the value is a multiple.
-        honor_user_dielectric: bool, default: True
+        honor_user_dielectric : bool, default: ``True``
             Whether to honor a user-defined dielectric primitive when calculating the dielectric
             extent.
-        airbox_truncate_at_ground: bool, default: False
+        airbox_truncate_at_ground : bool, default: ``False``
             Whether to truncate the airbox at the ground layers.
-        airbox_horizontal: (float, bool), default: (0.15, True)
+        airbox_horizontal : (float, bool), default: (0.15, True)
             Airbox horizontal extent size. The first parameter is the value.
             The second parameter is a Boolean indicating if the value is a multiple.
-        airbox_vertical_positive: (float, bool), default: (0.15, True)
+        airbox_vertical_positive : (float, bool), default: (0.15, True)
             Airbox positive vertical extent size. The first parameter is the value.
             The second parameter is a Boolean indicating if the value is a multiple.
-        airbox_vertical_negative: (float, bool), default: (0.15, True)
+        airbox_vertical_negative : (float, bool), default: (0.15, True)
             Airbox negative vertical extent size. The first parameter is the value.
             The second parameter is a Boolean indicating if the value is a multiple.
-        sync_airbox_vertical_extent: bool, default: True
+        sync_airbox_vertical_extent : bool, default: ``True``
             Whether to synchronize the airbox positive and negative vertical extent.
-        is_pml_visible: bool, default: False
+        is_pml_visible : bool, default: ``False``
             Whether to check to see if PML boxes are to be rendered.
-        operating_frequency : :class:`.Value`, default: "5GHz"
+        operating_frequency : :term:`ValueLike`, default: 5GHz
             PML operating frequency.
-        radiation_level : :class:`.Value`, default: 0
+        radiation_level : .Value, default: 0
             PML radiation level for calculating the thickness of the boundary.
-        user_xy_data_extent_for_vertical_expansion: bool, default: True
+        user_xy_data_extent_for_vertical_expansion : bool, default: ``True``
             Whether to retain the old behavior for the vertical expansion of the airbox.
             The default is ``True``, in which case the vertical extent is calculated from
             the XY data extent.