Deprecating extra_data flag.

* TrajectoryDataFilter always records initial TrajectoryData row.
* Engines always return at least 2 points if they can calculate even one step.

Author: dbookstaber

py_ballisticcalc.exts/py_ballisticcalc_exts/base_engine.pyx

@@ -100,7 +100,7 @@ cdef BaseTrajData TrajDataFilter_t_should_record(TrajDataFilter_t * tdf, const V
         _check_mach_crossing(tdf, mag(velocity_ptr), mach)
     if tdf.filter & TrajFlag_t.APEX:
         _check_apex(tdf, velocity_ptr)
-    if (tdf.current_flag & tdf.filter) != 0 and data is None:
+    if ((tdf.current_flag & tdf.filter) != 0 and data is None) or time==0:
         data = BaseTrajData(time=time, position=position_ptr[0],
                             velocity=velocity_ptr[0], mach=mach)
     tdf.previous_time = time

py_ballisticcalc.exts/py_ballisticcalc_exts/euler_engine.pyx

@@ -94,7 +94,6 @@ cdef class CythonizedEulerIntegrationEngine(CythonizedBaseIntegrationEngine):
         velocity_vector = mulS(&_tv, velocity)
         # endregion
 
-        min_step = fmin(calc_step, range_step_ft)
         # With non-zero look_angle, rounding can suggest multiple adjacent zero-crossings
         data_filter = TrajDataFilter_t_create(filter_flags=filter_flags, range_step=range_step_ft,
                                                  initial_position_ptr=&range_vector,
@@ -107,7 +106,7 @@ cdef class CythonizedEulerIntegrationEngine(CythonizedBaseIntegrationEngine):
         termination_reason = None
         last_recorded_range = 0.0
 
-        while (range_vector.x <= range_limit_ft + min_step) or (
+        while (range_vector.x <= range_limit_ft) or (
                 last_recorded_range <= range_limit_ft - 1e-6):
             self.integration_step_count += 1
 
@@ -169,9 +168,9 @@ cdef class CythonizedEulerIntegrationEngine(CythonizedBaseIntegrationEngine):
                 data.time, &data.position, &data.velocity, data.mach,
                 &self._shot_s, density_ratio, drag, data_filter.current_flag
             ))
-        # Ensure that we have at least two data points in trajectory, or 1 if filter_flags==NONE
+        # Ensure that we have at least two data points in trajectory
         # ... as well as last point if we had an incomplete trajectory
-        if (filter_flags and ((len(ranges) < 2) or termination_reason)) or len(ranges) == 0:
+        if (filter_flags and ((len(ranges) < 2) or termination_reason)) or len(ranges) == 1:
             if len(ranges) > 0 and ranges[-1].time == time:  # But don't duplicate the last point.
                 pass
             else:

py_ballisticcalc.exts/py_ballisticcalc_exts/rk4_engine.pyx

@@ -98,7 +98,6 @@ cdef class CythonizedRK4IntegrationEngine(CythonizedBaseIntegrationEngine):
         velocity_vector = mulS(&_dir_vector, velocity)
         # endregion
 
-        min_step = fmin(calc_step, range_step_ft)
         # With non-zero look_angle, rounding can suggest multiple adjacent zero-crossings
         data_filter = TrajDataFilter_t_create(filter_flags=filter_flags, range_step=range_step_ft,
                                                 initial_position_ptr=&range_vector,
@@ -111,7 +110,7 @@ cdef class CythonizedRK4IntegrationEngine(CythonizedBaseIntegrationEngine):
         termination_reason = None
         last_recorded_range = 0.0
 
-        while (range_vector.x <= range_limit_ft + min_step) or (
+        while (range_vector.x <= range_limit_ft) or (
                 last_recorded_range <= range_limit_ft - 1e-6):
             self.integration_step_count += 1
 
@@ -241,9 +240,9 @@ cdef class CythonizedRK4IntegrationEngine(CythonizedBaseIntegrationEngine):
                 data.time, &data.position, &data.velocity, data.mach,
                 &self._shot_s, density_ratio, drag, data_filter.current_flag
             ))
-        # Ensure that we have at least two data points in trajectory, or 1 if filter_flags==NONE
+        # Ensure that we have at least two data points in trajectory,
         # ... as well as last point if we had an incomplete trajectory
-        if (filter_flags and ((len(ranges) < 2) or termination_reason)) or len(ranges) == 0:
+        if (filter_flags and ((len(ranges) < 2) or termination_reason)) or len(ranges) == 1:
             if len(ranges) > 0 and ranges[-1].time == time:  # But don't duplicate the last point.
                 pass
             else:

py_ballisticcalc/engines/base_engine.py

@@ -147,7 +147,7 @@ def should_record(self, position: Vector, velocity: Vector, mach: float,
             self.check_mach_crossing(velocity.magnitude(), mach)
         if self.filter & TrajFlag.APEX:
             self.check_apex(velocity)
-        if bool(self.current_flag & self.filter) and data is None:
+        if (bool(self.current_flag & self.filter) and data is None) or time==0.0:
             data = BaseTrajData(time=time, position=position,
                                 velocity=velocity, mach=mach)
         self.previous_time = time

py_ballisticcalc/engines/euler.py

@@ -85,9 +85,6 @@ def _integrate(self, props: ShotProps, range_limit_ft: float, range_step_ft: flo
         ).mul_by_const(velocity)  # type: ignore
         # endregion
 
-        # Ensure one iteration when record step is smaller than calc_step
-        min_step = min(props.calc_step, range_step_ft)
-
         data_filter = _TrajectoryDataFilter(filter_flags=filter_flags, range_step=range_step_ft,
                                             initial_position=range_vector, initial_velocity=velocity_vector,
                                             barrel_angle_rad=props.barrel_elevation_rad,
@@ -99,7 +96,7 @@ def _integrate(self, props: ShotProps, range_limit_ft: float, range_step_ft: flo
         termination_reason = None
         last_recorded_range = 0.0
         start_integration_step_count = self.integration_step_count
-        while (range_vector.x <= range_limit_ft + min_step) or (
+        while (range_vector.x <= range_limit_ft) or (
                 last_recorded_range <= range_limit_ft - 1e-6):
             self.integration_step_count += 1
 
@@ -152,9 +149,9 @@ def _integrate(self, props: ShotProps, range_limit_ft: float, range_step_ft: flo
             ranges.append(make_trajectory_row(
                 props, data.time, data.position, data.velocity, data.mach, data_filter.current_flag)
             )
-        # Ensure that we have at least two data points in trajectory, or 1 if filter_flags==NONE
+        # Ensure that we have at least two data points in trajectory,
         # ... as well as last point if we had an incomplete trajectory
-        if (filter_flags and ((len(ranges) < 2) or termination_reason)) or len(ranges) == 0:
+        if (filter_flags and ((len(ranges) < 2) or termination_reason)) or len(ranges) == 1:
             if len(ranges) > 0 and ranges[-1].time == time:  # But don't duplicate the last point.
                 pass
             else:

py_ballisticcalc/engines/rk4.py

@@ -78,8 +78,6 @@ def _integrate(self, props: ShotProps, range_limit_ft: float, range_step_ft: flo
         ).mul_by_const(velocity)  # type: ignore
         # endregion
 
-        min_step = min(props.calc_step, range_step_ft)
-
         data_filter = _TrajectoryDataFilter(filter_flags=filter_flags, range_step=range_step_ft,
                                             initial_position=range_vector, initial_velocity=velocity_vector,
                                             barrel_angle_rad=props.barrel_elevation_rad,
@@ -92,7 +90,7 @@ def _integrate(self, props: ShotProps, range_limit_ft: float, range_step_ft: flo
         termination_reason = None
         last_recorded_range = 0.0
         start_integration_step_count = self.integration_step_count
-        while (range_vector.x <= range_limit_ft + min_step) or (
+        while (range_vector.x <= range_limit_ft) or (
                 last_recorded_range <= range_limit_ft - 1e-6):
             self.integration_step_count += 1
 
@@ -160,9 +158,9 @@ def f(v: Vector) -> Vector:  # dv/dt (acceleration)
             ranges.append(make_trajectory_row(
                 props, data.time, data.position, data.velocity, data.mach, data_filter.current_flag)
             )
-        # Ensure that we have at least two data points in trajectory, or 1 if filter_flags==NONE
+        # Ensure that we have at least two data points in trajectory,
         # ... as well as last point if we had an incomplete trajectory
-        if (filter_flags and ((len(ranges) < 2) or termination_reason)) or len(ranges) == 0:
+        if (filter_flags and ((len(ranges) < 2) or termination_reason)) or len(ranges) == 1:
             if len(ranges) > 0 and ranges[-1].time == time:  # But don't duplicate the last point.
                 pass
             else:

py_ballisticcalc/engines/velocity_verlet.py

@@ -87,9 +87,6 @@ def _integrate(self, props: ShotProps, range_limit_ft: float, range_step_ft: flo
         acceleration_vector = self.gravity_vector - drag * relative_velocity # type: ignore[operator]
         # endregion
 
-        # Ensure one iteration when record step is smaller than calc_step
-        min_step = min(props.calc_step, range_step_ft)
-
         data_filter = _TrajectoryDataFilter(filter_flags=filter_flags, range_step=range_step_ft,
                                             initial_position=range_vector, initial_velocity=velocity_vector,
                                             barrel_angle_rad=props.barrel_elevation_rad,
@@ -102,7 +99,7 @@ def _integrate(self, props: ShotProps, range_limit_ft: float, range_step_ft: flo
         termination_reason = None
         last_recorded_range = 0.0
         start_integration_step_count = self.integration_step_count
-        while (range_vector.x <= range_limit_ft + min_step) or (
+        while (range_vector.x <= range_limit_ft) or (
                 last_recorded_range <= range_limit_ft - 1e-6):
             self.integration_step_count += 1
 
@@ -160,9 +157,9 @@ def _integrate(self, props: ShotProps, range_limit_ft: float, range_step_ft: flo
             ranges.append(make_trajectory_row(
                 props, data.time, data.position, data.velocity, data.mach, data_filter.current_flag)
             )
-        # Ensure that we have at least two data points in trajectory, or 1 if filter_flags==NONE
+        # Ensure that we have at least two data points in trajectory,
         # ... as well as last point if we had an incomplete trajectory
-        if (filter_flags and ((len(ranges) < 2) or termination_reason)) or len(ranges) == 0:
+        if (filter_flags and ((len(ranges) < 2) or termination_reason)) or len(ranges) == 1:
             if len(ranges) > 0 and ranges[-1].time == time:  # But don't duplicate the last point.
                 pass
             else:

py_ballisticcalc/generics/engine.py

@@ -8,6 +8,7 @@
 zeroing angles for firearms.
 """
 
+from abc import abstractmethod
 from typing import TypeVar, Optional, Union
 
 from typing_extensions import Protocol, runtime_checkable
@@ -37,6 +38,7 @@ def __init__(self, _config: ConfigT):
             _config (Config): The configuration object.
         """
 
+    @abstractmethod
     def integrate(self, shot_info: Shot,
                   max_range: Distance,
                   dist_step: Optional[Distance] = None,
@@ -66,6 +68,7 @@ def integrate(self, shot_info: Shot,
             HitResult: Object for describing the trajectory.
         """
 
+    @abstractmethod
     def zero_angle(self, shot_info: Shot, distance: Distance) -> Angular:
         """
         Iterative algorithm to find barrel elevation needed for a particular zero

py_ballisticcalc/interface.py

@@ -2,6 +2,7 @@
 from dataclasses import dataclass, field
 from importlib.metadata import entry_points, EntryPoint
 from typing import Generic, Any
+import warnings
 
 from deprecated import deprecated
 from typing_extensions import Union, List, Optional, TypeVar, Type
@@ -170,39 +171,49 @@ def set_weapon_zero(self, shot: Shot, zero_distance: Union[float, Distance]) ->
 
     def fire(self, shot: Shot,
              trajectory_range: Union[float, Distance],
-             trajectory_step: Optional[Union[float, Distance]] = None,
+             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:
         """Calculates the trajectory for the given shot parameters.
 
         Args:
-            shot (Shot): Initial shot parameters, including position and barrel angle.
+            shot (Shot): Shot parameters, including position and barrel angle.
             trajectory_range (float | Distance): Distance at which to stop computing the trajectory.
             trajectory_step (float | Distance | None, optional): Distance between recorded trajectory points.
-                If 0 or None, defaults to `trajectory_range`.
-            extra_data (bool, optional): If True, requests all TrajFlags. Otherwise only requests TrajFlag.RANGE.
-                Defaults to False.
+                                                                 If 0 or None, defaults to `trajectory_range`.
+            extra_data (bool, optional): [DEPRECATED] Requests flags=TrajFlags.ALL
+                                         and trajectory_step=PreferredUnits.distance(1).
+            dense_output (bool, optional): HitResult stores all calculation steps so it can interpolate any point.
             time_step (float, optional): Minimum time sampling interval in seconds. If > 0, data is
-                recorded at least this frequently. Defaults to 0.0.
+                                         recorded at least this frequently. Defaults to 0.0.
+            flags (TrajFlag, optional): Flags for specific points of interest. Defaults to TrajFlag.NONE.
             raise_range_error (bool, optional): 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 = TrajFlag.RANGE
+        filter_flags = flags
         if trajectory_step:
             dist_step = PreferredUnits.distance(trajectory_step)
-            filter_flags = TrajFlag.RANGE
+            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)
+        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

tests/test_incomplete_shots.py

@@ -7,6 +7,7 @@
     Distance,
     TrajFlag
 )
+from py_ballisticcalc.unit import PreferredUnits
 from tests.fixtures_and_helpers import print_out_trajectory_compact, zero_height_calc, \
     shot_with_relative_angle_in_degrees
 
@@ -51,7 +52,7 @@ def test_vertical_shot(zero_height_calc, loaded_engine_instance):
     hit_result = zero_height_calc.fire(shot, range, extra_data=extra_data, raise_range_error=False)
     print_out_trajectory_compact(hit_result)
     # In this case all we know is we should have two points, and the last point should be below zero.
-    assert len(hit_result) == 2
+    assert len(hit_result) == 2, "With extra_data=False, calculator should return exactly 2 points"
     assert hit_result[-1].height.raw_value < 1e-9, "Last point's height should be at or below zero"
 
     extra_data = True
@@ -167,4 +168,4 @@ def test_end_points_are_included(distance, height, angle_in_degrees, zero_height
     print(f'Difference in results Distance: {distance_difference :.02f} '
           f'Height {height_difference :.02f}')
 
-    assert distance_difference <= Distance.Foot(0.2) >> Distance.Meter
+    assert distance_difference <= (PreferredUnits.distance(1.0) >> Distance.Meter)