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.