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_ridder(props, distance, lofted)[0]

def find_zero_point(
    self, shot_info: Shot, distance: Distance, lofted: bool = False
) -> tuple[Angular, TrajectoryData]:
    """Find a zero trajectory and return its solved angle and terminal point.

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

    Returns:
        The solved barrel elevation and the terminal RANGE point from the
        successful zero-finding iteration.

    Raises:
        SolverRuntimeError: If a zero-angle fast path did not integrate a
            trajectory and therefore has no trajectory point to return.
    """
    props = self._init_trajectory(shot_info)
    angle, point = self._find_zero_ridder(props, distance, lofted)
    if point is None:
        raise SolverRuntimeError("Zero-angle fast path did not evaluate a trajectory point")
    return angle, point

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 the damped Newton solver; if that fails then falls back on
    `_find_zero_ridder`.

    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._find_zero_newton(props, distance)[0]
    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_ridder(props, distance)[0]

def zero_point(self, shot_info: Shot, distance: Distance) -> tuple[Angular, TrajectoryData]:
    """Return the zero angle and the trajectory point used to determine it.

    This is the terminal RANGE point from the successful zero-finding
    iteration.  It performs no final re-integration after finding the
    angle, so it is useful to callers that need both the zero geometry and
    its ballistic state.

    Args:
        shot_info: The shot information.
        distance: Slant distance to the zero point.

    Returns:
        A pair of the lower-arc barrel elevation and the trajectory point
        from the successful zero-finding iteration.

    Raises:
        SolverRuntimeError: If a zero-angle fast path did not integrate a
            trajectory and therefore has no trajectory point to return.
    """
    props = self._init_trajectory(shot_info)
    try:
        # Bypass optional-engine overrides while this API is limited to
        # the pure-Python solver path.
        angle, point = BaseIntegrationEngine._find_zero_newton(self, props, distance)
    except ZeroFindingError as error:
        logger.warning(f"Failed to find zero point using base iterative method: {error}")
        angle, point = BaseIntegrationEngine._find_zero_ridder(self, props, distance, False)
    if point is None:
        raise SolverRuntimeError("Zero-angle fast path did not evaluate a trajectory point")
    return angle, point

def integrate(
    self,
    shot_info: Shot,
    max_range: Distance,
    dist_step: Distance | None = None,
    time_step: float = 0.0,
    filter_flags: 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

@override
def find_zero_angle(self, shot_info: Shot, distance: Distance, lofted: bool = False) -> Angular:
    """Find a zero angle with SciPy's ``brentq`` root solver."""
    props = self._init_trajectory(shot_info)
    return self._find_zero_brentq(props, distance, lofted)[0]

@override
def find_zero_point(
    self, shot_info: Shot, distance: Distance, lofted: bool = False
) -> tuple[Angular, TrajectoryData]:
    """Find a zero point with SciPy's ``brentq`` root solver."""
    props = self._init_trajectory(shot_info)
    angle, point = self._find_zero_brentq(props, distance, lofted)
    if point is None:
        raise SolverRuntimeError("Zero-angle fast path did not evaluate a trajectory point")
    return angle, point

@override
def zero_angle(self, shot_info: Shot, distance: Distance) -> Angular:
    """Find the lower zero angle, falling back from Newton to ``brentq``."""
    props = self._init_trajectory(shot_info)
    try:
        return self._find_zero_newton(props, distance)[0]
    except ZeroFindingError as error:
        logger.warning(f"Failed to find zero angle using Newton method: {error}")
        return self._find_zero_brentq(props, distance)[0]

@override
def zero_point(self, shot_info: Shot, distance: Distance) -> tuple[Angular, TrajectoryData]:
    """Return SciPy's zero solution and its already-evaluated terminal point.

    Unlike the base implementation, this directly uses the ``root_scalar``
    solver implemented by :meth:`_find_zero_brentq`.
    """
    props = self._init_trajectory(shot_info)
    angle, point = self._find_zero_brentq(props, distance)
    if point is None:
        raise SolverRuntimeError("Zero-angle fast path did not evaluate a trajectory point")
    return angle, point

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_zero_point(
    self, shot_info: Shot, distance: Distance, lofted: bool = False
) -> tuple[Angular, TrajectoryData]:
    """Find a zero trajectory and return its solved angle and terminal point.

    The returned point is the terminal ``RANGE`` point evaluated by the
    successful zero-finding iteration. No final trajectory integration is
    performed after the angle is found.

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

    Returns:
        The solved barrel elevation and the terminal RANGE point from the
        successful zero-finding iteration.

    Raises:
        SolverRuntimeError: If a zero-angle fast path did not integrate a
            trajectory and therefore has no trajectory point to return.
    """

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 zero_point(self, shot_info: Shot, distance: Distance) -> tuple[Angular, TrajectoryData]:
    """Return the zero angle and the trajectory point used to determine it.

    This is the terminal ``RANGE`` point from the successful zero-finding
    iteration. It performs no final re-integration after finding the
    angle, so callers receive both the zero geometry and its ballistic
    state from one solve.

    Args:
        shot_info: The shot information.
        distance: Slant distance to the zero point.

    Returns:
        A pair of the lower-arc barrel elevation and the trajectory point
        from the successful zero-finding iteration.

    Raises:
        SolverRuntimeError: If a zero-angle fast path did not integrate a
            trajectory and therefore has no trajectory point to return.
    """

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 (Distance | None):
            Distance step for recording RANGE TrajectoryData rows.
        time_step (float, optional):
            Time step for recording trajectory data. Defaults to 0.0.
        filter_flags (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
    """

def get_step_stats(self) -> tuple[int, int]:
    """Returns (accepted, rejected) step counts from the most recent integration call."""

def get_step_stats(self) -> tuple[int, int]:
    """Returns (accepted, rejected) step counts from the most recent integration call."""

def get_step_stats(self) -> tuple[int, int]:
    """Returns (accepted, rejected) step counts from the most recent integration call."""