27. FV3 physics tendencies

27.1. Description

Plot tendencies of temperature, moisture, and wind components averaged over a time window and spatial domain. Tendencies are partitioned into physics parameterizations and dynamics. Physics parameterizations include schemes like deep convection, convective gravity wave drag, short wave radiation, planetary boundary layer, microphysics, and others listed below. Non-physics tendencies (or dynamics) are due to horizontal and vertical motion (advection).

residual = all tendencies - actual change

The residual (which should be close to zero) is the difference between the actual change in the state variable over the requested time window and the combined change due to all physics parameterizations and dynamics tendencies. One can plot a single tendency component at multiple pressure levels or plot all tendency components at a single pressure level. Plan views (horizontal cross sections), vertical profiles, and vertical cross sections are also available.

27.2. Required Packages:

  • cartopy

  • matplotlib

  • metpy

  • numpy

  • pandas

  • shapely

  • xarray

27.3. Required input:

  1. FV3 3-D history file with physics and dynamics tendencies (fv3_history.nc)

  2. FV3 2-D grid specification file with latititude and longitude of each grid point (grid_spec.nc)

Download the fv3_history.nc and grid_spec.nc files

Save to $DATA_DIR directory where you have read and write permissions.

For additional details see grid description in UFS Short Range Weather App user manual

27.3.1. Default tendency variable names

Default tendency variable names are below. The tendencies that are available depend on the physics suite that the user selects when running FV3; more specifically, its contents are determined by the diag_table file that the user sets up. The history file that we use our example is for a specific diag_table and so may change with different FV3 configurations. The user must make sure the names in the configuration file $METPLOTPY_BASE/test/fv3_physics_tend/fv3_physics_tend_defaults.yaml match the names used in fv3_history.nc for their case. Some tendencies do not apply to all four state variables, so these cells are left blank.

NOTE: $METPLOTPY_BASE is the directory where the METplotpy code is saved (e.g. /path/to/user/dir/METplotpy).

State Variable

temperature

specific humidity

u-wind

v-wind

typical name

tmp

spfh

ugrd

vgrd

Typical Tendency variable names (change in config file if your case is different)

Tendency Variable

temperature

specific humidity

u-wind

v-wind

convective gravity wave drag

dtend_temp_cnvgwd

dtend_u_cnvgwd

dtend_v_cnvgwd

deep convection

dtend_temp_deepcnv

dtend_qv_deepcnv

dtend_u_deepcnv

dtend_v_deepcnv

long wave radiation

dtend_temp_lw

microphysics

dtend_temp_mp

dtend_qv_mp

orographic gravity wave drag

dtend_temp_orogwd

dtend_u_orogwd

dtend_v_orogwd

planetary boundary layer

dtend_temp_pbl

dtend_qv_pbl

dtend_u_pbl

dtend_v_pbl

Rayleigh damping

dtend_temp_rdamp

dtend_u_rdamp

dtend_v_rdamp

shallow convection

dtend_temp_shalcnv

dtend_qv_shalcnv

dtend_u_shalcnv

dtend_v_shalcnv

short wave radiation

dtend_temp_sw

all physics tendencies

dtend_temp_phys

dtend_qv_phys

dtend_u_phys

dtend_v_phys

dynamics (advection)

dtend_temp_nophys

dtend_qv_nophys

dtend_u_nophys

dtend_v_nophys

Derived tendency variables that show up in plots:

Derived Variable

temperature

specific humidity

u-wind

v-wind

all phys and nophys

all

all

all

all

actual change

actual

actual

actual

actual

residual (all - actual)

resid

resid

resid

resid

27.3.2. If time window overlaps initialization time

The history file does not necessarily have the temperature, moisture, or wind at the exact time of model initialization. It is usally the next timestep (e.g. 180 seconds later). This means you cannot derive the actual change in temperature starting at the model initialization time. You must choose a later valid time and/or a shorter time window that does not overlap the initialization time. In other words, it is a problem if your model initialization time is 0z, your valid time is 1z and your time window is one hour.

27.4. Example

27.4.1. Configuration File

$METPLOTPY_BASE is the directory where the METplotpy code is saved.

27.5. Run from the Command Line

The example tendency plots use the settings in the following YAML configuration files (located in the $METPLOTPY_BASE/test/fv3_physics_tend directory):

tmp_500hPa.yaml

# Names of tendency variables in model output (i.e. FV3 history file)
# Each type of tendency (moisture, temperature, wind component) has its own set of variables.
tendency_varnames:
    spfh:
    - dtend_qv_pbl
    - dtend_qv_deepcnv
    - dtend_qv_shalcnv
    - dtend_qv_mp
    - dtend_qv_phys
    - dtend_qv_nophys
    tmp:
    - dtend_temp_lw
    - dtend_temp_sw
    - dtend_temp_pbl
    - dtend_temp_deepcnv
    - dtend_temp_shalcnv
    - dtend_temp_mp
    - dtend_temp_orogwd
    - dtend_temp_cnvgwd
    - dtend_temp_phys
    - dtend_temp_nophys
    ugrd:
    - dtend_u_pbl
    - dtend_u_orogwd
    - dtend_u_deepcnv
    - dtend_u_cnvgwd
    - dtend_u_shalcnv
    - dtend_u_phys
    - dtend_u_nophys
    vgrd:
    - dtend_v_pbl
    - dtend_v_orogwd
    - dtend_v_deepcnv
    - dtend_v_cnvgwd
    - dtend_v_shalcnv
    - dtend_v_phys
    - dtend_v_nophys



# Name of the longitude and latitude variables in the grid specification file.
lon_name : "grid_lont"
lat_name : "grid_latt"


# Geographic extent (in degrees) of 2-D plots.
# (lonmin, lonmax, latmin, latmax)  
extent:
    - -122
    - -72.7
    - 22.1
    - 49.5

# Found FV3 standard_parallel by trial and error with smaller and smaller tolerances given to mepy.assign_y_x(). longitude is mean.
standard_parallel : 38.139

# color map
cmap : "RdBu_r"

# coordinate reference system used in cross_section_vert .metpy.assign_crs(crs).metpy.assign_y_x
crs : null

# True : more logging messages
debug : False

# resolution (dots per inch) of output
dpi : 100

# number of columns in FacetGrid
ncols : null

# Add metadata and `created by` date (for comparing images)
fineprint : False

# pressure levels in hPa to plot. Levels must be on different line
# from pfull indicating an array, even if only one element.
# If only one pressure level is provided, the type-of-tendency
# argument will be ignored and all tendencies will be plotted.
pfull :
    - 500

# compute colormap range with extremes, not 2nd and 98th percentiles
robust : True

# selection method for vertical pressure level
# "nearest" : select the nearest level to the specified pressure level
# "linear" : interpolate the two nearest levels to the specified pressure level
# "loglinear" : interpolate the two nearest levels to the specified pressure level in log10(pressure)
sel_method : "nearest"

# shape file directory for mask
shp : null

# start  lat lon of vertical cross section
startpt :
    - 28
    - -120

# end  lat lon of vertical cross section
endpt :
    - 26
    - -75

statevarname : "tmp"

# Accumulated tendencies were zeroed and divided by time since last output.
tendencies_were_zeroed_and_averaged_after_every_output : True

tendencytype : "pbl"

# time window in hours
twindow : 1

# Valid time
validtime : "20190615T20"

# color bar minimum (overrides robust=True)
vmin : null

# color bar maximum (overrides robust=True)
vmax : null

# x-axis minimum
xmin : -0.0002

# x-axis maximum
xmax : 0.0002

tmp_pbl.yaml

# Names of tendency variables in model output (i.e. FV3 history file)
# Each type of tendency (moisture, temperature, wind component) has its own set of variables.
tendency_varnames:
    spfh:
    - dtend_qv_pbl
    - dtend_qv_deepcnv
    - dtend_qv_shalcnv
    - dtend_qv_mp
    - dtend_qv_phys
    - dtend_qv_nophys
    tmp:
    - dtend_temp_lw
    - dtend_temp_sw
    - dtend_temp_pbl
    - dtend_temp_deepcnv
    - dtend_temp_shalcnv
    - dtend_temp_mp
    - dtend_temp_orogwd
    - dtend_temp_cnvgwd
    - dtend_temp_phys
    - dtend_temp_nophys
    ugrd:
    - dtend_u_pbl
    - dtend_u_orogwd
    - dtend_u_deepcnv
    - dtend_u_cnvgwd
    - dtend_u_shalcnv
    - dtend_u_phys
    - dtend_u_nophys
    vgrd:
    - dtend_v_pbl
    - dtend_v_orogwd
    - dtend_v_deepcnv
    - dtend_v_cnvgwd
    - dtend_v_shalcnv
    - dtend_v_phys
    - dtend_v_nophys



# Name of the longitude and latitude variables in the grid specification file.
lon_name : "grid_lont"
lat_name : "grid_latt"


# Geographic extent (in degrees) of 2-D plots.
# (lonmin, lonmax, latmin, latmax)  
extent:
    - -122
    - -72.7
    - 22.1
    - 49.5

# Found FV3 standard_parallel by trial and error with smaller and smaller tolerances given to mepy.assign_y_x(). longitude is mean.
standard_parallel : 38.139

# color map
cmap : "RdBu_r"

# coordinate reference system used in cross_section_vert .metpy.assign_crs(crs).metpy.assign_y_x
crs : null

# True : more logging messages
debug : False

# resolution (dots per inch) of output
dpi : 100

# number of columns in FacetGrid
ncols : null

# Add metadata and `created by` date (for comparing images)
fineprint : False

# pressure levels in hPa to plot. Levels must be on different line
# from pfull indicating an array, even if only one element.
# If only one pressure level is provided, the type-of-tendency
# argument will be ignored and all tendencies will be plotted.
pfull :
    - 1000
    - 925
    - 850
    - 700
    - 500
    - 300
    - 200
    - 100
    - 0

# compute colormap range with extremes, not 2nd and 98th percentiles
robust : True

# selection method for vertical pressure level
# "nearest" : select the nearest level to the specified pressure level
# "linear" : interpolate the two nearest levels to the specified pressure level
# "loglinear" : interpolate the two nearest levels to the specified pressure level in log10(pressure)
sel_method : "nearest"

# shape file directory for mask
shp : null

# start  lat lon of vertical cross section
startpt :
    - 28
    - -120

# end  lat lon of vertical cross section
endpt :
    - 26
    - -75

statevarname : "tmp"

# Accumulated tendencies were zeroed and divided by time since last output.
tendencies_were_zeroed_and_averaged_after_every_output : True

tendencytype : "pbl"

# time window in hours
twindow : 1

# Valid time
validtime : "20190615T20"

# color bar minimum (overrides robust=True)
vmin : null

# color bar maximum (overrides robust=True)
vmax : null

# x-axis minimum
xmin : -0.0002

# x-axis maximum
xmax : 0.0002

tmp.vert_profile.MID_CONUS.yaml

# Names of tendency variables in model output (i.e. FV3 history file)
# Each type of tendency (moisture, temperature, wind component) has its own set of variables.
tendency_varnames:
    spfh:
    - dtend_qv_pbl
    - dtend_qv_deepcnv
    - dtend_qv_shalcnv
    - dtend_qv_mp
    - dtend_qv_phys
    - dtend_qv_nophys
    tmp:
    - dtend_temp_lw
    - dtend_temp_sw
    - dtend_temp_pbl
    - dtend_temp_deepcnv
    - dtend_temp_shalcnv
    - dtend_temp_mp
    - dtend_temp_orogwd
    - dtend_temp_cnvgwd
    - dtend_temp_phys
    - dtend_temp_nophys
    ugrd:
    - dtend_u_pbl
    - dtend_u_orogwd
    - dtend_u_deepcnv
    - dtend_u_cnvgwd
    - dtend_u_shalcnv
    - dtend_u_phys
    - dtend_u_nophys
    vgrd:
    - dtend_v_pbl
    - dtend_v_orogwd
    - dtend_v_deepcnv
    - dtend_v_cnvgwd
    - dtend_v_shalcnv
    - dtend_v_phys
    - dtend_v_nophys



# Name of the longitude and latitude variables in the grid specification file.
lon_name : "grid_lont"
lat_name : "grid_latt"


# Geographic extent (in degrees) of 2-D plots.
# (lonmin, lonmax, latmin, latmax)  
extent:
    - -122
    - -72.7
    - 22.1
    - 49.5

# Found FV3 standard_parallel by trial and error with smaller and smaller tolerances given to mepy.assign_y_x(). longitude is mean.
standard_parallel : 38.139

# color map
cmap : "RdBu_r"

# coordinate reference system used in cross_section_vert .metpy.assign_crs(crs).metpy.assign_y_x
crs : null

# True : more logging messages
debug : False

# resolution (dots per inch) of output
dpi : 100

# number of columns in FacetGrid
ncols : null

# Add metadata and `created by` date (for comparing images)
fineprint : False

# pressure levels in hPa to plot. Levels must be on different line
# from pfull indicating an array, even if only one element.
# If only one pressure level is provided, the type-of-tendency
# argument will be ignored and all tendencies will be plotted.
pfull :
    - 500

# compute colormap range with extremes, not 2nd and 98th percentiles
robust : True

# selection method for vertical pressure level
# "nearest" : select the nearest level to the specified pressure level
# "linear" : interpolate the two nearest levels to the specified pressure level
# "loglinear" : interpolate the two nearest levels to the specified pressure level in log10(pressure)
sel_method : "nearest"

# shape file directory for mask
shp : "shapefiles/MID_CONUS"

# start  lat lon of vertical cross section
startpt :
    - 28
    - -120

# end  lat lon of vertical cross section
endpt :
    - 26
    - -75

statevarname : "tmp"

# Accumulated tendencies were zeroed and divided by time since last output.
tendencies_were_zeroed_and_averaged_after_every_output : True

tendencytype : "pbl"

# time window in hours
twindow : 1

# Valid time
validtime : "20190615T20"

# color bar minimum (overrides robust=True)
vmin : null

# color bar maximum (overrides robust=True)
vmax : null

# x-axis minimum
xmin : -0.0002

# x-axis maximum
xmax : 0.0002

ugrd_cross_section.yaml

# Names of tendency variables in model output (i.e. FV3 history file)
# Each type of tendency (moisture, temperature, wind component) has its own set of variables.
tendency_varnames:
    spfh:
    - dtend_qv_pbl
    - dtend_qv_deepcnv
    - dtend_qv_shalcnv
    - dtend_qv_mp
    - dtend_qv_phys
    - dtend_qv_nophys
    tmp:
    - dtend_temp_lw
    - dtend_temp_sw
    - dtend_temp_pbl
    - dtend_temp_deepcnv
    - dtend_temp_shalcnv
    - dtend_temp_mp
    - dtend_temp_orogwd
    - dtend_temp_cnvgwd
    - dtend_temp_phys
    - dtend_temp_nophys
    ugrd:
    - dtend_u_pbl
    - dtend_u_orogwd
    - dtend_u_deepcnv
    - dtend_u_cnvgwd
    - dtend_u_shalcnv
    - dtend_u_phys
    - dtend_u_nophys
    vgrd:
    - dtend_v_pbl
    - dtend_v_orogwd
    - dtend_v_deepcnv
    - dtend_v_cnvgwd
    - dtend_v_shalcnv
    - dtend_v_phys
    - dtend_v_nophys



# Name of the longitude and latitude variables in the grid specification file.
lon_name : "grid_lont"
lat_name : "grid_latt"


# Geographic extent (in degrees) of 2-D plots.
# (lonmin, lonmax, latmin, latmax)  
extent:
    - -122
    - -72.7
    - 22.1
    - 49.5

# Found FV3 standard_parallel by trial and error with smaller and smaller tolerances given to mepy.assign_y_x(). longitude is mean.
standard_parallel : 38.139

# color map
cmap : "RdBu_r"

# coordinate reference system used in cross_section_vert .metpy.assign_crs(crs).metpy.assign_y_x
crs : null

# True : more logging messages
debug : False

# resolution (dots per inch) of output
dpi : 100

# number of columns in FacetGrid
ncols : null

# Add metadata and `created by` date (for comparing images)
fineprint : False

# pressure levels in hPa to plot. Levels must be on different line
# from pfull indicating an array, even if only one element.
# If only one pressure level is provided, the type-of-tendency
# argument will be ignored and all tendencies will be plotted.
pfull :
    - 500

# compute colormap range with extremes, not 2nd and 98th percentiles
robust : True

# selection method for vertical pressure level
# "nearest" : select the nearest level to the specified pressure level
# "linear" : interpolate the two nearest levels to the specified pressure level
# "loglinear" : interpolate the two nearest levels to the specified pressure level in log10(pressure)
sel_method : "nearest"

# shape file directory for mask
shp : null # "shapefiles/MID_CONUS"

# start  lat lon of vertical cross section
startpt :
    - 28
    - -120

# end  lat lon of vertical cross section
endpt :
    - 26
    - -75

statevarname : "ugrd"

# Accumulated tendencies were zeroed and divided by time since last output.
tendencies_were_zeroed_and_averaged_after_every_output : True

tendencytype : "pbl"

# time window in hours
twindow : 1

# Valid time
validtime : "20190615T20"

# color bar minimum (overrides robust=True)
vmin : null

# color bar maximum (overrides robust=True)
vmax : null

# x-axis minimum
xmin : -0.0002

# x-axis maximum
xmax : 0.0002

27.5.1. Plan View

Generate a plan view of all temperature tendencies at 500 hPa. Settings in config file:

pfull :
    - 500
shp : null
statevarname : "tmp"

python planview_fv3.py $CONFIG_DIR/tmp_500hPa.yaml $DATA_DIR/fv3_history.nc $DATA_DIR/grid_spec.nc

The plot tmp_500hPa.png will be saved in the directory where the command was issued.

../_images/tmp_500hPa.png

Generate a plan view of PBL tendency at specified pressure levels. Set pfull to an array of levels in config file:

pfull :
    - 1000
    - 925
    - 850
    - 700
    - 500
    - 300
    - 200
    - 100
    - 0

python planview_fv3.py $CONFIG_DIR/tmp_pbl.yaml $DATA_DIR/fv3_history.nc $DATA_DIR/grid_spec.nc

The plot tmp_pbl.png will be saved in the directory where the command was issued.

../_images/tmp_pbl.png

27.5.2. Vertical Profile

Generate vertical profile of temperature tendencies averaged over the central US. Plot residual tendency and its components. Limit the x-axis range with xmin and xmax. Settings in config file:

shp : "shapefiles/MID_CONUS"
xmin : -0.0002
xmax : 0.0002

python vert_profile_fv3.py $CONFIG_DIR/tmp.vert_profile.MID_CONUS.yaml $DATA_DIR/fv3_history.nc $DATA_DIR/grid_spec.nc

The plot tmp.vert_profile.MID_CONUS.png will be saved in the directory where the command was issued.

../_images/tmp.vert_profile.MID_CONUS.png

27.5.3. Vertical Cross Section

Generate vertical cross section of u-wind tendencies from 28°N 120°W to 26°N 75°W over one-hour time window ending 20z June 15, 2019. Settings in config file:

statevarname : "ugrd"
startpt :
   - 28
   - -120
endpt :
   - 26
   - -75

python cross_section_vert.py $CONFIG_DIR/ugrd_cross_section.yaml $DATA_DIR/fv3_history.nc $DATA_DIR/grid_spec.nc

The plot ugrd_28.0N-120.0E-26.0N-75.0E.png will be saved in the directory where the command was issued.

../_images/ugrd_28.0N-120.0E-26.0N-75.0E.png