Interface

def __enter__(self) -> Self:
    """Enter the runtime context for this Calculator.

    Returns:
        Self: The Calculator instance.

    Example:
        >>> with Calculator(config, RK4IntegrationEngine) as calc:
        ...     result = calc.fire(shot, Distance.Meter(1000))
    """
    return self

def __exit__(
    self,
    exc_type: type[BaseException] | None,
    exc_val: BaseException | None,
    exc_tb: TracebackType | None,
) -> None:
    """Exit the runtime context.

    This is a no-op as Calculator is stateless and thread-safe
    by design — each method call creates an isolated engine instance.

    Args:
        exc_type: Exception type if an exception was raised, None otherwise.
        exc_val: Exception instance if an exception was raised, None otherwise.
        exc_tb: Traceback if an exception was raised, None otherwise.
    """

def __getattr__(self, item: str) -> Any:
    """Delegate attribute access to the underlying engine instance.

    This method is called when an attribute is requested on the `Calculator`
    instance that is not found through normal attribute lookup (i.e., it's
    not a direct attribute of `Calculator` or its class). It then attempts
    to retrieve the attribute from the `_engine_instance`.

    Args:
        item: The name of the attribute to retrieve.

    Returns:
        Any: The value of the attribute from `_engine_instance`.

    Raises:
        AttributeError: If the attribute is not found on either the
            `Calculator` object or its `_engine_instance`.

    Examples:
        >>> calc = Calculator(engine=DEFAULT_ENTRY)
        >>> calc_step = calc.get_calc_step()
        >>> print(calc_step)
        0.0025
        >>> try:
        ...     calc.unknown_method()
        ... except AttributeError as e:
        ...     print(e)
        'Calculator' object or its underlying engine 'RK4IntegrationEngine' has no attribute 'unknown_method'
    """
    engine_instance = self._engine_instance
    if hasattr(engine_instance, item):
        return getattr(engine_instance, item)
    raise AttributeError(
        f"'{self.__class__.__name__}' object or its underlying engine "
        f"'{engine_instance.__class__.__name__}' has no attribute '{item}'"
    )

def __getstate__(self):
    """
    Called by pickle for serialization.
    We only serialize the public fields required for reconstruction.
    We explicitly exclude the calculated fields like _engine_class
    to ensure proper re-initialization in the new process.
    """
    return {"config": self.config, "engine": self.engine}

def __setstate__(self, state):
    """
    Called by pickle for deserialization.
    We manually set the fields and call __post_init__ to reload the engine class.
    """
    # Set the serialized fields
    self.config = state["config"]
    self.engine = state["engine"]
    # Manually run __post_init__ to load the _engine_class
    self._engine_factory = _EngineLoader.load(self.engine)

def barrel_elevation_for_target(self, shot: Shot, target_distance: 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 aim(self, shot: Shot, target_distance: float | Distance) -> tuple[Angular, Angular, TrajectoryData]:
    """Calculate a target's zero solution and retain its trajectory point.

    Args:
        shot: Shot instance to solve.
        target_distance: Look-distance to the target.
            This is the distance that a rangefinder would return with no ballistic adjustment.

    Returns:
        The vertical hold relative to the weapon's zero, the windage
        angle, and the trajectory point evaluated by the successful
        zero-finding iteration.  The windage angle uses the sign
        convention of :attr:`TrajectoryData.windage_angle`.

    Raises:
        NotImplementedError: If the selected engine has no ``zero_point`` API.
    """
    target_distance = PreferredUnits.distance(target_distance)
    total_elevation, point = self._engine_instance.zero_point(shot, target_distance)
    target_zero_elevation = Angular.Radian(
        (total_elevation >> Angular.Radian) - (shot.look_angle >> Angular.Radian)
    )
    vertical_hold = Angular.Radian(
        (target_zero_elevation >> Angular.Radian) - (shot.weapon.zero_elevation >> Angular.Radian)
    )
    return vertical_hold, point.windage_angle, point

def aiming_solution_for_target(
    self, shot: Shot, target_distance: float | Distance
) -> tuple[Angular, Angular, TrajectoryData]:
    """Return :meth:`aim`'s solution for callers using the descriptive API name.

    Args:
        shot: Shot instance to solve.
        target_distance: Look-distance to the target.

    Returns:
        The vertical hold relative to the weapon's zero, windage angle,
        and terminal trajectory point.
    """
    return self.aim(shot, target_distance)

def set_weapon_zero(self, shot: Shot, zero_distance: 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: float | Distance,
    trajectory_step: float | Distance | None = None,
    *,
    extra_data: bool = False,
    dense_output: bool = False,
    time_step: float = 0.0,
    flags: 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()

@classmethod
def engine_id(cls, ep: EntryPoint) -> str:
    """Public identifier of an entry point: ``<engine>+<method>`` for new-style, plain name for legacy."""
    if ep.group.startswith(cls._engines_group_prefix):
        return f"{ep.group.removeprefix(cls._engines_group_prefix)}+{ep.name}"
    return ep.name

@classmethod
def iter_engines(cls) -> Generator[EntryPoint, None, None]:
    """Iterate over all available engines (new-style first, legacy deduplicated by target)."""
    seen: set[str] = set()
    for ep in cls._get_engine_entries():
        seen.add(ep.value)
        yield ep
    for ep in sorted(cls._get_entries_by_group(), key=lambda e: e.name):
        if ep.name.endswith(cls._entry_point_suffix) and ep.value not in seen:
            seen.add(ep.value)
            yield ep