Procedure

     DACOSN (arc cosine of bracketed argument)

     DOUBLE PRECISION FUNCTION DACOSN ( ARG, TOL )

Abstract

     Compute arc cosine of a bracketed argument.

     This routine produces a SPICE error if the |argument| exceeds
     1.D0 by more than TOL. If ARG exceeds 1.D0, the argument is
     evaluated as if it equaled 1.D0, if ARG is less than -1.,
     the argument is evaluated as if it equaled -1.D0.

Required_Reading

     None.

Keywords

     INTERVALS
     INVERSE TRIGONOMETRIC FUNCTION
     NUMBERS
     UTILITY

Declarations

     IMPLICIT NONE

     DOUBLE PRECISION   ARG
     DOUBLE PRECISION   TOL

Brief_I/O

     VARIABLE  I/O  DESCRIPTION
     --------  ---  --------------------------------------------------
     ARG        I   Argument to be evaluated.
     TOL        I   Tolerance.

     The function returns the arc cosine of ARG.

Detailed_Input

     ARG      is the arc cosine argument that is to be evaluated such
              that if it is less than -1.D0 by more than TOL or greater
              than 1.D0 by more than TOL, an error results.

     TOL      is a tolerance such that |ARG| is considered to be equal
              to 1.D0 if |ARG| <= 1.D0 + TOL. TOL must be non-negative.

Detailed_Output

     The function returns the arc cosine of ARG. If

        |ARG| >= 1.D0,

     it returns DACOS (1.D0) or DACOS (-1.D0) as appropriate. Values
     range from 0 to PI.

Parameters

     None.

Exceptions

     1)  If |ARG| > 1.D0 + TOL, the error SPICE(INPUTOUTOFBOUNDS) is
         signaled.

     2)  If TOL is less than zero, the error SPICE(VALUEOUTOFRANGE) is
         signaled.

Files

     None.

Particulars

     This routine determines whether |ARG| > 1.D0 + TOL. If it is, an
     error will be flagged. In addition, the values of ARG are
     constrained to [-1.D0, 1.D0].

Examples

     The following illustrate the operation of DACOSN.

           DACOSN (  -1.D0,        1.D-7 )  =   PI
           DACOSN (  -1.00001D0,   1.D-3 )  =   PI
           DACOSN (  -1.00001D0,   1.D-7 )  =   PI   (error flagged)
           DACOSN (   0.D0,        1.D-7 )  =   PI/2
           DACOSN (   1.00001D0,   1.D-3 )  =   0.
           DACOSN (   1.00001D0,   1.D-7 )  =   0. (error flagged)

Restrictions

     None.

Literature_References

     None.

Author_and_Institution

     J. Diaz del Rio    (ODC Space)
     L.S. Elson         (JPL)

Version

    SPICELIB Version 1.1.0, 26-OCT-2021 (JDR)

        Added IMPLICIT NONE statement.

        Edited the header to comply with NAIF standard.

    SPICELIB Version 1.0.0, 28-FEB-2006 (LSE)