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
148

# nsb

Night-sky background evaluation and observation planning for ground-based
astronomy.

This is the scientific runtime library for NSB. It provides typed point
evaluation and observing-window search over the production-safe composition of
zodiacal light, airglow, scattered moonlight, and an admitted integrated
starlight product when one is available.

## Installation

```bash
cargo add nsb@0.1.0
```

The minimum supported Rust version is 1.89.

NSB deliberately uses domain types from Siderust and tempoch at public
boundaries instead of duplicating coordinate, atmosphere, or time semantics.
Applications that construct those upstream types directly should add the
corresponding dependencies as needed.

## Cargo features

`serde` is enabled by default for backwards compatibility. It forwards
serialization support to `siderust` (including its coordinate and quantity
dependencies) and `tempoch`, covering the upstream `Observer`, `Target`,
and UTC `Time` types used at NSB's public Rust boundary.

To build without upstream Serde support:

```toml
nsb = { version = "0.1.0", default-features = false }
```

NSB's own internal TOML/JSON data formats remain available independently
of this feature; `serde` does not imply that all NSB evaluator, configuration,
or result structs implement Serde.

QTTY defines `SurfaceBrightness` (mag/arcsec²), which NSB re-exports through
`nsb::units::photometry`. This photometric newtype does not currently implement
Serde's traits upstream. Under `nsb/serde`, the
`nsb::serde_support::surface_brightness` field adapter lets applications
deserialize or serialize it as a plain JSON number without a separate wire
`f64` field or a duplicate physical type:

```rust
use nsb::units::photometry::SurfaceBrightness;
use serde::{Deserialize, Serialize};

#[derive(Deserialize, Serialize)]
struct NsbConstraintRequest {
    #[serde(with = "nsb::serde_support::surface_brightness")]
    minimum_nsb_in_mag_arcsec2: SurfaceBrightness,
    #[serde(with = "nsb::serde_support::surface_brightness")]
    maximum_nsb_in_mag_arcsec2: SurfaceBrightness,
}
```

The JSON remains `{"minimum_nsb_in_mag_arcsec2":21.39,"maximum_nsb_in_mag_arcsec2":30.0}`.
Application code must still validate finite, positive, ordered bounds before
converting magnitudes into profile-dependent photon radiance. This adapter
does not add validation to QTTY's type.

## Minimal Rust workflow

```rust,no_run
use nsb::{ComponentMask, NsbEvaluator, PointQuery, Target, DEG};
use siderust::catalogs::observatories;

# fn evaluate(time: tempoch::Time<tempoch::UTC>) -> nsb::Result<()> {
let evaluator = NsbEvaluator::new()?;
let query = PointQuery::new(
    observatories::EL_PARANAL.geodetic(),
    time,
    Target::new(266.41683 * DEG, -29.00781 * DEG),
)
.with_components(ComponentMask::ALL);

let result = evaluator.evaluate(&query)?;
println!("{}", result.integrated);
for component in &result.components {
    println!("{}: {}", component.name, component.integrated);
}
# Ok(())
# }
```

Construct an evaluator once and reuse it. Immutable model data and runtime
assets are prepared during evaluator construction.

## Scientific interpretation

`ComponentMask::DEFAULT` and `ComponentMask::ALL` are the same
production-safe composition for the `0.1.x` model contract. Starlight enters
that composition only when a validated production map is embedded. The
frozen candidate remains repository evidence; packages contain the approved
compact binary and sidecar, with all scientific f64 values preserved.

Observatory coordinates and scientific site assumptions are separate. The core
crate exposes generic typed site profiles; CTAO North/South planning presets
belong to application layers and are not site-calibration claims.

B/V magnitude and S10 outputs are central-wavelength diagnostics, not validated
Johnson B/V passband integrations. Consult component maturity, provenance,
validated-domain, uncertainty, and asset metadata before making scientific or
operational claims.

## Interfaces and documentation

- Rust API: <https://docs.rs/nsb>
- Repository documentation: <https://github.com/VPRamon/NSB/tree/main/docs>
- Scientific model: <https://github.com/VPRamon/NSB/blob/main/docs/specifications/scientific-model.md>
- Model maturity: <https://github.com/VPRamon/NSB/blob/main/docs/specifications/model-maturity.md>
- Validation matrix: <https://github.com/VPRamon/NSB/blob/main/docs/specifications/validation.md>
- Python distribution: `nsb-rust` on PyPI, imported as `nsb`
- CLI: sibling workspace crate `nsb-cli` (binary name `nsb`; not separately
  published in `0.1.0`)

The CLI owns command-line parsing, named-site lookup, and stable JSON/CSV
rendering. Offline catalogue acquisition and scientific data-product generation
belong to `nsb-data-tools`; the runtime library performs no catalogue downloads.

## License

AGPL-3.0-only. Scientific assets and third-party dependencies retain their own
licensing and attribution requirements; see the [notices included in this
crate](THIRD_PARTY_NOTICES.md) and the repository asset manifests.

## Scientific data and licensing

NSB **code** is AGPL-3.0-only; that does not make all scientific data AGPL.
PALACE and selected reference products use CC BY 4.0, NOAA products have their
applicable federal-work/data conditions, and Gaia-derived Starlight retains
applicable **CC BY-NC 3.0 IGO** terms. The code may be used commercially under
AGPL's obligations; commercial use of protected bundled data may need separate
rights. Credits do not imply endorsement by ESA, DPAC, CDS or the authors.

The approved compact Starlight map is embedded for fully offline evaluation.
`ALL`, `DEFAULT` and the standard Rust/Python evaluator include Starlight,
Airglow, Moonlight and Zodiacal Light. The maintainer accepted the pinned
calculated-output and independent-data findings under #103; source-specific
licences and noncommercial data restrictions remain applicable.

See the [source terms, attribution, public contact directory and concern procedure](https://github.com/VPRamon/NSB/blob/main/docs/nsb_components/starlight/licensing/README.md)
and the distributed `THIRD_PARTY_NOTICES.md`. Cite the original scientific
sources, preserve their notices and assess the data terms for your actual use.