Night-sky background evaluation and observation planning for ground-based astronomy.
NSB estimates the optical night-sky background at an observatory, UTC time, and target direction. It also finds observing windows that satisfy sky-brightness, Sun-altitude, and target-altitude constraints. Use the same Rust-powered scientific engine from Rust, Python, or the command line.
Integrated starlight data product in Galactic coordinates; not a total NSB prediction.
NSB combines zodiacal light, integrated starlight, airglow and scattered moonlight. The default configuration is a planning model, not an observatory-calibrated prediction of absolute night-sky brightness.
In v0.3.0, Automatic Airglow selects the experimental PALACE Oxygen model
(ParanalPalaceOxygenV1), valid for the standard continuum geometry and
zenith distances up to 60°. Outside that domain NSB returns an explicit
error rather than substituting a different model. Select
ParanalPalaceV1 for continuum-only calculations and broader geometries;
that is a different physical model, not a calibrated substitute.
The integrated Starlight product is a provenance-checked 300–650 nm map; its cross-implementation validation does not establish absolute observational accuracy. CTAO site profiles are planning presets, not site calibrations. See the scientific validation and limitations before interpreting predictions or using them in a scientific publication. The model maturity contract specifies the status and validated domain of each component.
This source checkout targets NSB 0.3.0. Registry installation of that version requires the corresponding release to be published; before publication, use a source checkout to test the candidate. For reproducible applications, pin the exact released version and record the scientific asset and model identities.
Choose the interface that fits your workflow:
| Interface | Installation | Requirements |
|---|---|---|
| Python | python -m pip install nsb-py |
Python 3.10+ |
| Rust | cargo add nsb |
Rust 1.89+ |
| CLI | Build from the repository (below) | Rust 1.89+ |
For reproducible applications after v0.3.0 publication, install
cargo add nsb@0.3.0 or python -m pip install nsb-py==0.3.0.
For the Rust query-target and Python direction migrations since v0.2.0, see
the release notes and Python guide.
The PyPI distribution is nsb-py, but its import is nsb.
The crates.io library is nsb. The executable is also named nsb,
but its workspace crate, nsb-cli, is not separately published to crates.io.
Install the CLI from the repository:
git clone https://github.com/VPRamon/NSB.git
cd NSB
cargo install --path crates/nsb-cli --locked
nsb --helpThe Rust example below uses the same UTC instant, coordinates and target as the Python example. It also uses Siderust, Tempoch and Chrono at the API boundary; add the matching dependencies to your application:
cargo add nsb@0.3.0 siderust@0.15.1 tempoch@0.11.1 chrono@0.4All examples use Sagittarius A* (RA 266.41683°, Dec −29.00781°).
Point evaluations return integrated photon radiance over 300–650 nm
in ph cm^-2 ns^-1 sr^-1.
from datetime import datetime, timezone
import nsb
import siderust
from siderust.direction import ICRS
observer = siderust.Observer(
lon_deg=-70.31634, lat_deg=-24.683427, height_m=2184.6
)
target = ICRS(ra_deg=266.41683, dec_deg=-29.00781)
evaluator = nsb.NsbEvaluator()
result = evaluator.evaluate(
nsb.PointQuery(observer, datetime(2026, 6, 19, 3, tzinfo=timezone.utc), target)
)
print(f"NSB: {result.integrated_photons_cm2_ns_sr:.3e} ph/(cm² ns sr)")This example uses CTAO South's coordinates with the generic clear-sky profile and experimental Automatic Oxygen Airglow, not a site-calibrated CTAO model. The chosen night-time target lies within Oxygen's zenith-distance ≤60° domain. Python input times must be timezone-aware. For component breakdowns, planning and site profiles, see the Python guide.
use chrono::{DateTime, Utc};
use nsb::{NsbEvaluator, PointQuery, Target, DEG};
use siderust::coordinates::centers::Geodetic;
use siderust::coordinates::frames::ECEF;
use siderust::qtty::{Degrees, Meters};
use tempoch::{Time, UTC};
fn main() -> nsb::Result<()> {
let utc = DateTime::parse_from_rfc3339("2026-06-19T03:00:00Z")
.unwrap()
.with_timezone(&Utc);
let query = PointQuery::new(
Geodetic::<ECEF>::new_raw(
Degrees::new(-70.31634),
Degrees::new(-24.683427),
Meters::new(2184.6),
),
Time::<UTC>::from_chrono(utc),
Target::new(266.41683 * DEG, -29.00781 * DEG),
);
let result = NsbEvaluator::new()?.evaluate(&query)?;
println!("NSB: {:.3e} ph/(cm² ns sr)", result.integrated.value());
Ok(())
}The equivalent, CI-compiled example can be run from a checkout:
cargo run --locked -p nsb --example point_querySee more Rust examples and the Rust API documentation. NSB uses Siderust and Tempoch types at its public Rust boundaries.
After installing the executable above, evaluate the same target, time and coordinates with the same generic clear-sky assumptions:
nsb --format table point \
--time 2026-06-19T03:00:00Z \
--lon -70.31634 --lat -24.683427 --height 2184.6 \
--site-profile generic-clear-sky \
--ra 266.41683 --dec -29.00781Use --format json or --format csv for machine-readable output.
For observing-window searches (nsb window), named observatories and advanced
options, follow the CLI getting-started guide.
| Capability | What you get |
|---|---|
| Evaluate sky background | Integrated radiance and per-component contributions for a target, site and UTC instant |
| Plan observing windows | Periods satisfying an NSB threshold and optional Sun/target-altitude limits |
| Choose sky models | Zodiacal light, airglow, scattered moonlight and admitted integrated starlight products |
| Integrate with pipelines | Stable, versioned CLI JSON/CSV schemas and reusable library APIs |
| Inspect scientific provenance | Model identity, component maturity, validated domain and uncertainty where available |
| Run offline | Local deterministic evaluation for fixed inputs and admitted scientific assets |
NSB deliberately distinguishes observatory coordinates from scientific site assumptions. Generic clear-sky and CTAO planning presets are not site-calibrated predictions. Starlight inclusion follows validation and admission rules; an experimental candidate is never silently substituted. Reported B/V magnitude and S10 values are central-wavelength diagnostics, not validated Johnson B/V passband integrations.
For scientific use, review model maturity, validation and scientific metadata.
| Start here | Covers |
|---|---|
| Examples index | Runnable Rust examples, Python and CLI guides |
| Python bindings | Installation, point evaluation, window planning and API types |
| Getting started | CLI usage, site selection and first Rust workflows |
| Observatory configuration | Named sites, custom coordinates and site profiles |
| Scientific validation | Evidence, limitations, uncertainties and fitness for scientific use |
| Scientific model | Physical contributions and modeling assumptions |
| CLI output schemas | Versioned JSON/CSV for automation |
| Documentation hub | Full user, developer and maintainer documentation |
The source of truth for the version is
crates/nsb/Cargo.toml; Maturin derives the Python
package version from that same manifest. The
tag-triggered release workflow builds and
checks the Rust crate, Python wheels and source distribution before uploading
anything.
The CLI remains a source-installed workspace application in 0.3.0.
NSB source code is licensed under AGPL-3.0-only. Scientific datasets and third-party dependencies retain their own licensing and attribution requirements; the code license does not grant rights to all underlying data.
Some reference products are CC BY 4.0, NOAA data follows its applicable conditions, and Gaia-derived starlight retains applicable CC BY-NC 3.0 IGO terms. Commercial use of protected scientific data may require separate permissions. Credits do not imply endorsement by ESA, DPAC, CDS or the scientific authors.
Read the Starlight source terms and attribution and third-party notices before redistributing data or using model outputs for scientific claims. Cite the software using CITATION.cff and record the exact release and model configuration.
nsb::transport::single::single_scattering provides a separate opt-in scalar
reference for synthetic wavelength-resolved TOA illumination (360–570 nm,
output zenith 0–80°). Direct and first-order spectral photon radiance are separate;
higher orders are uncomputed. Evaluator/component defaults do not use this solver.
Run cargo run -p nsb --example single_scattering from the repository.
transport::single::starlight adapts checksum-validated native spectral bins
with explicit flat photon density, local site/TT/UT1 geometry and independently
refined full-bin wavelength integration. Run the offline starlight_transport
example. A conservative HEALPix subpixel path resolves the frozen Gaia angular
case; the labelled historical comparison retains explicit astrometric differences. See the spectral contract
for the bounded numerical method and diagnostic limitations.
The transport APIs use published Siderust 0.15.1 with the coordinated Python 0.5 bridges. This remains an experimental physical reference, with no empirical sky-accuracy or complete transport claim.
