Surface file parameters

This page is generated from the surface variable registry.

All surface variables

Variable	Dimensions	Units	Required level	Contexts	Description
ALB_IMPROAD_DIF	numrad,numurbl,topounit,lsmlat,lsmlon	unitless	optional	topounits, urban	Diffuse albedo of impervious road; spectral-dependent surface reflectance for urban impervious surfaces.
ALB_IMPROAD_DIR	numrad,numurbl,topounit,lsmlat,lsmlon	unitless	optional	topounits, urban	Direct albedo of impervious road; spectral-dependent surface reflectance for urban impervious surfaces.
ALB_PERROAD_DIF	numrad,numurbl,topounit,lsmlat,lsmlon	unitless	optional	topounits, urban	Diffuse albedo of pervious road; spectral-dependent surface reflectance for urban pervious surfaces.
ALB_PERROAD_DIR	numrad,numurbl,topounit,lsmlat,lsmlon	unitless	optional	topounits, urban	Direct albedo of pervious road; spectral-dependent surface reflectance for urban pervious surfaces.
ALB_ROOF_DIF	numrad,numurbl,topounit,lsmlat,lsmlon	unitless	optional	topounits, urban	Diffuse albedo of roof; spectral-dependent surface reflectance for urban roof surfaces.
ALB_ROOF_DIR	numrad,numurbl,topounit,lsmlat,lsmlon	unitless	optional	topounits, urban	Direct albedo of roof; spectral-dependent surface reflectance for urban roof surfaces.
ALB_WALL_DIF	numrad,numurbl,topounit,lsmlat,lsmlon	unitless	optional	topounits, urban	Diffuse albedo of wall; spectral-dependent surface reflectance for urban wall surfaces.
ALB_WALL_DIR	numrad,numurbl,topounit,lsmlat,lsmlon	unitless	optional	topounits, urban	Direct albedo of wall; spectral-dependent surface reflectance for urban wall surfaces.
APATITE_P	topounit,lsmlat,lsmlon	gP/m2	optional	phosphorus_cycle, topounits	Apatite phosphorus; soil phosphorus pool in apatite (primary mineral) form; used by phosphorus biogeochemistry when enabled.
AREA	lsmlat,lsmlon	m2	required	core, grid_topography	Area (m2) of each land grid cell; used to weight land-surface properties and to compare with domain/topography.
CANYON_HWR	numurbl,topounit,lsmlat,lsmlon	unitless	optional	topounits, urban	Canyon height to width ratio; urban geometric parameter affecting radiation and wind.
CV_IMPROAD	nlevurb,numurbl,topounit,lsmlat,lsmlon	J/m^3*K	optional	topounits, urban	Volumetric heat capacity of impervious road; thermal mass property affecting diurnal temperature variations.
CV_ROOF	nlevurb,numurbl,topounit,lsmlat,lsmlon	J/m^3*K	optional	topounits, urban	Volumetric heat capacity of roof; thermal mass property affecting building heat dynamics.
CV_WALL	nlevurb,numurbl,topounit,lsmlat,lsmlon	J/m^3*K	optional	topounits, urban	Volumetric heat capacity of wall; thermal mass property affecting wall temperature dynamics.
Ds	topounit,lsmlat,lsmlon	unitless	optional	hydrology, topounits	VIC Ds parameter for the ARNO curve; fractional saturated area infiltration parameter.
Dsmax	topounit,lsmlat,lsmlon	mm/day	optional	hydrology, topounits	VIC Dsmax parameter for the ARNO curve; maximum infiltration rate.
EF1_BTR	topounit,lsmlat,lsmlon	unitless	optional	biogeochemistry, topounits, vegetation_structure	EF1 isoprene emission factor for broadleaf tree (BTR); vegetation-dependent emission rate.
EF1_CRP	topounit,lsmlat,lsmlon	unitless	optional	biogeochemistry, topounits, vegetation_structure	EF1 isoprene emission factor for crop (CRP); vegetation-dependent emission rate.
EF1_FDT	topounit,lsmlat,lsmlon	unitless	optional	biogeochemistry, topounits, vegetation_structure	EF1 isoprene emission factor for deciduous forest (FDT); vegetation-dependent emission rate.
EF1_FET	topounit,lsmlat,lsmlon	unitless	optional	biogeochemistry, topounits, vegetation_structure	EF1 isoprene emission factor for evergreen forest (FET); vegetation-dependent emission rate.
EF1_GRS	topounit,lsmlat,lsmlon	unitless	optional	biogeochemistry, topounits, vegetation_structure	EF1 isoprene emission factor for grass (GRS); vegetation-dependent emission rate.
EF1_SHR	topounit,lsmlat,lsmlon	unitless	optional	biogeochemistry, topounits, vegetation_structure	EF1 isoprene emission factor for shrub (SHR); vegetation-dependent emission rate.
EM_IMPROAD	numurbl,topounit,lsmlat,lsmlon	unitless	optional	topounits, urban	Emissivity of impervious road; controls longwave radiation emission from urban surfaces.
EM_PERROAD	numurbl,topounit,lsmlat,lsmlon	unitless	optional	topounits, urban	Emissivity of pervious road; controls longwave radiation emission from pervious urban surfaces.
EM_ROOF	numurbl,topounit,lsmlat,lsmlon	unitless	optional	topounits, urban	Emissivity of roof; controls longwave radiation emission from building roof.
EM_WALL	numurbl,topounit,lsmlat,lsmlon	unitless	optional	topounits, urban	Emissivity of wall; controls longwave radiation emission from building walls.
F0	topounit,lsmlat,lsmlon	unitless	optional	hydrology, inland_water, topounits	Maximum gridcell fractional inundated area; controls wetland extent.
FGRD	topounit,lsmlat,lsmlon	unitless	conditional	crops_irrigation, topounits	Fraction of irrigation water applied via ground/sprinkler/drip; complements FSURF. (Requirement: Required when firrig_data is true; optional otherwise)
FIRRIG	topounit,lsmlat,lsmlon	unitless	conditional	crops_irrigation, topounits	Fraction (0–1) of cropland that is irrigated; read only when irrigation data are enabled (firrig_data). (Requirement: Required when firrig_data is true; optional otherwise)
FMAX	topounit,lsmlat,lsmlon	unitless	optional	hydrology, topounits	Maximum fractional saturated area; upper bound on inundation fraction.
FSURF	topounit,lsmlat,lsmlon	unitless	conditional	crops_irrigation, topounits	Fraction of irrigation water applied via surface irrigation; required with FIRRIG when irrigation data are used. (Requirement: Required when firrig_data is true; optional otherwise)
GLCMASK	lsmlat,lsmlon	unitless	optional	glaciers	Glacier mask read from a separate glacier file; ensures that glacier cells are a subset of the land mask. (Requirement: Optional (only used when a glacier mask file is provided))
GLC_MEC	lsmlat,lsmlon	unitless	conditional	glaciers	Integer glacier elevation-class index for each grid cell when using mechanistic glacier (MEC) landunits. (Requirement: Required when glacier MEC landunits are used; optional otherwise)
HT_ROOF	numurbl,topounit,lsmlat,lsmlon	m	optional	topounits, urban	Height of roof; geometric property defining building structure.
LABILE_P	topounit,lsmlat,lsmlon	gP/m2	optional	phosphorus_cycle, topounits	Labile inorganic phosphorus; soil labile (readily available) phosphorus pool; used by P-cycle parameterizations.
LAKEDEPTH	topounit,lsmlat,lsmlon	m	optional	hydrology, inland_water, topounits	Lake depth; average water depth for lake landunit.
LANDFRAC	lsmlat,lsmlon	unitless	required	core, land_cover	Fraction of each grid cell that is land (0–1); used to weight surface properties; a missing variable causes a fatal error.
LANDFRAC_PFT	lsmlat,lsmlon	unitless	required	core, land_cover	Fraction (0–1) of the global gridcell that is land in the PFT landunit; used to weight PFT tiles relative to the gridcell.
LANDMASK	lsmlat,lsmlon	unitless	required	core	Binary mask (1 = land, 0 = not-land) defining which grid cells are part of the land model; read from the surface file or domain file.
LATIXY	lsmlat,lsmlon	degrees_north	required	core	Latitude (degrees) of the centre of each land grid cell.
LONGXY	lsmlat,lsmlon	degrees_east	required	core	Longitude (degrees) of the centre of each land grid cell; used to compare the surface file with the domain and topography files.
MONTHLY_HEIGHT_BOT	time,lsmpft,topounit,lsmlat,lsmlon	m	optional	topounits, vegetation_structure	Monthly climatology of canopy bottom height (m) for vegetated landunits.
MONTHLY_HEIGHT_TOP	time,lsmpft,topounit,lsmlat,lsmlon	m	optional	topounits, vegetation_structure	Monthly climatology of canopy top height (m) for vegetated landunits.
MONTHLY_LAI	time,lsmpft,topounit,lsmlat,lsmlon	unitless	optional	topounits, vegetation_structure	Leaf area index (LAI; m2 leaf per m2 ground) monthly climatology; time is typically 12 months.
MONTHLY_SAI	time,lsmpft,topounit,lsmlat,lsmlon	unitless	optional	topounits, vegetation_structure	Stem area index (SAI) monthly climatology; time is typically 12 months.
MaxTopounitElv	lsmlat,lsmlon	m	optional	grid_topography, topounits	Maximum topounits elevation in each grid cell; a summary statistic reflecting the highest elevation among topounits. (Requirement: Optional (not required, but improves topounit characterization))
NFERT	cft,topounit,lsmlat,lsmlon	unknown	optional	crops_irrigation, topounits	Nitrogen fertilizer application for each crop functional type; if absent, values default to zero. (Requirement: Optional (values default to zero when absent))
NLEV_IMPROAD	numurbl,topounit,lsmlat,lsmlon	unitless	optional	topounits, urban	Number of impervious road layers; structural discretization for temperature calculation.
OCCLUDED_P	topounit,lsmlat,lsmlon	gP/m2	optional	phosphorus_cycle, topounits	Occluded phosphorus; soil occluded phosphorus pool (sorbed or otherwise inaccessible); part of multi-pool P parameterization.
ORGANIC	nlevsoi,topounit,lsmlat,lsmlon	kg/m3 (assumed carbon content 0.58 gC per gOM)	optional	soil_properties, topounits	Organic matter density per soil layer; used in biogeochemical and thermal calculations.
P3	topounit,lsmlat,lsmlon	s/mm	optional	hydrology, topounits	Coefficient for qflx_surf_lag for finundated; surface runoff delay parameter.
PCT_CFT	cft,topounit,lsmlat,lsmlon	percent	conditional	crops_irrigation, land_cover, topounits	Fraction of vegetated area allocated to each crop functional type; code aborts if missing when cft dimension exists. (Requirement: Required when the surface file includes crop functional types (cft_size > 0))
PCT_CLAY	nlevsoi,topounit,lsmlat,lsmlon	percent	required	soil_properties, topounits	Soil clay percentage by mass (0–100) in each soil layer; controls hydraulic and thermal properties.
PCT_CROP	topounit,lsmlat,lsmlon	percent	required	crops_irrigation, land_cover, topounits	Percent of grid cell area covered by cropland.
PCT_FCP	topounit,lsmlat,lsmlon	percent	conditional	land_cover, polygonal_tundra, topounits	Fraction of natural vegetation that is flat-centered polygons. (Requirement: Required when use_polygonal_tundra is true; optional otherwise)
PCT_GLACIER	topounit,lsmlat,lsmlon	percent	conditional	glaciers, land_cover, topounits	Fraction of grid cell area covered by simple glacier landunits within each topounit. (Requirement: Required unless glacier MEC landunits are used; optional when create_glacier_mec_landunit is true)
PCT_GLC_MEC	nglcec,topounit,lsmlat,lsmlon	percent	conditional	glaciers, land_cover, topounits	Percent of grid cell area assigned to mechanistic glacier classes (accumulation/ablation, etc.). (Requirement: Required when glacier MEC landunits are created; optional otherwise)
PCT_GRVL	nlevsoi,topounit,lsmlat,lsmlon	percent	optional	soil_properties, topounits	Percent gravel content (0–100) in each soil layer; affects soil water storage and hydraulic conductivity.
PCT_HCP	topounit,lsmlat,lsmlon	percent	conditional	land_cover, polygonal_tundra, topounits	Fraction of natural vegetation landunit that is high-centered polygons (polygonal tundra). (Requirement: Required when use_polygonal_tundra is true; optional otherwise)
PCT_LAKE	topounit,lsmlat,lsmlon	percent	required	inland_water, land_cover, topounits	Percentage of each grid cell area that is lake within each topounit; used for lake landunit weighting.
PCT_LCP	topounit,lsmlat,lsmlon	percent	conditional	land_cover, polygonal_tundra, topounits	Fraction of natural vegetation that is low-centered polygons. (Requirement: Required when use_polygonal_tundra is true; optional otherwise)
PCT_NATVEG	topounit,lsmlat,lsmlon	percent	required	land_cover, topounits	Percent of grid cell area covered by natural vegetation (non-crop vegetated landunit).
PCT_NAT_PFT	natpft,topounit,lsmlat,lsmlon	percent	required	land_cover, topounits	Fraction of vegetated area allocated to each natural plant functional type; code aborts if missing.
PCT_SAND	nlevsoi,topounit,lsmlat,lsmlon	percent	required	soil_properties, topounits	Soil sand percentage by mass (0–100) in each soil layer; controls hydraulic and thermal properties.
PCT_URBAN	numurbl,topounit,lsmlat,lsmlon	percent	conditional	land_cover, topounits, urban	Fraction of each grid cell that is urban, for each density class in the multi-density urban scheme. (Requirement: Required when the multi-density urban model is used (nlevurb > 0); optional otherwise)
PCT_WETLAND	topounit,lsmlat,lsmlon	percent	required	inland_water, land_cover, topounits	Percentage (0–100) of each grid cell area covered by wetlands within each topounit.
PFERT	cft,topounit,lsmlat,lsmlon	unknown	optional	crops_irrigation, phosphorus_cycle, topounits	Phosphorus fertilizer application for each crop functional type; treated like NFERT.
PFTDATA_MASK	lsmlat,lsmlon	unitless	required	core, land_cover	Mask marking land grid cells that contain valid plant functional type (PFT) data; if missing the code stops with an error.
SECONDARY_P	topounit,lsmlat,lsmlon	gP/m2	optional	phosphorus_cycle, topounits	Secondary mineral phosphorus; soil secondary mineral phosphorus pool; intermediate in reactivity between apatite and labile pools.
SINSL_COSAS	lsmlat,lsmlon	unitless	conditional	grid_topography, topographic_radiation	sin(slope) * cos(aspect) for each grid cell; used in solar-radiation calculations. (Requirement: Required when TOP solar-radiation is used; optional otherwise)
SINSL_SINAS	lsmlat,lsmlon	unitless	conditional	grid_topography, topographic_radiation	sin(slope) * sin(aspect) for each grid cell; used with SINSL_COSAS. (Requirement: Required when TOP solar-radiation is used; optional otherwise)
SKY_VIEW	lsmlat,lsmlon	unitless	conditional	grid_topography, topographic_radiation	Sky-view factor (0–1) describing horizon obstruction by surrounding terrain; needed by the TOP solar-radiation scheme. (Requirement: Required when TOP solar-radiation is used; optional otherwise)
SLOPE	lsmlat,lsmlon	degrees	required	grid_topography	Mean surface slope (degrees) for each land grid cell; used in topographic and hydrologic parameterizations.
SLP_P10	nlevslp,topounit,lsmlat,lsmlon	km km^-1	optional	grid_topography, topounits	Slope at quantiles (minimum and 10 to 100 percentile); topographic distribution parameter.
SOIL_COLOR	topounit,lsmlat,lsmlon	unitless	optional	soil_properties, topounits	Soil color; categorical index affecting soil albedo parameterization.
SOIL_ORDER	topounit,lsmlat,lsmlon	unitless	optional	soil_properties, topounits	Soil order; categorical soil classification for pedogenic properties.
STDEV_ELEV	lsmlat,lsmlon	m	conditional	grid_topography, topographic_radiation	Standard deviation of elevation (m) used by the TOP solar-radiation parameterization; if STDEV_ELEV is missing the code tries STD_ELEV. (Requirement: Required when TOP solar-radiation is used; optional otherwise)
STD_ELEV	lsmlat,lsmlon	m	conditional	grid_topography, topographic_radiation	Standard deviation of elevation (m) used by the TOP solar-radiation parameterization; alternative name to STDEV_ELEV. (Requirement: Required when TOP solar-radiation is used; optional otherwise)
TERRAIN_CONFIG	lsmlat,lsmlon	unitless	conditional	grid_topography, topographic_radiation	Terrain configuration parameter used in the TOP scheme to account for terrain-induced shading. (Requirement: Required when TOP solar-radiation is used; optional otherwise)
THICK_ROOF	numurbl,topounit,lsmlat,lsmlon	m	optional	topounits, urban	Thickness of roof; structural property affecting heat capacity.
THICK_WALL	numurbl,topounit,lsmlat,lsmlon	m	optional	topounits, urban	Thickness of wall; structural property affecting heat capacity.
TK_IMPROAD	nlevurb,numurbl,topounit,lsmlat,lsmlon	W/m*K	optional	topounits, urban	Thermal conductivity of impervious road; controls heat diffusion through urban surface layers.
TK_ROOF	nlevurb,numurbl,topounit,lsmlat,lsmlon	W/m*K	optional	topounits, urban	Thermal conductivity of roof; controls heat transfer through building roof material.
TK_WALL	nlevurb,numurbl,topounit,lsmlat,lsmlon	W/m*K	optional	topounits, urban	Thermal conductivity of wall; controls heat transfer through building wall material.
TOPO	lsmlat,lsmlon	m	required	grid_topography	Mean elevation (m) of each land grid cell read from the topography file; required by surfrd_get_topo.
TOPO2	lsmlat,lsmlon	m	optional	grid_topography, topounits	Weighted average of topounits elevation in each grid cell; a summary statistic for topounit-based elevation characterization.
TOPO_GLC_MEC	nglcec,topounit,lsmlat,lsmlon	m	conditional	glaciers, grid_topography, topounits	Elevation (m) of each mechanistic glacier class. (Requirement: Required when glacier MEC landunits are used; optional otherwise)
T_BUILDING_MAX	numurbl,topounit,lsmlat,lsmlon	K	optional	topounits, urban	Maximum interior building temperature; upper limit constraint for urban heating/cooling.
T_BUILDING_MIN	numurbl,topounit,lsmlat,lsmlon	K	optional	topounits, urban	Minimum interior building temperature; lower limit constraint for urban heating/cooling.
TopounitAspect	topounit,lsmlat,lsmlon	degrees	optional	grid_topography, topounits	Aspect (azimuth) of each topounit; optional and unused by default.
TopounitAveElv	topounit,lsmlat,lsmlon	m	optional	grid_topography, topounits	Average elevation (m) of each topounit; optional if available.
TopounitElv	topounit,lsmlat,lsmlon	m	optional	grid_topography, topounits	Average elevation (m) of each topounit; optional if available.
TopounitFracArea	topounit,lsmlat,lsmlon	unitless	optional	grid_topography, topounits	Fraction of the grid cell’s area represented by each topounit; read only if present.
TopounitSlope	topounit,lsmlat,lsmlon	degrees	optional	grid_topography, topounits	Slope (degrees) of each topounit; not currently used but may improve topographic representation.
URBAN_REGION_ID	topounit,lsmlat,lsmlon	unitless	conditional	topounits, urban	Integer identifier linking urban grid cells to regional urban morphology datasets. (Requirement: Required when PCT_URBAN is used; optional otherwise)
WIND_HGT_CANYON	numurbl,topounit,lsmlat,lsmlon	m	optional	topounits, urban	Height of wind in canyon; reference height for urban wind profile.
WTLUNIT_ROOF	numurbl,topounit,lsmlat,lsmlon	unitless	optional	topounits, urban	Fraction of roof; weight for urban landunit distribution.
WTROAD_PERV	numurbl,topounit,lsmlat,lsmlon	unitless	optional	topounits, urban	Fraction of pervious road; weight for pervious surface distribution.
Ws	topounit,lsmlat,lsmlon	unitless	optional	hydrology, topounits	VIC Ws parameter for the ARNO Curve; maximum soil moisture storage.
ZWT0	topounit,lsmlat,lsmlon	m	optional	hydrology, topounits	Decay factor for finundated; controls inundated area decay with water table.
abm	topounit,lsmlat,lsmlon	unitless	optional	disturbance, land_cover, topounits	Agricultural fire peak month; seasonal indicator for fire occurrence.
aveDTB	topounit,lsmlat,lsmlon	m	optional	grid_topography, soil_properties, topounits	Average depth to bedrock of the subgrid; critical for groundwater dynamics.
binfl	topounit,lsmlat,lsmlon	unitless	optional	hydrology, topounits	VIC b parameter for the Variable Infiltration Capacity Curve; infiltration nonlinearity.
frac	lsmlat,lsmlon	unitless	required	core, land_cover	Fraction of each grid cell that is land (0–1); used to weight surface properties; a missing variable causes a fatal error.
gdp	topounit,lsmlat,lsmlon	unitless	optional	anthropogenic, topounits	GDP (parameter); economic/anthropogenic activity indicator.
mask	lsmlat,lsmlon	unitless	required	core	Binary mask (1 = land, 0 = not-land) defining which grid cells are part of the land model; read from the surface file or domain file.
parEro_c1	topounit,lsmlat,lsmlon	unitless	optional	disturbance, grid_topography, topounits	Scalar parameter for rainfall-driven hillslope erosion; controls erosion from precipitation.
parEro_c2	topounit,lsmlat,lsmlon	unitless	optional	disturbance, grid_topography, hydrology, topounits	Scalar parameter for runoff-driven hillslope erosion; controls erosion from surface runoff.
parEro_c3	topounit,lsmlat,lsmlon	unitless	optional	disturbance, grid_topography, hydrology, topounits	Scalar parameter for transport capacity of hillslope overland flow; controls sediment transport capacity.
peatf	topounit,lsmlat,lsmlon	unitless	optional	land_cover, soil_properties, topounits	Peatland fraction; fraction of grid cell area classified as peat soils.
topoPerGrid	lsmlat,lsmlon	unitless	optional	grid_topography, topounits	Number of topounits in each grid cell; if absent, the number of topounits is set to 1.
xCell	lsmlat,lsmlon	unknown	optional	unstructured_grid	Unstructured grid coordinates (e.g., MPAS x) when using an irregular mesh; the code reads them only if they exist.
yCell	lsmlat,lsmlon	unknown	optional	unstructured_grid	Unstructured grid coordinates (e.g., MPAS y) when using an irregular mesh; the code reads them only if they exist.

Variables by context

Context: anthropogenic

Variable	Dimensions	Units	Required level	Contexts	Description
gdp	topounit,lsmlat,lsmlon	unitless	optional	anthropogenic, topounits	GDP (parameter); economic/anthropogenic activity indicator.

Context: biogeochemistry

Variable	Dimensions	Units	Required level	Contexts	Description
EF1_BTR	topounit,lsmlat,lsmlon	unitless	optional	biogeochemistry, topounits, vegetation_structure	EF1 isoprene emission factor for broadleaf tree (BTR); vegetation-dependent emission rate.
EF1_CRP	topounit,lsmlat,lsmlon	unitless	optional	biogeochemistry, topounits, vegetation_structure	EF1 isoprene emission factor for crop (CRP); vegetation-dependent emission rate.
EF1_FDT	topounit,lsmlat,lsmlon	unitless	optional	biogeochemistry, topounits, vegetation_structure	EF1 isoprene emission factor for deciduous forest (FDT); vegetation-dependent emission rate.
EF1_FET	topounit,lsmlat,lsmlon	unitless	optional	biogeochemistry, topounits, vegetation_structure	EF1 isoprene emission factor for evergreen forest (FET); vegetation-dependent emission rate.
EF1_GRS	topounit,lsmlat,lsmlon	unitless	optional	biogeochemistry, topounits, vegetation_structure	EF1 isoprene emission factor for grass (GRS); vegetation-dependent emission rate.
EF1_SHR	topounit,lsmlat,lsmlon	unitless	optional	biogeochemistry, topounits, vegetation_structure	EF1 isoprene emission factor for shrub (SHR); vegetation-dependent emission rate.

Context: core

Variable	Dimensions	Units	Required level	Contexts	Description
AREA	lsmlat,lsmlon	m2	required	core, grid_topography	Area (m2) of each land grid cell; used to weight land-surface properties and to compare with domain/topography.
LANDFRAC	lsmlat,lsmlon	unitless	required	core, land_cover	Fraction of each grid cell that is land (0–1); used to weight surface properties; a missing variable causes a fatal error.
LANDFRAC_PFT	lsmlat,lsmlon	unitless	required	core, land_cover	Fraction (0–1) of the global gridcell that is land in the PFT landunit; used to weight PFT tiles relative to the gridcell.
LANDMASK	lsmlat,lsmlon	unitless	required	core	Binary mask (1 = land, 0 = not-land) defining which grid cells are part of the land model; read from the surface file or domain file.
LATIXY	lsmlat,lsmlon	degrees_north	required	core	Latitude (degrees) of the centre of each land grid cell.
LONGXY	lsmlat,lsmlon	degrees_east	required	core	Longitude (degrees) of the centre of each land grid cell; used to compare the surface file with the domain and topography files.
PFTDATA_MASK	lsmlat,lsmlon	unitless	required	core, land_cover	Mask marking land grid cells that contain valid plant functional type (PFT) data; if missing the code stops with an error.
frac	lsmlat,lsmlon	unitless	required	core, land_cover	Fraction of each grid cell that is land (0–1); used to weight surface properties; a missing variable causes a fatal error.
mask	lsmlat,lsmlon	unitless	required	core	Binary mask (1 = land, 0 = not-land) defining which grid cells are part of the land model; read from the surface file or domain file.

Context: crops_irrigation

Variable	Dimensions	Units	Required level	Contexts	Description
FGRD	topounit,lsmlat,lsmlon	unitless	conditional	crops_irrigation, topounits	Fraction of irrigation water applied via ground/sprinkler/drip; complements FSURF. (Requirement: Required when firrig_data is true; optional otherwise)
FIRRIG	topounit,lsmlat,lsmlon	unitless	conditional	crops_irrigation, topounits	Fraction (0–1) of cropland that is irrigated; read only when irrigation data are enabled (firrig_data). (Requirement: Required when firrig_data is true; optional otherwise)
FSURF	topounit,lsmlat,lsmlon	unitless	conditional	crops_irrigation, topounits	Fraction of irrigation water applied via surface irrigation; required with FIRRIG when irrigation data are used. (Requirement: Required when firrig_data is true; optional otherwise)
NFERT	cft,topounit,lsmlat,lsmlon	unknown	optional	crops_irrigation, topounits	Nitrogen fertilizer application for each crop functional type; if absent, values default to zero. (Requirement: Optional (values default to zero when absent))
PCT_CFT	cft,topounit,lsmlat,lsmlon	percent	conditional	crops_irrigation, land_cover, topounits	Fraction of vegetated area allocated to each crop functional type; code aborts if missing when cft dimension exists. (Requirement: Required when the surface file includes crop functional types (cft_size > 0))
PCT_CROP	topounit,lsmlat,lsmlon	percent	required	crops_irrigation, land_cover, topounits	Percent of grid cell area covered by cropland.
PFERT	cft,topounit,lsmlat,lsmlon	unknown	optional	crops_irrigation, phosphorus_cycle, topounits	Phosphorus fertilizer application for each crop functional type; treated like NFERT.

Context: disturbance

Variable	Dimensions	Units	Required level	Contexts	Description
abm	topounit,lsmlat,lsmlon	unitless	optional	disturbance, land_cover, topounits	Agricultural fire peak month; seasonal indicator for fire occurrence.
parEro_c1	topounit,lsmlat,lsmlon	unitless	optional	disturbance, grid_topography, topounits	Scalar parameter for rainfall-driven hillslope erosion; controls erosion from precipitation.
parEro_c2	topounit,lsmlat,lsmlon	unitless	optional	disturbance, grid_topography, hydrology, topounits	Scalar parameter for runoff-driven hillslope erosion; controls erosion from surface runoff.
parEro_c3	topounit,lsmlat,lsmlon	unitless	optional	disturbance, grid_topography, hydrology, topounits	Scalar parameter for transport capacity of hillslope overland flow; controls sediment transport capacity.

Context: glaciers

Variable	Dimensions	Units	Required level	Contexts	Description
GLCMASK	lsmlat,lsmlon	unitless	optional	glaciers	Glacier mask read from a separate glacier file; ensures that glacier cells are a subset of the land mask. (Requirement: Optional (only used when a glacier mask file is provided))
GLC_MEC	lsmlat,lsmlon	unitless	conditional	glaciers	Integer glacier elevation-class index for each grid cell when using mechanistic glacier (MEC) landunits. (Requirement: Required when glacier MEC landunits are used; optional otherwise)
PCT_GLACIER	topounit,lsmlat,lsmlon	percent	conditional	glaciers, land_cover, topounits	Fraction of grid cell area covered by simple glacier landunits within each topounit. (Requirement: Required unless glacier MEC landunits are used; optional when create_glacier_mec_landunit is true)
PCT_GLC_MEC	nglcec,topounit,lsmlat,lsmlon	percent	conditional	glaciers, land_cover, topounits	Percent of grid cell area assigned to mechanistic glacier classes (accumulation/ablation, etc.). (Requirement: Required when glacier MEC landunits are created; optional otherwise)
TOPO_GLC_MEC	nglcec,topounit,lsmlat,lsmlon	m	conditional	glaciers, grid_topography, topounits	Elevation (m) of each mechanistic glacier class. (Requirement: Required when glacier MEC landunits are used; optional otherwise)

Context: grid_topography

Variable	Dimensions	Units	Required level	Contexts	Description
AREA	lsmlat,lsmlon	m2	required	core, grid_topography	Area (m2) of each land grid cell; used to weight land-surface properties and to compare with domain/topography.
MaxTopounitElv	lsmlat,lsmlon	m	optional	grid_topography, topounits	Maximum topounits elevation in each grid cell; a summary statistic reflecting the highest elevation among topounits. (Requirement: Optional (not required, but improves topounit characterization))
SINSL_COSAS	lsmlat,lsmlon	unitless	conditional	grid_topography, topographic_radiation	sin(slope) * cos(aspect) for each grid cell; used in solar-radiation calculations. (Requirement: Required when TOP solar-radiation is used; optional otherwise)
SINSL_SINAS	lsmlat,lsmlon	unitless	conditional	grid_topography, topographic_radiation	sin(slope) * sin(aspect) for each grid cell; used with SINSL_COSAS. (Requirement: Required when TOP solar-radiation is used; optional otherwise)
SKY_VIEW	lsmlat,lsmlon	unitless	conditional	grid_topography, topographic_radiation	Sky-view factor (0–1) describing horizon obstruction by surrounding terrain; needed by the TOP solar-radiation scheme. (Requirement: Required when TOP solar-radiation is used; optional otherwise)
SLOPE	lsmlat,lsmlon	degrees	required	grid_topography	Mean surface slope (degrees) for each land grid cell; used in topographic and hydrologic parameterizations.
SLP_P10	nlevslp,topounit,lsmlat,lsmlon	km km^-1	optional	grid_topography, topounits	Slope at quantiles (minimum and 10 to 100 percentile); topographic distribution parameter.
STDEV_ELEV	lsmlat,lsmlon	m	conditional	grid_topography, topographic_radiation	Standard deviation of elevation (m) used by the TOP solar-radiation parameterization; if STDEV_ELEV is missing the code tries STD_ELEV. (Requirement: Required when TOP solar-radiation is used; optional otherwise)
STD_ELEV	lsmlat,lsmlon	m	conditional	grid_topography, topographic_radiation	Standard deviation of elevation (m) used by the TOP solar-radiation parameterization; alternative name to STDEV_ELEV. (Requirement: Required when TOP solar-radiation is used; optional otherwise)
TERRAIN_CONFIG	lsmlat,lsmlon	unitless	conditional	grid_topography, topographic_radiation	Terrain configuration parameter used in the TOP scheme to account for terrain-induced shading. (Requirement: Required when TOP solar-radiation is used; optional otherwise)
TOPO	lsmlat,lsmlon	m	required	grid_topography	Mean elevation (m) of each land grid cell read from the topography file; required by surfrd_get_topo.
TOPO2	lsmlat,lsmlon	m	optional	grid_topography, topounits	Weighted average of topounits elevation in each grid cell; a summary statistic for topounit-based elevation characterization.
TOPO_GLC_MEC	nglcec,topounit,lsmlat,lsmlon	m	conditional	glaciers, grid_topography, topounits	Elevation (m) of each mechanistic glacier class. (Requirement: Required when glacier MEC landunits are used; optional otherwise)
TopounitAspect	topounit,lsmlat,lsmlon	degrees	optional	grid_topography, topounits	Aspect (azimuth) of each topounit; optional and unused by default.
TopounitAveElv	topounit,lsmlat,lsmlon	m	optional	grid_topography, topounits	Average elevation (m) of each topounit; optional if available.
TopounitElv	topounit,lsmlat,lsmlon	m	optional	grid_topography, topounits	Average elevation (m) of each topounit; optional if available.
TopounitFracArea	topounit,lsmlat,lsmlon	unitless	optional	grid_topography, topounits	Fraction of the grid cell’s area represented by each topounit; read only if present.
TopounitSlope	topounit,lsmlat,lsmlon	degrees	optional	grid_topography, topounits	Slope (degrees) of each topounit; not currently used but may improve topographic representation.
aveDTB	topounit,lsmlat,lsmlon	m	optional	grid_topography, soil_properties, topounits	Average depth to bedrock of the subgrid; critical for groundwater dynamics.
parEro_c1	topounit,lsmlat,lsmlon	unitless	optional	disturbance, grid_topography, topounits	Scalar parameter for rainfall-driven hillslope erosion; controls erosion from precipitation.
parEro_c2	topounit,lsmlat,lsmlon	unitless	optional	disturbance, grid_topography, hydrology, topounits	Scalar parameter for runoff-driven hillslope erosion; controls erosion from surface runoff.
parEro_c3	topounit,lsmlat,lsmlon	unitless	optional	disturbance, grid_topography, hydrology, topounits	Scalar parameter for transport capacity of hillslope overland flow; controls sediment transport capacity.
topoPerGrid	lsmlat,lsmlon	unitless	optional	grid_topography, topounits	Number of topounits in each grid cell; if absent, the number of topounits is set to 1.

Context: hydrology

Variable	Dimensions	Units	Required level	Contexts	Description
Ds	topounit,lsmlat,lsmlon	unitless	optional	hydrology, topounits	VIC Ds parameter for the ARNO curve; fractional saturated area infiltration parameter.
Dsmax	topounit,lsmlat,lsmlon	mm/day	optional	hydrology, topounits	VIC Dsmax parameter for the ARNO curve; maximum infiltration rate.
F0	topounit,lsmlat,lsmlon	unitless	optional	hydrology, inland_water, topounits	Maximum gridcell fractional inundated area; controls wetland extent.
FMAX	topounit,lsmlat,lsmlon	unitless	optional	hydrology, topounits	Maximum fractional saturated area; upper bound on inundation fraction.
LAKEDEPTH	topounit,lsmlat,lsmlon	m	optional	hydrology, inland_water, topounits	Lake depth; average water depth for lake landunit.
P3	topounit,lsmlat,lsmlon	s/mm	optional	hydrology, topounits	Coefficient for qflx_surf_lag for finundated; surface runoff delay parameter.
Ws	topounit,lsmlat,lsmlon	unitless	optional	hydrology, topounits	VIC Ws parameter for the ARNO Curve; maximum soil moisture storage.
ZWT0	topounit,lsmlat,lsmlon	m	optional	hydrology, topounits	Decay factor for finundated; controls inundated area decay with water table.
binfl	topounit,lsmlat,lsmlon	unitless	optional	hydrology, topounits	VIC b parameter for the Variable Infiltration Capacity Curve; infiltration nonlinearity.
parEro_c2	topounit,lsmlat,lsmlon	unitless	optional	disturbance, grid_topography, hydrology, topounits	Scalar parameter for runoff-driven hillslope erosion; controls erosion from surface runoff.
parEro_c3	topounit,lsmlat,lsmlon	unitless	optional	disturbance, grid_topography, hydrology, topounits	Scalar parameter for transport capacity of hillslope overland flow; controls sediment transport capacity.

Context: inland_water

Variable	Dimensions	Units	Required level	Contexts	Description
F0	topounit,lsmlat,lsmlon	unitless	optional	hydrology, inland_water, topounits	Maximum gridcell fractional inundated area; controls wetland extent.
LAKEDEPTH	topounit,lsmlat,lsmlon	m	optional	hydrology, inland_water, topounits	Lake depth; average water depth for lake landunit.
PCT_LAKE	topounit,lsmlat,lsmlon	percent	required	inland_water, land_cover, topounits	Percentage of each grid cell area that is lake within each topounit; used for lake landunit weighting.
PCT_WETLAND	topounit,lsmlat,lsmlon	percent	required	inland_water, land_cover, topounits	Percentage (0–100) of each grid cell area covered by wetlands within each topounit.

Context: land_cover

Variable	Dimensions	Units	Required level	Contexts	Description
LANDFRAC	lsmlat,lsmlon	unitless	required	core, land_cover	Fraction of each grid cell that is land (0–1); used to weight surface properties; a missing variable causes a fatal error.
LANDFRAC_PFT	lsmlat,lsmlon	unitless	required	core, land_cover	Fraction (0–1) of the global gridcell that is land in the PFT landunit; used to weight PFT tiles relative to the gridcell.
PCT_CFT	cft,topounit,lsmlat,lsmlon	percent	conditional	crops_irrigation, land_cover, topounits	Fraction of vegetated area allocated to each crop functional type; code aborts if missing when cft dimension exists. (Requirement: Required when the surface file includes crop functional types (cft_size > 0))
PCT_CROP	topounit,lsmlat,lsmlon	percent	required	crops_irrigation, land_cover, topounits	Percent of grid cell area covered by cropland.
PCT_FCP	topounit,lsmlat,lsmlon	percent	conditional	land_cover, polygonal_tundra, topounits	Fraction of natural vegetation that is flat-centered polygons. (Requirement: Required when use_polygonal_tundra is true; optional otherwise)
PCT_GLACIER	topounit,lsmlat,lsmlon	percent	conditional	glaciers, land_cover, topounits	Fraction of grid cell area covered by simple glacier landunits within each topounit. (Requirement: Required unless glacier MEC landunits are used; optional when create_glacier_mec_landunit is true)
PCT_GLC_MEC	nglcec,topounit,lsmlat,lsmlon	percent	conditional	glaciers, land_cover, topounits	Percent of grid cell area assigned to mechanistic glacier classes (accumulation/ablation, etc.). (Requirement: Required when glacier MEC landunits are created; optional otherwise)
PCT_HCP	topounit,lsmlat,lsmlon	percent	conditional	land_cover, polygonal_tundra, topounits	Fraction of natural vegetation landunit that is high-centered polygons (polygonal tundra). (Requirement: Required when use_polygonal_tundra is true; optional otherwise)
PCT_LAKE	topounit,lsmlat,lsmlon	percent	required	inland_water, land_cover, topounits	Percentage of each grid cell area that is lake within each topounit; used for lake landunit weighting.
PCT_LCP	topounit,lsmlat,lsmlon	percent	conditional	land_cover, polygonal_tundra, topounits	Fraction of natural vegetation that is low-centered polygons. (Requirement: Required when use_polygonal_tundra is true; optional otherwise)
PCT_NATVEG	topounit,lsmlat,lsmlon	percent	required	land_cover, topounits	Percent of grid cell area covered by natural vegetation (non-crop vegetated landunit).
PCT_NAT_PFT	natpft,topounit,lsmlat,lsmlon	percent	required	land_cover, topounits	Fraction of vegetated area allocated to each natural plant functional type; code aborts if missing.
PCT_URBAN	numurbl,topounit,lsmlat,lsmlon	percent	conditional	land_cover, topounits, urban	Fraction of each grid cell that is urban, for each density class in the multi-density urban scheme. (Requirement: Required when the multi-density urban model is used (nlevurb > 0); optional otherwise)
PCT_WETLAND	topounit,lsmlat,lsmlon	percent	required	inland_water, land_cover, topounits	Percentage (0–100) of each grid cell area covered by wetlands within each topounit.
PFTDATA_MASK	lsmlat,lsmlon	unitless	required	core, land_cover	Mask marking land grid cells that contain valid plant functional type (PFT) data; if missing the code stops with an error.
abm	topounit,lsmlat,lsmlon	unitless	optional	disturbance, land_cover, topounits	Agricultural fire peak month; seasonal indicator for fire occurrence.
frac	lsmlat,lsmlon	unitless	required	core, land_cover	Fraction of each grid cell that is land (0–1); used to weight surface properties; a missing variable causes a fatal error.
peatf	topounit,lsmlat,lsmlon	unitless	optional	land_cover, soil_properties, topounits	Peatland fraction; fraction of grid cell area classified as peat soils.

Context: phosphorus_cycle

Variable	Dimensions	Units	Required level	Contexts	Description
APATITE_P	topounit,lsmlat,lsmlon	gP/m2	optional	phosphorus_cycle, topounits	Apatite phosphorus; soil phosphorus pool in apatite (primary mineral) form; used by phosphorus biogeochemistry when enabled.
LABILE_P	topounit,lsmlat,lsmlon	gP/m2	optional	phosphorus_cycle, topounits	Labile inorganic phosphorus; soil labile (readily available) phosphorus pool; used by P-cycle parameterizations.
OCCLUDED_P	topounit,lsmlat,lsmlon	gP/m2	optional	phosphorus_cycle, topounits	Occluded phosphorus; soil occluded phosphorus pool (sorbed or otherwise inaccessible); part of multi-pool P parameterization.
PFERT	cft,topounit,lsmlat,lsmlon	unknown	optional	crops_irrigation, phosphorus_cycle, topounits	Phosphorus fertilizer application for each crop functional type; treated like NFERT.
SECONDARY_P	topounit,lsmlat,lsmlon	gP/m2	optional	phosphorus_cycle, topounits	Secondary mineral phosphorus; soil secondary mineral phosphorus pool; intermediate in reactivity between apatite and labile pools.

Context: polygonal_tundra

Variable	Dimensions	Units	Required level	Contexts	Description
PCT_FCP	topounit,lsmlat,lsmlon	percent	conditional	land_cover, polygonal_tundra, topounits	Fraction of natural vegetation that is flat-centered polygons. (Requirement: Required when use_polygonal_tundra is true; optional otherwise)
PCT_HCP	topounit,lsmlat,lsmlon	percent	conditional	land_cover, polygonal_tundra, topounits	Fraction of natural vegetation landunit that is high-centered polygons (polygonal tundra). (Requirement: Required when use_polygonal_tundra is true; optional otherwise)
PCT_LCP	topounit,lsmlat,lsmlon	percent	conditional	land_cover, polygonal_tundra, topounits	Fraction of natural vegetation that is low-centered polygons. (Requirement: Required when use_polygonal_tundra is true; optional otherwise)

Context: soil_properties

Variable	Dimensions	Units	Required level	Contexts	Description
ORGANIC	nlevsoi,topounit,lsmlat,lsmlon	kg/m3 (assumed carbon content 0.58 gC per gOM)	optional	soil_properties, topounits	Organic matter density per soil layer; used in biogeochemical and thermal calculations.
PCT_CLAY	nlevsoi,topounit,lsmlat,lsmlon	percent	required	soil_properties, topounits	Soil clay percentage by mass (0–100) in each soil layer; controls hydraulic and thermal properties.
PCT_GRVL	nlevsoi,topounit,lsmlat,lsmlon	percent	optional	soil_properties, topounits	Percent gravel content (0–100) in each soil layer; affects soil water storage and hydraulic conductivity.
PCT_SAND	nlevsoi,topounit,lsmlat,lsmlon	percent	required	soil_properties, topounits	Soil sand percentage by mass (0–100) in each soil layer; controls hydraulic and thermal properties.
SOIL_COLOR	topounit,lsmlat,lsmlon	unitless	optional	soil_properties, topounits	Soil color; categorical index affecting soil albedo parameterization.
SOIL_ORDER	topounit,lsmlat,lsmlon	unitless	optional	soil_properties, topounits	Soil order; categorical soil classification for pedogenic properties.
aveDTB	topounit,lsmlat,lsmlon	m	optional	grid_topography, soil_properties, topounits	Average depth to bedrock of the subgrid; critical for groundwater dynamics.
peatf	topounit,lsmlat,lsmlon	unitless	optional	land_cover, soil_properties, topounits	Peatland fraction; fraction of grid cell area classified as peat soils.

Context: topographic_radiation

Variable	Dimensions	Units	Required level	Contexts	Description
SINSL_COSAS	lsmlat,lsmlon	unitless	conditional	grid_topography, topographic_radiation	sin(slope) * cos(aspect) for each grid cell; used in solar-radiation calculations. (Requirement: Required when TOP solar-radiation is used; optional otherwise)
SINSL_SINAS	lsmlat,lsmlon	unitless	conditional	grid_topography, topographic_radiation	sin(slope) * sin(aspect) for each grid cell; used with SINSL_COSAS. (Requirement: Required when TOP solar-radiation is used; optional otherwise)
SKY_VIEW	lsmlat,lsmlon	unitless	conditional	grid_topography, topographic_radiation	Sky-view factor (0–1) describing horizon obstruction by surrounding terrain; needed by the TOP solar-radiation scheme. (Requirement: Required when TOP solar-radiation is used; optional otherwise)
STDEV_ELEV	lsmlat,lsmlon	m	conditional	grid_topography, topographic_radiation	Standard deviation of elevation (m) used by the TOP solar-radiation parameterization; if STDEV_ELEV is missing the code tries STD_ELEV. (Requirement: Required when TOP solar-radiation is used; optional otherwise)
STD_ELEV	lsmlat,lsmlon	m	conditional	grid_topography, topographic_radiation	Standard deviation of elevation (m) used by the TOP solar-radiation parameterization; alternative name to STDEV_ELEV. (Requirement: Required when TOP solar-radiation is used; optional otherwise)
TERRAIN_CONFIG	lsmlat,lsmlon	unitless	conditional	grid_topography, topographic_radiation	Terrain configuration parameter used in the TOP scheme to account for terrain-induced shading. (Requirement: Required when TOP solar-radiation is used; optional otherwise)

Context: topounits

Variable	Dimensions	Units	Required level	Contexts	Description
ALB_IMPROAD_DIF	numrad,numurbl,topounit,lsmlat,lsmlon	unitless	optional	topounits, urban	Diffuse albedo of impervious road; spectral-dependent surface reflectance for urban impervious surfaces.
ALB_IMPROAD_DIR	numrad,numurbl,topounit,lsmlat,lsmlon	unitless	optional	topounits, urban	Direct albedo of impervious road; spectral-dependent surface reflectance for urban impervious surfaces.
ALB_PERROAD_DIF	numrad,numurbl,topounit,lsmlat,lsmlon	unitless	optional	topounits, urban	Diffuse albedo of pervious road; spectral-dependent surface reflectance for urban pervious surfaces.
ALB_PERROAD_DIR	numrad,numurbl,topounit,lsmlat,lsmlon	unitless	optional	topounits, urban	Direct albedo of pervious road; spectral-dependent surface reflectance for urban pervious surfaces.
ALB_ROOF_DIF	numrad,numurbl,topounit,lsmlat,lsmlon	unitless	optional	topounits, urban	Diffuse albedo of roof; spectral-dependent surface reflectance for urban roof surfaces.
ALB_ROOF_DIR	numrad,numurbl,topounit,lsmlat,lsmlon	unitless	optional	topounits, urban	Direct albedo of roof; spectral-dependent surface reflectance for urban roof surfaces.
ALB_WALL_DIF	numrad,numurbl,topounit,lsmlat,lsmlon	unitless	optional	topounits, urban	Diffuse albedo of wall; spectral-dependent surface reflectance for urban wall surfaces.
ALB_WALL_DIR	numrad,numurbl,topounit,lsmlat,lsmlon	unitless	optional	topounits, urban	Direct albedo of wall; spectral-dependent surface reflectance for urban wall surfaces.
APATITE_P	topounit,lsmlat,lsmlon	gP/m2	optional	phosphorus_cycle, topounits	Apatite phosphorus; soil phosphorus pool in apatite (primary mineral) form; used by phosphorus biogeochemistry when enabled.
CANYON_HWR	numurbl,topounit,lsmlat,lsmlon	unitless	optional	topounits, urban	Canyon height to width ratio; urban geometric parameter affecting radiation and wind.
CV_IMPROAD	nlevurb,numurbl,topounit,lsmlat,lsmlon	J/m^3*K	optional	topounits, urban	Volumetric heat capacity of impervious road; thermal mass property affecting diurnal temperature variations.
CV_ROOF	nlevurb,numurbl,topounit,lsmlat,lsmlon	J/m^3*K	optional	topounits, urban	Volumetric heat capacity of roof; thermal mass property affecting building heat dynamics.
CV_WALL	nlevurb,numurbl,topounit,lsmlat,lsmlon	J/m^3*K	optional	topounits, urban	Volumetric heat capacity of wall; thermal mass property affecting wall temperature dynamics.
Ds	topounit,lsmlat,lsmlon	unitless	optional	hydrology, topounits	VIC Ds parameter for the ARNO curve; fractional saturated area infiltration parameter.
Dsmax	topounit,lsmlat,lsmlon	mm/day	optional	hydrology, topounits	VIC Dsmax parameter for the ARNO curve; maximum infiltration rate.
EF1_BTR	topounit,lsmlat,lsmlon	unitless	optional	biogeochemistry, topounits, vegetation_structure	EF1 isoprene emission factor for broadleaf tree (BTR); vegetation-dependent emission rate.
EF1_CRP	topounit,lsmlat,lsmlon	unitless	optional	biogeochemistry, topounits, vegetation_structure	EF1 isoprene emission factor for crop (CRP); vegetation-dependent emission rate.
EF1_FDT	topounit,lsmlat,lsmlon	unitless	optional	biogeochemistry, topounits, vegetation_structure	EF1 isoprene emission factor for deciduous forest (FDT); vegetation-dependent emission rate.
EF1_FET	topounit,lsmlat,lsmlon	unitless	optional	biogeochemistry, topounits, vegetation_structure	EF1 isoprene emission factor for evergreen forest (FET); vegetation-dependent emission rate.
EF1_GRS	topounit,lsmlat,lsmlon	unitless	optional	biogeochemistry, topounits, vegetation_structure	EF1 isoprene emission factor for grass (GRS); vegetation-dependent emission rate.
EF1_SHR	topounit,lsmlat,lsmlon	unitless	optional	biogeochemistry, topounits, vegetation_structure	EF1 isoprene emission factor for shrub (SHR); vegetation-dependent emission rate.
EM_IMPROAD	numurbl,topounit,lsmlat,lsmlon	unitless	optional	topounits, urban	Emissivity of impervious road; controls longwave radiation emission from urban surfaces.
EM_PERROAD	numurbl,topounit,lsmlat,lsmlon	unitless	optional	topounits, urban	Emissivity of pervious road; controls longwave radiation emission from pervious urban surfaces.
EM_ROOF	numurbl,topounit,lsmlat,lsmlon	unitless	optional	topounits, urban	Emissivity of roof; controls longwave radiation emission from building roof.
EM_WALL	numurbl,topounit,lsmlat,lsmlon	unitless	optional	topounits, urban	Emissivity of wall; controls longwave radiation emission from building walls.
F0	topounit,lsmlat,lsmlon	unitless	optional	hydrology, inland_water, topounits	Maximum gridcell fractional inundated area; controls wetland extent.
FGRD	topounit,lsmlat,lsmlon	unitless	conditional	crops_irrigation, topounits	Fraction of irrigation water applied via ground/sprinkler/drip; complements FSURF. (Requirement: Required when firrig_data is true; optional otherwise)
FIRRIG	topounit,lsmlat,lsmlon	unitless	conditional	crops_irrigation, topounits	Fraction (0–1) of cropland that is irrigated; read only when irrigation data are enabled (firrig_data). (Requirement: Required when firrig_data is true; optional otherwise)
FMAX	topounit,lsmlat,lsmlon	unitless	optional	hydrology, topounits	Maximum fractional saturated area; upper bound on inundation fraction.
FSURF	topounit,lsmlat,lsmlon	unitless	conditional	crops_irrigation, topounits	Fraction of irrigation water applied via surface irrigation; required with FIRRIG when irrigation data are used. (Requirement: Required when firrig_data is true; optional otherwise)
HT_ROOF	numurbl,topounit,lsmlat,lsmlon	m	optional	topounits, urban	Height of roof; geometric property defining building structure.
LABILE_P	topounit,lsmlat,lsmlon	gP/m2	optional	phosphorus_cycle, topounits	Labile inorganic phosphorus; soil labile (readily available) phosphorus pool; used by P-cycle parameterizations.
LAKEDEPTH	topounit,lsmlat,lsmlon	m	optional	hydrology, inland_water, topounits	Lake depth; average water depth for lake landunit.
MONTHLY_HEIGHT_BOT	time,lsmpft,topounit,lsmlat,lsmlon	m	optional	topounits, vegetation_structure	Monthly climatology of canopy bottom height (m) for vegetated landunits.
MONTHLY_HEIGHT_TOP	time,lsmpft,topounit,lsmlat,lsmlon	m	optional	topounits, vegetation_structure	Monthly climatology of canopy top height (m) for vegetated landunits.
MONTHLY_LAI	time,lsmpft,topounit,lsmlat,lsmlon	unitless	optional	topounits, vegetation_structure	Leaf area index (LAI; m2 leaf per m2 ground) monthly climatology; time is typically 12 months.
MONTHLY_SAI	time,lsmpft,topounit,lsmlat,lsmlon	unitless	optional	topounits, vegetation_structure	Stem area index (SAI) monthly climatology; time is typically 12 months.
MaxTopounitElv	lsmlat,lsmlon	m	optional	grid_topography, topounits	Maximum topounits elevation in each grid cell; a summary statistic reflecting the highest elevation among topounits. (Requirement: Optional (not required, but improves topounit characterization))
NFERT	cft,topounit,lsmlat,lsmlon	unknown	optional	crops_irrigation, topounits	Nitrogen fertilizer application for each crop functional type; if absent, values default to zero. (Requirement: Optional (values default to zero when absent))
NLEV_IMPROAD	numurbl,topounit,lsmlat,lsmlon	unitless	optional	topounits, urban	Number of impervious road layers; structural discretization for temperature calculation.
OCCLUDED_P	topounit,lsmlat,lsmlon	gP/m2	optional	phosphorus_cycle, topounits	Occluded phosphorus; soil occluded phosphorus pool (sorbed or otherwise inaccessible); part of multi-pool P parameterization.
ORGANIC	nlevsoi,topounit,lsmlat,lsmlon	kg/m3 (assumed carbon content 0.58 gC per gOM)	optional	soil_properties, topounits	Organic matter density per soil layer; used in biogeochemical and thermal calculations.
P3	topounit,lsmlat,lsmlon	s/mm	optional	hydrology, topounits	Coefficient for qflx_surf_lag for finundated; surface runoff delay parameter.
PCT_CFT	cft,topounit,lsmlat,lsmlon	percent	conditional	crops_irrigation, land_cover, topounits	Fraction of vegetated area allocated to each crop functional type; code aborts if missing when cft dimension exists. (Requirement: Required when the surface file includes crop functional types (cft_size > 0))
PCT_CLAY	nlevsoi,topounit,lsmlat,lsmlon	percent	required	soil_properties, topounits	Soil clay percentage by mass (0–100) in each soil layer; controls hydraulic and thermal properties.
PCT_CROP	topounit,lsmlat,lsmlon	percent	required	crops_irrigation, land_cover, topounits	Percent of grid cell area covered by cropland.
PCT_FCP	topounit,lsmlat,lsmlon	percent	conditional	land_cover, polygonal_tundra, topounits	Fraction of natural vegetation that is flat-centered polygons. (Requirement: Required when use_polygonal_tundra is true; optional otherwise)
PCT_GLACIER	topounit,lsmlat,lsmlon	percent	conditional	glaciers, land_cover, topounits	Fraction of grid cell area covered by simple glacier landunits within each topounit. (Requirement: Required unless glacier MEC landunits are used; optional when create_glacier_mec_landunit is true)
PCT_GLC_MEC	nglcec,topounit,lsmlat,lsmlon	percent	conditional	glaciers, land_cover, topounits	Percent of grid cell area assigned to mechanistic glacier classes (accumulation/ablation, etc.). (Requirement: Required when glacier MEC landunits are created; optional otherwise)
PCT_GRVL	nlevsoi,topounit,lsmlat,lsmlon	percent	optional	soil_properties, topounits	Percent gravel content (0–100) in each soil layer; affects soil water storage and hydraulic conductivity.
PCT_HCP	topounit,lsmlat,lsmlon	percent	conditional	land_cover, polygonal_tundra, topounits	Fraction of natural vegetation landunit that is high-centered polygons (polygonal tundra). (Requirement: Required when use_polygonal_tundra is true; optional otherwise)
PCT_LAKE	topounit,lsmlat,lsmlon	percent	required	inland_water, land_cover, topounits	Percentage of each grid cell area that is lake within each topounit; used for lake landunit weighting.
PCT_LCP	topounit,lsmlat,lsmlon	percent	conditional	land_cover, polygonal_tundra, topounits	Fraction of natural vegetation that is low-centered polygons. (Requirement: Required when use_polygonal_tundra is true; optional otherwise)
PCT_NATVEG	topounit,lsmlat,lsmlon	percent	required	land_cover, topounits	Percent of grid cell area covered by natural vegetation (non-crop vegetated landunit).
PCT_NAT_PFT	natpft,topounit,lsmlat,lsmlon	percent	required	land_cover, topounits	Fraction of vegetated area allocated to each natural plant functional type; code aborts if missing.
PCT_SAND	nlevsoi,topounit,lsmlat,lsmlon	percent	required	soil_properties, topounits	Soil sand percentage by mass (0–100) in each soil layer; controls hydraulic and thermal properties.
PCT_URBAN	numurbl,topounit,lsmlat,lsmlon	percent	conditional	land_cover, topounits, urban	Fraction of each grid cell that is urban, for each density class in the multi-density urban scheme. (Requirement: Required when the multi-density urban model is used (nlevurb > 0); optional otherwise)
PCT_WETLAND	topounit,lsmlat,lsmlon	percent	required	inland_water, land_cover, topounits	Percentage (0–100) of each grid cell area covered by wetlands within each topounit.
PFERT	cft,topounit,lsmlat,lsmlon	unknown	optional	crops_irrigation, phosphorus_cycle, topounits	Phosphorus fertilizer application for each crop functional type; treated like NFERT.
SECONDARY_P	topounit,lsmlat,lsmlon	gP/m2	optional	phosphorus_cycle, topounits	Secondary mineral phosphorus; soil secondary mineral phosphorus pool; intermediate in reactivity between apatite and labile pools.
SLP_P10	nlevslp,topounit,lsmlat,lsmlon	km km^-1	optional	grid_topography, topounits	Slope at quantiles (minimum and 10 to 100 percentile); topographic distribution parameter.
SOIL_COLOR	topounit,lsmlat,lsmlon	unitless	optional	soil_properties, topounits	Soil color; categorical index affecting soil albedo parameterization.
SOIL_ORDER	topounit,lsmlat,lsmlon	unitless	optional	soil_properties, topounits	Soil order; categorical soil classification for pedogenic properties.
THICK_ROOF	numurbl,topounit,lsmlat,lsmlon	m	optional	topounits, urban	Thickness of roof; structural property affecting heat capacity.
THICK_WALL	numurbl,topounit,lsmlat,lsmlon	m	optional	topounits, urban	Thickness of wall; structural property affecting heat capacity.
TK_IMPROAD	nlevurb,numurbl,topounit,lsmlat,lsmlon	W/m*K	optional	topounits, urban	Thermal conductivity of impervious road; controls heat diffusion through urban surface layers.
TK_ROOF	nlevurb,numurbl,topounit,lsmlat,lsmlon	W/m*K	optional	topounits, urban	Thermal conductivity of roof; controls heat transfer through building roof material.
TK_WALL	nlevurb,numurbl,topounit,lsmlat,lsmlon	W/m*K	optional	topounits, urban	Thermal conductivity of wall; controls heat transfer through building wall material.
TOPO2	lsmlat,lsmlon	m	optional	grid_topography, topounits	Weighted average of topounits elevation in each grid cell; a summary statistic for topounit-based elevation characterization.
TOPO_GLC_MEC	nglcec,topounit,lsmlat,lsmlon	m	conditional	glaciers, grid_topography, topounits	Elevation (m) of each mechanistic glacier class. (Requirement: Required when glacier MEC landunits are used; optional otherwise)
T_BUILDING_MAX	numurbl,topounit,lsmlat,lsmlon	K	optional	topounits, urban	Maximum interior building temperature; upper limit constraint for urban heating/cooling.
T_BUILDING_MIN	numurbl,topounit,lsmlat,lsmlon	K	optional	topounits, urban	Minimum interior building temperature; lower limit constraint for urban heating/cooling.
TopounitAspect	topounit,lsmlat,lsmlon	degrees	optional	grid_topography, topounits	Aspect (azimuth) of each topounit; optional and unused by default.
TopounitAveElv	topounit,lsmlat,lsmlon	m	optional	grid_topography, topounits	Average elevation (m) of each topounit; optional if available.
TopounitElv	topounit,lsmlat,lsmlon	m	optional	grid_topography, topounits	Average elevation (m) of each topounit; optional if available.
TopounitFracArea	topounit,lsmlat,lsmlon	unitless	optional	grid_topography, topounits	Fraction of the grid cell’s area represented by each topounit; read only if present.
TopounitSlope	topounit,lsmlat,lsmlon	degrees	optional	grid_topography, topounits	Slope (degrees) of each topounit; not currently used but may improve topographic representation.
URBAN_REGION_ID	topounit,lsmlat,lsmlon	unitless	conditional	topounits, urban	Integer identifier linking urban grid cells to regional urban morphology datasets. (Requirement: Required when PCT_URBAN is used; optional otherwise)
WIND_HGT_CANYON	numurbl,topounit,lsmlat,lsmlon	m	optional	topounits, urban	Height of wind in canyon; reference height for urban wind profile.
WTLUNIT_ROOF	numurbl,topounit,lsmlat,lsmlon	unitless	optional	topounits, urban	Fraction of roof; weight for urban landunit distribution.
WTROAD_PERV	numurbl,topounit,lsmlat,lsmlon	unitless	optional	topounits, urban	Fraction of pervious road; weight for pervious surface distribution.
Ws	topounit,lsmlat,lsmlon	unitless	optional	hydrology, topounits	VIC Ws parameter for the ARNO Curve; maximum soil moisture storage.
ZWT0	topounit,lsmlat,lsmlon	m	optional	hydrology, topounits	Decay factor for finundated; controls inundated area decay with water table.
abm	topounit,lsmlat,lsmlon	unitless	optional	disturbance, land_cover, topounits	Agricultural fire peak month; seasonal indicator for fire occurrence.
aveDTB	topounit,lsmlat,lsmlon	m	optional	grid_topography, soil_properties, topounits	Average depth to bedrock of the subgrid; critical for groundwater dynamics.
binfl	topounit,lsmlat,lsmlon	unitless	optional	hydrology, topounits	VIC b parameter for the Variable Infiltration Capacity Curve; infiltration nonlinearity.
gdp	topounit,lsmlat,lsmlon	unitless	optional	anthropogenic, topounits	GDP (parameter); economic/anthropogenic activity indicator.
parEro_c1	topounit,lsmlat,lsmlon	unitless	optional	disturbance, grid_topography, topounits	Scalar parameter for rainfall-driven hillslope erosion; controls erosion from precipitation.
parEro_c2	topounit,lsmlat,lsmlon	unitless	optional	disturbance, grid_topography, hydrology, topounits	Scalar parameter for runoff-driven hillslope erosion; controls erosion from surface runoff.
parEro_c3	topounit,lsmlat,lsmlon	unitless	optional	disturbance, grid_topography, hydrology, topounits	Scalar parameter for transport capacity of hillslope overland flow; controls sediment transport capacity.
peatf	topounit,lsmlat,lsmlon	unitless	optional	land_cover, soil_properties, topounits	Peatland fraction; fraction of grid cell area classified as peat soils.
topoPerGrid	lsmlat,lsmlon	unitless	optional	grid_topography, topounits	Number of topounits in each grid cell; if absent, the number of topounits is set to 1.

Context: unstructured_grid

Variable	Dimensions	Units	Required level	Contexts	Description
xCell	lsmlat,lsmlon	unknown	optional	unstructured_grid	Unstructured grid coordinates (e.g., MPAS x) when using an irregular mesh; the code reads them only if they exist.
yCell	lsmlat,lsmlon	unknown	optional	unstructured_grid	Unstructured grid coordinates (e.g., MPAS y) when using an irregular mesh; the code reads them only if they exist.

Context: urban

Variable	Dimensions	Units	Required level	Contexts	Description
ALB_IMPROAD_DIF	numrad,numurbl,topounit,lsmlat,lsmlon	unitless	optional	topounits, urban	Diffuse albedo of impervious road; spectral-dependent surface reflectance for urban impervious surfaces.
ALB_IMPROAD_DIR	numrad,numurbl,topounit,lsmlat,lsmlon	unitless	optional	topounits, urban	Direct albedo of impervious road; spectral-dependent surface reflectance for urban impervious surfaces.
ALB_PERROAD_DIF	numrad,numurbl,topounit,lsmlat,lsmlon	unitless	optional	topounits, urban	Diffuse albedo of pervious road; spectral-dependent surface reflectance for urban pervious surfaces.
ALB_PERROAD_DIR	numrad,numurbl,topounit,lsmlat,lsmlon	unitless	optional	topounits, urban	Direct albedo of pervious road; spectral-dependent surface reflectance for urban pervious surfaces.
ALB_ROOF_DIF	numrad,numurbl,topounit,lsmlat,lsmlon	unitless	optional	topounits, urban	Diffuse albedo of roof; spectral-dependent surface reflectance for urban roof surfaces.
ALB_ROOF_DIR	numrad,numurbl,topounit,lsmlat,lsmlon	unitless	optional	topounits, urban	Direct albedo of roof; spectral-dependent surface reflectance for urban roof surfaces.
ALB_WALL_DIF	numrad,numurbl,topounit,lsmlat,lsmlon	unitless	optional	topounits, urban	Diffuse albedo of wall; spectral-dependent surface reflectance for urban wall surfaces.
ALB_WALL_DIR	numrad,numurbl,topounit,lsmlat,lsmlon	unitless	optional	topounits, urban	Direct albedo of wall; spectral-dependent surface reflectance for urban wall surfaces.
CANYON_HWR	numurbl,topounit,lsmlat,lsmlon	unitless	optional	topounits, urban	Canyon height to width ratio; urban geometric parameter affecting radiation and wind.
CV_IMPROAD	nlevurb,numurbl,topounit,lsmlat,lsmlon	J/m^3*K	optional	topounits, urban	Volumetric heat capacity of impervious road; thermal mass property affecting diurnal temperature variations.
CV_ROOF	nlevurb,numurbl,topounit,lsmlat,lsmlon	J/m^3*K	optional	topounits, urban	Volumetric heat capacity of roof; thermal mass property affecting building heat dynamics.
CV_WALL	nlevurb,numurbl,topounit,lsmlat,lsmlon	J/m^3*K	optional	topounits, urban	Volumetric heat capacity of wall; thermal mass property affecting wall temperature dynamics.
EM_IMPROAD	numurbl,topounit,lsmlat,lsmlon	unitless	optional	topounits, urban	Emissivity of impervious road; controls longwave radiation emission from urban surfaces.
EM_PERROAD	numurbl,topounit,lsmlat,lsmlon	unitless	optional	topounits, urban	Emissivity of pervious road; controls longwave radiation emission from pervious urban surfaces.
EM_ROOF	numurbl,topounit,lsmlat,lsmlon	unitless	optional	topounits, urban	Emissivity of roof; controls longwave radiation emission from building roof.
EM_WALL	numurbl,topounit,lsmlat,lsmlon	unitless	optional	topounits, urban	Emissivity of wall; controls longwave radiation emission from building walls.
HT_ROOF	numurbl,topounit,lsmlat,lsmlon	m	optional	topounits, urban	Height of roof; geometric property defining building structure.
NLEV_IMPROAD	numurbl,topounit,lsmlat,lsmlon	unitless	optional	topounits, urban	Number of impervious road layers; structural discretization for temperature calculation.
PCT_URBAN	numurbl,topounit,lsmlat,lsmlon	percent	conditional	land_cover, topounits, urban	Fraction of each grid cell that is urban, for each density class in the multi-density urban scheme. (Requirement: Required when the multi-density urban model is used (nlevurb > 0); optional otherwise)
THICK_ROOF	numurbl,topounit,lsmlat,lsmlon	m	optional	topounits, urban	Thickness of roof; structural property affecting heat capacity.
THICK_WALL	numurbl,topounit,lsmlat,lsmlon	m	optional	topounits, urban	Thickness of wall; structural property affecting heat capacity.
TK_IMPROAD	nlevurb,numurbl,topounit,lsmlat,lsmlon	W/m*K	optional	topounits, urban	Thermal conductivity of impervious road; controls heat diffusion through urban surface layers.
TK_ROOF	nlevurb,numurbl,topounit,lsmlat,lsmlon	W/m*K	optional	topounits, urban	Thermal conductivity of roof; controls heat transfer through building roof material.
TK_WALL	nlevurb,numurbl,topounit,lsmlat,lsmlon	W/m*K	optional	topounits, urban	Thermal conductivity of wall; controls heat transfer through building wall material.
T_BUILDING_MAX	numurbl,topounit,lsmlat,lsmlon	K	optional	topounits, urban	Maximum interior building temperature; upper limit constraint for urban heating/cooling.
T_BUILDING_MIN	numurbl,topounit,lsmlat,lsmlon	K	optional	topounits, urban	Minimum interior building temperature; lower limit constraint for urban heating/cooling.
URBAN_REGION_ID	topounit,lsmlat,lsmlon	unitless	conditional	topounits, urban	Integer identifier linking urban grid cells to regional urban morphology datasets. (Requirement: Required when PCT_URBAN is used; optional otherwise)
WIND_HGT_CANYON	numurbl,topounit,lsmlat,lsmlon	m	optional	topounits, urban	Height of wind in canyon; reference height for urban wind profile.
WTLUNIT_ROOF	numurbl,topounit,lsmlat,lsmlon	unitless	optional	topounits, urban	Fraction of roof; weight for urban landunit distribution.
WTROAD_PERV	numurbl,topounit,lsmlat,lsmlon	unitless	optional	topounits, urban	Fraction of pervious road; weight for pervious surface distribution.

Context: vegetation_structure

Variable	Dimensions	Units	Required level	Contexts	Description
EF1_BTR	topounit,lsmlat,lsmlon	unitless	optional	biogeochemistry, topounits, vegetation_structure	EF1 isoprene emission factor for broadleaf tree (BTR); vegetation-dependent emission rate.
EF1_CRP	topounit,lsmlat,lsmlon	unitless	optional	biogeochemistry, topounits, vegetation_structure	EF1 isoprene emission factor for crop (CRP); vegetation-dependent emission rate.
EF1_FDT	topounit,lsmlat,lsmlon	unitless	optional	biogeochemistry, topounits, vegetation_structure	EF1 isoprene emission factor for deciduous forest (FDT); vegetation-dependent emission rate.
EF1_FET	topounit,lsmlat,lsmlon	unitless	optional	biogeochemistry, topounits, vegetation_structure	EF1 isoprene emission factor for evergreen forest (FET); vegetation-dependent emission rate.
EF1_GRS	topounit,lsmlat,lsmlon	unitless	optional	biogeochemistry, topounits, vegetation_structure	EF1 isoprene emission factor for grass (GRS); vegetation-dependent emission rate.
EF1_SHR	topounit,lsmlat,lsmlon	unitless	optional	biogeochemistry, topounits, vegetation_structure	EF1 isoprene emission factor for shrub (SHR); vegetation-dependent emission rate.
MONTHLY_HEIGHT_BOT	time,lsmpft,topounit,lsmlat,lsmlon	m	optional	topounits, vegetation_structure	Monthly climatology of canopy bottom height (m) for vegetated landunits.
MONTHLY_HEIGHT_TOP	time,lsmpft,topounit,lsmlat,lsmlon	m	optional	topounits, vegetation_structure	Monthly climatology of canopy top height (m) for vegetated landunits.
MONTHLY_LAI	time,lsmpft,topounit,lsmlat,lsmlon	unitless	optional	topounits, vegetation_structure	Leaf area index (LAI; m2 leaf per m2 ground) monthly climatology; time is typically 12 months.
MONTHLY_SAI	time,lsmpft,topounit,lsmlat,lsmlon	unitless	optional	topounits, vegetation_structure	Stem area index (SAI) monthly climatology; time is typically 12 months.