Core Functions

calculate

solweig.calculate(surface, weather, location=None, *, output_dir, config=None, human=None, precomputed=None, use_anisotropic_sky=None, conifer=False, physics=None, materials=None, wall_material=None, max_shadow_distance_m=None, outputs=None, heat_thresholds_day=None, heat_thresholds_night=None, progress_callback=None)

Calculate mean radiant temperature (Tmrt).

Single entry point for all SOLWEIG calculations. SVF and shadow matrices must already be on surface (via :meth:SurfaceData.prepare) or in precomputed. The anisotropic sky model is on by default.

Parameters:

Name	Type	Description	Default
surface	SurfaceData	Prepared surface data from :meth:SurfaceData.prepare.	required
weather	list[Weather]	One or more Weather objects.	required
location	Location | None	Geographic location. If None, extracted from surface CRS.	None
config	ModelConfig | None	Model settings. Explicit keyword args override config values.	None
human	HumanParams | None	Human body parameters (posture, absorption, etc.).	None
precomputed	PrecomputedData | None	Alternative source for SVF/shadow matrices (advanced).	None
use_anisotropic_sky	bool | None	Anisotropic (True) or uniform (False) sky diffuse radiation. Default True.	None
conifer	bool	Treat vegetation as evergreen (always leaf-on).	False
physics	SimpleNamespace | None	Physics parameters from load_physics().	None
materials	SimpleNamespace | None	Material properties from load_materials().	None
wall_material	str | None	Wall material type ("brick", "concrete", "wood", "cobblestone").	None
max_shadow_distance_m	float | None	Maximum shadow reach in metres (default 1000.0).	None
output_dir	str | Path	Working directory for all output. Summary grids are always saved to output_dir/summary/. Per-timestep GeoTIFFs are saved when outputs is specified.	required
outputs	list[str] | None	Which per-timestep outputs to save as GeoTIFFs (e.g., ["tmrt", "shadow"]). If None, only summary grids are saved.	None
heat_thresholds_day	list[float] | None	Daytime UTCI thresholds for exceedance grids.	None
heat_thresholds_night	list[float] | None	Nighttime UTCI thresholds for exceedance grids.	None
progress_callback	Callable[[int, int], None] | None	Called as progress_callback(current, total) per timestep.	None

Returns:

Type	Description
TimeseriesSummary	TimeseriesSummary with per-pixel grids (mean/max/min Tmrt and UTCI,
TimeseriesSummary	sun/shade hours, heat-stress exceedance).

Example::

surface = solweig.SurfaceData.prepare(dsm="dsm.tif", working_dir="cache/")
weather = solweig.Weather.from_epw("weather.epw")

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

---

validate_inputs

solweig.api.validate_inputs(surface, location=None, weather=None, use_anisotropic_sky=False, precomputed=None)

Validate inputs before calculation (preflight check).

Call this before expensive operations to catch errors early. Raises exceptions for fatal errors, returns warnings for potential issues.

Parameters:

Name	Type	Description	Default
surface	SurfaceData	Surface data to validate.	required
location	Location | None	Location to validate (optional).	None
weather	Weather | list[Weather] | None	Weather data to validate (optional, can be single or list).	None
use_anisotropic_sky	bool	Whether anisotropic sky will be used.	False
precomputed	PrecomputedData | None	Precomputed data to validate.	None

Returns:

Type	Description
list[str]	List of warning messages (empty if all valid).

Raises:

Type	Description
GridShapeMismatch	If surface grid shapes don't match DSM.
MissingPrecomputedData	If required precomputed data is missing.
WeatherDataError	If weather data is invalid.

Example

try: warnings = solweig.validate_inputs(surface, location, weather) for w in warnings: print(f"Warning: {w}") result = solweig.calculate(surface, location, weather) except solweig.GridShapeMismatch as e: print(f"Grid mismatch: {e.field} expected {e.expected}, got {e.got}") except solweig.MissingPrecomputedData as e: print(f"Missing data: {e}")