Metadata-Version: 2.4
Name: openamundsen-da
Version: 0.9.0
Summary: Data assimilation extension for openAMUNDSEN
Author-email: Franz Wagner <franz.wagner@uibk.ac.at>
Maintainer-email: Franz Wagner <franz.wagner@uibk.ac.at>
License-Expression: MIT
Project-URL: Documentation, https://openamundsen-da.pages.dev/
Project-URL: Repository, https://github.com/franzwagner-uibk/openamundsen_da
Project-URL: Issues, https://github.com/franzwagner-uibk/openamundsen_da/issues
Keywords: data assimilation,openAMUNDSEN,particle filter,snow hydrology
Classifier: Development Status :: 4 - Beta
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: Programming Language :: Python :: 3.14
Classifier: Topic :: Scientific/Engineering
Requires-Python: <3.15,>=3.11
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: openamundsen>=1.1
Requires-Dist: numpy>=1.24
Requires-Dist: pandas>=1.5
Requires-Dist: loguru>=0.7
Requires-Dist: geopandas>=0.14
Requires-Dist: rasterio>=1.3
Requires-Dist: xarray>=2023.0
Requires-Dist: netCDF4>=1.6
Requires-Dist: pyyaml>=6.0
Requires-Dist: ruamel.yaml>=0.17
Requires-Dist: matplotlib>=3.7
Requires-Dist: psutil>=5.9
Provides-Extra: test
Requires-Dist: pytest>=8.0; extra == "test"
Requires-Dist: ruff>=0.6; extra == "test"
Dynamic: license-file

# openAMUNDSEN-DA

openAMUNDSEN-DA is the data assimilation layer for the distributed snow and
hydrological model [openAMUNDSEN](https://github.com/openamundsen/openamundsen).
It prepares configured snow observations, executes sequential ensemble updates
and writes reproducible diagnostics and compact gridded results.

The project is a v0.9 research preview. Its scientific formulation and Rofental
application are described by Wagner et al. (2026); this repository documents the
software interface and operational workflow.

## Documentation

- [Installation](https://openamundsen-da.pages.dev/installation.html)
- [Input data](https://openamundsen-da.pages.dev/guides/observations.html)
- [Configuration](https://openamundsen-da.pages.dev/guides/configuration.html)
- [Running](https://openamundsen-da.pages.dev/running.html)
- [Output data](https://openamundsen-da.pages.dev/output-data.html)
- [Example data](https://openamundsen-da.pages.dev/example-data.html)
- [How to Use](https://openamundsen-da.pages.dev/tutorial/)
- [CLI reference](https://openamundsen-da.pages.dev/reference/cli.html)

## Install

Install the Python package on Python 3.11–3.14:

```bash
python -m pip install openamundsen-da
```

For the complete geospatial runtime, use the multi-architecture container:

```bash
docker pull ghcr.io/franzwagner-uibk/openamundsen_da:0.9.0
```

Use exact versions or image digests for reproducible work. The moving `edge`
image tracks the latest green `main` commit and is not a release.

## Command-line workflow

The installed distribution exposes one command, `openamundsen-da`:

```text
openamundsen-da observations snow-cover PROJECT_DIR
openamundsen-da observations wet-snow PROJECT_DIR
openamundsen-da prepare PROJECT_DIR
openamundsen-da run PROJECT_DIR --max-workers 24
openamundsen-da render PROJECT_DIR --max-workers 24
openamundsen-da clean PROJECT_DIR
```

`clean` is preview-only unless `--apply` is supplied. A successful single-domain
run already removes package-owned restart state after all configured outputs pass
validation; member grids remain available.

Large domains use explicit data assimilation stages:

```text
openamundsen-da subdomains prepare PROJECT_DIR
openamundsen-da subdomains run PROJECT_DIR
openamundsen-da subdomains merge PROJECT_DIR
openamundsen-da subdomains render PROJECT_DIR
```

The separate `openamundsen-da subdomains model prepare|run|merge` branch tiles
one ordinary openAMUNDSEN simulation without projects or assimilation.

## Python interface

```python
from openamundsen_da import prepare_project, run_project

project = "/data/rofental/projects/project_2022_2023"
prepare_project(project)
result = run_project(project, max_workers=24)
print(result.manifest_path)
```

The supported Python surface contains the six top-level workflow operations
documented in the [API reference](https://openamundsen-da.pages.dev/reference/api.html).
Subdomain modules and lower-level scientific routines are internal interfaces.

## Configuration boundary

- `<setup-name>.yml` is pure openAMUNDSEN configuration and shared setup data.
- `<project-name>.yml` owns the time span, observations and data assimilation.
- generated step YAML files own one assimilation window and step-local model overrides.

Model grid inputs are selected exclusively by `output_data.grids.format` and
support grid-layout NetCDF or deterministic georeferenced GeoTIFF. The compact
data assimilation result is always `results/grids/da_output_grids.nc`.

## Development

Build and validate the distribution, then build the same wheel-based image used
for release:

```bash
python -m pip install build twine
bash scripts/ci/build_distribution.sh
docker build -t openamundsen-da:local .
```

Run tests through the repository wrappers:

```bash
bash scripts/ci/run_lint.sh
bash scripts/ci/run_unit_tests.sh
bash scripts/ci/run_integration_tests.sh
bash scripts/ci/run_integration_tests_subdomain.sh
```

See [tests/README.md](tests/README.md) for the exact validation contracts.

## License

openAMUNDSEN-DA is released under the [MIT License](LICENSE), including
commercial use subject to the license terms.
