Metadata-Version: 2.4
Name: cos-comparison
Version: 0.3.0
Summary: Local similarity comparison for feature extraction – biologically inspired, zero‑training edge/pattern detection, multi-backend acceleration.
Author: Li Jinxin
License-Expression: MIT
Project-URL: Homepage, https://github.com/LiJinxin/cos-comparison
Project-URL: Repository, https://github.com/LiJinxin/cos-comparison.git
Project-URL: Documentation, https://cos-comparison.readthedocs.io/
Keywords: cosine similarity,local comparison,AGI,feature extraction,edge detection,template matching
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Science/Research
Classifier: Intended Audience :: Developers
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.8
Classifier: Programming Language :: Python :: 3.9
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Programming Language :: Python :: 3.14
Classifier: Programming Language :: C
Classifier: Operating System :: OS Independent
Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
Classifier: Topic :: Scientific/Engineering :: Image Processing
Requires-Python: >=3.8
Description-Content-Type: text/markdown
License-File: LICENSE.txt
Provides-Extra: numpy
Requires-Dist: numpy>=1.20; extra == "numpy"
Provides-Extra: test
Requires-Dist: pytest>=7.0; extra == "test"
Requires-Dist: pillow>=9.0; extra == "test"
Dynamic: license-file

# Cos Comparison

[!\[PyPI version](https://badge.fury.io/py/cos-comparison.svg)](https://pypi.org/project/cos-comparison/)
[!\[Python 3.8+](https://img.shields.io/badge/python-3.8+-blue.svg)](https://www.python.org/downloads/)
[!\[License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)

**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**:

```python
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

```bash
pip install cos-comparison
```

To install with NumPy acceleration (optional):

```bash
pip install cos-comparison\[numpy]
```

\---

## Quick Start

### 1D – find similar segments (passive mode)

```python
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)

```python
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

```python
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

```python
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

```python
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

```python
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

```bash
# 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

```bash
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

```bash
# 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](https://pypi.org/project/cos-comparison/) for details.

