Skip to content

Error Handling

SOLWEIG uses structured exceptions for diagnostic error reporting.

Exception Hierarchy

SolweigError (base)
├── InvalidSurfaceData
├── GridShapeMismatch
├── MissingPrecomputedData
├── WeatherDataError
└── ConfigurationError

Catching Errors

import solweig
from solweig.errors import GridShapeMismatch, MissingPrecomputedData, SolweigError

try:
    result = solweig.calculate(surface, location, weather, output_dir="output/")
except GridShapeMismatch as e:
    print(f"Grid mismatch: {e.field}")
    print(f"  Expected: {e.expected}")
    print(f"  Got: {e.got}")
except MissingPrecomputedData as e:
    print(f"Missing data: {e}")
    print(f"  Suggestion: {e.suggestion}")
except SolweigError as e:
    print(f"Error: {e}")

SolweigError

solweig.errors.SolweigError

Bases: Exception

Base class for all SOLWEIG errors.

GridShapeMismatch

solweig.errors.GridShapeMismatch

Bases: InvalidSurfaceData

Raised when grid shapes don't match the DSM.

All surface grids (CDSM, DEM, TDSM, land_cover, etc.) must have the same shape as the DSM.

Example

surface = SurfaceData(dsm=np.ones((100, 100)), cdsm=np.ones((50, 50))) GridShapeMismatch: Grid shape mismatch for 'cdsm': Expected: (100, 100) (matching DSM) Got: (50, 50)

MissingPrecomputedData

solweig.errors.MissingPrecomputedData

Bases: SolweigError

Raised when required precomputed data is not available.

Some features require precomputed data (e.g., anisotropic sky needs shadow matrices). This error explains what's missing and how to fix it.

Attributes:

Name Type Description
what

Description of the missing data.
suggestion

How to fix the issue (optional).

InvalidSurfaceData

solweig.errors.InvalidSurfaceData

Bases: SolweigError

Raised when surface data is invalid or inconsistent.

Attributes:

Name Type Description
message

Human-readable error description.
field

Name of the problematic field (e.g., "cdsm", "dem").
expected

What was expected (optional).
got

What was actually provided (optional).

WeatherDataError

solweig.errors.WeatherDataError

Bases: SolweigError

Raised when weather data is invalid.

Attributes:

Name Type Description
field

The problematic weather field (e.g., "ta", "rh").
value

The invalid value.
reason

Why the value is invalid.

ConfigurationError

solweig.errors.ConfigurationError

Bases: SolweigError

Raised when configuration is invalid or inconsistent.

Attributes:

Name Type Description
parameter

The problematic parameter name.
reason

Why the configuration is invalid.

Pre-Flight Validation

Use validate_inputs() to identify errors before computation:

from solweig.errors import GridShapeMismatch, MissingPrecomputedData

try:
    warnings = solweig.validate_inputs(surface, location, weather)
    for w in warnings:
        print(f"Warning: {w}")

    result = solweig.calculate(surface, location, weather, output_dir="output/")

except GridShapeMismatch as e:
    print(f"Grid shape mismatch: {e.field}")
except MissingPrecomputedData as e:
    print(f"Missing required data: {e}")

This catches shape mismatches, missing data, and other issues prior to SVF computation.