Astrod2 aims to replicate the functional specification of Astrod in a more general way. Currently, it focuses only on World Transits.
Engines
Astrod2 is written in Python and can perform its calculations using the following Python libraries:
(Astrod2 primarily now uses the Swiss Ephemeris. For recent history, there is no significant difference between the libraries. The only case in which Swisseph, which uses a newer version of the NASA JPL ephemeris, may be more appropriate is for alignments involving Pluto prior to 0AD, where there are significant differences in the predictions of the two libraries. See here for more information.)
Queries
Parameters
- Start & end date
- Interval as hours/days/weeks/months/years (depending on date method; see below)
- Stride as size of interval
- The set or a subset of the Sun, Moon, planets and supported asteroids
- The orb condition (for alignedness and alignment calculations; see below)
- The planetary configurations of interest (for alignment calculations; see below)
Dates
The following methods to generate date ranges are supported; each have their advantages and limitations. In all cases, they are corrected to the native format of the chosen engine (see above).
- Python datetimes: simplest to work with, support from 1AD onwards only and Gregorian calendar is assumed
- Tuples: allows year or month (AD or BC) to be specified, a simple format for long and sparse date ranges
- Ephem dates: these are a useful format specific to the library, and have built in handling for the Julian/Gregorian switch
- File: allows a series of dates to be read from a file in a format (using a format string)
AD and BC dates
There is no year zero. Swisseph and Ephem handle this differently, and in the former case a correction is needed to obtain consistency with other astrological software. A future blog post will explain this in more detail. The basic difficulty is that an iteration of years must pass through a year that does not exist.
Julian and Gregorian dates
These are taken to switch on 15 October 1582. Ephem handles this automatically while in Swisseph a calendar flag is required. This is actually much more useful, as in reality the switch occurred over many centuries, and both calendars may be required in different contexts. Care is needed in subsequent analysis as many systems assume dates to be Gregorian including Python dates and Matplotlib dates.
Timezones
All dates are timezone agnostic, including Python datetimes which do support timezones. A timezone offset can then be supplied.
Functions
Generate positions
The geocentric longitudinal positions of all planets on the solar ecliptic, the basic positional measure in astrological calculations. These readily provide the sign of the planet (by the tropical zodiac), via an additional function.
Generate all body positions
I.e. a natal chart. Thus automated chart generation is readily possible, for example from a file specifying a list of dates.
Generate velocities
These likewise readily provide whether a planet is retrograde, via an additional function.
Generate alignedness
The ‘alignedness’ of all pairs of planets, by one of the following metrics:
Separation
The angular separation based on the above positions.
Alignedness
A numerical metric of the degree of alignedness, of arbitrary magnitude. The following measure are available:
- Linear, in which alignedness increases linearly from zero at a separation corresponding to the specified orb to a maximum value at exact alignment.
- Gaussian, in which alignedness takes the form a normal distribution with a mean at exact alignment and 3σ occurring at a separation corresponding to the the specified orb. The use of 3σ means that at separations beyond the specified orb there is negligible alignedness.
- Boolean, in which simply whether or not an alignment is in force is returned.
All measures require an orb condition and the first two an amplitude factor. These may be specified on a per alignment basis (i.e. different parameters for different alignments). Note that these measures are heuristic, and have no meaning beyond a helpful way to represent separation. The normal distribution is used for its form and does not represent the distribution of anything.
Alignments
The requested alignments occurring between the specified start dates (that have finished within this period; unfinished alignments are not counted).
Alignment searches (see below) can search for any combinations of planets, whose separations in that combinations are specified as tuples. Therefore all of the following are possible, as well as arbitrarily many others:
"bodies": ["Jupiter","Saturn","Uranus","Neptune","Pluto"]
"Conjunction": (0,0) "Triple Conjunction": (0,0,0) "Full Conjunction": (0,0,0,0,0,0,0,0,0,0) "Opposition": (0,180) "Square": (0,90) "Semisextile": (0,30) "Sextile": (0,60) "Trine": (0,120) "Quincunx": (0,150) "Grand Cross": (0,90,180,270) "Grand Trine": (0,120,240)
This is a particularly powerful feature of Astrod2. Sets of planets are in general permuted to match these patterns and therefore calculation times increase very rapidly for configurations involving greater numbers of planets.
The following are returned, where the alignment meets the specified orb condition. The variable orbs of the alignedness calculations above may be used on a per alignment basis.
- Start date of alignment
- End date of alignment
- Minimum deviation, where deviation is calculated as the one of the following measures of the set of planets being analysed. (For two planets these are simply separation, while for more complex alignments they are possible measure of the closeness of the overall alignment.)
- Mean
- Total
- The date of minimum deviation
Sign periods
This returns periods in which a planet is in a particular sign.
Retrograde periods
This returns periods in which a planet is retrograde.
Complex searches
In the above, the two basic formats are quantities specified by date (e.g. position, separation) and periods in which a condition is true (e.g. planets are aligned, a planet is retrograde). Using Pandas dataframes, complex “boolean” searches may then be performed by simple layers of code for each of these formats. This part of the library is very open-ended, as research requirements will vary at this stage. However as an illustration, the following searches would be possible:
- When are Jupiter and Saturn conjunct, Mercury retrograde and Neptune in Pisces?
- When are Mars and Venus trine, and Pluto is in Aquarius or Leo?
The combination of the above ability to search for arbitrarily complex planetary and alignments and also to perform complex searches such as these makes the library particularly powerful. Everything it does is of course achievable directly from an ephemeris, and this library may be thought of as a thin but highly functional wrapper on an ephemeris of choice.
Output
Metrics
Angles may be returned as:
- Decimals
- Base 60 (degrees/minutes/seconds)
- Base 60 referenced to the tropical Zodiac (e.g. 15°30’45” Aries), useful for comparision to astrological software
Format
Output is Python generators and may be written to Pandas dataframes, CSV files or other formats for subsequent analysis.
Frameworks
There are many possible approaches. At present, we are running Astrod in the superb Anaconda framework. This provides Python and Jupyter out of the box, with support for PyEphem through its own package manager:
conda install ephem
and installation of Swisseph also straightforward via the package manager pip:
pip install pyswisseph
Jupyter notebooks provide an excellent framework for exploratory data analysis, in combination with Pandas (data analysis) and Matplotlib (plotting). Many other packages are of course available depending on need.
Astrod2 has been tested and verified against Solar Fire and AstroGold in an extensive and ongoing way.
Future work
In its present form, Astrod2 handles the main tenets of (tropical) astrology related to quantities derived from geocentric ecliptic longitude. The two main areas that are not supported are houses and sidereal astrology.