Files
sorsfonalak/crates/astro-engine/src/forecast.rs
T

665 lines
24 KiB
Rust
Raw Normal View History

//! Forecast techniques on top of a natal chart, for one year of life (from a
//! solar return to the next):
//!
//! * [`solar_return`]: the moment the Sun comes back to its natal longitude
//! (the chart of that moment is an ordinary chart, cast by the caller for
//! the place where the person is);
//! * transits of the slow planets (Jupiter to Pluto) to the natal planets
//! and angles, with exact dates and the periods within orb;
//! * secondary progressions ("a day for a year");
//! * the annual profection (the house and the "lord" of the year);
//! * eclipses on the natal chart.
//!
//! Dates are calendar days at a fixed UTC offset given by the caller.
use serde::Serialize;
use crate::angle::separation;
use crate::chart::{
AspectKind, AspectNature, MoonPhaseName, NatalChart, PointId, ZodiacPosition, house_of, phase_name,
};
use crate::engine::{EclipseKind, EclipseType, EngineError, Ephemeris, Frame};
use crate::time::gregorian_from_jdn;
use crate::types::{Body, ZodiacSign, ZodiacType};
/// Days in a tropical year: "a day for a year" in progressions.
pub const TROPICAL_YEAR: f64 = 365.242_19;
/// Orb of transits and progressions, degrees.
pub const ORB: f64 = 1.0;
/// Orb of an eclipse on a natal point, degrees.
pub const ECLIPSE_ORB: f64 = 3.0;
/// Days scanned before and after the year, so that passes that began earlier
/// or end later show their whole length.
const MARGIN_DAYS: f64 = 400.0;
/// Passes starting or ending farther than this from the year belong to
/// another cycle and are left out.
const NEAR_DAYS: f64 = 200.0;
const TRANSITING: [Body; 5] = [Body::Jupiter, Body::Saturn, Body::Uranus, Body::Neptune, Body::Pluto];
const PROGRESSED: [Body; 5] = [Body::Sun, Body::Moon, Body::Mercury, Body::Venus, Body::Mars];
/// The aspects of the default chart (`AspectSet::Standard`): the major ones and the quincunx.
const ASPECTS: [AspectKind; 6] = [
AspectKind::Conjunction,
AspectKind::Sextile,
AspectKind::Square,
AspectKind::Trine,
AspectKind::Quincunx,
AspectKind::Opposition,
];
type Result<T> = std::result::Result<T, EngineError>;
/// Signed difference `a - b` in `[-180, 180)`.
fn diff(a: f64, b: f64) -> f64 {
(a - b + 180.0).rem_euclid(360.0) - 180.0
}
/// The calendar day of a moment at a fixed UTC offset, `YYYY-MM-DD`.
pub fn date_of(jd_ut: f64, offset_hours: f64) -> String {
let (y, m, d) = gregorian_from_jdn((jd_ut + 0.5 + offset_hours / 24.0).floor() as i64);
format!("{y:04}-{m:02}-{d:02}")
}
/// The zodiac of the natal chart, geocentric (transits are not topocentric).
fn frame_of(natal: &NatalChart) -> Frame {
let o = natal.settings.options;
Frame { sidereal: (o.zodiac == ZodiacType::Sidereal).then_some(o.ayanamsa), topocentric: None }
}
fn natal_lon(natal: &NatalChart, id: PointId) -> Option<f64> {
natal.points.iter().find(|p| p.id == id).map(|p| p.position.longitude)
}
fn cusps_of(natal: &NatalChart) -> Option<[f64; 12]> {
let houses = natal.houses.as_ref()?;
let mut cusps = [0.0; 12];
for (c, h) in cusps.iter_mut().zip(&houses.cusps) {
*c = h.position.longitude;
}
Some(cusps)
}
/// The natal points transits and progressions are measured to: the ten
/// planets and, with a known birth time, the Ascendant and the Midheaven.
/// Without a birth time the Moon is left out (it may be 7° off).
fn natal_targets(natal: &NatalChart) -> Vec<(PointId, f64)> {
let known = natal.angles.is_some();
let mut out: Vec<(PointId, f64)> = Body::PLANETS
.iter()
.map(|&b| PointId::from_planet(b))
.filter(|&id| known || id != PointId::Moon)
.filter_map(|id| natal_lon(natal, id).map(|lon| (id, lon)))
.collect();
if let Some(a) = &natal.angles {
out.push((PointId::Ascendant, a.ascendant.position.longitude));
out.push((PointId::Midheaven, a.midheaven.position.longitude));
}
out
}
/// The moment near `approx_jd` when `body` (moving forward) reaches `target`.
pub fn return_moment(engine: &dyn Ephemeris, body: Body, target: f64, approx_jd: f64, frame: &Frame) -> Result<f64> {
let mut jd = approx_jd;
for _ in 0..50 {
let s = engine.position(body, jd, frame)?;
let d = diff(target, s.longitude);
if d.abs() < 1e-9 {
return Ok(jd);
}
if s.speed_longitude <= 0.0 {
return Err(EngineError::Calculation(format!("{body:?} is not moving forward")));
}
jd += d / s.speed_longitude;
}
Ok(jd)
}
/// The solar return of a natal chart in a calendar year (the birthday of that year).
pub fn solar_return(engine: &dyn Ephemeris, natal: &NatalChart, year: i32) -> Result<f64> {
let natal_jd = natal.astronomy.julian_day_ut;
let birth_year = gregorian_from_jdn((natal_jd + 0.5).floor() as i64).0;
let sun = natal_lon(natal, PointId::Sun).expect("the Sun is always in a chart");
let approx = natal_jd + f64::from(year - birth_year) * TROPICAL_YEAR;
return_moment(engine, Body::Sun, sun, approx, &frame_of(natal))
}
/// A run of samples within orb: first and last moment.
type Window = (f64, f64);
/// The runs within orb, and the exact moments with "moving backward".
type Crossings = (Vec<Window>, Vec<(f64, bool)>);
/// Longitude and daily motion sampled at equal steps.
struct Samples {
start: f64,
step: f64,
lon: Vec<f64>,
speed: Vec<f64>,
}
impl Samples {
fn take(from: f64, to: f64, step: f64, at: &dyn Fn(f64) -> Result<(f64, f64)>) -> Result<Self> {
let n = ((to - from) / step).ceil() as usize + 1;
let mut lon = Vec::with_capacity(n);
let mut speed = Vec::with_capacity(n);
for i in 0..n {
let (l, s) = at(from + i as f64 * step)?;
lon.push(l);
speed.push(s);
}
Ok(Self { start: from, step, lon, speed })
}
fn jd(&self, i: usize) -> f64 {
self.start + i as f64 * self.step
}
}
/// Where a moving longitude meets `target`: the runs of samples within `orb`
/// (as moments) and the exact moments (with "retrograde" for backward motion).
fn crossings(s: &Samples, target: f64, orb: f64, lon_at: &dyn Fn(f64) -> Result<f64>) -> Result<Crossings> {
let d: Vec<f64> = s.lon.iter().map(|&l| diff(l, target)).collect();
let mut windows = Vec::new();
let mut open: Option<usize> = None;
for (i, x) in d.iter().enumerate() {
match (x.abs() <= orb, open) {
(true, None) => open = Some(i),
(false, Some(first)) => {
windows.push((s.jd(first), s.jd(i - 1)));
open = None;
}
_ => {}
}
}
if let Some(first) = open {
windows.push((s.jd(first), s.jd(d.len() - 1)));
}
let mut exact = Vec::new();
for i in 0..d.len().saturating_sub(1) {
let (a, b) = (d[i], d[i + 1]);
let crosses = (a <= 0.0 && b > 0.0) || (a >= 0.0 && b < 0.0);
if !crosses || a.abs() > 90.0 || b.abs() > 90.0 {
continue;
}
let (mut lo, mut hi) = (s.jd(i), s.jd(i + 1));
let rising = b > a;
for _ in 0..30 {
let mid = (lo + hi) / 2.0;
let below = diff(lon_at(mid)?, target) < 0.0;
if below == rising {
lo = mid;
} else {
hi = mid;
}
}
exact.push(((lo + hi) / 2.0, !rising));
}
Ok((windows, exact))
}
#[derive(Debug, Clone, Serialize)]
pub struct DateRange {
pub start: String,
pub end: String,
}
#[derive(Debug, Clone, Serialize)]
pub struct Exact {
pub date: String,
/// The moving planet is retrograde (a pass while it moves backward).
pub retrograde: bool,
}
/// A transiting or progressed planet in aspect to a natal point.
#[derive(Debug, Clone, Serialize)]
pub struct Contact {
pub planet: PointId,
pub natal_point: PointId,
pub aspect: AspectKind,
pub nature: AspectNature,
/// Exact hits inside the year.
pub exact: Vec<Exact>,
/// Periods within orb (transits only): whole passes, which may begin
/// before the year or end after it.
#[serde(skip_serializing_if = "Vec::is_empty")]
pub periods: Vec<DateRange>,
/// When it matters most inside the year: the first exact hit, or else the closest approach.
pub peak: String,
/// The closest orb inside the year (0 when exact).
pub min_orb: f64,
/// Natal house of the moving planet at the peak (birth time known).
#[serde(skip_serializing_if = "Option::is_none")]
pub house: Option<u8>,
#[serde(skip)]
peak_jd: f64,
}
/// One year of a natal chart.
struct Year<'a> {
engine: &'a dyn Ephemeris,
natal: &'a NatalChart,
frame: Frame,
start: f64,
end: f64,
offset: f64,
cusps: Option<[f64; 12]>,
}
impl Year<'_> {
fn date(&self, jd: f64) -> String {
date_of(jd, self.offset)
}
fn inside(&self, jd: f64) -> bool {
(self.start..=self.end).contains(&jd)
}
/// Contacts of one moving planet (sampled in `s`) with the natal points.
fn contacts(
&self,
planet: PointId,
s: &Samples,
lon_at: &dyn Fn(f64) -> Result<f64>,
targets: &[(PointId, f64)],
with_periods: bool,
) -> Result<Vec<Contact>> {
let mut out = Vec::new();
for &(natal_point, natal) in targets {
for aspect in ASPECTS {
let a = aspect.angle();
let mut points = vec![natal + a];
if a != 0.0 && a != 180.0 {
points.push(natal - a);
}
let (mut windows, mut exact) = (Vec::new(), Vec::new());
for target in points {
let (w, e) = crossings(s, target, ORB, lon_at)?;
windows.extend(w);
exact.extend(e);
}
if !windows.iter().any(|&(from, to)| to >= self.start && from <= self.end) {
continue;
}
windows.retain(|&(from, to)| to >= self.start - NEAR_DAYS && from <= self.end + NEAR_DAYS);
windows.sort_by(|a, b| a.0.total_cmp(&b.0));
exact.retain(|&(jd, _)| self.inside(jd));
exact.sort_by(|a, b| a.0.total_cmp(&b.0));
// The closest approach inside the year among the samples.
let (closest_i, closest) = (0..s.lon.len())
.filter(|&i| self.inside(s.jd(i)))
.map(|i| (i, separation(s.lon[i], natal)))
.map(|(i, sep)| (i, (sep - a).abs()))
.min_by(|x, y| x.1.total_cmp(&y.1))
.unwrap_or((0, ORB));
let (peak_jd, min_orb) = match exact.first() {
Some(&(jd, _)) => (jd, 0.0),
None => (s.jd(closest_i), closest),
};
let peak_lon = lon_at(peak_jd)?;
out.push(Contact {
planet,
natal_point,
aspect,
nature: aspect.nature(),
exact: exact.iter().map(|&(jd, retrograde)| Exact { date: self.date(jd), retrograde }).collect(),
periods: if with_periods {
windows
.iter()
.map(|&(from, to)| DateRange { start: self.date(from), end: self.date(to) })
.collect()
} else {
Vec::new()
},
peak: self.date(peak_jd),
min_orb: (min_orb * 100.0).round() / 100.0,
house: self.cusps.map(|c| house_of(peak_lon, &c)),
peak_jd,
});
}
}
Ok(out)
}
fn position(&self, body: Body, jd: f64) -> Result<(f64, f64)> {
let s = self.engine.position(body, jd, &self.frame)?;
Ok((s.longitude, s.speed_longitude))
}
fn transits(&self) -> Result<(Vec<Contact>, Vec<PlanetHouses>)> {
let targets = natal_targets(self.natal);
let mut contacts = Vec::new();
let mut houses = Vec::new();
for body in TRANSITING {
let at = |jd: f64| self.position(body, jd);
let lon_at = |jd: f64| at(jd).map(|(l, _)| l);
let s = Samples::take(self.start - MARGIN_DAYS, self.end + MARGIN_DAYS, 1.0, &at)?;
let planet = PointId::from_planet(body);
contacts.extend(self.contacts(planet, &s, &lon_at, &targets, true)?);
if let Some(cusps) = self.cusps {
houses.push(self.house_changes(planet, &s, &cusps));
}
}
contacts.sort_by(|a, b| a.peak_jd.total_cmp(&b.peak_jd));
Ok((contacts, houses))
}
/// The natal house a sampled planet is in at the start, and when it changes house during the year.
fn house_changes(&self, planet: PointId, s: &Samples, cusps: &[f64; 12]) -> PlanetHouses {
let in_year: Vec<usize> = (0..s.lon.len()).filter(|&i| self.inside(s.jd(i))).collect();
let first = in_year.first().copied().unwrap_or(0);
let mut current = house_of(s.lon[first], cusps);
let at_start = current;
let mut ingresses = Vec::new();
for &i in &in_year[1.min(in_year.len())..] {
let house = house_of(s.lon[i], cusps);
if house != current {
ingresses.push(HouseIngress { house, date: self.date(s.jd(i)), retrograde: s.speed[i] < 0.0 });
current = house;
}
}
PlanetHouses { planet, house_at_start: at_start, ingresses }
}
fn progressions(&self) -> Result<Progressions> {
let natal_jd = self.natal.astronomy.julian_day_ut;
let progressed = |jd: f64| natal_jd + (jd - natal_jd) / TROPICAL_YEAR;
let known = self.natal.angles.is_some();
let targets = natal_targets(self.natal);
let mut bodies = Vec::new();
let mut contacts = Vec::new();
let mut samples = Vec::new();
for body in PROGRESSED {
// Motion per real day: the progressed speed divided by the year length.
let at = |jd: f64| self.position(body, progressed(jd)).map(|(l, sp)| (l, sp / TROPICAL_YEAR));
let lon_at = |jd: f64| at(jd).map(|(l, _)| l);
let s = Samples::take(self.start, self.end, 1.0, &at)?;
let planet = PointId::from_planet(body);
let reliable = known || body != Body::Moon;
if reliable {
// A progressed planet meeting its own natal place only matters for the Moon (the progressed lunar return).
let own: Vec<(PointId, f64)> =
targets.iter().copied().filter(|&(id, _)| id != planet || body == Body::Moon).collect();
contacts.extend(self.contacts(planet, &s, &lon_at, &own, false)?);
}
let start = ZodiacPosition::new(s.lon[0]);
let mut sign_changes = Vec::new();
let mut house_changes = Vec::new();
if reliable {
for i in 1..s.lon.len() {
let sign = ZodiacSign::from_longitude(s.lon[i]);
if sign != ZodiacSign::from_longitude(s.lon[i - 1]) {
sign_changes.push(SignIngress { sign, date: self.date(s.jd(i)) });
}
if let Some(c) = &self.cusps {
let house = house_of(s.lon[i], c);
if house != house_of(s.lon[i - 1], c) {
house_changes.push(HouseIngress {
house,
date: self.date(s.jd(i)),
retrograde: s.speed[i] < 0.0,
});
}
}
}
}
bodies.push(ProgressedBody {
planet,
house: self.cusps.map(|c| house_of(s.lon[0], &c)),
position: start,
retrograde: s.speed[0] < 0.0,
approximate: !reliable,
sign_changes,
house_changes,
});
samples.push(s);
}
contacts.sort_by(|a, b| a.peak_jd.total_cmp(&b.peak_jd));
// The progressed lunation phase: the progressed Moon's distance from the progressed Sun.
let (sun, moon) = (&samples[0], &samples[1]);
let phase_at = |i: usize| phase_name(sun.lon[i], moon.lon[i]);
let lunar_phase = phase_at(0);
let lunar_phase_change = if known {
(1..moon.lon.len())
.find(|&i| phase_at(i) != lunar_phase)
.map(|i| PhaseChange { phase: phase_at(i), date: self.date(moon.jd(i)) })
} else {
None
};
Ok(Progressions { bodies, lunar_phase, lunar_phase_change, contacts })
}
fn profection(&self, age: i32) -> Option<Profection> {
let angles = self.natal.angles.as_ref()?;
let cusps = self.cusps?;
let rising = angles.ascendant.position.sign;
let sign = ZodiacSign::ALL[(rising.index() + age.rem_euclid(12) as usize) % 12];
let lord = sign.traditional_ruler();
let lord_lon = natal_lon(self.natal, PointId::from_planet(lord))?;
let planets_in_sign = Body::PLANETS
.iter()
.map(|&b| PointId::from_planet(b))
.filter(|&id| natal_lon(self.natal, id).is_some_and(|lon| ZodiacSign::from_longitude(lon) == sign))
.collect();
Some(Profection {
house: (age.rem_euclid(12) + 1) as u8,
sign,
lord: PointId::from_planet(lord),
lord_sign: ZodiacSign::from_longitude(lord_lon),
lord_house: house_of(lord_lon, &cusps),
planets_in_sign,
})
}
fn eclipses(&self) -> Result<Vec<EclipseHit>> {
let targets = natal_targets(self.natal);
let mut out = Vec::new();
for e in self.engine.eclipses(self.start, self.end)? {
let body = match e.kind {
EclipseKind::Solar => Body::Sun,
EclipseKind::Lunar => Body::Moon,
};
let (lon, _) = self.position(body, e.jd_ut)?;
let mut contacts: Vec<EclipseContact> = targets
.iter()
.filter_map(|&(point, natal)| {
let sep = separation(lon, natal);
let (aspect, orb) = if sep <= ECLIPSE_ORB {
(AspectKind::Conjunction, sep)
} else if 180.0 - sep <= ECLIPSE_ORB {
(AspectKind::Opposition, 180.0 - sep)
} else {
return None;
};
Some(EclipseContact { point, aspect, orb: (orb * 100.0).round() / 100.0 })
})
.collect();
contacts.sort_by(|a, b| a.orb.total_cmp(&b.orb));
out.push(EclipseHit {
date: self.date(e.jd_ut),
kind: e.kind,
eclipse_type: e.eclipse_type,
house: self.cusps.map(|c| house_of(lon, &c)),
position: ZodiacPosition::new(lon),
contacts,
});
}
Ok(out)
}
}
#[derive(Debug, Clone, Serialize)]
pub struct HouseIngress {
pub house: u8,
pub date: String,
pub retrograde: bool,
}
/// A slow planet's way through the natal houses during the year.
#[derive(Debug, Clone, Serialize)]
pub struct PlanetHouses {
pub planet: PointId,
pub house_at_start: u8,
pub ingresses: Vec<HouseIngress>,
}
#[derive(Debug, Clone, Serialize)]
pub struct SignIngress {
pub sign: ZodiacSign,
pub date: String,
}
/// A progressed planet at the start of the year and its sign and house changes during it.
#[derive(Debug, Clone, Serialize)]
pub struct ProgressedBody {
pub planet: PointId,
#[serde(flatten)]
pub position: ZodiacPosition,
/// Natal house (birth time known).
pub house: Option<u8>,
pub retrograde: bool,
/// The progressed Moon without a birth time: may be months off.
pub approximate: bool,
pub sign_changes: Vec<SignIngress>,
pub house_changes: Vec<HouseIngress>,
}
#[derive(Debug, Clone, Serialize)]
pub struct PhaseChange {
pub phase: MoonPhaseName,
pub date: String,
}
#[derive(Debug, Clone, Serialize)]
pub struct Progressions {
pub bodies: Vec<ProgressedBody>,
/// Phase of the progressed Moon to the progressed Sun at the start of the year.
pub lunar_phase: MoonPhaseName,
pub lunar_phase_change: Option<PhaseChange>,
/// Progressed planets in aspect to natal points during the year.
pub contacts: Vec<Contact>,
}
/// The annual profection: each year of life activates the next house (whole
/// signs from the Ascendant); the ruler of its sign is the lord of the year.
#[derive(Debug, Clone, Serialize)]
pub struct Profection {
pub house: u8,
pub sign: ZodiacSign,
pub lord: PointId,
pub lord_sign: ZodiacSign,
/// Natal house of the lord.
pub lord_house: u8,
/// Natal planets in the profected sign.
pub planets_in_sign: Vec<PointId>,
}
#[derive(Debug, Clone, Serialize)]
pub struct EclipseContact {
pub point: PointId,
/// Conjunction or opposition.
pub aspect: AspectKind,
pub orb: f64,
}
#[derive(Debug, Clone, Serialize)]
pub struct EclipseHit {
pub date: String,
pub kind: EclipseKind,
pub eclipse_type: EclipseType,
/// The Sun (solar eclipse) or the Moon (lunar eclipse) at the maximum.
#[serde(flatten)]
pub position: ZodiacPosition,
/// Natal house of the eclipse (birth time known).
pub house: Option<u8>,
/// Natal points within 3° of the eclipse or its opposite point.
pub contacts: Vec<EclipseContact>,
}
/// One year of forecasts for a natal chart.
#[derive(Debug, Clone, Serialize)]
pub struct Forecast {
/// First and last day of the year (solar return to the next one).
pub start: String,
pub end: String,
pub start_jd: f64,
pub end_jd: f64,
/// Completed years of life at the start.
pub age: i32,
/// Only with a known birth time.
pub profection: Option<Profection>,
/// Slow-planet transits within the year, by their peak date.
pub transits: Vec<Contact>,
/// The slow planets' natal houses (birth time known).
pub transit_houses: Vec<PlanetHouses>,
pub progressions: Progressions,
pub eclipses: Vec<EclipseHit>,
#[serde(skip_serializing_if = "Vec::is_empty")]
pub warnings: Vec<String>,
}
/// Forecasts for the year from `start_jd` to `end_jd` (normally a solar return
/// and the next one); dates are given at `offset_hours` from UTC.
pub fn calculate_forecast(
engine: &dyn Ephemeris,
natal: &NatalChart,
start_jd: f64,
end_jd: f64,
offset_hours: f64,
) -> Result<Forecast> {
if end_jd <= start_jd || end_jd - start_jd > 400.0 {
return Err(EngineError::Calculation("the forecast period must be at most about a year".into()));
}
let year = Year {
engine,
natal,
frame: frame_of(natal),
start: start_jd,
end: end_jd,
offset: offset_hours,
cusps: cusps_of(natal),
};
let age = ((start_jd - natal.astronomy.julian_day_ut) / TROPICAL_YEAR).round() as i32;
let (transits, transit_houses) = year.transits()?;
let mut warnings = Vec::new();
if natal.angles.is_none() {
warnings.push(
"Birth time unknown: no profection, houses or angles, and the Moon (natal and progressed) is left out of \
the contacts."
.into(),
);
}
Ok(Forecast {
start: year.date(start_jd),
end: year.date(end_jd),
start_jd,
end_jd,
age,
profection: year.profection(age),
transits,
transit_houses,
progressions: year.progressions()?,
eclipses: year.eclipses()?,
warnings,
})
}
#[cfg(test)]
mod tests {
use super::*;
#[test]
fn signed_difference() {
assert_eq!(diff(10.0, 350.0), 20.0);
assert_eq!(diff(350.0, 10.0), -20.0);
assert_eq!(diff(180.0, 0.0), -180.0);
}
#[test]
fn dates_at_an_offset() {
// 2000-01-01 12:00 UT
assert_eq!(date_of(2_451_545.0, 0.0), "2000-01-01");
// 23:30 UT is the next day at UTC+1
assert_eq!(date_of(2_451_545.479_2, 1.0), "2000-01-02");
}
}