velantis-wind/velantiswind

1. Host environment and main boundary

VelantisWind is a QGIS Python plugin, not a standalone app. The architectural boundary is the QGIS host: plugin code reads project layers, launches Qt dialogs/panels, runs domain calculations in-process, and writes results back into QGIS layers, rasters, or plugin dialogs.

2. Top-level plugin entry and feature navigation

plugin.py is the integration point that exposes the plugin to QGIS. From there, the user is routed into three major workflows: Energy, Noise, and Shadow. The UI entry files (energy_page.py, noise_page.py, shadow_page.py) and dialogs (*_dialog.py, results dialogs, support/help dialogs) act as presentation shells around the computational cores.

3. Shared UI and compatibility layer

The plugin includes a small shared UI layer: ui_core/responsive.py for layout behavior and qt_compat.py for Qt/QGIS version compatibility. This matters because the repository targets both QGIS 3.x / Qt5 and QGIS 4 / Qt6. UI code is therefore separated from computation so the computational modules can survive Qt migration with minimal change.

4. Energy / AEP subsystem

The energy workflow is split into a higher-level orchestration layer (energy_core) and a deeper analysis engine (ag_core). energy_core handles dialog state, validation, user feedback, and runner control. ag_core contains the actual AEP pipeline: turbine models, wind resource loading, simulation orchestration, physics factories, results building, and QGIS export adapters. The readme notes that the wake-aware energy path depends on PyWake in the QGIS Python environment.

5. Energy data flow

The energy flow is: user inputs and QGIS layers → validation and model setup → resource loading (wrg_reader.py, wrg_site.py, ag_core/orchestration/resource_loader.py) → simulation (ag_core/simulation/runner.py, ag_core/aep_compute.py) → result assembly (ag_core/orchestration/result_builder.py, ag_core/results/*) → export to QGIS or file outputs (ag_core/qgis_io/*, ag_core/export_results.py). This subsystem is the most clearly layered one in the repo.

6. Energy physics and model boundaries

Within ag_core/physics, the calculation engine is split into wake, turbulence, blockage, and rotor_average factories, plus a common/compat.py utility. These factory-style subpackages indicate interchangeable physics implementations behind a common orchestration interface, which is important for diagramming the numerical core as modular rather than monolithic.

7. Noise subsystem

noise_core is a self-contained workflow for early-stage acoustic assessment. It has its own dialog controller/state, validation, runner, task orchestration, result evaluation, and QGIS output adapters. Internally it separates sources, receivers, propagation, acoustics/spectra, and raster/task processing, with both a noise_engine_fast.py and noise_engine_iso.py suggesting alternate calculation paths or standards-based modes.

8. Noise data flow

The noise pipeline is: source and receiver collection from QGIS layers → snapshot/task preparation → propagation and spectral calculations → result payload/summary generation → QGIS layer updates via noise_core/qgis_io/*. The bundled spectrum_library/*.csv files are a key architectural input source, meaning the noise engine relies on packaged turbine spectrum data rather than only external inputs.

9. Shadow flicker subsystem

shadow_core is another independent domain workflow. It collects turbines and receptors, models terrain and solar position, handles timezone logic, and runs calculations via calculation/executor.py and point_runner.py. Like noise, it has a dedicated runner, dialog controller/state, validation, results summary, raster tasking, and QGIS I/O layer.

10. Shadow-specific infrastructure

The shadow module includes solar_geometry.py, terrain/dem.py, and timezone_utils.py, showing that shadow flicker depends on both geographic elevation and time-zone-aware solar timing. The bundled assets/tzdata package is architecturally important here: it gives the plugin a self-contained timezone database so time calculations can be done reliably inside QGIS environments.

11. QGIS integration and output surfaces

Each major module has a QGIS adapter package (ag_core/qgis_io, noise_core/qgis_io, shadow_core/qgis_io) to translate calculation outputs into map layers, raster products, or project objects. This is the main boundary where numerical results become GIS-visible artifacts. Result dialogs (results_dialog.py, noise_results_dialog.py) complement the map outputs for review and validation.

12. Shared data model and validation pattern

Across modules, the repository consistently uses a pattern of domain.py, dialog_state.py, validation.py, runner.py, and ui_feedback.py. That implies a repeated architecture: define a domain model, validate user/project inputs, run the computation, and report status back to the UI. This makes the modules independently testable and easier to diagram as parallel pipelines.

13. External and packaged dependencies

The key runtime dependency that materially affects architecture is QGIS itself, with the plugin running in its embedded Python environment. For energy calculations, PyWake is an external dependency that must be installed into the same environment. The repo also bundles supporting assets like timezone data and wind/noise spectrum files, reducing reliance on system-installed data.

14. Overall architectural shape

The repository is a plugin shell around three domain engines, with shared UI/runtime compatibility at the top and QGIS adapters at the edges. The dominant flow is: QGIS layers and project state in → module-specific validation and computation in the core → QGIS layers, rasters, and result dialogs out. The clearest diagram should show three parallel vertical stacks—Energy, Noise, Shadow—sharing the same host/plugin boundary but using separate numerical and data-handling internals.