Protocol

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: Any,
) -> HitResult:
    """Perform ballistic trajectory calculation from shot parameters to maximum range.

    This method integrates the projectile's equations of motion to generate
    a complete trajectory from muzzle to the specified maximum range, accounting
    for gravitational acceleration, atmospheric drag, and environmental conditions.

    Args:
        shot_info: Complete shot configuration containing projectile data,
                  environmental conditions, sight configuration, and firing
                  parameters. Must include muzzle velocity, ballistic coefficient,
                  atmospheric conditions, and sight height information.
        max_range: Maximum distance for trajectory calculation. The integration
                  continues until the projectile reaches this range or impacts the ground.
        dist_step: Distance interval between trajectory data points. If None,
                  engine uses default step size for optimal accuracy/performance balance.
        time_step: Time interval for integration steps. Zero means engine
                  determines optimal step size automatically.
        filter_flags: Trajectory flags to control which data points are included
                     in the output. Use TrajFlag values to filter specific conditions.
        dense_output: If True, return trajectory data at every integration step.
                     If False, return data only at specified distance intervals.
        **kwargs: Additional engine-specific parameters for specialized calculations.

    Returns:
        HitResult: Complete trajectory calculation parameters and results.

    Raises:
        ValueError: If shot_info contains invalid or inconsistent parameters.
        RuntimeError: If the numerical integration fails to converge.
        OutOfRangeError: If the requested max_range exceeds computational limits.

    Mathematical Background:
        The integration solves the vector differential equation for projectile
        motion under the influence of gravity and atmospheric drag:
        ```
        dV/dt = D * |V| * (V - W) - g

        Where:
        - V = (v_x, v_y, v_z) is velocity relative to the ground
        - W = (w_x, w_y, w_z) is wind velocity vector relative to the ground
        - D = drag factor, which is a function of velocity, atmosphere, and
                projectile characteristics that include shape and mass
        - g is gravitational acceleration
        ```

    Typical implementation steps:
        1. Initialize state vectors from shot_info parameters
        2. Set up integration bounds and step size parameters
        3. Begin numerical integration loop using chosen method
        4. At each step, calculate drag forces from atmospheric conditions
        5. Update position and velocity using integration formulae
        6. Check termination conditions (range limit, ground impact)
        7. Store trajectory points at specified intervals
        8. Return complete trajectory data structure
    """
    ...

def zero_angle(self, shot_info: Shot, distance: Distance) -> Angular:
    """Calculate launch angle required to hit target at specified distance.

    Args:
        shot_info: Complete shot configuration containing projectile data,
                  environmental conditions, sight configuration, and target
                  information. Must include muzzle velocity, ballistic coefficient,
                  atmospheric conditions, sight height, and target height.
        distance: Horizontal distance to target. Must be within the effective
                 range of the projectile under the given conditions.

    Returns:
        Angular: Launch angle required to hit the target.

    Raises:
        ValueError: If shot_info contains invalid parameters or distance
                   is negative or unreasonably large.
        ZeroFindingError: If the iterative algorithm fails to converge.
        OutOfRangeError: If the target distance exceeds maximum effective range.

    Note:
        This method returns the lower of the two ballistic solutions hit a target point.
        To get the higher ("lofted") solution we have been adding a .find_zero_angle()
        method that offers a `lofted: bool` parameter to select between the two.

    Mathematical Background:
        The method solves the equation `f(θ) = 0` where:
        ```
        f(θ) = y(target_distance, θ) - target_height

        Where y(x, θ) is the trajectory height function at distance x for
        launch angle θ. This requires iterative solution since the trajectory
        equation cannot be solved analytically for arbitrary drag functions.
        ```

    Typical implementation approach:
        1. Establish reasonable bounds for elevation angle search
        2. Define target function: trajectory_height(distance) - target_height
        3. Use root-finding algorithm (bisection, Newton, etc.)
        4. For each iteration, calculate trajectory to target distance
        5. Evaluate height difference at target distance
        6. Adjust angle estimate based on convergence strategy
        7. Continue until convergence tolerance is met
        8. Return final angle estimate
    """
    ...

def zero_point(self, shot_info: Shot, distance: Distance) -> tuple[Angular, TrajectoryData]:
    """Calculate the lower zero and return its angle and terminal point.

    The returned point is the terminal ``RANGE`` point evaluated by the
    successful zero-finding iteration; implementations must not perform a
    separate final trajectory integration to obtain it.

    Args:
        shot_info: Complete shot configuration used for the zero solve.
        distance: Slant distance from the sight to the requested zero point.

    Returns:
        A pair of the lower-arc barrel elevation and the corresponding
        terminal trajectory point.

    Raises:
        SolverRuntimeError: If a zero-angle fast path did not evaluate a
            trajectory point.
    """
    ...

def find_zero_angle(self, shot_info: Shot, distance: Distance, lofted: bool = False) -> Angular:
    """Calculate the lower or lofted zero angle at a specific distance.

    Args:
        shot_info: Complete shot configuration used for the zero solve.
        distance: Slant distance from the sight to the requested zero point.
        lofted: If True, select the higher trajectory that reaches the
            zero point; otherwise select the lower trajectory.

    Returns:
        Barrel elevation needed to hit the zero point.
    """
    ...

def find_zero_point(
    self, shot_info: Shot, distance: Distance, lofted: bool = False
) -> tuple[Angular, TrajectoryData]:
    """Calculate the lower or lofted zero and return its angle and terminal point.

    The returned point is the terminal ``RANGE`` point evaluated by the
    successful zero-finding iteration; implementations must not perform a
    separate final trajectory integration to obtain it.

    Args:
        shot_info: Complete shot configuration used for the zero solve.
        distance: Slant distance from the sight to the requested zero point.
        lofted: If True, select the higher trajectory that reaches the
            zero point; otherwise select the lower trajectory.

    Returns:
        A pair of the selected barrel elevation and the corresponding
        terminal trajectory point.

    Raises:
        SolverRuntimeError: If a zero-angle fast path did not evaluate a
            trajectory point.
    """
    ...

def __call__(self, config: ConfigT | None) -> EngineProtocol:
    """Make any Engine constructor or factory to match this signature"""
    ...