All calculations that depend on date and time change their behavior depending on the state of the USESYSTEMTIME variable. If USESYSTEMTIME is false (the default) the computer's clock is read just before its used, otherwise the local time variables (YEAR, MONTH, DAYOFMONTH, HOUR, MINUTE, and SECOND) are used. Also see the setdatetime, calcjuliandate, and calcdatetime commands.

Corrections to UTC time depend on the time zone and daylight savings time settings.

Below are commands that calculate various astronomical and other quantities:

setdatetime

Syntax: setdatetime

This sets the local time variables (YEAR, MONTH, DAYOFMONTH, HOUR, MINUTE, and SECOND) from the computer's clock, regardless of the value of the USESYSTEMTIME variable.

calcdatetime

Syntax: calcdatetime <utflag>

Converts the julian date in the variable JD to the time variables (YEAR, MONTH, DAYOFMONTH, HOUR, MINUTE, and SECOND). If utflag is omitted or "false" the result is in local time. If "true" it is in UT. The USESYSTEMTIME variable should be set of false if the new time variables are to be used by subsequent calculation commands.

calcjuliandate

Syntax: calcjuliandate <utflag>

Computes the julian date (set in the JD variable) from the time variables (YEAR, MONTH, DAYOFMONTH, HOUR, MINUTE, and SECOND). If 'utflag' is omitted or "false" the time variables are interpreted as being in local time. If "true" it they are interpreted as being in UT. If the USESYSTEMTIME variable is "true", local time variables are set to the computer's clock beforehand - this variable is ignored 'utflag' is "true".

calcheliocentricjuliandate

Syntax: calcheliocentricjuliandate

Computes the Heliocentric Julian Date (set in the HJD variable) from the current values of the Julian Date (JD) and RA and DEC variables. This small correction, up to plus or minus about 8 minutes, considers difference in light travel time for an object given the Earth's position in its orbit.  

radectoazalt

Syntax: radectoazalt

Converts right ascension and declination to altitude and azimuth using the current time and geographic location. The variables RA and DEC are used and the variables AZ and ALT are set. If REFRACTIONENABLED is true, the effects of atmospheric refraction are considered.

azalttoradec

Syntax: azalttoradec

Converts altitude and azimuth to right ascension and declination using the current time and geographic location. The variables AZ and ALT are used and the variables RA and DEC are set. If REFRACTIONENABLED is true, the effects of atmospheric refraction are considered.

sunradec

Syntax: sunradec

Computes the position of the Sun at the current time and sets the variables RA and DEC.

moonradec

Syntax: moonradec

Computes the position of the Moon at the current time and sets the variables RA and DEC. The following variables are also set:

  • ILLUMINATION - the Moon's illumination fraction (0 to 1)
  • MOONPHASE - the Moon's phase in degrees (0 is new, 180 is full, etc.)
  • PHASENAME - the textual name of the Moon's phase (eg. 'Waning Crescent")
  • AGE - the age of the Moon in days

planetradec

Syntax: planetradec planet_no

Computes the position of a planet at the current time and sets the variables RA and DEC. The planet is specified by "planet_no", a number from 0 to 7 representing the planets Mercury through Pluto in order from the Sun (excluding Earth).

orbitradec

Syntax: orbitradec orbitnumber

The “orbitnumber” specifies an orbit (1 is the first orbit) from the database of currently loaded orbits (see loadorbits command). The variables RA and DEC are set to the orbit's position at the current time. The variable ORBITMAG is set to the magnitude and the variable ORBITNAME is set to its full name. The variable ORBITERROR is set accordingly.

calchourangle

Syntax: calchourangle

Computes the hour angle (westward from the meridian) of the position specified by the variables RA and DEC at the current time and geographic location. The variable HOURANGLE is set.

calcra

Syntax: calcra

Computes the right ascension, at the current time and geographic location, from the hour angle (westward from the meridian) in the variable HOURANGLE and the declination in the variable DEC. The variable RA is set.

calcairmass

Syntax: calcairmass

Computes the current air mass of the position specified by the variables RA and DEC at the current time and geographic location. The variable AIRMASS is set. If the air mass refers to an altitude less than 5 degrees, then the result will always be -1.

azaltseparation

Syntax: azaltseparation az1 alt1 az2 alt2

Computes the distance, in degrees, between two angular azimuth and altitude positions identified as az1/alt1 and az2/alt2. It also computes the initial position angle from position 1 to 2 counter-clockwise from north. The variables SEPARATION and POSITIONANGLE are set.

radecseparation

Syntax: radecseparation ra1 dec1 ra2 dec2

Computes the distance in degrees between two equatorial right ascension and declination positions identified as ra1/dec1 and ra2/dec2. It also computes the initial position angle from position 1 to 2 counter-clockwise from north. The variables SEPARATION and POSITIONANGLE are set.

precessfrom2000

Syntax: precessfrom2000

Precesses the position specified by the variables RA and DEC from epoch J2000 to the current date.

precessto2000

Syntax: precessto2000

Precesses the position specified by the variables RA and DEC from the current date to epoch J2000.

calcdomesyncazimuth

Syntax: calcdomesyncazimuth

This command uses the values in the SIDEOFPIER, HOURANGLE, and DEC variables (a telescope position) to compute an azimuth to move the dome. It reads a tab-delimited text file called "misc\domeaz.txt" which provides a table of azimuths for a grid of hour angle and declinations for both sides of the pier. The azimuths in the text file need to be measured for each dome and telescope geometry. A 2-D interpolation of the table is performed to calculate the correct azimuth which is saved in the variable DOMESYNCAZIMUTH. The variable TELESCOPEERROR is "true" if an error occurs.

This routine was developed because the facilities of the ASCOM POTH and ASCOM Dome Control do not always calculate the correct dome azimuth!

Notes:

  • The DEC is not precessed to current date, but this error would be very small.
  • If the mount is not a german equatorial and SIDEOFPIER is not used, set the same table of azimuths for both sides of the pier.

A sample domeaz.txt file is below. Note that the hour angle lines need to in physical hour angle order (eg. 12 to 0 then 23 to 13):

East Side Looking West

9

Decs        80        70        60        50        40        30        20        0        -20

10

11        342        337        334        334        334        334        334        334        334

9        333        328        319        315        310        310        310        310        310

7        337        319        310        301        292        285        279        279        279

5        346        324        306        288        274        265        256        243        243

4        355        333        301        283        265        252        243        229        229

3        6        348        319        283        256        243        231        216        205

2        13        9        346        292        230        216        207        200        193

1        18        27        36        90        167        180        180        177        177

0        22        31        40        81        117        135        148        157        162

23        27        36        49        76        96        112        128        139        150

West Side Looking East

9

Decs        80        70        60        50        40        30        20        0        -20

10

1        337        328        315        288        265        247        234        214        211

0        339        333        324        292        252        220        207        200        193

23        342        342        337        324        189        180        180        175        180

22        346        355        13        58        117        139        146        157        164

21        353        13        40        72        94        117        126        139        150

20        0        25        45        67        85        94        103        125        125

19        13        31        49        67        76        85        103        112        112

17        22        25        40        58        63        72        79        79        79

15        22        31        40        45        49        49        49        49        49

13        22        22        22        27        27        27        27        27        27


calcphase

Syntax: calcphase jd epoch period adjustment tolerance

This command calculates the phase (0 to 1) for events periodic in nature. This is intended to be used to time the observations of objects such as variable stars and exoplanets.

The input parameters are:

  • jd - the Julian Date for which the phase is calculated
  • epoch - a reference Julian Date where the phase is 0
  • period - the period in days (up to 10 years)
  • adjustment - an adjustment to the epoch, in minutes (-1440 to 1440). This allows the phase to be shifted forward or backward up to one day. For example: the time of interest for an eclipsing binary star might begin an hour before the calculated phase (time of minimum).An 'adjustment' of -60 will give a phase of 0 just as the eclipse starts.
  • tolerance - INPHASE variable is set to true when "jd" is within the specified number of minutes (before or after). The valid "tolerance" range is 0 to 1440 minutes.

The variable PHASE is set to the calculated phase (0 is in phase, 0.99 is very close to being in phase before being in phase, 0.01 is very close to being in phase after being in phase , 0.5 is the most out of phase).

Note that both "epoch" and "jd" need to be set in the same time system, typically the Julian Date (based on UT time) or Heliocentric Julian Date (which is corrected to the centre of the Sun). If these two Julian Dates are mixed,

phase errors of up to about 8 minutes can occur (this is because of the variable light travel time given the Earth's orbit around the Sun).  

offsetradec

Syntax: offsetradec distanceew distancens

This command offsets the position in the variables RA and DEC by the specified east-west and north-south distance angles.

The input parameters are:

  • distanceew - the east/west offset angle in degrees (from -180 to +180). Positive angles are eastward and negative numbers are westward.
  • distancens - the north/south offset angle in degrees (from -180 to +180). Positive angles are northward and negative numbers are southward.

This commands first calculates the combined distance and angle (assuming 2 dimensional geometry). It uses these values to then compute the offset position. Because the angle used is the initial angle of a great circle path through the celestial sphere, the larger this angle is, the more inaccurate the result will be.

offsetradecangle

Syntax: offsetradec distance direction

This command offsets the position in the variables RA and DEC by the specified angular distance and direction.

The input parameters are:

  • distance - the offset angle in degrees (from 0 to 180).
  • direction - the direction angle of the offset in degrees (0 to 360) counter-clockwise from north.

Because the direction angle used is the initial angle of a great circle path around the celestial sphere, the larger this angle is, the more inaccurate the result will be.

intensitytomagnitude

Syntax: intensitytomagnitude intensity

This command converts a linear intensity (flux) value (usually originating from the photometry command) to a logarithmic magnitude based on the reference values in variables PHOTOREFMAG and PHOTOREFINTENSITY.  If 'intensity' is less than or equal to 0 (no flux), the result is set to 30 (very faint!). The result is stored in the PHOTOMAG variable.

calcfixedrisesettransit

Syntax: calcfixerisesettransit <size>

Computes the rise, set and transit times of the object at the position in variables RA and DEC at the current time. If the variable REFRACTIONENABLED is true, the effects of atmospheric refraction are considered. If "size" is omitted or 0, the rise and set times are for the centre of the object. If "size" is set to the size of the object in degrees, the rise and set times are for the upper limb of the object.

The following variables are set:

  • RSTFLAGS - 0 = object both rises and sets, 1 = object is always above the horizon, 2 = object never rises above the horizon
  • RISETIME - the rise time in hours (local time)
  • SETTIME - the set time in hours (local time)
  • TRANSITTIME - the transit time in hours (local time)

calcmovingrisesettransit

Syntax: calcmovingrisesettransit planet_no <size>

Computes the rise, set and transit times of a planet, the Sun, or the Moon. The planet is specified by "planet_no", as a number from 0 to 7 representing the planets Mercury through Pluto in order from the Sun (excluding Earth), 8 for the Moon, and 9 for the Sun. If the variable REFRACTIONENABLED is true, the effects of atmospheric refraction are considered. If "size" is omitted or 0, the rise and set times are for the centre of the object. If "size" is set to the size of the object in degrees, the rise and set times are for the upper limb of the object. To calculate twilight times set "planet_no" to 9, set variable REFRACTIONENABLED to "false", and set the "size" to twice the sun's altitude below the horizon (for example, a size of 12 calculates the times of civil twilight or when the Sun is 6 degrees below the horizon).

The following variables are set:

  • RSTFLAGS - 0 = object both rises and sets, 1 = object is always above the horizon, 2 = object never rises above the horizon, 3 = the Moon does not rise today, 4 = The Moon does not set today
  • RISETIME - the rise time in hours (local time)
  • SETTIME - the set time in hours (local time)
  • TRANSITTIME - the transit time in hours (local time). This value is not set if the object is the Moon.