geographiclib 0.0.1

data/ext/geographiclib/GeographicLib/SphericalEngine.hpp

@@ -0,0 +1,376 @@
+/**
+ * \file SphericalEngine.hpp
+ * \brief Header for GeographicLib::SphericalEngine class
+ *
+ * Copyright (c) Charles Karney (2011-2012) <charles@karney.com> and licensed
+ * under the MIT/X11 License.  For more information, see
+ * http://geographiclib.sourceforge.net/
+ **********************************************************************/
+
+#if !defined(GEOGRAPHICLIB_SPHERICALENGINE_HPP)
+#define GEOGRAPHICLIB_SPHERICALENGINE_HPP 1
+
+#include <vector>
+#include <istream>
+#include <GeographicLib/Constants.hpp>
+
+#if defined(_MSC_VER)
+// Squelch warnings about dll vs vector
+#  pragma warning (push)
+#  pragma warning (disable: 4251)
+#endif
+
+namespace GeographicLib {
+
+  class CircularEngine;
+
+  /**
+   * \brief The evaluation engine for SphericalHarmonic
+   *
+   * This serves as the backend to SphericalHarmonic, SphericalHarmonic1, and
+   * SphericalHarmonic2.  Typically end-users will not have to access this
+   * class directly.
+   *
+   * See SphericalEngine.cpp for more information on the implementation.
+   *
+   * Example of use:
+   * \include example-SphericalEngine.cpp
+   **********************************************************************/
+
+  class GEOGRAPHICLIB_EXPORT SphericalEngine {
+  private:
+    typedef Math::real real;
+    // A table of the square roots of integers
+    static std::vector<real> root_;
+    friend class CircularEngine; // CircularEngine needs access to root_, scale_
+    // An internal scaling of the coefficients to avoid overflow in
+    // intermediate calculations.
+    static real scale() {
+      using std::pow;
+      return pow(real(std::numeric_limits<real>::radix),
+                 -3 * (std::numeric_limits<real>::max_exponent < (1<<14) ?
+                       std::numeric_limits<real>::max_exponent : (1<<14)) / 5);
+    }
+    // Move latitudes near the pole off the axis by this amount.
+    static real eps() {
+      using std::sqrt;
+      return std::numeric_limits<real>::epsilon() *
+        sqrt(std::numeric_limits<real>::epsilon());
+    }
+    static const std::vector<real> Z_;
+    SphericalEngine();          // Disable constructor
+  public:
+    /**
+     * Supported normalizations for associated Legendre polynomials.
+     **********************************************************************/
+    enum normalization {
+      /**
+       * Fully normalized associated Legendre polynomials.  See
+       * SphericalHarmonic::FULL for documentation.
+       *
+       * @hideinitializer
+       **********************************************************************/
+      FULL = 0,
+      /**
+       * Schmidt semi-normalized associated Legendre polynomials.  See
+       * SphericalHarmonic::SCHMIDT for documentation.
+       *
+       * @hideinitializer
+       **********************************************************************/
+      SCHMIDT = 1,
+    };
+
+    /**
+     * \brief Package up coefficients for SphericalEngine
+     *
+     * This packages up the \e C, \e S coefficients and information about how
+     * the coefficients are stored into a single structure.  This allows a
+     * vector of type SphericalEngine::coeff to be passed to
+     * SphericalEngine::Value.  This class also includes functions to aid
+     * indexing into \e C and \e S.
+     *
+     * The storage layout of the coefficients is documented in
+     * SphericalHarmonic and SphericalHarmonic::SphericalHarmonic.
+     **********************************************************************/
+    class GEOGRAPHICLIB_EXPORT coeff {
+    private:
+      int _Nx, _nmx, _mmx;
+      std::vector<real>::const_iterator _Cnm;
+      std::vector<real>::const_iterator _Snm;
+    public:
+      /**
+       * A default constructor
+       **********************************************************************/
+      coeff()
+        : _Nx(-1)
+        , _nmx(-1)
+        , _mmx(-1)
+        , _Cnm(Z_.begin())
+        , _Snm(Z_.begin()) {}
+      /**
+       * The general constructor.
+       *
+       * @param[in] C a vector of coefficients for the cosine terms.
+       * @param[in] S a vector of coefficients for the sine terms.
+       * @param[in] N the degree giving storage layout for \e C and \e S.
+       * @param[in] nmx the maximum degree to be used.
+       * @param[in] mmx the maximum order to be used.
+       * @exception GeographicErr if \e N, \e nmx, and \e mmx do not satisfy
+       *   \e N &ge; \e nmx &ge; \e mmx &ge; &minus;1.
+       * @exception GeographicErr if \e C or \e S is not big enough to hold the
+       *   coefficients.
+       * @exception std::bad_alloc if the memory for the square root table
+       *   can't be allocated.
+       **********************************************************************/
+      coeff(const std::vector<real>& C,
+            const std::vector<real>& S,
+            int N, int nmx, int mmx)
+        : _Nx(N)
+        , _nmx(nmx)
+        , _mmx(mmx)
+        , _Cnm(C.begin())
+        , _Snm(S.begin())
+      {
+        if (!(_Nx >= _nmx && _nmx >= _mmx && _mmx >= -1))
+          throw GeographicErr("Bad indices for coeff");
+        if (!(index(_nmx, _mmx) < int(C.size()) &&
+              index(_nmx, _mmx) < int(S.size()) + (_Nx + 1)))
+          throw GeographicErr("Arrays too small in coeff");
+        SphericalEngine::RootTable(_nmx);
+      }
+      /**
+       * The constructor for full coefficient vectors.
+       *
+       * @param[in] C a vector of coefficients for the cosine terms.
+       * @param[in] S a vector of coefficients for the sine terms.
+       * @param[in] N the maximum degree and order.
+       * @exception GeographicErr if \e N does not satisfy \e N &ge; &minus;1.
+       * @exception GeographicErr if \e C or \e S is not big enough to hold the
+       *   coefficients.
+       * @exception std::bad_alloc if the memory for the square root table
+       *   can't be allocated.
+       **********************************************************************/
+      coeff(const std::vector<real>& C,
+            const std::vector<real>& S,
+            int N)
+        : _Nx(N)
+        , _nmx(N)
+        , _mmx(N)
+        , _Cnm(C.begin())
+        , _Snm(S.begin())
+      {
+        if (!(_Nx >= -1))
+          throw GeographicErr("Bad indices for coeff");
+        if (!(index(_nmx, _mmx) < int(C.size()) &&
+              index(_nmx, _mmx) < int(S.size()) + (_Nx + 1)))
+          throw GeographicErr("Arrays too small in coeff");
+        SphericalEngine::RootTable(_nmx);
+      }
+      /**
+       * @return \e N the degree giving storage layout for \e C and \e S.
+       **********************************************************************/
+      inline int N() const { return _Nx; }
+      /**
+       * @return \e nmx the maximum degree to be used.
+       **********************************************************************/
+      inline int nmx() const { return _nmx; }
+      /**
+       * @return \e mmx the maximum order to be used.
+       **********************************************************************/
+      inline int mmx() const { return _mmx; }
+      /**
+       * The one-dimensional index into \e C and \e S.
+       *
+       * @param[in] n the degree.
+       * @param[in] m the order.
+       * @return the one-dimensional index.
+       **********************************************************************/
+      inline int index(int n, int m) const
+      { return m * _Nx - m * (m - 1) / 2 + n; }
+      /**
+       * An element of \e C.
+       *
+       * @param[in] k the one-dimensional index.
+       * @return the value of the \e C coefficient.
+       **********************************************************************/
+      inline Math::real Cv(int k) const { return *(_Cnm + k); }
+      /**
+       * An element of \e S.
+       *
+       * @param[in] k the one-dimensional index.
+       * @return the value of the \e S coefficient.
+       **********************************************************************/
+      inline Math::real Sv(int k) const { return *(_Snm + (k - (_Nx + 1))); }
+      /**
+       * An element of \e C with checking.
+       *
+       * @param[in] k the one-dimensional index.
+       * @param[in] n the requested degree.
+       * @param[in] m the requested order.
+       * @param[in] f a multiplier.
+       * @return the value of the \e C coefficient multiplied by \e f in \e n
+       *   and \e m are in range else 0.
+       **********************************************************************/
+      inline Math::real Cv(int k, int n, int m, real f) const
+      { return m > _mmx || n > _nmx ? 0 : *(_Cnm + k) * f; }
+      /**
+       * An element of \e S with checking.
+       *
+       * @param[in] k the one-dimensional index.
+       * @param[in] n the requested degree.
+       * @param[in] m the requested order.
+       * @param[in] f a multiplier.
+       * @return the value of the \e S coefficient multiplied by \e f in \e n
+       *   and \e m are in range else 0.
+       **********************************************************************/
+      inline Math::real Sv(int k, int n, int m, real f) const
+      { return m > _mmx || n > _nmx ? 0 : *(_Snm + (k - (_Nx + 1))) * f; }
+
+      /**
+       * The size of the coefficient vector for the cosine terms.
+       *
+       * @param[in] N the maximum degree.
+       * @param[in] M the maximum order.
+       * @return the size of the vector of cosine terms as stored in column
+       *   major order.
+       **********************************************************************/
+      static inline int Csize(int N, int M)
+      { return (M + 1) * (2 * N - M + 2) / 2; }
+
+      /**
+       * The size of the coefficient vector for the sine terms.
+       *
+       * @param[in] N the maximum degree.
+       * @param[in] M the maximum order.
+       * @return the size of the vector of cosine terms as stored in column
+       *   major order.
+       **********************************************************************/
+      static inline int Ssize(int N, int M)
+      { return Csize(N, M) - (N + 1); }
+
+      /**
+       * Load coefficients from a binary stream.
+       *
+       * @param[in] stream the input stream.
+       * @param[out] N The maximum degree of the coefficients.
+       * @param[out] M The maximum order of the coefficients.
+       * @param[out] C The vector of cosine coefficients.
+       * @param[out] S The vector of sine coefficients.
+       * @exception GeographicErr if \e N and \e M do not satisfy \e N &ge;
+       *   \e M &ge; &minus;1.
+       * @exception GeographicErr if there's an error reading the data.
+       * @exception std::bad_alloc if the memory for \e C or \e S can't be
+       *   allocated.
+       *
+       * \e N and \e M are read as 4-byte ints.  \e C and \e S are resized to
+       * accommodate all the coefficients (with the \e m = 0 coefficients for
+       * \e S excluded) and the data for these coefficients read as 8-byte
+       * doubles.  The coefficients are stored in column major order.  The
+       * bytes in the stream should use little-endian ordering.  IEEE floating
+       * point is assumed for the coefficients.
+       **********************************************************************/
+      static void readcoeffs(std::istream& stream, int& N, int& M,
+                             std::vector<real>& C, std::vector<real>& S);
+    };
+
+    /**
+     * Evaluate a spherical harmonic sum and its gradient.
+     *
+     * @tparam gradp should the gradient be calculated.
+     * @tparam norm the normalization for the associated Legendre polynomials.
+     * @tparam L the number of terms in the coefficients.
+     * @param[in] c an array of coeff objects.
+     * @param[in] f array of coefficient multipliers.  f[0] should be 1.
+     * @param[in] x the \e x component of the cartesian position.
+     * @param[in] y the \e y component of the cartesian position.
+     * @param[in] z the \e z component of the cartesian position.
+     * @param[in] a the normalizing radius.
+     * @param[out] gradx the \e x component of the gradient.
+     * @param[out] grady the \e y component of the gradient.
+     * @param[out] gradz the \e z component of the gradient.
+     * @result the spherical harmonic sum.
+     *
+     * See the SphericalHarmonic class for the definition of the sum.  The
+     * coefficients used by this function are, for example, c[0].Cv + f[1] *
+     * c[1].Cv + ... + f[L&minus;1] * c[L&minus;1].Cv.  (Note that f[0] is \e
+     * not used.)  The upper limits on the sum are determined by c[0].nmx() and
+     * c[0].mmx(); these limits apply to \e all the components of the
+     * coefficients.  The parameters \e gradp, \e norm, and \e L are template
+     * parameters, to allow more optimization to be done at compile time.
+     *
+     * Clenshaw summation is used which permits the evaluation of the sum
+     * without the need to allocate temporary arrays.  Thus this function never
+     * throws an exception.
+     **********************************************************************/
+    template<bool gradp, normalization norm, int L>
+      static Math::real Value(const coeff c[], const real f[],
+                              real x, real y, real z, real a,
+                              real& gradx, real& grady, real& gradz);
+
+    /**
+     * Create a CircularEngine object
+     *
+     * @tparam gradp should the gradient be calculated.
+     * @tparam norm the normalization for the associated Legendre polynomials.
+     * @tparam L the number of terms in the coefficients.
+     * @param[in] c an array of coeff objects.
+     * @param[in] f array of coefficient multipliers.  f[0] should be 1.
+     * @param[in] p the radius of the circle = sqrt(<i>x</i><sup>2</sup> +
+     *   <i>y</i><sup>2</sup>).
+     * @param[in] z the height of the circle.
+     * @param[in] a the normalizing radius.
+     * @exception std::bad_alloc if the memory for the CircularEngine can't be
+     *   allocated.
+     * @result the CircularEngine object.
+     *
+     * If you need to evaluate the spherical harmonic sum for several points
+     * with constant \e f, \e p = sqrt(<i>x</i><sup>2</sup> +
+     * <i>y</i><sup>2</sup>), \e z, and \e a, it is more efficient to construct
+     * call SphericalEngine::Circle to give a CircularEngine object and then
+     * call CircularEngine::operator()() with arguments <i>x</i>/\e p and
+     * <i>y</i>/\e p.
+     **********************************************************************/
+    template<bool gradp, normalization norm, int L>
+      static CircularEngine Circle(const coeff c[], const real f[],
+                                   real p, real z, real a);
+    /**
+     * Check that the static table of square roots is big enough and enlarge it
+     * if necessary.
+     *
+     * @param[in] N the maximum degree to be used in SphericalEngine.
+     * @exception std::bad_alloc if the memory for the square root table can't
+     *   be allocated.
+     *
+     * Typically, there's no need for an end-user to call this routine, because
+     * the constructors for SphericalEngine::coeff do so.  However, since this
+     * updates a static table, there's a possible race condition in a
+     * multi-threaded environment.  Because this routine does nothing if the
+     * table is already large enough, one way to avoid race conditions is to
+     * call this routine at program start up (when it's still single threaded),
+     * supplying the largest degree that your program will use.  E.g., \code
+     GeographicLib::SphericalEngine::RootTable(2190);
+     \endcode
+     * suffices to accommodate extant magnetic and gravity models.
+     **********************************************************************/
+    static void RootTable(int N);
+
+    /**
+     * Clear the static table of square roots and release the memory.  Call
+     * this only when you are sure you no longer will be using SphericalEngine.
+     * Your program will crash if you call SphericalEngine after calling this
+     * routine.  <b>It's safest not to call this routine at all.</b> (The space
+     * used by the table is modest.)
+     **********************************************************************/
+    static void ClearRootTable() {
+      std::vector<real> temp(0);
+      root_.swap(temp);
+    }
+  };
+
+} // namespace GeographicLib
+
+#if defined(_MSC_VER)
+#  pragma warning (pop)
+#endif
+
+#endif  // GEOGRAPHICLIB_SPHERICALENGINE_HPP

data/ext/geographiclib/GeographicLib/SphericalHarmonic.hpp

@@ -0,0 +1,354 @@
+/**
+ * \file SphericalHarmonic.hpp
+ * \brief Header for GeographicLib::SphericalHarmonic class
+ *
+ * Copyright (c) Charles Karney (2011) <charles@karney.com> and licensed under
+ * the MIT/X11 License.  For more information, see
+ * http://geographiclib.sourceforge.net/
+ **********************************************************************/
+
+#if !defined(GEOGRAPHICLIB_SPHERICALHARMONIC_HPP)
+#define GEOGRAPHICLIB_SPHERICALHARMONIC_HPP 1
+
+#include <vector>
+#include <GeographicLib/Constants.hpp>
+#include <GeographicLib/SphericalEngine.hpp>
+#include <GeographicLib/CircularEngine.hpp>
+
+namespace GeographicLib {
+
+  /**
+   * \brief Spherical harmonic series
+   *
+   * This class evaluates the spherical harmonic sum \verbatim
+   V(x, y, z) = sum(n = 0..N)[ q^(n+1) * sum(m = 0..n)[
+     (C[n,m] * cos(m*lambda) + S[n,m] * sin(m*lambda)) *
+     P[n,m](cos(theta)) ] ]
+   \endverbatim
+   * where
+   * - <i>p</i><sup>2</sup> = <i>x</i><sup>2</sup> + <i>y</i><sup>2</sup>,
+   * - <i>r</i><sup>2</sup> = <i>p</i><sup>2</sup> + <i>z</i><sup>2</sup>,
+   * - \e q = <i>a</i>/<i>r</i>,
+   * - &theta; = atan2(\e p, \e z) = the spherical \e colatitude,
+   * - &lambda; = atan2(\e y, \e x) = the longitude.
+   * - P<sub><i>nm</i></sub>(\e t) is the associated Legendre polynomial of
+   *   degree \e n and order \e m.
+   *
+   * Two normalizations are supported for P<sub><i>nm</i></sub>
+   * - fully normalized denoted by SphericalHarmonic::FULL.
+   * - Schmidt semi-normalized denoted by SphericalHarmonic::SCHMIDT.
+   *
+   * Clenshaw summation is used for the sums over both \e n and \e m.  This
+   * allows the computation to be carried out without the need for any
+   * temporary arrays.  See SphericalEngine.cpp for more information on the
+   * implementation.
+   *
+   * References:
+   * - C. W. Clenshaw,
+   *   <a href="https://dx.doi.org/10.1090/S0025-5718-1955-0071856-0">
+   *   A note on the summation of Chebyshev series</a>,
+   *   %Math. Tables Aids Comput. 9(51), 118--120 (1955).
+   * - R. E. Deakin, Derivatives of the earth's potentials, Geomatics
+   *   Research Australasia 68, 31--60, (June 1998).
+   * - W. A. Heiskanen and H. Moritz, Physical Geodesy, (Freeman, San
+   *   Francisco, 1967).  (See Sec. 1-14, for a definition of Pbar.)
+   * - S. A. Holmes and W. E. Featherstone,
+   *   <a href="https://dx.doi.org/10.1007/s00190-002-0216-2">
+   *   A unified approach to the Clenshaw summation and the recursive
+   *   computation of very high degree and order normalised associated Legendre
+   *   functions</a>, J. Geodesy 76(5), 279--299 (2002).
+   * - C. C. Tscherning and K. Poder,
+   *   <a href="http://cct.gfy.ku.dk/publ_cct/cct80.pdf">
+   *   Some geodetic applications of Clenshaw summation</a>,
+   *   Boll. Geod. Sci. Aff. 41(4), 349--375 (1982).
+   *
+   * Example of use:
+   * \include example-SphericalHarmonic.cpp
+   **********************************************************************/
+
+  class GEOGRAPHICLIB_EXPORT SphericalHarmonic {
+  public:
+    /**
+     * Supported normalizations for the associated Legendre polynomials.
+     **********************************************************************/
+    enum normalization {
+      /**
+       * Fully normalized associated Legendre polynomials.
+       *
+       * These are defined by
+       * <i>P</i><sub><i>nm</i></sub><sup>full</sup>(\e z)
+       * = (&minus;1)<sup><i>m</i></sup>
+       * sqrt(\e k (2\e n + 1) (\e n &minus; \e m)! / (\e n + \e m)!)
+       * <b>P</b><sub><i>n</i></sub><sup><i>m</i></sup>(\e z), where
+       * <b>P</b><sub><i>n</i></sub><sup><i>m</i></sup>(\e z) is Ferrers
+       * function (also known as the Legendre function on the cut or the
+       * associated Legendre polynomial) http://dlmf.nist.gov/14.7.E10 and \e k
+       * = 1 for \e m = 0 and \e k = 2 otherwise.
+       *
+       * The mean squared value of
+       * <i>P</i><sub><i>nm</i></sub><sup>full</sup>(cos&theta;)
+       * cos(<i>m</i>&lambda;) and
+       * <i>P</i><sub><i>nm</i></sub><sup>full</sup>(cos&theta;)
+       * sin(<i>m</i>&lambda;) over the sphere is 1.
+       *
+       * @hideinitializer
+       **********************************************************************/
+      FULL = SphericalEngine::FULL,
+      /**
+       * Schmidt semi-normalized associated Legendre polynomials.
+       *
+       * These are defined by
+       * <i>P</i><sub><i>nm</i></sub><sup>schmidt</sup>(\e z)
+       * = (&minus;1)<sup><i>m</i></sup>
+       * sqrt(\e k (\e n &minus; \e m)! / (\e n + \e m)!)
+       * <b>P</b><sub><i>n</i></sub><sup><i>m</i></sup>(\e z), where
+       * <b>P</b><sub><i>n</i></sub><sup><i>m</i></sup>(\e z) is Ferrers
+       * function (also known as the Legendre function on the cut or the
+       * associated Legendre polynomial) http://dlmf.nist.gov/14.7.E10 and \e k
+       * = 1 for \e m = 0 and \e k = 2 otherwise.
+       *
+       * The mean squared value of
+       * <i>P</i><sub><i>nm</i></sub><sup>schmidt</sup>(cos&theta;)
+       * cos(<i>m</i>&lambda;) and
+       * <i>P</i><sub><i>nm</i></sub><sup>schmidt</sup>(cos&theta;)
+       * sin(<i>m</i>&lambda;) over the sphere is 1/(2\e n + 1).
+       *
+       * @hideinitializer
+       **********************************************************************/
+      SCHMIDT = SphericalEngine::SCHMIDT,
+    };
+
+  private:
+    typedef Math::real real;
+    SphericalEngine::coeff _c[1];
+    real _a;
+    unsigned _norm;
+
+  public:
+    /**
+     * Constructor with a full set of coefficients specified.
+     *
+     * @param[in] C the coefficients <i>C</i><sub><i>nm</i></sub>.
+     * @param[in] S the coefficients <i>S</i><sub><i>nm</i></sub>.
+     * @param[in] N the maximum degree and order of the sum
+     * @param[in] a the reference radius appearing in the definition of the
+     *   sum.
+     * @param[in] norm the normalization for the associated Legendre
+     *   polynomials, either SphericalHarmonic::FULL (the default) or
+     *   SphericalHarmonic::SCHMIDT.
+     * @exception GeographicErr if \e N does not satisfy \e N &ge; &minus;1.
+     * @exception GeographicErr if \e C or \e S is not big enough to hold the
+     *   coefficients.
+     *
+     * The coefficients <i>C</i><sub><i>nm</i></sub> and
+     * <i>S</i><sub><i>nm</i></sub> are stored in the one-dimensional vectors
+     * \e C and \e S which must contain (\e N + 1)(\e N + 2)/2 and \e N (\e N +
+     * 1)/2 elements, respectively, stored in "column-major" order.  Thus for
+     * \e N = 3, the order would be:
+     * <i>C</i><sub>00</sub>,
+     * <i>C</i><sub>10</sub>,
+     * <i>C</i><sub>20</sub>,
+     * <i>C</i><sub>30</sub>,
+     * <i>C</i><sub>11</sub>,
+     * <i>C</i><sub>21</sub>,
+     * <i>C</i><sub>31</sub>,
+     * <i>C</i><sub>22</sub>,
+     * <i>C</i><sub>32</sub>,
+     * <i>C</i><sub>33</sub>.
+     * In general the (\e n,\e m) element is at index \e m \e N &minus; \e m
+     * (\e m &minus; 1)/2 + \e n.  The layout of \e S is the same except that
+     * the first column is omitted (since the \e m = 0 terms never contribute
+     * to the sum) and the 0th element is <i>S</i><sub>11</sub>
+     *
+     * The class stores <i>pointers</i> to the first elements of \e C and \e S.
+     * These arrays should not be altered or destroyed during the lifetime of a
+     * SphericalHarmonic object.
+     **********************************************************************/
+    SphericalHarmonic(const std::vector<real>& C,
+                      const std::vector<real>& S,
+                      int N, real a, unsigned norm = FULL)
+      : _a(a)
+      , _norm(norm)
+    { _c[0] = SphericalEngine::coeff(C, S, N); }
+
+    /**
+     * Constructor with a subset of coefficients specified.
+     *
+     * @param[in] C the coefficients <i>C</i><sub><i>nm</i></sub>.
+     * @param[in] S the coefficients <i>S</i><sub><i>nm</i></sub>.
+     * @param[in] N the degree used to determine the layout of \e C and \e S.
+     * @param[in] nmx the maximum degree used in the sum.  The sum over \e n is
+     *   from 0 thru \e nmx.
+     * @param[in] mmx the maximum order used in the sum.  The sum over \e m is
+     *   from 0 thru min(\e n, \e mmx).
+     * @param[in] a the reference radius appearing in the definition of the
+     *   sum.
+     * @param[in] norm the normalization for the associated Legendre
+     *   polynomials, either SphericalHarmonic::FULL (the default) or
+     *   SphericalHarmonic::SCHMIDT.
+     * @exception GeographicErr if \e N, \e nmx, and \e mmx do not satisfy
+     *   \e N &ge; \e nmx &ge; \e mmx &ge; &minus;1.
+     * @exception GeographicErr if \e C or \e S is not big enough to hold the
+     *   coefficients.
+     *
+     * The class stores <i>pointers</i> to the first elements of \e C and \e S.
+     * These arrays should not be altered or destroyed during the lifetime of a
+     * SphericalHarmonic object.
+     **********************************************************************/
+    SphericalHarmonic(const std::vector<real>& C,
+                      const std::vector<real>& S,
+                      int N, int nmx, int mmx,
+                      real a, unsigned norm = FULL)
+      : _a(a)
+      , _norm(norm)
+    { _c[0] = SphericalEngine::coeff(C, S, N, nmx, mmx); }
+
+    /**
+     * A default constructor so that the object can be created when the
+     * constructor for another object is initialized.  This default object can
+     * then be reset with the default copy assignment operator.
+     **********************************************************************/
+    SphericalHarmonic() {}
+
+    /**
+     * Compute the spherical harmonic sum.
+     *
+     * @param[in] x cartesian coordinate.
+     * @param[in] y cartesian coordinate.
+     * @param[in] z cartesian coordinate.
+     * @return \e V the spherical harmonic sum.
+     *
+     * This routine requires constant memory and thus never throws an
+     * exception.
+     **********************************************************************/
+    Math::real operator()(real x, real y, real z) const {
+      real f[] = {1};
+      real v = 0;
+      real dummy;
+      switch (_norm) {
+      case FULL:
+        v = SphericalEngine::Value<false, SphericalEngine::FULL, 1>
+          (_c, f, x, y, z, _a, dummy, dummy, dummy);
+        break;
+      case SCHMIDT:
+        v = SphericalEngine::Value<false, SphericalEngine::SCHMIDT, 1>
+          (_c, f, x, y, z, _a, dummy, dummy, dummy);
+        break;
+      }
+      return v;
+    }
+
+    /**
+     * Compute a spherical harmonic sum and its gradient.
+     *
+     * @param[in] x cartesian coordinate.
+     * @param[in] y cartesian coordinate.
+     * @param[in] z cartesian coordinate.
+     * @param[out] gradx \e x component of the gradient
+     * @param[out] grady \e y component of the gradient
+     * @param[out] gradz \e z component of the gradient
+     * @return \e V the spherical harmonic sum.
+     *
+     * This is the same as the previous function, except that the components of
+     * the gradients of the sum in the \e x, \e y, and \e z directions are
+     * computed.  This routine requires constant memory and thus never throws
+     * an exception.
+     **********************************************************************/
+    Math::real operator()(real x, real y, real z,
+                          real& gradx, real& grady, real& gradz) const {
+      real f[] = {1};
+      real v = 0;
+      switch (_norm) {
+      case FULL:
+        v = SphericalEngine::Value<true, SphericalEngine::FULL, 1>
+          (_c, f, x, y, z, _a, gradx, grady, gradz);
+        break;
+      case SCHMIDT:
+        v = SphericalEngine::Value<true, SphericalEngine::SCHMIDT, 1>
+          (_c, f, x, y, z, _a, gradx, grady, gradz);
+        break;
+      }
+      return v;
+    }
+
+    /**
+     * Create a CircularEngine to allow the efficient evaluation of several
+     * points on a circle of latitude.
+     *
+     * @param[in] p the radius of the circle.
+     * @param[in] z the height of the circle above the equatorial plane.
+     * @param[in] gradp if true the returned object will be able to compute the
+     *   gradient of the sum.
+     * @exception std::bad_alloc if the memory for the CircularEngine can't be
+     *   allocated.
+     * @return the CircularEngine object.
+     *
+     * SphericalHarmonic::operator()() exchanges the order of the sums in the
+     * definition, i.e., &sum;<sub><i>n</i> = 0..<i>N</i></sub>
+     * &sum;<sub><i>m</i> = 0..<i>n</i></sub> becomes &sum;<sub><i>m</i> =
+     * 0..<i>N</i></sub> &sum;<sub><i>n</i> = <i>m</i>..<i>N</i></sub>.
+     * SphericalHarmonic::Circle performs the inner sum over degree \e n (which
+     * entails about <i>N</i><sup>2</sup> operations).  Calling
+     * CircularEngine::operator()() on the returned object performs the outer
+     * sum over the order \e m (about \e N operations).
+     *
+     * Here's an example of computing the spherical sum at a sequence of
+     * longitudes without using a CircularEngine object \code
+     SphericalHarmonic h(...);     // Create the SphericalHarmonic object
+     double r = 2, lat = 33, lon0 = 44, dlon = 0.01;
+     double
+       phi = lat * Math::degree<double>(),
+       z = r * sin(phi), p = r * cos(phi);
+     for (int i = 0; i <= 100; ++i) {
+       real
+         lon = lon0 + i * dlon,
+         lam = lon * Math::degree<double>();
+       std::cout << lon << " " << h(p * cos(lam), p * sin(lam), z) << "\n";
+     }
+     \endcode
+     * Here is the same calculation done using a CircularEngine object.  This
+     * will be about <i>N</i>/2 times faster. \code
+     SphericalHarmonic h(...);     // Create the SphericalHarmonic object
+     double r = 2, lat = 33, lon0 = 44, dlon = 0.01;
+     double
+       phi = lat * Math::degree<double>(),
+       z = r * sin(phi), p = r * cos(phi);
+     CircularEngine c(h(p, z, false)); // Create the CircularEngine object
+     for (int i = 0; i <= 100; ++i) {
+       real
+         lon = lon0 + i * dlon;
+       std::cout << lon << " " << c(lon) << "\n";
+     }
+     \endcode
+     **********************************************************************/
+    CircularEngine Circle(real p, real z, bool gradp) const {
+      real f[] = {1};
+      switch (_norm) {
+      case FULL:
+        return gradp ?
+          SphericalEngine::Circle<true, SphericalEngine::FULL, 1>
+          (_c, f, p, z, _a) :
+          SphericalEngine::Circle<false, SphericalEngine::FULL, 1>
+          (_c, f, p, z, _a);
+        break;
+      case SCHMIDT:
+      default:                  // To avoid compiler warnings
+        return gradp ?
+          SphericalEngine::Circle<true, SphericalEngine::SCHMIDT, 1>
+          (_c, f, p, z, _a) :
+          SphericalEngine::Circle<false, SphericalEngine::SCHMIDT, 1>
+          (_c, f, p, z, _a);
+        break;
+      }
+    }
+
+    /**
+     * @return the zeroth SphericalEngine::coeff object.
+     **********************************************************************/
+    const SphericalEngine::coeff& Coefficients() const
+    { return _c[0]; }
+  };
+
+} // namespace GeographicLib
+
+#endif  // GEOGRAPHICLIB_SPHERICALHARMONIC_HPP