/// <summary>
/// Compute the spherical harmonic sum and its gradient.
/// </summary>
/// <param name="x"><i>x</i> component of the cartesian coordinate.</param>
/// <param name="y"><i>y</i> component of the cartesian coordinate.</param>
/// <param name="z"><i>z</i> component of the cartesian coordinate.</param>
/// <param name="gradx"><i>x</i> component of the gradient.</param>
/// <param name="grady"><i>y</i> component of the gradient.</param>
/// <param name="gradz"><i>z</i> component of the gradient.</param>
/// <returns><i>V</i>, the spherical harmonic sum.</returns>
/// <remarks>
/// This is the same as <see cref="Evaluate(double, double, double)"/>,
/// except that the components of the gradients of the sum in the <i>x</i>, <i>y</i>, and <i>z</i> directions are computed.
/// This routine requires constant memory and thus never throws an exception.
/// </remarks>
public double Evaluate(double x, double y, double z,
out double gradx, out double grady, out double gradz)
{
Span <double> f = stackalloc double[] { 1 };
return(SphericalEngine.Value(true, _norm, _c.Span, f, x, y, z, _a, out gradx, out grady, out gradz));
}
/// <summary>
/// Create a <see cref="CircularEngine"/> to allow the efficient evaluation of several points on a circle of latitude.
/// </summary>
/// <param name="p">the radius of the circle.</param>
/// <param name="z">the height of the circle above the equatorial plane.</param>
/// <param name="gradp">if <see langword="true"/> the returned object will be able to compute the gradient of the sum.</param>
/// <returns>A <see cref="CircularEngine"/> instance.</returns>
/// <remarks>
/// <see cref="Evaluate(double, double, double)"/> exchanges the order of the sums in the definition,
/// i.e., ∑<i>n</i> = 0..<i>N</i> ∑<i>m</i> = 0..<i>n</i> becomes ∑<i>m</i> = 0..<i>N</i> ∑<i>n</i> = <i>m</i>..<i>N</i>.
/// <see cref="Circle(double, double, bool)"/> performs the inner sum over degree n (which entails about <i>N</i>^2 operations).
/// Calling <see cref="CircularEngine.Evaluate(double)"/> on the returned object performs the outer sum over the order <i>m</i> (about <i>N</i> operations).
/// </remarks>
public CircularEngine Circle(double p, double z, bool gradp)
{
Span <double> f = stackalloc double[] { 1 };
return(SphericalEngine.Circle(true, _norm, _c.Span, f, p, z, _a));
}
/// <summary>
/// Compute the spherical harmonic sum.
/// </summary>
/// <param name="x"><i>x</i> component of the cartesian coordinate.</param>
/// <param name="y"><i>y</i> component of the cartesian coordinate.</param>
/// <param name="z"><i>z</i> component of the cartesian coordinate.</param>
/// <returns><i>V</i>, the spherical harmonic sum.</returns>
/// <remarks>
/// This routine requires constant memory and thus never throws an exception.
/// </remarks>
public double Evaluate(double x, double y, double z)
{
Span <double> f = stackalloc double[] { 1 };
return(SphericalEngine.Value(false, _norm, _c.Span, f, x, y, z, _a, out _, out _, out _));
}