R/gainOmni.R

In jbrzusto/sensorgnome-R-package: Tools for the sensorgnome project.

#' Gain pattern of an omnidirectional antenna.
#'
#' Calculate the one-way far-field power gain (relative to isotropic)
#' for an omnidirectional (half-wave dipole) antenna, given the
#' displacement angle to points in space.
#' 
#' @param angle (radians) vector or matrix of direction angles in space.  A
#' vector is treated as an n x 1 matrix.  The first column of this
#' parameter is taken as a set of angles between the antenna axis and
#' the desired direction. Any other columns are ignored, since this
#' antenna pattern is symmetric around the antenna axis. 
#'
#' @return one-way far-field power gain factor, in linear units,
#' relative to the isotropic pattern.
#'
#' @note This gain factor is purely due to far-field antenna pattern,
#' and does not consider distance to the remote point(s) or relative
#' polarization of remote antenna.
#'
#' @references \url{http://en.wikipedia.org/wiki/Dipole_antenna#Half-wave_dipole}
#'
#' @author John Brzustowski \email{jbrzusto@@REMOVE_THIS_PART_fastmail.fm}

gainOmni = function(angle) {
    ## use the first column only, since the gain pattern doesn't depend
    ## on the second angle
    
    theta = as.matrix(angle)[,1]
    sinTheta = sin(theta)
    cosTheta = cos(theta)
    
    ## we use the closed-form formula from the reference.  The only
    ## parameter is \theta, the angle between antAxis and displacement
    ## to the remote position.
    
    ## E-field gain is D * cos (pi / 2 * cos(theta)) / sin(theta);
    ## square this for power.  Deal correctly with theta ~ 0.
    ## D is 1.280985

    ifelse(abs(sinTheta) >= .Machine$double.eps, 1.280985 * cos(pi / 2 * cosTheta) / sinTheta, 0)^2
}