//! 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 = std::result::Result; /// 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 { 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 { 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 { 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, Vec<(f64, bool)>); /// Longitude and daily motion sampled at equal steps. struct Samples { start: f64, step: f64, lon: Vec, speed: Vec, } impl Samples { fn take(from: f64, to: f64, step: f64, at: &dyn Fn(f64) -> Result<(f64, f64)>) -> Result { 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) -> Result { let d: Vec = s.lon.iter().map(|&l| diff(l, target)).collect(); let mut windows = Vec::new(); let mut open: Option = 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, /// 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, /// 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, #[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, targets: &[(PointId, f64)], with_periods: bool, ) -> Result> { 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, Vec)> { 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 = (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 { 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 { 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> { 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 = 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, } #[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, pub retrograde: bool, /// The progressed Moon without a birth time: may be months off. pub approximate: bool, pub sign_changes: Vec, pub house_changes: Vec, } #[derive(Debug, Clone, Serialize)] pub struct PhaseChange { pub phase: MoonPhaseName, pub date: String, } #[derive(Debug, Clone, Serialize)] pub struct Progressions { pub bodies: Vec, /// Phase of the progressed Moon to the progressed Sun at the start of the year. pub lunar_phase: MoonPhaseName, pub lunar_phase_change: Option, /// Progressed planets in aspect to natal points during the year. pub contacts: Vec, } /// 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, } #[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, /// Natal points within 3° of the eclipse or its opposite point. pub contacts: Vec, } /// 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, /// Slow-planet transits within the year, by their peak date. pub transits: Vec, /// The slow planets' natal houses (birth time known). pub transit_houses: Vec, pub progressions: Progressions, pub eclipses: Vec, #[serde(skip_serializing_if = "Vec::is_empty")] pub warnings: Vec, } /// 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 { 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"); } }