-------------------------------------------------------------------------------
help for vincenty
-------------------------------------------------------------------------------

Calculate distances on the Earth's surface

        vincenty lat1 lon1 lat2 lon2 [if exp] [in range]
              [, vin(varname) hav(varname) loc(varname) replace immed inkm]

Description

vincenty is used for calculating geodesic distances between a pair of points on
the surface of the Earth (specified in signed decimal degrees latitude and
longitude), using an accurate ellipsoidal model of the Earth.  see 
http://www.ngs.noaa.gov/PUBS_LIB/inverse.pdf.

Acknowledgements

The program is named for Thaddeus Vincenty who wrote "Direct and Inverse
Solutions of Geodesics on the Ellipsoid with application of nested equations"
but the code borrows extensively from Javascript code at 
http://www.movable-type.co.uk/scripts/LatLongVincenty.html.

Limitations

The calculations are accurate to insane precision assuming elevation above the
ellipsoid is zero, so the real 3D distance could differ substantially.  Note
that elevation, even if available, cannot be included in these calculations.

The Vincenty-style calculations may fail if distance is close to a quarter of
the Earth's circumference, or if it is close to zero, where the trig functions
tax the limits of machine precision. Haversine calculations and those based on
the Law of Cosines are more robust to these odd cases.

Options

immed calculates distances between two locations specified on the command line.
    If immed is not specified, one set of locations should contain variable
    names. If no new variable names are specified, the immediate option is
    implied.

inkm requests distances expressed in kilometers; the default is miles, each of
    which is 5280*12*2.54/1e5=1.609344 km.

vin stores the results of Vincenty-style calculations in the named variable.

hav stores the results of Haversine-based calculations in the named variable.

loc stores the results of Law-of-Cosines-based calculations in the named
    variable.

Examples

        . set obs 5000

        . g double lon1=360*uniform()-180

        . g double lon2=360*uniform()-180

        . g double lat1=360*uniform()-180

        . g double lat2=180*uniform()-90

        . drop if abs(lat1)>90

        . vincenty lat1 lon1 lat2 lon2, v(v) hav(h) l(loc)

        . gen double diff=(v-h)/v

        . su v h diff

        . vincenty 38.9 -77.077 39 -77.077

        . ret li

        . vincenty 38.9 -77.077 39 -77.077, v(vb) h(hb)

        . vincenty lat1 lon1 39 -77, h(ddc)

        . su

{Remarks

Type return list to see saved results in r() in the immediate version of the
command.

Author

    Austin Nichols
    austinnichols@gmail.com