lib.orb

class lib.orb.Orb(orb, lon, lat, elev=False, neverup_delta=1e-05, backend='ephem')

Bases: object

Save an observers location and the name of a celestial body for future use

The Methods internally use a swappable backend for computation (currently only PyEphem is implemented, see _OrbBackend/_EphemBackend above).

All calculations are based on utc time. Changelog of pypehem: > Version 4.1.1 (2021 November 27) > When you provide PyEphem with a Python datetime that has a time zone attached, > PyEphem now detects the time zone and converts the date and time to UTC automatically.

To prevent side effects by this behaviour every datetime object given to any function in class Orb will be converted to utc. In case the given datetime is - naive (no timezone attached) –> the current timezone of SmartHomeNG will be used and the datetime will be converted to utc - has a timezone other than utc –> dt will be converted to utc - has utc timezone –> dt will not be changed and has always an offset of 0:00

TODO: It can be that datetime conversion from and to utc is ambigous: Imagine October 27th, in 2024, at 2:30 in the night. dt = datetime(2024, 10, 27, 2, 30, tzinfo=berlin) This is ambigous because it could well be summertime having still utc+2 hours or wintertime with utc+1 hours This ambiguity is not handled right now

aware_datetime_to_utc(aware_dt)

get_observer_and_orb()

Return a tuple of an instance of an observer with location information and a celestial body, as provided by the active backend. Both returned objects are uniquely created to prevent errors in computation.

Rückgabe:

tuple of observer and celestial body

midnight(doff=0, moff=0, dt=None)

Calculate the time of next antitransit starting with dt. If dt is None the the time of this function call will be used

Parameter:

• doff (float, optional) – degrees offset, defaults to 0

• moff (float, optional) – minutes offset, defaults to 0

• dt (datetime, optional) – datetime object to start calculation with, defaults to None

Rückgabe:

datetime of next antitransit

Rückgabetyp:

datetime

noon(doff=0, moff=0, dt=None)

calculate the time of next transit starting with dt. If dt is None the the time of this function call will be used

Parameter:

• doff (float, optional) – degrees offset, defaults to 0

• moff (float, optional) – minutes offset, defaults to 0

• dt (datetime, optional) – datetime object to start calculation with, defaults to None

Rückgabe:

datetime of next transit

Rückgabetyp:

datetime

pos(offset=None, degree=False, dt=None)

Calculates the position of either sun or moon :type offset: :param offset: given in minutes, shifts the time of calculation by some minutes back or forth :type degree: :param degree: if True: return the position of either sun or moon from the observer as degrees, otherwise as radians :type dt: :param dt: time for which the position needs to be calculated :return: a tuple with azimuth and elevation

rise(doff=0, moff=0, center=True, dt=None)

Computes the rise of either sun or moon :type doff: :param doff: degrees offset for the observers horizon :type moff: :param moff: minutes offset from time of rise (either before or after) :type center: :param center: if True then the centerpoint of either sun or moon will be considered to make the transit otherwise the upper limb will be considered :type dt: :param dt: start time for the search for a rise, if not given the current time will be used :return: datetime of next rising in utc timezone, or None if the body does not rise during this circuit

set(doff=0, moff=0, center=True, dt=None)

Computes the setting of either sun or moon :type doff: :param doff: degrees offset for the observers horizon :type moff: :param moff: minutes offset from time of setting (either before or after) :type center: :param center: if True then the centerpoint of either sun or moon will be considered to make the transit otherwise the upper limb will be considered :type dt: :param dt: start time for the search for a setting, if not given the current time will be used :return: datetime of next setting in utc timezone, or None if the body does not set during this circuit

unaware_datetime_to_utc(naive_dt)

utc_to_local(utc_dt)

lib.orb Backends Update

Die Bibliothek lib.orb kann intern mit verschiedenen Backends arbeiten:

• ephem (pyephem)

• skyfield

• skyfield mit Cache

ephem hat den Vorteil, dass es als native C-Bibliothek sehr schnell ist. Nachteilig ist, dass es auf manchen Plattformen keine fertigen Pakete gibt oder die Installation schwierig ist.

skyfield ist als reines Python-Modul trivial zu installieren, muss vor dem erstmaligen Start eine Datei (17 MB) herunterladen, die bis 2053 gültig bleibt. Die Berechnungen sind langsamer als ephem.

In der Variante von skyfield mit Cache werden alle Daten für ein Jahr auf einen Schlag berechnet und alle folgenden Abfragen, die in das Fenster der 365 Tage fallen, werden ohne erneute Berechnung zurückgegeben.

ephem ist pro Einzelabfrage mit Abstand am schnellsten (~70-100x schneller als ungecachted skyfield) - die Cache-Schicht gleicht das nur gegenüber skyfield selbst aus, nicht gegenüber ephem. Der Cache-Aufbau kostet konstant ~7ms, unabhängig von der Anzahl der Aufrufe, und amortisiert sich gegenüber ungecachtem skyfield bereits nach 3-4 Abfragen. Sequenzielle Abfragen (das reale Nutzungsmuster von Skytime, Tag fuer Tag vorwärts) profitieren deutlich stärker vom Cache als zufällige Abfragen, da letztere gelegentlich einen erneuten Cache-Aufbau auslösen.

Benchmark-Ergebnisse: lib.orb Backends (Berlin, 365-Tage-Fenster)

Aufrufe	Modus	ephem (ms)	skyfield (ms)	skyfield-cached Ø (ms)	Cache-Aufbau (ms)
10	zufällig	0,033	2,441	0,788	6,9
10	sequenziell	0,029	2,409	0,013	7,0
100	zufällig	0,027	1,952	0,149	7,1
100	sequenziell	0,025	1,889	0,010	6,8
1000	zufällig	0,025	1,863	0,039	6,8
1000	sequenziell	0,022	1,859	0,023	6,9

Werte = Durchschnitt pro Aufruf in Millisekunden außer „Cache-Aufbau“ = einmalige Kosten für die erste Abfrage

Die Backends können über den etc/smarthome.yaml-Parameter orb_backend: <Wert> konfiguriert werden. Gültige Werte sind „ephem“, „skyfield“ und „skyfield-cache“.