astroceleste-engine 0.0.2__tar.gz → 0.0.4__tar.gz

{astroceleste_engine-0.0.2 → astroceleste_engine-0.0.4}/Cargo.lock

@@ -4,7 +4,7 @@ version = 4
 
 [[package]]
 name = "astroceleste-engine"
-version = "0.0.2"
+version = "0.0.4"
 dependencies = [
  "serde",
  "serde_json",
@@ -12,7 +12,7 @@ dependencies = [
 
 [[package]]
 name = "astroceleste-engine-py"
-version = "0.0.2"
+version = "0.0.4"
 dependencies = [
  "astroceleste-engine",
  "pyo3",
@@ -22,7 +22,7 @@ dependencies = [
 
 [[package]]
 name = "astroceleste-engine-wasm"
-version = "0.0.2"
+version = "0.0.4"
 dependencies = [
  "astroceleste-engine",
  "js-sys",

{astroceleste_engine-0.0.2 → astroceleste_engine-0.0.4}/Cargo.toml

@@ -3,7 +3,7 @@ resolver = "2"
 members = ["crates/astroceleste-engine", "crates/astroceleste-engine-py"]
 
 [workspace.package]
-version = "0.0.2"
+version = "0.0.4"
 edition = "2021"
 rust-version = "1.85"
 license = "MIT OR Apache-2.0"

{astroceleste_engine-0.0.2 → astroceleste_engine-0.0.4}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: astroceleste-engine
-Version: 0.0.2
+Version: 0.0.4
 Classifier: Development Status :: 2 - Pre-Alpha
 Classifier: Programming Language :: Rust
 Classifier: Programming Language :: Python :: 3
@@ -28,6 +28,9 @@ Project-URL: Repository, https://github.com/ffalcinelli/astroceleste-engine
 Python bindings for [astroceleste-engine](https://github.com/ffalcinelli/astroceleste-engine),
 astrological chart calculation on NASA JPL ephemerides, written in Rust.
 
+[Website and live demo](https://ffalcinelli.github.io/astroceleste-engine/) ·
+[API guide](https://github.com/ffalcinelli/astroceleste-engine/blob/main/docs/api.md)
+
 ```python
 from datetime import datetime, timezone
 import astroceleste_engine as ace

{astroceleste_engine-0.0.2/crates/astroceleste-engine-py → astroceleste_engine-0.0.4}/README.md

@@ -7,6 +7,9 @@
 Python bindings for [astroceleste-engine](https://github.com/ffalcinelli/astroceleste-engine),
 astrological chart calculation on NASA JPL ephemerides, written in Rust.
 
+[Website and live demo](https://ffalcinelli.github.io/astroceleste-engine/) ·
+[API guide](https://github.com/ffalcinelli/astroceleste-engine/blob/main/docs/api.md)
+
 ```python
 from datetime import datetime, timezone
 import astroceleste_engine as ace

{astroceleste_engine-0.0.2 → astroceleste_engine-0.0.4}/crates/astroceleste-engine/README.md

@@ -12,11 +12,15 @@ It is the calculation core of [Astroceleste](https://astroceleste.it). The same
 on the server (Python bindings), in the desktop and mobile apps (native) and in the browser
 (WASM), so every platform computes the same chart down to the arcsecond.
 
+**[Website and live demo](https://ffalcinelli.github.io/astroceleste-engine/)** · [API docs](https://docs.rs/astroceleste-engine) ·
+[Guides](https://github.com/ffalcinelli/astroceleste-engine/tree/main/docs)
+
 > **Experimental (0.0.x):** the API may change in any release. Pin an exact version.
 
 > Status: the complete chart pipeline is ported and matches the reference implementation
 > on every golden chart: planets, lunar nodes, Chiron, Lilith, houses (Placidus, Whole Sign,
-> Equal, Porphyry), aspects and orbs, fixed stars, Arabic parts, temperament, lunar status,
+> Equal, Porphyry; Koch, Regiomontanus, Campanus, Topocentric, Alcabitius, Morinus and Vehlow
+> are checked against Swiss Ephemeris), aspects and orbs, fixed stars, Arabic parts, temperament, lunar status,
 > horary charts (planetary hours from computed sunrise and sunset), transits, synastry and
 > derived charts, with Python and WebAssembly bindings.
 
@@ -35,21 +39,32 @@ println!("{}", serde_json::to_string_pretty(&chart)?);
 ```
 
 Charts serialize to the same JSON as the Astroceleste API. Other entry points:
-`calculate_horary_chart`, `calculate_transit_chart`, `calculate_synastry` and
-`calculate_derived_chart`. In the browser or on mobile, load the kernel from memory with
+`calculate_horary_chart`, `calculate_transit_chart`, `calculate_synastry`,
+`calculate_derived_chart`, and for electional astrology `calculate_election_chart` and
+`search_elections` (the best moments over a span of time). In the browser or on mobile, load the kernel from memory with
 `Spk::from_bytes`.
 
 ## Bindings
 
 - **Python** (`pip install astroceleste-engine`, CPython ≥ 3.12): `Engine([kernel paths])`
-  with `.chart()`, `.horary()`, `.transit()`, plus `synastry()` and `derived_chart()`,
-  returning plain dicts. See [crates/astroceleste-engine-py](crates/astroceleste-engine-py).
+  with `.chart()`, `.horary()`, `.transit()`, `.election()`, `.elections()`, plus `synastry()` and `derived_chart()`,
+  returning plain dicts. See [crates/astroceleste-engine-py](https://github.com/ffalcinelli/astroceleste-engine/tree/main/crates/astroceleste-engine-py).
 - **JavaScript / WebAssembly** (`npm install astroceleste-engine`): the same API over
   kernels loaded from memory, for browsers and Node. See
-  [crates/astroceleste-engine-wasm](crates/astroceleste-engine-wasm).
+  [crates/astroceleste-engine-wasm](https://github.com/ffalcinelli/astroceleste-engine/tree/main/crates/astroceleste-engine-wasm).
 
 Both are tested against the same golden fixtures as the Rust crate.
 
+## Documentation
+
+- [API reference on docs.rs](https://docs.rs/astroceleste-engine)
+- [API guide](https://github.com/ffalcinelli/astroceleste-engine/blob/main/docs/api.md): request options, the chart JSON, error codes in every
+  language
+- [Ephemerides](https://github.com/ffalcinelli/astroceleste-engine/blob/main/docs/ephemerides.md): kernels, date coverage, loading from memory,
+  smaller excerpts for the web and mobile
+- [Accuracy](https://github.com/ffalcinelli/astroceleste-engine/blob/main/docs/accuracy.md): how every number is verified
+- [Architecture](https://github.com/ffalcinelli/astroceleste-engine/blob/main/docs/architecture.md): crates and calculation pipeline
+
 ## Layout
 
 | Path | Content |
@@ -63,78 +78,44 @@ Both are tested against the same golden fixtures as the Rust crate.
 | `scripts/make_spk_fixtures.py` | rebuilds the excerpt and the SPK reference states with `jplephem` |
 | `scripts/make_reduction_fixtures.py` | stage-by-stage reference values from Skyfield |
 | `scripts/gen_tables.py` | regenerates the embedded ΔT, nutation and Chiron tables |
+| `scripts/build-site.sh` | builds the landing site and live demo into `target/site/` |
+| `docs/` | guides |
+| `site/` | landing site and live demo, deployed to GitHub Pages |
+
+## Contributing
 
-## Development
+Contributions are welcome: see [CONTRIBUTING.md](https://github.com/ffalcinelli/astroceleste-engine/blob/main/CONTRIBUTING.md) for setup, the test
+suite and the rules that keep every platform identical. Report vulnerabilities privately,
+as described in [SECURITY.md](https://github.com/ffalcinelli/astroceleste-engine/blob/main/SECURITY.md). Maintainers release by pushing a version
+tag ([RELEASING.md](https://github.com/ffalcinelli/astroceleste-engine/blob/main/RELEASING.md)).
 
 ```bash
 cargo test --workspace --exclude astroceleste-engine-py   # uses the committed excerpt
-scripts/fetch-kernels.sh        # optional: full de440s (1849-2150), enables the full-range tests
+scripts/fetch-kernels.sh        # full de440s (1849-2150): enables the golden and full-range tests
 cargo clippy --workspace --all-targets -- -D warnings
-
-# Python bindings (in a virtualenv)
-pip install maturin pytest && maturin develop -m crates/astroceleste-engine-py/Cargo.toml
-pytest crates/astroceleste-engine-py/tests
-
-# WebAssembly bindings (needs wasm-pack and the wasm32-unknown-unknown target)
-wasm-pack build --target nodejs --out-dir pkg-node crates/astroceleste-engine-wasm
-node crates/astroceleste-engine-wasm/tests/golden.mjs
 ```
 
-## Releasing
-
-Releases are trunk-based: there are no release branches or release PRs. Pushing a
-`vX.Y.Z` tag on `main` publishes that version.
-
-1. Commits on `main` follow [Conventional Commits](https://www.conventionalcommits.org)
-   (`feat:`, `fix:`, `perf:`, `refactor:`, … and `!` for breaking changes). While the
-   version is 0.0.x, `feat`/`fix` bump the patch version and a breaking change bumps the
-   minor version.
-2. Prepare the release on `main`: run `release-plz update` (or edit by hand) to bump the
-   workspace version, the bindings' `astroceleste-engine` dependency version and
-   `CHANGELOG.md`, then commit as `chore: release vX.Y.Z` and push.
-3. Once CI is green, tag that commit and push the tag:
-   `git tag vX.Y.Z && git push origin vX.Y.Z`.
-4. The `Release` workflow checks that the tag is on `main`, matches the version in
-   `Cargo.toml` and has a `CHANGELOG.md` entry. It then publishes the crate to crates.io,
-   creates the GitHub Release from the changelog entry, and publishes the Python wheels
-   (Linux x86_64/aarch64 glibc and musl, macOS universal2, Windows x64, sdist) to PyPI
-   and the WebAssembly package to npm.
-
-Protect `v*` tags with a tag ruleset so only maintainers can trigger a release.
-
-All three registries use Trusted Publishing (OIDC), so no long-lived token is stored.
-crates.io and npm can only trust a workflow for a package that already exists, so the
-first release uses short-lived tokens instead:
-
-1. Create the `release`, `pypi` and `npm` environments in the repository settings
-   (optionally with required reviewers).
-2. **crates.io**: create an API token scoped to `publish-new` and `publish-update` for the
-   crate `astroceleste-engine`, with a short expiry, and store it as the
-   `CARGO_REGISTRY_TOKEN` secret of the `release` environment.
-3. **npm**: create a granular access token with publish rights and a short expiry, and store
-   it as the `NPM_TOKEN` secret of the `npm` environment.
-4. **PyPI**: add a *pending* trusted publisher for project `astroceleste-engine` (workflow
-   `release.yml`, environment `pypi`). No token is needed.
-5. Push the `vX.Y.Z` tag for the version in `Cargo.toml`.
-6. Once the packages exist, add the trusted publisher on crates.io (crate settings →
-   *Trusted Publishing*: this repository, workflow `release.yml`, environment `release`)
-   and on npm (package settings: workflow `release.yml`, environment `npm`). Then delete
-   both secrets and revoke the tokens. The workflow prefers OIDC whenever it is available.
-
 ## Ephemerides
 
 The engine reads NASA JPL SPK kernels (DE440s by default, DE441 for dates outside 1849–2150).
-Dates outside the loaded kernels are reported as errors, never approximated.
+Dates outside the loaded kernels are reported as errors, never approximated. See
+[docs/ephemerides.md](https://github.com/ffalcinelli/astroceleste-engine/blob/main/docs/ephemerides.md) for coverage, sizes and excerpts.
 
 ## License
 
 Licensed under either of
 
-- Apache License, Version 2.0 ([LICENSE-APACHE](LICENSE-APACHE))
-- MIT license ([LICENSE-MIT](LICENSE-MIT))
+- Apache License, Version 2.0 ([LICENSE-APACHE](https://github.com/ffalcinelli/astroceleste-engine/blob/main/LICENSE-APACHE))
+- MIT license ([LICENSE-MIT](https://github.com/ffalcinelli/astroceleste-engine/blob/main/LICENSE-MIT))
 
 at your option.
 
+The astronomical reduction (ΔT, IAU 2000A nutation, IAU 2006 precession, light-time,
+deflection and aberration) is ported from [Skyfield](https://github.com/skyfielders/python-skyfield)
+by Brandon Rhodes, used under the MIT license: see
+[NOTICE](https://github.com/ffalcinelli/astroceleste-engine/blob/main/NOTICE), which is shipped in
+every package.
+
 Unless you explicitly state otherwise, any contribution intentionally submitted for inclusion
 in this work, as defined in the Apache-2.0 license, shall be dual licensed as above, without
 any additional terms or conditions.

{astroceleste_engine-0.0.2 → astroceleste_engine-0.0.4}/crates/astroceleste-engine/src/almanac.rs

@@ -155,7 +155,55 @@ pub fn rise_set(
     let t_start = Time::from_ut1(jd_utc - 1.5);
     let t_end = Time::from_ut1(jd_utc + 1.5);
     let events = find_transitions(kernel, &site, t_start.tt(), t_end.tt())?;
+    Ok(select_rise_set(&events, jd_utc))
+}
+
+/// Sunrises and sunsets over a span, found once for all the days in it.
+pub(crate) struct SunEvents {
+    /// (TT Julian date, whether it is a sunrise), in time order.
+    events: Vec<(f64, bool)>,
+    /// TT span searched.
+    span: (f64, f64),
+}
+
+impl SunEvents {
+    /// Every sunrise and sunset from UT1 Julian date `jd0` to `jd1`, when a single kernel
+    /// covers the whole span (`None` otherwise).
+    pub fn find(
+        kernels: &KernelSet,
+        jd0: f64,
+        jd1: f64,
+        latitude: f64,
+        longitude: f64,
+    ) -> Result<Option<Self>, EngineError> {
+        let kernel = require_kernel(kernels, jd0)?;
+        if !(kernel.start_jd..=kernel.end_jd).contains(&jd1) {
+            return Ok(None);
+        }
+        let site = Site::new(latitude, longitude);
+        let span = (Time::from_ut1(jd0).tt(), Time::from_ut1(jd1).tt());
+        let events = find_transitions(kernel, &site, span.0, span.1)?;
+        Ok(Some(SunEvents { events, span }))
+    }
+
+    /// [`rise_set`] for `jd_utc`, from the events of its ±1.5 day window; `None` when
+    /// the window is not inside the span searched.
+    pub fn rise_set(&self, jd_utc: f64) -> Option<(f64, f64, f64)> {
+        let (t0, t1) = (
+            Time::from_ut1(jd_utc - 1.5).tt(),
+            Time::from_ut1(jd_utc + 1.5).tt(),
+        );
+        if t0 < self.span.0 || t1 > self.span.1 {
+            return None;
+        }
+        let from = self.events.partition_point(|e| e.0 < t0);
+        let to = self.events.partition_point(|e| e.0 <= t1);
+        Some(select_rise_set(&self.events[from..to], jd_utc))
+    }
+}
 
+/// The day's sunrise, sunset and next sunrise among the events around `jd_utc`.
+fn select_rise_set(events: &[(f64, bool)], jd_utc: f64) -> (f64, f64, f64) {
     let ut1 = |jd_tt: f64| Time::from_tt_jd(jd_tt).ut1();
     let sunrises: Vec<f64> = events.iter().filter(|e| e.1).map(|e| ut1(e.0)).collect();
     let sunsets: Vec<f64> = events.iter().filter(|e| !e.1).map(|e| ut1(e.0)).collect();
@@ -176,5 +224,5 @@ pub fn rise_set(
         .copied()
         .find(|&s| s > rise + 0.1)
         .unwrap_or(rise + 1.0);
-    Ok((rise, set, next_rise))
+    (rise, set, next_rise)
 }

{astroceleste_engine-0.0.2 → astroceleste_engine-0.0.4}/crates/astroceleste-engine/src/chart.rs

@@ -8,7 +8,7 @@ use crate::aspects::{natal_aspects, Aspect, OrbSettings, Point};
 use crate::ephemeris::KernelSet;
 use crate::error::EngineError;
 use crate::fixed_stars::{fixed_stars, FixedStarPosition};
-use crate::houses::{calculate_houses, HouseSystem};
+use crate::houses::{calculate_houses, HouseSystem, Houses};
 use crate::instant::UtcInstant;
 use crate::lots::{arabic_parts, Lot};
 use crate::lunar::{lunar_status, LunarStatus};
@@ -16,7 +16,7 @@ use crate::planets::calculate_planets;
 use crate::symbolic::symbolic_degree_number;
 use crate::temperament::{temperament, Temperament};
 use crate::zodiac::{
-    ayanamsa, ayanamsa_info, determine_house, longitude_to_zodiac, DEFAULT_AYANAMSA,
+    ayanamsa, ayanamsa_info, determine_house, longitude_to_zodiac, AyanamsaInfo, DEFAULT_AYANAMSA,
 };
 
 /// Every body a complete chart carries; missing ones are reported in
@@ -200,15 +200,28 @@ fn symbol_of(name: &str) -> &'static str {
     }
 }
 
-/// Compute a chart (`calculate_chart_data`).
-pub fn calculate_chart(kernels: &KernelSet, req: &ChartRequest) -> Result<Chart, EngineError> {
+/// The positions part of a chart: placements and house cusps, without aspects, fixed
+/// stars, lots or temperament. Electional searches evaluate thousands of these.
+pub(crate) struct Sky {
+    pub zodiac_type: &'static str,
+    pub is_sidereal: bool,
+    pub ayanamsa_code: &'static str,
+    pub info: AyanamsaInfo,
+    pub jd: f64,
+    /// Cusps 1-12, degrees.
+    pub cusps: Vec<f64>,
+    pub house_cusps: Vec<HouseCusp>,
+    pub planets: Vec<Placement>,
+}
+
+/// Placements and houses of a request (the first half of [`calculate_chart`]).
+pub(crate) fn sky(kernels: &KernelSet, req: &ChartRequest) -> Result<Sky, EngineError> {
     let zodiac_type = match req.zodiac_type.trim().to_lowercase().as_str() {
         "sidereal" => "sidereal",
         _ => "tropical",
     };
     let is_sidereal = zodiac_type == "sidereal";
     let ayanamsa_code = ayanamsa(req.ayanamsa).code;
-    let orbs = OrbSettings::merge(req.orb_settings)?;
 
     let jd = req.instant.julian_day();
     let info = ayanamsa_info(jd, ayanamsa_code);
@@ -242,16 +255,34 @@ pub fn calculate_chart(kernels: &KernelSet, req: &ChartRequest) -> Result<Chart,
         })
         .collect();
 
-    let mut raw: Vec<(&'static str, f64, f64, bool)> = engine
+    let raw: Vec<(&'static str, f64, f64, bool)> = engine
         .bodies
         .iter()
         .map(|b| (b.name, b.longitude, b.speed, b.is_retrograde))
         .collect();
+    let planets = placements(raw, &houses);
+
+    Ok(Sky {
+        zodiac_type,
+        is_sidereal,
+        ayanamsa_code,
+        info,
+        jd,
+        cusps,
+        house_cusps,
+        planets,
+    })
+}
+
+/// Placements of bodies given as (name, longitude, speed, retrograde), followed by the
+/// Ascendant and the Midheaven, with their houses.
+pub(crate) fn placements(
+    mut raw: Vec<(&'static str, f64, f64, bool)>,
+    houses: &Houses,
+) -> Vec<Placement> {
     raw.push(("Ascendant", houses.ascendant, 0.0, false));
     raw.push(("Midheaven", houses.midheaven, 0.0, false));
-
-    let planets: Vec<Placement> = raw
-        .iter()
+    raw.iter()
         .map(|&(name, lon, speed, is_retrograde)| {
             let z = longitude_to_zodiac(lon);
             Placement {
@@ -262,13 +293,28 @@ pub fn calculate_chart(kernels: &KernelSet, req: &ChartRequest) -> Result<Chart,
                 degree: z.degree,
                 minute: z.minute,
                 ecliptic_longitude: lon,
-                house: determine_house(lon, &cusps),
+                house: determine_house(lon, &houses.cusps),
                 speed,
                 is_retrograde,
                 symbolic_degree: symbolic_degree_number(z.degree, z.minute),
             }
         })
-        .collect();
+        .collect()
+}
+
+/// Compute a chart (`calculate_chart_data`).
+pub fn calculate_chart(kernels: &KernelSet, req: &ChartRequest) -> Result<Chart, EngineError> {
+    let orbs = OrbSettings::merge(req.orb_settings)?;
+    let Sky {
+        zodiac_type,
+        is_sidereal,
+        ayanamsa_code,
+        info,
+        jd,
+        cusps,
+        house_cusps,
+        planets,
+    } = sky(kernels, req)?;
     let points: Vec<Point> = planets
         .iter()
         .map(|p| Point {