smhi2epw

Build complete-year EnergyPlus weather files (.epw) from Swedish weather data. smhi2epw combines SMHI station observations and STRÅNG solar data, fills gaps, and can use nearby stations or same-year ERA5 when needed. Each automatic run writes a JSON receipt describing its sources and recovery steps.

Install

Python 3.11 or newer is required:

python -m pip install smhi2epw

Creating a weather file needs internet access to SMHI and may use Open-Meteo for ERA5 recovery. Reading an existing EPW works offline.

Use

smhi2epw 2023 gothenburg.epw --station 71420 --city Gothenburg

Or use the Python API:

from smhi2epw import EPWConfig, compile_epw

result = compile_epw(EPWConfig(
    year=2023,
    output_path="gothenburg.epw",
    station_id=71420,
    city="Gothenburg",
))
print(result.report.warnings)

Automatic recovery is the default. Use --weather-policy strict to stop when required source data are missing. See the quick start and CLI guide for options, and the method limitations before using reconstructed weather in calibration or event analysis.

Docs and examples

On the development feature branch, batch generation supports multiple locations and source years, with optional SSP/RCP morphing through pyfwg. Install with python -m pip install -e ".[morphing]", then use smhi2epw batch examples/future_weather_plan.json --dry-run to inspect a plan. Execution requires Java and the appropriate Future Weather Generator JAR. See the batch and morphing guide for configuration, prerequisites and scientific limits. The guide includes exact tested versions, repeatable environment setup, JAR placement, and real integration checks. External JARs and incomplete downloads are Git-ignored and excluded from source packages.

The online documentation covers the API, methods, and limitations. The notebook course covers EPW inspection, comparisons, heat waves, gap filling, solar components, batch runs, and EnergyPlus. To run the notebooks from a source checkout:

git clone https://github.com/SB-Chalmers/smhi2epw.git
cd smhi2epw
python -m pip install -e ".[tutorials]"
jupyter lab examples/

Completeness evidence

The archived EPSM runs covered jobs from 2017–2024. Their recorded results were:

All 128 v3 files were rechecked for calendar, row, field, range, and dew-point validity. They all used some reconstruction; completeness does not establish local weather accuracy. The archived results predate the pvlib solar refactor. See the run summary and notebook 08 for details and limitations.

Related SMHI packages

Thanks to the maintainers of smhi-open-data, smhi-weather, smhi-pkg, and ifk-smhi. These projects provide SMHI API clients and forecast access; smhi2epw focuses on complete-year weather files for EnergyPlus.

Development

python -m pip install -e ".[dev,docs,tutorials]"
pytest -m "not network and not energyplus and not fwg"
ruff check src tests examples docs
python -m sphinx -W --keep-going -b html docs docs/_build/html

The CI workflow also checks minimum dependencies, installed wheels, notebooks, and required EnergyPlus cases. Live provider tests run separately on the weekly schedule.

License

MIT

Operation logging

Library calls use Python's standard logging module and install no console or file output. Instrumented operations accept optional keyword-only log_context with small identifier mappings; nested events carry operation and parent IDs. INFO describes major stages; DEBUG exposes selections, conversions and caches. Logging context does not change physical models or scientific cache inputs.

For an application using EPSM's coordinated logging setup:

from epsm import configure_logging, reset_logging

configure_logging(directory="outputs/example")  # INFO stderr, DEBUG JSONL
# Run operations here.
configure_logging(enabled=False)  # Stop console and file logging.
reset_logging()  # Restore the host application's settings.

EPSM is needed only for this combined configuration, not for ordinary library logging. Existing scripts can keep using logging.basicConfig(level=logging.INFO).

Migration: compile_epw() no longer configures a handler automatically. Select output in the calling application. The standalone CLI still configures stderr; use --log-level OFF to silence status.