Pre-Processing Reference Guide

This page defines the configurable pre-processing parameters available in FastEddy^® and provides a workflow image.

Parameters are organized by the JSON file in which they appear.

Each table provides the:

• Name

• Description

These definitions serve as a reference to ensure correct configuration.

See the FastEddy Pre-Processing Workflow Diagram* for a visual representation of the workflow.

geospec.json

Name	Description
name_dom	The base domain name string used as a prefix for output filenames.
gis_root	Path to the root directory containing GIS input files. Used as prefix for ‘gis_file’ and ‘landcover_table’.
gis_file	Filename of the input GIS netCDF file (relative to ‘gis_root’). Expected variable names depend on ‘gis_opt’.
landcover_table	Filename of the land cover CSV lookup table (relative to ‘gis_root’). Maps land cover categories to roughness length (z0). Used when gis_opt=0.
water_cats	List of integer land-cover class IDs to classify as water. Used to set SeaMask=1 at those cells. Only evaluated when gis_opt=0.
urban_opt	Enables urban building height processing. If 0: building height data is ignored. If 1: reads the BuildingHeights variable from the GIS file, replaces missing values (−9999) with 0, and writes it to the output netCDF. Must match the value used in the corresponding SimGrid run.
FE_dataset_path	Output directory where the GeoSpec netCDF and optional diagnostic plot are written. The directory must exist and be writable prior to execution.
name_dom_add	Optional suffix appended to ‘name_dom’ in output filenames (e.g., for versioning). Can be empty.
gis_opt	Selects the GIS input format and determines all downstream variable name mappings. If 0: reads lat, lon, elevation, LandCover. Derives z0 from ‘landcover_table’ CSV. Builds SeaMask from ‘water_cats’. If 1: (WRF-style dataset) reads XLAT, XLONG, HGT, LU_INDEX, ZNT, LANDMASK SeaMask convention is inverted (WRF LANDMASK=1 is land, output SeaMask=1 is sea).
save_plot_opt	Controls diagnostic plot generation. If 0: no plot is created. If 1: saves a 4-panel PNG showing terrain elevation, land cover, roughness length z0m, and SeaMask.

simgrid.json

Name	Description
name_dom	The base domain name string used as a prefix for output filenames.
FE_ref_GIS_nc	Full path to the GeoSpec output netCDF file produced by GeoSpec.py. This is a required upstream dependency.
FE_params_file	Full path to the FastEddy parameters file (.in) containing grid dimensions and resolution.
center_lat	Latitude (decimal degrees) of the desired simulation domain center. Used to locate the nearest point in the GIS dataset and anchor the simulation grid.
center_lon	Longitude (decimal degrees) of the desired simulation domain center. Used with ‘center_lat’ to define grid placement.
urban_opt	Enables urban building processing. If 0: building fields are not computed or written. If 1: reads BuildingHeights from the GeoSpec netCDF, constructs a 3-D building mask array (BuildingMask), and writes both to the output. Must match the value set in GeoSpec.
FE_new_nc_path	Output directory for the SimGrid netCDF, binary terrain file (name_dom_Topography_NxN.dat), and optional diagnostic plot. Created automatically if it does not exist.
name_dom_add	Optional suffix appended to ‘name_dom’ in output filenames. Can be empty.
urban_heatRedis_opt	Enables urban surface heat flux redistribution. Only evaluated when urban_opt=1. If 0: heat redistribution field is not computed. If 1: reads z0 lookup tables from ‘landcover_table’ and computes a 2-D UrbanHeatRedis field written to the output netCDF file.
landcover_table	Full path to the land-cover CSV lookup table. Only read when urban_opt=1 and urban_heatRedis_opt=1. Used to determine original and modified z0 values for heat flux redistribution over urban areas. Requires a fourth column with the modified z0 corresponding to surface vegetation only (excluding the building contribution).
topo_average_opt	Controls how terrain elevation is resampled from the GIS resolution to the simulation grid resolution. If 0: direct sampling or interpolation. Nearest-neighbor decimation when the simulation grid is an integer multiple of GIS resolution, spline interpolation otherwise. If 1: block averaging smooths sub-grid terrain variability (prevents aliasing).
save_plot_opt	Controls diagnostic plot generation. If 0: no plot is created. If 1: saves a 2-panel PNG showing vertical grid level profiles at the lowest- and highest-elevation points in the domain.

genicbcs.json

Name	Description
ICBC_dir	Output directory where initial condition and lateral boundary condition files are written (FE_Bndys.N and FE_interp_*.0). Created automatically if it does not exist. At startup, each MPI rank checks this directory and skips files that already exist.
FE_simGrid	Full path to the SimGrid output netCDF file created by SimGrid.py. Required upstream dependency to define the target interpolation grid.
parent_model	Selects the parent model that supplies boundary data and controls all variable name mappings and interpolation paths. If 0: WRF is the parent. Variables read: Z, ALT, U, V, W, T, QVAPOR, QCLOUD, QKE or TKE_PBL (not required), TSK, Q2. If 1: FastEddy is the parent. T Variables read: zPos, rho, u, v, w, theta, qv, ql, TKE_0, tskin, qskin.
nest_tke_opt	Controls how turbulent kinetic energy (TKE) is handled in the nested domain. If false: TKE_0 is set to a near-zero floor value (1×10⁻¹⁰ m^2/s^{-2}). If true: TKE is interpolated from the parent and clipped to the floor value to avoid negative or near-zero artifacts.

WRF as Parent Domain Section

Active only when parent_model=0.

Name	Description
WRF_PrntDir	Filename prefix for WRF output files, appearing before the timestamp in the filename (e.g., wrf_fasteddy_d01_ for wrf_fasteddy_d01_2024-02-16_17:00:00).
date0	Start date for the WRF file list in YYYY-MM-DD format. Combined with time* fields to form the initial timestamp.
timeHour0	Hour (UTC) of the first WRF output file to process.
timeMinute0	Minute (UTC) of the first WRF output file to process.
timeSecond0	Second (UTC) of the first WRF output file to process.
secMax	Total duration (seconds) to process WRF files.
secInc	Time increment (seconds) between WRF files. Must exactly match the actual WRF output interval or files will not be found.

FastEddy as Parent Domain Section

Active only when parent_model = 1.

Name	Description
FE_PrntDir	Directory containing parent FastEddy output files. Files are expected to be named as FE_PrntOutPrefix.TIMESTEP.
FE_PrntOutPrefix	Base filename of the parent FastEddy output series. The integer timestep index is appended after a period.
itMin	Starting timestep index of the parent FastEddy file series.
dt_FE	Parent FastEddy model timestep (seconds). Used to convert between timestep index and physical time. Must match the timestep used in the parent simulation exactly.
outputFrequency	Output interval of FastEddy data. Used to compute timestep increment.
timeLengthSec	Total simulation time (seconds) to process for FastEddy input.
ideal_opt	Flag for idealized (non-real-data) simulations. If true: use Cartesian coordinates (xPos, yPos). If false: use lat/lon-based interpolation.