API Reference¶

Complete reference for the SOLWEIG public API.

Core Functions¶

Function	Description
`calculate()`	Single or multi-timestep Tmrt calculation (tiling is applied for large rasters)
`validate_inputs()`	Pre-flight input validation

Data Classes¶

Class	Description
`SurfaceData`	Terrain data (DSM, CDSM, walls, SVF)
`Location`	Geographic coordinates
`Weather`	Meteorological conditions
`HumanParams`	Human body parameters
`ModelConfig`	Runtime configuration
`Settings`	Resolved configuration `calculate()` works from internally
`TimeseriesSummary`	What `calculate()` returns — aggregated grids + per-timestep scalars
`Timeseries`	Per-timestep scalar series (inside `TimeseriesSummary`)
`SolweigResult`	Per-timestep internal result (advanced single-step workflows)
`ThermalState`	Carry-forward thermal state for multi-day chains

I/O Functions¶

Function	Description
`load_raster()`	Load a GeoTIFF with optional bbox cropping
`save_raster()`	Save array as Cloud-Optimized GeoTIFF
`rasterise_gdf()`	Rasterise vector data to a height grid
`download_epw()`	Download EPW weather from PVGIS
`read_epw()`	Parse an EPW file to weather records

GPU Utilities¶

Function	Description
`is_gpu_available()`	Check whether GPU acceleration is available
`get_compute_backend()`	Returns `"gpu"` or `"cpu"`
`enable_gpu()`	Enable GPU on all three paths (shadows, aniso, GVF)
`disable_gpu()`	Disable GPU on all three paths, fall back to CPU
`get_gpu_limits()`	Inspect GPU device limits
`gpu_dispatch_count()`	Successful GPU dispatches since process start / last reset
`gpu_fallback_count()`	GPU→CPU fallbacks since process start / last reset
`reset_gpu_metrics()`	Zero both counters (typical test pattern: reset → run → check)

Import Pattern¶

import solweig

# All public API is available at the top level
surface = solweig.SurfaceData.prepare(dsm=my_dsm, pixel_size=1.0)
summary = solweig.calculate(surface, weather=[weather], location=location, output_dir="output/")

The top-level namespace is the documented import surface — every class and function on this reference page is reachable as solweig.<name>. The sub-modules listed in the repository layout (solweig.models.surface, solweig.io_epw, solweig.grid_accumulator, …) exist for code-organisation reasons and may be reorganised between releases; depend on solweig.<name> rather than the sub-module path to stay forward-compatible.

For QGIS-plugin / batch-pipeline authors who need geospatial helpers (extract_bounds, intersect_bounds, resample_to_grid, looks_like_relative, …), the entry point is solweig.geospatial. The b85→b86 top-level re-exports were removed in b87 — accessing solweig.extract_bounds now raises AttributeError.

Type Annotations¶

SOLWEIG is fully typed. Type checking can be enabled in any IDE:

from solweig import SurfaceData, Location, Weather, TimeseriesSummary

def process_area(dsm: np.ndarray) -> TimeseriesSummary:
    surface: SurfaceData = SurfaceData.prepare(dsm=dsm, pixel_size=1.0)
    location: Location = Location(latitude=57.7, longitude=12.0, utc_offset=1)
    weather: Weather = Weather(...)
    return solweig.calculate(surface, weather=[weather], location=location, output_dir="output/")