Skip to content

aersurface

aersurface

AERSURFACE input-deck generation.

EPA's AERSURFACE binary derives monthly surface-characteristic tables (albedo, Bowen ratio, surface roughness) from NLCD land-use rasters for use in AERMET Stage 3. This module is the deck-builder; binary dispatch lives in :mod:pyaermod.aersurface_runner.

The deck format follows the EPA AERSURFACE v24 User's Guide. Common keywords are exposed as :class:AERSURFACEConfig fields; uncommon / forward-compatibility keywords can be passed via the extra_lines escape hatch.

Typical usage::

cfg = AERSURFACEConfig(
    title="Salem AERSURFACE run",
    site_id="SALEM",
    latitude=44.92, longitude=-123.04, utc_offset=-8,
    nlcd_file="/data/nlcd/NLCD_2019.img",
    nlcd_year=2019,
    snow_regime="CONTINENTAL_WARM",
    moisture_per_month=["AVERAGE"] * 12,
    snow_cover_per_month=["N"] * 12,
    output_dir=".",
)
deck_text = cfg.to_aersurface_input()

AERSURFACEConfig dataclass

Configuration for one AERSURFACE run.

Parameters:

Name Type Description Default
title str

Free-form run title written as the deck's TITLE keyword.

 required
site_id str

Short station identifier (<=8 characters recommended).

 required
latitude float

Site location in decimal degrees (WGS84).

 required
longitude float

Site location in decimal degrees (WGS84).

 required
utc_offset int

UTC offset hours, e.g. -8 for PST.

 required
nlcd_file str

Path to the NLCD raster (.img / .tif) covering the site and the surrounding sample radii.

 required
nlcd_year int

NLCD release year. Must be one of: 1992, 2001, 2006, 2011, 2013, 2016, 2019, 2021.

 required
arid bool

Set to True for arid/semi-arid regions (alters Bowen ratio).

 False
airport bool

Set to True for airport-style assumptions (mowed grass dominant).

 False
snow_regime str

Snow temperature regime; one of CONTINENTAL_WARM, CONTINENTAL_COOL, MARITIME_WARM, MARITIME_COOL, POLAR.

 'CONTINENTAL_WARM'
moisture_per_month List[str]

12-element list of "AVERAGE" | "DRY" | "WET" per Jan..Dec.

 (lambda: ['AVERAGE'] * 12)()
snow_cover_per_month List[str]

12-element list of "Y" | "N" per Jan..Dec.

 (lambda: ['N'] * 12)()
sectors Optional[List[float]]

List of sector boundary angles in degrees (clockwise from north), or None for a single uniform sector.

 None
radius_roughness_km float

Sample radius for surface-roughness averaging (km). EPA default 1.0.

 1.0
radius_albedo_bowen_km float

Sample radius for albedo + Bowen-ratio averaging (km). EPA default 10.0.

 10.0
output_dir str

Directory for AERSURFACE output files (the .out summary + the 12-month .sfc characteristic table consumed by AERMET Stage 3).

 '.'
extra_lines List[str]

Free-form lines appended verbatim after the standard keywords. Use for forward-compatibility with new AERSURFACE keywords or site-specific overrides not yet modelled here.

 list()

to_aersurface_input 

to_aersurface_input() -> str

Render the AERSURFACE input deck as a string.