Error Handling

SOLWEIG uses structured exceptions for diagnostic error reporting.

Exception Hierarchy

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

Catching Errors

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

try:
    result = solweig.calculate(surface, weather=[weather], location=location, 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).

---

StalePrecomputedData

solweig.errors.StalePrecomputedData

Bases: SolweigError

Raised when a cached SVF/shadow dataset was computed for a different raster.

A prepared surface directory can accumulate SVF and shadow-matrix caches from earlier runs (a different extent, resolution, or study area). Loading such a cache against the current DSM would fail later with a confusing grid-shape error, so the mismatch is reported at load time with the offending cache path.

Attributes:

Name	Type	Description
what		Which cached dataset mismatched (e.g., "SVF").
cache_dir		Directory the stale cache was loaded from.
expected_shape		Grid shape of the current DSM.
actual_shape		Grid shape the cache was computed for.

---

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.

---

ComputationCancelled

solweig.errors.ComputationCancelled

Bases: SolweigError

Raised when a long-running computation is cancelled by the user.

Raised on cancellation (e.g. QGIS feedback isCanceled()) so partial results are never persisted as valid caches. Callers that treat cancellation as a graceful stop should catch this and return.

Attributes:

Name	Type	Description
stage		The computation stage that was cancelled (e.g., "SVF").

---

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, weather=[weather], location=location, 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.