1 /* 2 3 -Procedure gfstol_c ( GF, set a tolerance value for GF ) 4 5 -Abstract 6 7 Override the default GF convergence value used in the high 8 level GF routines. 9 10 -Disclaimer 11 12 THIS SOFTWARE AND ANY RELATED MATERIALS WERE CREATED BY THE 13 CALIFORNIA INSTITUTE OF TECHNOLOGY (CALTECH) UNDER A U.S. 14 GOVERNMENT CONTRACT WITH THE NATIONAL AERONAUTICS AND SPACE 15 ADMINISTRATION (NASA). THE SOFTWARE IS TECHNOLOGY AND SOFTWARE 16 PUBLICLY AVAILABLE UNDER U.S. EXPORT LAWS AND IS PROVIDED "AS-IS" 17 TO THE RECIPIENT WITHOUT WARRANTY OF ANY KIND, INCLUDING ANY 18 WARRANTIES OF PERFORMANCE OR MERCHANTABILITY OR FITNESS FOR A 19 PARTICULAR USE OR PURPOSE (AS set_c FORTH IN UNITED STATES UCC 20 SECTIONS 2312-2313) OR FOR ANY PURPOSE WHATSOEVER, FOR THE 21 SOFTWARE AND RELATED MATERIALS, HOWEVER USED. 22 23 IN NO EVENT SHALL CALTECH, ITS JET PROPULSION LABORATORY, OR NASA 24 BE LIABLE FOR ANY DAMAGES AND/OR COSTS, INCLUDING, BUT NOT 25 LIMITED TO, INCIDENTAL OR CONSEQUENTIAL DAMAGES OF ANY KIND, 26 INCLUDING ECONOMIC DAMAGE OR INJURY TO PROPERTY AND LOST PROFITS, 27 REGARDLESS OF WHETHER CALTECH, JPL, OR NASA BE ADVISED, HAVE 28 REASON TO KNOW, OR, IN FACT, SHALL KNOW OF THE POSSIBILITY. 29 30 RECIPIENT BEARS ALL RISK RELATING TO QUALITY AND PERFORMANCE OF 31 THE SOFTWARE AND ANY RELATED MATERIALS, AND AGREES TO INDEMNIFY 32 CALTECH AND NASA FOR ALL THIRD-PARTY CLAIMS RESULTING FROM THE 33 ACTIONS OF RECIPIENT IN THE USE OF THE SOFTWARE. 34 35 -Required_Reading 36 37 GF 38 39 -Keywords 40 41 GEOMETRY 42 43 */ 44 45 #include "SpiceUsr.h" 46 #include "SpiceZfc.h" 47 gfstol_c(SpiceDouble value)48 void gfstol_c ( SpiceDouble value ) 49 50 /* 51 52 -Brief_I/O 53 54 Variable I/O Description 55 -------- --- -------------------------------------------------- 56 value I Double precision value returned or to store. 57 58 -Detailed_Input 59 60 value The scalar double precision value to use as the GF subsystem 61 convergence tolerance. This value will override the default 62 tolerance, SPICE_GF_CNVTOL, defined in SpiceGF.h Units are 63 TDB seconds. 64 65 -Detailed_Output 66 67 None. 68 69 -Parameters 70 71 None. 72 73 -Exceptions 74 75 1) The error SPICE(INVALIDTOL) signals if 'value' is not strictly 76 greater-than-zero. 77 78 -Files 79 80 None. 81 82 -Particulars 83 84 The high level GF routines (see GF.REQ for a listing) use a 85 default value for the convergence tolerance, SPICE_GF_CNVTOL, 86 defined in SpiceGF.h. It may occur that a GF search run needs a 87 different convergence tolerance. gfstol_c programmatically changes 88 the tolerance used by those routines. 89 90 -Examples 91 92 The numerical results shown for these examples may differ across 93 platforms. The results depend on the SPICE kernels used as 94 input, the compiler and supporting libraries, and the machine 95 specific arithmetic implementation. 96 97 Use the meta-kernel shown below to load the required SPICE 98 kernels. 99 100 KPL/MK 101 102 File name: standard.tm 103 104 This meta-kernel is intended to support operation of SPICE 105 example programs. The kernels shown here should not be 106 assumed to contain adequate or correct versions of data 107 required by SPICE-based user applications. 108 109 In order for an application to use this meta-kernel, the 110 kernels referenced here must be present in the user's 111 current working directory. 112 113 The names and contents of the kernels referenced 114 by this meta-kernel are as follows: 115 116 File name Contents 117 --------- -------- 118 de421.bsp Planetary ephemeris 119 pck00009.tpc Planet orientation and 120 radii 121 naif0009.tls Leapseconds 122 123 \begindata 124 125 KERNELS_TO_LOAD = ( 'de421.bsp', 126 'pck00009.tpc', 127 'naif0009.tls' ) 128 129 \begintext 130 131 Example: 132 133 Perform a search for occultation events of the sun by earth as 134 observed from the Moon center. Search during the interval from 135 14 A.D. SEP 1 to 14 A.D. SEP 30 (Julian). 136 137 #include <stdio.h> 138 #include "SpiceUsr.h" 139 140 int main() 141 { 142 /. 143 Local constants 144 ./ 145 146 #define TIMFMT "YYYY ERA MON DD HR:MN:SC.#### ::JCAL" 147 #define MAXWIN 200 148 #define TIMLEN 41 149 150 /. 151 Local variables 152 ./ 153 SPICEDOUBLE_CELL ( cnfine, MAXWIN ); 154 SPICEDOUBLE_CELL ( result, MAXWIN ); 155 156 SpiceChar * win0; 157 SpiceChar * win1; 158 SpiceChar begstr [ TIMLEN ]; 159 SpiceChar endstr [ TIMLEN ]; 160 161 SpiceDouble et0; 162 SpiceDouble et1; 163 SpiceDouble left; 164 SpiceDouble right; 165 SpiceDouble step; 166 167 SpiceInt i; 168 169 /. 170 Load kernels. 171 ./ 172 furnsh_c ( "standard.tm" ); 173 174 /. 175 Use an SPK covering year 14 AD. 176 ./ 177 furnsh_c ( "de408.bsp" ); 178 179 /. 180 Obtain the TDB time bounds of the confinement 181 window, which is a single interval in this case. 182 ./ 183 win0 = "14 A.D. SEP 1 00:00:00"; 184 win1 = "14 A.D. SEP 30 00:00:00"; 185 186 str2et_c ( win0, &et0 ); 187 str2et_c ( win1, &et1 ); 188 189 /. 190 Insert the time bounds into the confinement 191 window. 192 ./ 193 wninsd_c ( et0, et1, &cnfine ); 194 195 /. 196 Select a 3-minute step. We'll ignore any occultations 197 lasting less than 3 minutes. 198 ./ 199 step = 180.0; 200 201 /. 202 Perform the search. 'et[0]' and 'et[1]' have values ~-6*10^10, 203 SPICE_GF_CNVTOL has value 10^-6, so double precision addition or 204 subtraction of 'et[0]' and 'et[1]' with SPICE_GF_CNVTOL returns 205 a result indistinguishable from 'et[0]' and 'et[1]'. 206 207 Reduce the GF convergence tolerance by an order of magnitude 208 to resolve this condition. 209 ./ 210 gfstol_c( 1.e-5 ); 211 212 gfoclt_c ( "any", 213 "earth", "ellipsoid", "iau_earth", 214 "sun", "ellipsoid", "iau_sun", 215 "lt", "moon", step, 216 &cnfine, &result ); 217 218 if ( wncard_c(&result) == 0 ) 219 { 220 printf ( "No occultation was found.\n" ); 221 } 222 else 223 { 224 for ( i = 0; i < wncard_c(&result); i++ ) 225 { 226 /. 227 Fetch and display each occultation interval. 228 ./ 229 wnfetd_c ( &result, i, &left, &right ); 230 231 timout_c ( left, TIMFMT, TIMLEN, begstr ); 232 timout_c ( right, TIMFMT, TIMLEN, endstr ); 233 234 printf ( "Interval %d\n" 235 " Start time: %s\n" 236 " Stop time: %s\n", 237 (int)i, begstr, endstr ); 238 } 239 } 240 241 return ( 0 ); 242 } 243 244 245 The program outputs: 246 247 Interval 0 248 Start time: 14 A.D. SEP 27 05:02:02.8250 249 Stop time: 14 A.D. SEP 27 09:33:31.6995 250 251 -Restrictions 252 253 None. 254 255 -Literature_References 256 257 None. 258 259 -Author_and_Institution 260 261 E.D. Wright (JPL) 262 263 -Version 264 265 -CSPICE Version 1.0.1, 28-JUN-2016 (EDW) 266 267 Edit to header, correct Required Reading entry eliminating ".REQ" 268 suffix. 269 270 Edit to Example code, SpiceInts output as ints using 271 explicit casting. 272 273 -CSPICE Version 1.0.0, 27-SEP-2010 274 275 -Index_Entries 276 277 change default convergence tolerance for GF routines 278 279 -& 280 */ 281 282 { /* Begin gfstol_c */ 283 284 /* 285 Participate in error tracing. 286 */ 287 288 if ( return_c() ) 289 { 290 return; 291 } 292 293 chkin_c ( "gfstol_c" ); 294 295 /* 296 Let the f2c'd routine do the work. 297 */ 298 299 gfstol_ ( (doublereal * ) &value ); 300 301 chkout_c ( "gfstol_c" ); 302 303 } /* End gfstol_c */ 304