rust-zmanim 0.1.16

Rust Zmanim Library
Documentation 
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78

# \[WIP\] rust-zmanim
Calculate different astronomical times including sunrise and sunset and Jewish *zmanim* or religious times for prayers and other Jewish religious duties.

The [astronomical_calculator] provides non-religious astronomical / solar calculations such as sunrise, sunset and twilight.

The [zmanim_calculator] contains the basics for *zmanim* calculations.

The [complex_zmanim_calendar] provides a stateful struct with many premade *zmanim* calculations, both built on the [zmanim_calculator] API.

This project is a port from pinnymz's [python-zmanim project](https://github.com/pinnymz/python-zmanim) and Eliyahu Hershfeld's [KosherJava project](https://github.com/KosherJava/zmanim). Much of the code is ported directly from `python-zmanim` and `KosherJava`, and almost all of the documentation is from `KosherJava`

See the [KosherJava site](https://kosherjava.com) for additional information on the original Java project and *zmanim* in general.

**Note:** It is important to read the technical notes on top of the [astronomical_calculator] documentation.

### Disclaimer
I did my best to get accurate results using standardized astronomical calculations. Please use care when using the library for *halacha lemaaseh* applications. **Also**, despite the great *precision* of the returned values, the *accuracy* is nowhere near that. To quote the NOAA, whose algorithm this crate uses, "due to variations in atmospheric composition, temperature, pressure and conditions, observed values may vary from calculations"

## Example (more examples in /examples)
```rust
use chrono::TimeDelta;
use rust_zmanim::prelude::*;

// the time in the DateTime will be ignored in zmanim calculations
let dt = chrono_tz::Asia::Jerusalem
    .with_ymd_and_hms(2025, 7, 29, 10, 30, 26)
    .unwrap();

// your location here
let beit_meir = GeoLocation {
    latitude: 31.7975,
    longitude: 35.0345,
    elevation: 526.0,
    timezone: chrono_tz::Asia::Jerusalem,
};

// the `zmanim_calculator` lets you make any custom tzais, alos, etc
if let Some(tzais_pi_degrees) = zmanim_calculator::tzais(
    &dt,
    &beit_meir,
    false,
    &ZmanOffset::Degrees(std::f64::consts::PI),
) {
    assert_eq!(
        tzais_pi_degrees.to_string(),
        "2025-07-29 19:50:30.090272127 IDT"
    );
}

// there is also a `ComplexZmanimCalendar` struct which stores the date and
// location, convenient for getting many zmanim for the same point in 4D space.
// It also has many common zmanim pre-made
let czc = ComplexZmanimCalendar {
    geo_location: &beit_meir,
    date: &dt,
    use_elevation: UseElevation::No,
};

if let Some(alos120) = czc.alos_120_minutes() {
    assert_eq!(alos120.to_string(), "2025-07-29 03:53:39.574572512 IDT");
};

if let Some(sz18) = czc.shaah_zmanis_18_degrees() {
    // 01:24:14.106060472
    assert_eq!(sz18, TimeDelta::nanoseconds(5054106060472));
}

// the calculations will return `None` if the specified solar event will not
// occur
let north_pole = GeoLocation {
    latitude: 90.0,
    longitude: 0.0,
    elevation: 0.0,
    timezone: chrono_tz::UTC,
};
let polar_sunset = zmanim_calculator::shkia(&dt, &north_pole, false);
assert!(polar_sunset.is_none());
```