Yearly forecast: solar return, transits, progressions, profection, eclipses
CI / test (push) Successful in 56s
CI / build (push) Successful in 4m41s
CI / deploy (push) Skipped

- astro-engine: forecast module (solar return moment, slow-planet transits
  with exact dates and periods, natal house ingresses, secondary
  progressions, annual profection, eclipses via Swiss Ephemeris)
- horoscope-api: POST /v1/forecast, solar return chart cast for the place
  of the birthday
- backend: forecasts table, /v1/charts/{id}/forecasts, /v1/forecasts/{id}
  and its analyses using a new 'forecast' unit; current year of life open,
  the next one 30 days before the birthday
- packages: Páros and Család include forecasts (6 000 / 11 000 Ft),
  +1 éves előrejelzés add-on 2 500 Ft; Egy elemzés unchanged
- worker and prompt: forecast kind with five sections and forecast rules
  (trends, no event predictions); no birth data, place or exact age sent
- frontend: /kepletek/{id}/elorejelzes with the solar return wheel, the
  keys of the year, a monthly timeline, transit list and detailed forecast
- data export: forecasts added, model name removed

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_012vLHzh5qUhFtmJhzkcTbXL
This commit is contained in:
feco
2026-11-18 08:19:13 +00:00
co-authored by Claude Opus 5.5
parent 829c33e52f
commit f1bd34c394
42 changed files with 4764 additions and 85 deletions
+2 -2
View File
@@ -82,7 +82,7 @@ pub enum PointId {
}
impl PointId {
fn from_planet(body: Body) -> PointId {
pub(crate) fn from_planet(body: Body) -> PointId {
match body {
Body::Sun => PointId::Sun,
Body::Moon => PointId::Moon,
@@ -720,7 +720,7 @@ fn above_horizon(lon: f64, ascendant: f64) -> bool {
angle::arc(ascendant, lon) >= 180.0
}
fn phase_name(elongation: f64) -> MoonPhaseName {
pub(crate) fn phase_name(elongation: f64) -> MoonPhaseName {
use MoonPhaseName::*;
[NewMoon, WaxingCrescent, FirstQuarter, WaxingGibbous, FullMoon, WaningGibbous, LastQuarter, WaningCrescent]
[((elongation / 45.0).floor() as usize).min(7)]
+30
View File
@@ -109,6 +109,32 @@ pub struct EphemerisInfo {
pub license: String,
}
#[derive(Debug, Clone, Copy, PartialEq, Eq, Serialize)]
#[serde(rename_all = "snake_case")]
pub enum EclipseKind {
Solar,
Lunar,
}
#[derive(Debug, Clone, Copy, PartialEq, Eq, Serialize)]
#[serde(rename_all = "snake_case")]
pub enum EclipseType {
Total,
Annular,
/// Annular-total (hybrid) solar eclipse.
Hybrid,
Partial,
Penumbral,
}
/// An eclipse at its maximum.
#[derive(Debug, Clone, Copy, PartialEq)]
pub struct EclipseEvent {
pub kind: EclipseKind,
pub eclipse_type: EclipseType,
pub jd_ut: f64,
}
pub trait Ephemeris: Send + Sync {
fn info(&self) -> EphemerisInfo;
@@ -129,4 +155,8 @@ pub trait Ephemeris: Send + Sync {
/// Ayanamsa value in degrees.
fn ayanamsa(&self, jd_ut: f64, ayanamsa: Ayanamsa) -> Result<f64>;
/// Solar eclipses (all types) and lunar eclipses (partial and total, not
/// the barely visible penumbral ones) between two moments, in time order.
fn eclipses(&self, from_jd: f64, to_jd: f64) -> Result<Vec<EclipseEvent>>;
}
+657
View File
@@ -0,0 +1,657 @@
//! 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];
const ASPECTS: [AspectKind; 5] =
[AspectKind::Conjunction, AspectKind::Sextile, AspectKind::Square, AspectKind::Trine, 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((moon.lon[i] - sun.lon[i]).rem_euclid(360.0));
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");
}
}
+9 -2
View File
@@ -4,11 +4,14 @@
//! Swiss Ephemeris, see [`swiss::SwissEphemeris`]); everything astrological on
//! top of it (signs, houses, aspects, dignities, lots, summaries) lives in
//! [`chart`] and is independent of the engine, so the engine can be replaced
//! without touching the chart logic. [`synastry`] compares two charts.
//! without touching the chart logic. [`synastry`] compares two charts;
//! [`forecast`] looks at one year of a chart (solar return, transits,
//! progressions, profection, eclipses).
pub mod angle;
pub mod chart;
pub mod engine;
pub mod forecast;
pub mod synastry;
pub mod time;
pub mod types;
@@ -17,6 +20,10 @@ pub mod types;
pub mod swiss;
pub use chart::{ChartInput, ChartOptions, NatalChart, calculate_chart};
pub use engine::{BodyState, EngineError, Ephemeris, EphemerisInfo, Frame, GeoPosition, HouseResult, Obliquity};
pub use engine::{
BodyState, EclipseEvent, EclipseKind, EclipseType, EngineError, Ephemeris, EphemerisInfo, Frame, GeoPosition,
HouseResult, Obliquity,
};
pub use forecast::{Forecast, calculate_forecast, solar_return};
pub use synastry::{Synastry, calculate_synastry};
pub use types::{AspectSet, Ayanamsa, Body, HouseSystem, LilithType, NodeType, ZodiacSign, ZodiacType};
+61 -1
View File
@@ -14,7 +14,8 @@ use swisseph_sys as sys;
use crate::angle::normalize;
use crate::engine::{
BodyState, EngineError, Ephemeris, EphemerisInfo, Frame, GeoPosition, HouseResult, Obliquity, Result,
BodyState, EclipseEvent, EclipseKind, EclipseType, EngineError, Ephemeris, EphemerisInfo, Frame, GeoPosition,
HouseResult, Obliquity, Result,
};
use crate::types::{Ayanamsa, Body, HouseSystem};
@@ -324,6 +325,65 @@ impl Ephemeris for SwissEphemeris {
}
Ok(daya)
}
fn eclipses(&self, from_jd: f64, to_jd: f64) -> Result<Vec<EclipseEvent>> {
let _guard = lock();
let mut out = Vec::new();
for kind in [EclipseKind::Solar, EclipseKind::Lunar] {
let mut start = from_jd;
loop {
let mut tret = [0.0f64; 10];
let mut serr = [0 as c_char; sys::AS_MAXCH];
// SAFETY: tret has the 10 elements and serr the AS_MAXCH bytes the API requires.
let ret = unsafe {
match kind {
EclipseKind::Solar => sys::swe_sol_eclipse_when_glob(
start,
sys::SEFLG_SWIEPH,
0,
tret.as_mut_ptr(),
0,
serr.as_mut_ptr(),
),
EclipseKind::Lunar => sys::swe_lun_eclipse_when(
start,
sys::SEFLG_SWIEPH,
sys::SE_ECL_TOTAL | sys::SE_ECL_PARTIAL,
tret.as_mut_ptr(),
0,
serr.as_mut_ptr(),
),
}
};
if ret == sys::ERR {
return Err(EngineError::Calculation(c_string(&serr)));
}
let jd = tret[0];
if jd > to_jd {
break;
}
out.push(EclipseEvent { kind, eclipse_type: eclipse_type(ret), jd_ut: jd });
// Eclipses of one kind are at least two weeks apart.
start = jd + 10.0;
}
}
out.sort_by(|a, b| a.jd_ut.total_cmp(&b.jd_ut));
Ok(out)
}
}
fn eclipse_type(flags: i32) -> EclipseType {
if flags & sys::SE_ECL_ANNULAR_TOTAL != 0 {
EclipseType::Hybrid
} else if flags & sys::SE_ECL_TOTAL != 0 {
EclipseType::Total
} else if flags & sys::SE_ECL_ANNULAR != 0 {
EclipseType::Annular
} else if flags & sys::SE_ECL_PARTIAL != 0 {
EclipseType::Partial
} else {
EclipseType::Penumbral
}
}
#[cfg(test)]
@@ -163,3 +163,57 @@ fn sidereal_zodiac_subtracts_ayanamsa() {
assert!((23.0..24.5).contains(&ayanamsa), "lahiri ayanamsa {ayanamsa}");
assert!(close(tropical.longitude - sidereal.longitude, ayanamsa, 1e-3));
}
#[test]
fn eclipses_of_2026() {
use astro_engine::{EclipseKind, EclipseType};
// 2026-01-01 .. 2027-01-01 (UT): annular 17 Feb, total lunar 3 Mar, total solar 12 Aug, partial lunar 28 Aug.
let found = engine().eclipses(2_461_041.5, 2_461_406.5).unwrap();
let list: Vec<(EclipseKind, EclipseType, String)> =
found.iter().map(|e| (e.kind, e.eclipse_type, astro_engine::forecast::date_of(e.jd_ut, 0.0))).collect();
assert_eq!(
list,
vec![
(EclipseKind::Solar, EclipseType::Annular, "2026-02-17".into()),
(EclipseKind::Lunar, EclipseType::Total, "2026-03-03".into()),
(EclipseKind::Solar, EclipseType::Total, "2026-08-12".into()),
(EclipseKind::Lunar, EclipseType::Partial, "2026-08-28".into()),
]
);
}
#[test]
fn solar_return_and_forecast() {
use astro_engine::chart::PointId;
use astro_engine::{calculate_forecast, solar_return};
let input = ChartInput { jd_ut: JD, observer: BUDAPEST, time_known: true, options: ChartOptions::default() };
let natal = calculate_chart(engine(), &input).unwrap();
let sr = solar_return(engine(), &natal, 2026).unwrap();
// The Sun is back at 112.0007251° (Cancer 22°) on 14 July 2026.
let sun = engine().position(Body::Sun, sr, &Frame::TROPICAL_GEOCENTRIC).unwrap();
assert!(close(sun.longitude, 112.0007251, 1e-6), "{}", sun.longitude);
assert_eq!(astro_engine::forecast::date_of(sr, 2.0), "2026-07-14");
let next = solar_return(engine(), &natal, 2027).unwrap();
assert!((next - sr - 365.25).abs() < 0.1);
let f = calculate_forecast(engine(), &natal, sr, next, 2.0).unwrap();
assert_eq!(f.age, 41);
assert_eq!((f.start.as_str(), f.end.as_str()), ("2026-07-14", "2027-07-14"));
// Age 41: the 6th house from a Scorpio Ascendant (Aries), lord Mars.
let p = f.profection.as_ref().unwrap();
assert_eq!(p.house, 6);
assert_eq!(p.sign, astro_engine::ZodiacSign::Aries);
assert_eq!(p.lord, PointId::Mars);
// Every transit touches the year, has a peak inside it and exact hits inside it.
assert!(!f.transits.is_empty());
for t in &f.transits {
assert!(t.peak.as_str() >= f.start.as_str() && t.peak.as_str() <= f.end.as_str(), "{t:?}");
assert!(t.min_orb <= 1.0 && !t.periods.is_empty());
assert!(t.exact.iter().all(|e| e.date >= f.start && e.date <= f.end));
}
assert_eq!(f.transit_houses.len(), 5);
assert_eq!(f.progressions.bodies.len(), 5);
// The partial lunar eclipse of 28 Aug 2026 and the two in early 2027 fall in this year.
assert!(f.eclipses.iter().any(|e| e.date == "2026-08-28"));
serde_json::to_string(&f).unwrap();
}