Interface

def barrel_elevation_for_target(self, shot: Shot, target_distance: Union[float, Distance]) -> Angular:
    """Calculate barrel elevation to hit target at zero_distance.

    Args:
        shot: Shot instance we want to zero.
        target_distance: Look-distance to "zero," which is point we want to hit.
            This is the distance that a rangefinder would return with no ballistic adjustment.

    Note:
        Some rangefinders offer an adjusted distance based on inclinometer measurement.
        However, without a complete ballistic model these can only approximate the effects
        on ballistic trajectory of shooting uphill or downhill. Therefore:
        For maximum accuracy, use the raw sight distance and look_angle as inputs here.
    """
    target_distance = PreferredUnits.distance(target_distance)
    total_elevation = self._engine_instance.zero_angle(shot, target_distance)
    return Angular.Radian(
        (total_elevation >> Angular.Radian) - (shot.look_angle >> Angular.Radian)
    )

def set_weapon_zero(self, shot: Shot, zero_distance: Union[float, Distance]) -> Angular:
    """Set shot.weapon.zero_elevation so that it hits a target at zero_distance.

    Args:
        shot: Shot instance to zero.
        zero_distance: Look-distance to "zero," which is point we want to hit.
    """
    shot.weapon.zero_elevation = self.barrel_elevation_for_target(shot, zero_distance)
    return shot.weapon.zero_elevation

def fire(self, shot: Shot,
         trajectory_range: Union[float, Distance],
         trajectory_step: Optional[Union[float, Distance]] = None, *,
         extra_data: bool = False,
         dense_output: bool = False,
         time_step: float = 0.0,
         flags: Union[TrajFlag, int] = TrajFlag.NONE,
         raise_range_error: bool = True) -> HitResult:
    """Calculate the trajectory for the given shot parameters.

    Args:
        shot: Shot parameters, including position and barrel angle.
        trajectory_range: Distance at which to stop computing the trajectory.
        trajectory_step: Distance between recorded trajectory points. Defaults to `trajectory_range`.
        extra_data: [DEPRECATED] Requests flags=TrajFlags.ALL and trajectory_step=PreferredUnits.distance(1).
        dense_output: HitResult stores all calculation steps so it can interpolate any point.
        time_step: Maximum time between recorded points. If > 0, points are recorded at least this frequently.
                   Defaults to 0.0.
        flags: Flags for specific points of interest. Defaults to TrajFlag.NONE.
        raise_range_error: If True, raises RangeError if returned by integration.

    Returns:
        HitResult: Object containing computed trajectory.
    """
    trajectory_range = PreferredUnits.distance(trajectory_range)
    dist_step = trajectory_range
    filter_flags = flags
    if trajectory_step:
        dist_step = PreferredUnits.distance(trajectory_step)
        filter_flags |= TrajFlag.RANGE
        if dist_step.raw_value > trajectory_range.raw_value:
            dist_step = trajectory_range

    if extra_data:
        warnings.warn("extra_data is deprecated and will be removed in future versions. "
            "Explicitly specify desired TrajectoryData frequency and flags.",
            DeprecationWarning
        )
        dist_step = PreferredUnits.distance(1.0)  # << For compatibility with v2.1
        filter_flags = TrajFlag.ALL

    result = self._engine_instance.integrate(shot, trajectory_range, dist_step, time_step,
                                             filter_flags, dense_output=dense_output)
    if result.error and raise_range_error:
        raise result.error
    return result

@staticmethod
def iter_engines() -> Generator[EntryPoint, None, None]:
    """Iterate all available engines in the entry points."""
    yield from _EngineLoader.iter_engines()