Welcome to pyfwg’s documentation! (Version 0.4.0)

pyfwg is a robust Python workflow manager for the Future Weather Generator command-line tools.

This documentation provides detailed information on the library’s three main interfaces, designed to cater to different levels of complexity:

  • High-Level Functions (morph_epw_global, morph_epw_europe, morph_epw_cordex): For simple, one-shot morphing tasks where you need direct control over the tool’s parameters without complex file renaming.

  • Advanced Workflow Classes (MorphingWorkflowGlobal, MorphingWorkflowEurope, MorphingWorkflowCordex): For complex projects requiring custom file renaming based on filename parsing, and full, step-by-step control over the validation and execution process.

  • Parametric Iterator (MorphingIterator): The most powerful feature, designed for automating large batches of morphing workflows defined in a Pandas DataFrame or an Excel file, making parametric analysis simple and structured.

What’s New in Version 0.4.0?

Version 0.4.0 adds support for the FWG Engine, the shared engine of the latest Future Weather Generator distributions: Global v5.x, Europe v3.x and the new CORDEX regional distributions. Earlier versions keep working exactly as before.

  • Global v5.x and Europe v3.x: Use them with the same classes and functions as before. pyfwg detects the version from the JAR and builds the new command line for you.

  • CORDEX Regional Distributions: The new MorphingWorkflowCordex class and morph_epw_cordex function support the Middle East and North Africa, Africa, North America, Central America, South America, West & South Asia, Southeast Asia and Australasia distributions (see CORDEX_REGIONS).

  • New FWG Engine Options: Select scenarios and future periods (fwg_scenarios, fwg_timeframes), solar decomposition, illuminance and infrared models, uncertainty cases (fwg_uncertainty_variant), output profile and a shared climate-data cache (fwg_model_unzipped_folder). Any other option of the tool can be passed with fwg_extra_args.

  • JAR Inspection: get_fwg_distribution_info reads the scenarios, periods and climate models packaged in FWG Engine JARs, which pyfwg also uses to validate your configuration.

  • Urban Heat Island: The FWG Engine no longer supports the UHI effect. By default, pyfwg applies it only with the versions that support it (Global v3/v4 and Europe v1/v2).

Requirements

Before using pyfwg, you need to have the following installed and configured:

  • Python 3.9+

  • Java: The java command must be accessible from your system’s terminal (i.e., it must be in your system’s PATH).

  • Future Weather Generator: You must download the appropriate .jar file from the official website.

    • The Global Tool (FutureWeatherGenerator_vX.X.X.jar) has been tested with versions v3.0.0, v3.0.1, and v4.0.2.

    • The Europe Tool (FutureWeatherGenerator_Europe_vX.X.X.jar) has been tested with versions v1.0.1 and v2.0.2.

    • The FWG Engine distributions have been tested with Global v5.2.0 (FutureWeatherGenerator-CMIP6-Global-v5.2.0.jar, FWG Engine v1.1.0). Europe v3.x (FutureWeatherGenerator-CORDEX-CMIP5-Europe-EUR-11-v3.X.X.jar) and the CORDEX regional distributions (FutureWeatherGenerator-CORDEX-CMIP5-<Region>-<Domain>-v1.X.X.jar) share the same engine and command-line interface.

Acknowledgements

This library would not be possible without the foundational work of Eugénio Rodrigues (University of Coimbra), the creator of the Future Weather Generator tool. pyfwg is essentially a Python wrapper designed to automate and streamline the use of his powerful command-line application.

Getting Started

Contents:

Indices and tables