forked from soniakeys/meeus
-
Notifications
You must be signed in to change notification settings - Fork 0
/
doc.go
191 lines (190 loc) · 10.4 KB
/
doc.go
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
// Copyright 2013 Sonia Keys
// License MIT: http://www.opensource.org/licenses/MIT
// Meeus implements algorithms from the book "Astronomical Algorithms"
// by Jean Meeus.
//
// It follows the second edition, copyright 1998, with corrections as of
// August 10, 2009.
//
// It requires Go 1.1 or later.
//
// Library Goals
//
// Jean Meeus's book has long been respected as a broad-reaching source of
// astronomical algorithms, and many code libraries have been based on it.
// This library will be distinct in several respects, I hope.
//
// First of all it is in the Go language, a programming language new enough
// that it well postdates the book itself. Go has many advantages for a
// large and diverse library such as this and it is a fine language for
// for scientific computations. I hope that a Go implementation will prove
// relevant for some time in the future.
//
// Next, this library attempts fairly comprehensive coverage of the book.
// Each chapter of the book is addressed, and in the very few cases where
// there seems no code from the chapter that is applicable in Go, similar
// and more appropriate techniques are at least discussed in documentation.
// If meaningful, examples are given as well.
//
// While this library attempts fairly comprehensive coverage of the book,
// it does not attempt to present a complete, well rounded, and polished
// astronomy library. Such a production-quality astronomy library would
// likely include some updated routines and data, routines and data from
// other sources, and would fill in various holes of functionality which
// Meeus elects to gloss over. Such a library could certainly be derived
// from this one, but it is beyond the scope of what is attempted here.
//
// Thus, this library should represent a solid foundation for the development
// of a broad range of astronomy software. Much software should be able to
// use this library directly. Some software will need routines from additional
// sources. When the API of this library begins to present friction with that
// of other code, it may be time to fork or otherwise derive a new library
// from this one. Please feel free to do this, respecting of course the MIT
// license under which this software is offered.
//
// Package Contents
//
// By Go convention, each package is in its own subdirectory. The
// "subdirectories" list of this documentation page lists all packages of
// of the library. Each package also corresponds to exacly one chapter of
// the book. The package documentation heading references the chapter number
// and a cross reference is given below of chapter numbers and package names.
//
// Within a chapter of the book, Meeus presents explanatory text, numbered
// formulas, numbered examples, and other exercises. Within a package of this
// library, there are library functions and other codified definitions; there
// are Go examples which appear in documentation and which are also evaluated
// and verified to produce correct output by the go test feature; and there is
// test code which is neither part of the API nor the documentation but which
// verified by the go test feature.
//
// The "API", or choice of functions to implement in Go, covers many of
// Meeus's numbered formulas and covers the algorithms needed to work most
// of the numbered examples. The correspondence is not one-to-one, but often
// "refactored" into functions that seem more idiomatic to Go. This is set
// as the limit of the API however, and thus the limit of the functionality
// offered by this library.
//
// Each numbered example in the book is also translated to a Go example
// function. This typically shows how to use the implemented API to compute
// the results of the example. As the go test feature validates these
// results, the examples also serve as baseline tests of the correctness
// of the API code. Relevant "exercises" from the book are also often
// implemented as Go examples.
//
// A few packages remain incomplete. A package is considered complete if
// it implements all major formulas and algorithms and if it implements all
// numbered examples. For incomplete packages, the package documentation
// will describe the ways in which it is incomplete and typically give reasons
// for the incompleteness.
//
// In addition to the chapter packages, there is a package called "base".
// This contains a few definitions that are provided by Meeus but are of such
// general use that they really don't belong with any one chapter. The much
// greater bulk of base however, are functions which Meeus does not explicitly
// provide, but again are of general use. The nature of these functions is
// as helper subroutines or IO subroutines. The functions do not offer
// additional astronomy algorithms beyond those provided by Meeus.
//
// Identifiers
//
// To more closely follow the book's use of Greek letters and other symbols,
// Unicode is freely used in the source code. Recognizing that these symbols
// are awkard to enter in many environments however, they are avoided for
// exported symbols that comprise the library API. The function Coord.EclToEq
// for example, returns (α, δ float64) but of course you can assign these
// return values to whatever variables you like. The struct Coord.Equatorial
// on the other hand, has exported fields RA and Dec. ASCII is used in this
// case to simplify using these symbols in your code.
//
// Some identifiers use the prime symbol (ʹ). That's Unicode U+02B9,
// not the ASCII '. Go uses ASCII ' for raw strings and does not allow it
// in identifiers. U+02B9 on the other hand is Unicode category Lm,
// and is perfectly valid in Go identifiers.
//
// Unit types
//
// An earler version of this library used the Go type float64 for most
// parameters and return values. This allowed terse, efficient code but
// required careful attention to the scaling or units used. Go defined types
// are now used for Time, RA, HourAngle, and general Angle quantities in the
// interest of making units and coversions more clear. These types are
// defined in the external package github.com/soniakeys/unit.
//
// Sexagesimal formatting
//
// An earlier version of this library included routines for formatting
// sexagesimal quantities. These have been moved to the external package
// github.com/soniakeys/sexagesimal and use of this package is now restricted
// to examples and tests.
//
// Meeus packages and the sexagesimal package both depend on the unit package.
// Meeus packages do not depend on sexagesimal, although the Meeus tests do.
//
// Chapter Cross-reference
//
// .
//
// Chapter Package
//
// 1. Hints and Tips hints
// 2. About Accuracy accuracy
// 3. Interpolation interp
// 4. Curve Fitting fit
// 5. Iteration iterate
// 6. Sorting Numbers sort
// 7. Julian Day julian
// 8. Date of Easter easter
// 9. Jewish and Moslem Calendars jm
// 10. Dynamical Time and Universal Time deltat
// 11. The Earth's Globe globe
// 12. Sidereal Time at Greenwich sidereal
// 13. Transformation of Coordinates coord
// 14. The Parallactic Angle, and three other Topics parallactic
// 15. Rising, Transit, and Setting rise
// 16. Atmospheric Refraction refraction
// 17. Angular Separation angle
// 18. Planetary Conjunctions conjunction
// 19. Bodies in Straight Line line
// 20. Smallest Circle containing three Celestial Bodies circle
// 21. Precession precess
// 22. Nutation and the Obliquity of the Ecliptic nutation
// 23. Apparent Place of a Star apparent
// 24. Reduction of Ecliptical Elements from one Equinox elementequinox
// to another one
// 25. Solar Coordinates solar
// 26. Rectangular Coordinates of the Sun solarxyz
// 27. Equinoxes and Solstices solstice
// 28. Equation of Time eqtime
// 29. Ephemeris for Physical Observations of the Sun solardisk
// 30. Equation of Kepler kepler
// 31. Elements of Planetary Orbits planetelements
// 32. Positions of the Planets planetposition
// 33. Elliptic Motion elliptic
// 34. Parabolic Motion parabolic
// 35. Near-parabolic Motion nearparabolic
// 36. The Calculation of some Planetary Phenomena planetary
// 37. Pluto pluto
// 38. Planets in Perihelion and in Aphelion perihelion
// 39. Passages through the Nodes node
// 40. Correction for Parallax parallax
// 41. Illuminated Fraction of the Disk and Magnitude illum
// of a Planet
// 42. Ephemeris for Physical Observations of Mars mars
// 43. Ephemeris for Physical Observations of Jupiter jupiter
// 44. Positions of the Satellites of Jupiter jupitermoons
// 45. The Ring of Saturn saturnring
// 46. Positions of the Satellites of Saturn saturnmoons
// 47. Position of the Moon moonposition
// 48. Illuminated Fraction of the Moon's Disk moonillum
// 49. Phases of the Moon moonphase
// 50. Perigee and apogee of the Moon apsis
// 51. Passages of the Moon through the Nodes moonnode
// 52. Maximum declinations of the Moon moonmaxdec
// 53. Ephemeris for Physical Observations of the Moon moon
// 54. Eclipses eclipse
// 55. Semidiameters of the Sun, Moon, and Planets semidiameter
// 56. Stellar Magnitudes stellar
// 57. Binary Stars binary
// 58. Calculation of a Planar Sundial sundial
package meeus