Skip to main content

ALPACAS

ALPACAS (A Library for Plotting And Computing All kinds of Sundials) is a Python library for sundials. As the name suggests, it possesses two main functionalities. On the one hand, one can use ALPACAS to plot custom-made sundials, without any expert knowledge. These sundial plots can be printed out and e.g. glued or otherwise fixated on a piece of wood or cardboard. Then one only needs to add a small vertical stick (e.g. a nail) serving as nodus and has created a fully functional sundial! This sundial can be customized to indicate the time in several different systems, as well as the date.

On the other hand, for experts ALPACAS provides many functions for performing sundial-related computations. It allows to compute the sun position in local coordinates as function of latitude, declination and hour angle, the position of the shadow cast by a nodus onto a sundial, the angles of the hour lines cast by a polar gnomon, the hour angle of sunset/sunrise and some more quantities. Furthermore, it has a celestial mechanics module that provides the declination and equation of time for a given date (taking as input only earth's orbital parameters, which are provided in a module with constants).

ALPACAS supports sundials of the following orientations (i.e. orientation of the dial plane): horizontal, vertical, polar, equatorial and of arbitrary orientation provided by inclination angles.

Requirements and Installation

ALPACAS needs only the numpy and matplotlib packages. Install with

pip install alpacas

or with

pip install git+https://github.com/philipp-heinen/ALPACAS.git

Sundial plotting functionalities

The sundial plotting functionalities are contained in the core module sundial. First import this module:

import alpacas.sundial as snd

Now we create a Sundial object:

sundial = snd.Sundial(latitude=50.733, longitude=7.104, orientation="horizontal")

The latitude and longitude of the position where the sundial will be located must be provided in degrees, with latitudes in the northern hemisphere counting as positive and in the southern hemisphere as negative, as well as longitudes east of Greenwich counted as positive and west of it as negative. The orientation parameter (which defaults to "horizontal") determines the orientation of the sundial. The following options are available:

  • "horizontal" (the dial is oriented horizontally)
  • "vertical" (the dial is oriented vertically, facing exactly south (northern hemisphere)/north (southern hemisphere))
  • "polar" (the dial is oriented parallel to the polar axis)
  • "equatorial_upper_side" (the dial is oriented parallel to the equator plane, and located on the "upper" side)
  • "equatorial_lower_side" (the dial is oriented parallel to the equator plane, and located on the "lower" side)
  • [alpha, beta] (a list of two inclination angles of the dial plane provided in degrees)

A horizontal sundial has the advantage that it can display the time during the whole day, from sunrise to sunset. It is also easy to realize and fairly common. Vertical sundials are also very widespread as they can be realized on south-facing (southern hemisphere: north-facing) walls of buildings. The other types are much rarer and their implementation in ALPACAS is provided rather for experts.

First, we initialize the sundial plot:

sundial.init_dial_plot(xsize=10, ysize=10, cm_per_unit=2)

xsize and ysize determine the relative size of the plotted dial, where we set the height of the nodus to 1. In many cases, the default xsize=10 and ysize=10 is a good choice. cm_per_unit sets how the relative units in which the height of the nodus amounts to 1 translate into centimeters. This depends on how large one wants the sundial to be.

Now we can populate the sundial with different elements. For example, before adding any lines indicating time, it is useful to add a marker for where the nodus has to be located (by default, it is placed in the center of the plot).

sundial.add_nodus_pos(style={"color":"black", "ms":4})

The function (optionally) takes a style argument which must be provided as a dictionary setting color and markersize (ms) of the marker.

Next, we can add lines for indicating the time. For example, one of the most common times displayed on sundials is the apparent zone time, which deviates from the time displayed by clocks only by a few minutes (the equation of time). To add lines for apparent zone time, we can e.g. write:

sundial.add_apparent_zone_time(which="hourly", timezone=1, gnomon_type="nodus", 
                               style={"color":"blue", "lw":2, "linestyle": "-"}, 
                               which_labels="roman_numerals", 
                               labelstyle={"side":"left", "position":0.8, "position_type":"relative", "tightness":0.25, "fontsize":8, "color":"blue", "rotate": False})

which determines for which hours to draw lines. It can be "hourly", "half-hourly", "two-hourly" or a costum list of hours. The timezone parameter must be set to the difference of the zonal time from UTC time in hours. It can also be set to "closest", in which case the closest time zone to the provided longitude is taken. This can be wrong, however, for many places on earth. gnomon_type should be "nodus" if a vertical stick (a nodus) is used, and "polar" if a polar gnomon, i.e. a stick parallel to the polar axis, is used. which_labels can be set to "roman_numerals", "arabic_numerals", "no_labels" or a custom list of labels (whose length then must match with that of the list provided for which). style and labelstyle optionally provide the possibility to highly customize the appearance of the hour lines and their labels.

Other possible types of time systems supported by ALPACAS are

  • apparent solar time (time system in which the sun reaches the zenith at 12:00): add_apparent_solar_time
  • mean solar time (as mean zone time but not uniform across time zone): add_mean_solar_time
  • mean zone time (time indicated by clocks): add_mean_zonal_time
  • Babylonian hours (hours since sunrise): add_babylonian_hours
  • Italian hours (hours since sunset): add_italian_hours
  • temporal hours (period from sunset to sunrise is divided into twelve hours of equal length): add_temporal_hours

These functions are well documented within the ALPACAS code.

Additionally to the lines indicating the time of the day, we can also add curves indicating a particular date. For example, in order to have the equinoxes and solstices displayed, we can write

sundial.add_date_line(date="equinox", label="Equinox")
sundial.add_date_line(date="summer_solstice", label="Summer solstice")
sundial.add_date_line(date="winter_solstice", label="Winter solstice")

Dates other than the equinox and solstices can be provided as a [month, day]. If desired, the appearence of the line and the labels can again be customized by style and labelstyle arguments.

Sometimes it can be nice to add some text to the dial. This can be done as

sundial.add_text("South", 0, -4, fontsize=12, color="black")

where the position of the text is given in coordinates in relative units.

Finally, if we are happy with the sundial we have created, we can save it to a file:

sundial.save_dial_plot("Sundial.png", resolution=300)

The resolution is provided in dpi.

Computation functionalities

The computation functionalities are contained in the basic_functions module. For example, compute the position of the shadow a nodus casts onto a horizontal sundial at hour angle $\tau=20^\circ$, declination $\delta=10^\circ$ and latitude $\phi=50^\circ$,:

>>> import alpacas.basic_functions as bf
>>> import numpy as np
>>> bf.nodus_horizontal(tau=np.deg2rad(20), delta=np.deg2rad(10), phi=np.deg2rad(50))
array([0.46275402, 0.82060332])

Note that the functions in basic_functions in general take angles in radian and not in degree. The single functions provided are documented well within the code, so we refrain from a detailed documentation here.

The module celestial_mechanics provides essential functionalities such as the computation of the solar declination and equation of time for a specified date. For example, compute the declination in radian and the equation of time in minutes for 1 January:

>>> import alpacas.celestial_mechanics as cm
>>> cm.declination_date(month=1, day=1, leap_year=False)
-0.40081282075217145
>>> cm.equation_of_time_date(month=1, day=1, leap_year=False)
-3.6196350209321593

Also the functions in this module are documented well within the code.

Metadata

Release files for alpacas 0.0.1

For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.

Source distribution (sdist)

Source distribution for alpacas 0.0.1
File Size Uploaded Provenance Actions
alpacas-0.0.1.tar.gz 31.5 kB Without provenance Details for alpacas-0.0.1.tar.gz

Built distribution (wheel)

Table of built distributions (wheels) for alpacas 0.0.1
File Interpreter ABI Platform Actions
alpacas-0.0.1-py3-none-any.whl Python 3 none any Details for alpacas-0.0.1-py3-none-any.whl

Total release size: 61.7 kB

Release files / alpacas-0.0.1.tar.gz

Download URL alpacas-0.0.1.tar.gz
Size 31.5 kB
Tags Source
SHA-256 checksum
How to use checksums
8aa989f4ae6422524052394cd91d674b3ccfbc615752e1d855c6eac40758b277
BLAKE2b-256 checksum
How to use checksums
a728f6c956a38f77a18585c745ff35608712a7b75b3c6893ce01a9de51c184ca
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
No
Uploaded via twine/6.2.0 CPython/3.12.3

Release files / alpacas-0.0.1-py3-none-any.whl

Download URL alpacas-0.0.1-py3-none-any.whl
Size 30.3 kB
Tags Python 3
SHA-256 checksum
How to use checksums
58bf1c529695cb6aea7945775d8384e51ed2d5a41ba9247e71277e869e42b78a
BLAKE2b-256 checksum
How to use checksums
684a838c1fceff100282ba8a0bc252ff24e6e424fbf2f3b248302455a066f308
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
No
Uploaded via twine/6.2.0 CPython/3.12.3

Security for alpacas 0.0.1

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

No provenance found

None of the files in this release were uploaded with provenance metadata.

A note on package security

PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.

To learn more about protecting yourself from malicious actors, visit our package security documentation.

Release history Release notifications | RSS feed

This release

0.0.1 This release

2 release files No provenance

Anthropic, PBC Visionary sponsor Bloomberg Visionary sponsor Hudson River Trading Visionary sponsor Meta Visionary sponsor NVIDIA Visionary sponsor Microsoft Sustainability sponsor Depot Continuous Integration AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page