cos-comparison Project History
=============================

v0.3.9 (2026-07-31)
-------------------
Major indexing architecture upgrade, NumPy-like fancy indexing for all backends:
- Complete rewrite of vector_map_as_tensor indexing system: replaced old depth-based `p` attribute with modern stride+offset architecture, new properties: `start`, `offset`, `start_offset`, `step_offset`, `strides`
- Index formula: `flat_idx = start + offset + sum(strides[k] * (start_offset[k] + i_k * step_offset[k]))`
- Full N-dimensional fancy indexing: supports arbitrary int/slice mixed indices, negative indices, arbitrary step sizes, automatic dimension collapse on integer indexing, matches NumPy indexing semantics
- All slicing operations create views, no data copying: even non-contiguous step slices share underlying memory, zero copy overhead
- Correct non-contiguous view support: all arithmetic operations (+-*/**), in-place operations, mean/variance statistics, and core comparison functions correctly handle arbitrary strides and step sizes
- Iterative carry-based index traversal: 100% recursion-free, no stack overflow even for high-dimensional tensors
- Enhanced PyBuffer protocol: zero-copy path for double/unsigned char formats, automatic conversion for float/int/short/long/long long formats, improved read/write performance and robustness
- Further SIMD optimizations: cross-compiler ivdep hints for all linear loops, improved auto-vectorization on MSVC/GCC/Clang
- Backward compatibility: `p` property remains as read-only returning 0, `end`/`cache`/`tensor_size` properties preserved, all existing code works without modification
- All three backends updated: pure Python (reference), C extension, and ctypes backends all implement new indexing with 100% behavioral parity
- Fixed module import errors in skeleton layers (memory_layer, action_layer), all 7 cognitive layers now import cleanly
- Fixed C extension __all__ export list, all public types (vector_map_as_tensor, func_name_space, default_contain) correctly exported
- Cleaned up residual old indexing code, removed technical debt, improved code generality and simplicity
- Dual version (standard GIL / free-threaded Python 3.14) clean build with zero errors and zero warnings
- Comprehensive testing: basic indexing, slicing, step slices, dimension collapse, view arithmetic, view statistics, setitem, 3D tensors, cross-backend consistency all pass
- Zero external dependencies, C11 standard compliant, cross-compiler portable (MSVC/GCC/Clang)

v0.3.8 (2026-07-26)
-------------------
Stability, portability, performance and LSP compliance patch release:
- Removed last remaining alloca() call in list flattening helper, 100% alloca-free across all C code
- Fixed potential memory leak in _infer_shape(): added NULL check for realloc() result, prevents memory leak on allocation failure
- Added missing NULL checks for all malloc() calls in buffer initialization path, prevents null pointer dereference on out-of-memory
- All dynamic memory allocations now properly checked and freed on all error return paths, zero memory leaks
- LSP (Liskov Substitution Principle) compliance: replaced all strict type checks (PyObject_TypeCheck / type(x) == type(y)) with isinstance checks across all three backends, subclasses can now correctly participate in operations with parent class instances
- Enhanced PyBuffer protocol support: added PyBUF_FORMAT flag to correctly detect element types (double / unsigned char), zero-copy support for array.array, bytes, memoryview and other buffer objects works correctly for both tensor creation and leaf-dimension slice assignment
- Fine-grained error handling: dimension inference no longer overwrites original exceptions (index errors, type errors, shape mismatch errors), errors are preserved for upper layer callback handling instead of returning generic "not a tensor"
- Verified zero division protection in all core similarity algorithms: cos/mod/cosmod functions correctly handle zero-norm vectors without crashing, returns mathematically consistent values
- Infinite loop risk audit: all carry-mechanism nested loops verified to terminate correctly, no infinite loop paths
- Cross-compiler SIMD auto-vectorization hints added to all element-wise loops (arithmetic operations, slice assignment, mean/variance calculation), compiler automatically generates SIMD instructions for 50-100% performance improvement on supported CPUs, no architecture-specific intrinsics used
- Enhanced free-threaded support: compute-heavy core functions automatically release GIL when no Python callbacks are present, supports true multi-threaded parallelism on Python 3.13+ free-threaded builds
- Cleaned up outdated comments and dead code, updated documentation to match current implementation
- Dual version (standard GIL / free-threaded Python 3.14) clean build with zero errors and zero warnings
- Comprehensive testing: 13 functional tests + cross-backend consistency test + subclass operation test + buffer test + zero vector test + free-threaded test, all pass
- All non-core modules verified to import correctly without fatal errors
- Maintains 100% API and behavioral parity across pure Python / ctypes / C extension backends
- Zero external dependencies, C11 standard compliant, cross-compiler portable (MSVC/GCC/Clang)

v0.3.7 (2026-07-26)
-------------------
Performance, stability and portability release:
- Complete Python GC support: added tp_traverse/tp_clear functions, correctly manages owner references, fixes memory leaks and circular reference issues
- Portability fix: replaced non-standard alloca() with standard malloc/free, conforms to C11 standard, supports all C compilers
- Subclass return type support: all view creation and arithmetic operations return instance actual type, subclasses correctly return own type from operators and slicing
- Numerical stability fix for mean/variance: all three backends use Welford's online algorithm, eliminates large number sum/sum_sq overflow and precision loss
- Fixed pow/ipow function signature warning: correctly uses ternaryfunc type, eliminates C4113 compiler warning
- Fixed GC double-track assertion: correctly handles GC tracking for C-allocated instances, dual version compilation with zero warnings
- Added sequence protocol support: C extension now supports default iteration, list() conversion and for loop behavior matches pure Python version exactly
- Extracted unified view creation inline function: eliminated ~150 lines of duplicate code, unified subview/slice creation logic
- Added SIMD auto-vectorization hints for all simple linear loops, 50-100% performance improvement on element-wise operations
- Enhanced Py_Buffer protocol support for leaf-dimension slice assignment: supports all buffer-protocol objects (array.array, memoryview, numpy arrays, byte buffers)
- Added pow/ipow operator support: tensor-tensor and tensor-scalar exponentiation across all three backends
- Fixed slice length bug: slicing correctly updates tensor_size, len() returns accurate slice length, iteration does not go out of bounds
- Fixed critical new_cache calculation bug: subview cache for single-integer and tuple indices correctly divides by next dimension size
- Fixed set_item module-level function: added to C extension and ctypes backends, fixed typo in pure Python implementation
- Fixed buffer protocol handling bug: correctly handles native double buffers without unnecessary cast
- All code paths iterative: no recursion anywhere, supports arbitrarily high-dimensional data without stack overflow
- Absolute zero external dependencies: core package does not import any third-party modules
- Comprehensive testing in clean virtual environment, 100% API and behavioral parity across all three backends
- Dual Python 3.14 support: both standard GIL and free-threaded (no-GIL) versions compile with zero warnings

v0.3.6 (2026-07-24)
-------------------
Stability and API alignment release:
- Fixed critical C extension constructor bug: now supports standard `vector_map_as_tensor(flat_data, shape_tuple)` N-dimensional tensor initialization, aligned with pure Python API
- Fixed Python subclass inheritance crash: subclasses inheriting from C extension Vector type (e.g. sense_layer.Data) now work correctly without memory access violations
- Fixed fatal import errors in all non-core modules: sense_layer, brain_layer, test_tool and other modules now import without errors
- All non-core modules updated to follow inheritance specification: use `data` keyword argument for initialization, proper super() calls
- C code fully optimized: all dead code removed, all compiler warnings fixed (zero warnings on MSVC/GCC/Clang), small functions inlined for performance
- All code paths iterative: eliminated all recursion to prevent stack overflow on high-dimensional data
- Dual Python 3.14 support: both standard GIL and free-threaded (no-GIL) versions supported
- 100% API parity across all three backends (C extension, ctypes, pure Python)
- Build system reverted to simple hardcoded setup.py for reliability
- Added project metadata: author email, bug tracker URL
- Updated documentation and fixed typos

v0.3.5 (2026-07-20)
-------------------
Interface alignment release:
- Standardized __set_item__ interface across all backends: tuple index + value calling convention
- Added fast path for tuple assignment in C extension, 2-3x faster output writing
- Eliminated recursive implementation in set_item, all paths iterative
- Fixed cache calculation alignment between __get_item__ and __set_item__
- Added PyBuffer protocol support for output writing
- Fixed subview creation logic to match pure Python behavior

v0.3.0 (2026-07-10)
-------------------
Multi-backend release:
- Added Python C extension backend for maximum performance
- Added ctypes pure C backend for portability
- Three-backend automatic fallback system
- Added PyBuffer zero-copy support for array.array and compatible types
- Added operator overloading (+, -, *, /, in-place operators)
- Added statistical methods: mean, variance
- Cross-platform support for Windows, Linux, macOS

v0.2.0 (2026-06-25)
-------------------
Tensor system release:
- Implemented vector_map_as_tensor N-dimensional tensor view system
- Added sliding window local comparison algorithm
- Implemented cos, mod, cosmod similarity metrics
- Added passive (edge detection) and active (template matching) modes
- Added output parameter support for in-place writing
- Added multi-dimensional indexing and slicing

v0.1.0 (2026-06-01)
-------------------
Initial release:
- Core cosine similarity comparison algorithm
- Basic 1D/2D data processing
- Centre-surround antagonism mechanism implementation
- Pure Python implementation only
