Metadata-Version: 2.4
Name: ohat-framework
Version: 1.2.0
Summary: Ô-HAT: 6-Dimensional Topological Noise Framework — phase-space operators (dH_curl, θ₁, χ_eff, H, Ô, D₁) + candidate D_fold
Author-email: "tygtDc, Deep Research" <nnrpmrmm@gmail.com>
License: CC-BY-4.0
Project-URL: Homepage, https://github.com/MMDR10/ohat-framework-mathematical-definition
Project-URL: Documentation, https://github.com/MMDR10/ohat-framework-mathematical-definition
Keywords: topological-noise,phase-space,fractal-dimension,box-counting,kakeya,geodesy,gps,plate-tectonics,orthogonality
Classifier: Programming Language :: Python :: 3
Classifier: License :: Other/Proprietary License
Classifier: Topic :: Scientific/Engineering :: Mathematics
Classifier: Topic :: Scientific/Engineering :: Physics
Requires-Python: >=3.8
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: numpy>=1.20
Dynamic: license-file

# Ô-HAT Framework

**6-Dimensional Topological Noise Framework** — phase-space operators for
structured-noise detection, with a candidate 7th dimension.

| | |
|---|---|
| **Author** | tygtDc, Deep Research (contact: nnrpmrmm@gmail.com) |
| **Spec** | Zenodo DOI: [10.5281/zenodo.21760992](https://doi.org/10.5281/zenodo.21760992) |
| **Repo** | [MMDR10/ohat-framework-mathematical-definition](https://github.com/MMDR10/ohat-framework-mathematical-definition) |
| **License** | CC-BY-4.0 |

---

## What it is

Ô-HAT is a family of topological operators that characterize *structured
noise* — residual fields that are neither pure noise nor smooth signal. It
was validated on plate-motion GPS residuals (NGL 8480 stations) and typhoon
vorticity fields, where it separates **core-condensed (aggregating)** from
**shell-dominant (releasing)** regimes.

The core vector is

```
Ô₆D = [dH_curl, θ₁, χ_eff, H, Ô, D₁]
```

| # | Operator | Meaning | Sign / scale |
|---|----------|---------|--------------|
| 1 | `dH_curl` | core–shell coupling difference | < 0 core-condensed |
| 2 | `θ₁` | principal geometric angle (PCA) | ~10° organized, ~55° noise |
| 3 | `χ_eff` | effective compressibility | high → geometric constraint |
| 4 | `H` (ΔH) | two-level helicity | ΔH = H_core − H_shell |
| 5 | `Ô` | positive/negative excursion ratio | > 2 continuous flow |
| 6 | `D₁` | fragmentation / cascade index | > 50 explosive |

The candidate 7th dimension `D_fold` measures the singularity-set
dimension difference (negative → folding / structure formation):

```
D_fold = d(S_θ) − d(S_θ^null)
```

## Install

```bash
pip install ohat-framework
```

## Quick start

```python
import numpy as np
from ohat import OHATEngine

rng = np.random.default_rng(0)
z1 = rng.normal(size=(20, 20))   # e.g. 850 hPa standardized vorticity
z2 = rng.normal(size=(20, 20))   # e.g. 200 hPa standardized vorticity

core = np.zeros((20, 20), bool); core[7:13, 7:13] = True
shell = ~core

engine = OHATEngine()
vec = engine.compute(z1, z2, core_mask=core, shell_mask=shell)
print(vec)   # {'dH_curl', 'theta_1', 'chi_eff', 'H', 'delta_H', 'O', 'D1'}
```

### Plate-GPS domain

```python
from ohat import OHATEngine

engine = OHATEngine()
result = engine.compute_plate_residual(
    dve, dvn,         # residual east/north velocity grids (Nx, Ny)
    lon2d, lat2d,     # coordinate grids (degrees)
    threshold="p90",  # D_fold singularity threshold
)
# result: 6D vector + 'D_fold' dict
```

## Operators reference

Each operator is importable directly:

```python
from ohat import dH_curl, theta_1, chi_eff, helicity, o_hat, d1
from ohat import d_fold, box_counting_dimension, singularity_set_dimension
```

## Tests

```bash
python -m pytest tests/ -v
```

16 tests covering sign conventions, noise baselines, box-counting
convergence (line → 1, grid → 2) and the D_fold random-null property.

## Citation

```bibtex
@misc{tygtDc2026ohat,
  author = {{tygtDc, Deep Research}},
  title  = {Ô-HAT: A 6-Dimensional Topological Noise Framework},
  year   = {2026},
  doi    = {10.5281/zenodo.21760992},
  url    = {https://doi.org/10.5281/zenodo.21760992}
}
```

## Status & caveats

- `dH_curl` has two estimators: continuous-field (core–shell mean
  difference) and discrete spatial-curl (plate GPS grid).
- `D_fold` is a *candidate* 7th dimension: validated on plate GPS
  (18 segments, 12/12 subduction negative) but **not** yet cross-domain
  validated (typhoon). Treat results accordingly.
- `θ₁` of a random noise field is *not* a statistical invariant — it is a
  single-draw PCA angle; use distributional comparisons across ensembles.
