Programming interface to the Swiss Ephemeris

 

Copyright Astrodienst AG 1997-2003.

This document describes the proprietary programmer's interface to the Swiss Ephemeris DLL.

 

Swiss Ephemeris is made available by its authors under a dual licensing  system. The software developer, who uses any part of Swiss Ephemeris  in his or her software, must choose between one of the two license models,   which are

  a) GNU public license version 2 or later

  b) Swiss Ephemeris Professional License

 

The choice must be made before the software developer distributes software  containing parts of Swiss Ephemeris to others, and before any public service using the developed software is activated.

 

If the developer chooses the GNU GPL software license, he or she must fulfill the conditions of that license, which includes the obligation to place his or her whole software project under the GNU GPL or a compatible license. See http://www.gnu.org/licenses/old-licenses/gpl-2.0.html

 

If the developer chooses the Swiss Ephemeris Professional license, he must follow the instructions as found in http://www.astro.com/swisseph/ and purchase the Swiss Ephemeris Professional Edition from Astrodienst and sign the corresponding license contract.

 


1. The programming steps to get a planet’s position. 5

2. The functions swe_calc_ut() and swe_calc(). 7

2.1. The call parameters. 7

2.2. Error handling and return values. 7

2.3. Bodies ( int ipl ). 8

Additional asteroids. 8

Fictitious planets. 11

Obliquity and nutation. 13

2.4. Options chosen by flag bits (long  iflag). 13

2.4.1. The use of flag bits. 13

2.4.2. Ephemeris flags. 13

2.4.3. Speed flag. 14

2.4.4. Coordinate systems, degrees and radians. 14

2.4.5. Specialties (going beyond common interest). 14

a. True or apparent positions. 14

b. Topocentric positions. 14

c. Heliocentric positions. 14

d. Barycentric positions. 14

e. Astrometric positions. 15

f. True or mean equinox of date. 15

g. J2000 positions and positions referred to other equinoxes. 15

h. Sidereal positions. 15

2.5. Position and Speed (double xx[6]). 15

3. The function swe_get_planet_name(). 15

4. Fixed stars functions. 16

4.1 swe_fixstar_ut. 16

4.2 swe_fixstar(). 16

4.3 swe_fixstar_mag(). 17

5. Apsides functions. 17

5.1 swe_nod_aps_ut. 17

5.2 swe_nod_aps(). 17

6. Eclipse and planetary phenomena functions. 19

6.0. Example of a typical eclipse calculation. 19

6.1. swe_sol_eclipse_when_loc() and swe_lun_occult_when_loc(). 20

6.2. swe_sol_eclipse_when_glob(). 20

6.3. swe_sol_eclipse_how (). 21

6.4. swe_sol_eclipse_where (). 22

6.5. swe_lun_occult_when_loc(). 23

6.6. swe_lun_occult_when_glob(). 24

6.7. swe_lun_occult_where (). 25

6.8. swe_lun_eclipse_when (). 25

6.9. swe_lun_eclipse_how (). 26

6.10. swe_rise_trans(), risings, settings, meridian transits. 27

6.11. swe_pheno_ut() and swe_pheno(), planetary phenomena. 27

6.12. swe_azalt(), horizontal coordinates, azimuth, altitude. 28

6.13. swe_azalt_rev(). 28

6.14. swe_refrac(), swe_refract_extended(), refraction. 29

6.15. Heliacal risings etc.: swe_heliacal_ut(). 29

6.16. Magnitude limit for visibility: swe_vis_limit_mag(). 30

7. Date and time conversion functions. 31

7.1 Calendar Date ó Julian Day: swe_julday(), swe_date_conversion(), /swe_revjul(). 31

7.2. UTC ó Julian day: swe_utc_to_jd(), swe_jdet_to_utc(), swe_jdut1_to_utc(). 31

7.3. Future insertion of leap seconds and the file swe_leapsec.txt. 32

7.4. Mean solar time versus True solar time: swe_time_equ(). 33

8. Delta T-related functions. 33

8.1 swe_deltat(). 33

8.2 swe_set_tid_acc(), swe_get_tid_acc(). 33

8.3. Future updates of Delta T and the file swe_deltat.txt. 33

9. The function swe_set_topo() for topocentric planet positions. 34

10. Sidereal mode functions. 34

10.1. swe_set_sid_mode(). 34

10.2. swe_get_ayanamsa_ut() and swe_get_ayanamsa(). 36

11. The Ephemeris file related functions. 36

11.1 swe_set_ephe_path(). 36

11.2 swe_close(). 37

11.3 swe_set_jpl_file(). 37

11.4 swe_version(). 37

12. House cusp calculation. 38

12.1 swe_houses(). 38

12.2 swe_houses_armc(). 38

12.3 swe_houses_ex(). 38

13. The sign of geographical longitudes in Swisseph functions. 40

14. Getting the house position of a planet with swe_house_pos(). 40

14.1. Calculating the Gauquelin sector position of a planet with swe_house_pos() or swe_gauquelin_sector(). 41

15. Sidereal time with swe_sidtime() and swe_sidtime0(). 42

16. Summary of SWISSEPH functions. 43

16.1. Calculation of planets and stars. 43

Planets, moon, asteroids, lunar nodes, apogees, fictitious bodies. 43

Fixed stars. 43

Set the geographic location for topocentric planet computation. 43

Set the sidereal mode for sidereal planet positions. 43

16.2 Eclipses and planetary phenomena. 44

Find the next eclipse for a given geographic position. 44

Find the next eclipse globally. 44

Compute the attributes of a solar eclipse for a given tjd, geographic long., latit. and height. 44

Find out the geographic position where a central eclipse is central or a non-central one maximal 44

Find the next occultation of a body by the moon for a given geographic position. 45

Find the next occultation globally. 45

Find the next lunar eclipse. 45

Compute the attributes of a lunar eclipse at a given time. 45

Compute planetary phenomena. 46

16.3. Date and time conversion. 46

Delta T from Julian day number 46

Julian day number from year, month, day, hour, with check whether date is legal 46

Julian day number from year, month, day, hour 46

Year, month, day, hour from Julian day number 46

Get tidal acceleration used in swe_deltat(). 47

Set tidal acceleration to be used in swe_deltat(). 47

Equation of time. 47

16.4. Initialization, setup, and closing functions. 47

Set directory path of ephemeris files. 47

16.5. House calculation. 48

Sidereal time. 48

House cusps, ascendant and MC. 48

Extended house function; to compute tropical or sidereal positions. 48

Get the house position of a celestial point. 48

Get the Gauquelin sector position for a body. 49

16.6. Auxiliary functions. 50

Coordinate transformation, from ecliptic to equator or vice-versa. 50

Coordinate transformation of position and speed, from ecliptic to equator or vice-versa. 50

Get the name of a planet. 50

16.7. Other functions that may be useful 50

Normalize argument into interval [0..DEG360]. 50

Distance in centisecs p1 - p2 normalized to [0..360]. 50

Distance in degrees. 50

Distance in centisecs p1 - p2 normalized to [-180..180]. 50

Distance in degrees. 51

Round second, but at 29.5959 always down. 51

Double to long with rounding, no overflow check. 51

Day of week. 51

Centiseconds -> time string. 51

Centiseconds -> longitude or latitude string. 51

Centiseconds -> degrees string. 51

17. The SWISSEPH DLLs. 51

17.1 DLL Interface for brain damaged compilers. 51

18. Using the DLL with  Visual Basic 5.0. 52

19. Using the DLL with  Borland Delphi and C++ Builder 52

19.1 Delphi 2.0 and higher (32-bit). 52

19.2 Borland C++ Builder 53

20. Using the Swiss Ephemeris with Perl 53

21. The C sample program.. 53

21. The source code distribution. 54

22. The PLACALC compatibility API 55

23. Documentation files. 55

24. Swisseph with different hardware and compilers. 55

25. Debugging and Tracing Swisseph. 56

25.1. If you are using the DLL. 56

25.2 If you are using the source code. 57

Appendix. 57

Update and release history. 57

Changes from version 1.75 to 1.76. 58

Changes from version 1.74 to version 1.75. 59

Changes from version 1.73 to version 1.74. 59

Changes from version 1.72 to version 1.73. 59

Changes from version 1.71 to version 1.72. 59

Changes from version 1.70.03 to version 1.71. 59

Changes from version 1.70.02 to version 1.70.03. 60

Changes from version 1.70.01 to version 1.70.02. 60

Changes from version 1.70.00 to version 1.70.01. 60

Changes from version 1.67 to version 1.70. 60

Changes from version 1.66 to version 1.67. 60

Changes from version 1.65 to version 1.66. 60

Changes from version 1.64.01 to version 1.65.00. 60

Changes from version 1.64 to version 1.64.01. 61

Changes from version 1.63 to version 1.64. 61

Changes from version 1.62 to version 1.63. 61

Changes from version 1.61.03 to version 1.62. 61

Changes from version 1.61 to 1.61.01. 61

Changes from version 1.60 to 1.61. 61

Changes from version 1.51 to 1.60. 62

Changes from version 1.50 to 1.51. 62

Changes from version 1.40 to 1.50. 62

Changes from version 1.31 to 1.40. 62

Changes from version 1.30 to 1.31. 62

Changes from version 1.27 to 1.30. 62

Changes from version 1.26 to 1.27. 63

Changes from version 1.25 to 1.26. 63

Changes from version 1.22 to 1.23. 63

Changes from version 1.21 to 1.22. 63

Changes from version 1.20 to 1.21. 63

Changes from version 1.11 to 1.20. 63

Changes from version 1.10 to 1.11. 63

Changes from version 1.04 to 1.10. 64

Changes from Version 1.03 to 1.04. 64

Changes from Version 1.02 to 1.03. 64

Changes from Version 1.01 to 1.02. 64

Changes from Version 1.00  to 1.01. 64

1. Sidereal time. 64

2. Houses. 65

3. Ecliptic obliquity and nutation. 65

Appendix A. 65

What is missing ?. 65

Index. 66


 

1. The programming steps to get a planet’s position

 

To compute a celestial body or point with SWISSEPH, you have to do the following steps (use swetest.c as an example). The details of the functions will be explained in the following chapters.

 

1.         Set the directory path of the ephemeris files, e.g.:

         swe_set_ephe_path(”C:\\SWEPH\\EPHE”);

 

2..         From the birth date, compute the Julian day number:

         jul_day_UT = swe_julday(year, month, day, hour, gregflag);

 

3..  Compute a planet or other bodies:

         ret_flag = swe_calc_ut(jul_day_UT, planet_no, flag, lon_lat_rad, err_msg);

     or a fixed star:

         ret_flag = swe_fixstar_ut(star_nam, jul_day_UT, flag, lon_lat_rad, err_msg);

 

     Note:

      The functions swe_calc_ut() and swe_fixstar_ut() were introduced with Swisseph version 1.60.

      If you use a Swisseph version older than 1.60 or if you want to work with Ephemeris Time, you have to proceed as follows instead:

 

      First, if necessary, convert Universal Time (UT) to Ephemeris Time (ET):

         jul_day_ET = jul_day_UT + swe_deltat(jul_day_UT);

 

      Then Compute a planet or other bodies:

         ret_flag = swe_calc(jul_day_ET, planet_no, flag, lon_lat_rad, err_msg);

      or a fixed star:

         ret_flag = swe_fixstar(star_nam, jul_day_ET, flag, lon_lat_rad, err_msg);

 

5..         At the end of your computations close all files and free memory calling swe_close();

 

Here is a miniature sample program, it is in the source distribution as swemini.c

 

#include "swephexp.h"      /* this includes  "sweodef.h" */

int main()

{

  char *sp, sdate[AS_MAXCH], snam[40], serr[AS_MAXCH]; 

  int jday = 1, jmon = 1, jyear = 2000;

  double jut = 0.0;

  double tjd_ut, te, x2[6];

  long iflag, iflgret;

  int p;

  iflag = SEFLG_SPEED;

  while (TRUE) {

    printf("\nDate (d.m.y) ?");

    gets(sdate);

          /* stop if a period . is entered */

    if (*sdate == '.')

      return OK;

    if (sscanf (sdate, "%d%*c%d%*c%d", &jday,&jmon,&jyear) < 1) exit(1);

             /*

              * we have day, month and year and convert to Julian day number

              */

    tjd_ut = swe_julday(jyear,jmon,jday,jut,SE_GREG_CAL);       

             /*

              * compute Ephemeris time from Universal time by adding delta_t

              * not required for Swisseph versions smaller than 1.60

              */

       /* te = tjd_ut + swe_deltat(tjd_ut); */

    printf("date: %02d.%02d.%d at 0:00 Universal time\n", jday, jmon, jyear);

    printf("planet     \tlongitude\tlatitude\tdistance\tspeed long.\n");

             /*

              * a loop over all planets

              */

    for (p = SE_SUN; p <= SE_CHIRON; p++) {

      if (p == SE_EARTH) continue;

          /*

           * do the coordinate calculation for this planet p

           */

iflgret = swe_calc_ut(tjd_ut, p, iflag, x2, serr);

         /* Swisseph versions older than 1.60 require the following

          * statement instead */

/* iflgret = swe_calc(te, p, iflag, x2, serr); */

               /*

                * if there is a problem, a negative value is returned and an

                * error message is in serr.

                */

      if (iflgret < 0)

         printf("error: %s\n", serr);

               /*

                * get the name of the planet p

                */

      swe_get_planet_name(p, snam);

               /*

                * print the coordinates

                */

      printf("%10s\t%11.7f\t%10.7f\t%10.7f\t%10.7f\n",

              snam, x2[0], x2[1], x2[2], x2[3]);

    }

  }

  return OK;

}

2. The functions swe_calc_ut() and swe_calc()

2.1. The call parameters

swe_calc_ut() was introduced with Swisseph version 1.60 and makes planetary calculations a bit simpler. For the steps required, see the chapter  The programming steps to get a planet’s position.

swe_calc_ut() and swe_calc() work exactly the same way except that swe_calc() requires Ephemeris Time ( more accurate: Dynamical Time ) as a parameter whereas swe_calc_ut() expects Universal Time. For common astrological calculations, you will only need swe_calc_ut() and will not have to think anymore about the conversion between Universal Time and Ephemeris Time.

swe_calc_ut() and swe_calc() compute positions of planets, asteroids, lunar nodes and apogees. They are defined as follows:

 

int swe_calc_ut ( double tjd_ut, int ipl, int iflag, double* xx, char* serr),

where

tjd_ut     =Julian day, Universal Time

ipl       =body number

iflag    =a 32 bit integer containing bit flags that indicate what kind of computation is wanted

xx       =array of 6 doubles for longitude, latitude, distance, speed in long., speed in lat., and speed in dist.

serr[256] =character string to return error messages in case of error.

 

and

int swe_calc(double tjd_et, int ipl, int iflag, double *xx, char *serr),

same but

tjd_et     =     Julian day, Ephemeris time,  where tjd_et = tjd_ut + swe_deltat(tjd_ut)

 

A detailed description of these variables will be given in the following sections.

2.2. Error handling and return values

On success, swe_calc ( or swe_calc_ut ) returns a 32-bit integer containing flag bits that indicate what kind of computation has been done. This value may or may not be equal to iflag. If an option specified by iflag cannot be fulfilled or makes no sense, swe_calc just does what can be done. E.g., if you specify that you want JPL ephemeris, but swe_calc cannot find the ephemeris file, it tries to do the computation with any available ephemeris. This will be indicated in the return value of swe_calc. So, to make sure that swe_calc () did exactly what you had wanted, you may want to check whether or not the return code == iflag.

However, swe_calc() might return an fatal error code (< 0) and an error string in one of the following cases:

 

·         if an illegal body number has been specified

·         if a Julian day beyond the ephemeris limits has been specified

·         if the length of the ephemeris file is not correct (damaged file)

·         on read error, e.g. a file index points to a position beyond file length ( data on file are corrupt )

·         if the copyright section in the ephemeris file has been destroyed.

 

If any of these errors occurs,

 

·         the return code of the function is -1,

·         the position and speed variables are set to zero,

·         the type of error is indicated in the error string serr.

2.3. Bodies ( int ipl )

 

To tell swe_calc() which celestial body or factor should be computed, a fixed set of body numbers is used. The body numbers are defined in swephexp.h:

/* planet numbers for the ipl parameter in swe_calc() */

 

#define SE_ECL_NUT     -1     

#define SE_SUN               0      

#define SE_MOON              1      

#define SE_MERCURY           2      

#define SE_VENUS             3      

#define SE_MARS              4      

#define SE_JUPITER           5      

#define SE_SATURN            6      

#define SE_URANUS            7      

#define SE_NEPTUNE           8      

#define SE_PLUTO             9      

#define SE_MEAN_NODE         10     

#define SE_TRUE_NODE         11

#define SE_MEAN_APOG         12     

#define SE_OSCU_APOG         13   

#define SE_EARTH             14

#define SE_CHIRON            15

#define SE_PHOLUS            16

#define SE_CERES             17

#define SE_PALLAS            18

#define SE_JUNO              19

#define SE_VESTA             20

#define SE_INTP_APOG             21

#define SE_INTP_PERG             22

 

#define SE_NPLANETS             23

#define SE_FICT_OFFSET       40

#define SE_NFICT_ELEM                15

 

/* Hamburger or Uranian "planets" */

 

#define SE_CUPIDO            40

#define SE_HADES             41

#define SE_ZEUS              42

#define SE_KRONOS            43

#define SE_APOLLON           44

#define SE_ADMETOS           45

#define SE_VULKANUS          46

#define SE_POSEIDON          47

 

/* other fictitious bodies */

 

#define SE_ISIS              48

#define SE_NIBIRU            49

#define SE_HARRINGTON           50

#define SE_NEPTUNE_LEVERRIER      51

#define SE_NEPTUNE_ADAMS         52

#define SE_PLUTO_LOWELL          53

#define SE_PLUTO_PICKERING        54

 

#define SE_AST_OFFSET     10000

 

 

Additional asteroids

 

Body numbers of other asteroids are above SE_AST_OFFSET (=10000) and have to be constructed as follows:

ipl = SE_AST_OFFSET + Minor_Planet_Catalogue_number;

e.g. Eros :  ipl = SE_AST_OFFSET +  433

The names of the asteroids and their catalogue numbers can be found in seasnam.txt.

Examples are:

 

5              Astraea

6              Hebe    

7              Iris         

8              Flora

9              Metis

10              Hygiea  

30              Urania  

42              Isis              not identical with "Isis-Transpluto"

153              Hilda              (has an own asteroid belt at 4 AU)

227              Philosophia        

251              Sophia  

259              Aletheia

275              Sapientia             

279              Thule              (asteroid close to Jupiter)

375              Ursula   

433              Eros      

763              Cupido              different from Witte's Cupido

944              Hidalgo 

1181              Lilith              (not identical with Dark Moon 'Lilith')

1221              Amor     

1387              Kama    

1388              Aphrodite           

1862              Apollo              (different from Witte's Apollon)

3553              Damocles              highly eccentric orbit betw. Mars and Uranus

3753              Cruithne              ("second moon" of earth)

4341              Poseidon              Greek Neptune (different from Witte's Poseidon)

4464              Vulcano              fire god (different from Witte's Vulkanus and intramercurian Vulcan)

5731              Zeus              Greek Jupiter (different from Witte's Zeus)

7066              Nessus              third named Centaur (beween Saturn and Pluto)

 

 

There are two ephemeris files for each asteroid (except the main asteroids), a long one and a short one:

 

se09999.se1     long-term ephemeris of asteroid number 9999, 3000 BC – 3000 AD

se09999s.se1     short ephemeris of asteroid number 9999, 1500 – 2100 AD

 

The larger file is about 10 times the size of the short ephemeris. If the user does not want an ephemeris for the time before 1500 he might prefer to work with the short files. If so, just copy the files ending with ”s.se1” to your hard disk. Swe_calc() tries the long one and on failure automatically takes the short one.

Asteroid ephemerides are looked for in the subdirectories ast0, ast1, ast2 .. ast9 etc of the ephemeris directory and, if not found there, in the ephemeris directory itself. Asteroids with numbers 0 – 999 are expected in directory ast0, those with numbers 1000 – 1999 in directory ast1 etc.

 

Note that  not all asteroids  can be computed for the whole period of Swiss Ephemeris. The orbits of some of them are extremely sensitive to perturbations by major planets. E.g. CHIRON, cannot be computed for the time before 650 AD and after 4650 AD because of close encounters with Saturn. Outside this time range, Swiss Ephemeris returns the error code, an error message, and a position value 0. Be aware, that the user will have to handle this case in his program. Computing Chiron transits for Jesus or Alexander the Great will not work.

The same is true for Pholus before 3850 BC, and for many other asteroids, as e.g. 1862 Apollo. He becomes chaotic before the year 1870 AD, when he approaches Venus very closely. Swiss Ephemeris does not provide positions of Apollo for earlier centuries !

 

Note on asteroid names

Asteroid names are listed in the file seasnam.txt. This file is in the ephemeris directory.

 

Fictitious planets

 

Fictitious planets have numbers greater than or equal to 40. The user can define his or her own fictitious planets. The orbital elements of these planets must be written into the file seorbel.txt. The function swe_calc() looks for the file seorbel.txt in the ephemeris path set by swe_set_ephe_path(). If no orbital elements file is found, swe_calc() uses the built-in orbital elements of the above mentioned Uranian planets and some other bodies. The planet number of a fictitious planet is defined as

 

ipl = SE_FICT_OFFSET_1 + number_of_elements_set;

 

e.g. for Kronos: ipl = 39 + 4 = 43.

 

The file seorbel.txt has the following structure:

 

    # Orbital elements of fictitious planets

    # 27 Jan. 2000

    #

    # This file is part of the Swiss Ephemeris, from Version 1.60 on.

    #

    # Warning! These planets do not exist!

    #

    # The user can add his or her own elements.

    # 960 is the maximum number of fictitious planets.

    #

    # The elements order is as follows:

    # 1. epoch of elements (Julian day)

    # 2. equinox (Julian day or "J1900" or "B1950" or "J2000" or “JDATE”)

    # 3. mean anomaly at epoch

    # 4. semi-axis

    # 5. eccentricity

    # 6. argument of perihelion (ang. distance of perihelion from node)

    # 7. ascending node

    # 8. inclination

    # 9. name of planet

    #

    # use '#' for comments

    # to compute a body with swe_calc(), use planet number

    # ipl = SE_FICT_OFFSET_1 + number_of_elements_set,

    # e.g. number of Kronos is ipl = 39 + 4 = 43

    #

    # Witte/Sieggruen planets, refined by James Neely

J1900, J1900, 163.7409, 40.99837, 0.00460, 171.4333, 129.8325, 1.0833, Cupido   # 1

J1900, J1900,  27.6496, 50.66744, 0.00245, 148.1796, 161.3339, 1.0500, Hades    # 2

J1900, J1900, 165.1232, 59.21436, 0.00120, 299.0440,   0.0000, 0.0000, Zeus     # 3

J1900, J1900, 169.0193, 64.81960, 0.00305, 208.8801,   0.0000, 0.0000, Kronos   # 4

J1900, J1900, 138.0533, 70.29949, 0.00000,   0.0000,   0.0000, 0.0000, Apollon  # 5

J1900, J1900, 351.3350, 73.62765, 0.00000,   0.0000,   0.0000, 0.0000, Admetos  # 6

J1900, J1900,  55.8983, 77.25568, 0.00000,   0.0000,   0.0000, 0.0000, Vulcanus # 7

J1900, J1900, 165.5163, 83.66907, 0.00000,   0.0000,   0.0000, 0.0000, Poseidon # 8

    #

    # Isis-Transpluto; elements from "Die Sterne" 3/1952, p. 70ff.

    # Strubell does not give an equinox. 1945 is taken in order to

    # reproduce the as best as ASTRON ephemeris. (This is a strange

    # choice, though.)

    # The epoch according to Strubell is 1772.76.

    # 1772 is a leap year!

    # The fraction is counted from 1 Jan. 1772

2368547.66, 2431456.5, 0.0, 77.775, 0.3, 0.7, 0, 0, Isis-Transpluto             # 9

    # Nibiru, elements from Christian Woeltge, Hannover

1856113.380954, 1856113.380954, 0.0, 234.8921, 0.981092, 103.966, -44.567, 158.708, Nibiru # 10

    # Harrington, elements from Astronomical Journal 96(4), Oct. 1988

2374696.5, J2000, 0.0, 101.2, 0.411, 208.5, 275.4, 32.4, Harrington             # 11

    # according to W.G. Hoyt, "Planets X and Pluto", Tucson 1980, p. 63

2395662.5, 2395662.5, 34.05, 36.15, 0.10761, 284.75, 0, 0, Leverrier (Neptune)  # 12

2395662.5, 2395662.5, 24.28, 37.25, 0.12062, 299.11, 0, 0, Adams (Neptune)      # 13

2425977.5, 2425977.5, 281, 43.0, 0.202, 204.9, 0, 0, Lowell (Pluto)             # 14

2425977.5, 2425977.5, 48.95, 55.1, 0.31, 280.1, 100, 15, Pickering (Pluto)      # 15

J1900,JDATE, 252.8987988 + 707550.7341 * T, 0.13744, 0.019, 322.212069+1670.056*T, 47.787931-1670.056*T, 7.5, Vulcan # 16

# Selena/White Moon

J2000,JDATE, 242.2205555, 0.05279142865925, 0.0, 0.0, 0.0, 0.0, Selena/White Moon, geo # 17

 

All orbital elements except epoch and equinox may have T  terms, where

T = (tjd – epoch) / 36525.

(See, e.g., Vulcan, the second last elements set (not the ”Uranian” Vulcanus but the intramercurian hypothetical planet Vulcan).) ”T * T”, ”T2”, ”T3” are also allowed.

The equinox can either be entered as a Julian day or as ”J1900” or ”B1950” or ”J2000” or, if the equinox of date is required, as ”JDATE”. If you use T terms, note that precession has to be taken into account with JDATE, whereas it has to be neglected with fixed equinoxes.

 

No T term is required with the mean anomaly, i.e. for the speed of the body, because our software can compute it from semi-axis and gravity. However, a mean anomaly T term had to be added with Vulcan because its speed is not in agreement with the laws of physics. In such cases, the software takes the speed given in the elements and does not compute it internally.

 

From Version 1.62 on, the software also accepts orbital elements for fictitious bodies that move about the earth. As an example, study the last elements set in the excerpt of seorbel.txt above. After the name of the body, ”, geo” has to be added.

 

 

 

Obliquity and nutation

 

A special body number SE_ECL_NUT is provided to compute the obliquity of the ecliptic and the nutation. Of course nutation is already added internally to the planetary coordinates by swe_calc() but sometimes it will be needed as a separate value.

 

iflgret = swe_calc(tjd_et, SE_ECL_NUT, 0, x, serr);

 

x is an array of 6 doubles as usual. They will be filled as follows:

 

x[0] = true obliqutiy of the Ecliptic (includes nutation)

x[1] = mean obliquity of the Ecliptic

x[2] = nutation in longitude

x[3] = nutation in obliquity

x[4] = x[5] = 0

2.4. Options chosen by flag bits (long  iflag)

2.4.1. The use of flag bits

 

If no bits are set, i.e. if  iflag == 0, swe_calc() computes what common astrological ephemerides (as available in book shops) supply, i.e. an apparent  body position in geocentric ecliptic polar coordinates ( longitude, latitude, and distance) relative to the true equinox of the date.

If the speed of the body is required, set iflag = SEFLG_SPEED

For mathematical points as the mean lunar node and the mean apogee, there is no apparent position. Swe_calc() returns true positions for these points.

If you need another kind of computation, use the flags explained in the following paragraphs (c.f. swephexp.h). Their names begin with ‚SEFLG_‘. To combine them, you have to concatenate them (inclusive-or) as in the following example:

iflag = SEFLG_SPEED | SEFLG_TRUEPOS;  (or: iflag = SEFLG_SPEED + SEFLG_TRUEPOS;) // C

iflag = SEFLG_SPEED or SEFLG_TRUEPOS;(or: iflag = SEFLG_SPEED + SEFLG_TRUEPOS;) // Pascal

 

With this value of iflag, swe_calc() will compute true positions ( i.e. not accounted for light-time ) with speed.

The flag bits, which are defined in swephexp.h, are:

 

#define SEFLG_JPLEPH         1L     // use JPL ephemeris

#define SEFLG_SWIEPH         2L     // use SWISSEPH ephemeris, default

#define SEFLG_MOSEPH         4L     // use Moshier ephemeris

 

#define SEFLG_HELCTR              8L     // return heliocentric position

#define SEFLG_TRUEPOS      16L     // return true positions, not apparent

#define SEFLG_J2000               32L     // no precession, i.e. give J2000 equinox

#define SEFLG_NONUT               64L     // no nutation, i.e. mean equinox of date

#define SEFLG_SPEED3              128L     // speed from 3 positions (do not use it, SEFLG_SPEED is

                   // faster and preciser.)

#define SEFLG_SPEED               256L     // high precision speed (analyt. comp.)

#define SEFLG_NOGDEFL      512L     // turn off gravitational deflection

#define SEFLG_NOABERR      1024L     // turn off 'annual' aberration of light

#define SEFLG_EQUATORIAL     2048L     // equatorial positions are wanted

#define SEFLG_XYZ                 4096L     // cartesian, not polar, coordinates

#define SEFLG_RADIANS            8192L     // coordinates in radians, not degrees

#define SEFLG_BARYCTR            16384L     // barycentric positions

#define SEFLG_TOPOCTR      (32*1024L)     // topocentric positions

#define SEFLG_SIDEREAL     (64*1024L)     // sidereal positions

2.4.2. Ephemeris flags

 

The flags to choose an ephemeris are: (s. swephexp.h)

 

SEFLG_JPLEPH           /* use JPL ephemeris */

SEFLG_SWIEPH           /* use Swiss Ephemeris */

SEFLG_MOSEPH           /* use Moshier ephemeris */

 

If none of this flags is specified, swe_calc() tries to compute the default ephemeris. The default ephemeris is defined in swephexp.h:

#define SEFLG_DEFAULTEPH SEFLG_SWIEPH

In this case the default ephemeris is Swiss Ephemeris. If you have not specified an ephemeris in iflag, swe_calc() tries to compute a Swiss Ephemeris position. If it does not find the required Swiss Ephemeris file either, it computes a Moshier position.

2.4.3. Speed flag

 

Swe_calc() does not compute speed if you do not add the speed flag SEFLG_SPEED. E.g.

iflag |= SEFLG_SPEED;

The computation of speed is usually cheap, so you may set this bit by default even if you do not need the speed.

 

2.4.4. Coordinate systems, degrees and radians

 

SEFLG_EQUATORIAL              returns equatorial positions: rectascension and declination.

SEFLG_XYZ                             returns x, y, z coordinates instead of longitude, latitude, and distance.

SEFLG_RADIANS                      returns position in radians, not degrees.

 

E.g. to compute rectascension and declination, write:

iflag = SEFLG_SWIEPH | SEFLG_SPEED | SEFLG_EQUATORIAL;

2.4.5. Specialties (going beyond common interest)

a. True or apparent positions

Common ephemerides supply apparent geocentric positions. Since the journey of the light from a planet to the earth takes some time, the planets are never seen where they actually are, but where they were a few minutes or hours before. Astrology uses to work with the positions we see. ( More precisely: with the positions we would see, if we stood at the center of the earth and could see the sky. Actually, the geographical position of the observer could be of importance as well and topocentric positions could be computed, but this is usually not taken into account in astrology.). The geocentric position for the earth (SE_EARTH) is returned as zero.

To compute the true geometrical position of a planet, disregarding light-time, you have to add the flag SEFLG_TRUEPOS.

b. Topocentric positions

To compute topocentric positions, i.e. positions referred to the place of the observer (the birth place) rather than to the center of the earth, do as follows:

·         call swe_set_topo(geo_lon, geo_lat, altitude_above_sea)  (The longitude and latitude must be in degrees, the altitude in meters.)

·        add the flag SEFLG_TOPOCTR to iflag

·          call swe_calc(...)

c. Heliocentric positions

To compute a heliocentric position, add SEFLG_HELCTR.

A heliocentric position can be computed for all planets including the moon. For the sun, lunar nodes and lunar apogees the coordinates are returned as zero; no error message appears.

d. Barycentric positions

SEFLG_BARYCTR yields coordinates as referred to the solar system barycenter. However, this option is not completely implemented.  It was used for program tests during development.  It works only with the JPL and the Swiss Ephemeris, not with the Moshier ephemeris; and only with physical bodies, but not with the nodes and the apogees.

Moreover, the barycentric Sun of Swiss Ephemeris has ”only” a precision of 0.1”. Higher accuracy would have taken a lot of storage, on the other hand it is not needed for precise geocentric and heliocentric positions. For more precise barycentric positions the JPL ephemeris file should be used.

A barycentric position can be computed for all planets including the sun and moon. For the lunar nodes and lunar apogees the coordinates are returned as zero; no error message appears.

e. Astrometric positions

For astrometric positions, which are sometimes given in the Astronomical Almanac, the light-time correction is computed, but annual aberration and the light-deflection by the sun neglected. This can be done with SEFLG_NOABERR and SEFLG_NOGDEFL. For positions related to the mean equinox of 2000, you must set SEFLG_J2000 and SEFLG_NONUT, as well.

f. True or mean equinox of date

Swe_calc() usually computes the positions as referred to the true equinox of the date ( i.e. with nutation ). If you want the mean equinox, you can turn nutation off, using the flag bit SEFLG_NONUT.

g. J2000 positions and positions referred to other equinoxes

Swe_calc() usually computes the positions as referred to the equinox of date. SEFLG_J2000 yields data referred to the equinox J2000. For positions referred to other equinoxes, SEFLG_SIDEREAL has to be set and the equinox specified by swe_set_sid_mode(). For more information, read the description of this function.

h. Sidereal positions

To compute sidereal positions, set bit SEFLG_SIDEREAL and use the function swe_set_sid_mode() in order to define the ayanamsha you want. For more information, read the description of this function.

 

2.5. Position and Speed (double xx[6])

 

swe_calc() returns the coordinates of position and velocity in the following order:

 

Ecliptic position

Equatorial position ( SEFLG_EQUATORIAL )

Longitude

Rectascension

Latitude

Declination

Distance in AU

distance in AU

Speed in longitude (deg/day)

Speed in rectascension (deg/day)

Speed in latitude (deg/day)

Speed in declination (deg/day)

Speed in distance (AU/day)

Speed in distance (AU/day)

 

If you need rectangular coordinates ( SEFLG_XYZ ), swe_calc() returns x, y, z, dx, dy, dz in AU.

Once you have computed a planet, e.g., in ecliptic coordinates, its equatorial position or its rectangular coordinates are available, too.  You can get them very cheaply ( little CPU time used ), calling again swe_calc() with the same parameters, but adding SEFLG_EQUATORIAL or SEFLG_XYZ to iflag. swe_calc() will not compute the body again, just return the data specified from internal storage.

 

3. The function swe_get_planet_name()

This function allows to find a planetary or asteroid name, when the planet number is given. The function definition is

char* swe_get_planet_name(int ipl, char *spname);

 

If an asteroid name is wanted, the function does the following:

 

·         The name is first looked for in the asteroid file.

·         Because many asteroids, especially the ones with high catalogue numbers, have no names yet (or have only a preliminary designation like 1968 HB), and because the Minor Planet Center of the IAU add new names quite often, it happens that there is no name in the asteroid file although the asteroid has already been given a name. For this, we have the file seasnam.txt, a file that contains a list of all named asteroid and is usually more up to date. If swe_calc() finds a preliminary designation, it looks for a name in this file.

 

The file seasnam.txt can be updated by the user. To do this, download the names list from the Minor Planet Center http://cfa-www.harvard.edu/iau/lists/MPNames.html, rename it as seasnam.txt and move it into your ephemeris directory.

 

The file seasnam.txt need not be ordered in any way. There must be one asteroid per line, first its catalogue number, then its name. The asteroid number may or may not be in brackets.

Example:

 

(3192) A'Hearn

(3654) AAS

(8721) AMOS

(3568) ASCII

(2848) ASP

(677) Aaltje

  ...

4. Fixed stars functions

4.1 swe_fixstar_ut

The function swe_fixstar_ut() was introduced with Swisseph version 1.60. It does exactly the same as swe_fixstar() except that it expects Universal Time rather than Ephemeris time as an input value. (cf. swe_calc_ut() and swe_calc())

The functions swe_fixstar_ut() and swe_fixstar() computes fixed stars. They are defined as follows:

 

long swe_fixstar_ut(char* star, double tjd_ut, long iflag, double* xx, char* serr);

where

star              =name of fixed star to be searched, returned name of found star

tjd_ut              =Julian day in Universal Time

iflag       =an integer containing several flags that indicate what      kind of computation is wanted

xx              =array of 6 doubles for longitude, latitude, distance, speed in long., speed in lat., and speed in dist.

serr[256] =character string to contain error messages in case of error.

 For more info, see below under 4.2. swe_fixstar()

 

4.2 swe_fixstar()

long swe_fixstar(char *star, double tjd_et, long iflag, double* xx, char* serr);

same, but  tjd_et= Julian day in Ephemeris Time

 

The  parameter star must provide for at least 41 characters for the returned star name (= 2 x SE_MAX_STNAME + 1, where SE_MAX_STNAME is defined in swephexp.h). If a star is found, its name is returned in this field in the format
traditional_name, nomenclature_name e.g. "Aldebaran,alTau".

 

The function has three modes to search for a star in the file fixstars.cat:

 

·         star contains a positive number ( in ASCII string format, e.g. "234"): The 234-th non-comment line in the file fixstars.cat is used. Comment lines begin with # and are ignored.

·         star contains a traditional name: the first star in the file fixstars.cat is used whose traditional name fits the given name. All names are mapped to lower case before comparison. If star has n characters, only the first n characters of the traditional name field are compared. If a comma appears after a non-zero-length traditional name, the traditional name is cut off at the comma before the search. This allows the reuse of the returned star name from a previous call in the next call.

·         star begins with a comma, followed by a nomenclature name, e.g. ",alTau": the star with this name in the nomenclature field ( the second field ) is returned. Letter case is observed in the comparison for nomenclature names.

 

For correct spelling of nomenclature names, see file fixstars.cat. Nomenclature names are usually composed of a Greek letter and the name of a star constellation. The Greek letters were originally used to write numbers, therefore to number the stars of the constellation. The abbreviated nomenclature names we use in fixstars.cat are constructed from two lowercase letters for the Greek letter (e.g. ”al” for ”alpha”) and three letters for the constellation (e.g. ”Tau” for ”Tauri”).

 

The function and the DLL should survive damaged fixstars.cat files which contain illegal data and star names exceeding the accepted length. Such fields are cut to acceptable length.

There are two special entries in the file fixstars.cat:

 

·         an entry for the Galactic Center, named "Gal. Center" with one blank.

·         a star named "AA_page_B40" which is the star calculation sample of Astronomical Almanac  (our bible of the last two years), page B40.

 

You may edit the star catalogue and move the stars you prefer to the top of the file. This will increase the speed of your computations. The search mode is linear through the whole star file for each call of swe_fixstar().

As for the explanation of the other parameters, see swe_calc().

Barycentric positions are not implemented. The difference between geocentric and heliocentric fix star position is noticeable and arises from parallax and gravitational deflection.

Attention: swe_fixstar() does not compute speeds of the fixed stars. If you need them, you have to compute them on your own, calling swe_fixstar() for a second ( and third ) time.

 

4.3 swe_fixstar_mag()

long swe_fixstar_mag(char *star, double* mag, char* serr);

 

Function calculates the magnitude of a fixed star. The function returns OK or ERR. The magnitude value is returned in the parameter mag.

For the definition and use of the parameter star see function swe_fixstar(). The parameter serr and is, as usually, an error string pointer.

 

5. Apsides functions

5.1 swe_nod_aps_ut

The functions swe_nod_aps_ut() and swe_nod_aps() compute planetary nodes and apsides ( perihelia, aphelia, second focal points of the orbital ellipses ). Both functions do exactly the same except that they expect a different time parameter (cf. swe_calc_ut() and swe_calc() ).

 

The definitions are:

 

int32 swe_nod_aps_ut(double tjd_ut, int32 ipl, int32 iflag, int32 method, double *xnasc, double *xndsc, double *xperi, double *xaphe, char *serr);

where

tjd_ut             =Julian day in Universal Time

ipl              =planet number

iflag             =same as with swe_calc_ut() and swe_fixstar_ut()

method             =another integer that specifies the calculation method, see explanations below

xnasc             =array of 6 doubles for ascending node

xndsc             =array of 6 doubles for descending node

xperi             =array of 6 doubles for perihelion

xaphe             =array of 6 doubles for aphelion

serr[256]              =character string to contain error messages in case of error.

5.2 swe_nod_aps()

int32 swe_nod_aps(double tjd_et, int32 ipl, int32 iflag, int32 method, double *xnasc, double *xndsc, double *xperi, double *xaphe, char *serr);

same, but

tjd_et     =     Julian day in Ephemeris Time

 

The parameter iflag allows the same specifications as with the function swe_calc_ut(). I.e., it contains the Ephemeris flag, the heliocentric, topocentric, speed, nutation flags etc. etc.

The parameter method tells the function what kind of nodes or apsides are required:

#define SE_NODBIT_MEAN          1

 

This is also the default. Mean nodes and apsides are calculated for the bodies that have them, i.e. for the Moon and the planets Mercury through Neptune, osculating ones for Pluto and the asteroids.

#define SE_NODBIT_OSCU          2

 

Osculating nodes and apsides are calculated for all bodies.

#define SE_NODBIT_OSCU_BAR     4

 

Osculating nodes and apsides are calculated for all bodies. With planets beyond Jupiter, they are computed from a barycentric ellipse. Cf. the explanations in swisseph.doc.

 

If this bit is combined with SE_NODBIT_MEAN, mean values are given for the planets Mercury - Neptun.

#define SE_NODBIT_FOPOINT     256

 

The second focal point of the orbital ellipse is computed and returned in the array of the aphelion. This bit can be combined with any other bit.

 

It is not meaningful to compute mean oribital elements topocentrically. The concept of mean elements precludes consideration of any short term fluctuations in coordinates.

 

6. Eclipse and planetary phenomena functions

 

There are the following functions for eclipse and occultation calculations.

 

Solar eclipses:

·         swe_sol_eclipse_when_loc( tjd...) finds the next eclipse for a given geographic position.

·         swe_sol_eclipse_when_glob( tjd...) finds the next eclipse globally.

·         swe_sol_eclipse_where() computes the geographic location of a solar eclipse for a given tjd.

·         swe_sol_eclipse_how() computes attributes of a solar eclipse for a given tjd, geographic longitude, latitude and height.

 

Occultations of planets by the moon:

These functions can also be used for solar eclipses. But they are slightly less efficient.

·         swe_lun_occult_when_loc( tjd...) finds the next occultation for a body and a given geographic position.

·         swe_lun_occult_when_glob( tjd...) finds the next occultation of a given body globally.

·         swe_lun_occult_where() computes the geographic location of an occultation for a given tjd.

 

Lunar eclipses:

·         swe_lun_eclipse_when(tjd...) finds the next lunar eclipse.

·         swe_lun_eclipse_how() computes the attributes of a lunar eclipse for a given tjd.

 

Risings, settings, and meridian transits of planets and stars:

·         swe_rise_trans()

 

Planetary phenomena:

·         swe_pheno_ut() and swe_pheno() compute phase angle, phase, elongation, apparent diameter, and apparent magnitude of the Sun, the Moon, all planets and asteroids.

 

6.0. Example of a typical eclipse calculation

Find the next total eclipse, calculate the geographical position where it is maximal and the four contacts for that position (for a detailed explanation of all eclipse functions see the next chapters):

 

double tret[10], attr[20], geopos[10];

char serr[255];

int32 whicheph = 0; /* default ephemeris */

double tjd_start = 2451545; /* Julian day number for 1 Jan 2000 */

int32 ifltype = SE_ECL_TOTAL ¦ SE_ECL_CENTRAL ¦ SE_ECL_NONCENTRAL;

/* find next eclipse anywhere on earth */

eclflag = swe_sol_eclipse_when_glob(tjd_start, whicheph,  ifltype, tret, 0, serr);

if (eclflag == ERR)

  return ERR;

/* the time of the greatest eclipse has been returned in tret[0];

 * now we can find geographical position of the eclipse maximum */

tjd_start = tret[0];

eclflag = swe_sol_eclipse_where(tjd_start, whicheph, geopos, attr, serr);

if (eclflag == ERR)

  return ERR;

/* the geographical position of the eclipse maximum is in geopos[0] and geopos[1];

 * now we can calculate the four contacts for this place. The start time is chosen

 * a day before the maximum eclipse: */

tjd_start = tret[0] - 1;

eclflag = swe_sol_eclipse_when_loc(tjd_start, whicheph, geopos, tret, attr, 0, serr);

if (eclflag == ERR)

  return ERR;

/* now tret[] contains the following values:

 * tret[0] = time of greatest eclipse (Julian day number)

 * tret[1] = first contact

 * tret[2] = second contact

 * tret[3] = third contact

 * tret[4] = fourth contact */

 

6.1. swe_sol_eclipse_when_loc() and swe_lun_occult_when_loc()

 

To find the next eclipse for a given geographic position, use swe_sol_eclipse_when_loc().

 

int32 swe_sol_eclipse_when_loc(

double tjd_start,      /* start date for search, Jul. day UT */

int32 ifl,      /* ephemeris flag */

double *geopos,      /* 3 doubles for geo. lon, lat, height eastern longitude is positive,

                western longitude is negative,  northern latitude is positive,

                southern latitude is negative */

double *tret,      /* return array, 10 doubles, see below */

double *attr,      /* return array, 20 doubles, see below */

AS_BOOL backward,      /* TRUE, if backward search */

char *serr);     /* return error string */

 

The function returns:

/* retflag     -1 (ERR) on error (e.g. if swe_calc() for sun or moon fails)

              SE_ECL_TOTAL or SE_ECL_ANNULAR or SE_ECL_PARTIAL

              SE_ECL_VISIBLE,

              SE_ECL_MAX_VISIBLE,

              SE_ECL_1ST_VISIBLE, SE_ECL_2ND_VISIBLE

              SE_ECL_3ST_VISIBLE, SE_ECL_4ND_VISIBLE

 

  tret[0]     time of maximum eclipse

  tret[1]     time of first contact

  tret[2]     time of second contact

  tret[3]     time of third contact

  tret[4]     time of forth contact

  tret[5]     time of sunrise between first and forth contact (not implemented so far)

  tret[6]     time of sunset beween first and forth contact  (not implemented so far)

 

  attr[0]     fraction of solar diameter covered by moon (magnitude)

  attr[1]     ratio of lunar diameter to solar one

  attr[2]     fraction of solar disc covered by moon (obscuration)

  attr[3]     diameter of core shadow in km

  attr[4]     azimuth of sun at tjd

  attr[5]     true altitude of sun above horizon at tjd

  attr[6]     apparent altitude of sun above horizon at tjd

  attr[7]     elongation of moon in degrees     */

 

6.2. swe_sol_eclipse_when_glob()

 

To find the next eclipse globally:

int32 swe_sol_eclipse_when_glob(

double tjd_start,      /* start date for search, Jul. day UT */

int32 ifl,      /* ephemeris flag */

int32 ifltype,      /* eclipse type wanted: SE_ECL_TOTAL etc. or 0, if any eclipse type */

double *tret,      /* return array, 10 doubles, see below */

AS_BOOL backward,      /* TRUE, if backward search */

char *serr);       /* return error string */

 

This function requires the time parameter tjd_start in Universal Time and also yields the return values (tret[]) in UT.  For conversions between ET and UT, use the function swe_deltat().

 

Note: An implementation of this function with parameters in Ephemeris Time would have been possible. The question when the next solar eclipse will happen anywhere on earth is independent of the rotational position of the earth and therefore independent of Delta T. However, the function is often used in combination with other eclipse functions (see example below), for which input and output in ET makes no sense, because they concern local circumstances of an eclipse and therefore are dependent on the rotational position of the earth. For this reason, UT has been chosen for the time parameters of all eclipse functions.

 

ifltype specifies the eclipse type wanted. It can be a combination of the following bits (see swephexp.h):

 

#define SE_ECL_CENTRAL      1

#define SE_ECL_NONCENTRAL        2

#define SE_ECL_TOTAL                4

#define SE_ECL_ANNULAR           8

#define SE_ECL_PARTIAL           16

#define SE_ECL_ANNULAR_TOTAL     32

 

Recommended values for ifltype:

/* search for any eclipse, no matter which type */

ifltype = 0; 

/* search a total eclipse; note: non-central total eclipses are very rare */

ifltype = SE_ECL_TOTAL ¦ SE_ECL_CENTRAL ¦ SE_ECL_NONCENTRAL;

/* search an annular eclipse */

ifltype = SE_ECL_TOTAL ¦ SE_ECL_CENTRAL ¦ SE_ECL_NONCENTRAL;

/* search an annular-total (hybrid) eclipse */

ifltype_ = SE_ECL_ANNULAR_TOTAL ¦ SE_ECL_CENTRAL ¦ SE_ECL_NONCENTRAL;

/* search a partial eclipse */

ifltype = SE_ECL_PARTIAL;

 

If your code does not work, please study the sample code in swetest.c.

 

The function returns:

 

/* retflag     -1 (ERR) on error (e.g. if swe_calc() for sun or moon fails)

              SE_ECL_TOTAL or SE_ECL_ANNULAR or SE_ECL_PARTIAL or SE_ECL_ANNULAR_TOTAL

              SE_ECL_CENTRAL

              SE_ECL_NONCENTRAL

 

  tret[0]     time of maximum eclipse

  tret[1]     time, when eclipse takes place at local apparent noon

  tret[2]     time of eclipse begin

  tret[3]     time of eclipse end

  tret[4]     time of totality begin

  tret[5]     time of totality end

  tret[6]     time of center line begin

  tret[7]     time of center line end

  tret[8]     time when annular-total eclipse becomes total not implemented so far

  tret[9]     time when annular-total eclipse becomes annular again not implemented so far

 

         declare as tret[10] at least !

 */

6.3. swe_sol_eclipse_how ()

 

To calculate the attributes of an eclipse for a given geographic position and time:

 

int32 swe_sol_eclipse_how(

double tjd_ut,      /* time, Jul. day UT */

int32 ifl,      /* ephemeris flag */

double *geopos     /* geogr. longitude, latitude, height above sea

                     * eastern longitude is positive,

               * western longitude is negative,

               * northern latitude is positive,

               * southern latitude is negative */

double *attr,      /* return array, 20 doubles, see below */

char *serr);     /* return error string */

 

/* retflag      -1 (ERR) on error (e.g. if swe_calc() for sun or moon fails)

              SE_ECL_TOTAL or SE_ECL_ANNULAR or SE_ECL_PARTIAL

               0, if no eclipse is visible at geogr. position.

 

 attr[0]     fraction of solar diameter covered by moon (magnitude)

 attr[1]     ratio of lunar diameter to solar one

 attr[2]     fraction of solar disc covered by moon (obscuration)

 attr[3]     diameter of core shadow in km

 attr[4]     azimuth of sun at tjd

 attr[5]     true altitude of sun above horizon at tjd

 attr[6]     apparent altitude of sun above horizon at tjd

 attr[7]     elongation of moon in degrees

 

6.4. swe_sol_eclipse_where ()

 

This function can be used to find out the geographic position, where, for a given time, a central eclipse is central or where a non-central eclipse is maximal.

If you want to draw the eclipse path of a total or annular eclipse on a map, first compute the start and end time of the total or annular phase with swe_sol_eclipse_when_glob(), then call swe_sol_eclipse_how() for several time intervals to get geographic positions on the central path. The northern and southern limits of the umbra and penumbra are not implemented yet.

 

int32 swe_sol_eclipse_where (

double tjd_ut,      /* time, Jul. day UT */

int32 ifl,      /* ephemeris flag */

double *geopos,     /* return array, 2 doubles, geo. long. and lat.

               * eastern longitude is positive,

               * western longitude is negative,

               * northern latitude is positive,

               * southern latitude is negative */

double *attr,      /* return array, 20 doubles, see below */

char *serr);       /* return error string */

The function returns:

 

/* -1 (ERR)     on error (e.g. if swe_calc() for sun or moon fails)

  0      if there is no solar eclipse at tjd

  SE_ECL_TOTAL

  SE_ECL_ANNULAR

  SE_ECL_TOTAL | SE_ECL_CENTRAL

  SE_ECL_TOTAL | SE_ECL_NONCENTRAL

  SE_ECL_ANNULAR | SE_ECL_CENTRAL

  SE_ECL_ANNULAR | SE_ECL_NONCENTRAL

  SE_ECL_PARTIAL

 

  geopos[0]:     geographic longitude of central line

  geopos[1]:     geographic latitude of central line

 

  not implemented so far:

  geopos[2]:     geographic longitude of northern limit of umbra

  geopos[3]:     geographic latitude of northern limit of umbra

  geopos[4]:     geographic longitude of southern limit of umbra

  geopos[5]:     geographic latitude of southern limit of umbra

  geopos[6]:     geographic longitude of northern limit of penumbra

  geopos[7]:     geographic latitude of northern limit of penumbra

  geopos[8]:     geographic longitude of southern limit of penumbra

  geopos[9]:     geographic latitude of southern limit of penumbra

 

  eastern longitudes are positive,

  western longitudes are negative,

  northern latitudes are positive,

  southern latitudes are negative

 

  attr[0]     fraction of solar diameter covered by moon (magnitude)

  attr[1]     ratio of lunar diameter to solar one

  attr[2]     fraction of solar disc covered by moon (obscuration)

  attr[3]     diameter of core shadow in km

  attr[4]     azimuth of sun at tjd

  attr[5]     true altitude of sun above horizon at tjd

  attr[6]     apparent altitude of sun above horizon at tjd

  attr[7]     angular distance of moon from sun in degrees

 

      declare as attr[20]!

 */

 

6.5. swe_lun_occult_when_loc()

To find the next occultation of a planet or star by the moon for a given location, use swe_lun_occult_when_loc().

The same function can also be used for local solar eclipses instead of swe_sol_eclipse_when_loc(), but is a bit less efficient.

 

/* Same declaration as swe_sol_eclipse_when_loc().

 * In addition:

 * int32 ipl               planet number of occulted body

 * char* starname          name of occulted star. Must be NULL or "", if a planetary

 *                         occultation is to be calculated. For use of this field,

 *                             see swe_fixstar().

 * int32 ifl             ephemeris flag. If you want to have only one conjunction

 *                         of the moon with the body tested, add the following flag:

 *                         backward |= SE_ECL_ONE_TRY. If this flag is not set,

 *                         the function will search for an occultation until it

 *                         finds one. For bodies with ecliptical latitudes > 5,

 *                         the function may search successlessly until it reaches

 *                         the end of the ephemeris.

 */

int32 swe_lun_occult_when_loc(

double tjd_start,      /* start date for search, Jul. day UT */

int32 ipl,      /* planet number */

char* starname,      /* star name, must be NULL or ”” if not a star */

int32 ifl,      /* ephemeris flag */

double *geopos,      /* 3 doubles for geo. lon, lat, height eastern longitude is positive,

                western longitude is negative,  northern latitude is positive,

                southern latitude is negative */

double *tret,      /* return array, 10 doubles, see below */

double *attr,      /* return array, 20 doubles, see below */

AS_BOOL backward,      /* TRUE, if backward search */

char *serr);     /* return error string */

 

If an occultation of any planet is wanted, call the function for all planets you want to consider and find the one with the smallest tret[1] (first contact). (If searching backward, find the one with the greatest tret[1]). For efficiency, set ifl |= SE_ECL_ONE_TRY. With this flag, only the next conjunction of the moon with the bodies is checked. If no occultation has been found, repeat the calculation with tstart = tstart + 20.

 

The function returns:

/* retflag    

         -1 (ERR) on error (e.g. if swe_calc() for sun or moon fails)

         0  (if no occultation/no eclipse found)