Metadata-Version: 2.4
Name: wrfaddvar
Version: 0.1.0
Summary: Add external variables to WRF input files (wrfinput)
Project-URL: Homepage, https://github.com/xuelingbo/wrfaddvar
Project-URL: Issues, https://github.com/xuelingbo/wrfaddvar/issues
Author-email: xuelingbo <xuelingbo@gmail.com>
License: MIT
Keywords: AHE,WRF,atmospheric,meteorology,netcdf,wrfinput
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Topic :: Scientific/Engineering :: Atmospheric Science
Requires-Python: >=3.9
Requires-Dist: click>=8.0
Requires-Dist: netcdf4>=1.5
Requires-Dist: numpy>=1.20
Requires-Dist: pandas>=1.3
Requires-Dist: rasterio>=1.2
Requires-Dist: rioxarray>=0.13
Requires-Dist: scipy>=1.7
Requires-Dist: xarray>=0.19
Requires-Dist: xesmf>=0.8
Provides-Extra: dev
Requires-Dist: pytest-cov; extra == 'dev'
Requires-Dist: pytest>=7; extra == 'dev'
Description-Content-Type: text/markdown

# wrfaddvar

Add external variables to WRF input files (`wrfinput`).

## Installation

### Basic install (bilinear / nearest interpolation only)

```bash
pip install wrfaddvar
```

> [!WARNING]
> **Conservative remapping (`--method conservative`) requires `xesmf`, which cannot be
> installed via pip alone** — the underlying ESMF Fortran library must come from conda-forge.
> If you use conservative interpolation without installing these packages, you will see a
> **red error** and a yellow hint in the terminal telling you exactly what to run.

### Full install with conservative remapping support

```bash
conda install -c conda-forge esmf esmpy xesmf
pip install wrfaddvar
```

> [!NOTE]
> `wrfaddahe` uses **conservative remapping by default** (`--method conservative`).
> Install the conda packages above if you want to use this command without switching to
> `--method bilinear`.

## Commands

### `wrfaddvar` — general-purpose

```text
wrfaddvar --varname VARNAME [OPTIONS] SOURCE_FILE WRFINPUT_FILE
```

Reads `VARNAME` from `SOURCE_FILE`, interpolates it to the WRF grid, and
writes it into `WRFINPUT_FILE`.

Supported source formats (auto-detected from extension):

| Extension | Format |
| --------- | ------ |
| `.nc` / `.nc4` | NetCDF — variable + lat/lon coordinates |
| `.csv` | CSV — columns `lat`, `lon`, `<varname>` |
| `.tif` / `.tiff` | GeoTIFF (requires `rasterio`) |

#### Options

| Flag | Default | Description |
| ---- | ------- | ----------- |
| `--varname` | *(required)* | Variable name to write into wrfinput |
| `--source-varname` | same as `--varname` | Variable name inside SOURCE_FILE |
| `--method` | `bilinear` | Interpolation method: `bilinear`, `conservative`, or `nearest` |
| `--output / -o` | *(in-place)* | Write to a new file instead of modifying wrfinput |

#### Examples

```bash
# Add AHE from a GeoTIFF (bilinear by default)
wrfaddvar --varname AHE emissions.tif wrfinput.d01

# Add ERA5 2-m temperature (t2m) as T2_OBS, write to a new file
wrfaddvar --varname T2_OBS --source-varname t2m era5.nc wrfinput.d01 -o wrfinput.d01.new

# Nearest-neighbour interpolation from a CSV point dataset
wrfaddvar --varname NDVI --method nearest ndvi_stations.csv wrfinput.d01
```

---

### `wrfaddahe` — anthropogenic heat emissions shortcut

```text
wrfaddahe [OPTIONS] TIF_FILE WRFINPUT_FILE
```

Convenience wrapper that reads a GeoTIFF band and writes an `AHE` variable
with WRF-compatible attributes (`units = "W m-2"`, `FieldType = 104`, etc.).
Conservative remapping is used by default, which preserves the spatial
integral of the flux field.

#### wrfaddahe Options

| Flag | Default | Description |
| ---- | ------- | ----------- |
| `--band` | `1` | GeoTIFF band number |
| `--varname` | `AHE` | Variable name in wrfinput |
| `--method` | `conservative` | Interpolation method |
| `--output / -o` | *(in-place)* | Write to a new file |

#### wrfaddahe Examples

```bash
# Annual mean AHE (conservative remapping)
wrfaddahe ahe_2020.tif wrfinput.d01

# July (band 7), save to a new file
wrfaddahe --band 7 --output wrfinput.d01.ahe monthly_ahe.tif wrfinput.d01
```

---

## Python API

```python
from wrfaddvar import read_geotiff, to_wrf_grid, write_to_wrfinput
import netCDF4 as nc
import numpy as np

src = read_geotiff("ahe_2020.tif", band=1)

with nc.Dataset("wrfinput.d01") as ds:
    wrf_lats = np.array(ds.variables["XLAT"][0])
    wrf_lons = np.array(ds.variables["XLONG"][0])

data_on_wrf = to_wrf_grid(src, wrf_lats, wrf_lons, method="conservative")
write_to_wrfinput("wrfinput.d01", "AHE", data_on_wrf,
                  attrs={"units": "W m-2", "description": "ANTHROPOGENIC HEAT FLUX"})
```

## Publishing

```bash
pip install build twine
python -m build
twine upload dist/*
```
