nsb 0.1.0

Night-sky background evaluation and observation planning for ground-based astronomy.
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
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121

// SPDX-License-Identifier: AGPL-3.0-only
// Copyright (C) 2026 Vallés Puig, Ramon
//! `nsb` — Night Sky Background model.
//!
//! Computes the photon flux reaching a ground-based observer from a configurable
//! sum of zodiacal light, integrated starlight, airglow, and scattered moonlight.
//! Integrated starlight is included in defaults only when the build embeds a
//! validated production catalogue-derived map.
//!
//! The library API is intentionally typed and CLI-free: callers pass
//! [`Observer`] values, `Time<UTC>` instants, and equatorial [`Target`]
//! directions directly. Named-site parsing, command-line flags, and output
//! formatting belong in a separate CLI crate that consumes this library.
//!
//! # Supported public API
//!
//! The first-release surface is classified in
//! [`docs/developer-guide/public-api.md`](../../docs/developer-guide/public-api.md).
//!
//! 1. **Core root API** — normal evaluator/planning integrations and durable
//!    component selectors.
//! 2. **Advanced nested API** — `components::starlight`, `components::airglow`,
//!    `site`, and `solar_activity` for supported scientific workflows.
//! 3. **Metadata/schema API** — intentional persisted or inspectable records
//!    (bundled assets, F10.7 stores).
//! 4. **Private implementation** — concrete component evaluators, spectra,
//!    planning internals, and test/tooling helpers.
//!
//! The recommended application path is:
//!
//! 1. Build an [`NsbEvaluator`] from [`NsbModelConfig`].
//! 2. Evaluate a [`PointQuery`] or search with [`ThresholdQuery`].
//! 3. Read [`NsbResult`] / [`ThresholdQueryResult`] and per-component
//!    [`NsbComponentMetadata`].
//!
//! # Airglow selection
//!
//! [`NsbModelConfig::generic_clear_sky`], [`NsbModelConfig::default`], and
//! [`NsbEvaluator::new`] use [`AirglowSelection::Automatic`]. Explicit
//! [`NsbModelConfig::with_airglow_model`] selection wins and never silently
//! switches models. Until the global climatological model is admitted (#157),
//! automatic policy resolves to the temporary Paranal-derived planning fallback
//! with typed fallback metadata in [`NsbComponentMetadata::airglow_selection`].
//! Physical evaluation outcomes live in
//! [`NsbComponentMetadata::airglow_evaluation`] and are absent from
//! [`NsbEvaluator::describe_components`] descriptors.
//!
//! # Dependency types
//!
//! NSB uses Siderust, `qtty`, and `tempoch` types at the supported boundary
//! (`Observer`, `Target`, `Time<UTC>`, radiances, angles). The [`units`]
//! module is the canonical NSB-facing entry point for `qtty`: it re-exports
//! the upstream crate and the quantity modules used by NSB. [`DEG`] remains
//! re-exported at the crate root for the documented getting-started path.
//!
//! # Architecture
//!
//! Shared physical spectra used across components live in the internal `spectra`
//! module; component-specific calibrations and grids live inside their component
//! modules.
//!
//! `siderust` owns astronomy, time, coordinates, events, atmosphere, lunar
//! photometry, and passbands. NSB owns NSB-specific component composition,
//! atmospheric-transport orchestration ([`transport`]), observing-window
//! planning, and site-profile metadata that distinguishes generic fallbacks
//! from explicit named planning presets.

#![forbid(unsafe_code)]
#![warn(missing_docs)]

/// Advanced component models used to construct or inspect individual contributors.
pub mod components;
/// Runtime scientific data and build-verified bundled metadata.
pub mod data;
pub(crate) mod error;
mod evaluator;
mod planning;
#[cfg(feature = "python")]
mod python;
/// Serde field adapters for QTTY photometric types used by NSB consumers.
#[cfg(feature = "serde")]
pub mod serde_support;
/// Site profiles and shared atmospheric assumptions.
pub mod site;
/// Offline F10.7 resolution used by airglow configuration.
pub mod solar_activity;
mod spectra;
/// Atmospheric transport of spectral sky radiance (identity and direct paths).
pub mod transport;
/// Physical quantities, NSB-specific conventions, and the `qtty` facade.
pub mod units;

pub use components::airglow::AirglowModel;
pub use components::airglow::AirglowSelection;
pub use components::moonlight::MoonlightModel;
pub use components::starlight::StarlightProduct;
pub use components::zodiacal::{ZodiacalExtinction, ZodiacalModel};
pub use error::{NsbError, Result};
pub use evaluator::{
    BandDiagnostic, CalibrationStatus as ComponentCalibrationStatus, ComponentMask, NsbComponent,
    NsbComponentDescriptor, NsbComponentMetadata, NsbEvaluator, NsbModelConfig, NsbResult,
    Observer, PointQuery, Target,
};
pub use planning::{SiteWindowContext, ThresholdQuery, ThresholdQueryResult};
pub use site::{CalibrationStatus, GenericClearSky, SiteProfile, SiteProfileTag};
use units::photometry::SurfaceBrightness;
pub use units::{SolarFluxUnit, SolarFluxUnits};

/// Angle unit used with [`Target::new`] in documented examples.
pub use siderust::qtty::DEG;

pub(crate) const NSB_S10_ZP: SurfaceBrightness = SurfaceBrightness::new(27.78);

/// Version of the NSB library crate.
pub const NSB_VERSION: &str = env!("CARGO_PKG_VERSION");
/// Versioned model-composition contract used in operational metadata.
pub const MODEL_VERSION: &str = "nsb-model-v1";
/// Siderust package version represented by the locked dependency.
pub const SIDERUST_VERSION: &str = "0.14.1";
/// Truthful package-source identity for the Siderust dependency.
pub const SIDERUST_SOURCE: &str = "crates.io:siderust:0.14.1";