Developer Reference Manual

Release

0.5.1

Date

Jul 13, 2020

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.

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.

calculate_mass_continuity(u, v, w, z, dx, dy, dz)

Calculates the mass continuity cost function by taking the divergence of the wind field.

calculate_mass_continuity_gradient(u, v, w, …)

Calculates the gradient of mass continuity cost function.

calculate_smoothness_cost(u, v, w[, Cx, Cy, Cz])

Calculates the smoothness cost function by taking the Laplacian of the wind field.

calculate_smoothness_gradient(u, v, w[, Cx, …])

Calculates the gradient of the smoothness cost function by taking the Laplacian of the Laplacian of the wind field.

calculate_background_cost(u, v, w, weights, …)

Calculates the background cost function.

calculate_background_gradient(u, v, w, …)

Calculates the gradient of the background cost function.

calculate_vertical_vorticity_cost(u, v, w, …)

Calculates the cost function due to deviance from vertical vorticity equation.

calculate_vertical_vorticity_gradient(u, v, …)

Calculates the gradient of the cost function due to deviance from vertical vorticity equation.

calculate_model_cost(u, v, w, weights, …)

Calculates the cost function for the model constraint.

calculate_model_gradient(u, v, w, weights, …)

Calculates the cost function for the model constraint.

calculate_fall_speed(grid[, refl_field, frz])

Estimates fall speed based on reflectivity.

calculate_point_cost(u, v, x, y, z, point_list)

Calculates the cost function related to point observations.

calculate_point_gradient(u, v, x, y, z, …)

Calculates the gradient of the cost function related to point 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, w_init)

This function takes in a list of Py-ART Grid objects and derives a wind field.

get_dd_wind_field_nested(grid_list, u_init, …)

This function performs a wind retrieval using a nested domain.

get_bca(rad1_lon, rad1_lat, rad2_lon, …)

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.

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_era_interim(Grid[, …])

This function will read ERA Interim 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_era_interim(Grid[, …])

This function will read ERA Interim in NetCDF format and add it to the Py-ART grid specified by Grid.

download_needed_era_data(Grid, start_date, …)

This function will download the ERA interim data in the region specified by the input Py-ART Grid within the interval specified by start_date and end_date.

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.