R/RcppExports.R

In geanders/stormwindmodel: Model Tropical Cyclone Wind Speeds

# Generated by using Rcpp::compileAttributes() -> do not edit by hand
# Generator token: 10BE3573-1514-4C36-9D1C-5A225CD40393

#' Willoughby et al. (2006), Equation 1(a)
#'
#' This is the equation that is used for the wind profile inside the  eye (more
#' specifically, from the center of the storm to R1, where the transition region
#' for the model starts). It assumes that the wind increases from the center of
#' the storm to the radius of maximum wind in proportion to a power of the radius
#' from the center.
#'
#' @param vmax_gl A numeric value giving the maximum gradient-level 1-minute
#'   sustained wind for the tropical cyclone, in meters per second. This is the
#'   value given for the storm as a whole at the time point (for example, in
#'   tracking data).
#' @param r A numeric value of radius from the storm center to the point you are
#'   measuring, in kilometers
#' @param Rmax A numeric value with the distance from the center of the storm to
#'   the storm's radius of maximum wind, in kilometers
#' @param n A numeric value giving the power by which the wind is assumed to
#'   increase with radius within the center of the storm (i.e., from the center
#'   to the radius of maximum wind)
#'
#' @return A numeric value with the modeled wind at distance r from the center of
#'   the storm, in meters per second.
#'
#' @references
#'
#' Willoughby HE, Darling RWR, and Rahn ME. 2006. Parametric representation
#' of the primary hurricane vortex. Part II: A new family of sectionally
#' continuous profiles. Monthly Weather Review 134(4):1102-1120.
#'
NULL

#' Calculate equation 4 from Willoughby
#'
#' This is the equation that is used for the wind profile in outer regions of the
#' storm (more specifically, outside of the second radius defining the transition
#' region, R2).
#'
#' @param vmax_gl A numeric value giving the maximum gradient-level 1-minute
#'   sustained wind for the tropical cyclone, in meters per second. This is the
#'   value given for the storm as a whole at the time point (for example, in
#'   tracking data).
#' @param A A numeric value with the fitted contribution of the faster exponential
#'   to the profile for Willoughby
#' @param r A numeric value giving the distance from the center of the storm to
#'   the location where you would like to model the local wind, in kilometers
#' @param Rmax A numeric value with the distance from the center of the storm to
#'   the storm's radius of maximum wind, in kilometers
#' @param X1 A numeric value with the fitted slower decay length for Willoughby
#' @param X2 A numeric value with the fixed rapid decay length for Willoughby
#'
#' @return A numeric value with the modeled wind at distance r from the center of
#'   the storm, in meters per second.
#'
#' @references
#'
#' Willoughby HE, Darling RWR, and Rahn ME. 2006. Parametric representation
#' of the primary hurricane vortex. Part II: A new family of sectionally
#' continuous profiles. Monthly Weather Review 134(4):1102-1120.
#'
NULL

#' Calculate distance between two latitude / longitude points
#'
#' @param tclat A numeric value with the latitude of the tropical cyclone's center
#'   in radians
#' @param tclon A numeric value with the longitude of the tropical cyclone's center
#'   in radians
#' @param glat A numeric value with the latitude of the grid point in radians
#' @param glon A numeric value with the longitude of the grid point in radians
#' @param Rearth A numeric value with the radius of the earth in kilometers. This
#'   value defaults to 6,371 km, which is the median radius of the earth.
#' @return A numeric value with the distance (in kilometers) from the tropical
#'   cyclone center to the grid point.
calc_distance <- function(tclat, tclon, glat, glon, Rearth = 6371) {
    .Call(`_stormwindmodel_calc_distance`, tclat, tclon, glat, glon, Rearth)
}

#' Calculate equation 2 from Willoughby
#'
#' @param r A numeric value giving the distance from the center of the storm to
#'   the location where you would like to model the local wind, in kilometers
#' @param R1 A numeric value with the lower boundary of the transition zone (in
#'   km from the storm center)
#' @param R2 A numeric value with the upper boundary of the transition zone (in
#'   km from the storm center)
#'
#' @return A numeric value between 0 and 1 that gives the amount to weight Vi
#'   versus Vo when estimating wind within the transition zone.
#'
#' @references
#'
#' Willoughby HE, Darling RWR, and Rahn ME. 2006. Parametric representation
#' of the primary hurricane vortex. Part II: A new family of sectionally
#' continuous profiles. Monthly Weather Review 134(4):1102-1120.
#'
will2 <- function(r, R1, R2) {
    .Call(`_stormwindmodel_will2`, r, R1, R2)
}

#' Model wind speed at a grid point for a storm track observation
#'
#' Models the gradient wind speed at a certain radius from
#' a storm's center. To do this, it uses different equations and subfunctions
#' depending on how large the radius is (see details). This function requires,
#' as inputs, Willoughby wind model parameters calculated using the
#' \code{\link{add_wind_radii}} function.
#'
#' @param cdist A numeric value with the distance between the grid point and the
#'   center of the storm (in km)
#' @param R1 A numeric value with the lower boundary of the transition zone (in
#'   km from the storm center)
#' @param R2 A numeric value with the upper boundary of the transition zone (in
#'   km from the storm center)
#' @param vmax_gl A numeric value with the maximum gradient level 1-minute
#'   sustained wind, in (m/s)
#' @param A A numeric value that is a parameter between 0 and 1 for the Willoughby
#'   model
#' @param Rmax A numeric value with the radius at which the maximum wind occurs
#'   (in km)
#' @param X1 A numeric value that is a parameter for the Willoughby model
#' @param X2 A numeric value as a parameter for the Willoughby model, set to 25
#'   (Willoughby, Darling, and Rahn 2006)
#' @param n A numeric value giving the power by which the wind is assumed to
#'   increase with radius within the center of the storm (i.e., from the center
#'   to the radius of maximum wind)
#'
#' @return Returns a numeric vector with gradient wind speed at a radius of
#'    \eqn{r} from the storm's center, in meters per second.
#'
#' @details If \eqn{r \le R_1}{r \le R1}, this function is calculating the equation:
#'
#'    \deqn{V(r) = V_i = V_{max} \left( \frac{r}{R_{max}} \right)^n}{
#'    V(r) = Vi = vmax_gl (r / Rmax)^n}
#'
#'    where:
#'    \itemize{
#'      \item{\eqn{V(r)}: Maximum sustained gradient wind speed at a radius of
#'        \eqn{r} from the storm's center}
#'      \item{\eqn{r}: Radius from the storm center, in kilometers}
#'      \item{\eqn{V_{max,G}}{vmax_gl}: Maximum sustained gradient wind speed of the
#'        storm, in meters per second}
#'      \item{\eqn{R_1}{R1}: A parameter for the Willoughby wind model (radius to
#'        start of transition region)}
#'      \item{\eqn{R_{max}}{Rmax}: Radius (in kilometers) to highest winds}
#'      \item{\eqn{n}: A parameter for the Willoughby wind model}
#'    }
#'
#'    If \eqn{R_2 < r}{R2 \le r}, this function is calculating
#'      the equation:
#'
#'      \deqn{V(r) = V_o = V_{max}\left[(1 - A) e^\frac{R_{max} - r}{X_1} + A e^\frac{R_{max} - r}{X_2}\right]}{
#'      V(r) = Vo = vmax_gl[(1 - A) e^((Rmax - r) / X1) + A e^((Rmax - r) / X_2)]}
#'
#'    where:
#'    \itemize{
#'      \item{\eqn{V(r)}: Maximum sustained gradient wind speed at a radius of
#'        \eqn{r} kilometers from the storm's center}
#'      \item{\eqn{r}: Radius from the storm center, in kilometers}
#'      \item{\eqn{V_{max,G}}{vmax_gl}: Maximum sustained gradient wind speed of the
#'        storm, in meters per second}
#'      \item{\eqn{R_{max}}{Rmax}: Radius (in kilometers) to highest winds}
#'      \item{\eqn{A}, \eqn{X_1}{X1}, \eqn{X_2}{X2}: Parameters for the
#'         Willoughby wind model}
#'    }
#'
#'    If \eqn{R_1 < r \le R_2}{R1 < r \le R2}, this function uses
#'      the equations:
#'
#'      \deqn{\xi = \frac{r - R_1}{R_2 - R_1}}{
#'      \xi = (r - R1) / (R2 - R1)}
#'
#'      and, if \eqn{0 \le \xi < \le 1} (otherwise, \eqn{w = 0}):
#'
#'      \deqn{w = 126 \xi^5 - 420 \xi^6 + 540 \xi^7- 315 \xi^8 + 70 \xi^9}
#'
#'      and then:
#'
#'      \deqn{V(r) = V_i (1 - w) + V_o w, (R_1 \le r \le R_2)}{
#'      V(r) = Vi (1 - w) + Vo w}
#'
#'    where, for this series of equations:
#'    \itemize{
#'      \item{\eqn{V(r)}: Maximum sustained gradient wind speed at a radius of
#'        \eqn{r} kilometers from the storm's center}
#'      \item{\eqn{r}: Radius from the storm center, in kilometers}
#'      \item{\eqn{w}: Weighting variable}
#'      \item{\eqn{R_1}{R1}, \eqn{R_2}{R2}: Parameters for the Willoughby wind model}
#'    }
#'
#' @references
#'
#' Willoughby HE, Darling RWR, and Rahn ME. 2006. Parametric representation
#' of the primary hurricane vortex. Part II: A new family of sectionally
#' continuous profiles. Monthly Weather Review 134(4):1102-1120.
#'
will1 <- function(cdist, Rmax, R1, R2, vmax_gl, n, A, X1, X2 = 25.0) {
    .Call(`_stormwindmodel_will1`, cdist, Rmax, R1, R2, vmax_gl, n, A, X1, X2)
}

#' Calculate bearing from one lat/long to another for a single point
#'
#' @param tclat A numeric value with the latitude of the tropical cyclone's center
#'   in radians
#' @param tclon A numeric value with the longitude of the tropical cyclone's center
#'   in radians
#' @param glat A numeric value with the latitude of the grid point in radians
#' @param glon A numeric value with the longitude of the grid point in radians
#' @return A numeric value with the bearing from the storm's center to the grid point
#'   in polar coordinates (i.e., due East is 0 degrees, due North is 90 degrees, etc.)
calc_bearing_single <- function(tclat, tclon, glat, glon) {
    .Call(`_stormwindmodel_calc_bearing_single`, tclat, tclon, glat, glon)
}

#' Calculate gradient wind direction at a point
#'
#' This function determines the bearing from the storm's center to a
#' grid point location and then calculates the direction of gradient
#' winds at that grid point. Gradient winds will be perpendicular to
#' the direction from the storm's center to the grid point. In the
#' Northern hemisphere, cyclonic winds are counterclockwise, so you
#' add 90 degrees to the bearing from the storm center to the grid point
#' when using polar coordinates. In the Southern hemisphere, cyclonic
#' winds are clockwise, so you subtract 90 degrees.
#'
#' @param tclat A numeric value with the latitude of the tropical cyclone's center
#'   in radians
#' @param tclon A numeric value with the longitude of the tropical cyclone's center
#'   in radians
#' @param glat A numeric value with the latitude of the grid point in radians
#' @param glon A numeric value with the longitude of the grid point in radians
#'
#' @return A numeric value with the the direction of gradient storm winds at a location,
#'   in polar coordinates (i.e., due East is 0 degrees, due North is 90 degrees, etc.)
#'
calc_gwd <- function(tclat, tclon, glat, glon) {
    .Call(`_stormwindmodel_calc_gwd`, tclat, tclon, glat, glon)
}

#' Calculate symmetrical surface wind from gradient wind
#'
#' Calculates the surface wind speed based on an estimated gradient
#' wind speed at a point and the radius from the storm center to
#' the grid point.
#'
#' @param wind_gl_aa The gradient-level wind at the location at which the wind
#'   is being modeled (in m/s)
#' @param cdist The distance from the center of the storm to the location at
#'   which the wind is being modeled (in kilometers)
#' @param glandsea A logical value that specifies whether the location at which
#'   the wind is being modeled is over land (TRUE) or over water (FALSE)
#'
#' @return A numeric value giving the surface-level wind at that location (before
#'   incorporating the role of forward motion of the storm) (in m/s)
#'
#' @details The reduction factor is based on Figure 3 of Knaff et al., 2003.
#' Over water, it is estimated to be 0.9 up to a radius of 100 km,
#' 0.75 for a radius of 700 km or more, and decrease linearly between
#' a radius of 100 km and 700 km. Points over land use a reduction
#' factor that is 20\% lower.
#'
#' @references
#'
#' Knaff JA, DeMaria M, Molenar DA, Sampson CR, and Seybold MG. 2011. An
#' automated, objective, multiple-satellite-platform tropical cyclone surface
#' wind speed analysis. Journal of Applied Meteorology and Climatology
#' 50(10):2149-2166
#'
gradient_to_surface <- function(wind_gl_aa, cdist, glandsea) {
    .Call(`_stormwindmodel_gradient_to_surface`, wind_gl_aa, cdist, glandsea)
}

#' Add inflow to direction of surface winds
#'
#' This function adds an inflow angle to the angle of the wind direction.
#' It calculates an inflow angle as a function of the distance from the
#' storm center to a location (Phadke et al. 2003). If the locations is over
#' land, it then adds 20 degrees to this inflow angle to account for the location
#' being over land rather than over water.
#'
#' @param gwd A numeric value with the gradient wind direction in polar degrees
#'   (e.g., due east is 0 degrees, due north is 90 degrees)
#' @param cdist The distance from the center of the storm to the location at
#'   which the wind is being modeled (in kilometers)
#' @param Rmax A numeric value with the radius at which maximum winds occur in kilometers
#' @param tclat A numeric value with latitude in radians
#' @param glandsea A logical value that specifies whether the location at which
#'   the wind is being modeled is over land (TRUE) or over water (FALSE)
#'
#' @return swd A numeric value with the surface wind direction in polar degrees
#'   (e.g., due east is 0, due north is 90)
#'
#' @details
#'
#' This function uses equations 11a-c from Phadke et al. (2003).
#'
#' @references
#'
#' Phadke AC, Martino CD, Cheung KF, and Houston SH. 2003. Modeling of
#'    tropical cyclone winds and waves for emergency management. Ocean
#'    Engineering 30(4):553-578.
#'
add_inflow <- function(gwd, cdist, Rmax, tclat, glandsea) {
    .Call(`_stormwindmodel_add_inflow`, gwd, cdist, Rmax, tclat, glandsea)
}

#' Add in forward speed of the storm
#'
#' Adds the storm's forward speed component (i.e., motion asymmetry) back
#' into the estimated surface wind speed at a grid point location after
#' rotational winds have been modeled for the location.
#'
#' @param wind_sfc_sym A numeric value with the estimated symmetric surface
#' wind speed at the grid point, in meters / second
#' @param tcspd_u A numeric value with the u-component of the tropical cyclone
#' speed in meters / second
#' @param tcspd_v A numeric value with the v-component of the tropical cyclone
#' speed in meters / second
#' @param swd A numeric value with the surface wind direction in degrees
#' @param cdist A numeric value with the radius from the storm's center to the
#' grid point in kilometers
#' @param Rmax A numeric value with the radius at which maximum winds occur in kilometers
#'
#' @return windspeed A numeric value with the asymmetric surface windspeed at the
#' location, in meters/second
#'
#' @details
#'
#' This function uses equation 12 from Phadke et al. (2003).
#'
#' @references
#'
#' Phadke AC, Martino CD, Cheung KF, and Houston SH. 2003. Modeling of
#'    tropical cyclone winds and waves for emergency management. Ocean
#'    Engineering 30(4):553-578.
#'
add_forward_speed <- function(wind_sfc_sym, tcspd_u, tcspd_v, swd, cdist, Rmax) {
    .Call(`_stormwindmodel_add_forward_speed`, wind_sfc_sym, tcspd_u, tcspd_v, swd, cdist, Rmax)
}

calc_grid_winds_cpp <- function(glat, glon, glandsea, max_dist, tclat, tclon, Rmax, R1, R2, vmax_gl, n, A, X1, tcspd_u, tcspd_v) {
    .Call(`_stormwindmodel_calc_grid_winds_cpp`, glat, glon, glandsea, max_dist, tclat, tclon, Rmax, R1, R2, vmax_gl, n, A, X1, tcspd_u, tcspd_v)
}

#' Calculate coefficients for linear interpolation
#'
#' @param x A numeric vector with independent values of the original function.
#' @param y A numeric vector with dependent values of the original function.
#' @return A numeric vector with slope coefficients for the linear interpolation of
#'   the original function. This vector has a length one less that the input vectors.
#'   The slope is for the section starting at that location in the x input vector.
#' @export
calc_linear_coefs <- function(x, y) {
    .Call(`_stormwindmodel_calc_linear_coefs`, x, y)
}

#' Find the location of a new value in a table of values
#'
#' @param new_x A double floating point number giving a new value of x for which
#'   you want to find the indices of the sections of a vector x that contain the
#'   new value.
#' @param x A numeric vector for which you want to find the position that brackets
#'   the new value, new_x.
#' @return An integer giving the zero-based index of the position in the x vector
#'   that gives the lower bracket of the section of the x-vector containing the new
#'   x value.
#' @export
find_x_section <- function(new_x, x) {
    .Call(`_stormwindmodel_find_x_section`, new_x, x)
}

#' Interpolate new y-values using linear interpolation
#'
#' @param new_x A numeric value providing the new x values at which you want to
#'   interpolate y values.
#' @param x A numeric vector with the x values of the original function.
#' @param y A numeric vector with the y values of the original function. This should
#'   be the same length as x.
#' @return A numeric vector with the interpolated values of y at each of the new
#'   x values provided by the new_x input.
#' @name interpolate_line
#'
#' @export
interpolate_line <- function(x, y, new_x) {
    .Call(`_stormwindmodel_interpolate_line`, x, y, new_x)
}

#' Make interp
#' @inheritParams interpolate_line
#' @export
make_interp <- function(x, y) {
    .Call(`_stormwindmodel_make_interp`, x, y)
}

apply_interp <- function(new_x, x, y, y2d) {
    .Call(`_stormwindmodel_apply_interp`, new_x, x, y, y2d)
}

#' Perform spline interpolation
#'
#' @param x A numeric vector with independent values of the original function.
#' @param y A numeric vector with dependent values of the original function.
#' @param new_x A numeric vector with the values of x at which you want to interpolate v
#'          values of y.
#' @return A numeric vector with the interpolated values of y at the \code{new_x} values.
#'
#' @export
interpolate_spline <- function(x, y, new_x) {
    .Call(`_stormwindmodel_interpolate_spline`, x, y, new_x)
}

#' Convert from radians to degrees
#'
#' Convert an angle from radians to degrees
#'
#' @param radians A numeric vector with measurements in radians.
#'
#' @return A numeric vector with the measurement in degrees.
NULL

#' Convert from degrees to radians
#'
#' Convert an angle from degrees to radians
#'
#' @param degrees A numeric vector with measurements in degrees.
#'
#' @return A numeric vector with measurement in radians.
#' @export
NULL

#' Calculate distance between two locations
#'
#' This function takes latitudes and longitudes for two locations and
#' calculates the distance (in meters) between the locations using the
#' Haversine method.
#'
#' @param tclat_1 A numeric vector giving latitude of the first location
#'    (degrees)
#' @param tclon_1 A numeric vector giving longitude of the first location
#'    (degrees). This value should be expressed as a positive value for Western
#'    hemisphere longitudes.
#' @param tclat_2 A numeric vector giving latitude of the second location
#'    (degrees)
#' @param tclon_2 A numeric vector giving longitude of the second location
#'    (degrees). This value should be expressed as a positive value for Western
#'    hemisphere longitudes.
#' @param Rearth Radius of the earth (km). Default is 6378.14 km.
#'
#' @return A vector with the distance between the two locations, in kilometers.
#'
#' @details This function uses the Haversine method with great circle distance
#'    to calculate this distance. It is applying the following equations to
#'    determine distance (in kilometers) between two latitude-longitude pairs:
#'    \deqn{hav(\gamma) = hav(\phi_1 - \phi_2) + cos(\phi_1)*cos(\phi_2)*hav(L_1 - L_2)}{
#'    hav(\gamma) = hav(\phi1 - \phi2) + cos(\phi1)*cos(\phi2)*hav(L1 - L2)}
#'    where:
#'    \itemize{
#'      \item{\eqn{\phi_1}{\phi1}: Latitude of first location, in radians}
#'      \item{\eqn{\phi_2}{\phi2}: Latitude of second location, in radians}
#'      \item{\eqn{L_1}{L1}: Longitude of first location, in radians}
#'      \item{\eqn{L_2}{L2}: Longitude of second location, in radians}
#'      \item{\eqn{hav(\gamma)}: The haversine function,
#'         \eqn{hav(\gamma) = sin^2 \left(\frac{\gamma}{2}\right)}{
#'         hav(\gamma) = sin^2 (\gamma / 2)}}
#'      \item{\eqn{R_earth}{Rearth}: Radius of the earth, here assumed to be 6378.14 kilometers}
#'      \item{\eqn{D}}: Distance between the two locations, in kilometers
#'    }
#'
#'
#' @export
NULL

radians_to_degrees <- function(radians) {
    .Call(`_stormwindmodel_radians_to_degrees`, radians)
}

degrees_to_radians <- function(degrees) {
    .Call(`_stormwindmodel_degrees_to_radians`, degrees)
}

latlon_to_km <- function(tclat_1, tclon_1, tclat_2, tclon_2, Rearth = 6378.14) {
    .Call(`_stormwindmodel_latlon_to_km`, tclat_1, tclon_1, tclat_2, tclon_2, Rearth)
}

#' Calculate storm's forward speed
#'
#' This storm takes two storm locations and their observations times and
#' calculates the average speed of the storm between the two observations.
#'
#' @param time_1 A date-time vector giving the time of the first observation.
#' @param time_2 A date-time vector giving the time of the second observation.
#' @param tclat_1 A numeric vector giving latitude of the first location
#'    (degrees)
#' @param tclon_1 A numeric vector giving longitude of the first location
#'    (degrees). This value should be expressed as a positive value for Western
#'    hemisphere longitudes.
#' @param tclat_2 A numeric vector giving latitude of the second location
#'    (degrees)
#' @param tclon_2 A numeric vector giving longitude of the second location
#'    (degrees). This value should be expressed as a positive value for Western
#'    hemisphere longitudes.
#'
#' @return A numeric vector with the average forward speed of the storm between
#'    the two observations, in meters per second.
#'
#' @export
calc_forward_speed <- function(tclat_1, tclon_1, time_1, tclat_2, tclon_2, time_2) {
    .Call(`_stormwindmodel_calc_forward_speed`, tclat_1, tclon_1, time_1, tclat_2, tclon_2, time_2)
}

#' Calculate bearing from one location to another
#'
#' Calculates the bearing of a second location, as seen from
#' the first location, based on latitude and longitude coordinates for both
#' locations.
#'
#' @param tclat_1 A numeric vector giving latitude of the first location
#'    (degrees)
#' @param tclon_1 A numeric vector giving longitude of the first location
#'    (degrees). This value should be expressed as a positive value for Western
#'    hemisphere longitudes.
#' @param tclat_2 A numeric vector giving latitude of the second location
#'    (degrees)
#' @param tclon_2 A numeric vector giving longitude of the second location
#'    (degrees). This value should be expressed as a positive value for Western
#'    hemisphere longitudes.
#'
#' @return A numeric vector giving the direction of the second location from the first location,
#'    in degrees. A direction of 0 degrees indicates the second location is
#'    due east of the first, 90 degrees indicates the second location is due
#'    north of the first, etc (i.e., polar, rather than meteorological, coordinate system).
#'
#' @details This function uses the following equations to calculate the bearing
#'    from one latitude-longitude pair to another:
#'
#'    \deqn{S = cos(\phi_2) * sin(L_2 - L_1)}{
#'    S = cos(\phi2) * sin(L2 - L1)}
#'
#'    \deqn{C = cos(\phi_1) * sin(\phi_2) - sin(\phi_1) * cos(\phi_2) * cos(L_2 - L_1)}{
#'    C = cos(\phi1) * sin(\phi2) - sin(\phi1) * cos(\phi2) * cos(L2 - L1)}
#'
#'    \deqn{\theta = 90 - atan2(S, C) * \frac{180}{\pi}}
#'
#'    where:
#'    \itemize{
#'      \item{\eqn{\phi_1}{\phi1}: Latitude of first location, in radians}
#'      \item{\eqn{L_1}{L1}: Longitude of first location, in radians}
#'      \item{\eqn{\phi_2}{\phi2}: Latitude of second location, in radians}
#'      \item{\eqn{L_2}{L2}: Longitude of second location, in radians}
#'      \item{\eqn{S, C}: Intermediary results}
#'      \item{\eqn{\theta}: Direction of the storm movement, in degrees}
#'    }
#'
#'    In cases where this equation results in values below 0 degrees or above
#'    360 degrees, the function applies modular arithmetic to bring the value
#'    back within the 0--360 degree range.
#'
#' @export
calc_bearing <- function(tclat_1, tclon_1, tclat_2, tclon_2) {
    .Call(`_stormwindmodel_calc_bearing`, tclat_1, tclon_1, tclat_2, tclon_2)
}

#' Calculate right-hand side of Willoughby Eqn. 3
#'
#' Calculates the right hand side of the version of Eqn. 3 in Willoughby et al.
#' (2006) with the dual exponential profile.
#'
#' @param n A numeric vector of one of the parameters of the Willoughby model.
#' @param A A numeric vector of one of the parameters of the Willoughby model.
#' @param X1 A numeric vector of one of the parameters of the Willoughby model.
#' @param Rmax A numeric vector giving the radius to maximum winds (in kilometers)
#'    for the tropical storm.
#'
#' @return A numeric vector with the value for the right-hand side of Eqn. 3 in
#'    Willoughby et al. 2006, using the dual exponential version of that
#'    equation.
#'
#' @references
#'
#' Willoughby HE, Darling RWR, and Rahn ME. 2006. Parametric representation
#' of the primary hurricane vortex. Part II: A new family of sectionally
#' continuous profiles. Monthly Weather Review 134(4):1102-1120.
#'
#' @export
NULL

#' Calculate radius to start of transition region
#'
#' Once you've solved for \eqn{\xi}, this function uses this value and the estimated
#' \eqn{R_{max}}{Rmax} to determine \eqn{R1}, the radius from the storm center to the start of
#' the transition region.
#'
#' @param xi A numeric value with the \eqn{\xi} value determined by
#'    \code{\link{solve_for_xi}}
#' @inheritParams will1a
#'
#' @return A numeric vector with the estimated value of \eqn{R_1}, a parameter
#'    required for the Willoughby wind model.
#'
#' @details This function is calculating the equation:
#'
#'    \deqn{R_1 = R_{max} - \xi(R_2 - R_1)}{
#'    R1 = Rmax - \xi(R2 - R1)}
#'
#'    where:
#'    \itemize{
#'      \item{\eqn{R_1}{R1}: A parameter for the Willoughby wind model (radius to
#'        start of transition region)}
#'      \item{\eqn{R_{max}}{Rmax}: Radius (in kilometers) to highest winds}
#'      \item{\eqn{R_2 - R_1}{R2 - R1}: Width of the transition region. This is
#'        assumed to be 25 kilometers if \eqn{R_{max}}{Rmax} is greater than
#'        20 kilometers and 15 kilometers otherwise.}
#'    }
#'
#' @references
#'
#' Willoughby HE, Darling RWR, and Rahn ME. 2006. Parametric representation
#' of the primary hurricane vortex. Part II: A new family of sectionally
#' continuous profiles. Monthly Weather Review 134(4):1102-1120.
#'
#' @export
NULL

#' Calculate X1 for Willoughby model
#'
#' Calculates \eqn{X_1}{X1}, a parameter for the Willoughby wind model using
#' equation 10a (Willoughby et al. 2006).
#'
#' @inheritParams will1a
#' @inheritParams will7a
#'
#' @return A numeric vector giving one of the parameters (\eqn{X_1}{X1})
#'    required for the Willoughby wind model.
#'
#' @details This function uses the following equation (equation 10a, Willoughby
#' et al. 2006) to calculate the \eqn{X_1}{X1} parameter:
#'    \deqn{X_1 = 317.1 - 2.026V_{max,G} + 1.915 \phi}{
#'    X1 = 317.1 - 2.026vmax_gl + 1.915 \phi}
#'    where:
#'    \itemize{
#'      \item{\eqn{X_1}{X1}: Parameter for the Willoughby wind model}
#'      \item{\eqn{V_{max,G}}{vmax_gl}: Maximum gradient-level 1-min sustained
#'         wind (m / s)}
#'      \item{\eqn{\phi}: Absolute value of latitude, in decimal degrees}
#'    }
#'
#' @references
#'
#' Willoughby HE, Darling RWR, and Rahn ME. 2006. Parametric representation
#' of the primary hurricane vortex. Part II: A new family of sectionally
#' continuous profiles. Monthly Weather Review 134(4):1102-1120.
#'
#' @export
NULL

#' Calculate n for the Willoughby model
#'
#' Calculates \eqn{n}, a parameter for the Willoughby model, using equation 10b
#' (Willoughby et al. 2006).
#'
#' @inheritParams will1a
#' @inheritParams will7a
#'
#' @return A numeric vector for \eqn{n}, a parameter needed for the Willoughby wind
#'    model.
#'
#' @details This function is calculating the equation:
#'    \deqn{n = 0.4067 + 0.0144 V_{max,G} - 0.0038 \phi}{
#'    n = 0.4067 + 0.0144 vmax_gl - 0.0038 \phi}
#'    where:
#'    \itemize{
#'      \item{\eqn{n}: Parameter for the Willoughby wind model}
#'      \item{\eqn{V_{max,G}}{vmax_gl}:  Maximum gradient-level 1-min sustained
#'         wind (m / s)}
#'      \item{\eqn{\phi}: Absolute value of latitude, in decimal degrees}
#'    }
#'
#' @references
#'
#' Willoughby HE, Darling RWR, and Rahn ME. 2006. Parametric representation
#' of the primary hurricane vortex. Part II: A new family of sectionally
#' continuous profiles. Monthly Weather Review 134(4):1102-1120.
#'
#' @export
NULL

#' Calculate A for Willoughby model
#'
#' Calculates \eqn{A}, a parameter for the Willoughby wind model, using equation 10c
#' (Willoughby et al. 2006).
#'
#' @inheritParams will1a
#' @inheritParams will7a
#'
#' @return A numeric vector that is a parameter required for the Willoughby
#'    model.
#'
#' @details This function calculates \eqn{A} using equation 10c (Willoughby et al.
#'    2006):
#'
#'    \deqn{A = 0.0696 + 0.0049 V_{max,G} - 0.0064 \phi}{
#'    A = 0.0696 + 0.0049 vmax_gl - 0.0064 \phi}
#'
#'    where:
#'    \itemize{
#'      \item{\eqn{A}: Parameter for the Willoughby wind model (any value
#'          of A calculated as negative is re-set to 0)}
#'      \item{\eqn{V_{max,G}}{vmax_gl}: Tangential component of the maximum
#'            gradient-level sustained wind speed (in m / s)}
#'      \item{\eqn{\phi}: Absolute value of latitude, in decimal degrees}
#'    }
#'    Any negative values of \eqn{A} are reset to 0.
#'
#' @references
#'
#' Willoughby HE, Darling RWR, and Rahn ME. 2006. Parametric representation
#' of the primary hurricane vortex. Part II: A new family of sectionally
#' continuous profiles. Monthly Weather Review 134(4):1102-1120.
#'
#' @export
NULL

will3_right <- function(n, A, X1, Rmax) {
    .Call(`_stormwindmodel_will3_right`, n, A, X1, Rmax)
}

calc_R1 <- function(Rmax, xi) {
    .Call(`_stormwindmodel_calc_R1`, Rmax, xi)
}

#' Calculate radius of maximum winds
#'
#' Calculates the radius at which the maximum wind occurs
#' (\eqn{R_{max}}{Rmax}), based on the maximum gradient-level 1-min sustained
#' wind (\eqn{V_{max,G}}{vmax_gl}) and latitude (\eqn{\phi}). This function
#' implements Willoughby et al. (2006), Equation 7a.
#'
#' @param tclat Numeric vector of the value of latitude, in degrees.
#' @param vmax_gl Maximum gradient-level 1-min sustained wind for the tropical cyclone
#'
#' @details This function fits the following equation:
#' \deqn{R_{max} = 46.4 e^{- 0.0155 V_{max,G} + 0.0169\phi}}{
#' Rmax = 46.4 e^(- 0.0155 vmax_gl) + 0.0169\phi}
#' where:
#' \itemize{
#'   \item{\eqn{R_{max}}{Rmax}: Radius from the storm center to the point at which the maximum wind occurs (km)}
#'   \item{\eqn{V_{max,G}}{vmax_gl}: Tangential wind component of the gradient-level maximum wind speed (m / s)}
#'   \item{\eqn{\phi}: Absolute value of latitude (in decimal degrees)}
#' }
#'
#' @return A numeric vector with \eqn{R_{max}}{Rmax}, the radius of maximum
#'    winds, in kilometers.
#'
#' @references
#'
#' Willoughby HE, Darling RWR, and Rahn ME. 2006. Parametric representation
#' of the primary hurricane vortex. Part II: A new family of sectionally
#' continuous profiles. Monthly Weather Review 134(4):1102-1120.
#'
#' @export
will7a <- function(vmax_gl, tclat) {
    .Call(`_stormwindmodel_will7a`, vmax_gl, tclat)
}

will10a <- function(vmax_gl, tclat) {
    .Call(`_stormwindmodel_will10a`, vmax_gl, tclat)
}

will10b <- function(vmax_gl, tclat) {
    .Call(`_stormwindmodel_will10b`, vmax_gl, tclat)
}

will10c <- function(vmax_gl, tclat) {
    .Call(`_stormwindmodel_will10c`, vmax_gl, tclat)
}