Metadata-Version: 2.5
Name: hgfx
Version: 1.0.0
Summary: GPU-native Python/JAX toolbox for Hierarchical Gaussian Filters
Author: HGFX contributors
License: MIT
License-File: LICENSE
Requires-Python: >=3.11
Requires-Dist: jax>=0.4.30
Requires-Dist: numpy>=2.0
Provides-Extra: dev
Requires-Dist: hypothesis>=6; extra == 'dev'
Requires-Dist: matplotlib>=3.9; extra == 'dev'
Requires-Dist: mypy>=1.11; extra == 'dev'
Requires-Dist: pytest-cov>=5; extra == 'dev'
Requires-Dist: pytest>=8; extra == 'dev'
Requires-Dist: ruff>=0.6; extra == 'dev'
Provides-Extra: plot
Requires-Dist: matplotlib>=3.9; extra == 'plot'
Description-Content-Type: text/markdown

# HGFX

**HGFX — A GPU-Native Python Toolbox for Hierarchical Gaussian Filters**

HGFX is a Python/JAX reimplementation and extension framework for the Hierarchical Gaussian Filter (HGF). The v1.0 target is functional/scientific equivalence with the frozen MATLAB HGF Toolbox 8.2.0 reference while requiring no MATLAB runtime for users.

## Current status

HGFX is in final `1.0.0` promotion after the release candidate, independent review, remediation, and main-branch integration validation passed.

- M0–M17 are completed in their documented scopes.
- Historical M18 scientific failures remain preserved rather than retuned away.
- Exact shared MATLAB/HGFX limitations are tracked explicitly as scoped `REFERENCE_LIMITATION_MATCH` results, not scientific PASS claims.
- S9 CPU/backend is `PASS_CPU_BACKEND_EQUIVALENCE`.
- S9 physical NVIDIA GPU applicability passed on 2x Tesla T4; archived H100 results retain their original scope.
- M19 evidence freeze is complete.
- M20 candidate finalization passed as `PASS_M20_CANDIDATE`.
- The independent frontier review completed; its release-blocking H1/H2 findings were resolved without changing frozen scientific criteria.
- PR #29 was merged to `main` at `ffa84c616343714d7d384b0a21e6f8d73f7cb990`; main `HGFX Regression` run `35087865209` succeeded.
- Package and citation metadata are being promoted from `1.0.0rc1` to `1.0.0`; the exact final promotion revision must pass release checks before the final tag/release is recorded.

See `docs/planning/V1_RELEASE_GATE.md` and `docs/validation/V1_EVIDENCE_INDEX.md` for the live release state.

## Install

Python 3.11+ is required.

HGFX has not yet been formally published to PyPI as part of the v1 release process. Install from a source checkout:

```bash
python -m venv .venv
source .venv/bin/activate  # Windows PowerShell: .venv\Scripts\Activate.ps1
python -m pip install --upgrade pip
python -m pip install .
```

Development install:

```bash
python -m pip install -e '.[dev]'
pytest
```

After a future PyPI publication, the intended install command is `python -m pip install hgfx`.

MATLAB is a development-time reference oracle only; it is not a user runtime dependency.

## Quick start

```bash
python examples/quickstart.py
```

Or directly:

```python
import numpy as np
import hgfx

u = np.array([0, 1, 1, 0, 1, 0, 0, 1], dtype=float)
y = np.array([0, 1, 1, 0, 1, 0, 0, 1], dtype=float)

result = hgfx.fit_model(y, u)
print(result.optim.LME)
print(result.optim.BIC)
```

The public compatibility surface includes Python-first and MATLAB-style aliases such as `fit_model`/`fitModel`, `sim_model`/`simModel`, and `sample_model`/`sampleModel`.

User documentation:

- `docs/user/GETTING_STARTED.md` — minimal installation and first fit
- `docs/user/USER_GUIDE.md` — practical v1 guide for fitting, simulation, sampling, GPU use, migration from MATLAB, and reproducibility
- `docs/user/API.md` — public API surface
- `docs/user/MATLAB_DEMOS.md` — exact official MATLAB demo reproductions and cross-language parity evidence
- `examples/README.md` — runnable examples

## Official MATLAB demo reproductions

With the frozen reference submodule initialized:

```bash
git submodule update --init --recursive
python examples/matlab_demo_model_selection.py
python examples/matlab_demo_uhgf_ar1.py
```

The corresponding CI workflows regenerate the real MATLAB outputs and compare them with HGFX at frozen tolerances. See `docs/user/MATLAB_DEMOS.md` for exact results and evidence IDs.

## Scope

HGFX provides:

- HGF/eHGF/uHGF and specialized model implementations covered by the migration plan;
- MATLAB-compatible fit, simulation, sampling and statistical output surfaces in documented validated scopes;
- JAX-based fast CPU/GPU paths;
- batch and multi-GPU infrastructure;
- parameter/model recovery and validation tooling;
- explicit provenance for direct PASS, numerical/inferential equivalence and reference limitations.

Bitwise identity across hardware is not a general requirement. Acceptance is governed by the frozen equivalence policies and release gate; thresholds, seeds, datasets, starts, grids, model families and optimizers are not changed post-hoc to manufacture PASS results.

## Reference implementation

The frozen MATLAB toolbox is retained only as a validation oracle. The product runtime goal is:

```text
MATLAB dependency = 0
```

## Core project documents

- `docs/planning/V1_RELEASE_GATE.md`
- `docs/planning/M18_COMPLETION_PLAN.md`
- `docs/planning/ROADMAP.md`
- `docs/planning/MILESTONES.md`
- `docs/validation/MATLAB_TOOLBOX_VALIDATION_MATRIX.md`
- `docs/validation/MATLAB_EQUIVALENCE_POLICY.md`
- `docs/validation/MATLAB_REFERENCE_LIMITATIONS_POLICY.md`
- `docs/validation/V1_EVIDENCE_INDEX.md`

## License

HGFX project code is MIT licensed. Third-party material must retain its own provenance and licensing; see `THIRD_PARTY_NOTICES.md`.
