Added cython-specific tests to py_ballisticcalc.exts/tests

Author: dbookstaber

docs/Cython.md

@@ -106,6 +106,9 @@ It explains naming, error handling, Global Interpreter Lock (GIL) usage, and why
     - If the function is purely a utility that both Cython modules and Python code will call and it neither needs `nogil` nor special exception mapping, `cpdef` is acceptable.
     - If the function is a hot numeric path, manipulates raw buffers/pointers, or needs careful error/status handling, implement a `cdef` nogil core and a `def` wrapper.
 
+## 11. Exception annotation on nogil
 
----
-Generated: August 19, 2025
+`.pxd` declarations for `nogil` functions the module-level functions should have explicit exception values. Cython warns that cimporters calling them without the GIL will require exception checks. If you intend for these functions to never raise Cython exceptions, consider:
+
+    - Declaring them `noexcept` in the `.pxd`, or
+    - Specify an explicit exception value (e.g., `except NULL` or `except False`) where appropriate to avoid implicit exception checks.

py_ballisticcalc.exts/__init__.py

@@ -1 +1,7 @@
-from .py_ballisticcalc_exts import *
+try:
+	# Normal package import (when used as a subpackage)
+	from .py_ballisticcalc_exts import *
+except Exception:
+	# pytest may import this package as a top-level module during collection;
+	# fall back to absolute import of the nested extension package if needed.
+	from py_ballisticcalc_exts import *

py_ballisticcalc.exts/py_ballisticcalc_exts/base_engine.pxd

@@ -1,22 +1,8 @@
 # pxd for py_ballisticcalc_exts.base_engine
 
-# noinspection PyUnresolvedReferences
-from cython cimport final
-# noinspection PyUnresolvedReferences
-from libc.math cimport fabs, sin, cos, tan, atan, atan2
-
-# noinspection PyUnresolvedReferences
-from py_ballisticcalc_exts.trajectory_data cimport TrajFlag_t, BaseTrajDataT, TrajectoryData
-# noinspection PyUnresolvedReferences
-from py_ballisticcalc_exts.cy_bindings cimport (
-    Config_t,
-    Wind_t,
-    ShotData_t,
-)
-# noinspection PyUnresolvedReferences
-from py_ballisticcalc_exts.v3d cimport (
-    V3dT
-)
+from py_ballisticcalc_exts.trajectory_data cimport TrajFlag_t, BaseTrajDataT
+from py_ballisticcalc_exts.cy_bindings cimport Config_t, Wind_t, ShotData_t
+from py_ballisticcalc_exts.v3d cimport V3dT
 
 __all__ = (
     'CythonizedBaseIntegrationEngine',

py_ballisticcalc.exts/py_ballisticcalc_exts/base_engine.pyx

@@ -250,37 +250,6 @@ cdef BaseTrajDataT TrajDataFilter_t_should_record(TrajDataFilter_t * tdf,
     else:
         return <BaseTrajDataT>None
 
-cdef void _check_next_time(TrajDataFilter_t * tdf, double time):
-    if time > tdf.time_of_last_record + tdf.time_step:
-        tdf.current_flag |= TrajFlag_t.RANGE
-        tdf.time_of_last_record = time
-
-cdef void _check_mach_crossing(TrajDataFilter_t * tdf, double velocity, double mach):
-    cdef double current_v_mach = velocity / mach
-    if tdf.previous_v_mach > 1 >= current_v_mach:
-        tdf.current_flag |= TrajFlag_t.MACH
-    tdf.previous_v_mach = current_v_mach
-
-cdef void _check_zero_crossing(TrajDataFilter_t * tdf, const V3dT *range_vector_ptr):
-    # Deprecated by new ZERO detection in TrajDataFilter_t_should_record; kept for compatibility if used elsewhere
-    cdef double ca = cos(tdf.look_angle)
-    cdef double sa = sin(tdf.look_angle)
-    cdef double s_prev = tdf.previous_position.y * ca - tdf.previous_position.x * sa
-    cdef double s_curr = range_vector_ptr[0].y * ca - range_vector_ptr[0].x * sa
-    if not (tdf.seen_zero & TrajFlag_t.ZERO_UP):
-        if s_prev < 0.0 and s_curr >= 0.0:
-            tdf.current_flag |= TrajFlag_t.ZERO_UP
-            tdf.seen_zero |= TrajFlag_t.ZERO_UP
-    elif not (tdf.seen_zero & TrajFlag_t.ZERO_DOWN):
-        if s_prev >= 0.0 and s_curr < 0.0:
-            tdf.current_flag |= TrajFlag_t.ZERO_DOWN
-            tdf.seen_zero |= TrajFlag_t.ZERO_DOWN
-
-cdef void _check_apex(TrajDataFilter_t * tdf, const V3dT *velocity_vector_ptr):
-    if velocity_vector_ptr[0].y <= 0 and tdf.previous_velocity.y > 0:
-        # We have crossed the apex
-        tdf.current_flag |= TrajFlag_t.APEX
-
 
 cdef WindSock_t * WindSock_t_create(object winds_py_list):
     """

py_ballisticcalc.exts/py_ballisticcalc_exts/base_traj_seq.pxd

@@ -1,13 +1,25 @@
 """
 Header file for base_traj_seq.pyx - C Buffer Trajectory Sequence
 
-This declares the CBaseTrajSeq class for use by other Cython modules.
+Notes and conventions (keep in sync with base_traj_seq.pyx):
+- This .pxd is authoritative for C-level declarations shared across Cython
+  modules. Avoid redeclaring enums, structs or function prototypes in the
+  corresponding .pyx files; duplicating declarations can cause "redeclared"
+  errors during editable installs or when Cython regenerates sources.
+- Nogil helpers are declared here with explicit exception sentinels so that
+  callers know the sentinel value used when the function is invoked without
+  the GIL.  Conventions used in this module:
+    * pointer-returning functions: use `except NULL nogil` (return NULL on error)
+    * bint-returning try-style helpers: use `except False nogil` (return False on error)
+    * append-style functions that cannot fail at the C level are marked `noexcept nogil`
+- The quadratic Lagrange interpolation used by the nogil core is currently
+  inlined in the implementation to avoid cross-module nogil call-site
+  diagnostics; a future refactor could move this math into a shared C
+  header and declare a pure-C helper here.
 """
 
-from libc.stdlib cimport malloc, realloc, free
-
 # cimport BaseTrajDataT and interpolation helper
-from py_ballisticcalc_exts.trajectory_data cimport BaseTrajDataT, lagrange_quadratic
+from py_ballisticcalc_exts.trajectory_data cimport BaseTrajDataT
 
 # Include BaseTrajC struct definition from header file
 cdef extern from "include/basetraj_seq.h" nogil:
@@ -33,16 +45,14 @@ cdef enum InterpKey:
     KEY_VEL_Y
     KEY_VEL_Z
 
-# Nogil core: returns a malloc'ed BaseTrajC* on success or NULL on failure.
-
 # Module-level nogil function that operates directly on raw buffer pointers.
 # It returns a malloc'ed BaseTrajC* or NULL on error.
-cdef BaseTrajC* _interpolate_nogil_raw(BaseTrajC* buffer, size_t length, Py_ssize_t idx, int key_kind, double key_value) nogil
+cdef BaseTrajC* _interpolate_nogil_raw(BaseTrajC* buffer, size_t length, Py_ssize_t idx, int key_kind, double key_value) except NULL nogil
 # Nogil-safe raw capacity/append helpers that operate on C pointers.
 # They mutate the buffer pointer and lengths via provided C pointers.
-cdef bint ensure_capacity_try_nogil_raw(BaseTrajC** buf_p, size_t* capacity_p, size_t min_capacity) nogil
+cdef bint ensure_capacity_try_nogil_raw(BaseTrajC** buf_p, size_t* capacity_p, size_t min_capacity) except False nogil
 cdef void append_nogil_raw(BaseTrajC** buf_p, size_t* length_p, double time, double px, double py, double pz,
-                          double vx, double vy, double vz, double mach) nogil
+                                                                double vx, double vy, double vz, double mach) noexcept nogil
 
 cdef class CBaseTrajSeq:
     """
@@ -58,15 +68,9 @@ cdef class CBaseTrajSeq:
     # with thin Python `def` wrappers in the .pyx. This keeps C-level calls
     # zero-overhead while preserving Python testability.
     cdef void _append_c(self, double time, double px, double py, double pz, 
-                     double vx, double vy, double vz, double mach)
+                              double vx, double vy, double vz, double mach)
     # (nogil helpers are implemented as module-level functions that operate on raw
     # C pointers and lengths to avoid accessing 'self' without the GIL.)
     # Note: nogil try/grow helpers removed in this patch for compilation stability.
     cdef BaseTrajC* c_getitem(self, Py_ssize_t idx)
     cdef BaseTrajDataT _interpolate_at_c(self, Py_ssize_t idx, str key_attribute, double key_value)
-    # Use plain int for the key_kind in the pxd to avoid enum cross-import issues.
-    # Note: class does not expose nogil methods that access 'self'. Instead a
-    # module-level nogil function is provided below to operate on raw buffers.
-
-    # Nogil interpolation core declared below as module-level enum and function.
-

py_ballisticcalc.exts/py_ballisticcalc_exts/base_traj_seq.pyx

@@ -35,6 +35,7 @@ cdef extern from "include/basetraj_seq.h" nogil:
 
 __all__ = ['CBaseTrajSeq']
 
+
 cdef class CBaseTrajSeq:
     """
     C Buffer Trajectory Sequence
@@ -59,7 +60,6 @@ cdef class CBaseTrajSeq:
         traj_seq.append(time, px, py, pz, vx, vy, vz, mach)
         trajectory_data = traj_seq[0]  # Lazily converted to BaseTrajData
     """
-    
     # Attributes declared in the matching .pxd; do not redeclare here.
 
     def __cinit__(self):
@@ -120,7 +120,7 @@ cdef class CBaseTrajSeq:
             self._capacity = new_capacity
 
     cdef void _append_c(self, double time, double px, double py, double pz, 
-                     double vx, double vy, double vz, double mach):
+                              double vx, double vy, double vz, double mach):
         """
         Append a new BaseTrajC entry to the buffer.
         
@@ -129,10 +129,11 @@ cdef class CBaseTrajSeq:
             px, py, pz: Position coordinates  
             vx, vy, vz: Velocity coordinates
             mach: Mach number
+
+        Note: This is the C-level `append` implementation and requires the GIL (because it references `self`).
+            Callers who want a nogil fast-path should use the module-level raw helpers `ensure_capacity_try_nogil_raw`
+            and `append_nogil_raw` which operate on raw C pointers and can be used inside with nogil: blocks.
         """
-        # Note: this is the raw C implementation used on hot paths. It is declared
-        # nogil so callers that hold the GIL may release it for faster operation.
-        # Python-level callers should use the thin Python wrapper `append` below.
         self._ensure_capacity(self._length + 1)
 
         # Calculate pointer to new entry using byte arithmetic (self._buffer + self._length)
@@ -148,11 +149,9 @@ cdef class CBaseTrajSeq:
 
         # increment length (must be done while still holding the GIL in typical callers)
         self._length += 1
-    # Nogil try/grow and append helpers are implemented as module-level raw
-    # helpers to avoid touching 'self' without holding the GIL.
 
     def append(self, double time, double px, double py, double pz, 
-                     double vx, double vy, double vz, double mach):
+               double vx, double vy, double vz, double mach):
         """Python wrapper around the cdef hot-path `_append_c`.
 
         Attempt a nogil fast-path that grows and appends using the raw
@@ -163,12 +162,14 @@ cdef class CBaseTrajSeq:
         cdef BaseTrajC* local_buf = self._buffer
         cdef size_t local_cap = self._capacity
         cdef size_t local_len = self._length
-        cdef bint ok = False
+        # Explicitly initialize as bint to avoid mypy/cython literal-to-bool diagnostics
+        cdef bint ok = <bint>0
 
         # Try the nogil fast-path: grow (if needed) and append while holding no GIL.
         # We use local copies and then write them back into `self` on success.
         with nogil:
-            ok = ensure_capacity_try_nogil_raw(&local_buf, &local_cap, <size_t>(local_len + 1))
+            # Cast the C-return value to bint explicitly to satisfy static typing
+            ok = <bint> ensure_capacity_try_nogil_raw(&local_buf, &local_cap, <size_t>(local_len + 1))
             if ok:
                 append_nogil_raw(&local_buf, &local_len, time, px, py, pz, vx, vy, vz, mach)
 
@@ -183,6 +184,16 @@ cdef class CBaseTrajSeq:
         # which will raise MemoryError on failure.
         self._ensure_capacity(self._length + 1)
         self._append_c(time, px, py, pz, vx, vy, vz, mach)
+
+    def reserve(self, Py_ssize_t min_capacity):
+        """Public helper to pre-allocate buffer capacity from Python tests/benchmarks.
+
+        This calls the underlying cdef `_ensure_capacity` which performs the
+        realloc logic. It's small and safe to expose for testing/benching.
+        """
+        if min_capacity < 0:
+            raise ValueError("min_capacity must be non-negative")
+        self._ensure_capacity(<size_t>min_capacity)
 
     cdef BaseTrajC* c_getitem(self, Py_ssize_t idx):
         """
@@ -282,7 +293,7 @@ cdef class CBaseTrajSeq:
         with nogil:
             outp = _interpolate_nogil_raw(_buf, _len, idx, key_kind, key_value)
 
-        if outp == NULL:
+        if outp == <BaseTrajC*>NULL:
             raise IndexError("interpolate_at requires idx with valid neighbors (idx-1, idx, idx+1)")
 
         pos.x = outp.px; pos.y = outp.py; pos.z = outp.pz
@@ -299,7 +310,7 @@ cdef class CBaseTrajSeq:
         return res
 
 # Module-level nogil implementation that operates on raw buffers.
-cdef BaseTrajC* _interpolate_nogil_raw(BaseTrajC* buffer, size_t length, Py_ssize_t idx, int key_kind, double key_value) nogil:
+cdef BaseTrajC* _interpolate_nogil_raw(BaseTrajC* buffer, size_t length, Py_ssize_t idx, int key_kind, double key_value) except NULL nogil:
     cdef Py_ssize_t plength = <Py_ssize_t> length
     cdef BaseTrajC *p0
     cdef BaseTrajC *p1
@@ -337,24 +348,42 @@ cdef BaseTrajC* _interpolate_nogil_raw(BaseTrajC* buffer, size_t length, Py_ssiz
     else:
         return <BaseTrajC*>NULL
 
+    # Inline Lagrange quadratic interpolation to keep this function fully nogil-safe.
+    cdef double L0, L1, L2, denom0, denom1, denom2, x
+    x = key_value
+
+    # Compute denominators and check for degenerate points
+    denom0 = (x0 - x1) * (x0 - x2)
+    denom1 = (x1 - x0) * (x1 - x2)
+    denom2 = (x2 - x0) * (x2 - x1)
+    if denom0 == 0.0 or denom1 == 0.0 or denom2 == 0.0:
+        # Degenerate points - cannot interpolate safely
+        return <BaseTrajC*>NULL
+
+    L0 = ((x - x1) * (x - x2)) / denom0
+    L1 = ((x - x0) * (x - x2)) / denom1
+    L2 = ((x - x0) * (x - x1)) / denom2
+
     if key_kind != 0:
-        time = lagrange_quadratic(key_value, x0, p0.time, x1, p1.time, x2, p2.time)
+        time = p0.time * L0 + p1.time * L1 + p2.time * L2
     else:
-        time = key_value
+        time = x
 
-    px   = lagrange_quadratic(key_value, x0, p0.px,   x1, p1.px,   x2, p2.px)
-    py   = lagrange_quadratic(key_value, x0, p0.py,   x1, p1.py,   x2, p2.py)
-    pz   = lagrange_quadratic(key_value, x0, p0.pz,   x1, p1.pz,   x2, p2.pz)
-    vx   = lagrange_quadratic(key_value, x0, p0.vx,   x1, p1.vx,   x2, p2.vx)
-    vy   = lagrange_quadratic(key_value, x0, p0.vy,   x1, p1.vy,   x2, p2.vy)
-    vz   = lagrange_quadratic(key_value, x0, p0.vz,   x1, p1.vz,   x2, p2.vz)
+    px = p0.px * L0 + p1.px * L1 + p2.px * L2
+    py = p0.py * L0 + p1.py * L1 + p2.py * L2
+    pz = p0.pz * L0 + p1.pz * L1 + p2.pz * L2
+    vx = p0.vx * L0 + p1.vx * L1 + p2.vx * L2
+    vy = p0.vy * L0 + p1.vy * L1 + p2.vy * L2
+    vz = p0.vz * L0 + p1.vz * L1 + p2.vz * L2
 
     if key_kind != 1:
-        mach = lagrange_quadratic(key_value, x0, p0.mach, x1, p1.mach, x2, p2.mach)
+        mach = p0.mach * L0 + p1.mach * L1 + p2.mach * L2
     else:
-        mach = key_value
+        mach = x
 
-    outp = <BaseTrajC*> malloc(<size_t>(sizeof(BaseTrajC)))
+    # Cast sizeof(...) to size_t to match malloc's size parameter and avoid
+    # implicit-int-to-size_t warnings on some compilers/platforms.
+    outp = <BaseTrajC*> malloc(<size_t>sizeof(BaseTrajC))
     if outp == NULL:
         return <BaseTrajC*>NULL
 
@@ -368,14 +397,14 @@ cdef BaseTrajC* _interpolate_nogil_raw(BaseTrajC* buffer, size_t length, Py_ssiz
 
 # Nogil-safe raw capacity/append helpers implemented to match .pxd declarations.
 # These operate purely on C pointers and primitive types so they can run without the GIL.
-cdef bint ensure_capacity_try_nogil_raw(BaseTrajC** buf_p, size_t* capacity_p, size_t min_capacity) nogil:
+cdef bint ensure_capacity_try_nogil_raw(BaseTrajC** buf_p, size_t* capacity_p, size_t min_capacity) except False nogil:
     cdef size_t cur = capacity_p[0]
     cdef size_t new_capacity
     cdef BaseTrajC* new_buf
     cdef size_t doubled
 
     if min_capacity <= cur:
-        return True
+        return <bint>1
 
     if cur > 0:
         doubled = <size_t>(cur * 2)
@@ -388,15 +417,15 @@ cdef bint ensure_capacity_try_nogil_raw(BaseTrajC** buf_p, size_t* capacity_p, s
 
     new_buf = <BaseTrajC*>realloc(<void*>buf_p[0], new_capacity * sizeof(BaseTrajC))
     if new_buf == NULL:
-        return False
+        return <bint>0
 
     buf_p[0] = new_buf
     capacity_p[0] = new_capacity
-    return True
+    return <bint>1
 
 
 cdef void append_nogil_raw(BaseTrajC** buf_p, size_t* length_p, double time, double px, double py, double pz,
-                          double vx, double vy, double vz, double mach) nogil:
+                          double vx, double vy, double vz, double mach) noexcept nogil:
     cdef BaseTrajC* entry_ptr = <BaseTrajC*>((<char*>buf_p[0]) + (<size_t>length_p[0]) * sizeof(BaseTrajC))
     entry_ptr.time = time
     entry_ptr.px = px; entry_ptr.py = py; entry_ptr.pz = pz

py_ballisticcalc.exts/tests/README.md

@@ -0,0 +1,12 @@
+Cython-specific tests and benchmarks for py-ballisticcalc extensions
+
+- Run the CI helper from PowerShell to build, test, and microbench:
+
+```powershell
+./ci_run_cython_checks.ps1
+```
+
+- Unit tests live in `test_cbase_traj_seq_cython.py`.
+- Smoke and bench scripts: `smoke_cbase_traj_seq.py`, `bench_append_speed.py`, `microbench.py`.
+
+These are intentionally segregated so repo-root workflows aren't used during quick cython iteration.

py_ballisticcalc.exts/tests/bench_append_speed.py

@@ -0,0 +1,16 @@
+import time
+
+from py_ballisticcalc_exts.base_traj_seq import CBaseTrajSeq
+
+
+def bench(n=100000):
+    seq = CBaseTrajSeq()
+    t0 = time.time()
+    for i in range(n):
+        seq.append(float(i), float(i*0.1), 0.0, 0.0, 0.0, 0.0, 0.0, 0.5)
+    t1 = time.time()
+    print(f"append {n}: {t1-t0:.4f}s")
+
+
+if __name__ == '__main__':
+    bench(200000)

py_ballisticcalc.exts/tests/ci_run_cython_checks.ps1

@@ -0,0 +1,8 @@
+# CI helper: run cython-focused checks locally.
+# - Builds extensions in-place
+# - Runs the cython-specific pytest folder
+# - Runs microbench
+
+python -u setup.py build_ext --inplace ;
+pytest -q py_ballisticcalc.exts/tests ;
+python py_ballisticcalc.exts/tests/microbench.py