cilmminus.3

.\" Automatically generated by Pandoc 3.1.3
.\"
.\" Define V font for inline verbatim, using C font in formats
.\" that render this, and otherwise B font.
.ie "\f[CB]x\f[]"x" \{\
. ftr V B
. ftr VI BI
. ftr VB B
. ftr VBI BI
.\}
.el \{\
. ftr V CR
. ftr VI CI
. ftr VB CB
. ftr VBI CBI
.\}
.TH "cilmminus" "1" "2021-02-15" "Fortran 95" "SHTOOLS 4.11"
.hy
.SH CilmMinus
.PP
Calculate the gravitational potential interior to relief referenced to a
spherical interface using the finite-amplitude algorithm of Wieczorek
and Phillips (1998).
.SH Usage
.PP
call CilmMinus (\f[V]cilm\f[R], \f[V]gridin\f[R], \f[V]lmax\f[R],
\f[V]nmax\f[R], \f[V]mass\f[R], \f[V]d\f[R], \f[V]rho\f[R],
\f[V]gridtype\f[R], \f[V]w\f[R], \f[V]zero\f[R], \f[V]plx\f[R],
\f[V]n\f[R], \f[V]dref\f[R], \f[V]exitstatus\f[R])
.SH Parameters
.TP
\f[V]cilm\f[R] : output, real(dp), dimension (2, \f[V]lmax\f[R]+1, \f[V]lmax\f[R]+1)
The real spherical harmonic coefficients (geodesy normalized) of the
gravitational potential corresponding to constant density relief
referenced to a spherical interface of radius \f[V]d\f[R].
.TP
\f[V]gridin\f[R] : input, real(dp), dimension (\f[V]lmax\f[R]+1, 2*\f[V]lmax\f[R]+1) for gridtype 1, (\f[V]n\f[R], \f[V]n\f[R]) for gridtype 2, (\f[V]n\f[R], 2*\f[V]n\f[R]) for gridtype 3
The radii of the interface evaluated on a grid corresponding to a
function of maximum spherical harmonic degree \f[V]lmax\f[R].
This is calculated by a call to either \f[V]MakeGridGLQ\f[R] or
\f[V]MakeGridDH\f[R].
.TP
\f[V]lmax\f[R] : input, integer(int32)
The maximum spherical harmonic degree of the output spherical harmonic
coefficients.
This degree also determines the dimension of the input relief
\f[V]gridin\f[R] for \f[V]gridtype\f[R] 1.
For Driscoll-Healy grids, \f[V]lmax\f[R] must be less than or equal to
\f[V]n/2-1\f[R].
.TP
\f[V]nmax\f[R] : input, integer(int32)
The maximum order used in the Taylor-series expansion used in
calculating the potential coefficients.
.TP
\f[V]mass\f[R] : input, real(dp)
The mass of the planet in kg.
.TP
\f[V]d\f[R] : output, real(dp)
The mean radius of the relief in meters.
.TP
\f[V]rho\f[R] : input, real(dp)
The density contrast of the relief in kg/m\[ha]3.
.TP
\f[V]gridtype\f[R] : input, integer(int32)
1 = Gauss-Legendre grids, calculated using \f[V]SHGLQ\f[R] and
\f[V]MakeGridGLQ>\f[R].
2 = Equally sampled Driscoll-Healy grids, \f[V]n\f[R] by \f[V]n\f[R],
calculated using \f[V]MakeGridDH\f[R].
3 = Equally spaced Driscoll-Healy grids, \f[V]n\f[R] by 2\f[V]n\f[R],
calculated using \f[V]MakeGridDH\f[R].
.TP
\f[V]w\f[R] : optional, input, real(dp), dimension (\f[V]lmax\f[R]+1)
The weights used in the Gauss-Legendre quadrature, which are required
for \f[V]gridtype\f[R] = 1.
These are calculated from a call to \f[V]SHGLQ\f[R].
.TP
\f[V]zero\f[R] : optional, input, real(dp), dimension (\f[V]lmax\f[R]+1)
The nodes used in the Gauss-Legendre quadrature over latitude for
\f[V]gridtype\f[R] 1, calculated by a call to \f[V]SHGLQ\f[R].
One of \f[V]plx\f[R] or \f[V]zero\f[R] must be present when
\f[V]gridtype=1\f[R], but not both.
.TP
\f[V]plx\f[R] : optional, input, real(dp), dimension (\f[V]lmax\f[R]+1, (\f[V]lmax\f[R]+1)*(\f[V]lmax\f[R]+2)/2)
An array of the associated Legendre functions calculated at the nodes
used in the Gauss-Legendre quadrature for \f[V]gridtype\f[R] 1.
These are determined from a call to \f[V]SHGLQ\f[R].
One of \f[V]plx\f[R] or \f[V]zero\f[R] must be present when
\f[V]gridtype=1\f[R], but not both.
.TP
\f[V]n\f[R] : optional, input, integer(int32)
The number of samples in latitude when using Driscoll-Healy grids.
For a function bandlimited to \f[V]lmax\f[R], \f[V]n=2(lmax+1)\f[R].
This is required for gridtypes 2 and 3.
.TP
\f[V]dref\f[R] : optional, input, real(dp)
The reference radius to be used when calculating both the relief and
spherical harmonic coefficients.
If this is not specified, this parameter will be set equal to the mean
radius of \f[V]gridin\f[R].
.TP
\f[V]exitstatus\f[R] : output, optional, integer(int32)
If present, instead of executing a STOP when an error is encountered,
the variable exitstatus will be returned describing the error.
0 = No errors; 1 = Improper dimensions of input array; 2 = Improper
bounds for input variable; 3 = Error allocating memory; 4 = File IO
error.
.SH Description
.PP
\f[V]CilmMinus\f[R] will calculate the spherical harmonic coefficients
of the gravitational potential that correspond to constant density
relief referenced to a spherical interface.
This is equation 12 of Wieczorek and Phillips (1998), where the
potential is strictly valid only when the coefficients are evaluated at
a radius greater than the maximum radius of the relief.
The relief is input as a grid, whose type is specified by
\f[V]gridtype\f[R] (1 for Gauss-Legendre quadrature grids, 2 for
\f[V]n\f[R] by \f[V]n\f[R] Driscoll and Healy sampled grids, and 3 for
\f[V]n\f[R] by 2\f[V]n\f[R] Driscoll and Healy sampled grids).
The input relief \f[V]gridin\f[R] must correspond to absolute radii.
The parameter \f[V]nmax\f[R] is the order of the Taylor series used in
the algorithm to approximate the potential coefficients.
By default, the relief and spherical harmonic coefficients will be
referenced to the mean radius of \f[V]gridin\f[R].
However, if the optional parameter \f[V]dref\f[R] is specified, this
will be used instead as the reference radius.
.PP
It is important to understand that as an intermediate step, this routine
calculates the spherical harmonic coefficients of the relief (referenced
to the mean radius of \f[V]gridin\f[R] or \f[V]dref\f[R]) raised to the
nth power, i.e., \f[V](gridin-d)\[rs]*\[rs]*n\f[R].
As such, if the input function is bandlimited to degree \f[V]L\f[R], the
resulting function will be bandlimited to degree \f[V]L*nmax\f[R].
This subroutine implicitly assumes that the \f[V]gridin\f[R] has an
effective spherical harmonic bandwidth greater or equal to this value.
(The effective bandwidth is equal to \f[V]lmax\f[R] for
\f[V]gridtype\f[R] 1, and is \f[V]n/2-1\f[R] for \f[V]gridtype\f[R] 2 or
3.)
If this is not the case, aliasing will occur.
In practice, for accurate results, it is found that the effective
bandwidth needs only to be about three times the size of \f[V]L\f[R],
though this should be verified for each application.
Thus, if the input function is considered to be bandlimited to degree
\f[V]L\f[R], the function should be evaluated on a grid corresponding to
a maximum degree of about \f[V]3*\f[R]L.
Aliasing effects can be partially mitigated by using Driscoll and Healy
\f[V]n\f[R] by 2\f[V]n\f[R] grids.
.PP
If the input grid is evaluated on the Gauss-Legendre points, it is
necessary to specify the optional parameters \f[V]w\f[R] and
\f[V]zero\f[R], or \f[V]w\f[R] and \f[V]plx\f[R], which are calculated
by a call to \f[V]SHGLQ\f[R].
In contast, if Driscoll-Healy grids are used, it is necessary to specify
the optional parameter \f[V]n\f[R].
If memory is not an issue, the algorithm can be speeded up when using
Gauss-Lengendre grids by inputing the optional array \f[V]plx\f[R]
(along with \f[V]w\f[R]) of precomputed associated Legendre functions on
the Gauss-Legendre nodes.
Both of these variables are computed by a call to \f[V]SHGLQ\f[R].
.PP
This routine uses geodesy 4-pi normalized spherical harmonics that
exclude the Condon-Shortley phase.
.SH References
.PP
Wieczorek, M.
A.
and R.
J.
Phillips, Potential anomalies on a sphere: applications to the thickness
of the lunar crust, J.
Geophys.
Res., 103, 1715-1724, 1998.
.SH See also
.PP
cilmminusrhoh, cilmplus, cilmplusrhoh, shexpandglq, makegridglq, shglq,
glqgridcoord, makegriddh