1 /*
2 
3 -Procedure  vnorm_c ( Vector norm, 3 dimensions )
4 
5 -Abstract
6 
7    Compute the magnitude of a double precision, 3-dimensional vector.
8 
9 -Disclaimer
10 
11    THIS SOFTWARE AND ANY RELATED MATERIALS WERE CREATED BY THE
12    CALIFORNIA INSTITUTE OF TECHNOLOGY (CALTECH) UNDER A U.S.
13    GOVERNMENT CONTRACT WITH THE NATIONAL AERONAUTICS AND SPACE
14    ADMINISTRATION (NASA). THE SOFTWARE IS TECHNOLOGY AND SOFTWARE
15    PUBLICLY AVAILABLE UNDER U.S. EXPORT LAWS AND IS PROVIDED "AS-IS"
16    TO THE RECIPIENT WITHOUT WARRANTY OF ANY KIND, INCLUDING ANY
17    WARRANTIES OF PERFORMANCE OR MERCHANTABILITY OR FITNESS FOR A
18    PARTICULAR USE OR PURPOSE (AS SET FORTH IN UNITED STATES UCC
19    SECTIONS 2312-2313) OR FOR ANY PURPOSE WHATSOEVER, FOR THE
20    SOFTWARE AND RELATED MATERIALS, HOWEVER USED.
21 
22    IN NO EVENT SHALL CALTECH, ITS JET PROPULSION LABORATORY, OR NASA
23    BE LIABLE FOR ANY DAMAGES AND/OR COSTS, INCLUDING, BUT NOT
24    LIMITED TO, INCIDENTAL OR CONSEQUENTIAL DAMAGES OF ANY KIND,
25    INCLUDING ECONOMIC DAMAGE OR INJURY TO PROPERTY AND LOST PROFITS,
26    REGARDLESS OF WHETHER CALTECH, JPL, OR NASA BE ADVISED, HAVE
27    REASON TO KNOW, OR, IN FACT, SHALL KNOW OF THE POSSIBILITY.
28 
29    RECIPIENT BEARS ALL RISK RELATING TO QUALITY AND PERFORMANCE OF
30    THE SOFTWARE AND ANY RELATED MATERIALS, AND AGREES TO INDEMNIFY
31    CALTECH AND NASA FOR ALL THIRD-PARTY CLAIMS RESULTING FROM THE
32    ACTIONS OF RECIPIENT IN THE USE OF THE SOFTWARE.
33 
34 -Required_Reading
35 
36    None.
37 
38 -Keywords
39 
40    VECTOR
41 
42 */
43    #include <math.h>
44    #include "SpiceUsr.h"
45    #include "SpiceZmc.h"
46    #undef    vnorm_c
47 
48 
vnorm_c(ConstSpiceDouble v1[3])49    SpiceDouble vnorm_c ( ConstSpiceDouble v1[3] )
50 
51 /*
52 
53 -Brief_I/O
54 
55    VARIABLE  I/O  DESCRIPTION
56    --------  ---  --------------------------------------------------
57    v1         I   Vector whose magnitude is to be found.
58 
59    The function returns the norm of v1.
60 
61 -Detailed_Input
62 
63    v1             may be any 3-dimensional, double precision vector.
64 
65 -Detailed_Output
66 
67    The function returns the magnitude of v1 calculated in a numerically
68    stable way.
69 
70 -Parameters
71 
72    None.
73 
74 -Exceptions
75 
76    Error free.
77 
78 -Files
79 
80    None.
81 
82 -Particulars
83 
84    vnorm_c takes care to avoid overflow while computing the norm of the
85    input vector v1.  vnorm_c finds the component of v1 whose magnitude
86    is the largest.  Calling this magnitude v1max, the norm is computed
87    using the formula
88 
89        vnorm_c  =  v1max *  ||  (1/v1max) * v1  ||
90 
91    where the notation ||x|| indicates the norm of the vector x.
92 
93 -Examples
94 
95    The following table show the correlation between various input
96    vectors v1 and vnorm_c:
97 
98    v1                                    vnorm_c
99    -----------------------------------------------------------------
100    ( 1.e0,    2.e0,   2.e0    )          3.e0
101    ( 5.e0,    12.e0,  0.e0    )          13.e0
102    ( -5.e-17, 0.0e0,  12.e-17 )          13.e-17
103 
104 -Restrictions
105 
106    None.
107 
108 -Literature_References
109 
110    None.
111 
112 -Author_and_Institution
113 
114    N.J. Bachman       (JPL)
115    W.L. Taber         (JPL)
116    W.M. Owen          (JPL)
117 
118 -Version
119 
120    -CSPICE Version 1.0.2, 16-JAN-2008   (EDW)
121 
122       Corrected typos in header titles:
123 
124       Detailed Input to Detailed_Input
125       Detailed Output to Detailed_Output
126 
127    -CSPICE Version 1.0.1, 12-NOV-2006 (EDW)
128 
129       Added Parameters section header.
130 
131    -CSPICE Version 1.0.0, 16-APR-1999 (NJB)
132 
133 -Index_Entries
134 
135    norm of 3-dimensional vector
136 
137 -&
138 */
139 
140 {  /* Begin vnorm_c */
141 
142    /*
143    Local variables
144    */
145    SpiceDouble                        normSqr;
146    SpiceDouble                        tmp0;
147    SpiceDouble                        tmp1;
148    SpiceDouble                        tmp2;
149    SpiceDouble                        v1max;
150 
151 
152    /*
153    Determine the maximum component of the vector.
154    */
155    v1max = MaxAbs(  v1[0],   MaxAbs( v1[1], v1[2] )   );
156 
157 
158    /*
159    If the vector is zero, return zero; otherwise normalize first.
160    Normalizing helps in the cases where squaring would cause overflow
161    or underflow.  In the cases where such is not a problem it not worth
162    it to optimize further.
163    */
164 
165    if ( v1max == 0.0 )
166    {
167       return ( 0.0 );
168    }
169    else
170    {
171       tmp0     =  v1[0]/v1max;
172       tmp1     =  v1[1]/v1max;
173       tmp2     =  v1[2]/v1max;
174 
175       normSqr  =  tmp0*tmp0 + tmp1*tmp1 + tmp2*tmp2;
176 
177       return (  v1max * sqrt( normSqr )  );
178    }
179 
180 
181 } /* End vnorm_c */
182