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

// SPDX-License-Identifier: AGPL-3.0-only
// Copyright (C) 2026 Vallés Puig, Ramon
use siderust::qtty;
use siderust::qtty::area::SquareMeter;
use siderust::qtty::length::Nanometer;
use siderust::qtty::power::Watt;
use siderust::qtty::{unit, Per, Quantity};

/// A generic multiplicative scale factor.
pub(crate) type ScaleFactors = siderust::qtty::dimensionless::Ratios;

/// Structural qtty unit for spectral solar irradiance, W m⁻² nm⁻¹.
///
/// This is deliberately expressed as qtty unit algebra rather than as an
/// unrelated placeholder unit, so dimensional correctness remains enforced by
/// the compiler without requiring a bespoke NSB unit marker.
pub(crate) type SolarSpectralIrradianceUnit = Per<Per<Watt, SquareMeter>, Nanometer>;

/// Spectral solar irradiance in W m⁻² nm⁻¹.
pub(crate) type SolarSpectralIrradiance = Quantity<SolarSpectralIrradianceUnit>;

/// SkyCalc spectral photon radiance unit:
/// photons s⁻¹ m⁻² arcsec⁻² µm⁻¹.
#[derive(Clone, Copy, Debug, PartialEq, PartialOrd, siderust::qtty::Unit)]
#[unit(
    crate = qtty,
    symbol = "ph·s⁻¹·m⁻²·arcsec⁻²·µm⁻¹",
    dimension = siderust::qtty::radiometry::SpectralPhotonRadiance,
    ratio = 4.254_517_029_022_576e16
)]
#[allow(dead_code)]
pub(crate) struct SkyCalcPhotonPerSquareMeterSecondSquareArcsecondMicrometer;

/// Spectral photon radiance in SkyCalc's native tabulated convention.
#[allow(dead_code)]
pub(crate) type SkyCalcSpectralPhotonRadiance =
    Quantity<SkyCalcPhotonPerSquareMeterSecondSquareArcsecondMicrometer>;

/// Spectral radiance unit: W m⁻² sr⁻¹ µm⁻¹.
#[derive(Clone, Copy, Debug, PartialEq, PartialOrd, siderust::qtty::Unit)]
#[unit(
    crate = qtty,
    symbol = "W·m⁻²·sr⁻¹·µm⁻¹",
    dimension = siderust::qtty::radiometry::SpectralRadiance,
    ratio = 1.0e6
)]
pub(crate) struct WattPerSquareMeterSteradianMicrometer;

/// Spectral radiance in W m⁻² sr⁻¹ µm⁻¹.
pub(crate) type WattsPerSquareMeterSteradianMicrometer =
    Quantity<WattPerSquareMeterSteradianMicrometer>;

/// Solar radio flux unit:
/// 1 SFU = 10⁻²² W m⁻² Hz⁻¹.
///
/// `qtty` currently has no spectral-flux-density dimension, so this is kept as
/// a dimensionless convention unit until the upstream dimensional catalogue can
/// represent W m⁻² Hz⁻¹.
#[derive(Clone, Copy, Debug, PartialEq, PartialOrd, siderust::qtty::Unit)]
#[unit(
    crate = qtty,
    symbol = "SFU",
    dimension = siderust::qtty::dimensionless::Dimensionless,
    ratio = 1.0
)]
pub struct SolarFluxUnit;

/// Solar radio flux in solar flux units.
pub type SolarFluxUnits = Quantity<SolarFluxUnit>;

/// Atmospheric extinction coefficient in magnitudes per airmass.
///
/// This is a dimensionless atmospheric convention. The name preserves the
/// domain meaning while allowing qtty-style construction and comparison.
#[derive(Clone, Copy, Debug, PartialEq, PartialOrd, siderust::qtty::Unit)]
#[unit(
    crate = qtty,
    symbol = "mag·airmass⁻¹",
    dimension = siderust::qtty::dimensionless::Dimensionless,
    ratio = 1.0
)]
pub(crate) struct MagnitudePerAirmass;

/// Atmospheric extinction coefficients in mag per airmass.
pub(crate) type MagnitudesPerAirmass = Quantity<MagnitudePerAirmass>;

/// Luminance convention used by Krisciunas & Schaefer: nanolamberts.
#[derive(Clone, Copy, Debug, PartialEq, PartialOrd, siderust::qtty::Unit)]
#[unit(
    crate = qtty,
    symbol = "nL",
    dimension = siderust::qtty::dimensionless::Dimensionless,
    ratio = 1.0
)]
pub(crate) struct Nanolambert;

/// Brightness in nanolamberts.
pub(crate) type Nanolamberts = Quantity<Nanolambert>;

/// Integrated photon flux over a pixel solid angle.
pub(crate) type PixelIntegratedPhotonFlux =
    Quantity<unit::Prod<unit::PhotonPerSquareCentimeterNanosecondSteradian, unit::Steradian>>;

#[cfg(test)]
mod tests {
    use super::*;
    use crate::units::radiometry::PhotonPerSquareCentimeterNanosecondSteradianNanometer;

    #[test]
    fn skycalc_spectral_photon_radiance_converts_to_band_units() {
        let converted = SkyCalcSpectralPhotonRadiance::new(1.0)
            .to::<PhotonPerSquareCentimeterNanosecondSteradianNanometer>();
        assert!((converted.value() - 4.254_517_029_022_576e-6).abs() < 1.0e-18);
    }

    #[test]
    fn skycalc_spectral_photon_radiance_round_trips() {
        let original = SkyCalcSpectralPhotonRadiance::new(123.456);
        let round_trip = original
            .to::<PhotonPerSquareCentimeterNanosecondSteradianNanometer>()
            .to::<SkyCalcPhotonPerSquareMeterSecondSquareArcsecondMicrometer>();
        let rel = (round_trip.value() - original.value()).abs() / original.value();
        assert!(rel < 1.0e-12);
    }

    #[test]
    fn solar_spectral_irradiance_uses_qtty_dimension_algebra() {
        let irradiance = SolarSpectralIrradiance::new(2.5);
        assert_eq!(irradiance.value(), 2.5);
    }
}