cos-comparison 0.3.0

Local similarity comparison for feature extraction – biologically inspired, zero‑training edge/pattern detection, multi-backend acceleration.

Cos Comparison

  

An AGI-oriented project based on local similarity comparison for feature extraction – biologically inspired, zero‑training edge / pattern detection.

---

Core Idea

Information is produced by local comparison in raw data.
This module implements the centre‑surround antagonism mechanism from neuroscience, extracting edges, textures, and keypoints using only sliding‑window similarity.

The main formula (cosine‑modulated similarity):

[ \text{cosmod} = \frac{2,(A\cdot B)}{|A|^2 + |B|^2} ]

• A step toward real AGI
• No training, no labels, no backpropagation
• Works on 1D, 2D, 3D, 4D data (audio, images, video, volumes)
• Supports passive (reflex) and active (template matching) modes
• Pure Python core with optional NumPy / C acceleration

---

Core Principles

1. Information emerges from local comparison – edges, textures, and patterns arise by comparing neighbouring regions.
2. Centre‑surround antagonism – two sliding windows are compared with a fixed displacement vector d, mimicking retinal ganglion cells.
3. Three complementary similarity measures – \_cos (angular), \_mod (magnitude), \_cosmod (recommended combination).
4. Dual operational modes – passive (boundary detection without templates) and active (template matching with a user‑supplied kernel).
5. Multi‑scale and multi‑directionality – vary window size for scale, change d for orientation selectivity (vertical, horizontal, diagonal).
6. Dimension‑agnostic – the same algorithm runs on 1D, 2D, 3D, 4D, and beyond.
7. Zero training, zero labels – fully deterministic, ready to use out of the box.
8. Full determinism and interpretability – every output has a clear geometric meaning.
9. Modular, pluggable architecture – pure Python reference, NumPy‑vectorised, and C high‑performance backends with automatic fallback.

---

Design Principles

The library adheres to two key design principles:

• Zero internal dependencies – the core is self‑contained and does not rely on any third‑party modules. It runs everywhere Python runs.
• Open integration – a generic hook/interface mechanism is provided, allowing users to seamlessly plug in any external module that conforms to the specified protocols (e.g., GPU/NPU accelerators, custom tensor types, or specialised hardware backends). This keeps the core lightweight while enabling unlimited extensibility.

---

🚀 What's New in Version 0.3.0

Version 0.3.0 brings major architectural improvements, performance optimisations, and expanded documentation.

Highlights

• Multi‑Backend Architecture – three backends with automatic fallback:

  • Python C Extension (cos\_comparison\_pydll) – maximum performance, tight Python integration, GIL release support.
  • C via ctypes (cos\_comparison\_c) – high performance, easy compilation, full feature parity.
  • Pure Python (cos\_comparison) – zero‑dependency reference implementation, always works.

• Preallocated Output Support – output, output\_start, output\_step parameters for memory‑efficient batch processing.

• Callback System – start\_callback, end\_callback, global\_error\_callback, local\_error\_callback, return\_callback for extensibility.

• Custom Types – vector\_map\_as\_tensor, func\_name\_space, default\_contain for advanced use cases.

• Duck Typing Protocol – \_\_cos\_comparison\_passive\_\_ / \_\_cos\_comparison\_active\_\_ for custom data types.

• Dimension Aliases – \*\_1d, \*\_2d, \*\_3d, \*\_4d convenience functions for all core operations.

• Seven‑Layer Cognitive Architecture – brain‑inspired layered design from core computation to high‑level cognition.

• Complete English Documentation – professional, academic‑grade documentation covering principles, architecture, and API.

Backend Performance Comparison

Backend	Relative Speed	Memory Usage	Status
Python C Extension	100–200×	~5–8 MB (estimated)	🟡 Beta
C (ctypes)	50–100×	~28 MB	🟡 Beta
Pure Python	1×	~22 MB	✅ Stable

**Note**: Memory measurements are based on a 424×322×3 test image with a 3×3 window. C‑extension memory is estimated because tracemalloc cannot track C‑level allocations. C(ctypes) can currently only be compiled by youself because I fail to find a way to compile it in installing by pip ,but I succeed to compile it by compiler.

⚠️ Breaking Changes

1. NumPy backend removed
Introducing numpy made the project more complex and potentially unsafe – it was difficult to profile, and it opened a risk of supply‑chain attacks (e.g., a malicious package named numpy). Therefore, it has been removed. However, the core now natively supports numpy arrays (and any type implementing \_\_index\_\_ and \_\_len\_\_, such as PyTorch tensors) via the duck‑typing protocol.

2. Spelling errors fixed
All misspellings (e.g., genrate → generate) have been corrected throughout the codebase and documentation.

---

⚠️ Migration Guide from 0.2.x

Starting from version 0.2.0, the package has been restructured.
All core functions now reside in the core submodule.

Import using:

from cos\_comparison import core

Old code using import cos\_comparison as cc will not work with 0.3.0. Update your imports accordingly.

---

Installation

pip install cos-comparison

To install with NumPy acceleration (optional):

pip install cos-comparison\[numpy]

---

Quick Start

1D – find similar segments (passive mode)

from cos\_comparison import core

data = \[1.0, 2.0, 3.0, 4.0, 5.0]
result = core.cos\_comparison\_passive\_1d(
    data,
    window\_size=(2,),
    step=(1,),
    d=(1,)
)
print(result)

2D – edge detection (passive mode)

from cos\_comparison import core

image = \[
    \[1, 1, 0, 0],
    \[1, 1, 0, 0],
    \[0, 0, 1, 1],
    \[0, 0, 1, 1]
]
edges = core.cos\_comparison\_passive\_2d(
    image,
    window\_size=(2, 2),
    step=(1, 1),
    d=(1, 0)
)
print(edges)

Active mode – template matching

from cos\_comparison import core

data = \[1.0, 2.0, 3.0, 4.0, 5.0]
kernel = \[1.0, 0.0]
result = core.cos\_comparison\_active\_1d(
    data,
    kernel=kernel,
    step=(1,)
)
print(result)

Whole‑tensor cosine

from cos\_comparison import core

a = \[1, 2, 3]
b = \[2, 3, 4]
sim = core.cos\_1d(a, b)
print(sim)

Using the recommended \_cosmod similarity

from cos\_comparison import core

result = core.cos\_comparison\_passive\_1d(
    data,
    window\_size=(2,),
    step=(1,),
    d=(1,),
    algorithm=core.\_cosmod
)

---

Multi‑Backend System

The package provides a sophisticated multi‑backend manager that automatically selects the fastest available backend while maintaining a unified API.

Default Backend Priority

Priority	Backend	Implementation	Performance	Status
1	cos\_comparison\_pydll	Python C Extension	100–200×	🟡 Beta
2	cos\_comparison\_c	C via ctypes	50–100×	🟡 Beta
3	cos\_comparison	Pure Python	1×	✅ Stable

Key Features

• Automatic fallback – if a higher‑priority backend is unavailable, the system automatically tries the next one.
• Runtime switching – manually switch backends at any time.
• Unified API – all backends expose the same interface.
• Configuration flexibility – control backend priority via a config file or environment variable.
• Zero‑dependency guarantee – the pure Python backend always works.

Switching Backends

from cos\_comparison import core

# Check current backend configuration
backends = core.get\_mode()
print(backends)

# Force a specific backend
core.set\_mode("cos\_comparison")  # Pure Python for debugging

# Multiple backends (tried in order)
core.set\_mode(\["cos\_comparison\_c", "cos\_comparison"])

Environment Variable

# Unix
export COS\_BACKEND=cos\_comparison\_pydll,cos\_comparison

# Windows
set COS\_BACKEND=cos\_comparison\_pydll,cos\_comparison

---

API Overview

Passive mode (self‑similarity)

• cos\_comparison\_passive\_1d / \_2d / \_3d / \_4d + generic N‑dim cos\_comparison\_passive

Active mode (template matching)

• cos\_comparison\_active\_1d / \_2d / \_3d / \_4d + generic N‑dim cos\_comparison\_active

Whole‑tensor cosine

• cos\_1d / \_2d / \_3d / \_4d

Statistics (sliding window)

• mean\_local\_1d / \_2d / \_3d / \_4d
• local\_variance\_1d / \_2d / \_3d / \_4d

Generic helpers

• cos(A, B, algorithm=core.\_cos) – works on arbitrarily nested lists.
• execute\_many(func, arg\_iter, kwarg\_iter) – batch execution (returns a list).
• execute\_many\_iter(func, arg\_iter, kwarg\_iter) – batch execution (generator).

---

Command Line Interface

python -m cos\_comparison.core passive --data input.json --window 3 3 --output out.json

---

Performance & Memory Benchmarks

Benchmark results for the three backends (pure Python, C via ctypes, and the Python C extension) using a 322×424×3 RGB test image.
All tests were run with the same parameter grid: 3 window sizes, 3 offsets, and 3 similarity algorithms (27 combinations total).
Measurements were taken on a standard CPU (no GPU) with Python 3.11.

**Note**: Memory figures for the C extension are **estimated** because tracemalloc cannot track C‑level allocations. They are derived from process‑level RSS measurements on Linux.

---

⏱️ Execution Time (27‑run average)

Backend	3×3 window (s)	5×5 window (s)	7×7 window (s)	Total (27 runs)	Speedup vs Python
Pure Python	7.31	18.80	28.00	486.8 s	1×
C (ctypes)	0.338	0.380	0.449	10.5 s	~46×
Python C Extension	0.088	0.213	0.407	6.35 s	~77×

• Algorithm type (cos / mod / cosmod) has negligible impact (<5%) on execution time.
• Window size is the dominant factor – larger windows increase time proportionally.
• The C extension is 65% faster than the ctypes wrapper and 77× faster than pure Python.

---

🧠 Memory Usage (peak RSS, pure Python & ctypes)

Backend	Average peak memory	Notes
Pure Python	~21.5 MB	Stable across all parameters
C (ctypes)	~28 MB (Python side) + C buffers	Real RSS may be higher
Python C Extension	~5–8 MB (estimated)	C‑allocated memory not fully captured

• Memory is largely independent of window size, offset, or algorithm.
• The pure Python backend uses a fixed ~21–22 MB for the test image.
• The C extension is extremely memory‑efficient, allocating only the output tensor.

---

✅ Output Consistency

All three backends produce identical output values (within floating‑point precision) for every parameter combination – verifying that the core algorithm is correctly implemented across all implementations.

---

📊 Full Raw Data

Complete CSV results (time and memory for all 27 combinations) are available in the tests/ directory:

• test\_python.txt, test\_c.txt, test\_pydll.txt – performance data
• memory\_python.txt, memory\_c.txt, memory\_pydll.txt – memory data
• out\_\*.txt – execution logs with saved heatmap paths

---

🧪 How to Reproduce

# Performance test (all backends)
python tests/test\_performance.py --image tests/testdata/image\_20260408.png --repeat 3 --output results.csv

# Memory test (using process RSS)
python tests/test\_memory.py --image tests/testdata/image\_20260408.png --output memory.csv

Benchmarks run on a commodity CPU (Intel Core i7‑1260P). Your results may vary depending on hardware and operating system.

---

Author

I born in May 31 2008,and it is lucy for me to meet that AI have a great development today.

These days, I have been running many tests and observing surprising data outputs.

the reason why the versions before it often have many problem is that I did not have time to test it enough in examination-oriented education,now I have enough time to test it and polish it. Yet there is still a long road ahead to achieve a true AGI.
I may be forced to abandon AI research due to overwhelming personal reasons, but I do not want my ideas to fade away unnoticed.
Thus, the purpose of this project is to share my thoughts, in the hope of inspiring others to build upon them.

---

Next Plan

1. Introduce an extension interface in the core, allowing users to plug in GPU, NPU, or other accelerators.
2. Complete the remaining cognitive submodules, striving toward a simple but functional AI agent.

---

License

MIT © 2026 Li Jinxin. See LICENSE for details.