Command-Line Applications

heniautos

The heniautos command-line application gives you access to most of the calendar calculations described in Festival Calendars and Athenian Conciliar Calendars. There are quite a few options. Use -h to see them in the console:

$ heniautos -h
usage: heniautos [-h] [-c {argos,athens,delos,delphi,sparta,corinth,generic}]
             [--month {1,2,3,4,5,6,7,8,9,10,11,12,13}] [--day DAY]
             [--doy DOY] [-m] [-y]
             [--intercalate {1,2,3,4,5,6,7,8,9,10,11,12}] [-C] [--arabic]
             [--prytany {I,II,III,IV,V,VI,VII,VIII,IX,X,XI,XII,XIII}]
             [--as-ce] [-a] [-g] [--new-moons]
             [--summer-solstice] [--spring-equinox] [--autumn-equinox]
             [--winter-solstice] [--gmt] [-v N] [-s N]
             [--calendar-start {summer,fall,winter,spring}] [-E] [-e FILE]
             [--julian] [--julian-solar-events] [--julian-new-moons]
             [--tab] [--version]
             start_year [end_year]

Ancient Athenian calendar generator

positional arguments:
  start_year
  end_year

optional arguments:
  -h, --help            show this help message and exit
  -c {argos,athens,delos,delphi,sparta,corinth,generic}, --calendar {argos,athens,delos,delphi,sparta,corinth,generic}
                    Festival calendar to display
  --month {1,2,3,4,5,6,7,8,9,10,11,12,13}
                    Only show requested month
  --day DAY             Only show selected day
  --doy DOY             Only show selected day of year
  -m, --month-summary
  -y, --year-summary
  --intercalate {1,2,3,4,5,6,7,8,9,10,11,12}
                    Month after which to intercalate
  -C, --conciliar       Output conciliar calendar (prytanies)
  --arabic              Display prytany numbers as Arabic rather than Roman
                        numerals
  --prytany {I,II,III,IV,V,VI,VII,VIII,IX,X,XI,XII,XIII}
                    Only show selected prytany
  --as-ce               Treat dates as CE rather than BCE
  -a, --abbreviations   Abbreviate month names
  -g, --greek-names     Use Greek names for months
  --new-moons           Only list times of astronomical new moons
  --full-moons          Only list times of astronomical full moons
  --summer-solstice     Only list dates of solstices
  --spring-equinox      Only list dates of spring equinox
  --autumn-equinox      Only list dates of autumn equinox
  --winter-solstice     Only list dates of winter solstice
  --gmt                 Format times as GMT (rather than EET)
  -v N, --visibility-offset N
                        Offset for determining date of new moon. N days after
                        astronomical conjunction(default: 1)
  -s N, --solar-offset N
                        Offset for determining the date of solstices and
                        equinoxes
  --calendar-start {summer,fall,winter,spring}
                        Season for beginning of the year (with -c generic,
                        default: summer
  -E, --use-ephemeris   Use ephemeris for data
  -e FILE, --ephemeris FILE
                        Use existing ephemeris FILE (if it cannot
                        automatically be found)
  --julian              Just output Julian calendar dates
  --julian-solar-events
                        Include solstices and equinoxes in Julian calendar
                        output
  --julian-new-moons    Include new moons in Julian calendar output
  --tab                 Output in tab-delimited format
  --version             Print version and exit

Basic Usage

Athenian Festival Calendar

The simplest use is provide a single year. This will be interpreted as a year BCE, and heniautos will output a festival calendar for the year (many lines not shown):

$ heniautos 400
     Year     |        Month          | Day |      Start      | DOY
--------------|-----------------------|-----|-----------------|-----
BCE 400/399   | Hekatombaiṓn          |   1 | BCE 0400-Jul-22 |   1
BCE 400/399   | Hekatombaiṓn          |   2 | BCE 0400-Jul-23 |   2
BCE 400/399   | Hekatombaiṓn          |   3 | BCE 0400-Jul-24 |   3
BCE 400/399   | Hekatombaiṓn          |   4 | BCE 0400-Jul-25 |   4
...
BCE 400/399   | Skirophoriṓn          |  27 | BCE 0399-Jul-08 | 352
BCE 400/399   | Skirophoriṓn          |  28 | BCE 0399-Jul-09 | 353
BCE 400/399   | Skirophoriṓn          |  29 | BCE 0399-Jul-10 | 354

The year column shows the Greek year, which probably spans two Julian years. The start column is the proleptic Julian date (for BCE) or Gregorian date (for CE) of the Greek date. DOY is the day of the year.

Use the -m switch to summarize by month:

$ heniautos 400 -m
     Year     |        Month          |      Start      | Days
--------------|-----------------------|-----------------|------
BCE 400/399   | Hekatombaiṓn          | BCE 0400-Jul-22 |   29
BCE 400/399   | Metageitniṓn          | BCE 0400-Aug-20 |   30
BCE 400/399   | Boēdromiṓn            | BCE 0400-Sep-19 |   29
BCE 400/399   | Puanopsiṓn            | BCE 0400-Oct-18 |   30
BCE 400/399   | Maimaktēriṓn          | BCE 0400-Nov-17 |   30
BCE 400/399   | Posideiṓn             | BCE 0400-Dec-17 |   30
BCE 400/399   | Gamēliṓn              | BCE 0399-Jan-16 |   30
BCE 400/399   | Anthestēriṓn          | BCE 0399-Feb-15 |   29
BCE 400/399   | Elaphēboliṓn          | BCE 0399-Mar-16 |   29
BCE 400/399   | Mounukhiṓn            | BCE 0399-Apr-14 |   30
BCE 400/399   | Thargēliṓn            | BCE 0399-May-14 |   29
BCE 400/399   | Skirophoriṓn          | BCE 0399-Jun-12 |   29

Instead of the DOY column, the month summary shows the length of the month under Days.

Or -y to summarize by year:

$ heniautos 400 -y
     Year     | Y |      Start      | Days
--------------|---|-----------------|------
BCE 400/399   | O | BCE 0400-Jul-22 |  354

The Y column indicates whether the year is ordinary (O) or intercalary (I).

You can provide two years to see a calendar spanning the full range of years given. This is easiest to illustrate in the year summary:

$ heniautos 400 395 -y
     Year     | Y |      Start      | Days
--------------|---|-----------------|------
BCE 400/399   | O | BCE 0400-Jul-22 |  354
BCE 399/398   | O | BCE 0399-Jul-11 |  355
BCE 398/397   | I | BCE 0398-Jul-01 |  384
BCE 397/396   | O | BCE 0397-Jul-19 |  355
BCE 396/395   | I | BCE 0396-Jul-09 |  383
BCE 395/394   | O | BCE 0395-Jul-27 |  354

With --as-ce, the year or years will be interpreted as CE. With this you can generate a calendar for a modern year:

$ heniautos 2023 -m --as-ce
     Year     |        Month          |      Start      | Days
--------------|-----------------------|-----------------|------
 CE 2023/2024 | Hekatombaiṓn          |  CE 2023-Jul-18 |   30
 CE 2023/2024 | Metageitniṓn          |  CE 2023-Aug-17 |   30
 CE 2023/2024 | Boēdromiṓn            |  CE 2023-Sep-16 |   29
 CE 2023/2024 | Puanopsiṓn            |  CE 2023-Oct-15 |   30
 CE 2023/2024 | Maimaktēriṓn          |  CE 2023-Nov-14 |   29
 CE 2023/2024 | Posideiṓn             |  CE 2023-Dec-13 |   30
 CE 2023/2024 | Gamēliṓn              |  CE 2024-Jan-12 |   29
 CE 2023/2024 | Anthestēriṓn          |  CE 2024-Feb-10 |   30
 CE 2023/2024 | Elaphēboliṓn          |  CE 2024-Mar-11 |   29
 CE 2023/2024 | Mounukhiṓn            |  CE 2024-Apr-09 |   30
 CE 2023/2024 | Thargēliṓn            |  CE 2024-May-09 |   29
 CE 2023/2024 | Skirophoriṓn          |  CE 2024-Jun-07 |   29

Use -a to show the month names as abbreviations:

$ heniautos 400 -m -a
     Year     |        Month          |      Start      | Days
--------------|-----------------------|-----------------|------
BCE 400/399   | Hek                   | BCE 0400-Jul-22 |   29
BCE 400/399   | Met                   | BCE 0400-Aug-20 |   30
BCE 400/399   | Boe                   | BCE 0400-Sep-19 |   29
...

And -g to show them in Greek:

$ heniautos 400 -m -g
     Year     |        Month          |      Start      | Days
--------------|-----------------------|-----------------|------
BCE 400/399   | Ἑκατομβαιών           | BCE 0400-Jul-22 |   29
BCE 400/399   | Μεταγειτνιών          | BCE 0400-Aug-20 |   30
BCE 400/399   | Βοηδρομιών            | BCE 0400-Sep-19 |   29
...

Importing into Spreadsheets

Anything can be output with tab-delimites columns by using --tab:

$ heniautos 400 395 -y --tab
"BCE 400/399"       "O"     "BCE 0400-Jul-22"       354
"BCE 399/398"       "O"     "BCE 0399-Jul-11"       355
"BCE 398/397"       "I"     "BCE 0398-Jul-01"       384
"BCE 397/396"       "O"     "BCE 0397-Jul-19"       355
"BCE 396/395"       "I"     "BCE 0396-Jul-09"       383
"BCE 395/394"       "O"     "BCE 0395-Jul-27"       354

This is useful for importing into spreadsheets. You can either save the output to a file, that you can open or import into a spreadsheet

$ heniautos 400 395 -y --tab > 400_to_395.tsc

Or you can send it to the clipboard so you can then just paste it in. On a Mac you can do this with pbcopy:

$ heniautos 400 395 -y --tab | pbcopy

Intercalations

Intercalations are handled automatically, and Posideiṓn is intercalated by default:

$ heniautos 401 -m
     Year     |        Month          |      Start      | Days
--------------|-----------------------|-----------------|------
BCE 401/400   | Hekatombaiṓn          | BCE 0401-Jul-03 |   29
BCE 401/400   | Metageitniṓn          | BCE 0401-Aug-01 |   30
BCE 401/400   | Boēdromiṓn            | BCE 0401-Aug-31 |   30
BCE 401/400   | Puanopsiṓn            | BCE 0401-Sep-30 |   30
BCE 401/400   | Maimaktēriṓn          | BCE 0401-Oct-30 |   29
BCE 401/400   | Posideiṓn             | BCE 0401-Nov-28 |   30
BCE 401/400   | Posideiṓn hústeros    | BCE 0401-Dec-28 |   30
BCE 401/400   | Gamēliṓn              | BCE 0400-Jan-27 |   29
BCE 401/400   | Anthestēriṓn          | BCE 0400-Feb-25 |   30
BCE 401/400   | Elaphēboliṓn          | BCE 0400-Mar-27 |   29
BCE 401/400   | Mounukhiṓn            | BCE 0400-Apr-25 |   29
BCE 401/400   | Thargēliṓn            | BCE 0400-May-24 |   29
BCE 401/400   | Skirophoriṓn          | BCE 0400-Jun-22 |   30

To choose another month for intercalation, use --intercalate with the number of the desired month. For instance, 8 for Anthestēriṓn:

$ heniautos 401 -m --intercalate 8
     Year     |        Month          |      Start      | Days
--------------|-----------------------|-----------------|------
BCE 401/400   | Hekatombaiṓn          | BCE 0401-Jul-03 |   29
BCE 401/400   | Metageitniṓn          | BCE 0401-Aug-01 |   30
BCE 401/400   | Boēdromiṓn            | BCE 0401-Aug-31 |   30
BCE 401/400   | Puanopsiṓn            | BCE 0401-Sep-30 |   30
BCE 401/400   | Maimaktēriṓn          | BCE 0401-Oct-30 |   29
BCE 401/400   | Posideiṓn             | BCE 0401-Nov-28 |   30
BCE 401/400   | Gamēliṓn              | BCE 0401-Dec-28 |   30
BCE 401/400   | Anthestēriṓn          | BCE 0400-Jan-27 |   29
BCE 401/400   | Anthestēriṓn hústeros | BCE 0400-Feb-25 |   30
BCE 401/400   | Elaphēboliṓn          | BCE 0400-Mar-27 |   29
BCE 401/400   | Mounukhiṓn            | BCE 0400-Apr-25 |   29
BCE 401/400   | Thargēliṓn            | BCE 0400-May-24 |   29
BCE 401/400   | Skirophoriṓn          | BCE 0400-Jun-22 |   30

Athenian Conciliar Calendar

Show the Athenian concilar calendar with -C

$ heniautos 400 -m -C
     Year     |        Prytany        |      Start      | Days
--------------|-----------------------|-----------------|------
BCE 400/399   | I                     | BCE 0400-Jul-15 |   37
BCE 400/399   | II                    | BCE 0400-Aug-21 |   37
BCE 400/399   | III                   | BCE 0400-Sep-27 |   37
BCE 400/399   | IV                    | BCE 0400-Nov-03 |   37
BCE 400/399   | V                     | BCE 0400-Dec-10 |   37
BCE 400/399   | VI                    | BCE 0399-Jan-16 |   37
BCE 400/399   | VII                   | BCE 0399-Feb-22 |   36
BCE 400/399   | VIII                  | BCE 0399-Mar-30 |   36
BCE 400/399   | IX                    | BCE 0399-May-05 |   36
BCE 400/399   | X                     | BCE 0399-Jun-10 |   36

The number of prytanies will be based on the year as described in Types of Conciliar Calendars.

If you want the prytanies numbered with Arabic rather than Roman numerals, use the --arabic switch.

Other Calendars

You can see festival calendars from a few other Greek cities besides Athens with -c:

$ heniautos 400 -m -c corinth
     Year     |        Month          |      Start      | Days
--------------|-----------------------|-----------------|------
BCE 400/399   | Phoinikaîos           | BCE 0400-Sep-19 |   29
BCE 400/399   | Kráneios              | BCE 0400-Oct-18 |   30
BCE 400/399   | Lanotropíos           | BCE 0400-Nov-17 |   30
BCE 400/399   | Makhaneús             | BCE 0400-Dec-17 |   30
BCE 400/399   | Dōdekateús            | BCE 0399-Jan-16 |   30
BCE 400/399   | Εúkleios              | BCE 0399-Feb-15 |   29
BCE 400/399   | Artemísios            | BCE 0399-Mar-16 |   29
BCE 400/399   | Psudreús              | BCE 0399-Apr-14 |   30
BCE 400/399   | Gameílios             | BCE 0399-May-14 |   29
BCE 400/399   | Agriánios             | BCE 0399-Jun-12 |   29
BCE 400/399   | Pánamos               | BCE 0399-Jul-11 |   30
BCE 400/399   | Apellaîos             | BCE 0399-Aug-10 |   29

All the options shown under Athenian Festival Calendar work with these calendars.

Generic Calendar

Calendars from various Greek cities differ not only in the names of their months but also in when they start, which can be immediately before or after any any solstice ot equinox. For example, the Athenian calendar begins just after the summer solstice, the Corinthian just before the autumn equinox.

You can generate a “generic” calendar that simple has numbered months. By default this will start after the summer solstice (like the Athenian calendar), but you can use --calendar-start to choose another season. For example, this creates a “generic” calendar that starts after the spring equinox:

$ heniautos 400 -m -c generic --calendar-start spring
     Year     |        Month          |      Start      | Days
--------------|-----------------------|-----------------|------
BCE 400/399   | 1                     | BCE 0400-Mar-27 |   29
BCE 400/399   | 2                     | BCE 0400-Apr-25 |   29
BCE 400/399   | 3                     | BCE 0400-May-24 |   29
BCE 400/399   | 4                     | BCE 0400-Jun-22 |   30
BCE 400/399   | 5                     | BCE 0400-Jul-22 |   29
BCE 400/399   | 6                     | BCE 0400-Aug-20 |   30
BCE 400/399   | 6 hústeros            | BCE 0400-Sep-19 |   29
BCE 400/399   | 7                     | BCE 0400-Oct-18 |   30
BCE 400/399   | 8                     | BCE 0400-Nov-17 |   30
BCE 400/399   | 9                     | BCE 0400-Dec-17 |   30
BCE 400/399   | 10                    | BCE 0399-Jan-16 |   30
BCE 400/399   | 11                    | BCE 0399-Feb-15 |   29
BCE 400/399   | 12                    | BCE 0399-Mar-16 |   29

Note

The Spartan calendar is a special case of the generic calendar. Because we do not know the names of all the months or their order, Spartan months are numbered.

Other Astronomical Data

Julian Years

The --julian option will output a Julian calendar for the year or years requested. The first column is the Julian Day Number.

$ heniautos 400 --julian
1575324|BCE 0400-Jan-01
1575325|BCE 0400-Jan-02
1575326|BCE 0400-Jan-03
...
1575686|BCE 0400-Dec-29
1575687|BCE 0400-Dec-30
1575688|BCE 0400-Dec-31

Note

This will actually output a Gregorian calendar for years forllowing the Gregorian reform

With --julian-solar-events and/or --julian-new-moons, columns will be added for solstices and equinoxes, and new moons

$ heniautos 400 --julian --julian-solar-events --julian-new-moons
1575324|BCE 0400-Jan-01||
1575325|BCE 0400-Jan-02||
...
1575348|BCE 0400-Jan-25||
1575349|BCE 0400-Jan-26||NM
1575350|BCE 0400-Jan-27||
...
1575407|BCE 0400-Mar-25||
1575408|BCE 0400-Mar-26|SpEq|NM
1575409|BCE 0400-Mar-27||
...

This is the underlying data that heniautos uses to generate calendars, so you can use this to check the work of heniautos or come up with yout own ideas.

Note

The new moons marked by --julian-new-moons are conjunctions, not visible new moons. Neither the new moons or solstices/equinoxes are affected by --visibility-offset or --solar-offset

Solstices and Equinoxes

You can see the dates of solstices and equinoxes for any year or years with --summer-solstice, --autumn-equinox, --winter-solstice:, and --spring-equinox

$ heniautos 400 --summer-solstice
BCE 0400-Jun-28 07:06:35 GMT

$ heniautos 400 --autumn-equinox
BCE 0400-Sep-28 10:24:44 GMT

$ heniautos 400 395 --winter-solstice
BCE 0400-Dec-25 23:45:54 GMT
BCE 0399-Dec-25 05:41:51 GMT
BCE 0398-Dec-25 11:26:39 GMT
BCE 0397-Dec-25 17:10:24 GMT
BCE 0396-Dec-25 23:03:29 GMT
BCE 0395-Dec-25 04:43:24 GMT

$ heniautos 2023 --as-ce --spring-equinox
 CE 2023-Mar-20 21:25:35 GMT

New Moons

The dates of new moons can be listed with --new-moons:

$ heniautos 400 --new-moons
BCE 0400-Jan-26 03:43:18 GMT
BCE 0400-Feb-24 15:23:36 GMT
BCE 0400-Mar-26 00:24:59 GMT
BCE 0400-Apr-24 07:48:26 GMT
BCE 0400-May-23 14:39:58 GMT
BCE 0400-Jun-21 21:58:47 GMT
BCE 0400-Jul-21 06:36:18 GMT
BCE 0400-Aug-19 17:19:56 GMT
BCE 0400-Sep-18 06:51:40 GMT
BCE 0400-Oct-17 23:31:21 GMT
BCE 0400-Nov-16 18:45:30 GMT
BCE 0400-Dec-16 14:51:35 GMT

Note

The new moons listes for the --new-moons option are for the Julian year given (or Gregorian for years following the Gregorian reform). For all the new moons relevant to the Greek year 400 (that is, 400/399 BCE) you would need some new moons from 400 and some from 399.

Athens Local Time

By default times of solstices, equinoxes, and new moons are given in Greenwich Mean Time. “Athens Local Time” (see Time Zones) can be selected instead with --athens-local-time.

Ephemerides

If you have the Skyfield package installed you can tell heniautos to use that for astronomical data rather than the data supplied with heniautos—for instance, if you want a calendar for a year not covered by the built-in data—with the --use-ephemeris option (-E for short).

Use --ephemeris (or -e) to specify the path to a particular ephemeris file. If no ephemeris file is specified and one cannot be found on your file path (or if a file is specified but it cannot be found at the specified path) Skyfield will automatically download a (large) ephemeris.

$ heniautos 1600 --as-ce --use-ephemeris -e de422.bsp

See Ephimerides and Custom Data.

heniautos Option Reference

start_year

A year, or the first year of a range to display (required). Years will be treated as BCE unless --as-ce is used

end_year

If provided, this and start_year will be treated as the first and last years of a range. They must be provided in the correct order or an error will be raised

-a, --abbreviations

Show month names as abbreviations

--arabic

Display prytany numbers as Arabic rather than Roman numerals

--as-ce

Treat dates as CE rather than BCE

--athens-local-time

Show times in Athens Local Times (see Time Zones)

--autumn-equinox

Only list dates of autumn equinox

-c <city>

Show calender for specific city (default Athens). Choices are argos, athens, delos, delphi, sparta, corinth, generic

-C, --conciliar

Output conciliar calendar (prytanies)

--calendar-start <season>

Season for beginning of the year (with -c generic). Choices are one of: summer, fall, winter, spring. Default: summer

-E, --use-ephemeris

Use ephemeris for data

-e <FILE>, --ephemeris <FILE>

Use existing ephemeris file (with -E)

-g, --greek-names

Show month names in Greek

-h

Show help

--intercalate <month number>

Month after which to intercalate

--julian

Output a Julian Calendar (Gregorian if after the Gregorian reform)

--julian-new-moons

TK

--julian-solar-events

TK

-m, --month-summary

Summarize calendar by month

--new-moons

Only list dates of new moons (conjunctions)

-s, --solar-offset

TK

--spring-equinox

Only list dates of spring equinox

--summer-solstice

Only list dates of solstices

--tab

Format output with tabs. Good for importing into spreadsheets (see Importing into Spreadsheets)

-v, --visibility-offset

TK

--winter-solstice

Only list dates of winter solstice

-y, --year-summary

Summarize calendar by year