Inside
Astrology Engine
Learn the astronomy and mathematics behind chart calculation. Start with an angle and follow the calculations from prepared astronomical data to a chart, then to the search for a particular moment.
Begin with orientationDifferent numbers.
The same direction.
Before dates, orbits and charts, there is a useful idea to get comfortable with: angles wrap around.
Move the slider, or use the arrow keys. A full turn changes the number by 360° and leaves the direction unchanged.
What are we calculating?
An astrology chart collects sky positions for a chosen time and location. For example, you supply a date, time and place, and the engine returns numbers describing the Sun, Moon and planets, along with angles used to divide the chart. This course teaches how those numbers are calculated.
One position number is ecliptic longitude: an angle around the sky measured along the ecliptic, the Sun’s apparent yearly path. Think of it as a reading on a 360° dial with an agreed zero direction. A Sun crossing is a time when the Sun reaches a chosen reading on that dial, such as 30°. It is a search for a time, rather than a position at a supplied time. The U.S. Naval Observatory glossary gives the precise coordinate definitions; later lessons will explain the reference directions.
Houses are twelve divisions used in an astrology chart. A house system is a rule for constructing those divisions from the time and location; their boundary angles are called cusps. Astronomy supplies models of positions and motion, while the choice of house system is an astrological convention. The lessons keep those roles distinct.
Three paths through one engine
The engine separates work done while preparing its dataset from work done when you request a chart. Event search repeats calculations to find a time that meets a condition. The lessons follow that flow.
New to astronomy? Start with orientation, then follow the lessons in order. The full sequence is: prepare the dataset, calculate a chart, then find a Sun crossing. These three paths are stages of one learning sequence; later stages build on earlier ones.
Looking for a particular calculation? Use the contents below to open its lesson directly, then follow its “Before this lesson” links for prerequisites. Choose dataset preparation to understand where the position tables come from, chart calculation to understand their use for a time and place, or event search to understand finding a time from a target angle.
Prepare the dataset
Turn source positions into the small tables the engine reads.
- Start with recorded positions
- Put time and distance on a scale
- Fit the source position curves
- Find the shared usable interval
- Account for light travel time
- Describe the moving reference planes
- Rotate vectors into chart coordinates
- Find the Moon orbit crossing direction
- Compress the angular samples
- Measure the approximation error
- Package a reusable dataset
Calculate a chart
Read positions, measure motion, and construct chart angles and houses.
Find a Sun crossing
Find when the Sun reaches a chosen longitude, with explicit search limits.
Bring your programming intuition
You need basic algebra: addition, multiplication, fractions and rearranging a simple equation. We will introduce trigonometry where a calculation needs it. Read the main explanation first, then open the derivations if you want more detail.
Examples use small, readable TypeScript functions. The lessons explain whether an example reproduces the Rust calculation or simplifies it for teaching.