Developer Reference Manual

Release:

2.1.0

Date:

Dec 06, 2024

This is the developer reference guide for PyDDA which covers most of the available functions, modules, and classes.

cost_functions Module

Module containing cost functions and their gradients.

pydda.cost_functions (pydda.cost_functions)

The procedures in this module calculate the individual cost functions and their gradients. All cost functions output a single floating point value. All gradients to cost functions will output an 1D numpy array whose shape is 3 x the total number of grid points N. The first N points will correspond to the gradient of the cost function for each value of u, the second N points will correspond to the gradient of the cost function for each value of v, and the third N points will correspond to the gradient of the cost function for each value of w.

In order to calculate the gradients of cost functions, assuming that your cost function can be written as a functional in the form of:

\[J(\vec{u(x,y,z)}) = \int_{domain} f(\vec{u(x,y,z)}) dxdydz\]

Then, the gradient \(\nabla J\) is for each \(u_{i} \in {\vec{u}}\):

\[\frac{\delta J}{\delta u_{i}} = \frac{\delta f}{\delta u_{i}(x,y,z)} - \frac{d}{dx}\frac{\delta f}{\delta u'_{i}(x,y,z)}\]

So, for a cost function such as:

\[J(\vec{u}) = \int_{domain} (\vec{u}-\vec{u_{back}})^2 dxdydz\]

We get for each \(u_{i} \in {\vec{u}}\):

\[\frac{\delta J}{\delta u_{i}} = \frac{\delta f}{\delta u_{i}(x,y,z)} - \frac{d}{dx}\frac{\delta L}{\delta u'_{i}(x,y,z)}\]

Since \(f\) does not depend on \(u'_{i}(x,y,z)\), we have:

\[ \begin{align}\begin{aligned}\frac{\delta J}{\delta u_{i}} = 2(u_{i}-\vec{u_{back}}) - 0\\\frac{\delta J}{\delta u_{i}} = 2(u_{i}-\vec{u_{back}})\end{aligned}\end{align} \]

Therefore, in order to add your own custom cost functions for your point observation, you need to explicitly be able to write both the cost function and its gradient using the methodology above. One you have implemented both procedures in Python, they then need to be added to pydda.cost_functions.

J_function(winds, parameters)	Calculates the total cost function.
grad_J(winds, parameters)	Calculates the gradient of the cost function.
calculate_radial_vel_cost_function(vrs, azs, ...)	Calculates the cost function due to difference of the wind field from radar radial velocities. For more information on this cost function, see Potvin et al. (2012) and Shapiro et al. (2009). All arrays in the given lists must have the same dimensions and represent the same spatial coordinates. :Parameters: * vrs (List of float arrays) -- List of radial velocities from each radar * els (List of float arrays) -- List of elevations from each radar * azs (List of float arrays) -- List of azimuths from each radar * u (Float array) -- Float array with u component of wind field * v (Float array) -- Float array with v component of wind field * w (Float array) -- Float array with w component of wind field * wts (List of float arrays) -- Float array containing fall speed from radar. * rmsVr (float) -- The sum of squares of velocity/num_points. Use for normalization of data weighting coefficient * weights (n_radars x_bins x y_bins float array) -- Data weights for each pair of radars * coeff (float) -- Constant for cost function.
calculate_grad_radial_vel(vrs, els, azs, u, ...)	Calculates the gradient of the cost function due to difference of wind field from radar radial velocities. All arrays in the given lists must have the same dimensions and represent the same spatial coordinates. :Parameters: * vrs (List of float arrays) -- List of radial velocities from each radar * els (List of float arrays) -- List of elevations from each radar * azs (List of azimuths) -- List of azimuths from each radar * u (Float array) -- Float array with u component of wind field * v (Float array) -- Float array with v component of wind field * w (Float array) -- Float array with w component of wind field * coeff (float) -- Constant for cost function * vel_name (str) -- Background velocity field name * weights (n_radars x_bins x y_bins float array) -- Data weights for each pair of radars.
calculate_mass_continuity(u, v, w, z, dx, dy, dz)	Calculates the mass continuity cost function by taking the divergence of the wind field. All arrays in the given lists must have the same dimensions and represent the same spatial coordinates. :Parameters: * u (Float array) -- Float array with u component of wind field * v (Float array) -- Float array with v component of wind field * w (Float array) -- Float array with w component of wind field * dx (float) -- Grid spacing in x direction. * dy (float) -- Grid spacing in y direction. * dz (float) -- Grid spacing in z direction. * z (Float array (1D)) -- 1D Float array with heights of grid * coeff (float) -- Constant controlling contribution of mass continuity to cost function * anel (int) -- = 1 use anelastic approximation, 0=don't.
calculate_mass_continuity_gradient(u, v, w, ...)	Calculates the gradient of mass continuity cost function. This is done by taking the negative gradient of the divergence of the wind field. All grids must have the same grid specification. :Parameters: * u (Float array) -- Float array with u component of wind field * v (Float array) -- Float array with v component of wind field * w (Float array) -- Float array with w component of wind field * z (Float array (1D)) -- 1D Float array with heights of grid * dx (float) -- Grid spacing in x direction. * dy (float) -- Grid spacing in y direction. * dz (float) -- Grid spacing in z direction. * coeff (float) -- Constant controlling contribution of mass continuity to cost function * anel (int) -- = 1 use anelastic approximation, 0=don't.
calculate_smoothness_cost(u, v, w, dx, dy, dz)	Calculates the smoothness cost function by taking the Laplacian of the wind field. All arrays in the given lists must have the same dimensions and represent the same spatial coordinates. :Parameters: * u (Float array) -- Float array with u component of wind field * v (Float array) -- Float array with v component of wind field * w (Float array) -- Float array with w component of wind field * Cx (float) -- Constant controlling smoothness in x-direction * Cy (float) -- Constant controlling smoothness in y-direction * Cz (float) -- Constant controlling smoothness in z-direction.
calculate_smoothness_gradient(u, v, w, dx, ...)	Calculates the gradient of the smoothness cost function by taking the Laplacian of the Laplacian of the wind field. All arrays in the given lists must have the same dimensions and represent the same spatial coordinates. :Parameters: * u (Float array) -- Float array with u component of wind field * v (Float array) -- Float array with v component of wind field * w (Float array) -- Float array with w component of wind field * Cx (float) -- Constant controlling smoothness in x-direction * Cy (float) -- Constant controlling smoothness in y-direction * Cz (float) -- Constant controlling smoothness in z-direction.
calculate_background_cost(u, v, w, weights, ...)	Calculates the background cost function. The background cost function is simply the sum of the squared differences between the wind field and the background wind field multiplied by the weighting coefficient. :Parameters: * u (Float array) -- Float array with u component of wind field * v (Float array) -- Float array with v component of wind field * w (Float array) -- Float array with w component of wind field * weights (Float array) -- Weights for each point to consider into cost function * u_back (1D float array) -- Zonal winds vs height from sounding * w_back (1D float array) -- Meridional winds vs height from sounding * Cb (float) -- Weight of background constraint to total cost function.
calculate_background_gradient(u, v, w, ...)	Calculates the gradient of the background cost function. For each u, v this is given as 2*coefficent*(analysis wind - background wind). :Parameters: * u (Float array) -- Float array with u component of wind field * v (Float array) -- Float array with v component of wind field * w (Float array) -- Float array with w component of wind field * weights (Float array) -- Weights for each point to consider into cost function * u_back (1D float array) -- Zonal winds vs height from sounding * w_back (1D float array) -- Meridional winds vs height from sounding * Cb (float) -- Weight of background constraint to total cost function.
calculate_vertical_vorticity_cost(u, v, w, ...)	Calculates the cost function due to deviance from vertical vorticity equation. For more information of the vertical vorticity cost function, see Potvin et al. (2012) and Shapiro et al. (2009). :Parameters: * u (3D array) -- Float array with u component of wind field * v (3D array) -- Float array with v component of wind field * w (3D array) -- Float array with w component of wind field * dx (float array) -- Spacing in x grid * dy (float array) -- Spacing in y grid * dz (float array) -- Spacing in z grid * coeff (float) -- Weighting coefficient * Ut (float) -- U component of storm motion * Vt (float) -- V component of storm motion.
calculate_vertical_vorticity_gradient(u, v, ...)	Calculates the gradient of the cost function due to deviance from vertical vorticity equation. This is done by taking the functional derivative of the vertical vorticity cost function. :Parameters: * u (3D array) -- Float array with u component of wind field * v (3D array) -- Float array with v component of wind field * w (3D array) -- Float array with w component of wind field * dx (float array) -- Spacing in x grid * dy (float array) -- Spacing in y grid * dz (float array) -- Spacing in z grid * Ut (float) -- U component of storm motion * Vt (float) -- V component of storm motion * coeff (float) -- Weighting coefficient.
calculate_model_cost(u, v, w, weights, ...)	Calculates the cost function for the model constraint. This is calculated simply as the sum of squares of the differences between the model wind field and the analysis wind field. Vertical velocities are not factored into this cost function as there is typically a high amount of uncertainty in model derived vertical velocities. :Parameters: * u (3D array) -- Float array with u component of wind field * v (3D array) -- Float array with v component of wind field * w (3D array) -- Float array with w component of wind field * weights (list of 3D arrays) -- Float array showing how much each point from model weighs into constraint. * u_model (list of 3D arrays) -- Float array with u component of wind field from model * v_model (list of 3D arrays) -- Float array with v component of wind field from model * w_model (list of 3D arrays) -- Float array with w component of wind field from model * coeff (float) -- Weighting coefficient.
calculate_model_gradient(u, v, w, weights, ...)	Calculates the cost function for the model constraint. This is calculated simply as twice the differences between the model wind field and the analysis wind field for each u, v. Vertical velocities are not factored into this cost function as there is typically a high amount of uncertainty in model derived vertical velocities. Therefore, the gradient for all of the w's will be 0. :Parameters: * u (Float array) -- Float array with u component of wind field * v (Float array) -- Float array with v component of wind field * w (Float array) -- Float array with w component of wind field * weights (list of 3D float arrays) -- Weights for each point to consider into cost function * u_model (list of 3D float arrays) -- Zonal wind field from model * v_model (list of 3D float arrays) -- Meridional wind field from model * w_model (list of 3D float arrays) -- Vertical wind field from model * coeff (float) -- Weight of background constraint to total cost function.
calculate_fall_speed(grid[, refl_field, frz])	Estimates fall speed based on reflectivity. Uses methodology of Mike Biggerstaff and Dan Betten :Parameters: * Grid (Py-ART Grid) -- Py-ART Grid containing reflectivity to calculate fall speed from * refl_field (str) -- String containing name of reflectivity field. None will automatically determine the name. * frz (float) -- Height of freezing level in m.
calculate_point_cost(u, v, x, y, z, point_list)	Calculates the cost function related to point observations. A mean square error cost function term is applied to points that are within the sphere of influence whose radius is determined by roi. :Parameters: * u (Float array) -- Float array with u component of wind field * v (Float array) -- Float array with v component of wind field * x (Float array) -- X coordinates of grid centers * y (Float array) -- Y coordinates of grid centers * z (Float array) -- Z coordinated of grid centers * point_list (list of dicts) -- List of point constraints. Each member is a dict with keys of "u", "v", to correspond to each component of the wind field and "x", "y", "z" to correspond to the location of the point observation. In addition, "site_id" gives the METAR code (or name) to the station. * Cp (float) -- The weighting coefficient of the point cost function. * roi (float) -- Radius of influence of observations.
calculate_point_gradient(u, v, x, y, z, ...)	Calculates the gradient of the cost function related to point observations. A mean square error cost function term is applied to points that are within the sphere of influence whose radius is determined by roi. :Parameters: * u (Float array) -- Float array with u component of wind field * v (Float array) -- Float array with v component of wind field * x (Float array) -- X coordinates of grid centers * y (Float array) -- Y coordinates of grid centers * z (Float array) -- Z coordinated of grid centers * point_list (list of dicts) -- List of point constraints. Each member is a dict with keys of "u", "v", to correspond to each component of the wind field and "x", "y", "z" to correspond to the location of the point observation. In addition, "site_id" gives the METAR code (or name) to the station. * Cp (float) -- The weighting coefficient of the point cost function. * roi (float) -- Radius of influence of observations.

retrieval Module

Main module for wind retrieval.

pydda.retrieval (pydda.retrieval)

The module containing the core techniques for the multiple doppler wind retrieval. The get_dd_wind_field() procedure is the primary wind retrieval procedure in PyDDA. It contains the optimization loop that calls all of the cost functions and gradients in pydda.cost_functions so that the user does not need to know how to call these functions.

get_dd_wind_field(Grids[, u_init, v_init, ...])	This function takes in a list of Py-ART Grid objects and derives a wind field.
get_bca(Grid1, Grid2)	This function gets the beam crossing angle between two lat/lon pairs.
DDParameters()	This is a helper class for inserting more arguments into the pydda.cost_functions.J_function() and pydda.cost_functions.grad_J() function.
get_dd_wind_field_nested(grid_tree, **kwargs)	Does a wind retrieval over nested grids. The nested grids are created using PyART's pyart.map.grid_from_radars() function and then placed into a tree structure using :func:`dataTree`s. Each node of the tree has three parameters: .. list-table:: Title :widths: 25 100 :header-rows: 1.
make_initialization_from_other_grid(...[, ...])	This function will create an initaliation by interpolating a wind field from a grid with a different specification than the analysis grid.

vis Module

Visualization module for PyDDA.

pydda.vis (pydda.vis)

A visualization module for plotting generated wind fields. There is basic support for the visualization of wind fields over a given background field using barbs, streamlines, and quivers.

plot_horiz_xsection_barbs(Grids[, ax, ...])	This procedure plots a horizontal cross section of winds from wind fields generated by PyDDA using barbs.
plot_xz_xsection_barbs(Grids[, ax, ...])	This procedure plots a cross section of winds from wind fields generated by PyDDA in the X-Z plane using barbs.
plot_yz_xsection_barbs(Grids[, ax, ...])	This procedure plots a cross section of winds from wind fields generated by PyDDA in the Y-Z plane using barbs.
plot_horiz_xsection_barbs_map(Grids[, ax, ...])	This procedure plots a horizontal cross section of winds from wind fields generated by PyDDA onto a geographical map using barbs.
plot_horiz_xsection_streamlines(Grids[, ax, ...])	This procedure plots a horizontal cross section of winds from wind fields generated by PyDDA using streamlines.
plot_xz_xsection_streamlines(Grids[, ax, ...])	This procedure plots a cross section of winds from wind fields generated by PyDDA in the X-Z plane using streamlines.
plot_yz_xsection_streamlines(Grids[, ax, ...])	This procedure plots a cross section of winds from wind fields generated by PyDDA in the Y-Z plane using streamlines.
plot_horiz_xsection_streamlines_map(Grids[, ...])	This procedure plots a horizontal cross section of winds from wind fields generated by PyDDA using streamlines.
plot_horiz_xsection_quiver(Grids[, ax, ...])	This procedure plots a horizontal cross section of winds from wind fields generated by PyDDA using quivers.
plot_xz_xsection_quiver(Grids[, ax, ...])	This procedure plots a cross section of winds from wind fields generated by PyDDA in the X-Z plane using quivers.
plot_yz_xsection_quiver(Grids[, ax, ...])	This procedure plots a cross section of winds from wind fields generated by PyDDA in the Y-Z plane using quivers.
plot_horiz_xsection_quiver_map(Grids[, ax, ...])	This procedure plots a horizontal cross section of winds from wind fields generated by PyDDA using quivers onto a geographical map.

initalization Module

The module for creating custom initial states for the PyDDA retrieval.

pydda.initialization (pydda.initialization)

The module containing the core techniques for the multiple doppler wind retrieval. All of these techniques take in data from a desired format and will return a 3-tuple of numpy arrays that are in the same shape as the input Py-ART Grid object used for analysis. If you wish to add another initialization here, add a procedure that takes in a Py-Art Grid that is used for the grid specification (shape, x, y, z) and the dataset of your choice. Your output from the function should then be a 3-tuple of numpy arrays with the same shape as the fields in Grid.

make_constant_wind_field(Grid[, wind, vel_field])	This function makes a constant wind field given a wind vector.
make_wind_field_from_profile(Grid, profile)	This function makes a 3D wind field from a sounding.
make_background_from_wrf(Grid, file_path, ...)	This function makes an initalization field based off of the u and w from a WRF run.
make_initialization_from_era5(Grid[, ...])	Written by: Hamid Ali Syed and Bobby Jackson This function will read ERA 5 in NetCDF format and add it to the Py-ART grid specified by Grid.

constraints Module

The module for creating custom constraints (i.e. from models, satellites) for the PyDDA retrieval.

pydda.constraints (pydda.constraints)

The procedures in this module are used to add spatial fields from non-radar based datasets for use as a constraint. The model cost function uses the observations inserted into the Grid object from these procedures as a constraint. In order to develop your own custom constraint here, simply create a function that adds 3 fields into the input Py-ART Grid with names “u_(name)”, “v_(name)”, and “w_(name)” where (name) is the name of your dataset. Then, in order to have PyDDA use this dataset as a constraint, simply add (name) into the model_fields option of get_dd_wind_field().

make_constraint_from_wrf(Grid, file_path, ...)	This function makes an initalization field based off of the u and w from a WRF run in netCDF format.
add_hrrr_constraint_to_grid(Grid, file_path)	This function will read an HRRR GRIB2 file and create the constraining u, v, and w fields for the model constraint
make_constraint_from_era5(Grid[, file_name, ...])	Written by: Hamid Ali Syed (@syedhamidali), and Bobby Jackson This function will read ERA 5 in NetCDF format and add it to the Py-ART grid specified by Grid.
download_needed_era_data(Grid, start_date, ...)	Written by: Hamid Ali Syed (@syedhamidali), and Bobby Jackson.
get_iem_obs(Grid[, window])	Returns all of the station observations from the Iowa Mesonet for a given Grid in the format needed for PyDDA.