hilal-visibility 0.1.0__tar.gz
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- hilal_visibility-0.1.0/.gitignore +30 -0
- hilal_visibility-0.1.0/LICENSE +21 -0
- hilal_visibility-0.1.0/PKG-INFO +135 -0
- hilal_visibility-0.1.0/PYPI_README.md +102 -0
- hilal_visibility-0.1.0/README.md +217 -0
- hilal_visibility-0.1.0/hilal_visibility/__init__.py +21 -0
- hilal_visibility-0.1.0/hilal_visibility/contours.py +468 -0
- hilal_visibility-0.1.0/hilal_visibility/criteria.py +356 -0
- hilal_visibility-0.1.0/hilal_visibility/ephem.py +375 -0
- hilal_visibility-0.1.0/hilal_visibility/grid.py +536 -0
- hilal_visibility-0.1.0/hilal_visibility/hijri.py +66 -0
- hilal_visibility-0.1.0/hilal_visibility/narrative.py +266 -0
- hilal_visibility-0.1.0/hilal_visibility/py.typed +0 -0
- hilal_visibility-0.1.0/hilal_visibility/quantities.py +108 -0
- hilal_visibility-0.1.0/hilal_visibility/render.py +125 -0
- hilal_visibility-0.1.0/hilal_visibility/tests/__init__.py +0 -0
- hilal_visibility-0.1.0/hilal_visibility/tests/test_acceptance_muharram1445.py +116 -0
- hilal_visibility-0.1.0/hilal_visibility/tests/test_contours.py +555 -0
- hilal_visibility-0.1.0/hilal_visibility/tests/test_criteria.py +460 -0
- hilal_visibility-0.1.0/hilal_visibility/tests/test_ephem.py +318 -0
- hilal_visibility-0.1.0/hilal_visibility/tests/test_grid.py +218 -0
- hilal_visibility-0.1.0/hilal_visibility/tests/test_hijri.py +49 -0
- hilal_visibility-0.1.0/hilal_visibility/tests/test_narrative.py +175 -0
- hilal_visibility-0.1.0/hilal_visibility/tests/test_render.py +42 -0
- hilal_visibility-0.1.0/hilal_visibility/tests/test_validate_metrics.py +134 -0
- hilal_visibility-0.1.0/hilal_visibility/tests/test_validate_records.py +129 -0
- hilal_visibility-0.1.0/hilal_visibility/tests/test_webdata.py +115 -0
- hilal_visibility-0.1.0/hilal_visibility/validate/__init__.py +18 -0
- hilal_visibility-0.1.0/hilal_visibility/validate/data/.mphys-moon-commit +1 -0
- hilal_visibility-0.1.0/hilal_visibility/validate/data/LICENSE-mphys-moon +21 -0
- hilal_visibility-0.1.0/hilal_visibility/validate/data/SOURCES.md +93 -0
- hilal_visibility-0.1.0/hilal_visibility/validate/data/alrefay2018.csv +477 -0
- hilal_visibility-0.1.0/hilal_visibility/validate/data/yallop1997_table4.csv +296 -0
- hilal_visibility-0.1.0/hilal_visibility/validate/evaluate.py +142 -0
- hilal_visibility-0.1.0/hilal_visibility/validate/metrics.py +305 -0
- hilal_visibility-0.1.0/hilal_visibility/validate/records.py +289 -0
- hilal_visibility-0.1.0/hilal_visibility/webdata.py +137 -0
- hilal_visibility-0.1.0/pyproject.toml +73 -0
|
@@ -0,0 +1,30 @@
|
|
|
1
|
+
# Python
|
|
2
|
+
__pycache__/
|
|
3
|
+
*.pyc
|
|
4
|
+
.venv/
|
|
5
|
+
*.egg-info/
|
|
6
|
+
.pytest_cache/
|
|
7
|
+
|
|
8
|
+
# Ephemeris kernels (downloaded by setup, ~32 MB)
|
|
9
|
+
data/ephemeris/*.bsp
|
|
10
|
+
|
|
11
|
+
# Generated grids are regenerable (plan §5 allows committed OR Actions
|
|
12
|
+
# artifact — we take the artifact path; M1 adds a slim web format)
|
|
13
|
+
data/months/
|
|
14
|
+
data/scratch/
|
|
15
|
+
|
|
16
|
+
# Node / Astro (M1+)
|
|
17
|
+
node_modules/
|
|
18
|
+
site/dist/
|
|
19
|
+
|
|
20
|
+
# OS
|
|
21
|
+
.DS_Store
|
|
22
|
+
|
|
23
|
+
# Site
|
|
24
|
+
site/node_modules/
|
|
25
|
+
site/dist/
|
|
26
|
+
site/.astro/
|
|
27
|
+
|
|
28
|
+
# Python packaging
|
|
29
|
+
dist/
|
|
30
|
+
build/
|
|
@@ -0,0 +1,21 @@
|
|
|
1
|
+
MIT License
|
|
2
|
+
|
|
3
|
+
Copyright (c) 2026 Analytica Data Science Solutions
|
|
4
|
+
|
|
5
|
+
Permission is hereby granted, free of charge, to any person obtaining a copy
|
|
6
|
+
of this software and associated documentation files (the "Software"), to deal
|
|
7
|
+
in the Software without restriction, including without limitation the rights
|
|
8
|
+
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
|
|
9
|
+
copies of the Software, and to permit persons to whom the Software is
|
|
10
|
+
furnished to do so, subject to the following conditions:
|
|
11
|
+
|
|
12
|
+
The above copyright notice and this permission notice shall be included in all
|
|
13
|
+
copies or substantial portions of the Software.
|
|
14
|
+
|
|
15
|
+
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
|
|
16
|
+
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
|
|
17
|
+
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
|
|
18
|
+
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
|
|
19
|
+
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
|
|
20
|
+
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
|
|
21
|
+
SOFTWARE.
|
|
@@ -0,0 +1,135 @@
|
|
|
1
|
+
Metadata-Version: 2.5
|
|
2
|
+
Name: hilal-visibility
|
|
3
|
+
Version: 0.1.0
|
|
4
|
+
Summary: Crescent moon (hilal) visibility kernel: topocentric lunar circumstances from JPL DE440s and the Yallop, Odeh and SAAO visibility criteria, for single locations or global zone grids.
|
|
5
|
+
Project-URL: Homepage, https://hilal.analyticadss.com
|
|
6
|
+
Author: Aous Abdo
|
|
7
|
+
License-Expression: MIT
|
|
8
|
+
License-File: LICENSE
|
|
9
|
+
License-File: hilal_visibility/validate/data/LICENSE-mphys-moon
|
|
10
|
+
Keywords: astronomy,crescent,ephemeris,hijri,hilal,islamic calendar,lunar crescent visibility,moon,new moon,odeh,yallop
|
|
11
|
+
Classifier: Development Status :: 4 - Beta
|
|
12
|
+
Classifier: Intended Audience :: Developers
|
|
13
|
+
Classifier: Intended Audience :: Science/Research
|
|
14
|
+
Classifier: Operating System :: OS Independent
|
|
15
|
+
Classifier: Programming Language :: Python :: 3
|
|
16
|
+
Classifier: Programming Language :: Python :: 3 :: Only
|
|
17
|
+
Classifier: Programming Language :: Python :: 3.12
|
|
18
|
+
Classifier: Programming Language :: Python :: 3.13
|
|
19
|
+
Classifier: Topic :: Scientific/Engineering :: Astronomy
|
|
20
|
+
Classifier: Typing :: Typed
|
|
21
|
+
Requires-Python: >=3.12
|
|
22
|
+
Requires-Dist: contourpy>=1.3
|
|
23
|
+
Requires-Dist: numpy<2.5,>=1.26
|
|
24
|
+
Requires-Dist: pillow>=10.0
|
|
25
|
+
Requires-Dist: shapely>=2.0
|
|
26
|
+
Requires-Dist: skyfield>=1.49
|
|
27
|
+
Provides-Extra: dev
|
|
28
|
+
Requires-Dist: matplotlib>=3.8; extra == 'dev'
|
|
29
|
+
Requires-Dist: pytest>=8.0; extra == 'dev'
|
|
30
|
+
Provides-Extra: plot
|
|
31
|
+
Requires-Dist: matplotlib>=3.8; extra == 'plot'
|
|
32
|
+
Description-Content-Type: text/markdown
|
|
33
|
+
|
|
34
|
+
# hilal-visibility
|
|
35
|
+
|
|
36
|
+
Crescent moon (hilal) visibility kernel. It computes the circumstances of the
|
|
37
|
+
young crescent for any location and evening from the JPL DE440s ephemeris
|
|
38
|
+
(via [Skyfield](https://rhodesmill.org/skyfield/)), and classifies them under
|
|
39
|
+
the published visibility criteria. Each criterion is fed quantities in the
|
|
40
|
+
convention its constants were fitted on:
|
|
41
|
+
|
|
42
|
+
| Key | Source |
|
|
43
|
+
|---|---|
|
|
44
|
+
| `yallop` | Yallop (1997), NAO Technical Note 69, q-test (geocentric ARCV + TN 69 width W′) |
|
|
45
|
+
| `odeh` | Odeh (2004), Experimental Astronomy 18, V-test (topocentric airless ARCV + W) |
|
|
46
|
+
| `saao` | Caldwell & Laney (2001), SAAO lower-limb DALT criterion |
|
|
47
|
+
| `shaukat` | reconstruction of the moonsighting.com criterion (not a published rule) |
|
|
48
|
+
| `raw` | quantities plus q and V, no zone |
|
|
49
|
+
|
|
50
|
+
It also builds vectorized global zone grids, turns them into GeoJSON
|
|
51
|
+
contours, labels astronomical Hijri months, and includes a validation harness
|
|
52
|
+
against two historical sighting datasets. It is the compute kernel behind
|
|
53
|
+
<https://hilal.analyticadss.com>.
|
|
54
|
+
|
|
55
|
+
## Install
|
|
56
|
+
|
|
57
|
+
```bash
|
|
58
|
+
pip install hilal-visibility
|
|
59
|
+
pip install "hilal-visibility[plot]" # adds matplotlib for diagnostic PNG maps
|
|
60
|
+
```
|
|
61
|
+
|
|
62
|
+
Requires Python 3.12 or newer.
|
|
63
|
+
|
|
64
|
+
## Example: one location, one evening
|
|
65
|
+
|
|
66
|
+
```python
|
|
67
|
+
from datetime import date
|
|
68
|
+
|
|
69
|
+
from hilal_visibility.criteria import CRITERIA
|
|
70
|
+
from hilal_visibility.ephem import compute_evening, find_new_moon
|
|
71
|
+
|
|
72
|
+
# The new moon nearest 9 December 2026, and the evening of that day.
|
|
73
|
+
conjunction = find_new_moon(date(2026, 12, 9))
|
|
74
|
+
evening = conjunction.date()
|
|
75
|
+
|
|
76
|
+
# Mecca (lat, lon east-positive, elevation in metres).
|
|
77
|
+
r = compute_evening(21.4225, 39.8262, evening, conjunction=conjunction, elevation_m=277)
|
|
78
|
+
|
|
79
|
+
print(f"conjunction {conjunction:%Y-%m-%d %H:%M} UT")
|
|
80
|
+
print(f"evening of {evening}")
|
|
81
|
+
print(f"sunset {r.sunset_utc:%H:%M} UT, moonset {r.moonset_utc:%H:%M} UT, lag {r.lag_minutes:.0f} min")
|
|
82
|
+
p = r.params
|
|
83
|
+
print(f"moon age {p.moon_age_hours:.1f} h at sunset")
|
|
84
|
+
print(f"ARCV {p.arcv:.2f}° ARCL {p.arcl:.2f}° DAZ {p.daz:.2f}° W {p.w:.2f}′")
|
|
85
|
+
for name in ("yallop", "odeh", "saao"):
|
|
86
|
+
res = CRITERIA[name](p)
|
|
87
|
+
score = f"q = {res.q:+.3f}" if res.q is not None else f"V = {res.v:+.2f}" if res.v is not None else ""
|
|
88
|
+
print(f"{name:7s} zone {res.zone.value} {score}")
|
|
89
|
+
```
|
|
90
|
+
|
|
91
|
+
Output:
|
|
92
|
+
|
|
93
|
+
```
|
|
94
|
+
conjunction 2026-12-09 00:51 UT
|
|
95
|
+
evening of 2026-12-09
|
|
96
|
+
sunset 14:41 UT, moonset 14:54 UT, lag 13 min
|
|
97
|
+
moon age 13.8 h at sunset
|
|
98
|
+
ARCV 2.72° ARCL 7.28° DAZ -6.75° W 0.12′
|
|
99
|
+
yallop zone F q = -0.740
|
|
100
|
+
odeh zone D V = -3.70
|
|
101
|
+
saao zone D
|
|
102
|
+
```
|
|
103
|
+
|
|
104
|
+
Each criterion has its own zone letters, and the letters do not mean the same
|
|
105
|
+
thing across criteria. Here Yallop's F is "below the Danjon limit", Odeh's D
|
|
106
|
+
is "not visible", and SAAO's D is "not visible even with optical aid". The
|
|
107
|
+
docstring of `hilal_visibility.criteria` defines every zone.
|
|
108
|
+
`hilal_visibility.grid.compute_evening_grids` runs the same calculation over
|
|
109
|
+
the whole globe.
|
|
110
|
+
|
|
111
|
+
## The ephemeris file
|
|
112
|
+
|
|
113
|
+
The first call that needs the ephemeris downloads JPL's `de440s.bsp` (about
|
|
114
|
+
32 MB) through Skyfield and caches it. The cache directory is, in order:
|
|
115
|
+
|
|
116
|
+
1. `$HILAL_EPHEMERIS_DIR`, if set;
|
|
117
|
+
2. `data/ephemeris/` when running from a source checkout of the repository;
|
|
118
|
+
3. otherwise a per-user cache directory: `~/.cache/hilal-visibility` on Linux
|
|
119
|
+
(or `$XDG_CACHE_HOME/hilal-visibility`), `~/Library/Caches/hilal-visibility`
|
|
120
|
+
on macOS, `%LOCALAPPDATA%\hilal-visibility` on Windows.
|
|
121
|
+
|
|
122
|
+
`hilal_visibility.ephem.ephemeris_dir()` returns the directory in use. To work
|
|
123
|
+
offline, put a copy of `de440s.bsp` there.
|
|
124
|
+
|
|
125
|
+
## Validation data
|
|
126
|
+
|
|
127
|
+
`hilal_visibility.validate` scores the criteria against Yallop (1997) Table 4
|
|
128
|
+
(295 records) and Alrefay et al. (2018) (476 records). Both CSVs (about 50 KB)
|
|
129
|
+
ship inside the package. Their provenance is in
|
|
130
|
+
`hilal_visibility/validate/data/SOURCES.md`, next to the MIT notice of the
|
|
131
|
+
transcription they were taken from.
|
|
132
|
+
|
|
133
|
+
## Licence
|
|
134
|
+
|
|
135
|
+
MIT. Copyright (c) 2026 Analytica Data Science Solutions.
|
|
@@ -0,0 +1,102 @@
|
|
|
1
|
+
# hilal-visibility
|
|
2
|
+
|
|
3
|
+
Crescent moon (hilal) visibility kernel. It computes the circumstances of the
|
|
4
|
+
young crescent for any location and evening from the JPL DE440s ephemeris
|
|
5
|
+
(via [Skyfield](https://rhodesmill.org/skyfield/)), and classifies them under
|
|
6
|
+
the published visibility criteria. Each criterion is fed quantities in the
|
|
7
|
+
convention its constants were fitted on:
|
|
8
|
+
|
|
9
|
+
| Key | Source |
|
|
10
|
+
|---|---|
|
|
11
|
+
| `yallop` | Yallop (1997), NAO Technical Note 69, q-test (geocentric ARCV + TN 69 width W′) |
|
|
12
|
+
| `odeh` | Odeh (2004), Experimental Astronomy 18, V-test (topocentric airless ARCV + W) |
|
|
13
|
+
| `saao` | Caldwell & Laney (2001), SAAO lower-limb DALT criterion |
|
|
14
|
+
| `shaukat` | reconstruction of the moonsighting.com criterion (not a published rule) |
|
|
15
|
+
| `raw` | quantities plus q and V, no zone |
|
|
16
|
+
|
|
17
|
+
It also builds vectorized global zone grids, turns them into GeoJSON
|
|
18
|
+
contours, labels astronomical Hijri months, and includes a validation harness
|
|
19
|
+
against two historical sighting datasets. It is the compute kernel behind
|
|
20
|
+
<https://hilal.analyticadss.com>.
|
|
21
|
+
|
|
22
|
+
## Install
|
|
23
|
+
|
|
24
|
+
```bash
|
|
25
|
+
pip install hilal-visibility
|
|
26
|
+
pip install "hilal-visibility[plot]" # adds matplotlib for diagnostic PNG maps
|
|
27
|
+
```
|
|
28
|
+
|
|
29
|
+
Requires Python 3.12 or newer.
|
|
30
|
+
|
|
31
|
+
## Example: one location, one evening
|
|
32
|
+
|
|
33
|
+
```python
|
|
34
|
+
from datetime import date
|
|
35
|
+
|
|
36
|
+
from hilal_visibility.criteria import CRITERIA
|
|
37
|
+
from hilal_visibility.ephem import compute_evening, find_new_moon
|
|
38
|
+
|
|
39
|
+
# The new moon nearest 9 December 2026, and the evening of that day.
|
|
40
|
+
conjunction = find_new_moon(date(2026, 12, 9))
|
|
41
|
+
evening = conjunction.date()
|
|
42
|
+
|
|
43
|
+
# Mecca (lat, lon east-positive, elevation in metres).
|
|
44
|
+
r = compute_evening(21.4225, 39.8262, evening, conjunction=conjunction, elevation_m=277)
|
|
45
|
+
|
|
46
|
+
print(f"conjunction {conjunction:%Y-%m-%d %H:%M} UT")
|
|
47
|
+
print(f"evening of {evening}")
|
|
48
|
+
print(f"sunset {r.sunset_utc:%H:%M} UT, moonset {r.moonset_utc:%H:%M} UT, lag {r.lag_minutes:.0f} min")
|
|
49
|
+
p = r.params
|
|
50
|
+
print(f"moon age {p.moon_age_hours:.1f} h at sunset")
|
|
51
|
+
print(f"ARCV {p.arcv:.2f}° ARCL {p.arcl:.2f}° DAZ {p.daz:.2f}° W {p.w:.2f}′")
|
|
52
|
+
for name in ("yallop", "odeh", "saao"):
|
|
53
|
+
res = CRITERIA[name](p)
|
|
54
|
+
score = f"q = {res.q:+.3f}" if res.q is not None else f"V = {res.v:+.2f}" if res.v is not None else ""
|
|
55
|
+
print(f"{name:7s} zone {res.zone.value} {score}")
|
|
56
|
+
```
|
|
57
|
+
|
|
58
|
+
Output:
|
|
59
|
+
|
|
60
|
+
```
|
|
61
|
+
conjunction 2026-12-09 00:51 UT
|
|
62
|
+
evening of 2026-12-09
|
|
63
|
+
sunset 14:41 UT, moonset 14:54 UT, lag 13 min
|
|
64
|
+
moon age 13.8 h at sunset
|
|
65
|
+
ARCV 2.72° ARCL 7.28° DAZ -6.75° W 0.12′
|
|
66
|
+
yallop zone F q = -0.740
|
|
67
|
+
odeh zone D V = -3.70
|
|
68
|
+
saao zone D
|
|
69
|
+
```
|
|
70
|
+
|
|
71
|
+
Each criterion has its own zone letters, and the letters do not mean the same
|
|
72
|
+
thing across criteria. Here Yallop's F is "below the Danjon limit", Odeh's D
|
|
73
|
+
is "not visible", and SAAO's D is "not visible even with optical aid". The
|
|
74
|
+
docstring of `hilal_visibility.criteria` defines every zone.
|
|
75
|
+
`hilal_visibility.grid.compute_evening_grids` runs the same calculation over
|
|
76
|
+
the whole globe.
|
|
77
|
+
|
|
78
|
+
## The ephemeris file
|
|
79
|
+
|
|
80
|
+
The first call that needs the ephemeris downloads JPL's `de440s.bsp` (about
|
|
81
|
+
32 MB) through Skyfield and caches it. The cache directory is, in order:
|
|
82
|
+
|
|
83
|
+
1. `$HILAL_EPHEMERIS_DIR`, if set;
|
|
84
|
+
2. `data/ephemeris/` when running from a source checkout of the repository;
|
|
85
|
+
3. otherwise a per-user cache directory: `~/.cache/hilal-visibility` on Linux
|
|
86
|
+
(or `$XDG_CACHE_HOME/hilal-visibility`), `~/Library/Caches/hilal-visibility`
|
|
87
|
+
on macOS, `%LOCALAPPDATA%\hilal-visibility` on Windows.
|
|
88
|
+
|
|
89
|
+
`hilal_visibility.ephem.ephemeris_dir()` returns the directory in use. To work
|
|
90
|
+
offline, put a copy of `de440s.bsp` there.
|
|
91
|
+
|
|
92
|
+
## Validation data
|
|
93
|
+
|
|
94
|
+
`hilal_visibility.validate` scores the criteria against Yallop (1997) Table 4
|
|
95
|
+
(295 records) and Alrefay et al. (2018) (476 records). Both CSVs (about 50 KB)
|
|
96
|
+
ship inside the package. Their provenance is in
|
|
97
|
+
`hilal_visibility/validate/data/SOURCES.md`, next to the MIT notice of the
|
|
98
|
+
transcription they were taken from.
|
|
99
|
+
|
|
100
|
+
## Licence
|
|
101
|
+
|
|
102
|
+
MIT. Copyright (c) 2026 Analytica Data Science Solutions.
|
|
@@ -0,0 +1,217 @@
|
|
|
1
|
+
# Hilal Visibility Platform
|
|
2
|
+
|
|
3
|
+
A scientific crescent-moon (hilal) visibility reference: multi-criterion
|
|
4
|
+
interactive visibility maps, per-location answers, transparent methodology,
|
|
5
|
+
and — the differentiator — published validation of every criterion against
|
|
6
|
+
historical sighting reports.
|
|
7
|
+
|
|
8
|
+
Full spec: [hilal-platform-plan.md](hilal-platform-plan.md).
|
|
9
|
+
|
|
10
|
+
## Status
|
|
11
|
+
|
|
12
|
+
| Milestone | Status |
|
|
13
|
+
|---|---|
|
|
14
|
+
| **M0 — Compute kernel** | ✅ done (93 tests) |
|
|
15
|
+
| **M1 — Static maps site (Astro + MapLibre)** | ✅ done |
|
|
16
|
+
| **M2 — My Location (astronomy-engine worker)** | ✅ done (38 site tests) |
|
|
17
|
+
| **M3 — Methodology + Learn pages** | ✅ done (bilingual, 24 content-guard tests) |
|
|
18
|
+
| **M4 — Validation vs. observation database** | ✅ done (bilingual results page, 169 + 86 tests) |
|
|
19
|
+
| M5 — Reports (Supabase) | not started |
|
|
20
|
+
|
|
21
|
+
## Layout
|
|
22
|
+
|
|
23
|
+
```
|
|
24
|
+
hilal_visibility/ Python 3.12 compute kernel (Skyfield + JPL DE440s),
|
|
25
|
+
published to PyPI as `hilal-visibility`
|
|
26
|
+
quantities.py CrescentParams + shared math (TN 69 W', refraction, ARCL)
|
|
27
|
+
criteria.py yallop, odeh, saao, shaukat, raw (zones A–F, X)
|
|
28
|
+
ephem.py exact single-point circumstances (all conventions)
|
|
29
|
+
grid.py vectorized global zone grids (~4 s per evening at 0.5°)
|
|
30
|
+
hijri.py astronomical Hijri month labeling (lunation count)
|
|
31
|
+
narrative.py auto-generated en/ar narrative from grids
|
|
32
|
+
validate/ observation records, evaluation harness, metrics
|
|
33
|
+
data/ vendored crescent-sighting records + SOURCES.md
|
|
34
|
+
webdata.py web export: zone PNGs (pixel = zone code) + manifest.json
|
|
35
|
+
render.py diagnostic PNG maps
|
|
36
|
+
tests/ unit + acceptance tests
|
|
37
|
+
scripts/
|
|
38
|
+
m0_acceptance.py regenerate the Muharram 1445 artifacts
|
|
39
|
+
generate_months.py rolling-window web data → site/public/data/months/
|
|
40
|
+
run_validation.py regenerate site/src/data/validation.json
|
|
41
|
+
data/
|
|
42
|
+
ephemeris/ de440s.bsp (auto-downloaded, ~32 MB, gitignored; a
|
|
43
|
+
pip install caches it per user instead, see PYPI_README.md)
|
|
44
|
+
months/ full-resolution grid archives (.npz, gitignored)
|
|
45
|
+
acceptance/ rendered acceptance maps
|
|
46
|
+
site/ Astro + MapLibre app (bilingual en/ar, RTL)
|
|
47
|
+
src/lib/ zones, i18n, manifest loading, crescent kernel, city
|
|
48
|
+
search (+ vitest)
|
|
49
|
+
src/workers/ crescent kernel off the main thread
|
|
50
|
+
src/components/ MapView, LocationView
|
|
51
|
+
public/data/ month artifacts (~110 KB/month) + city index
|
|
52
|
+
.github/workflows/ daily regen + Pages deploy; kernel CI (3.12/3.13);
|
|
53
|
+
PyPI publish on v* tags
|
|
54
|
+
```
|
|
55
|
+
|
|
56
|
+
The site bundles its own Natural Earth land layer — no external tile
|
|
57
|
+
dependency. Zone PNGs are decoded client-side and re-projected row-by-row
|
|
58
|
+
onto web-mercator (equirectangular data cannot be linearly stretched onto
|
|
59
|
+
a mercator quad).
|
|
60
|
+
|
|
61
|
+
## Quantities and conventions
|
|
62
|
+
|
|
63
|
+
A criterion is (formula + fitted constants + data-reduction convention), so
|
|
64
|
+
**each criterion consumes quantities in the exact convention its constants
|
|
65
|
+
were calibrated on**. Lunar parallax alone shifts ARCV by ~0.9° near the
|
|
66
|
+
horizon — 40% of a Yallop zone width — so conventions are not interchangeable.
|
|
67
|
+
This amends plan §3.2's blanket "all topocentric": topocentric remains the
|
|
68
|
+
display convention (what an observer experiences), but criterion evaluation
|
|
69
|
+
is per-source.
|
|
70
|
+
|
|
71
|
+
The kernel computes, at best time T_b = T_sunset + (4/9)·lag (Bruin 1977;
|
|
72
|
+
TN 69 eq. 4.1):
|
|
73
|
+
|
|
74
|
+
- **Topocentric airless** ARCV/ARCL/DAZ/W → Odeh, display, raw mode.
|
|
75
|
+
- **Geocentric** ARCV/DAZ (TN 69 §2) + TN 69 width W′ = SD′(1 − cos ARCL),
|
|
76
|
+
SD = 0.27245π, SD′ = SD(1 + sin h sin π) (eqs 3.8–3.10) → Yallop.
|
|
77
|
+
|
|
78
|
+
and at sunset:
|
|
79
|
+
|
|
80
|
+
- **DALT** — apparent (refracted, Sæmundsson) altitude of the moon's lower
|
|
81
|
+
limb — and DAZ at sunset → SAAO.
|
|
82
|
+
|
|
83
|
+
Plus lag, moon age, and hard impossibility flags (moonset before sunset;
|
|
84
|
+
conjunction after sunset).
|
|
85
|
+
|
|
86
|
+
## Criteria
|
|
87
|
+
|
|
88
|
+
| Key | Source | Fidelity |
|
|
89
|
+
|---|---|---|
|
|
90
|
+
| `yallop` | Yallop (1997), NAO TN 69 q-test | exact — geocentric ARCV + W′; tests pinned to TN 69 Table 4 worked values |
|
|
91
|
+
| `odeh` | Odeh (2004), Exp. Astron. 18, V-test, Danjon 6.4° | exact — topocentric ARCV + W; tests pinned to Table V |
|
|
92
|
+
| `saao` | Caldwell & Laney (2001) DALT criterion | exact to the published table (Odeh 2004 Table IV); linear interp in \|DAZ\|, clamped past 20° |
|
|
93
|
+
| `shaukat` | moonsighting.com (Shaukat) | **reconstruction r0 — NOT published on the site.** Not monotone (its 8°/5° reference line lets zone A border zone C with no B between) and its terminal zone means "not visible", so it cannot share Yallop's zone language. Restore in `webdata.DEFAULT_CRITERIA` and `site/src/lib/zones.ts` once M4 refits it against the digitized map archive |
|
|
94
|
+
| `raw` | none | reports quantities + q + V (each in its own convention), no zone |
|
|
95
|
+
|
|
96
|
+
**Zone letters are criterion-specific and are never shared.** Yallop's A–F
|
|
97
|
+
and Odeh's A–D are different scales that reuse letters: Yallop's D is
|
|
98
|
+
"binoculars or telescope only", Odeh's D is "not visible at all". SAAO
|
|
99
|
+
defines three levels and has no B. The site renders the legend and hover
|
|
100
|
+
readout from the selected criterion's own table.
|
|
101
|
+
|
|
102
|
+
**Domain-of-validity gate.** Every criterion is a fit to observations where
|
|
103
|
+
the crescent was above the horizon and higher than the sun — every record in
|
|
104
|
+
Yallop's 295 and Odeh's 737 has ARCV > 0. Outside that domain the
|
|
105
|
+
polynomials extrapolate to absurdities (a wide crescent at ARCV ≈ 0.7°
|
|
106
|
+
scores Odeh V = 3.2, "visible with optical aid", with the moon's centre
|
|
107
|
+
*below* the horizon). `criteria.physically_visible` gates that off and
|
|
108
|
+
reports the criterion's not-visible zone. The gate is ours, not the source
|
|
109
|
+
papers'; it only ever demotes a verdict.
|
|
110
|
+
|
|
111
|
+
The scalar implementations in `criteria.py` are the single source of truth;
|
|
112
|
+
the vectorized grid twins are property-tested against them. Primary-source
|
|
113
|
+
PDFs (TN 69; Odeh 2004, which reproduces the SAAO table) are pinned in the
|
|
114
|
+
tests by table values, not by reference.
|
|
115
|
+
|
|
116
|
+
## Python package
|
|
117
|
+
|
|
118
|
+
The kernel is packaged as [`hilal-visibility`](PYPI_README.md) (import name
|
|
119
|
+
`hilal_visibility`): `pip install hilal-visibility`, plus the `plot` extra for
|
|
120
|
+
`render.py`'s matplotlib maps. [PYPI_README.md](PYPI_README.md) is the PyPI
|
|
121
|
+
page, with a worked single-location example. Releases are cut by pushing a
|
|
122
|
+
`v*` tag, which runs `.github/workflows/publish.yml` (trusted publishing, no
|
|
123
|
+
API token).
|
|
124
|
+
|
|
125
|
+
## Develop
|
|
126
|
+
|
|
127
|
+
```bash
|
|
128
|
+
uv venv --python 3.12 && uv pip install -e ".[dev]"
|
|
129
|
+
.venv/bin/pytest # full suite (~8 s after first ephemeris download)
|
|
130
|
+
.venv/bin/python scripts/m0_acceptance.py # regenerate Muharram 1445 maps
|
|
131
|
+
```
|
|
132
|
+
|
|
133
|
+
M0 acceptance: the Muharram 1445 evenings (conjunction 2023-07-17 18:31 UT)
|
|
134
|
+
reproduce the moonsighting.com ground truth — see
|
|
135
|
+
`hilal_visibility/tests/test_acceptance_muharram1445.py` and `data/acceptance/`.
|
|
136
|
+
|
|
137
|
+
**External validation.** Against Odeh (2004) Table VI record No. 514
|
|
138
|
+
(Sarajevo, 12 Feb 2002) — one of the 737 observations the criterion was
|
|
139
|
+
fitted to — this kernel reproduces the published values: ARCV 0.66 vs 0.70,
|
|
140
|
+
ARCL 5.77 vs 5.80, DAZ 5.73 vs 5.70, lag 4.02 vs 4 min, age 8.51 vs 8.4 h,
|
|
141
|
+
V −6.04 vs −5.96, and classifies it zone D (the crescent was not seen).
|
|
142
|
+
Residuals are consistent with Odeh's use of Accurate Times and a 630 m
|
|
143
|
+
observer elevation.
|
|
144
|
+
|
|
145
|
+
**Systematic validation (M4).** Recomputing all 271 evening records of
|
|
146
|
+
Yallop's Table 4 from DE440s reproduces his published q to a median of
|
|
147
|
+
−0.0004 (sd 0.0047, worst 0.050) against a narrowest zone width of 0.061 —
|
|
148
|
+
so no record is misfiled by the implementation. Scored against Alrefay et
|
|
149
|
+
al. (2018), on the 379 records that postdate Odeh 2004 and are therefore out
|
|
150
|
+
of sample, all three criteria miss at most one of 157 naked-eye sightings;
|
|
151
|
+
they differ only in false alarms, and that difference is where Yallop's B/C
|
|
152
|
+
boundary sits rather than anything about the models — his q and Odeh's V are
|
|
153
|
+
the same polynomial. Full results, including what the validation does not
|
|
154
|
+
show, are published at `/validation` and regenerated by
|
|
155
|
+
`scripts/run_validation.py`.
|
|
156
|
+
|
|
157
|
+
## Deploying
|
|
158
|
+
|
|
159
|
+
The site is built in GitHub Actions — the pipeline needs Python 3.12, uv,
|
|
160
|
+
Skyfield and a 32 MB JPL kernel, which is a poor fit for a host's own build
|
|
161
|
+
image — and Cloudflare Pages only hosts the finished `site/dist`.
|
|
162
|
+
|
|
163
|
+
**Deployment is opt-in.** The publish step runs only when the repo variable
|
|
164
|
+
`CLOUDFLARE_PROJECT` is set. Until then every push still builds and runs both
|
|
165
|
+
test suites, and nothing is published. That default is deliberate:
|
|
166
|
+
|
|
167
|
+
> A Cloudflare Pages deployment is **publicly reachable the moment it lands**.
|
|
168
|
+
> A private GitHub repo does not make a private site, and neither does the
|
|
169
|
+
> Pages "Enable access policy" toggle — that one covers *preview* deployments
|
|
170
|
+
> only, so it is easy to flip it, see a login prompt on a preview URL, and
|
|
171
|
+
> conclude the site is protected while `<project>.pages.dev` is wide open.
|
|
172
|
+
> Gating the production hostname means a Cloudflare Access application over
|
|
173
|
+
> it, with an explicit list of allowed emails.
|
|
174
|
+
|
|
175
|
+
One-time setup:
|
|
176
|
+
|
|
177
|
+
```bash
|
|
178
|
+
# 1. Create the Pages project. `wrangler pages deploy` will NOT create one —
|
|
179
|
+
# it fails with "Project not found [code: 8000007]" and cannot prompt in CI.
|
|
180
|
+
npx wrangler pages project create hilal-visibility --production-branch=main
|
|
181
|
+
|
|
182
|
+
# 2. Create an API token: Cloudflare dashboard -> My Profile -> API Tokens ->
|
|
183
|
+
# Create Custom Token, with Permissions = Account / Cloudflare Pages / Edit.
|
|
184
|
+
# That single permission is enough when the account ID is passed explicitly.
|
|
185
|
+
# Account ID: dashboard search (Cmd-K) "Copy account ID", or the hex in
|
|
186
|
+
# the dashboard URL.
|
|
187
|
+
|
|
188
|
+
# 3. Store them. Set these yourself — never paste a token into a prompt.
|
|
189
|
+
gh secret set CLOUDFLARE_API_TOKEN
|
|
190
|
+
gh secret set CLOUDFLARE_ACCOUNT_ID
|
|
191
|
+
|
|
192
|
+
# 4. Turn deployment on.
|
|
193
|
+
gh variable set CLOUDFLARE_PROJECT --body hilal-visibility
|
|
194
|
+
gh variable set ASTRO_SITE --body https://your-domain.example
|
|
195
|
+
```
|
|
196
|
+
|
|
197
|
+
`ASTRO_SITE` is not decoration: canonical links, the hreflang pairs between
|
|
198
|
+
the English and Arabic copies of every page, the Open Graph preview, the
|
|
199
|
+
sitemap and robots.txt are all derived from it. Point it at the real domain
|
|
200
|
+
when there is one and everything follows. The social preview image is
|
|
201
|
+
committed; regenerate it only if the wording or palette changes:
|
|
202
|
+
|
|
203
|
+
```bash
|
|
204
|
+
.venv/bin/python scripts/make_og_image.py
|
|
205
|
+
```
|
|
206
|
+
|
|
207
|
+
Free-plan headroom, measured against the current build (3,348 files, 30 MB):
|
|
208
|
+
the cap is **20,000 files** per deployment and 25 MiB per file, so this is at
|
|
209
|
+
17% of the file budget. The archive costs 24 files per month, leaving room for
|
|
210
|
+
roughly 690 more months. Bandwidth and static requests are unlimited; builds
|
|
211
|
+
are capped at 500/month.
|
|
212
|
+
|
|
213
|
+
## References
|
|
214
|
+
|
|
215
|
+
Bruin (1977) Vistas Astron. 21; Yallop (1997) NAO TN 69; Odeh (2004)
|
|
216
|
+
Exp. Astron. 18:39–64; Caldwell & Laney (2001) African Skies 5; Danjon
|
|
217
|
+
(1932, 1936) L'Astronomie; Schaefer's visibility papers.
|
|
@@ -0,0 +1,21 @@
|
|
|
1
|
+
"""hilal-visibility: crescent moon (hilal) visibility compute kernel.
|
|
2
|
+
|
|
3
|
+
Modules:
|
|
4
|
+
ephem exact single-point circumstances (``compute_evening``,
|
|
5
|
+
``find_new_moon``)
|
|
6
|
+
criteria Yallop, Odeh, SAAO, Shaukat (reconstruction) and raw criteria
|
|
7
|
+
grid vectorized global zone grids
|
|
8
|
+
contours zone grids to GeoJSON polygons
|
|
9
|
+
hijri astronomical Hijri month labelling
|
|
10
|
+
narrative auto-generated en/ar narrative from grids
|
|
11
|
+
webdata web export (zone PNGs + manifest)
|
|
12
|
+
validate historical observation records and scoring
|
|
13
|
+
render diagnostic PNG maps (needs the ``plot`` extra)
|
|
14
|
+
"""
|
|
15
|
+
|
|
16
|
+
from importlib.metadata import PackageNotFoundError, version
|
|
17
|
+
|
|
18
|
+
try:
|
|
19
|
+
__version__ = version("hilal-visibility")
|
|
20
|
+
except PackageNotFoundError: # running from a checkout without installing
|
|
21
|
+
__version__ = "0.0.0+unknown"
|