Engines

def get_calc_step(self) -> float:
    """Get step size for integration."""
    return self._config.cStepMultiplier

def find_max_range(
    self, shot_info: Shot, angle_bracket_deg: Tuple[float, float] = (0, 90)
) -> Tuple[Distance, Angular]:
    """Find the maximum range along shot_info.look_angle, and the launch angle to reach it.

    Args:
        shot_info: The shot information: gun, ammo, environment, look_angle.
        angle_bracket_deg: The angle bracket in degrees to search for max range. Defaults to (0, 90).

    Returns:
        The maximum slant-range and the launch angle to reach it.

    Raises:
        ValueError: If the angle bracket excludes the look_angle.
    """
    """
    TODO: Make sure user hasn't restricted angle bracket to exclude the look_angle.
        ... and check for weird situations, like backward-bending trajectories,
        where the max range occurs with launch angle less than the look angle.
    """
    props = self._init_trajectory(shot_info)
    return self._find_max_range(props, angle_bracket_deg)

def find_apex(self, shot_info: Shot) -> TrajectoryData:
    """Find the apex of the trajectory.

    Apex is defined as the point where the vertical component of velocity goes from positive to negative.

    Args:
        shot_info: The shot information.

    Returns:
        TrajectoryData: The trajectory data at the apex of the trajectory.

    Raises:
        SolverRuntimeError: If no apex is found in the trajectory data.
        ValueError: If barrel elevation is not > 0.
    """
    props = self._init_trajectory(shot_info)
    return self._find_apex(props)

def find_zero_angle(self, shot_info: Shot, distance: Distance, lofted: bool = False) -> Angular:
    """Find the barrel elevation needed to hit sight line at a specific distance.

    Args:
        shot_info: The shot information.
        distance: Slant distance to the target.
        lofted: If True, find the higher angle that hits the zero point.

    Returns:
        Barrel elevation needed to hit the zero point.
    """
    props = self._init_trajectory(shot_info)
    return self._find_zero_angle(props, distance, lofted)

def zero_angle(self, shot_info: Shot, distance: Distance) -> Angular:
    """Find the barrel elevation needed to hit sight line at a specific distance.

    First tries iterative approach; if that fails then falls back on `_find_zero_angle`.

    Args:
        shot_info: The shot information.
        distance: The distance to the target.

    Returns:
        Barrel elevation to hit height zero at zero distance along sight line
    """
    props = self._init_trajectory(shot_info)
    try:
        return self._zero_angle(props, distance)
    except ZeroFindingError as e:
        logger.warning(f"Failed to find zero angle using base iterative method: {e}")
        # Fallback to guaranteed method
        return self._find_zero_angle(props, distance)

def integrate(
    self,
    shot_info: Shot,
    max_range: Distance,
    dist_step: Optional[Distance] = None,
    time_step: float = 0.0,
    filter_flags: Union[TrajFlag, int] = TrajFlag.NONE,
    dense_output: bool = False,
    **kwargs,
) -> HitResult:
    """Compute the trajectory for the given shot.

    Args:
        shot_info: The shot information.
        max_range: Maximum range of the trajectory (if float then treated as feet).
        dist_step: Distance step for recording RANGE TrajectoryData rows.
        time_step: Time step for recording trajectory data. Defaults to 0.0.
        filter_flags: Flags to filter trajectory data. Defaults to TrajFlag.RANGE.
        dense_output: If True, HitResult will save BaseTrajData for interpolating TrajectoryData.

    Returns:
        HitResult object for describing the trajectory.
    """
    props = self._init_trajectory(shot_info)
    props.filter_flags = filter_flags
    range_limit_ft = max_range >> Distance.Foot
    if dist_step is None:
        range_step_ft = range_limit_ft
    else:
        range_step_ft = dist_step >> Distance.Foot
    return self._integrate(props, range_limit_ft, range_step_ft, time_step, filter_flags, dense_output, **kwargs)

@override
def get_calc_step(self) -> float:
    """Get the calculation step size for RK4 integration.

    Returns:
        Time-step size (in seconds) for integration calculations.

    Mathematical Context:
        The step size directly affects the accuracy and computational cost:
        - Smaller steps: Higher accuracy, more computation
        - Larger steps: Lower accuracy, faster computation
        - RK4's O(h⁵) error means accuracy improves rapidly with smaller h

    Examples:
        >>> config = BaseEngineConfigDict(cStepMultiplier=0.5)
        >>> engine = RK4IntegrationEngine(config)
        >>> engine.get_calc_step()
        0.00125

    Note:
        For RK4, the relationship between step size and accuracy is:
        - Halving the step size reduces error by ~32× (2⁵)
        - Default step size is sufficient to pass unit tests.
    """
    return super().get_calc_step() * self.DEFAULT_TIME_STEP

@override
def get_calc_step(self) -> float:
    """Get the base calculation step size for Euler integration.

    Calculates the effective step size by combining the base engine
    step multiplier with the Euler-specific DEFAULT_STEP constant.
    The step size directly affects accuracy and performance trade-offs.
    This is a distance-like quantity that is subsequently scaled by velocity
    to produce a time-like integration step.

    Returns:
        Base step size for integration calculations.

    Note:
        The step size is calculated as: `cStepMultiplier * DEFAULT_STEP`.
        Smaller step sizes increase accuracy but require more computation.
        The DEFAULT_STEP is sufficient to pass all unit tests.
    """
    return super().get_calc_step() * self.DEFAULT_TIME_STEP

def time_step(self, base_step: float, velocity: float) -> float:
    """Calculate adaptive time step based on current projectile velocity.

    Implements adaptive time stepping where the time step is inversely
    related to projectile velocity. This helps maintain numerical stability
    and accuracy as the projectile slows down or speeds up.

    Args:
        base_step: Base step size from the integration engine.
        velocity: Current projectile velocity in fps.

    Returns:
        Adaptive time step for the current integration step.

    Formula:
        time_step = base_step / max(1.0, velocity)

    Examples:
        >>> config = BaseEngineConfigDict(cStepMultiplier=0.5)
        >>> engine = EulerIntegrationEngine(config)
        >>> engine.time_step(0.5, 2000.0)
        0.00025
        >>> engine.time_step(0.5, 100.0)
        0.005

    Note:
        The max(1.0, velocity) ensures that the time step never becomes
        excessively large, maintaining numerical stability even at very
        low velocities.
    """
    return base_step / max(1.0, velocity)

@override
def get_calc_step(self) -> float:
    """Get the calculation step size for Velocity Verlet integration.

    Combines the base engine step multiplier with the Verlet-specific
    DEFAULT_TIME_STEP to determine the effective integration step size.

    Returns:
        Effective step size for Velocity Verlet integration.

    Formula:
        step_size = base_step_multiplier × DEFAULT_TIME_STEP

    Note:
        The small DEFAULT_TIME_STEP value is chosen to ensure
        that this engine can pass all unit tests, despite most of them
        being highly dissipative rather than conservative of energy.
    """
    return super().get_calc_step() * self.DEFAULT_TIME_STEP

def find_max_range(
    self, shot_info: Shot, angle_bracket_deg: Tuple[float, float] = (0, 90)
) -> Tuple[Distance, Angular]:
    """
    Finds the maximum range along shot_info.look_angle,
    and the launch angle to reach it.

    Args:
        shot_info (Shot): The shot information.
        angle_bracket_deg (Tuple[float, float], optional):
            The angle bracket in degrees to search for max range. Defaults to (0, 90).

    Returns:
        Tuple[Distance, Angular]: The maximum slant range and the launch angle to reach it.
    """
    ...

def find_zero_angle(self, shot_info: Shot, distance: Distance, lofted: bool = False) -> Angular:
    """
    Finds the barrel elevation needed to hit sight line at a specific distance,
    using unimodal root-finding that is guaranteed to succeed if a solution exists.

    Args:
        shot_info (Shot): The shot information.
        distance (Distance): The distance to the target.
        lofted (bool): Whether the shot is lofted.

    Returns:
        Angular: The required barrel elevation angle.
    """
    ...

def find_apex(self, shot_info: Shot) -> TrajectoryData:
    """
    Finds the apex of the trajectory, where apex is defined as the point
    where the vertical component of velocity goes from positive to negative.

    Args:
        shot_info (Shot): The shot information.

    Returns:
        TrajectoryData: The trajectory data at the apex.
    """
    ...

def zero_angle(self, shot_info: Shot, distance: Distance) -> Angular:
    """
    Finds the barrel elevation needed to hit sight line at a specific distance.
    First tries iterative approach; if that fails falls back on _find_zero_angle.

    Args:
        shot_info (Shot): The shot information.
        distance (Distance): The distance to the target.

    Returns:
        Angular: Barrel elevation to hit height zero at zero distance along sight line
    """
    ...

def integrate(
    self,
    shot_info: Shot,
    max_range: Distance,
    dist_step: Distance | None = None,
    time_step: float = 0.0,
    filter_flags: TrajFlag | int = 0,
    dense_output: bool = False,
    **kwargs: Any,
) -> HitResult:
    """
    Integrates the trajectory for the given shot.

    Args:
        shot_info (Shot): The shot information.
        max_range (Distance):
            Maximum range of the trajectory (if float then treated as feet).
        dist_step (Optional[Distance]):
            Distance step for recording RANGE TrajectoryData rows.
        time_step (float, optional):
            Time step for recording trajectory data. Defaults to 0.0.
        filter_flags (Union[TrajFlag, int], optional):
            Flags to filter trajectory data. Defaults to TrajFlag.RANGE.
        dense_output (bool, optional):
            If True, HitResult will save BaseTrajData for interpolating TrajectoryData.

    Returns:
        HitResult: Object for describing the trajectory.
    """
    ...

def integrate_raw_at(
    self, shot_info: Shot, key_attribute: str, target_value: float
) -> tuple[CythonizedBaseTrajData, TrajectoryData]:
    """
    Integrates the trajectory until a specified attribute reaches a target value
    and returns the interpolated data point.

    This method initializes the trajectory using the provided shot information,
    performs integration using the underlying C++ engine's 'integrate_at' function,
    and handles the conversion of C++ results back to Python objects.

    Args:
        shot_info (object): Information required to initialize the trajectory
            (e.g., muzzle velocity, drag model).
        key_attribute (str): The name of the attribute to track, such as
            'time', 'mach', or a vector component like 'position.z'.
        target_value (float): The value the 'key_attribute' must reach for
            the integration to stop and interpolation to occur.

    Returns:
        tuple[CythonizedBaseTrajData, TrajectoryData]:
            A tuple containing:
            - CythonizedBaseTrajData: The interpolated raw data point.
            - TrajectoryData: The fully processed trajectory data point.

    Raises:
        InterceptionError: If the underlying C++ integration fails to find
            the target point (e.g., due to insufficient range or data issues).
        SolverRuntimeError: If some other internal error occured
    """
    ...