Metadata-Version: 2.5
Name: xaig
Version: 0.1.0
Summary: Light, framework-agnostic tooling for E3SM AI campaigns: latent diagnostics, sparse autoencoders, figures, a local app
Project-URL: Homepage, https://e3sm-project.github.io/aigroup
Project-URL: Documentation, https://e3sm-project.github.io/aigroup/package/
Project-URL: Source, https://github.com/E3SM-Project/aigroup
Project-URL: Issues, https://github.com/E3SM-Project/aigroup/issues
Author: E3SM AI Group
License-Expression: BSD-3-Clause
License-File: LICENSE
License-File: NOTICE
Keywords: climate,e3sm,emulator,machine-learning
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Science/Research
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Scientific/Engineering :: Atmospheric Science
Requires-Python: >=3.11
Requires-Dist: click>=8.1
Provides-Extra: daig
Requires-Dist: netcdf4>=1.6; extra == 'daig'
Requires-Dist: numpy>=1.24; extra == 'daig'
Requires-Dist: xarray>=2023.1; extra == 'daig'
Provides-Extra: faig
Requires-Dist: cartopy>=0.23; extra == 'faig'
Requires-Dist: matplotlib>=3.7; extra == 'faig'
Requires-Dist: netcdf4>=1.6; extra == 'faig'
Requires-Dist: numpy>=1.24; extra == 'faig'
Requires-Dist: xarray>=2023.1; extra == 'faig'
Provides-Extra: taig
Requires-Dist: netcdf4>=1.6; extra == 'taig'
Requires-Dist: numpy>=1.24; extra == 'taig'
Requires-Dist: torch>=2.0; extra == 'taig'
Requires-Dist: xarray>=2023.1; extra == 'taig'
Provides-Extra: waig
Requires-Dist: cartopy>=0.23; extra == 'waig'
Requires-Dist: matplotlib>=3.7; extra == 'waig'
Requires-Dist: netcdf4>=1.6; extra == 'waig'
Requires-Dist: numpy>=1.24; extra == 'waig'
Requires-Dist: streamlit>=1.50; extra == 'waig'
Requires-Dist: xarray>=2023.1; extra == 'waig'
Description-Content-Type: text/markdown

# xaig

Light, framework-agnostic tooling for E3SM AI campaigns: what an emulator holds inside,
sparse autoencoders trained on it, figures, and a local app over them.

> **Research tool.** `xaig` is early. What is described here works; expect it to change.

## Install

The base install pulls only Click. Anything heavier sits behind an extra named after the
subpackage that needs it:

```console
$ uv pip install 'xaig[daig]'     # or: pip install 'xaig[daig]'
```

| Extra | Pulls | Gets you |
| --- | --- | --- |
| `daig` | numpy, xarray, netCDF4 | `xaig.daig`: latent diagnostics on a grid |
| `faig` | matplotlib, cartopy | `xaig.faig`: maps and series figures (brings `daig`) |
| `waig` | streamlit | `xaig waig`: a local web app (brings `faig`) |
| `taig` | torch | `xaig.taig` and `xaig taig`: sparse autoencoders (brings `daig`) |

A missing extra says so, with the command that fits how `xaig` was installed.

## Try it, with no model and no data

A toy emulator writes a latent archive with nothing but numpy; everything else reads it
like any other:

```console
$ xaig daig latent toy scratch/toy/control
$ xaig daig latent info scratch/toy/control --mask-variable sst
$ xaig daig latent region scratch/toy/control --lat 10 --lon -114 --time 2 --centred --pcs 2
$ xaig daig latent fields scratch/toy/control --field precipitation --top 3
$ xaig taig sae scratch/toy/control --features 64 --k 4 --out scratch/toy/sae.npz   # needs xaig[taig]
$ xaig waig --latents scratch/toy                                                  # needs xaig[waig]
```

The CLI is a thin client of the Python API; anything it can do, a notebook can:

```python
from xaig.daig.latent import Region, analyse_region, open_source

source = open_source("scratch/toy/control", mask_variable="sst")
result = analyse_region(
    source, time=2, layer=3, region=Region(lat=10, lon=-114, radius_km=1500), centred=True
)
result.ranking.channels  # the channels that respond most strongly there
```

## More

- Guides: <https://e3sm-project.github.io/aigroup/package/>
- Source and issues: <https://github.com/E3SM-Project/aigroup>

BSD-3-Clause. `xaig.daig.latent`, `xaig.faig` and `xaig.waig` grew out of the
[latent space visualiser for weather models](https://github.com/ktempestuous/latent_space_visualiser_weather_models)
(Tempest, Beylich & Craig 2026, doi:10.1007/978-3-032-29915-4_10); see `NOTICE`.
