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
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147

// SPDX-License-Identifier: AGPL-3.0-only
// Copyright (C) 2026 Vallés Puig, Ramon
//! Direct Beer–Lambert transmission configuration.
//!
//! ```text
//! I(λ) = I₀(λ) · exp(−τ(λ) · X(z))
//! ```
//!
//! Radiance application is only available through [`super::TransportModel`] so
//! [`super::RadianceOrigin`] checks cannot be bypassed.

use super::extinction::{optical_depth_breakdown, ExtinctionIngredients, OpticalDepthBreakdown};
use super::geometry::DirectPathGeometry;
use super::metadata::TransportModelMetadata;
use super::model::AirmassModel;
use crate::error::{NsbError, Result};
use crate::site::AtmosphericConditions;
use crate::units::angular::Radian;
use crate::units::dimensionless::Transmittances;
use siderust::atmosphere::{
    airmass, transmission as beer_lambert_transmission, KrisciunasSchaefer1991, PlaneParallel,
    Rozenberg1966, Young1994,
};
use siderust::qtty::Nanometers;

/// Direct-transmission configuration for top-of-atmosphere sources.
///
/// Not `Copy`: future aerosol tables or LUT handles must be able to land here
/// without a frozen `Copy` guarantee.
#[derive(Debug, Clone, PartialEq)]
#[non_exhaustive]
pub struct DirectTransmission {
    ingredients: ExtinctionIngredients,
    airmass: AirmassModel,
}

impl DirectTransmission {
    /// Rayleigh + Mie extinction with Young (1994) airmass.
    pub const fn rayleigh_mie_young1994() -> Self {
        Self {
            ingredients: ExtinctionIngredients::RAYLEIGH_MIE,
            airmass: AirmassModel::Young1994,
        }
    }

    /// Rayleigh + Mie + bundled ozone with Young (1994) airmass.
    pub const fn rayleigh_mie_ozone_young1994() -> Self {
        Self {
            ingredients: ExtinctionIngredients::RAYLEIGH_MIE_OZONE,
            airmass: AirmassModel::Young1994,
        }
    }

    /// Construct an explicit direct-transmission configuration.
    pub const fn new(ingredients: ExtinctionIngredients, airmass: AirmassModel) -> Self {
        Self {
            ingredients,
            airmass,
        }
    }

    /// Extinction ingredients.
    pub const fn ingredients(&self) -> ExtinctionIngredients {
        self.ingredients
    }

    /// Airmass model.
    pub const fn airmass(&self) -> AirmassModel {
        self.airmass
    }

    /// Model-only metadata for this configuration.
    pub fn metadata(&self) -> TransportModelMetadata {
        TransportModelMetadata::direct(self.ingredients, self.airmass)
    }

    /// Vertical optical-depth breakdown at `wavelength`.
    ///
    /// # Errors
    ///
    /// Returns [`NsbError::OutOfRange`] when `wavelength` is non-finite or not
    /// strictly positive.
    pub fn optical_depth(
        &self,
        wavelength: Nanometers,
        atmosphere: AtmosphericConditions,
    ) -> Result<OpticalDepthBreakdown> {
        validate_wavelength(wavelength)?;
        Ok(optical_depth_breakdown(
            wavelength,
            atmosphere,
            self.ingredients,
        ))
    }

    /// Slant-path transmission `T = exp(−τ X)`.
    ///
    /// # Errors
    ///
    /// Returns [`NsbError::OutOfRange`] for invalid wavelength. Geometry must
    /// already be validated via [`DirectPathGeometry::new`].
    pub fn transmission(
        &self,
        wavelength: Nanometers,
        geometry: DirectPathGeometry,
        atmosphere: AtmosphericConditions,
    ) -> Result<Transmittances> {
        let tau = self.optical_depth(wavelength, atmosphere)?.total;
        let path = self.airmass_value(geometry);
        Ok(beer_lambert_transmission(tau, path))
    }

    pub(crate) fn scale_factor(
        &self,
        wavelength: Nanometers,
        geometry: DirectPathGeometry,
        atmosphere: AtmosphericConditions,
    ) -> Result<f64> {
        Ok(self.transmission(wavelength, geometry, atmosphere)?.value())
    }

    fn airmass_value(&self, geometry: DirectPathGeometry) -> siderust::qtty::Airmasses {
        let zenith = geometry.zenith().to::<Radian>();
        match self.airmass {
            AirmassModel::Young1994 => airmass::<Young1994>(zenith),
            AirmassModel::KrisciunasSchaefer1991 => airmass::<KrisciunasSchaefer1991>(zenith),
            AirmassModel::PlaneParallel => airmass::<PlaneParallel>(zenith),
            AirmassModel::Rozenberg1966 => airmass::<Rozenberg1966>(zenith),
        }
    }
}

impl Default for DirectTransmission {
    fn default() -> Self {
        Self::rayleigh_mie_young1994()
    }
}

pub(crate) fn validate_wavelength(wavelength: Nanometers) -> Result<()> {
    let value = wavelength.value();
    if !value.is_finite() || value <= 0.0 {
        return Err(NsbError::OutOfRange(format!(
            "transport wavelength must be finite and > 0 nm, got {value}"
        )));
    }
    Ok(())
}