4. Hetlib Python Interface¶

The module, hetlib, defines useful functions and the basic configuration information. The hetlib package imports the low level packages tcssubsystem.py and provides wrappers for functionality so it is not necceasary to explicitly import the th low level package. You only need to have the line

import hetlib

in your file to get the full functionality of these packages.

Contants defined in hetlib:

hetlib.named_route¶: The default URL for the Control System tcsnamed, defined as ‘tcp://192.168.66.99:30000‘

A number of site specific constants are defined:

hetlib.Latitude_deg¶: The latitude of the Het is 30.681436 degrees

hetlib.Latitude_rad¶: Defined as radians(Latitude_deg)

hetlib.LongitudeWest_deg¶: The longitude of the het is 104.014742 degrees west

hetlib.LongitudeWest_rad¶: Defined as radians(LongitudeWest_deg)

hetlib.LongitudeEast_deg¶: Defined as 360.0 - LongitudeWest_deg

hetlib.LongitudeEast_rad¶: Defined as radians(LongitudeEast_deg)

hetlib.Altitude_deg¶: The elevation alitude of the Het primary mirror is 55.055223 degrees

hetlib.Altitude_rad¶: Defined as radians(Altitude_deg)

hetlib.Height_meters¶: The height of the Het telescope center of the primary is 2003.0 meters

hetlib.Fs_meters¶: The Focal length of the Het primary mirror is 13.37884180 meters

hetlib.Fs_millimeters¶: Defined as Fs_meters * 1000.0

hetlib.het_P¶: Defined as cos(Altitude_rad) * cos(Latitude_rad) radians

hetlib.het_Q¶: Defined as sin(Altitude_rad) * sin(Latitude_rad) radians

hetlib.BetaLimit_deg¶: The angular limit for trajectories is 8.5 degrees

hetlib.BetaLimit_rad¶: Defined as radians(BetaLimit_deg)

4.1. Hetlib Python Modules¶

4.1.1. tcsutils.py¶

tcsutils contains the workhorse functions for your python scripts. The principal one for client programs is start_clients().

The tcsutils module provides the following constant.

tcsutils.named_route¶: The default URI for the tcs_named-label, defined as ‘tcp://192.168.66.99:30000‘

The following functions are defined:

tcsutils.start_clients(tcs, tracker, legacy, pas, pfip, apc, lrs2, vdas, named, verbose)[source]¶

Start one or a number of clients links. The default values for the system names in ``start_client()` are False. Set them to be true to create a handle (as described in tcssubsystem.py. The function returns a dictionary of handles to Control Systems.

client_dict = start_clients(tcs=True, virus=True)
tcsClient = client_dict['tcs']
virusClient = client_dict['virus']

4.1.2. hetutils.py¶

The hetutils.py package provides functions to do calculations specific to the Hobby Eberly Telescope at McDonald Observatory. These functions provide information about telescope pointing as well as tracker information.

hetutils.Att(az_deg, dec_deg)[source]¶: Calculate the total possible track time for a give azimuth and declination. Input arguments are in degrees. The function returns the track time in minutes or 0 if no trajectory is available.

hetutils.BestAzimuth(dec_deg)[source]¶: This function calculates the best azimuth for a given declination. The function returns an azimuth only on the east side. If you want the west azimuth, simply add 180 degrees to the return value. The input declination is in degrees, The return value is the azimuth in degrees or None is the declinination is not visible at HET.

hetutils.Ho(azimuth_deg)[source]¶: Calculate the telecentric hour angle for a given azimuth. Negative values are east hour angles. The input azimuth is in degrees. Returns the hour angle in degrees.

hetutils.Pa(azimuth_deg)[source]¶: Calculate the zero-crossing paralactic angle as a function of azimuth. The input azimuth is in degrees. Returns the paralactic angle in degrees.

hetutils.Tde(azimuth_deg)[source]¶: Calculate the telecentric declination as a function of azimuth. The input azimuth is in degrees. Returns the declination in degrees or None if the input is not between 0 <= az < 360.0

hetutils.clipToCircle_deg(x)[source]¶

Return the value (dX mod 360). This has the result of clipping the value between 0 <= dR < 360.0.

Inputs dX - the value you want clipped

Outputs none

Return (dX mod 360)

hetutils.clipToCircle_rad(x)[source]¶

Return the value (dX mod 2PI). This has the result of clipping the value between 0 <= dR < 2PI.

Inputs dX - the value you want clipped

Outputs none

Return (dX mod 2PI)

hetutils.degrees_to_hours(deg)[source]¶: Convert decimal degrees to decimal hours.

hetutils.hours_to_degrees(hr)[source]¶: Convert decimal hours to decimal degrees.

hetutils.hours_to_radians(hr)[source]¶: Convert decimal hours to decimal radians.

hetutils.modulo(x, y)[source]¶

A general purpose modulo (x mod y) function.

Definition of ‘mod’ x mod y = x - y * floor( x/y) for y != 0 x mod 0 = x

if 0 < y then 0 <= (x mod y) < y if 0 > y then 0 >= (x mod y) > y

hetutils.radians_to_hours(rad)[source]¶: Convert decimal radians to decimal hours.

A number of constants are defined in hetutils and are duplicated in hetlib. Their use from hetutils is deprecated and they will be removed from hetutils at a future date.

Latitude_deg = 30.681436

Latitude_rad = radians(Latitude_deg)

LongitudeWest_deg = 104.014742

LongitudeWest_rad = radians(LongitudeWest_deg)

LongitudeEast_deg = 360.0 - LongitudeWest_deg

LongitudeEast_rad = radians(LongitudeEast_deg)

Altitude_deg = 55.055223

Altitude_rad = radians(Altitude_deg)

Height_meters = 2003.0

Fs_meters = 13.37884180

Fs_millimeters = Fs_meters * 1000.0

het_P = cos(Altitude_rad) * cos(Latitude_rad) # radians

het_Q = sin(Altitude_rad) * sin(Latitude_rad) # radians

# limit on the total angular travel of the tracker

BetaLimit_deg = 8.5

BetaLimit_rad = radians(BetaLimit_deg)

4.1.3. hetTime.py¶

Useful (or not) tools for dealing with Het time in its different formations.

Some definitions:

unix time – the number of seconds since the epoch. The epoch is

defined as 00:00:00 UTC, January 1, 1970. This number may be a floating point value with factional seconds.

index time – The tracker’s definition of the time of day. Index time

is reset to 0.0 at 1800 UT hours or 12 noon CST (1300 CDT). There is no information contained here that might indicate which day this index time occurred on. This number may be a floating point value.

0000 hours UT == 00000 secs UT == 0600 hours index == 21600 seconds index

0600 hours UT == 21600 secs UT == 1200 hours index == 43200 seconds index

1200 hours UT == 43200 secs UT == 1800 hours index == 64800 seconds index

1800 hours UT == 64800 secs UT == 2400 hours index == 86400 seconds index (0000)

2400 hours UT == 86400 secs UT == 0600 hours index == 21600 seconds index

ISO time – an ISO-8601 string of the format YYYY-MM-DDThh:mm:ss.mmmmmm, where YYYY is

the four digit year, MM is the two digit month (starts at 01), DD is the two digit day (starts at 01), hh is the two digit hour, mm is the two digit minute, ss is the two digit second, and mmmmmm is the fractional part of the second.

datetime – a python datetime.datetime() object. This is the intermediate

object through which the time conversion routines work. It is also a value which Python can work with. See the documentation for the datetime package within Python.

Note that the timezone information in the datetime.datetime() object is explicitly set to None and the assumption is that all times are UT. This may change in the future if we need to compare local time with HET times. In this case the timezone will be explicitly set to UTC.

Future Plans.

Convert to object hetTime(), subclass of datetime, which takes an index time, unix time, datetime object or ISO string at instantion. added functions hetTime.indexTime(), hetTime.unixTime(), hetTime.ISOtime() to return time in different format. ISOtime and unixTime contain year/mon/day information but index time does not. Use the current year/mon/day unless there is a specified year/mon/day at instantation.

e.g. hetTime(index|unix|iso, year=now.year, mon=year.mon, day=now.day)

The following functions are defined:

hetTime.DT_To_ISO(dt)[source]¶

Convert a datatime.datetime() object to a ISO time string.

input: datetime object

output: ISO-8601 format string

hetTime.DT_To_Index(dt)[source]¶

Convert datetime.datetime() to an index time.

input: datetime.datetime()

output: float

Note that we lose the date information from the datetime() object.

hetTime.DT_To_Unix(dt)[source]¶

Convert a datetime.datetime() object to a Unix time value.

input: datetime.datetime()

output: Unix time value

hetTime.ISO_To_DT(isoStr)[source]¶

Convert an ISO-8601 time string to a datetime.datetime() object.

input: ISO-8601 time string

output: datetime object

hetTime.ISO_To_Index(isoStr)[source]¶

Convert a ISO string to an Index time.

input: ISO-8601 format string

output: Index time

Note that we lose the date information from the ISO string.

hetTime.ISO_To_Unix(isoStr)[source]¶

Convert an ISO time string to a Unix time value.

input: ISO-8601 format string

output: Unix time value

hetTime.Index_To_DT(ind)[source]¶

Convert an Index time into a datetime.datetime() object.

input: Index time

output: datetime.datetime()

Note that Index time has no date information

hetTime.Index_To_ISO(idxtime)[source]¶

Convert an Index time to a ISO time string.

input: Index time

output: ISO-8601 format string

Note that Index time has no date information

hetTime.Index_To_Unix(idxtime)[source]¶

Convert an Index time to a Unix time value

input: Index time

output: Unix time value

Note that Index time has no date information

hetTime.Unix_To_DT(utime)[source]¶

Convert a Unix time value to a datatime.datetime) object. This function duplicates datetime.fromtimestamp() and is included only for consistence with the other time functions.

input: Unix time value

output: datetime.datetime()

hetTime.Unix_To_ISO(utime)[source]¶

Convert a Unix time value to an ISO time string.

input: Unix time value

output: ISO-8601 format string

hetTime.Unix_To_Index(utime)[source]¶

Convert a Unix time value to an Index time.

input: datetime object

output: ISO-8601 format string

Note that we lose the date information from the Unix time value.

The commands available are shown in the following matrix

From/To	DT	ISO	Index	Unix
DT		DT_To_ISO()	DT_To_Index()	DT_To_Unix()
ISO	ISO_To_DT()		ISO_To_Index()	ISO_To_Unix()
Index	Index_To_DT()	Index_To_ISO()		Index_To_Unix()
Unix	Unix_To_DT()	Unix_To_ISO()	Unix_To_Index()

4.1.4. Points.py¶

This file contains the list Points which consists of of 97 dictionary defining points in ITF coordinates that lie on the focal sphere. The dictionarys are defined as

Points = [
{'Index':  1, 
 'X':  790.877147,
 'Y': 1812.127196, 
 'Z':  146.930811, 
 'Theta': 7.799501970, 
 'Phi':   3.421093209, 
 'Rho':   0.000000000, 
 'Beta':  8.500000000},
 ...
 ...
 ...
 {'Index': 97,
  'X': -790.877147,
  'Y':-1812.127196,
  'Z':  146.930811,
  'Theta': -7.799501970,
  'Phi':   -3.421093209,
  'Rho':    0.000000000, '
  'Beta':   8.500000000},
 ]

The parameters X, Y, and Z are given in millimeter while Theta, Phi, Rho, and Beta are given in units of degrees

These points are primarily used in the program mountTest (DEFINE LINK HERE) but can be used anywhere. The points were calculated using a tracker sphere of ????? mm.

There are a number of pre-defined lists of points given in the dictionary knownLists. The dictionary contains keys of the form 'List_97' and the value of such a key is a list of the form [1,2,3,4,5,..95,96,97]. Note that the number given in the list is one more than the entry value in Points.

‘List_97’ is the array of all points,