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.
Files changed (38) hide show
  1. hilal_visibility-0.1.0/.gitignore +30 -0
  2. hilal_visibility-0.1.0/LICENSE +21 -0
  3. hilal_visibility-0.1.0/PKG-INFO +135 -0
  4. hilal_visibility-0.1.0/PYPI_README.md +102 -0
  5. hilal_visibility-0.1.0/README.md +217 -0
  6. hilal_visibility-0.1.0/hilal_visibility/__init__.py +21 -0
  7. hilal_visibility-0.1.0/hilal_visibility/contours.py +468 -0
  8. hilal_visibility-0.1.0/hilal_visibility/criteria.py +356 -0
  9. hilal_visibility-0.1.0/hilal_visibility/ephem.py +375 -0
  10. hilal_visibility-0.1.0/hilal_visibility/grid.py +536 -0
  11. hilal_visibility-0.1.0/hilal_visibility/hijri.py +66 -0
  12. hilal_visibility-0.1.0/hilal_visibility/narrative.py +266 -0
  13. hilal_visibility-0.1.0/hilal_visibility/py.typed +0 -0
  14. hilal_visibility-0.1.0/hilal_visibility/quantities.py +108 -0
  15. hilal_visibility-0.1.0/hilal_visibility/render.py +125 -0
  16. hilal_visibility-0.1.0/hilal_visibility/tests/__init__.py +0 -0
  17. hilal_visibility-0.1.0/hilal_visibility/tests/test_acceptance_muharram1445.py +116 -0
  18. hilal_visibility-0.1.0/hilal_visibility/tests/test_contours.py +555 -0
  19. hilal_visibility-0.1.0/hilal_visibility/tests/test_criteria.py +460 -0
  20. hilal_visibility-0.1.0/hilal_visibility/tests/test_ephem.py +318 -0
  21. hilal_visibility-0.1.0/hilal_visibility/tests/test_grid.py +218 -0
  22. hilal_visibility-0.1.0/hilal_visibility/tests/test_hijri.py +49 -0
  23. hilal_visibility-0.1.0/hilal_visibility/tests/test_narrative.py +175 -0
  24. hilal_visibility-0.1.0/hilal_visibility/tests/test_render.py +42 -0
  25. hilal_visibility-0.1.0/hilal_visibility/tests/test_validate_metrics.py +134 -0
  26. hilal_visibility-0.1.0/hilal_visibility/tests/test_validate_records.py +129 -0
  27. hilal_visibility-0.1.0/hilal_visibility/tests/test_webdata.py +115 -0
  28. hilal_visibility-0.1.0/hilal_visibility/validate/__init__.py +18 -0
  29. hilal_visibility-0.1.0/hilal_visibility/validate/data/.mphys-moon-commit +1 -0
  30. hilal_visibility-0.1.0/hilal_visibility/validate/data/LICENSE-mphys-moon +21 -0
  31. hilal_visibility-0.1.0/hilal_visibility/validate/data/SOURCES.md +93 -0
  32. hilal_visibility-0.1.0/hilal_visibility/validate/data/alrefay2018.csv +477 -0
  33. hilal_visibility-0.1.0/hilal_visibility/validate/data/yallop1997_table4.csv +296 -0
  34. hilal_visibility-0.1.0/hilal_visibility/validate/evaluate.py +142 -0
  35. hilal_visibility-0.1.0/hilal_visibility/validate/metrics.py +305 -0
  36. hilal_visibility-0.1.0/hilal_visibility/validate/records.py +289 -0
  37. hilal_visibility-0.1.0/hilal_visibility/webdata.py +137 -0
  38. 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"