// -*- text -*-
/**
 * \file geodesic-for.dox
 * \brief Documentation for geodesic routines implemented in Fortran
 *
 * Written by Charles Karney <charles@karney.com> and licensed under the
 * MIT/X11 License.  For more information, see
 * https://geographiclib.sourceforge.io/
 **********************************************************************/

/**
\mainpage Geodesic routines implemented in Fortran
\author Charles F. F. Karney (charles@karney.com)
\version 1.50

The documentation for other versions is available at
<tt>https://geographiclib.sourceforge.io/m.nn/Fortran</tt> for versions numbers
<tt>m.nn</tt> &ge; 1.28.

\section abstract-for Abstract

This is a Fortran implementation of the geodesic algorithms from <a
href="https://geographiclib.sourceforge.io">GeographicLib</a>.  This is a
self-contained library which makes it easy to do geodesic computations
for an ellipsoid of revolution in a Fortran program.  It is written in
Fortran 77 (avoiding features which are now deprecated) and should
compile correctly with just about any Fortran compiler.

\section download-for Downloading the source

The Fortran library is part of %GeographicLib which available for download at
- <a href="https://sourceforge.net/projects/geographiclib/files/distrib/GeographicLib-1.50.tar.gz">
  GeographicLib-1.50.tar.gz</a>
- <a href="https://sourceforge.net/projects/geographiclib/files/distrib/GeographicLib-1.50.zip">
  GeographicLib-1.50.zip</a>
.
as either a compressed tar file (tar.gz) or a zip file.  After unpacking
the source, the Fortran library can be found in the directory
<tt>legacy/Fortran</tt>.  The library consists of the file
geodesic.for.  The Fortran-90 interface is defined in geodesic.inc.

Licensed under the
<a href="http://www.opensource.org/licenses/MIT">MIT/X11 License</a>; see
<a href="https://geographiclib.sourceforge.io/html/LICENSE.txt">LICENSE.txt</a>.

\section doc-for Library documentation

Here is the
\link geodesic.for <i>application programming interface</i>\endlink
for the library (this is just the documentation for the source file,
geodesic.for).

\section samples-for Sample programs

Also included are 3 small test programs:
 - geoddirect.for is a simple command line utility for solving the
   direct geodesic problem;
 - geodinverse.for is a simple command line utility for solving the
   inverse geodesic problem;
 - planimeter.for is a simple command line utility for computing the
   area of a geodesic polygon given its vertices.
 .
Here, for example, is geodinverse.for
\include geodinverse.for
To compile, link, and run this, you would typically use \verbatim
f95 -o geodinverse geodinverse.for geodesic.for
echo 30 0 29.5 179.5 | ./geodinverse \endverbatim
These sample programs can also be built with the supplied cmake file,
CMakeLists.txt, as follows \verbatim
mkdir BUILD
cd BUILD
cmake ..
make
make test
echo 30 0 29.5 179.5 | ./geodinverse \endverbatim

Finally, the two programs
 - ngsforward
 - ngsinverse
 .
which are also built with cmake, provide drop-in replacements for
replacements for the NGS tools FORWARD and INVERSE available from
http://www.ngs.noaa.gov/PC_PROD/Inv_Fwd/.
These cure two problems of the Vincenty algorithms used by NGS:
 - the accuracy is "only" 0.1 mm;
 - the inverse program sometimes goes into an infinite loop.
 .
The corresponding source files
 - ngsforward.for
 - ngsinverse.for
 - ngscommon.for
 .
are derived from the NGS source files
 - forward.for, version 2.0, dated 2002-08-21
 - inverse.for, version 3.0, dated 2012-11-04
 .
and are therefore in the public domain.

\section library-for Using the library

- Optionally put @code{.for}
  include "geodesic.inc"
  @endcode
  in declaration section of your subroutines.
- make calls to the geodesic routines from your code.  The interface to
  the library is documented in geodesic.for.
- Compile and link as described above.

\section external-for External links

- These algorithms are derived in C. F. F. Karney,
  <a href="https://doi.org/10.1007/s00190-012-0578-z">
  Algorithms for geodesics</a>,
  J. Geodesy <b>87</b>, 43--55 (2013)
  (<a href="https://geographiclib.sourceforge.io/geod-addenda.html"> addenda</a>).
- A longer paper on geodesics: C. F. F. Karney,
   <a href="https://arxiv.org/abs/1102.1215v1">Geodesics
   on an ellipsoid of revolution</a>,
   Feb. 2011
   (<a href="https://geographiclib.sourceforge.io/geod-addenda.html#geod-errata">
   errata</a>).
- <a href="https://sourceforge.net/projects/geographiclib/">
  Main project page</a>
- <a href="https://geographiclib.sourceforge.io/">
  GeographicLib web site</a>
  - Documentation on the C++ classes: GeographicLib::Geodesic,
    GeographicLib::GeodesicLine, GeographicLib::PolygonAreaT.
  - The section in the %GeographicLib documentation on geodesics: \ref
    geodesic.
- <a href="https://sourceforge.net/p/geographiclib/code/ci/release/tree/">
  git repository</a>
- Implementations in various languages
  - C++ (complete library):
    <a href="../index.html">
      documentation</a>,
    <a href="https://sourceforge.net/projects/geographiclib/files/distrib">
      download</a>;
  - C (geodesic routines):
    <a href="../C/index.html">
      documentation</a>, also included with recent versions of
    <a href="https://github.com/OSGeo/proj.4/wiki">
      proj.4</a>;
  - Fortran (geodesic routines):
    <a href="../Fortran/index.html">
      documentation</a>;
  - Java (geodesic routines):
    <a href="http://repo1.maven.org/maven2/net/sf/geographiclib/GeographicLib-Java/">
      Maven Central package</a>,
    <a href="../java/index.html">
      documentation</a>;
  - JavaScript (geodesic routines):
    <a href="https://www.npmjs.com/package/geographiclib">
      npm package</a>,
    <a href="../js/index.html">
      documentation</a>;
  - Python (geodesic routines):
    <a href="http://pypi.python.org/pypi/geographiclib">
      PyPI package</a>,
    <a href="../python/index.html">
      documentation</a>;
  - Matlab/Octave (geodesic and some other routines):
    <a href="https://www.mathworks.com/matlabcentral/fileexchange/50605">
      Matlab Central package</a>,
    <a href="https://viewer.mathworks.com/?viewer=plain_code&url=https%3A%2F%2Fwww.mathworks.com%2Fmatlabcentral%2Fmlc-downloads%2Fdownloads%2Fsubmissions%2F50605%2Fversions%2F15%2Fcontents%2FContents.m">
      documentation</a>;
  - C# (.NET wrapper for complete C++ library):
    <a href="../NET/index.html">
      documentation</a>.
- <a href="https://geographiclib.sourceforge.io/geodesic-papers/biblio.html">
  A geodesic bibliography</a>.
- The wikipedia page,
  <a href="https://en.wikipedia.org/wiki/Geodesics_on_an_ellipsoid">
  Geodesics on an ellipsoid</a>.

\section changes-for Change log

 - <a href="https://geographiclib.sourceforge.io/1.50/Fortran">Version 1.50</a>
   (released 2019-09-24)
   - Allow arbitrarily complex polygons in area.  In the case of
     self-intersecting polygons the area is accumulated "algebraically",
     e.g., the areas of the 2 loops in a figure-8 polygon will partially
     cancel.

 - <a href="https://geographiclib.sourceforge.io/1.49/Fortran">Version 1.49</a>
   (released 2017-10-05)
   - Fix code formatting and add two tests.

 - <a href="https://geographiclib.sourceforge.io/1.48/Fortran">Version 1.48</a>
   (released 2017-04-09)
   - Change default range for longitude and azimuth to
     (&minus;180&deg;, 180&deg;] (instead of
     [&minus;180&deg;, 180&deg;)).

 - <a href="https://geographiclib.sourceforge.io/1.47/Fortran">Version 1.47</a>
   (released 2017-02-15)
   - Improve accuracy of area calculation (fixing a flaw introduced in
     version 1.46).

 - <a href="https://geographiclib.sourceforge.io/1.46/Fortran">Version 1.46</a>
   (released 2016-02-15)
   - More accurate inverse solution when longitude difference is close
     to 180&deg;.

 - <a href="https://geographiclib.sourceforge.io/1.45/Fortran">Version 1.45</a>
   (released 2015-09-30)
   - The solution of the inverse problem now correctly returns NaNs if
     one of the latitudes is a NaN.
   - Include a test suite that can be run with "make test" after
     configuring with cmake.
   - The library now treats latitudes outside the range [&minus;90&deg;,
     90&deg;] as NaNs; so the sample programs no longer check for legal
     values of latitude.

 - <a href="https://geographiclib.sourceforge.io/1.44/Fortran">Version 1.44</a>
   (released 2015-08-14)
   - Improve accuracy of calculations by evaluating trigonometric
     functions more carefully and replacing the series for the reduced
     length with one with a smaller truncation error.
   - The allowed ranges for longitudes and azimuths is now unlimited;
     it used to be [&minus;540&deg;, 540&deg;).
   - The sample programs, geoddirect and geodinverse, enforce the
     restriction of latitude to [&minus;90&deg;, 90&deg;].
   - The inverse calculation sets \e s12 to zero for coincident points
     at pole (instead of returning a tiny quantity).
**********************************************************************/