fdtdx.SimulationObject

def extend_to(
    self,
    other: "SimulationObject | None",
    axis: int,
    direction: Literal["+", "-"],
    other_position: float | None = None,
    offset: float = 0,
    grid_offset: int = 0,
) -> SizeExtensionConstraint:
    """Creates a SizeExtensionConstraint that extends this object along a specified axis until it
    reaches another object or the simulation boundary. The extension can be in either positive or
    negative direction.

    Args:
        other (SimulationObject | None): Target object to extend to, or None to extend to simulation boundary
        axis (int): Which axis to extend along (0, 1, or 2)
        direction (Literal["+", "-"]): Direction to extend in ('+' or '-')
        other_position (float | None, optional): Relative position on target object (-1 to 1) to extend to.
            If None, defaults to the corresponding side (-1 for '+' direction, 1 for '-' direction). Defaults to
            None.
        offset (float, optional): Additional offset in meters to apply after extension. Ignored when extending to
            simulation boundary. Defaults to zero.
        grid_offset (int, optional): Additional offset in Yee-grid voxels to apply after extension. Ignored when
            extending to simulation boundary. Defaults to zero.

    Returns:
        SizeExtensionConstraint: Constraint defining how the object extends
    """
    # default: extend to corresponding side
    if other_position is None:
        other_position = -1 if direction == "+" else 1
    if other is None:
        if offset != 0 or grid_offset != 0:
            raise Exception("Cannot use offset when extending object to infinity")
    return SizeExtensionConstraint(
        object=self,
        other_object=other,
        axis=axis,
        direction=direction,
        other_position=other_position,
        offset=offset,
        grid_offset=grid_offset,
    )

def face_to_face_negative_direction(
    self,
    other: "SimulationObject",
    axes: tuple[int, ...] | int,
    margins: tuple[float, ...] | float | None = None,
    grid_margins: tuple[int, ...] | int | None = None,
) -> PositionConstraint:
    """Creates a PositionConstraint that places this object facing another object in the negative direction
    of specified axes. The objects will touch at their facing boundaries unless margins are specified.

    Args:
        other (SimulationObject): Another object in the simulation scene
        axes (tuple[int, ...] | int): Either a single integer or a tuple describing which axes to align on
        margins (tuple[float, ...] | float | None, optional): Additional margins in meters between the facing
            surfaces. Must have same length as axes. If None, no margin is used. Defaults to None.
        grid_margins (tuple[int, ...] | int | None, optional): Additional margins in Yee-grid voxels between the
            facing surfaces. Must have same length as axes. If None, no margin is used. Defaults to None.

    Returns:
        PositionConstraint: Position constraint aligning objects face-to-face in negative direction
    """
    if isinstance(axes, int):
        axes = (axes,)
    own_positions = tuple([1 for _ in axes])
    other_positions = tuple([-1 for _ in axes])
    constraint = self.place_relative_to(
        other=other,
        axes=axes,
        own_positions=own_positions,
        other_positions=other_positions,
        margins=margins,
        grid_margins=grid_margins,
    )
    return constraint

def face_to_face_positive_direction(
    self,
    other: "SimulationObject",
    axes: tuple[int, ...] | int,
    margins: tuple[float, ...] | float | None = None,
    grid_margins: tuple[int, ...] | int | None = None,
) -> PositionConstraint:
    """Creates a PositionConstraint that places this object facing another object in the positive direction
    of specified axes. The objects will touch at their facing boundaries unless margins are specified.

    Args:
        other (SimulationObject): Another object in the simulation scene
        axes (tuple[int, ...] | int): Either a single integer or a tuple describing which axes to align on
        margins (tuple[float, ...] | float | None, optional): Additional margins in meters between the facing
            surfaces. Must have same length as axes. If None, no margin is used. Defaults to None.
        grid_margins (tuple[int, ...] | int | None, optional): Additional margins in Yee-grid voxels between the
            facing surfaces. Must have same length as axes. If None, no margin is used. Defaults to None

    Returns:
        PositionConstraint: Position constraint aligning objects face-to-face in positive direction
    """
    if isinstance(axes, int):
        axes = (axes,)
    own_positions = tuple([-1 for _ in axes])
    other_positions = tuple([1 for _ in axes])
    constraint = self.place_relative_to(
        other=other,
        axes=axes,
        own_positions=own_positions,
        other_positions=other_positions,
        margins=margins,
        grid_margins=grid_margins,
    )
    return constraint

def place_above(
    self,
    other: "SimulationObject",
    margins: tuple[float, ...] | float | None = None,
    grid_margins: tuple[int, ...] | int | None = None,
) -> PositionConstraint:
    """Creates a PositionConstraint that places this object above another object along the z-axis.
    This is a convenience wrapper around face_to_face_positive_direction() for axis 2 (z-axis).

    Args:
        other (SimulationObject): Another object in the simulation scene
        margins (tuple[float, ...] | float | None, optional): Additional vertical margins in meters between objects.
            If None, no margin is used. Defaults to None.
        grid_margins (tuple[int, ...] | int | None, optional): Additional vertical margins in Yee-grid voxels
            between objects. If None, no margin is used. Defaults to None.

    Returns:
        PositionConstraint: Position constraint placing this object above the other
    """
    constraint = self.face_to_face_positive_direction(
        other=other,
        axes=(2,),
        margins=margins,
        grid_margins=grid_margins,
    )
    return constraint

def place_at_center(
    self,
    other: "SimulationObject",
    axes: tuple[int, ...] | int = (0, 1, 2),
    own_positions: tuple[float, ...] | float | None = None,
    other_positions: tuple[float, ...] | float | None = None,
    margins: tuple[float, ...] | float | None = None,
    grid_margins: tuple[int, ...] | int | None = None,
) -> PositionConstraint:
    """Creates a PositionConstraint that centers this object relative to another object along specified axes.
    This is a convenience wrapper around place_relative_to() with default positions at the center (0).

    Args:
        other (SimulationObject): Another object in the simulation scene
        axes (tuple[int, ...] | int, optional): Either a single integer or a tuple describing which axes to center
            on. Defaults to all axes (0, 1, 2).
        own_positions (tuple[float, ...] | float | None, optional): Relative positions on this object (-1 to 1).
            If None, uses center (0). Defaults to None.
        other_positions (tuple[float, ...] | float | None, optional): Relative positions on other object (-1 to 1).
            If None, uses center (0). Defaults to None.
        margins (tuple[float, ...] | float | None, optional): Additional margins in meters between objects.
            Must have same length as axes. If None, no margin is used. Defaults to None.
        grid_margins ( tuple[int, ...] | int | None, optional): Additional margins in Yee-grid voxels between
            objects. Must have same length as axes. If None, no margin is used. Defaults to None.

    Returns:
        PositionConstraint: Position constraint centering objects relative to each other
    """
    if isinstance(axes, int):
        axes = (axes,)
    if own_positions is None:
        own_positions = tuple([0 for _ in axes])
    if other_positions is None:
        other_positions = tuple([0 for _ in axes])
    constraint = self.place_relative_to(
        other=other,
        axes=axes,
        own_positions=own_positions,
        other_positions=other_positions,
        margins=margins,
        grid_margins=grid_margins,
    )
    return constraint

def place_below(
    self,
    other: "SimulationObject",
    margins: tuple[float, ...] | float | None = None,
    grid_margins: tuple[int, ...] | int | None = None,
) -> PositionConstraint:
    """Creates a PositionConstraint that places this object below another object along the z-axis.
    This is a convenience wrapper around face_to_face_negative_direction() for axis 2 (z-axis).

    Args:
        other (SimulationObject): Another object in the simulation scene
        margins (tuple[float, ...] | float | None, optional): Additional vertical margins in meters between objects.
            If None, no margin is used. Defaults to None.
        grid_margins (tuple[int, ...] | int | None, optional): Additional vertical margins in Yee-grid voxels
            between objects. If None, no margin is used. Defaults to None.

    Returns:
        PositionConstraint: Position constraint placing this object below the other
    """
    constraint = self.face_to_face_negative_direction(
        other=other,
        axes=(2,),
        margins=margins,
        grid_margins=grid_margins,
    )
    return constraint

def place_relative_to(
    self,
    other: "SimulationObject",
    axes: tuple[int, ...] | int,
    own_positions: tuple[float, ...] | float,
    other_positions: tuple[float, ...] | float,
    margins: tuple[float, ...] | float | None = None,
    grid_margins: tuple[int, ...] | int | None = None,
) -> PositionConstraint:
    """Creates a PositionalConstraint between two objects. The constraint is defined by anchor points on
    both objects, which are constrainted to be at the same position. Anchors are defined in relative coordinates,
    i.e. a position of -1 is the left object boundary in the repective axis and a position of +1 the right boundary.

    Args:
        other (SimulationObject): Another object in the simulation scene
        axes (tuple[int, ...] | int): Eiter a single integer or a tuple describing the axes of the constraints
        own_positions (tuple[float, ...] | float): The positions of the own anchor in the axes. Must have the same lengths as axes
        other_positions (tuple[float, ...] | float): The positions of the other objects' anchor in the axes. Must have the same lengths as axes
        margins (tuple[float, ...] | float | None, optional): The margins between the anchors of both objects in
            meters. Must have the same lengths as axes. If None, no margin is used. Defaults to None.
        grid_margins (tuple[int, ...] | int | None, optional): The margins between the anchors of both objects
            in Yee-grid voxels. Must have the same lengths as axes. If none, no margin is used. Defaults to None.

    Returns:
        PositionConstraint: Positional constraint between this object and the other
    """
    if isinstance(axes, int):
        axes = (axes,)
    if isinstance(own_positions, int | float):
        own_positions = (float(own_positions),)
    if isinstance(other_positions, int | float):
        other_positions = (float(other_positions),)
    if isinstance(margins, int | float):
        margins = (float(margins),)
    if isinstance(grid_margins, int):
        grid_margins = (grid_margins,)
    if margins is None:
        margins = tuple([0 for _ in axes])
    if grid_margins is None:
        grid_margins = tuple([0 for _ in axes])
    if (
        len(axes) != len(own_positions)
        or len(axes) != len(other_positions)
        or len(axes) != len(margins)
        or len(axes) != len(grid_margins)
    ):
        raise Exception("All inputs should have same lengths")
    constraint = PositionConstraint(
        axes=axes,
        other_object=other,
        object=self,
        other_object_positions=other_positions,
        object_positions=own_positions,
        margins=margins,
        grid_margins=grid_margins,
    )
    return constraint

def same_position_and_size(
    self,
    other: "SimulationObject",
    axes: tuple[int, ...] | int = (0, 1, 2),
) -> tuple[PositionConstraint, SizeConstraint]:
    """Creates both position and size constraints to make this object match another object's position and size.
    This is a convenience wrapper combining place_at_center() and same_size().

    Args:
        other (SimulationObject): Another object in the simulation scene
        axes (tuple[int, ...] | int, optional): Either a single integer or a tuple describing which axes to match.
            Defaults to all axes (0, 1, 2).

    Returns:
        tuple[PositionConstraint, SizeConstraint]: Position and size constraints for matching objects
    """
    size_constraint = self.same_size(
        other=other,
        axes=axes,
    )
    pos_constraint = self.place_at_center(
        other=other,
        axes=axes,
    )
    return pos_constraint, size_constraint

def same_size(
    self,
    other: "SimulationObject",
    axes: tuple[int, ...] | int = (0, 1, 2),
    offsets: tuple[float, ...] | float | None = None,
    grid_offsets: tuple[int, ...] | int | None = None,
) -> SizeConstraint:
    """Creates a SizeConstraint that makes this object the same size as another object along specified axes.
    This is a convenience wrapper around size_relative_to() with proportions set to 1.0.

    Args:
        other (SimulationObject): Another object in the simulation scene
        axes (tuple[int, ...] | int, optional): Either a single integer or a tuple describing which axes should
            have the same size. Defaults to all axes (0, 1, 2).
        offsets (tuple[float, ...] | float | None, optional): Additional size offsets in meters to apply.
            Must have same length as axes. If None, no offset is used. Defaults to None.
        grid_offsets (tuple[int, ...] | int | None, optional): Additional size offsets in Yee-grid voxels to
            apply. Must have same length as axes. If None, no offset is used. Defaults to None.

    Returns:
        SizeConstraint: Size constraint ensuring equal sizes between objects
    """
    if isinstance(axes, int):
        axes = (axes,)
    proportions = tuple([1 for _ in axes])
    constraint = self.size_relative_to(
        other=other,
        axes=axes,
        proportions=proportions,
        offsets=offsets,
        grid_offsets=grid_offsets,
    )
    return constraint

def set_grid_coordinates(
    self,
    axes: tuple[int, ...] | int,
    sides: tuple[Literal["+", "-"], ...] | Literal["+", "-"],
    coordinates: tuple[int, ...] | int,
) -> GridCoordinateConstraint:
    """Creates a GridCoordinateConstraint that forces specific sides of this object to align with
    given grid coordinates. Used for precise positioning in the discretized simulation space.

    Args:
        axes (tuple[int, ...] | int): Either a single integer or a tuple describing which axes to constrain
        sides (tuple[Literal["+", "-"], ...] | Literal["+", "-"]): Either a single string or a tuple of strings
            ('+' or '-') indicating which side of each axis to constrain. Must have same length as axes.
        coordinates (tuple[int, ...] | int): Either a single integer or a tuple of integers specifying the
            grid coordinates to align with. Must have same length as axes.

    Returns:
        GridCoordinateConstraint: Constraint forcing alignment with specific grid coordinates
    """
    if isinstance(axes, int):
        axes = (axes,)
    if isinstance(sides, str):
        sides = (sides,)
    if isinstance(coordinates, int):
        coordinates = (coordinates,)
    if len(axes) != len(sides) or len(axes) != len(coordinates):
        raise Exception("All inputs need to have the same lengths!")
    return GridCoordinateConstraint(
        object=self,
        axes=axes,
        sides=sides,
        coordinates=coordinates,
    )

def set_real_coordinates(
    self,
    axes: tuple[int, ...] | int,
    sides: tuple[Literal["+", "-"], ...] | Literal["+", "-"],
    coordinates: tuple[float, ...] | float,
) -> RealCoordinateConstraint:
    """Creates a RealCoordinateConstraint that forces specific sides of this object to align with
    given real-space coordinates. Used for precise positioning in physical units.

    Args:
        axes (tuple[int, ...] | int): Either a single integer or a tuple describing which axes to constrain
        sides (tuple[Literal["+", "-"], ...] | Literal["+", "-"]): Either a single string or a tuple of
            strings ('+' or '-') indicating which side of each axis to constrain. Must have same length as axes.
        coordinates (tuple[float, ...] | float): Either a single float or a tuple of floats specifying the
            real-space coordinates in meters to align with. Must have same length as axes.

    Returns:
        RealCoordinateConstraint: Constraint forcing alignment with specific real-space coordinates
    """
    if isinstance(axes, int):
        axes = (axes,)
    if isinstance(sides, str):
        sides = (sides,)
    if isinstance(coordinates, int | float):
        coordinates = (float(coordinates),)
    if len(axes) != len(sides) or len(axes) != len(coordinates):
        raise Exception("All inputs need to have the same lengths!")
    return RealCoordinateConstraint(
        object=self,
        axes=axes,
        sides=sides,
        coordinates=coordinates,
    )

def size_relative_to(
    self,
    other: "SimulationObject",
    axes: tuple[int, ...] | int,
    other_axes: tuple[int, ...] | int | None = None,
    proportions: tuple[float, ...] | float | None = None,
    offsets: tuple[float, ...] | float | None = None,
    grid_offsets: tuple[int, ...] | int | None = None,
) -> SizeConstraint:
    """Creates a SizeConstraint between two objects. The constraint defines the size of this object relative
    to another object, allowing for proportional scaling and offsets in specified axes.

    Args:
        other (SimulationObject): Another object in the simulation scene
        axes (tuple[int, ...] | int): Either a single integer or a tuple describing which axes of this object to
            constrain.
        other_axes (tuple[int, ...] | int | None, optional): Either a single integer or a tuple describing which
            axes of the other object to reference. If None, uses the same axes as specified in 'axes'. Defaults
            to None.
        proportions (tuple[float, ...] | float | None, optional): Scale factors to apply to the other object's
            dimensions. Must have same length as axes. If None, uses 1.0 (same size). Defaults to None.
        offsets (tuple[float, ...] | float | None, optional): Additional size offsets in meters to apply after
            scaling. Must have same length as axes. If None, no offset is used. Defaults to None.
        grid_offsets (tuple[int, ...] | int | None, optional): Additional size offsets in Yee-grid voxels to
            apply after scaling. Must have same length as axes. If None, no offset is used. Defaults to None.

    Returns:
        SizeConstraint: Size constraint between this object and the other
    """
    if isinstance(axes, int):
        axes = (axes,)
    if isinstance(other_axes, int):
        other_axes = (other_axes,)
    if isinstance(proportions, int | float):
        proportions = (float(proportions),)
    if isinstance(offsets, int | float):
        offsets = (offsets,)
    if isinstance(grid_offsets, int):
        grid_offsets = (grid_offsets,)
    if offsets is None:
        offsets = tuple([0 for _ in axes])
    if grid_offsets is None:
        grid_offsets = tuple([0 for _ in axes])
    if proportions is None:
        proportions = tuple([1.0 for _ in axes])
    if other_axes is None:
        other_axes = tuple([a for a in axes])
    if len(axes) != len(proportions) or len(axes) != len(offsets) or len(axes) != len(grid_offsets):
        raise Exception("All inputs should have same lengths")
    constraint = SizeConstraint(
        other_object=other,
        object=self,
        axes=axes,
        other_axes=other_axes,
        proportions=proportions,
        offsets=offsets,
        grid_offsets=grid_offsets,
    )
    return constraint