Metadata-Version: 2.4
Name: conatt
Version: 0.1.0a3
Summary: Measure-aware attention for continuous, irregular, and constrained domains
Author: ConAtt Research Program
License-Expression: MIT
Keywords: attention,neural-ode,neural-operator,pde,irregular-grid
Classifier: Development Status :: 2 - Pre-Alpha
Classifier: Intended Audience :: Science/Research
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
Requires-Python: >=3.10
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: numpy>=2.0
Provides-Extra: dev
Requires-Dist: build>=1.2; extra == "dev"
Requires-Dist: pytest>=8; extra == "dev"
Provides-Extra: torch
Requires-Dist: torch>=2.5; extra == "torch"
Provides-Extra: benchmark
Requires-Dist: torch>=2.5; extra == "benchmark"
Requires-Dist: scikit-learn>=1.5; extra == "benchmark"
Requires-Dist: scipy>=1.12; extra == "benchmark"
Requires-Dist: pandas>=2.2; extra == "benchmark"
Dynamic: license-file

# ConAtt

ConAtt is an open-source PyTorch library for attention on continuous,
irregularly sampled, and constrained domains. It keeps ordinary attention as a
first-class case while adding explicit integration measures, geometric masks,
continuous-depth dynamics, neural-operator blocks, approximation certificates,
and evidence gates for fair model comparison.

The package is designed for reusable scientific and engineering work rather
than a single benchmark. Initial application targets include PDE surrogate
models, irregular time series, physical simulation, scientific sensing, and
spatiotemporal learning.

> Release status: `0.1.0a3` is a public alpha API, available from
> [PyPI](https://pypi.org/project/conatt/). Production stability is not yet
> guaranteed; scientific claims remain governed by the evidence gate below.

## Install

```bash
pip install conatt[torch]
```

From the pinned public release in Colab:

```bash
pip install "conatt[torch]==0.1.0a3"
```

## Continuous attention in three steps

```python
import torch
from conatt.torch_continuous import ContinuousAttentionOperator1D

coordinates = torch.tensor([[0.0], [0.03], [0.20], [0.74], [1.0]])
forcing = torch.randn(8, coordinates.shape[0], 1)

model = ContinuousAttentionOperator1D(
    input_channels=1, output_channels=1, width=64, heads=4, layers=4,
    use_measure=True,
)
prediction, attention_maps = model(forcing, coordinates)
```

The parameter-identical ablation is obtained with `use_measure=False`. This
makes the effect of continuous-domain normalization directly testable without
changing model capacity.

## Included capabilities

- NumPy and PyTorch scaled dot-product attention with positive measure weights;
- continuous 1-D operator model for irregular grids and variable resolutions;
- hybrid `ConAttOperator1D` coupling measure-aware attention with irregular
  Fourier/sine integral mixers and optional exact Dirichlet envelopes;
- `LatentConAttOperator1D` for measure-aware encode/process/decode between
  arbitrary observation points and a reusable continuous latent grid;
- `QuadratureSineOperator1D` and `GalerkinConAttOperator1D` for a stable
  irregular-grid Galerkin path plus an auditable native-attention correction;
- `KernelIntegralConAttOperator1D` with coordinate-only query/key geometry,
  nonlinear field values, and explicit key-domain quadrature;
- fixed-step Euler, midpoint, and RK4 integration for attention vector fields;
- causal and metric-radius structure masks;
- affine physical-constraint projection with residual certificate;
- retained-mass, spectral-tail, and finite-horizon propagation certificates;
- exact propagation-aware approximation-budget allocation;
- paired-seed statistics, fairness records, and immutable experiment storage;
- deterministic Poisson data generator and controlled killer tests.
- auditable FNO and DeepONet references for local baseline checks.

## Verify an installation

```bash
conatt verify
conatt benchmark-continuous --output continuous-killer-test.json
```

The controlled test isolates a known irregular-sampling failure. Its output is
deliberately blocked from becoming a publication claim. Learned-model claims
require real benchmarks, reproduced closest baselines, paired seeds, matched
budgets, negative controls, and immutable artifacts.

See [the five-track research program](docs/FIVE_PAPER_PROGRAM.md),
[baseline policy](docs/BASELINE_POLICY.md), and
[Colab quickstart](docs/COLAB_QUICKSTART.md). The
[results index](docs/RESULTS_INDEX.md) separates controlled evidence,
multi-seed smoke tests, and non-claim diagnostic probes; the
[public release record](docs/PUBLIC_RELEASE.md) records artifact hashes.

## License

MIT. See [LICENSE](LICENSE).
