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

// SPDX-License-Identifier: AGPL-3.0-only
// Copyright (C) 2026 Vallés Puig, Ramon
//! Error type for the NSB crate.
//!
//! Scientific role:
//! scientific code is only as trustworthy as its failure modes. This module
//! defines the explicit ways the NSB calculation can fail: malformed bundled
//! reference data, invalid geometry/ranges, unsupported model requests, or
//! interpolation issues.
//!
//! Contribution to the science:
//! by separating parse, range, and interpolation failures, this
//! file helps users distinguish between "the sky model says the answer is X"
//! and "the model could not be evaluated reliably for this input or dataset."

use thiserror::Error;

/// Failures returned by NSB model construction and evaluation.
///
/// This enum is `#[non_exhaustive]`: new variants may be added in minor
/// releases. Supported callers should match the documented variants they handle
/// and keep a wildcard arm.
///
/// Existing variant shapes and field payloads are part of the public contract.
/// Adding fields to an existing variant is a breaking change unless that
/// variant is separately redesigned for extensibility. Treat `Display` and
/// `source()` as the stable diagnostic interfaces for logging and reporting.
#[derive(Debug, Error)]
#[non_exhaustive]
pub enum NsbError {
    /// A bundled or caller-provided data file could not be parsed.
    #[error("data parse error in {file}: {message}")]
    DataParse {
        /// Logical data-file name.
        file: &'static str,
        /// Parse failure detail.
        message: String,
    },

    /// Required scientific data were unavailable.
    #[error("required data missing: {file}: {message}")]
    DataMissing {
        /// Logical data-file name.
        file: &'static str,
        /// Missing-data detail.
        message: String,
    },

    /// A starlight map failed schema or value validation.
    #[error("invalid starlight map: {message}")]
    InvalidMap {
        /// Validation failure detail.
        message: String,
    },

    /// An input lies outside the supported numeric/domain range.
    #[error("input out of range: {0}")]
    OutOfRange(String),

    /// The selected model configuration is not evaluable.
    #[error("unsupported configuration: {0}")]
    Unsupported(String),

    /// A table interpolation failed.
    #[error("interpolation error: {0}")]
    Interpolation(String),

    /// Filesystem input/output failure.
    #[error("io error: {0}")]
    Io(#[from] std::io::Error),
}

/// Crate result alias.
pub type Result<T> = std::result::Result<T, NsbError>;