cos-comparison 0.2.0

Local similarity comparison for feature extraction – biologically inspired, zero‑training edge/pattern detection, now with cognitive architecture layers.

Cos Comparison

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} ]

• Spurt for 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 + optional NumPy / C acceleration

---

Core Principles

1. Information is generated by local comparison – edges, textures, patterns arise from comparing neighbouring regions.
2. Centre‑surround antagonism – two sliding windows 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 (detects boundaries without templates) and active (template matching with 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 – same algorithm works on 1D, 2D, 3D, 4D and beyond.
7. Zero training, zero labels – deterministic computation, ready to use.
8. Full determinism and interpretability – every output has a clear geometric meaning.
9. Modular, pluggable architecture – pure Python reference, NumPy vectorised, C high‑performance backends with automatic fallback.

---

⚠️ Important Note for Version 0.2.0

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

To use the library, please import from cos_comparison.core:

from cos_comparison import core as cc

Old code using import cos_comparison as cc will not work with 0.2.0.
Update your imports accordingly.

---

Installation

pip install cos-comparison

To install with NumPy acceleration:

pip install cos-comparison[numpy]

---

Quick Start

1D – find similar segments (passive mode)

from cos_comparison import core as cc

data = [1.0, 2.0, 3.0, 4.0, 5.0]
result = cc.cos_comparison_passive_1d(
    data,
    window_size=(2,),
    step=(1,),
    d=(1,)
)
print(result)

2D – edge detection (passive mode)

image = [
    [1, 1, 0, 0],
    [1, 1, 0, 0],
    [0, 0, 1, 1],
    [0, 0, 1, 1]
]
edges = cc.cos_comparison_passive_2d(
    image,
    window_size=(2, 2),
    step=(1, 1),
    d=(1, 0)
)
print(edges)

Active mode – template matching

data = [1.0, 2.0, 3.0, 4.0, 5.0]
kernel = [1.0, 0.0]
result = cc.cos_comparison_active_1d(
    data,
    kernel=kernel,
    step=(1,)
)
print(result)

Whole‑tensor cosine

a = [1, 2, 3]
b = [2, 3, 4]
sim = cc.cos_1d(a, b)
print(sim)

Using the recommended _cosmod similarity

result = cc.cos_comparison_passive_1d(
    data,
    window_size=(2,),
    step=(1,),
    d=(1,),
    algorithm=cc._cosmod
)

---

Optional Backends

The package automatically selects the fastest available backend:

Priority	Backend	Requirement
1	C	Compile cos_comparison_c/include/core.c
2	NumPy	pip install numpy
3	Pure Python	Works out of the box

You can force a specific backend via environment variable:

export COS_BACKEND=cos_comparison.core,cos_comparison_numpy

---

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=cc._cos) – works on arbitrarily nested lists
• execute_many(func, arg_iter, kwarg_iter) – batch execution (returns 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

---

License

MIT © 2025 Li Jinxin. See LICENSE for details.

##Other

I born in May 31 2008,and I am still a student. Because I have to perpare for a very important examination,I decide that I will not maintain the module untill June 9 2026.