Nldas Gesdisc Point Download

---
name: nldas-gesdisc-point-download
description: Download NASA GES DISC NLDAS_FORA0125_H version 2.0 primary hourly forcing data for a point location. Use when Codex needs to retrieve NLDAS File A meteorological forcing from the GES DISC API or HTTPS archive for a longitude/latitude pair, including Earthdata username/password authentication, hourly URL generation, nearest-grid-point extraction, CSV output, or EcoSIM climate-forcing preprocessing.
---

# NLDAS GES DISC Point Download

## Overview

Use this skill to retrieve `NLDAS_FORA0125_H` version `2.0` primary hourly forcing ("File A") from NASA GES DISC for a single point. The user-provided location is always longitude first, latitude second. Output must contain only the requested location or the nearest native NLDAS grid point, never a spatial grid.

Prefer the bundled script for repeatable downloads and point extraction. By default, it uses GES DISC OPeNDAP constraint expressions to request only scalar values for the nearest NLDAS grid cell; it does not download full gridded NetCDF granules unless `--access-method https-granule` is explicitly selected. In this repository, use `.venv-cmip6/bin/python` when extracting values because it includes the NetCDF stack needed by the fallback granule path:

```bash
.venv-cmip6/bin/python .agents/skills/nldas-gesdisc-point-download/scripts/download_nldas_fora_point.py \
  --lon -72.1715 \
  --lat 42.5378 \
  --auto-span complete-calendar-years \
  --allow-large-download \
  --output result/nldas/US-Ha1_nldas_fora_primary.csv
```

If credentials are not provided as command-line arguments, the script checks `USR_NLDAS` and `PASSWD_NLDAS`. A `.netrc` file is used only when explicitly passed with `--netrc-file`. Never write credentials to output files, manifests, logs, or shell snippets shown back to the user.

When `USR_NLDAS` and `PASSWD_NLDAS` are defined in `~/.bashrc` but are not visible in the current shell process, the script sources `~/.bashrc` and reads only those two variables into memory.

## Inputs

- `--lon`: longitude in decimal degrees, west negative. Must be in the NLDAS domain `[-125, -67]`.
- `--lat`: latitude in decimal degrees. Must be in the NLDAS domain `[25, 53]`.
- `--start`, `--end`: UTC timestamps. Accept `YYYY-MM-DD`, `YYYY-MM-DDTHH`, or `YYYY-MM-DDTHH:MM`. The script downloads all whole UTC hours from start through end, inclusive.
- `--auto-span complete-calendar-years`: infer the first complete UTC calendar year and last complete UTC calendar year from the GES DISC archive. Use this for EcoSIM annual forcing.
- `--auto-span available-years`: start at the first actual product hour and end at the last complete UTC calendar year. For `NLDAS_FORA0125_H`, this includes partial year 1979 starting at `1979-01-01T13:00Z`.
- `--variables`: optional native NLDAS variable list. Defaults to the EcoSIM climate-native set: `Tair`, `Wind_E`, `Wind_N`, `Rainf`, `Qair`, `SWdown`, `PSurf`.
- `--variable-set`: `ecosim-climate` by default; use `all-primary-file-a` only when the user explicitly asks for non-EcoSIM File A fields.
- `--username`, `--password`: optional Earthdata credentials that override `USR_NLDAS` and `PASSWD_NLDAS`.
- `--credential-profile`: bash profile to source for credentials, default `~/.bashrc`.
- `--access-method`: `opendap-point` by default for scalar point API access; use `https-granule` only when debugging or when the OPeNDAP service is unavailable.
- `--keep-raw`: keep full hourly NetCDF granules after point extraction. By default, newly downloaded raw granules are deleted after selected-location CSV extraction.
- `--allow-large-download`: required when a request exceeds the large-download threshold. Without it, the script writes a manifest with the inferred span and aborts before issuing many hourly API requests.
- `download_nldas_fora_point.py --allow-invalid` and `download_nldas_giovanni_ecosim.py --allow-invalid`: allow outputs even when validity checks flag out-of-range values. By default, validity failures make the command exit nonzero after writing the manifest or quality report.

## Data Source Facts

Load [references/nldas_gesdisc_api.md](references/nldas_gesdisc_api.md) when you need endpoint details, official links, file naming, authentication notes, or variable definitions.

Core facts:

- Collection: `NLDAS_FORA0125_H_2.0`.
- OPeNDAP point API base: `https://hydro1.gesdisc.eosdis.nasa.gov/opendap/NLDAS/NLDAS_FORA0125_H.2.0/`.
- HTTPS archive base: `https://hydro1.gesdisc.eosdis.nasa.gov/data/NLDAS/NLDAS_FORA0125_H.2.0/`.
- File pattern: `YYYY/DDD/NLDAS_FORA0125_H.AYYYYMMDD.HH00.020.nc`, where `DDD` is day of year.
- Spatial domain: west `-125`, east `-67`, south `25`, north `53`.
- Native temporal resolution: hourly UTC.
- Dataset summary: `https://disc.gsfc.nasa.gov/datasets/NLDAS_FORA0125_H_2.0/summary?keywords=NLDAS`.
- CMR reports the first product time as `1979-01-01T13:00:00Z`; the GES DISC archive currently has year folders through `2026`, so on `2026-06-26` the complete calendar-year span is `1980-01-01T00:00Z` through `2025-12-31T23:00Z`.

EcoSIM climate-native variables downloaded/extracted by default:

- `Tair`: maps to `TMPH` after K to degC conversion.
- `Wind_E`, `Wind_N`: map to `WINDH` as scalar wind speed.
- `Rainf`: maps to `RAINH`; native `kg m-2` hourly accumulation is numerically equivalent to mm water.
- `Qair`, `PSurf`: used to derive atmospheric vapor pressure for `DWPTH`.
- `SWdown`: maps to `SRADH`.
- `PSurf`: maps to `PATM` after Pa to kPa conversion.

EcoSIM annual auxiliary variables written by the Giovanni EcoSIM writer:

- `Z0G`, `IFLGW`, and `ZNOONG` are derived directly from site/grid assumptions and longitude.
- For US/NLDAS-domain grids, precipitation chemistry variables are added from the same NADP source used by US AmeriFlux workflows: `PHRG`, `CN4RIG`, `CNORIG`, `CSORG`, `CCARG`, and other supported template variables when source rasters exist.
- The Giovanni EcoSIM writer defaults to `--add-us-chemistry auto`, which adds NADP chemistry for coordinates in `[-125, -67]` longitude and `[25, 53]` latitude. Use `--add-us-chemistry never` to skip or `--add-us-chemistry always` to force.
- Use `--chemistry-input` to point to an alternate NADP raster directory and `--chemistry-output` to choose the intermediate extracted-chemistry JSON path.

Other primary File A variables, only when explicitly requested:

- `LWdown`: downward longwave radiation, `W m-2`.
- `PotEvap`: potential evaporation, `kg m-2`.
- `CAPE`: convective available potential energy, `J kg-1`.
- `CRainf_frac`: fraction of total precipitation that is convective.

## Workflow

1. Confirm the user supplied longitude then latitude. If a value looks swapped, stop and ask for clarification because the grid-cell choice affects water and energy forcing.
2. Confirm the requested period and variables. Interpret all times as UTC unless the user explicitly says otherwise.
3. When the user asks for "first to last available year" for EcoSIM, use `--auto-span complete-calendar-years`; this drops the partial first year (`1979`) and incomplete trailing year (`2026` as of June 26, 2026).
4. Ensure Earthdata credentials are available when GES DISC requires authentication. The standard repo workflow is to set `USR_NLDAS` and `PASSWD_NLDAS` in `~/.bashrc`; the script sources that file automatically when needed. The user may still pass `--username` and `--password` to override.
5. Run the script from the repository root.
6. Inspect the generated CSV and manifest:
   - Check requested lon/lat and selected grid lon/lat.
   - Check that every requested UTC hour is represented.
   - Check that the variable set is `ecosim-climate` unless the user explicitly requested another set.
   - Check units before converting to EcoSIM forcing names.
   - Check the quality report's `validity_checks.all_passed` field before using the NetCDF in an EcoSIM run.
   - For EcoSIM NetCDF outputs, check `annual_forcing.auxiliary_climate_variables` to confirm whether NADP chemistry was added, skipped, or default-filled.

## Output Rules

- Put outputs under `result/` unless the user provides another path.
- The default OPeNDAP access path writes only scalar point values for the selected nearest native NLDAS grid cell. The HTTPS archive fallback serves full hourly NetCDF granules; when that fallback is used, the script extracts the point and removes newly downloaded raw granules unless `--keep-raw` is supplied.
- Long automatic spans are request-heavy. For `1980-2025`, expect `403,248` hourly point API requests. The script refuses such runs unless `--allow-large-download` is explicitly supplied.
- Write a JSON manifest next to the CSV. Include source URLs, selected grid cell, variables, units, and download timestamps, but never include username or password.
- Preserve native units. Do not convert precipitation, pressure, or temperature for EcoSIM until a downstream conversion step is explicitly requested.

## EcoSIM Unit Cautions

- `Tair` is Kelvin; EcoSIM climate tools often expect degC for `TMPH`.
- `PSurf` is Pa; EcoSIM climate tools often use kPa for `PATM`.
- `Rainf` is hourly accumulated water mass per area (`kg m-2`), numerically equivalent to mm water depth for liquid water density. Do not treat it as a `kg m-2 s-1` rate unless the file metadata for a future product says so.
- `Wind_E` and `Wind_N` are vector components. Compute wind speed as `sqrt(Wind_E**2 + Wind_N**2)` only when the downstream workflow needs scalar speed.

## Validity Checks

The bundled point downloader and Giovanni EcoSIM downloader write explicit `validity_checks` to the manifest or quality report and fail by default when a variable is outside its accepted range.

Native NLDAS checks:

- `Tair`: `183.15` to `333.15 K` (`-90` to `60 degC`).
- `Wind_E`, `Wind_N`: `-75` to `75 m s^-1`.
- `Rainf`: `0` to `500 kg m^-2 h^-1`.
- `Qair`: `0` to `0.05 kg kg^-1`.
- `SWdown`: `0` to `1400 W m^-2`.
- `PSurf`: `50000` to `110000 Pa`.
- `LWdown`: `0` to `800 W m^-2`.
- `PotEvap`: `0` to `500 kg m^-2 h^-1`.
- `CAPE`: `0` to `10000 J kg^-1`.
- `CRainf_frac`: `0` to `1`.

EcoSIM checks:

- `TMPH`: `-90` to `60 degC`.
- `WINDH`: `0` to `75 m s^-1`.
- `RAINH`: `0` to `500 mm h^-1`.
- `DWPTH`: `0` to `15 kPa`.
- `SRADH`: `0` to `1400 W m^-2`.
- `PATM`: `50` to `110 kPa`.

Annual auxiliary checks:

- `Z0G`: positive measurement height, `0.01` to `100 m`.
- `IFLGW`: allowed flags `0` or `1`.
- `ZNOONG`: `0` to `24 hour`.
- `PHRG`: `0` to `14 pH`.
- Precipitation chemistry concentrations: non-negative.

NADP chemistry values must be finite and non-negative, with `PHRG` constrained to pH `0-14`. Annual gaps are filled by linear interpolation with nearest-edge filling. If no valid NADP pH is available, use neutral `PHRG=7` and record the fallback in the quality report. Do not silently apply NADP chemistry outside the US/NLDAS auxiliary domain.

## Validation

For any delivered extraction, report:

- Product short name and version.
- Requested longitude/latitude and selected grid-cell longitude/latitude.
- UTC start/end and number of hourly files.
- Variables extracted and their native units.
- Whether `validity_checks.all_passed` is true and which variables failed if false.
- Whether authentication was supplied via CLI arguments, `USR_NLDAS`/`PASSWD_NLDAS`, or not needed. Do not reveal credential values.