User API

Routines

Diagnostic Routine

The routine below is the primary routine for extracting variables from a WRF-ARW NetCDF file (or sequence of files) and performing diagnostic calculations.

wrf.getvar Returns basic diagnostics from the WRF ARW model output.

Interpolation Routines

The routines below are the primary routines used for performing interpolation calculations.

wrf.interplevel Return the three-dimensional field interpolated to a horizontal plane at the specified vertical level.
wrf.vertcross Return the vertical cross section for a three-dimensional field.
wrf.interpline Return the two-dimensional field interpolated along a line.
wrf.vinterp Return the field vertically interpolated to the given the type of surface and a set of new levels.

Lat-Lon to/from XY Routines

The routines below are used for converting back and forth between xy-grid space and latitude-longitude space.

wrf.ll_to_xy Return the x,y coordinates for a specified latitude and longitude.
wrf.xy_to_ll Return the latitude and longitude for specified x,y coordinates.
wrf.ll_to_xy_proj Return the x, y coordinates for a specified latitude and longitude.
wrf.xy_to_ll_proj Return the latitude and longitude for the specified x,y coordinates.

Grid Destaggering Routine

The routine below is used to convert a variable on a staggered grid to the unstaggered grid.

wrf.destagger Return the variable on the unstaggered grid.

Numpy Extraction Routine

The routine below is used to extract a numpy.ndarray from a xarray.DataArray. This routine must be used before passing the array object to a compiled extension.

wrf.to_np Return the numpy.ndarray contained in an xarray.DataArray instance.

Variable Extraction Routines

The routines below are primarily used internally by wrf.getvar(), but some users may find them useful to manually extract variables from a WRF NetCDF file (or a sequence of NetCDF files).

wrf.extract_vars Extract variables from a NetCDF file object or a sequence of NetCDF file objects.
wrf.combine_files Combine and return an array object for the sequence of WRF output files.
wrf.extract_dim Return the dimension size for the specified dimension name.
wrf.extract_global_attrs Return the global attribute(s).
wrf.extract_times Return a sequence of time objects.

Plotting Helper Routines

The routines below are used to assist with plotting.

wrf.geo_bounds Return the geographic boundaries for the variable or file(s).
wrf.latlon_coords Return the latitude and longitude coordinates from a xarray.DataArray object.
wrf.get_cartopy Return a cartopy.crs.Projection subclass for the map projection.
wrf.get_basemap Return a matplotlib.mpl_toolkits.basemap.Basemap object
wrf.get_pyngl Return a Ngl.Resources object for the map projection.
wrf.cartopy_xlim Return the x-axis limits in the projected coordinates.
wrf.cartopy_ylim Return the y-axis limits in the projected coordinates.

Raw Diagnostic Routines

The routines below can be used when working with variables that are not contained in a WRF-ARW NetCDF file. They can also be used with non-WRF data. However, if you are working with WRF-ARW NetCDF files, use wrf.getvar() instead.

Keep in mind that these routines were developed for WRF-ARW, so your mileage may vary when working with non-WRF data. Also, the vast majority of these routines do not allow for missing values in any of the input arrays, so make sure they are removed before calling these routines.

wrf.xy Return the x,y points for a line within a two-dimensional grid.
wrf.interp1d Return the linear interpolation of a one-dimensional variable.
wrf.interp2dxy Return a cross section for a three-dimensional field.
wrf.interpz3d Return the field interpolated to a specified pressure or height level.
wrf.slp Return the sea level pressure.
wrf.tk Return the temperature.
wrf.td Return the dewpoint temperature.
wrf.rh Return the relative humidity.
wrf.uvmet Return the u,v components of the wind rotated to earth coordinates.
wrf.smooth2d Return the field smoothed.
wrf.cape_2d Return the two-dimensional MCAPE, MCIN, LCL, and LFC.
wrf.cape_3d Return the three-dimensional CAPE and CIN.
wrf.cloudfrac Return the cloud fraction.
wrf.ctt Return the cloud top temperature.
wrf.dbz Return the simulated radar reflectivity.
wrf.srhel Return the storm relative helicity.
wrf.udhel Return the updraft helicity.
wrf.avo Return the absolute vorticity.
wrf.pvo Return the potential vorticity.
wrf.eth Return the equivalent potential temperature.
wrf.wetbulb Return the wetbulb temperature.
wrf.tvirtual Return the virtual temperature.
wrf.omega Return omega.
wrf.pw Return the precipitable water.

OpenMP Runtime Library Routines

The routines below are the OpenMP runtime libraries that have been wrapped for wrf-python. The entire library (OpenMP 3.x) has been wrapped, but many of the routines are only useful inside of an OpenMP thread, so they aren’t useful from inside the Python interpreter. Also, the Fortran code in wrf-python is fairly simple in terms of threading, so features like nested threads aren’t used. The documentation below is split in to the useful OpenMP functions and the less useful functions.

The documentation for each routine was taken directly from the OpenMP Specification. Read the specification for more details about these routines.

Useful OpenMP Routines

The routines below are useful when called from within a Python program. These routines handle setting the number of threads, setting up the scheduler, and timing.

It is also important to note that the OpenMP directives within the Fortran code all specify a runtime scheduler. This means that the user can control the type of scheduling to use from within their Python application by using the routines below.

wrf.omp_enabled Return True if OpenMP is enabled.
wrf.omp_set_num_threads Specify the number of threads to use.
wrf.omp_get_max_threads Return the maximum number of threads that can be used in a parallel region.
wrf.omp_get_num_procs Return the number of processors on the device.
wrf.omp_set_dynamic Enable or disable dynamic adjustment of the number of threads available for the execution of subsequent parallel regions by setting the value of the dyn-var ICV.
wrf.omp_get_dynamic Return the value of the dyn-var ICV, which determines whether dynamic adjustment of the number of threads is enabled or disabled.
wrf.omp_set_schedule Set the schedule that is applied when runtime is used as schedule kind, by setting the value of the run-sched-var ICV.
wrf.omp_get_schedule Return the schedule that is applied when the runtime schedule is used.
wrf.omp_get_thread_limit Return the maximum number of OpenMP threads available to participate in the current contention group.
wrf.omp_get_wtime Return elapsed wall clock time in seconds.
wrf.omp_get_wtick Return the precision of the timer used by wrf.omp_get_wtime().

Less Useful OpenMP Routines

The routines below are less useful because wrf-python does not use nested parallelism and some of the routines are only applicable when called from within an OpenMP thread.

wrf.omp_get_num_threads Return the number of threads in the current team.
wrf.omp_get_thread_num Return the thread number, within the current team, of the calling thread.
wrf.omp_in_parallel Return 1 if the active-levels-var ICV is greater than zero; otherwise, return 0.
wrf.omp_set_nested Enable or disable nested parallelism, by setting the nest-var ICV
wrf.omp_get_nested Return the value of the nest-var ICV, which determines if nested parallelism is enabled or disabled
wrf.omp_set_max_active_levels Limit the number of nested active parallel regions on the device, by setting the max-active-levels-var ICV.
wrf.omp_get_max_active_levels Return the value of the max-active-levels-var ICV, which determines the maximum number of nested active parallel regions on the device
wrf.omp_get_level Return the value of the levels-var ICV.
wrf.omp_get_ancestor_thread_num Return, for a given nested level of the current thread, the thread number of the ancestor of the current thread.
wrf.omp_get_team_size Return, for a given nested level of the current thread, the size of the thread team to which the ancestor or the current thread belongs
wrf.omp_get_active_level Return the value of the active-level-vars ICV.
wrf.omp_in_final Return 1 (True) if the routine is executed in a final task region; otherwise, it returns 0 (False).
wrf.omp_init_lock Initialize a simple OpenMP lock.
wrf.omp_init_nest_lock Initialize a nestable OpenMP lock.
wrf.omp_destroy_lock Destroy a simple OpenMP lock.
wrf.omp_destroy_nest_lock Destroy a nestable OpenMP lock.
wrf.omp_set_lock Set a simple OpenMP lock.
wrf.omp_set_nest_lock Set a nestable OpenMP lock.
wrf.omp_unset_lock Unset a simple OpenMP lock.
wrf.omp_unset_nest_lock Unset a nestable OpenMP lock.
wrf.omp_test_lock Test a simple OpenMP lock.
wrf.omp_test_nest_lock Test a nestable OpenMP lock.

Configuration Routines

The routines below are used to configure wrf-python by enabling or disabling third party packages. For the most part, these settings are configured automatically based on the presence of a third party package. However, disabling xarray can be useful when you want to turn off all metadata in one place.

wrf.xarray_enabled Return True if xarray is installed and enabled.
wrf.disable_xarray Disable xarray.
wrf.enable_xarray Enable xarray if it is installed.
wrf.cartopy_enabled Return True if cartopy is installed and enabled.
wrf.disable_cartopy Disable cartopy.
wrf.enable_cartopy Enable cartopy if it is installed.
wrf.basemap_enabled Return True if basemap is installed and enabled.
wrf.disable_basemap Disable basemap.
wrf.enable_basemap Enable basemap if it is installed.
wrf.pyngl_enabled Return True if pyngl is installed and enabled.
wrf.enable_pyngl Enable pyngl if it is installed.
wrf.disable_pyngl Disable pyngl.
wrf.set_cache_size Set the maximum number of items that the threadlocal cache can retain.
wrf.get_cache_size Return the maximum number of items that the threadlocal cache can retain.
wrf.omp_enabled Return True if OpenMP is enabled.

Miscellaneous Routines

The routines below are primarily used internally, but some users may find them helpful for other purposes.

wrf.is_time_coord_var Return True if the input variable name is a time coordinate.
wrf.get_coord_pairs Return a tuple for the variable names of the coordinate pair used for the 2D curvilinear coordinate variable.
wrf.is_multi_time_req Return True if the requested time index is for wrf.ALL_TIMES or None.
wrf.is_multi_file Return True if the input argument is an iterable.
wrf.has_time_coord Return True if the input file or sequence contains the time coordinate variable.
wrf.is_mapping Return True if the input file or sequence is a mapping type.
wrf.latlon_coordvars Return the first found latitude and longitude coordinate names from a NetCDF variable dictionary.
wrf.is_coordvar Returns True if the variable is a coordinate variable.
wrf.get_iterable Returns a resettable iterable object.
wrf.is_moving_domain Return True if the domain is a moving nest.
wrf.npbytes_to_str Return a bytes object for the raw character array.
wrf.is_standard_wrf_var Return True if the variable is a standard WRF variable and not a diagnostic.
wrf.is_staggered Return True if the variable is on a staggered grid.
wrf.get_left_indexes Returns a tuple for the extra leftmost dimension sizes.
wrf.iter_left_indexes Yield the iteration tuples for a sequence of dimensions sizes.
wrf.get_right_slices Return an indexing tuple where the left dimensions are held to a fixed value and the right dimensions are set to slice objects.
wrf.get_proj_params Return a tuple of latitude, longitude, and projection parameters from a WRF output file object or a sequence of WRF output file objects.
wrf.psafilepath Return the full path to the ‘psadilookup.dat’ file.
wrf.get_id Return the cache id.
wrf.getproj Return a wrf.WrfProj subclass.
wrf.cache_item Store an item in the threadlocal cache.
wrf.get_cached_item Return an item from the threadlocal cache.
wrf.ll_points Return the lower left latitude and longitude point(s).
wrf.pairs_to_latlon Return latitude and longitude arrays from a sequence of wrf.CoordPair objects.

Classes

Exceptions

wrf.DiagnosticError Raised when an error occurs in a diagnostic routine.

CoordPair Class

The class below is used for storing coordinate metadata from routines that use a single point for an (x, y) or (lat, lon) location.

wrf.CoordPair A class that stores (x, y) and/or (latitude, longitude) coordinate pairs.

CoordPair Methods

wrf.CoordPair.latlon_str Return a str for the (latitude, longitude) coordinate pair.
wrf.CoordPair.xy_str Return a str for the (x,y) coordinate pair.

GeoBounds Class

The class below is used for specifying geographic boundaries.

wrf.GeoBounds A class that stores the geographic boundaries.

Projection Classes

The classes below are used to hold the projection information in the ‘projection’ entry within a xarray.DataArray.attrs attribute.

Projection Base Class

The base class for all map projection types.

wrf.WrfProj A base class for storing map projection information from WRF data.

Projection Base Class Methods

The class methods for all projection types.

wrf.WrfProj.basemap Return a matplotlib.mpl_toolkits.basemap.Basemap object for the map projection.
wrf.WrfProj.cartopy Return a cartopy.crs.Projection subclass for the map projection.
wrf.WrfProj.cartopy_xlim Return the x extents in projected coordinates for cartopy.
wrf.WrfProj.cartopy_ylim Return the y extents in projected coordinates for cartopy.
wrf.WrfProj.pyngl Return a Ngl.Resources object for the map projection.
wrf.WrfProj.cf Return a dictionary with the NetCDF CF parameters for the projection.
wrf.WrfProj.proj4 Return the PROJ.4 string for the map projection.

Projection Subclasses

See wrf.WrfProj for methods and attributes.

wrf.NullProjection A wrf.WrfProj subclass for empty projections.
wrf.LambertConformal A wrf.WrfProj subclass for Lambert Conformal Conic projections.
wrf.Mercator A wrf.WrfProj subclass for Mercator projections.
wrf.PolarStereographic A wrf.WrfProj subclass for Polar Stereographic projections.
wrf.LatLon A wrf.WrfProj subclass for Lat Lon projections.
wrf.RotatedLatLon A wrf.WrfProj subclass for Rotated Lat Lon projections.