highdimensionsmap 0.1.0__tar.gz → 0.2.2__tar.gz

highdimensionsmap-0.2.2/PKG-INFO

@@ -0,0 +1,103 @@
+Metadata-Version: 2.4
+Name: highdimensionsmap
+Version: 0.2.2
+Summary: High Dimensions Map: lightweight non-linear geometric scanning and phase-orbit indexing
+Author: Marta Reinhardt
+License-Expression: Apache-2.0
+Keywords: geometry,high-dimensions,embeddings,manifold-learning,kinematics,spectral
+Requires-Python: >=3.8
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: numpy>=1.20.0
+Requires-Dist: fastapi>=0.110.0
+Requires-Dist: uvicorn>=0.30.0
+Requires-Dist: scipy>=1.7.0
+Provides-Extra: test
+Requires-Dist: pytest>=7.0; extra == "test"
+Requires-Dist: httpx>=0.24; extra == "test"
+Dynamic: license-file
+
+
+# High Dimensions Map (HDM) 📐
+
+<p align="center">
+  <b>PT:</b> Biblioteca Python para projeção ortogonal analítica e compressão adaptativa de vetores via DCT-II.<br>
+  <b>EN:</b> Python library for analytical orthogonal projection and adaptive vector compression using DCT-II.
+</p>
+
+<p align="center">
+  <img src="https://img.shields.io/badge/Version-0.2.2-blue?style=flat-square" alt="Version">
+  <img src="https://img.shields.io/badge/Python-3.9+-blue?style=flat-square" alt="Python">
+  <img src="https://img.shields.io/badge/Status-Active%20Development-orange?style=flat-square" alt="Status">
+  <img src="https://img.shields.io/badge/License-Apache-green?style=flat-square" alt="License">
+</p>
+
+---
+
+## 🇧🇷 Português
+
+### Visão Geral
+O **HDM (High Dimensions Map)** é uma biblioteca focada na otimização, redução dimensional e compressão adaptativa de vetores em espaços de alta dimensão. 
+
+Ao contrário de métodos baseados em aprendizado iterativo ou matrizes de covariância (como PCA), o HDM utiliza a **Transformada Discreta de Cosseno Tipo II (DCT-II)** de forma analítica e determinística (*training-free*), permitindo processamento em lote em tempo real com preservação garantida de energia.
+
+### Principais Recursos
+- **`HDMCompressor` (Compressão Adaptativa):** Reduz a dimensão de vetores ordenando os coeficientes por magnitude decrescente e cortando no limiar exato de energia acumulada (`target_energy`).
+- **Sem Necessidade de Treino (*Training-Free*):** Funciona vetor por vetor ou em lotes sem requerer dados de ajuste prévio.
+- **Processamento Vetorizado:** Algoritmo implementado em C/NumPy nativo, capaz de processar 10.000 vetores de 1.000 dimensões em ~1.7 segundos.
+
+### Exemplo de Uso Prático
+
+```python
+import numpy as np
+from highdimensionmap import HDMCompressor
+
+# Matriz de 1.000 vetores de 100 dimensões
+X = np.random.randn(1000, 100)
+
+# Instancia o compressor para reter 99.9% da energia do sinal
+compressor = HDMCompressor(target_energy=0.999)
+
+# Executa a transformação adaptativa
+X_rec, k_componentes, tempo_ms = compressor.fit_transform(X)
+
+print(f"Tempo de execução: {tempo_ms:.2f} ms")
+print(f"Média de dimensões retidas: {np.mean(k_componentes):.1f} / {X.shape[1]}")
+```
+# 🇬🇧 English
+## Overview
+**HDM (High Dimensions Map) is a Python library focused on optimization**, dimensional reduction, and adaptive compression of high-dimensional vectors.
+Unlike methods relying on iterative learning or covariance matrices (such as PCA), HDM uses the Discrete Cosine Transform Type II (DCT-II) analytically and deterministically (training-free), enabling real-time batch processing with guaranteed energy preservation.
+Key Features
+***HDMCompressor (Adaptive Compression): Reduces vector dimensionality by sorting coefficients by descending magnitude and truncating at the exact threshold of cumulative energy (target_energy)."**
+**Training-Free: Operates vector-by-vector or in batches without requiring prior calibration data.**
+**Vectorized Performance: Core algorithm implemented natively using NumPy/SciPy, capable of processing 10,000 1,000-dimensional vectors in ~1.7 seconds.**
+Quickstart Example
+
+```
+import numpy as np
+from highdimensionmap import HDMCompressor
+
+# Matrix with 1,000 vectors of 100 dimensions
+X = np.random.randn(1000, 100)
+
+# Initialize compressor with 99.9% target energy threshold
+compressor = HDMCompressor(target_energy=0.999)
+
+# Execute adaptive transformation
+X_rec, k_components, time_ms = compressor.fit_transform(X)
+
+print(f"Execution time: {time_ms:.2f} ms")
+print(f"Average dimensions retained: {np.mean(k_components):.1f} / {X.shape[1]}")
+
+```
+
+⚙️ Instalação / Installation
+# Clone o repositório / Clone the repository
+git clone [https://github.com/reinhardtmarta/hdm.git](https://github.com/reinhardtmarta/hdm.git)
+cd hdm
+
+# Instalação local em modo editável / Local editable installation
+pip install -e .
+
+

highdimensionsmap-0.2.2/README.md

@@ -0,0 +1,84 @@
+
+# High Dimensions Map (HDM) 📐
+
+<p align="center">
+  <b>PT:</b> Biblioteca Python para projeção ortogonal analítica e compressão adaptativa de vetores via DCT-II.<br>
+  <b>EN:</b> Python library for analytical orthogonal projection and adaptive vector compression using DCT-II.
+</p>
+
+<p align="center">
+  <img src="https://img.shields.io/badge/Version-0.2.2-blue?style=flat-square" alt="Version">
+  <img src="https://img.shields.io/badge/Python-3.9+-blue?style=flat-square" alt="Python">
+  <img src="https://img.shields.io/badge/Status-Active%20Development-orange?style=flat-square" alt="Status">
+  <img src="https://img.shields.io/badge/License-Apache-green?style=flat-square" alt="License">
+</p>
+
+---
+
+## 🇧🇷 Português
+
+### Visão Geral
+O **HDM (High Dimensions Map)** é uma biblioteca focada na otimização, redução dimensional e compressão adaptativa de vetores em espaços de alta dimensão. 
+
+Ao contrário de métodos baseados em aprendizado iterativo ou matrizes de covariância (como PCA), o HDM utiliza a **Transformada Discreta de Cosseno Tipo II (DCT-II)** de forma analítica e determinística (*training-free*), permitindo processamento em lote em tempo real com preservação garantida de energia.
+
+### Principais Recursos
+- **`HDMCompressor` (Compressão Adaptativa):** Reduz a dimensão de vetores ordenando os coeficientes por magnitude decrescente e cortando no limiar exato de energia acumulada (`target_energy`).
+- **Sem Necessidade de Treino (*Training-Free*):** Funciona vetor por vetor ou em lotes sem requerer dados de ajuste prévio.
+- **Processamento Vetorizado:** Algoritmo implementado em C/NumPy nativo, capaz de processar 10.000 vetores de 1.000 dimensões em ~1.7 segundos.
+
+### Exemplo de Uso Prático
+
+```python
+import numpy as np
+from highdimensionmap import HDMCompressor
+
+# Matriz de 1.000 vetores de 100 dimensões
+X = np.random.randn(1000, 100)
+
+# Instancia o compressor para reter 99.9% da energia do sinal
+compressor = HDMCompressor(target_energy=0.999)
+
+# Executa a transformação adaptativa
+X_rec, k_componentes, tempo_ms = compressor.fit_transform(X)
+
+print(f"Tempo de execução: {tempo_ms:.2f} ms")
+print(f"Média de dimensões retidas: {np.mean(k_componentes):.1f} / {X.shape[1]}")
+```
+# 🇬🇧 English
+## Overview
+**HDM (High Dimensions Map) is a Python library focused on optimization**, dimensional reduction, and adaptive compression of high-dimensional vectors.
+Unlike methods relying on iterative learning or covariance matrices (such as PCA), HDM uses the Discrete Cosine Transform Type II (DCT-II) analytically and deterministically (training-free), enabling real-time batch processing with guaranteed energy preservation.
+Key Features
+***HDMCompressor (Adaptive Compression): Reduces vector dimensionality by sorting coefficients by descending magnitude and truncating at the exact threshold of cumulative energy (target_energy)."**
+**Training-Free: Operates vector-by-vector or in batches without requiring prior calibration data.**
+**Vectorized Performance: Core algorithm implemented natively using NumPy/SciPy, capable of processing 10,000 1,000-dimensional vectors in ~1.7 seconds.**
+Quickstart Example
+
+```
+import numpy as np
+from highdimensionmap import HDMCompressor
+
+# Matrix with 1,000 vectors of 100 dimensions
+X = np.random.randn(1000, 100)
+
+# Initialize compressor with 99.9% target energy threshold
+compressor = HDMCompressor(target_energy=0.999)
+
+# Execute adaptive transformation
+X_rec, k_components, time_ms = compressor.fit_transform(X)
+
+print(f"Execution time: {time_ms:.2f} ms")
+print(f"Average dimensions retained: {np.mean(k_components):.1f} / {X.shape[1]}")
+
+```
+
+⚙️ Instalação / Installation
+# Clone o repositório / Clone the repository
+git clone [https://github.com/reinhardtmarta/hdm.git](https://github.com/reinhardtmarta/hdm.git)
+cd hdm
+
+# Instalação local em modo editável / Local editable installation
+pip install -e .
+
+

highdimensionsmap-0.2.2/highdimensionsmap/__init__.py

@@ -0,0 +1,17 @@
+from .scanner import HDMScanner
+from .kinematics import HDMKinematics
+from .tracker import RobustMotionTracker, RobustMotionTracker as MotionNoiseTracker
+from .api import app
+from .tensor import TrajectoryMotionTensor
+from .compressor import HDMCompressor
+
+__version__ = "0.2.2"
+__all__ = [
+    "HDMScanner", 
+    "HDMKinematics", 
+    "MotionNoiseTracker", 
+    "RobustMotionTracker", 
+    "app", 
+    "TrajectoryMotionTensor",
+    "HDMCompressor"
+]

{highdimensionsmap-0.1.0 → highdimensionsmap-0.2.2}/highdimensionsmap/api.py

@@ -28,22 +28,31 @@ def healthcheck():
 @app.post("/transform")
 def transform_endpoint(payload: TransformRequest):
     try:
-        values = np.asarray(payload.input, dtype=float)
+        values = np.asarray(payload.input, dtype=np.float64)
     except ValueError as exc:
         raise HTTPException(status_code=400, detail="'input' precisa ser numérico.") from exc
 
     if values.ndim not in (1, 2):
         raise HTTPException(status_code=400, detail="'input' deve ser um vetor ou uma matriz 2D.")
 
+    was_1d = values.ndim == 1
     signature = scanner.transform(values)
-    return {"signature": np.asarray(signature).tolist()}
+    sig_array = np.asarray(signature, dtype=np.float64)
+
+    # Garante que a estrutura dimensional da resposta corresponda à entrada
+    if was_1d and sig_array.ndim > 1:
+        sig_array = sig_array[0]
+    elif not was_1d and sig_array.ndim == 1:
+        sig_array = sig_array.reshape(1, -1)
+
+    return {"signature": sig_array.tolist()}
 
 
 @app.post("/query")
 def query_endpoint(payload: QueryRequest):
     try:
-        dataset = np.asarray(payload.dataset, dtype=float)
-        query = np.asarray(payload.query, dtype=float)
+        dataset = np.asarray(payload.dataset, dtype=np.float64)
+        query = np.asarray(payload.query, dtype=np.float64)
     except ValueError as exc:
         raise HTTPException(status_code=400, detail="'dataset' e 'query' precisam ser numéricos.") from exc
 

highdimensionsmap-0.2.2/highdimensionsmap/compressor.py

@@ -0,0 +1,202 @@
+import time
+from typing import Tuple, Union
+import numpy as np
+from scipy.fftpack import dct, idct
+
+# Importações condicionais para frameworks de terceiros (não força dependência rígida)
+try:
+    import pandas as pd
+    HAS_PANDAS = True
+except ImportError:
+    HAS_PANDAS = False
+
+try:
+    import torch
+    HAS_TORCH = True
+except ImportError:
+    HAS_TORCH = False
+
+
+class HDMCompressor:
+    """Compressor e redutor de dimensionalidade adaptativo baseado na DCT-II.
+    
+    Seleciona coeficientes por ordem decrescente de magnitude até atingir
+    o limiar de energia acumulada especificado (target_energy).
+    """
+
+    def __init__(self, target_energy: float = 0.999):
+        if not (isinstance(target_energy, (float, int)) and 0.0 < target_energy <= 1.0):
+            raise ValueError("target_energy deve ser um numero entre 0.0 (exclusivo) e 1.0 (inclusivo).")
+        self.target_energy = float(target_energy)
+
+    def _convert_input(self, X: Union[np.ndarray, "pd.DataFrame", "pd.Series", "torch.Tensor"]) -> Tuple[np.ndarray, str]:
+        """Converte entradas diversas (Pandas, PyTorch) para numpy.ndarray com seguranca."""
+        original_type = "numpy"
+
+        if HAS_TORCH and isinstance(X, torch.Tensor):
+            original_type = "torch"
+            X = X.detach().cpu().numpy()
+        elif HAS_PANDAS and isinstance(X, (pd.DataFrame, pd.Series)):
+            original_type = "pandas"
+            X = X.to_numpy()
+
+        if not isinstance(X, np.ndarray):
+            X = np.asarray(X)
+
+        return X, original_type
+
+    def fit_transform(
+        self, X: Union[np.ndarray, "pd.DataFrame", "pd.Series", "torch.Tensor"]
+    ) -> Tuple[np.ndarray, np.ndarray, float]:
+        """Aplica a DCT-II e projeta os vetores com base na energia acumulada.
+
+        Trata casos de borda como NaN, Inf e vetores nulos.
+
+        Parâmetros:
+            X: Matriz 2D (n_amostras, n_dimensoes) ou vetor 1D. Aceita NumPy, Pandas e PyTorch.
+
+        Retorna:
+            tuple: (X_reconstruido, k_por_linha, tempo_execucao_ms)
+        """
+        t0 = time.perf_counter()
+
+        # 1. Normalização de tipo de entrada
+        X_np, original_type = self._convert_input(X)
+
+        # 2. Validação de formato (dimensionalidade)
+        if X_np.ndim not in (1, 2):
+            raise ValueError(f"Entrada invalida. Esperado array 1D ou 2D, mas recebido ndim={X_np.ndim}.")
+
+        is_1d = X_np.ndim == 1
+        if is_1d:
+            X_np = X_np.reshape(1, -1)
+
+        # 3. Tratamento de NaN e Inf
+        if not np.isfinite(X_np).all():
+            raise ValueError("A matriz de entrada contem valores invalidos (NaN ou Inf). Limpe os dados antes de processar.")
+
+        # 4. Processamento da DCT-II nas linhas (axis=1)
+        coefs = dct(X_np, type=2, norm="ortho", axis=1)
+
+        # 5. Ordenação por magnitude decrescente por linha
+        abs_coefs = np.abs(coefs)
+        sorted_indices = np.argsort(-abs_coefs, axis=1)
+
+        rows = np.arange(X_np.shape[0])[:, None]
+        sorted_sq_coefs = coefs[rows, sorted_indices] ** 2
+
+        # 6. Cálculo da Energia Total por linha (Tratamento para Vetores Nulos)
+        total_energy = np.sum(coefs**2, axis=1, keepdims=True)
+        null_vectors_mask = total_energy.squeeze(axis=1) == 0.0
+
+        # Evita divisão por zero em vetores nulos
+        safe_total_energy = np.where(total_energy == 0.0, 1.0, total_energy)
+        cum_energy = np.cumsum(sorted_sq_coefs, axis=1) / safe_total_energy
+
+        # 7. Determinação adaptativa do parâmetro K por linha
+        mask_energy = cum_energy >= self.target_energy
+        k_per_row = np.argmax(mask_energy, axis=1) + 1
+
+        # Trata linhas que não atingem o limiar exacto ou são nulas
+        no_reach = ~np.any(mask_energy, axis=1)
+        k_per_row[no_reach] = X_np.shape[1]
+        k_per_row[null_vectors_mask] = 1  # Vetores nulos exigem apenas 1 componente (zerado)
+
+        # 8. Filtro dos coeficientes fora do Top-K
+        col_indices = np.arange(X_np.shape[1])[None, :]
+        mask_top_k = col_indices < k_per_row[:, None]
+
+        filtered_coefs_sorted = np.zeros_like(coefs)
+        filtered_coefs_sorted[mask_top_k] = coefs[rows, sorted_indices][mask_top_k]
+
+        # 9. Reordenação para o espaço de frequência original
+        filtered_coefs = np.zeros_like(coefs)
+        filtered_coefs[rows, sorted_indices] = filtered_coefs_sorted
+
+        # 10. Reconstrução vetorial via IDCT-II
+        X_reconstructed = idct(filtered_coefs, type=2, norm="ortho", axis=1)
+
+        t1 = time.perf_counter()
+        exec_time_ms = (t1 - t0) * 1000.0
+
+        if is_1d:
+            return X_reconstructed.squeeze(0), k_per_row[0], exec_time_ms
+
+        return X_reconstructed, k_per_row, exec_time_ms
+
+    def compress(
+        self, X: Union[np.ndarray, "pd.DataFrame", "pd.Series", "torch.Tensor"]
+    ) -> dict:
+        """Comprime a matriz/vetor retornando apenas os K coeficientes relevantes e seus indices.
+
+        Retorna:
+            dict: {
+                'values': list de np.ndarray (coeficientes mantidos por linha),
+                'indices': list de np.ndarray (indices originais dos coeficientes),
+                'shape': tuple (formato original da matriz/vetor),
+                'is_1d': bool
+            }
+        """
+        X_np, _ = self._convert_input(X)
+        is_1d = X_np.ndim == 1
+        if is_1d:
+            X_np = X_np.reshape(1, -1)
+
+        if not np.isfinite(X_np).all():
+            raise ValueError("A matriz de entrada contem valores invalidos (NaN ou Inf).")
+
+        # 1. DCT-II e ordenacao por magnitude
+        coefs = dct(X_np, type=2, norm="ortho", axis=1)
+        abs_coefs = np.abs(coefs)
+        sorted_indices = np.argsort(-abs_coefs, axis=1)
+
+        rows = np.arange(X_np.shape[0])[:, None]
+        sorted_sq_coefs = coefs[rows, sorted_indices] ** 2
+
+        # 2. Determinar K por linha com protecao para vetores nulos
+        total_energy = np.sum(coefs**2, axis=1, keepdims=True)
+        null_mask = total_energy.squeeze(axis=1) == 0.0
+        safe_total = np.where(total_energy == 0.0, 1.0, total_energy)
+        cum_energy = np.cumsum(sorted_sq_coefs, axis=1) / safe_total
+
+        mask_energy = cum_energy >= self.target_energy
+        k_per_row = np.argmax(mask_energy, axis=1) + 1
+        k_per_row[~np.any(mask_energy, axis=1)] = X_np.shape[1]
+        k_per_row[null_mask] = 1
+
+        # 3. Extrair apenas os K coeficientes e indices por linha
+        compressed_values = []
+        compressed_indices = []
+
+        for i in range(X_np.shape[0]):
+            k = k_per_row[i]
+            idx = sorted_indices[i, :k]
+            val = coefs[i, idx]
+            compressed_indices.append(idx.astype(np.int32))
+            compressed_values.append(val.astype(np.float32))
+
+        return {
+            "values": compressed_values,
+            "indices": compressed_indices,
+            "shape": X_np.shape,
+            "is_1d": is_1d,
+        }
+
+    def decompress(self, compressed_data: dict) -> np.ndarray:
+        """Reconstrui a matriz/vetor original a partir do dicionario comprimido."""
+        values = compressed_data["values"]
+        indices = compressed_data["indices"]
+        shape = compressed_data["shape"]
+        is_1d = compressed_data["is_1d"]
+
+        coefs = np.zeros(shape, dtype=np.float32)
+
+        for i in range(shape[0]):
+            coefs[i, indices[i]] = values[i]
+
+        X_reconstructed = idct(coefs, type=2, norm="ortho", axis=1)
+
+        if is_1d:
+            return X_reconstructed.squeeze(0)
+        return X_reconstructed
+        

highdimensionsmap-0.2.2/highdimensionsmap/core.py

@@ -0,0 +1,19 @@
+from .scanner import HDMScanner
+from .kinematics import HDMKinematics
+from .tracker import RobustMotionTracker, RobustMotionTracker as MotionNoiseTracker
+from .core import hdm
+from .api import app
+from .tensor import TrajectoryMotionTensor
+from .compressor import HDMCompressor
+
+__version__ = "0.2.2"
+__all__ = [
+    "HDMScanner", 
+    "HDMKinematics", 
+    "MotionNoiseTracker", 
+    "RobustMotionTracker", 
+    "hdm", 
+    "app", 
+    "TrajectoryMotionTensor",
+    "HDMCompressor"
+]

highdimensionsmap-0.2.2/highdimensionsmap/scanner.py

@@ -0,0 +1,135 @@
+import numpy as np
+
+class HDMScanner:
+    """
+    Scanner dimensional determinístico com suporte a projeções ortogonais
+    adaptativas (SVD/PCA), padronização de feições e modos espectrais.
+    """
+
+    def __init__(self, input_dim=512, latent_modes=32, method="adaptive", scale=True, seed=42, steps=None):
+        if int(input_dim) < 1:
+            raise ValueError("input_dim precisa ser >= 1.")
+        if int(latent_modes) < 1:
+            raise ValueError("latent_modes precisa ser >= 1.")
+        if method not in ("adaptive", "spectral", "random"):
+            raise ValueError("method deve ser 'adaptive', 'spectral' ou 'random'.")
+        self.input_dim = int(input_dim)
+        self.latent_modes = int(latent_modes)
+        self.method = method
+        self.scale = scale
+        self.seed = seed
+        self.steps = steps  # mantido por compatibilidade com exemplos antigos
+        self.projection_matrix = None
+        self.mean_ = None
+        self.std_ = None
+
+        if self.method == "spectral":
+            self.projection_matrix = self._build_dct_basis(self.latent_modes, self.input_dim)
+        elif self.method == "random":
+            self.projection_matrix = self._build_random_basis(self.latent_modes, self.input_dim)
+
+    def _build_dct_basis(self, n_modes, d):
+        n = np.arange(d, dtype=np.float64)
+        basis = np.zeros((n_modes, d), dtype=np.float64)
+        for k in range(n_modes):
+            if k == 0:
+                basis[k, :] = 1.0 / np.sqrt(d)
+            else:
+                basis[k, :] = np.sqrt(2.0 / d) * np.cos((np.pi * (2.0 * n + 1.0) * k) / (2.0 * d))
+        return basis
+
+    def _build_random_basis(self, n_modes, d):
+        rng = np.random.default_rng(self.seed)
+        gaussian_matrix = rng.standard_normal((d, n_modes))
+        q, _ = np.linalg.qr(gaussian_matrix)
+        return q.T
+
+    def generate_dataset(self, n_samples=1, noise=0.05, drift=0.1):
+        """Gera dados sintéticos reproduzíveis para testes e exemplos.
+
+        Cada linha é uma amostra. ``noise`` controla o ruído gaussiano;
+        ``drift`` adiciona uma tendência gradual ao longo das amostras.
+        """
+        if int(n_samples) < 1:
+            raise ValueError("n_samples precisa ser >= 1.")
+        if noise < 0 or drift < 0:
+            raise ValueError("noise e drift precisam ser >= 0.")
+        rng = np.random.default_rng(self.seed)
+        data = rng.standard_normal((int(n_samples), self.input_dim))
+        if drift:
+            trend = np.linspace(0.0, float(drift), int(n_samples))[:, None]
+            direction = np.ones((1, self.input_dim), dtype=np.float64) / np.sqrt(self.input_dim)
+            data = data + trend * direction
+        if noise:
+            data = data + rng.normal(0.0, float(noise), size=data.shape)
+        return data
+
+    def fit(self, X):
+        X = np.asarray(X, dtype=np.float64)
+        X = np.atleast_2d(X)
+        if X.ndim != 2 or X.shape[0] == 0 or X.shape[1] == 0:
+            raise ValueError("X precisa ser uma matriz 2D não vazia.")
+        if not np.isfinite(X).all():
+            raise ValueError("X deve conter apenas valores finitos.")
+        self.input_dim = X.shape[1]
+
+        # Uma única amostra não permite estimar componentes principais.
+        # Use uma base ortogonal determinística sem centralizar pela amostra,
+        # pois isso zeraria completamente a assinatura.
+        if X.shape[0] == 1:
+            self.mean_ = np.zeros(self.input_dim, dtype=np.float64)
+            self.std_ = np.ones(self.input_dim, dtype=np.float64)
+            self.projection_matrix = self._build_random_basis(
+                min(self.latent_modes, self.input_dim), self.input_dim
+            )
+            return self
+
+        self.mean_ = np.mean(X, axis=0)
+        X_proc = X - self.mean_
+
+        if self.scale:
+            self.std_ = np.std(X_proc, axis=0)
+            self.std_[self.std_ == 0.0] = 1.0
+            X_proc = X_proc / self.std_
+        else:
+            self.std_ = np.ones(self.input_dim, dtype=np.float64)
+
+        _, _, Vh = np.linalg.svd(X_proc, full_matrices=False)
+        self.projection_matrix = Vh[: min(self.latent_modes, Vh.shape[0]), :]
+        return self
+
+    def transform(self, X, normalize=False):
+        X = np.asarray(X, dtype=np.float64)
+        X = np.atleast_2d(X)
+
+        if X.shape[1] != self.input_dim or self.projection_matrix is None:
+            self.fit(X)
+
+        X_proc = X - self.mean_ if self.mean_ is not None else X
+        if self.scale and self.std_ is not None:
+            X_proc = X_proc / self.std_
+
+        signatures = np.dot(X_proc, self.projection_matrix.T)
+
+        if normalize:
+            norms = np.linalg.norm(signatures, axis=1, keepdims=True)
+            norms[norms == 0] = 1.0
+            signatures = signatures / norms
+
+        return signatures if signatures.shape[0] > 1 else signatures[0]
+
+    def query(self, dataset, query_vector, k=5):
+        dataset_array = np.asarray(dataset, dtype=np.float64)
+        if dataset_array.ndim == 1:
+            dataset_array = dataset_array.reshape(1, -1)
+
+        query_sig = self.transform(query_vector)
+
+        if dataset_array.shape[1] != query_sig.shape[0]:
+            dataset_signatures = self.transform(dataset_array)
+        else:
+            dataset_signatures = dataset_array
+
+        distances = np.linalg.norm(dataset_signatures - query_sig, axis=1)
+        nearest = np.argsort(distances)[:k]
+        return nearest, distances[nearest]

highdimensionsmap-0.2.2/highdimensionsmap/tensor.py

@@ -0,0 +1,48 @@
+import numpy as np
+
+class TrajectoryMotionTensor:
+    """
+    Tensor de Trajetória no Espaço de Estados para Alta Dimensão.
+    Mede a coerência angular contínua e detecta anomalias dinâmicas.
+    """
+    def __init__(self, scanner=None):
+        self.scanner = scanner
+
+    def compute_coherence(self, trajectory_matrix, step_lag=1):
+        matriz = np.asarray(trajectory_matrix, dtype=np.float64)
+        if matriz.ndim != 2:
+            raise ValueError("A matriz de trajetória precisa ter 2 dimensões (N_passos, Dimensão).")
+            
+        if matriz.shape[0] <= step_lag:
+            return {
+                "global_coherence": 0.0,
+                "instantaneous_profile": np.array([]),
+                "drift_instability": np.array([]),
+                "is_structured": False
+            }
+
+        x0 = matriz[:-step_lag]
+        x1 = matriz[step_lag:]
+        
+        # Produto escalar normalizado
+        dot_products = np.sum(x0 * x1, axis=1)
+        normas = np.linalg.norm(x0, axis=1) * np.linalg.norm(x1, axis=1)
+        
+        # Evita divisão por zero/valores insignificantes
+        valid_mask = normas > 1e-8
+        instantaneous_coherence = np.ones(len(dot_products))
+        instantaneous_coherence[valid_mask] = dot_products[valid_mask] / normas[valid_mask]
+        
+        # Garante intervalo [-1.0, 1.0]
+        instantaneous_coherence = np.clip(instantaneous_coherence, -1.0, 1.0)
+        drift_instability = 1.0 - instantaneous_coherence
+        
+        global_coherence = float(np.median(instantaneous_coherence)) # Uso de mediana para robustez a outliers
+        
+        return {
+            "global_coherence": global_coherence,
+            "instantaneous_profile": instantaneous_coherence,
+            "drift_instability": drift_instability,
+            "is_structured": bool(global_coherence > 0.3) # Limiar adaptativo
+        }
+