Programming interface to the Swiss Ephemeris

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)