shine.config

Configuration handling with Pydantic models.

Parses YAML configuration files and validates all parameters. Distribution parameters (Normal, LogNormal, Uniform) are automatically treated as latent variables for Bayesian inference. The InferenceConfig supports three inference methods (NUTS, MAP, VI) with method-specific config blocks (NUTSConfig, MAPConfig, VIConfig).

config

DistributionConfig

Bases: BaseModel

Configuration for probability distributions used as priors.

Supports Normal, LogNormal, and Uniform distributions with appropriate parameters.

Attributes:

Name	Type	Description
type	str	Distribution type (e.g., 'Normal', 'LogNormal', 'Uniform').
mean	Optional[float]	Mean parameter for Normal/LogNormal distributions.
sigma	Optional[float]	Standard deviation for Normal/LogNormal distributions.
min	Optional[float]	Lower bound for Uniform distributions.
max	Optional[float]	Upper bound for Uniform distributions.

validate_sigma_positive(v) classmethod

Validate that sigma is positive when provided.

Source code in shine/config.py

@field_validator("sigma")
@classmethod
def validate_sigma_positive(cls, v: Optional[float]) -> Optional[float]:
    """Validate that sigma is positive when provided."""
    if v is not None and v <= 0:
        raise ValueError(f"sigma must be positive, got {v}")
    return v

validate_distribution_params()

Validate distribution type has required parameters.

Source code in shine/config.py

@model_validator(mode="after")
def validate_distribution_params(self) -> "DistributionConfig":
    """Validate distribution type has required parameters."""
    if self.type == "Normal" and (self.mean is None or self.sigma is None):
        raise ValueError(
            "Normal distribution requires 'mean' and 'sigma' parameters"
        )

    if self.type == "Uniform" and (self.min is None or self.max is None):
        raise ValueError(
            "Uniform distribution requires 'min' and 'max' parameters"
        )

    if self.type == "Uniform" and self.min >= self.max:
        raise ValueError(
            f"For Uniform distribution, min ({self.min}) must be less than max ({self.max})"
        )

    return self

NoiseConfig

Bases: BaseModel

Configuration for noise properties in observations.

Attributes:

Name	Type	Description
type	str	Noise distribution type (currently only 'Gaussian' is supported).
sigma	float	Standard deviation of the Gaussian noise.

validate_sigma_positive(v) classmethod

Validate that noise sigma is positive.

Source code in shine/config.py

@field_validator("sigma")
@classmethod
def validate_sigma_positive(cls, v: float) -> float:
    """Validate that noise sigma is positive."""
    if v <= 0:
        raise ValueError(f"Noise sigma must be positive, got {v}")
    return v

ImageConfig

Bases: BaseModel

Configuration for image properties and rendering parameters.

Attributes:

Name	Type	Description
pixel_scale	float	Physical size of one pixel in arcseconds.
size_x	int	Image width in pixels.
size_y	int	Image height in pixels.
n_objects	int	Number of galaxy objects to simulate/infer (default 1).
noise	NoiseConfig	Noise configuration for the observation.
fft_size	int	FFT size for JAX-GalSim rendering, must be a power of 2 (default 128).

validate_pixel_scale_positive(v) classmethod

Validate that pixel scale is positive.

Source code in shine/config.py

@field_validator("pixel_scale")
@classmethod
def validate_pixel_scale_positive(cls, v: float) -> float:
    """Validate that pixel scale is positive."""
    if v <= 0:
        raise ValueError(f"Pixel scale must be positive, got {v}")
    return v

validate_dimensions_positive(v) classmethod

Validate that image dimensions are positive.

Source code in shine/config.py

@field_validator("size_x", "size_y")
@classmethod
def validate_dimensions_positive(cls, v: int) -> int:
    """Validate that image dimensions are positive."""
    if v <= 0:
        raise ValueError(f"Image dimensions must be positive, got {v}")
    return v

validate_n_objects_positive(v) classmethod

Validate that number of objects is positive.

Source code in shine/config.py

@field_validator("n_objects")
@classmethod
def validate_n_objects_positive(cls, v: int) -> int:
    """Validate that number of objects is positive."""
    if v <= 0:
        raise ValueError(f"Number of objects must be positive, got {v}")
    return v

validate_fft_size(v) classmethod

Validate that fft_size is a positive power of 2.

Source code in shine/config.py

@field_validator("fft_size")
@classmethod
def validate_fft_size(cls, v: int) -> int:
    """Validate that fft_size is a positive power of 2."""
    if v <= 0:
        raise ValueError(f"fft_size must be positive, got {v}")
    if v & (v - 1) != 0:
        raise ValueError(f"fft_size must be a power of 2, got {v}")
    return v

PSFConfig

Bases: BaseModel

Configuration for Point Spread Function (PSF) models.

Supports Gaussian and Moffat profiles.

Attributes:

Name	Type	Description
type	str	PSF model type ('Gaussian' or 'Moffat').
sigma	float	Width parameter for the PSF in arcseconds.
beta	Optional[float]	Moffat beta parameter (only used for Moffat PSF, default 2.5).

validate_sigma_positive(v) classmethod

Validate that PSF sigma is positive.

Source code in shine/config.py

@field_validator("sigma")
@classmethod
def validate_sigma_positive(cls, v: float) -> float:
    """Validate that PSF sigma is positive."""
    if v <= 0:
        raise ValueError(f"PSF sigma must be positive, got {v}")
    return v

validate_beta_positive(v) classmethod

Validate that Moffat beta is positive when provided.

Source code in shine/config.py

@field_validator("beta")
@classmethod
def validate_beta_positive(cls, v: Optional[float]) -> Optional[float]:
    """Validate that Moffat beta is positive when provided."""
    if v is not None and v <= 0:
        raise ValueError(f"Moffat beta must be positive, got {v}")
    return v

ShearComponentConfig

Bases: BaseModel

Configuration for individual shear components (g1 or g2).

Allows specification of shear components as either fixed values or distributions.

Attributes:

Name	Type	Description
type	Optional[str]	Distribution type (optional, None for fixed values).
mean	Optional[float]	Mean value for the shear component (default 0.0).
sigma	Optional[float]	Standard deviation for the shear component distribution (default 0.05).

ShearConfig

Bases: BaseModel

Configuration for gravitational shear parameters.

Defines the shear as two components (g1, g2) which can be either fixed values or distributions for Bayesian inference.

Attributes:

Name	Type	Description
type	str	Shear parameterization type (e.g., 'G1G2' for reduced shear).
g1	Union[float, DistributionConfig]	First shear component (fixed value or distribution).
g2	Union[float, DistributionConfig]	Second shear component (fixed value or distribution).

EllipticityConfig

Bases: BaseModel

Configuration for intrinsic galaxy ellipticity.

Defines the intrinsic ellipticity of galaxies before shearing, parameterized as two components (e1, e2).

Attributes:

Name	Type	Description
type	str	Ellipticity parameterization type (e.g., 'E1E2').
e1	Union[float, DistributionConfig]	First ellipticity component (fixed value or distribution).
e2	Union[float, DistributionConfig]	Second ellipticity component (fixed value or distribution).

PositionConfig

Bases: BaseModel

Configuration for galaxy position priors.

Defines the prior distribution over galaxy positions in the image. Values less than 1 are treated as fractions of image size, values >= 1 as pixels.

Attributes:

Name	Type	Description
type	str	Distribution type for positions (default 'Uniform').
x_min	Optional[float]	Minimum x position (fraction if < 1, pixels if >= 1).
x_max	Optional[float]	Maximum x position (fraction if < 1, pixels if >= 1).
y_min	Optional[float]	Minimum y position (fraction if < 1, pixels if >= 1).
y_max	Optional[float]	Maximum y position (fraction if < 1, pixels if >= 1).

validate_position_bounds()

Validate that position bounds are consistent.

Source code in shine/config.py

@model_validator(mode="after")
def validate_position_bounds(self) -> "PositionConfig":
    """Validate that position bounds are consistent."""
    if self.x_min is not None and self.x_max is not None and self.x_min >= self.x_max:
        raise ValueError(
            f"x_min ({self.x_min}) must be less than x_max ({self.x_max})"
        )
    if self.y_min is not None and self.y_max is not None and self.y_min >= self.y_max:
        raise ValueError(
            f"y_min ({self.y_min}) must be less than y_max ({self.y_max})"
        )
    return self

GalaxyConfig

Bases: BaseModel

Configuration for galaxy morphology and properties.

Attributes:

Name	Type	Description
type	str	Galaxy profile type (e.g., 'Exponential', 'Sersic').
n	Optional[Union[float, DistributionConfig]]	Sersic index (optional, not used for Exponential profiles).
flux	Union[float, DistributionConfig]	Total flux of the galaxy (fixed value or distribution).
half_light_radius	Union[float, DistributionConfig]	Half-light radius in arcseconds (fixed value or distribution).
ellipticity	Optional[EllipticityConfig]	Intrinsic ellipticity configuration (optional).
shear	ShearConfig	Gravitational shear configuration.
position	Optional[PositionConfig]	Position prior configuration (optional).

MAPConfig

Bases: BaseModel

Configuration for Maximum A Posteriori (MAP) initialization.

Attributes:

Name	Type	Description
enabled	bool	Whether MAP initialization is enabled (default False).
num_steps	int	Number of optimization steps for MAP estimation (default 1000).
learning_rate	float	Learning rate for MAP optimization (default 1e-2).

validate_num_steps_positive(v) classmethod

Validate that number of MAP steps is positive.

Source code in shine/config.py

@field_validator("num_steps")
@classmethod
def validate_num_steps_positive(cls, v: int) -> int:
    """Validate that number of MAP steps is positive."""
    if v <= 0:
        raise ValueError(f"Number of MAP steps must be positive, got {v}")
    return v

validate_learning_rate_positive(v) classmethod

Validate that learning rate is positive.

Source code in shine/config.py

@field_validator("learning_rate")
@classmethod
def validate_learning_rate_positive(cls, v: float) -> float:
    """Validate that learning rate is positive."""
    if v <= 0:
        raise ValueError(f"Learning rate must be positive, got {v}")
    return v

NUTSConfig

Bases: BaseModel

Configuration for NUTS/MCMC inference.

Attributes:

Name	Type	Description
warmup	int	Number of warmup/burn-in steps for MCMC (default 500).
samples	int	Number of posterior samples to draw (default 1000).
chains	int	Number of independent MCMC chains to run (default 1).
dense_mass	bool	Whether to use dense mass matrix in NUTS (default False).
map_init	Optional[MAPConfig]	Optional MAP initialization before NUTS.

validate_positive_integers(v, info) classmethod

Validate that warmup and samples are positive.

Source code in shine/config.py

@field_validator("warmup", "samples")
@classmethod
def validate_positive_integers(cls, v: int, info) -> int:
    """Validate that warmup and samples are positive."""
    if v <= 0:
        raise ValueError(f"{info.field_name} must be positive, got {v}")
    return v

validate_chains_positive(v) classmethod

Validate that number of chains is positive.

Source code in shine/config.py

@field_validator("chains")
@classmethod
def validate_chains_positive(cls, v: int) -> int:
    """Validate that number of chains is positive."""
    if v <= 0:
        raise ValueError(f"Number of chains must be positive, got {v}")
    return v

VIConfig

Bases: BaseModel

Configuration for Variational Inference.

Attributes:

Name	Type	Description
num_steps	int	Number of SVI optimization steps (default 5000).
learning_rate	float	Learning rate for SVI optimizer (default 1e-3).
num_samples	int	Number of posterior samples to draw from fitted guide (default 1000).

validate_positive_integers(v, info) classmethod

Validate that num_steps and num_samples are positive.

Source code in shine/config.py

@field_validator("num_steps", "num_samples")
@classmethod
def validate_positive_integers(cls, v: int, info) -> int:
    """Validate that num_steps and num_samples are positive."""
    if v <= 0:
        raise ValueError(f"{info.field_name} must be positive, got {v}")
    return v

validate_learning_rate_positive(v) classmethod

Validate that learning rate is positive.

Source code in shine/config.py

@field_validator("learning_rate")
@classmethod
def validate_learning_rate_positive(cls, v: float) -> float:
    """Validate that learning rate is positive."""
    if v <= 0:
        raise ValueError(f"Learning rate must be positive, got {v}")
    return v

InferenceConfig

Bases: BaseModel

Configuration for Bayesian inference settings.

Supports three inference methods: - "nuts": NUTS/MCMC sampling (default), optionally with MAP initialization. - "map": MAP point estimation only. - "vi": Variational Inference with AutoNormal guide.

Each method reads its own config block; the others are ignored. When a method's config block is None, defaults are applied.

Attributes:

Name	Type	Description
method	Literal['nuts', 'map', 'vi']	Inference method ("nuts", "map", or "vi").
nuts_config	Optional[NUTSConfig]	Configuration for NUTS/MCMC (used when method="nuts").
map_config	Optional[MAPConfig]	Configuration for MAP estimation (used when method="map").
vi_config	Optional[VIConfig]	Configuration for Variational Inference (used when method="vi").
rng_seed	int	Random number generator seed for reproducibility (default 0).

validate_rng_seed_non_negative(v) classmethod

Validate that RNG seed is non-negative.

Source code in shine/config.py

@field_validator("rng_seed")
@classmethod
def validate_rng_seed_non_negative(cls, v: int) -> int:
    """Validate that RNG seed is non-negative."""
    if v < 0:
        raise ValueError(f"RNG seed must be non-negative, got {v}")
    return v

ShineConfig

Bases: BaseModel

Top-level configuration for SHINE inference pipeline.

Attributes:

Name	Type	Description
image	ImageConfig	Image and rendering configuration.
psf	PSFConfig	Point Spread Function configuration.
gal	GalaxyConfig	Galaxy morphology and properties configuration.
inference	InferenceConfig	Bayesian inference settings (default factory creates default config).
data_path	Optional[str]	Path to observational data file (optional, None for synthetic data).
output_path	str	Directory path for saving results (default 'results').

ConfigHandler

Handler for loading and validating SHINE configuration files.

load(path) staticmethod

Load and validate configuration from YAML file.

Parameters:

Name	Type	Description	Default
path	str	Path to the YAML configuration file.	required

Returns:

Type	Description
ShineConfig	Validated ShineConfig object.

Raises:

Type	Description
FileNotFoundError	If config file does not exist.
YAMLError	If YAML parsing fails.
ValueError	If configuration validation fails.

Source code in shine/config.py

@staticmethod
def load(path: str) -> ShineConfig:
    """Load and validate configuration from YAML file.

    Args:
        path: Path to the YAML configuration file.

    Returns:
        Validated ShineConfig object.

    Raises:
        FileNotFoundError: If config file does not exist.
        yaml.YAMLError: If YAML parsing fails.
        ValueError: If configuration validation fails.
    """
    path = Path(path)
    if not path.exists():
        raise FileNotFoundError(
            f"Configuration file not found: {path}\n"
            f"Please provide a valid path to a YAML configuration file."
        )

    try:
        with open(path, "r") as f:
            data = yaml.safe_load(f)
    except yaml.YAMLError as e:
        raise yaml.YAMLError(
            f"Failed to parse YAML configuration file '{path}':\n{e}"
        ) from e

    if data is None:
        raise ValueError(
            f"Configuration file '{path}' is empty or contains only comments."
        )

    try:
        return ShineConfig(**data)
    except Exception as e:
        raise ValueError(
            f"Configuration validation failed for '{path}':\n{e}"
        ) from e