added convenience function for voltage integral

tidy3d/components/geometry/base.py

@@ -684,6 +684,29 @@ def parse_xyz_kwargs(**xyz) -> Tuple[Axis, float]:
         axis = "xyz".index(axis_label)
         return axis, position
 
+    @staticmethod
+    def parse_two_xyz_kwargs(**xyz) -> List[Tuple[Axis, float]]:
+        """Turns x,y,z kwargs into indices of axes and the position along each axis.
+
+        Parameters
+        ----------
+        x : float = None
+            Position in x direction, only two of x,y,z can be specified to define line.
+        y : float = None
+            Position in y direction, only two of x,y,z can be specified to define line.
+        z : float = None
+            Position in z direction, only two of x,y,z can be specified to define line.
+
+        Returns
+        -------
+        [(int, float), (int, float)]
+            Index into xyz axis (0,1,2) and position along that axis.
+        """
+        xyz_filtered = {k: v for k, v in xyz.items() if v is not None}
+        assert len(xyz_filtered) == 2, "exactly two kwarg in [x,y,z] must be specified."
+        xyz_list = list(xyz_filtered.items())
+        return [("xyz".index(axis_label), position) for axis_label, position in xyz_list]
+
     @staticmethod
     def rotate_points(points: ArrayFloat3D, axis: Coordinate, angle: float) -> ArrayFloat3D:
         """Rotate a set of points in 3D.

tidy3d/plugins/microwave/path_integrals.py

@@ -19,7 +19,7 @@
     TimeDataArray,
 )
 from ...components.data.monitor_data import FieldData, FieldTimeData, ModeSolverData
-from ...components.geometry.base import Box
+from ...components.geometry.base import Box, Geometry
 from ...components.types import Ax, Axis, Coordinate2D, Direction
 from ...components.validators import assert_line, assert_plane
 from ...components.viz import add_ax_if_none
@@ -228,6 +228,62 @@ def _set_data_array_attributes(data_array: IntegralResultTypes) -> IntegralResul
         data_array.name = "V"
         return data_array.assign_attrs(units=VOLT, long_name="voltage")
 
+    @staticmethod
+    def from_terminal_positions(
+        plus_terminal: float,
+        minus_terminal: float,
+        x: float = None,
+        y: float = None,
+        z: float = None,
+        extrapolate_to_endpoints: bool = True,
+        snap_path_to_grid: bool = True,
+    ) -> VoltageIntegralAxisAligned:
+        """Helper to create a :class:`VoltageIntegralAxisAligned` from two coordinates that
+        define a line and two positions indicating the endpoints of the path integral.
+        Parameters
+        ----------
+        plus_terminal : float
+            Position along the voltage axis of the positive terminal.
+        minus_terminal : float
+            Position along the voltage axis of the negative terminal.
+        x : float = None
+            Position in x direction, only two of x,y,z can be specified to define line.
+        y : float = None
+            Position in y direction, only two of x,y,z can be specified to define line.
+        z : float = None
+            Position in z direction, only two of x,y,z can be specified to define line.
+        extrapolate_to_endpoints: bool = True
+            Passed directly to :class:`VoltageIntegralAxisAligned`
+        snap_path_to_grid: bool = True
+            Passed directly to :class:`VoltageIntegralAxisAligned`
+
+        Returns
+        -------
+        VoltageIntegralAxisAligned
+            The created path integral for computing voltage between the two terminals.
+        """
+        axis_positions = Geometry.parse_two_xyz_kwargs(x=x, y=y, z=z)
+        # Calculate center and size of the future box
+        midpoint = (plus_terminal + minus_terminal) / 2
+        length = np.abs(plus_terminal - minus_terminal)
+        center = [midpoint, midpoint, midpoint]
+        size = [length, length, length]
+        for axis, position in axis_positions:
+            size[axis] = 0
+            center[axis] = position
+
+        direction = "+"
+        if plus_terminal < minus_terminal:
+            direction = "-"
+
+        return VoltageIntegralAxisAligned(
+            center=center,
+            size=size,
+            extrapolate_to_endpoints=extrapolate_to_endpoints,
+            snap_path_to_grid=snap_path_to_grid,
+            sign=direction,
+        )
+
     @add_ax_if_none
     def plot(
         self,