# «Сегодня над Петербургом»: расчёт, источники и ограничения

Версия локального модуля: 1; проверено 5 ноября 2026 года. JavaScript не загружает
эфемериды и не вызывает API: все коэффициенты включены в `astronomy.js`.

## Даты, вечер и переход к карте

Параметры `/today/index.html` и внешней оболочки `/today.html`:

| Параметр | Значение по умолчанию | Смысл |
| --- | --- | --- |
| `date` | Текущая дата в выбранном `tz` | Реальная григорианская дата `YYYY-MM-DD`, 1900–2100 |
| `lat` | `59.9386` | Широта, север положительный, −90…90° |
| `lon` | `30.3141` | Долгота, восток положительный, −180…180° |
| `tz` | `180` | Фиксированное целое смещение от UTC, минуты, −720…840 |

`tz=180` — UTC+03:00 (МСК). Исторические часовые пояса и переходы на летнее время
не восстанавливаются. Часовой пояс браузера не участвует в вычислениях.
Десятичная запятая допустима для координат. Пустые и нечисловые поля, выход за
границы и несуществующие даты дают ошибку, предыдущий результат скрывается.

Выбранный вечер — полуоткрытый интервал от **местных 12:00 выбранной даты до
12:00 следующего дня**. Внутри него ищется первое пересечение Солнцем заданной
высоты на спуске. Если есть заход, конец сумерек берётся после него. У события
после полуночи явно показана следующая календарная дата.

Время карты — через 30 минут после конца астрономических сумерек, но не позднее
середины оставшегося периода астрономической ночи. Это сохраняет тёмное время
при очень короткой ночи и не выходит за интервал вечера. Если вечернего конца
сумерек нет, берётся **местная полночь следующей даты**, с явным объяснением,
что это условный момент карты. При полярной ночи не выдумывается новое начало
темноты. Фаза Луны вычисляется именно на время этой карты.

Переход открывает верхнее окно (`target="_top"`):

```text
/sky.html?lat=59.9386&lon=30.3141&time=<абсолютная ISO-дата UTC с Z>&tz=180
```

В `time` передаётся момент с UTC, а не местное время без зоны. `tz` отдельно
определяет отображение часов. Постоянная ссылка на выбранный вечер:
`/today.html?date=2026-11-05&lat=59.9386&lon=30.3141&tz=180`.

Диапазон карты проверяется по **местному году** (`time + tz`). Если вечер
2100-12-31 даёт момент в местном 2101 году, солнечная/лунная сводка сохраняется,
но ссылка карты отключается с объяснением. Время не подменяется соседним днём.
UTC-момент в соседнем году допустим, если местный год остаётся в 1900–2100.

## Солнце и сумерки

Основные формулы солнечных координат и уравнения времени — модель Ж. Меёса,
используемая [NOAA Solar Calculator](https://gml.noaa.gov/grad/solcalc/).
[Документация NOAA](https://gml.noaa.gov/grad/solcalc/calcdetails.html) описывает
предпосылки и ухудшение точности на высоких широтах. Сервис NOAA уже не
поддерживается; его доступность для работы этой страницы не требуется.

Геометрическая высота центра Солнца считается по склонению и истинному часовому
углу. Для захода используется `−0.833°`, объединяющее условную рефракцию и радиус
солнечного диска при ровном горизонте у уровня моря. Для конца астрономических
сумерек — `−18°` без рефракционной поправки. Это соглашения
[USNO Rise, Set, and Twilight Definitions](https://aa.usno.navy.mil/faq/RST_defs).

Поиск пересечений: шаг 5 минут, дополнительное уточнение суточных экстремумов,
затем бисекция до интервала 0,25 секунды. Это точность поиска **внутри модели**,
а не точность прогноза наблюдаемого захода. Округление до минуты выполняется
только для текста; ссылки и сравнения сохраняют абсолютный момент.

Отдельные состояния без времени: Солнце всё время выше границы, всё время ниже
границы, касание границы, отсутствие вечернего пересечения в выбранном интервале.
`null` обозначает отсутствие события; подстановка вымышленного времени не
применяется. Для Петербурга летом возможен заход при отсутствии конца сумерек.

Практический ориентир — несколько минут при обычных широтах; за ±72° и около
касания ошибка может быть больше 10 минут. Рельеф, высота наблюдателя, реальное
давление/температура, облачность и городская засветка в модель не входят. Сам
факт достижения −18° не гарантирует хороших условий наблюдения.

## Луна

Положение вычисляется по 60 членам ряда долготы/расстояния и 60 членам ряда
широты из [ERFA 2.0.1 `moon98.c`](https://github.com/liberfa/erfa/blob/v2.0.1/src/moon98.c)
(редакция 20 марта 2023; модель Meeus 1998 / Simon et al. 1994). Лицензия и
copyright сохранены в `ERFA-LICENSE.txt`. Это адаптация позиционной части, а не
полная библиотека ERFA/SOFA: скорости и поворот в GCRS не нужны, координаты
остаются в средней эклиптике даты. К точности полной ERFA эта страница не
приравнивается.

Солнечная долгота берётся из той же локальной солнечной модели. По лунной
широте, разности долгот и двум расстояниям определяется угол Солнце — Луна —
Земля `i`, затем освещённая доля видимого диска `(1 + cos(i)) / 2`.
Растущая/убывающая определяется знаком относительной эклиптической долготы:
0…180° / 180…360°. Подписи «около» четверти/новолуния/полнолуния обозначают
окрестность фазы; точные моменты основных фаз не ищутся. Синодический возраст
Луны не используется вместо координат.

Модель геоцентрическая. UTC приближённо принято за TT; таблицы секунд
координации, ΔT, тонкие эффекты видимого места и топоцентрический параллакс не
включены. Освещённость ориентировочная, заявленный ориентир — ±1 процентный
пункт. Геометрическая фаза не учитывает затмения и не сообщает высоту Луны над
горизонтом. Показатель не является прогнозом видимости или яркости неба.

## Независимая проверка

```sh
cd tools/today-check
go test -count=1 -v ./...
```

Go исполняет точный production `today/astronomy.js` через Node VM. Эталоны,
расчёт независимой солнечной модели, проверка дат и assertions написаны на Go.
Тестам нужен Node; дополнительные пакеты и сеть не нужны.

Солнце проверяется по отдельному алгоритму
[USNO Computing Approximate Solar Coordinates](https://aa.usno.navy.mil/faq/sun_approx):
прямое восхождение/склонение и звёздный поворот Земли, без production-формулы
уравнения времени. 600 случайных дат/мест в 1900–2100 дали максимальное различие
высоты **0,011358°**, при допуске теста 0,035°. Заход и сумерки дополнительно
находятся независимым Go-поиском: Петербург зимой/летом, экватор, южное
полушарие, высокие широты, полюса, UTC−10/UTC+14/UTC+05:45, заход после полуночи
и обе границы диапазона дат. Допуск времени — 3 минуты, за ±72° — 10 минут;
это сравнение моделей, не натурных наблюдений.

Внешняя опубликованная контрольная точка Солнца —
[официальный SPA tester NREL/NLR](https://midcdmz.nlr.gov/spa/spa_tester.c),
Golden, Colorado, 17 октября 2003 года. Тест учитывает отличие геометрической
высоты от видимой высоты с рефракцией; допуск 0,035° и 3 минуты для захода.

Лунный независимый эталон:
[NASA SVS Moon Phase and Libration, 2026](https://svs.gsfc.nasa.gov/5587/) и его
[почасовой JSON](https://svs.gsfc.nasa.gov/vis/a000000/a005500/a005587/mooninfo_2026.json).
11 извлечённых точек сохранены в `tools/today-check/moon-nasa-2026.json`:
новолуние с обеих сторон, полнолуние, четверти, лето/зима. Максимальное различие
освещённой доли — **0,018790 процентного пункта**, допуск теста 0,10 п.п.;
расстояния сравниваются с допуском 60 км. Проверка не доказывает такую же
точность для каждой даты 1900–2100.

Браузерная проверка вынесена в `tools/today-check/browser`, инструкция —
`tools/today-check/README.md`. Она проверяет живую форму, подписи, ошибки,
смену дат, независимость от зоны браузера, мобильную ширину и локальность
запросов. Сама научная проверка не зависит от Chromium.