Sun position
Sun position algorithm
skyfast.h
Go to the documentation of this file.
1 #ifndef SKYFAST_H
2 #define SKYFAST_H
3 /*============================================================================*/
4 /*! \file
5  * \brief
6  * skyfast.h - set up and use interpolation for rapid calculation of a celestial
7  * object's apparent coordinates.
8  *
9  * \author David Hoadley
10  *
11  * \details
12  * Routines to set up interpolation for celestial tracking, get the
13  * interpolated position at a given time, and to update the endpoints
14  * used by the interpolation algorithm. The error introduced by using
15  * interpolation rather than fully calculating each and every position
16  * can be very small - see \ref page-interpolation (the end of this
17  * source file)
18  *
19  *==============================================================================
20  */
21 /*
22  * Copyright (c) 2020, David Hoadley <vcrumble@westnet.com.au>
23  * All rights reserved.
24  *
25  * Redistribution and use in source and binary forms, with or without
26  * modification, are permitted provided that the following conditions are met:
27  *
28  * * Redistributions of source code must retain the above copyright notice, this
29  * list of conditions and the following disclaimer.
30  * * Redistributions in binary form must reproduce the above copyright notice,
31  * this list of conditions and the following disclaimer in the documentation
32  * and/or other materials provided with the distribution.
33  *
34  * THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
35  * AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
36  * IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
37  * ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE
38  * LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR
39  * CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF
40  * SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS
41  * INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN
42  * CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE)
43  * ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE
44  * POSSIBILITY OF SUCH DAMAGE.
45  */
46 #include "sky.h"
47 
48 /*
49  * Global #defines and typedefs
50  */
51 
52 
53 #ifdef __cplusplus
54 extern "C" {
55 #endif
56 /*
57  * Global functions available to be called by other modules
58  */
59 void skyfast_init(double tStartUtc_d,
60  int fullRecalcInterval_mins,
61  const Sky_DeltaTs *deltas,
62  void (*getApparent)(double j2kTT_cy, Sky_TrueEquatorial *pos)
63  );
64 void skyfast_backgroundUpdate(void);
65 void skyfast_getApprox(double t_cy, Sky_TrueEquatorial *approx);
66 
67 /*
68  * Global variables accessible by other modules
69  */
70 
71 #ifdef __cplusplus
72 }
73 #endif
74 
75 /*! \page page-interpolation Interpolation and its errors
76  * The interpolation process obtains an estimate of the apparent position (or
77  * alternatively, the celestial intermediate position) of a celestial object
78  * by interpolating between previously calculated position vectors. The amount
79  * of error introduced by this process depends of course on how much the
80  * position changed between the two previously calculated times. Here is a
81  * table of the errors when this process is used to obtain the position of the
82  * Sun, Moon, planets and a star. The errors are calculated from
83  * sqrt((azimuth_error * cos(elevation))^2 + elevation_error^2)
84  *
85  * The interpolation interval (in hours) is the time between the two previously
86  * fully calculated vectors. This value (multiplied by 60) is supplied to
87  * parameter \a fullRecalcInterval_mins of function skyfast_init().
88  *
89  * ###Maximum absolute position error (arcseconds) for different interpolation intervals (hours)
90 
91  hours |1 |2 |3 |6 |9 |12 |15 |18 |24 |
92  :-------|------:|------:|------:|------:|------:|------:|------:|------:|-----:|
93  Sun |0.0005 |0.0020 |0.0046 |0.0184 |0.0413 |0.0736 |0.1151 |0.1658 |0.2957|
94  - | | | | | | | | | |
95  Moon |0.3381 |1.3536 |3.0455 |12.07 |27.62 |49.55 |77.74 |112.1 |185.4 |
96  - | | | | | | | | | |
97  Mercury |0.1533 |0.6132 |1.3797 |5.5177 |12.42 |22.07 |34.44 |49.64 |88.17 |
98  Venus |0.0324 |0.1295 |0.2914 |1.1656 |3.2375 |4.6621 |7.2847 |10.49 |18.64 |
99  Mars |0.0115 |0.0459 |0.1032 |0.4127 |0.9287 |1.6510 |2.5796 |3.7146 |6.6035|
100  Jupiter |0.0025 |0.0101 |0.0227 |0.0907 |0.2040 |0.3627 |0.5667 |0.8161 |1.4508|
101  Saturn |0.0013 |0.0052 |0.0117 |0.0468 |0.1054 |0.1874 |0.2927 |0.4216 |0.7494|
102  Uranus |0.0007 |0.0027 |0.0062 |0.0247 |0.0556 |0.0988 |0.1544 |0.2223 |0.3951|
103  Neptune |0.0005 |0.0018 |0.0041 |0.0163 |0.0366 |0.0651 |0.1017 |0.1465 |0.2604|
104  - | | | | | | | | | |
105  Antares |<0.0001|<0.0001|<0.0001|0.0001 |0.0003 |0.0005 |0.0007 |0.0010 |0.0019|
106 
107  * As can be seen, the errors are very small for the Sun even with 24 hours
108  * between full calculations (i.e. a value of 1440 minutes supplied to
109  * parameter \a fullRecalcInterval_mins of function skyfast_init()).
110  * Actually a full twenty-four hours of tracking of the Sun can be obtained by
111  * supplying 720 minutes to this parameter, without ever having to call the
112  * function skyfast_backgroundUpdate(). This is because skyfast_init()
113  * calculates three apparent positions, not just two.
114  *
115  * Errors for the Moon are larger. The position algorithm itself is accurate
116  * to about 5 arcseconds, it seems, so this suggests that an interpolation
117  * interval of no more than about 2 hours should be used for the Moon.
118  *
119  * The maximum errors tracking planets are larger than for the Sun. These
120  * maximum errors seem to occur around the time the planet enters or leaves
121  * apparent retrograde motion.
122  *
123  * The errors when tracking a star are almost negligible.
124  *
125  * In all cases, the error appears to approximately quadruple for every
126  * doubling of the interpolation interval.
127  */
128 
129 #endif /* SKYFAST_H */
Sky_DeltaTs
This structure contains relatively constant data, and is set up by one of the three functions sky_ini...
Definition: sky.h:166
Sky_TrueEquatorial
Struct used for holding an object's coordinates in equatorial apparent or Intermediate coordinates.
Definition: sky.h:106
skyfast_getApprox
void skyfast_getApprox(double t_cy, Sky_TrueEquatorial *approx)
Get the best approximation to the celestial object's apparent coordinates and distance,...
Definition: skyfast.c:234
skyfast_backgroundUpdate
void skyfast_backgroundUpdate(void)
Recalculation of the low frequency quantities.
Definition: skyfast.c:199
skyfast_init
void skyfast_init(double tStartUtc_d, int fullRecalcInterval_mins, const Sky_DeltaTs *deltas, void(*getApparent)(double j2kTT_cy, Sky_TrueEquatorial *pos))
Initialise those items that take a long time to calculate, but which do not need to be recalculated f...
Definition: skyfast.c:111
sky.h
sky.h - structures and routines for astronomical observing & tracking