Metadata-Version: 2.4
Name: vinculum-f
Version: 0.1.0
Summary: High-performance Discrete Fréchet Distance implementation for trajectory analysis.
Author-email: Vecture Laboratories <engineering@vecture.de>
License: Vecture-1.0
Project-URL: Homepage, https://www.vecture.de
Project-URL: Bug Tracker, https://github.com/VectureLaboratories/vinculum-f/issues
Project-URL: Repository, https://github.com/VectureLaboratories/vinculum-f
Classifier: Programming Language :: Python :: 3
Classifier: License :: Other/Proprietary License
Classifier: Operating System :: OS Independent
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Science/Research
Classifier: Topic :: Scientific/Engineering :: Mathematics
Requires-Python: >=3.9
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: numpy>=1.20.0
Requires-Dist: numba>=0.55.0
Dynamic: license-file

# VINCULUM-F

[VECTURE ENGINEERING SOLUTION]
[CLASSIFICATION: OMNICRON-1]
[STATUS: OPERATIONAL]

**VINCULUM-F** is a high-performance computational engine designed for the precise analysis of trajectory divergence. It implements advanced geometric algorithms to calculate the convergence leash between multidimensional paths, optimized for high-throughput environments through LLVM-based JIT compilation.

## 1. OBJECTIVE

The primary objective of VINCULUM-F is to quantify the similarity between two polygonal chains (trajectories) in $d$-dimensional space. Unlike simple Euclidean distance metrics between point clouds, VINCULUM-F accounts for the **ordering**, **direction**, and **temporal continuity** of the paths.

## 2. SCIENTIFIC BACKGROUND

### 2.1 Discrete Fréchet Distance
The Fréchet distance is a measure of similarity between curves that takes into account the location and ordering of the points along the curves. It is often described via the "Dog and Leash" metaphor: a person walks along one curve and a dog walks along the other. Both can vary their speeds, but neither can move backwards. The Fréchet distance is the length of the shortest leash sufficient for both to traverse their respective paths from start to finish.

In the **Discrete** variant implemented here, we consider only the vertices of the polygonal chains, which simplifies the continuous problem into a combinatorial optimization task over a coupling sequence.

### 2.2 Dynamic Time Warping (DTW)
DTW is an algorithm for measuring similarity between two temporal sequences which may vary in speed. It finds an optimal alignment between the sequences by "warping" the time axis to minimize the cumulative distance between matched points.

## 3. MATHEMATICAL FOUNDATIONS

### 3.1 Discrete Fréchet Recurrence
Given two trajectories $P = (p_1, \dots, p_n)$ and $Q = (q_1, \dots, q_m)$, the Discrete Fréchet Distance $d_{dF}(P, Q)$ is computed using the following dynamic programming recurrence:

$$L(i, j) = \max \left( d(p_i, q_j), \min(L(i-1, j), L(i, j-1), L(i-1, j-1)) \right)$$

Where:
- $d(p_i, q_j)$ is the Euclidean distance between points.
- $L(1, 1) = d(p_1, q_1)$.
- $L(i, j) = \infty$ for $i < 1$ or $j < 1$.

### 3.2 Dynamic Time Warping Recurrence
The cumulative DTW distance $D(P, Q)$ is defined as:

$$D(i, j) = d(p_i, q_j) + \min(D(i-1, j), D(i, j-1), D(i-1, j-1))$$

Where:
- $D(1, 1) = d(p_1, q_1)$.
- $D(i, j) = \infty$ for $i < 1$ or $j < 1$.

## 4. ARCHITECTURE & IMPLEMENTATION

### 4.1 Computational Acceleration
The core algorithms are implemented using **Numba**, an LLVM-based Just-In-Time (JIT) compiler. This allows Python-level logic to execute at near-native C/C++ speeds by compiling mathematical bottlenecks into machine code at runtime.

### 4.2 Space Complexity Optimization: $O(\min(n, m))$
Traditional DP implementations require an $O(nm)$ matrix to store intermediate states. VINCULUM-F employs a **rolling-vector optimization**. By observing that the state at $(i, j)$ only depends on the previous row and the immediate previous element of the current row, we reduce the spatial requirement from $O(nm)$ to $O(\min(n, m))$.

### 4.3 Memory Efficiency
- **Contiguous Layouts**: Inputs are automatically coerced into C-contiguous `float64` arrays to maximize CPU cache hit rates.
- **Allocation Minimization**: The Euclidean distance calculation is unrolled into an explicit loop to prevent the creation of intermediate temporary arrays during JIT execution.

## 5. INSTALLATION

```bash
pip install numpy numba
pip install .
```

## 6. OPERATIONAL USAGE

### 6.1 Discrete Fréchet Distance
```python
import numpy as np
from vinculum_f import frechet_distance

# Define trajectories as (N, D) arrays
path_a = np.array([[0,0], [1,1], [2,0]], dtype=np.float64)
path_b = np.array([[0,1], [1,2], [2,1]], dtype=np.float64)

leash_length = frechet_distance(path_a, path_b)
```

### 6.2 Dynamic Time Warping
```python
from vinculum_f import dynamic_time_warping

warping_cost = dynamic_time_warping(path_a, path_b)
```

## 7. TECHNICAL SPECIFICATIONS

- **Temporal Complexity**: $O(nm)$
- **Spatial Complexity**: $O(\min(n, m))$
- **Precision**: 64-bit Floating Point (IEEE 754)
- **Engine**: Numba-Accelerated LLVM JIT

---

*Optimal output achieved. Remain compliant.*
