2D sampled-level output¶

ERF can append fields sampled on model-index, height, or pressure targets to a 2D output stream. Use a named level set to define the vertical coordinate, targets, fields, interpolation rule, and missing value.

For example, this configuration samples potential temperature, temperature, water vapor, and cloud water at 850, 700, and 500 hPa:

erf.plot2d_level_sets_1 = upper_air

erf.plot2d.level_set.upper_air.coordinate = pressure
erf.plot2d.level_set.upper_air.units = hPa
erf.plot2d.level_set.upper_air.values = 850 700 500
erf.plot2d.level_set.upper_air.fields = theta temp qv qc

ERF appends these fields after the fixed diagnostics selected for stream 1. It does not extrapolate beyond the model column.

Configuring a level set¶

The level-set keys define the coordinate, target values, fields, interpolation, and missing-value behavior for a named set.

Select sampled level sets for each 2D output stream with:

erf.plot2d_level_sets_1 = upper_air bl_heights
erf.plot2d_level_sets_2 = native_k

Define each level set under erf.plot2d.level_set.<name>..

Required keys:

erf.plot2d.level_set.<name>.coordinate = ...
erf.plot2d.level_set.<name>.values = ...
erf.plot2d.level_set.<name>.fields = ...

Optional keys:

erf.plot2d.level_set.<name>.units = ...
erf.plot2d.level_set.<name>.interpolation = ...
erf.plot2d.level_set.<name>.missing_value = ...

The default missing value is -999. ERF does not extrapolate sampled-level diagnostics. If a target lies outside the column, ERF writes the level set’s missing value.

Supported vertical coordinates¶

Coordinate	Meaning	Units	Interpolation
`model_index`	Cell-centered model level index.	`1`	`none`
`height_msl`	Cell-centered height above mean sea level.	`m`	`linear`
`height_agl`	Cell-centered height above local terrain.	`m`	`linear`
`pressure`	Cell-centered pressure.	`Pa` or `hPa`	`linear`

ERF converts pressure targets in hPa to canonical Pa values in metadata. Model-index values must be integers. ERF rejects unsupported coordinates and units during input parsing. Isentropic output is not enabled because it needs a crossing policy for non-monotonic potential-temperature columns.

Supported fields¶

Field	Meaning	Units	Availability
`rho`	Density.	`kg m^-3`	Always available.
`theta`	Potential temperature.	`K`	Always available.
`temp`	Temperature.	`K`	Always available.
`pressure`	Pressure.	`Pa`	Always available.
`height_msl`	Height above mean sea level.	`m`	Always available.
`height_agl`	Height above local terrain.	`m`	Always available.
`qv`	Water vapor mixing ratio.	`kg kg^-1`	Available when the active moisture model has `qv`.
`qc`	Cloud liquid water mixing ratio.	`kg kg^-1`	Available when the active moisture model has `qc`.
`qi`	Cloud ice mixing ratio.	`kg kg^-1`	Available when the active moisture model has `qi`.
`qr`	Rain mixing ratio.	`kg kg^-1`	Available when the active moisture model has `qr`.
`qs`	Snow mixing ratio.	`kg kg^-1`	Available when the active moisture model has `qs`.
`qg`	Graupel mixing ratio.	`kg kg^-1`	Available when the active moisture model has `qg`.
`u_east`	Eastward wind.	`m/s`	Always available.
`v_north`	Northward wind.	`m/s`	Always available.
`w`	Vertical wind.	`m/s`	Always available.
`wind_speed`	Horizontal wind speed.	`m/s`	Always available.
`wind_dir`	Meteorological wind direction.	`degrees`	Always available. ERF writes the missing value for calm winds.

Use the canonical sampled species names qv, qc, qi, qr, qs, and qg. Do not use 3D derived-variable aliases such as qrain, qsnow, or qgraup in sampled-level output.

If a requested moisture field is unavailable for the active moisture model, ERF warns and skips that field. If all requested fields in a level set are unavailable, ERF aborts with an input error.

Output names and ordering¶

Sampled-level output names follow this pattern:

<field>_<coordinate_tag>_<value_tag>

Examples include theta_p_850hPa, qv_p_700hPa, qc_z_agl_500m, theta_z_msl_1000m, theta_k_10, u_east_p_850hPa, v_north_p_850hPa, w_z_agl_500m, wind_speed_k_10, wind_speed_z_agl_500m, and wind_dir_k_10.

ERF writes sampled-level variables after built-in variables in the same 2D stream. Within sampled-level output, ERF writes variables in level-set order, target-value order, and field order.

Interpolation and missing values¶

For linear sampling, ERF finds adjacent cell centers \(k_0\) and \(k_1\) that bracket the target coordinate \(C_t\).

\[F_t = (1 - w) F_{k_0} + w F_{k_1}\]

with

\[w = \frac{C_t - C_{k_0}}{C_{k_1} - C_{k_0}}.\]

The bracket test works for increasing coordinates, such as height, and decreasing coordinates, such as pressure. Model-index sampling copies the requested level exactly.

Moisture fields¶

Microphysical mass species are sampled as mixing ratios. ERF stores each species as a conserved density \(\rho q_x\), so sampled output uses

\[q_x = \frac{\rho q_x}{\rho}.\]

ERF uses qv = 0 for dry-run pressure and temperature calculations, but it does not expose sampled qv unless the active moisture model has a water-vapor state component.

Wind fields¶

Wind fields are cell-centered sampled-level diagnostics. ERF destaggers the native face-centered velocity components to scalar cell centers before vertical sampling. u_east and v_north are earth-relative horizontal winds. When map-rotation coefficients are available, ERF rotates grid-relative horizontal winds before output. Otherwise, ERF uses identity rotation. w is the cell-centered vertical wind.

wind_speed is the horizontal speed computed from u_east and v_north. wind_dir is the meteorological wind direction in degrees clockwise from north, indicating where the wind comes from. ERF writes the level-set missing value for wind_dir when the horizontal wind is calm. wind_dir is derived from the interpolated vector; ERF does not vertically interpolate wind direction as a scalar angle.

AMReX metadata and NetCDF limitations¶

Sampled-level metadata records source_field and vertical_coordinate in the native AMReX 2DMetadata.json sidecar. NetCDF 2D output uses the same sampled-level variable names, but it does not write sampled-level metadata attributes.

The sampled-level record has this form:

{
  "format_version": 2,
  "kind": "ERF 2D plotfile metadata",
  "n_variables": 1,
  "variables": [
    {
      "component_index": 0,
      "name": "theta_p_850hPa",
      "long_name": "Potential temperature sampled on pressure levels",
      "units": "K",
      "category": "SampledLevel",
      "missing_policy": "FillMinus999WhenUnavailable",
      "missing_value": -999,
      "source_field": "theta",
      "vertical_coordinate": {
        "type": "pressure",
        "value": 850,
        "units": "hPa",
        "canonical_value": 85000,
        "canonical_units": "Pa",
        "interpolation": "linear"
      }
    }
  ]
}

Additional examples¶

Height-above-ground example:

erf.plot2d_level_sets_1 = bl_heights

erf.plot2d.level_set.bl_heights.coordinate = height_agl
erf.plot2d.level_set.bl_heights.values = 100 500 1000
erf.plot2d.level_set.bl_heights.fields = theta qv qc

Model-index example:

erf.plot2d_level_sets_1 = native_k

erf.plot2d.level_set.native_k.coordinate = model_index
erf.plot2d.level_set.native_k.values = 0 10 20
erf.plot2d.level_set.native_k.fields = theta qv qc

Wind example:

erf.plot2d_level_sets_1 = upper_air_winds

erf.plot2d.level_set.upper_air_winds.coordinate = pressure
erf.plot2d.level_set.upper_air_winds.units = hPa
erf.plot2d.level_set.upper_air_winds.values = 850 700
erf.plot2d.level_set.upper_air_winds.fields = u_east v_north wind_speed wind_dir

Current limitations¶

Isentropic levels, vorticity, potential vorticity, and staggered velocity fields need additional sampling rules. They are not part of this sampled-level output mode.