From 0c7a36383c869cd2da98331a6c633c87076c6cc3 Mon Sep 17 00:00:00 2001 From: lkstrp Date: Fri, 21 Feb 2025 11:41:39 +0100 Subject: [PATCH] wip: single schema structure --- Snakefile | 7 +- config/config.default.yaml | 7 +- config/config.schema.yaml | 954 ++++++++++++++++++++++++++++++ config/schemas/general.yaml | 76 --- doc/configtables/atlite.csv | 14 - doc/configtables/co2_budget.csv | 2 - doc/configtables/conventional.csv | 5 - doc/configtables/countries.csv | 2 - doc/configtables/electricity.csv | 45 -- doc/configtables/enable.csv | 8 - doc/configtables/foresight.csv | 2 - doc/configtables/hydro.csv | 11 - doc/configtables/lines.csv | 14 - doc/configtables/links.csv | 6 - doc/configtables/offwind.csv | 18 - doc/configtables/onwind.csv | 19 - doc/configtables/run.csv | 12 - doc/configtables/scenario.csv | 5 - doc/configtables/snapshots.csv | 4 - doc/configtables/solar.csv | 15 - doc/configuration.rst | 197 +++--- scripts/__init__.py | 2 - 22 files changed, 1081 insertions(+), 344 deletions(-) create mode 100644 config/config.schema.yaml delete mode 100644 config/schemas/general.yaml delete mode 100644 doc/configtables/atlite.csv delete mode 100644 doc/configtables/co2_budget.csv delete mode 100644 doc/configtables/conventional.csv delete mode 100644 doc/configtables/countries.csv delete mode 100644 doc/configtables/electricity.csv delete mode 100644 doc/configtables/enable.csv delete mode 100644 doc/configtables/foresight.csv delete mode 100644 doc/configtables/hydro.csv delete mode 100644 doc/configtables/lines.csv delete mode 100644 doc/configtables/links.csv delete mode 100644 doc/configtables/offwind.csv delete mode 100644 doc/configtables/onwind.csv delete mode 100644 doc/configtables/run.csv delete mode 100644 doc/configtables/scenario.csv delete mode 100644 doc/configtables/snapshots.csv delete mode 100644 doc/configtables/solar.csv diff --git a/Snakefile b/Snakefile index ba081f42e..fb8daec13 100644 --- a/Snakefile +++ b/Snakefile @@ -6,7 +6,7 @@ from pathlib import Path import yaml from os.path import normpath, exists, join from shutil import copyfile, move, rmtree -from snakemake.utils import min_version, validate +from snakemake.utils import min_version from scripts._helpers import ( path_provider, copy_default_files, @@ -15,8 +15,9 @@ from scripts._helpers import ( get_shadow, ) -min_version("8.11") +from scripts.lib.validation import validate_config +min_version("8.11") copy_default_files(workflow) @@ -24,7 +25,7 @@ configfile: "config/config.default.yaml" configfile: "config/config.yaml" -validate(config, "config/schemas/general.yaml") +validate_config(config, "config/config.schema.yaml") run = config["run"] diff --git a/config/config.default.yaml b/config/config.default.yaml index de1613bbd..f0422b333 100644 --- a/config/config.default.yaml +++ b/config/config.default.yaml @@ -17,7 +17,6 @@ private: remote: ssh: "" path: "" - test_deprecation: "" # docs in https://pypsa-eur.readthedocs.io/en/latest/configuration.html#run run: @@ -172,6 +171,7 @@ renewable: natura: true excluder_resolution: 100 clip_p_max_pu: 1.e-2 + offwind-ac: cutout: europe-2013-sarah3-era5 resource: @@ -190,6 +190,7 @@ renewable: excluder_resolution: 200 clip_p_max_pu: 1.e-2 landfall_length: 10 + offwind-dc: cutout: europe-2013-sarah3-era5 resource: @@ -208,6 +209,7 @@ renewable: excluder_resolution: 200 clip_p_max_pu: 1.e-2 landfall_length: 10 + offwind-float: cutout: europe-2013-sarah3-era5 resource: @@ -229,6 +231,7 @@ renewable: max_depth: 1000 clip_p_max_pu: 1.e-2 landfall_length: 10 + solar: cutout: europe-2013-sarah3-era5 resource: @@ -244,6 +247,7 @@ renewable: natura: true excluder_resolution: 100 clip_p_max_pu: 1.e-2 + solar-hsat: cutout: europe-2013-sarah3-era5 resource: @@ -259,6 +263,7 @@ renewable: natura: true excluder_resolution: 100 clip_p_max_pu: 1.e-2 + hydro: cutout: europe-2013-sarah3-era5 carriers: [ror, PHS, hydro] diff --git a/config/config.schema.yaml b/config/config.schema.yaml new file mode 100644 index 000000000..410cb6024 --- /dev/null +++ b/config/config.schema.yaml @@ -0,0 +1,954 @@ +# SPDX-FileCopyrightText: Contributors to PyPSA-Eur +# +# SPDX-License-Identifier: CC0-1.0 + +$schema: "https://json-schema.org/draft/2020-12/schema" +type: object +properties: + + # ------------------------------------------------------------------------------------ + # docs in https://pypsa-eur.readthedocs.io/en/latest/configuration.html#top-level-configuration + version: + title: Version + description: Version of PyPSA-Eur. Descriptive only. + type: string + examples: ['v2025.1.0'] + tutorial: + title: Tutorial + description: Switch to retrieve the tutorial data set instead of the full data set. + type: boolean + + logging: + title: "Logging" + description: "Logging configuration." + additionalProperties: false + properties: + level: + type: string + enum: ["DEBUG", "INFO", "WARNING", "ERROR", "CRITICAL"] + description: Restrict console outputs to all infos, warning or errors only. + format: + type: string + description: Custom format for log messages. See LogRecord attributes. + examples: ["%(levelname)s:%(name)s:%(message)s"] + + private: + title: Private + description: > + Personal API keys. + additionalProperties: false + properties: + keys: + type: object + additionalProperties: false + properties: + entsoe_api: + type: ["string", "null"] + description: > + Optionally specify the ENTSO-E API key. See the guidelines to get ENTSO-E API key. + + remote: + title: Remote + description: > + Configuration for remote access. + additionalProperties: false + properties: + ssh: + type: string + description: Optionally specify the SSH of a remote cluster to be synchronized. + path: + type: string + description: > + Optionally specify the file path within the remote cluster to be synchronized. + test_deprecation: + type: string + description: Deprecated property. Use 'xx' instead. + deprecated: true + + # ---------------------------------------------------------------------------------- + # docs in https://pypsa-eur.readthedocs.io/en/latest/configuration.html#run + run: + title: "Run" + description: > + Run scenarios with different configurations which are not covered by Wildcards + additionalProperties: false + properties: + prefix: + type: string + description: > + Prefix for the run name which is used as a top-layer directory name in the + results and resources folders. + name: + type: [string, array] + description: "Specify a name for your run. Results will be stored under this name. If ``scenario: enable:`` is set to ``true``, the name must contain a subset of scenario names defined in ``scenario: file:``. If the name is 'all', all defined scenarios will be run." + scenarios: + type: object + additionalProperties: false + properties: + enable: + type: boolean + description: "Switch to select whether workflow should generate scenarios based on ``file``." + file: + type: string + description: "Path to the scenario yaml file. The scenario file contains config overrides for each scenario. In order to be taken account, ``run: scenarios`` has to be set to ``true`` and ``run: name`` has to be a subset of top level keys given in the scenario file. In order to automatically create a `scenario.yaml` file based on a combination of settings, alter and use the ``config/create_scenarios.py`` script in the ``config`` directory." + disable_progressbar: + type: boolean + description: "Switch to select whether progressbar should be disabled." + shared_resources: + additionalProperties: false + properties: + policy: + type: boolean + description: "Boolean switch to select whether resources should be shared across runs. If a string is passed, this is used as a subdirectory name for shared resources. If set to 'base', only resources before creating the elec.nc file are shared." + exclude: + type: array + items: + type: string + description: "For the case shared_resources=base, specify additional files that should not be shared across runs." + shared_cutouts: + description: "Switch to select whether cutouts should be shared across runs." + use_shadow_directory: + type: boolean + description: "Set to ``true`` (default) if snakemake shadow directories (``shallow``) should be used. Set to ``false`` if problems occcur." + + # ---------------------------------------------------------------------------------- + # docs in https://pypsa-eur.readthedocs.io/en/latest/configuration.html#foresight + foresight: + title: Foresight + description: "See :ref:`Foresight Options` for detail explanations." + type: string + enum: ["overnight", "myopic", "perfect"] + + # ---------------------------------------------------------------------------------- + # docs in https://pypsa-eur.readthedocs.io/en/latest/configuration.html#scenario + # Wildcard docs in https://pypsa-eur.readthedocs.io/en/latest/wildcards.html + scenario: + title: Scenario + description: Scenario configuration. + additionalProperties: false + properties: + clusters: + description: List of ``{clusters}`` wildcards to run. See :ref:`clusters`. + type: array + items: + type: number + + opts: + description: List of ``{opts}`` wildcards to run. See :ref:`opts`. + type: array + items: + type: string + + sector_opts: + description: > + List of ``{sector_opts}`` wildcards to run. See :ref:`sector_opts`. + type: array + items: + type: string + + planning_horizons: + description: > + List of ``{planning_horizon}`` wildcards to run. See :ref:`planning_horizons`. + type: array + items: + type: number + + # ---------------------------------------------------------------------------------- + # docs in https://pypsa-eur.readthedocs.io/en/latest/configuration.html#countries + countries: + title: Countries + description: > + European countries defined by their `Two-letter country codes (ISO 3166-1) `_ which should be included in the energy system model." + type: array + items: + type: string + enum: ['AL', 'AT', 'BA', 'BE', 'BG', 'CH', 'CZ', 'DE', 'DK', 'EE', 'ES', 'FI', 'FR', 'GB', 'GR', 'HR', 'HU', 'IE', 'IT', 'LT', 'LU', 'LV', 'ME', 'MK', 'NL', 'NO', 'PL', 'PT', 'RO', 'RS', 'SE', 'SI', 'SK', 'XK'] + uniqueItems: true + + # ---------------------------------------------------------------------------------- + # docs in https://pypsa-eur.readthedocs.io/en/latest/configuration.html#snapshots + snapshots: + title: "Snapshots" + description: > + Snapshots configuration. + additionalProperties: false + properties: + start: + title: Start Date + description: Left bound of date range (YYYY-MM-DD). + examples: 2025-01-01 + type: string + format: date-time + end: + title: End Date + description: Right bound of date range (YYYY-MM-DD). + examples: 2025-12-31 + type: string + format: date-time + inclusive: + description: > + Make the time interval closed to the left, right, or both sides both or neither side. + type: string + enum: + - neither + - both + - left + - right + + # ---------------------------------------------------------------------------------- + # docs in https://pypsa-eur.readthedocs.io/en/latest/configuration.html#enable + enable: + additionalProperties: false + properties: + retrieve: + description: > + Switch to include (true) or exclude (false) the retrieve_* rules of snakemake into the workflow; 'auto' sets true|false based on availability of an internet connection to prevent issues with snakemake failing due to lack of internet connection. + type: string + enum: + - auto + - true + - false + retrieve_databundle: + description: > + Switch to retrieve databundle from zenodo via the rule :mod:`retrieve_databundle` or whether to keep a custom databundle located in + the corresponding folder. + type: boolean + retrieve_cost_data: + description: Switch to retrieve technology cost data from `technology-data repository `_. + type: boolean + build_cutout: + description: > + Switch to enable the building of cutouts via the rule :mod:`build_cutout`. + type: boolean + retrieve_cutout: + description: > + Switch to enable the retrieval of cutouts from zenodo with :mod:`retrieve_cutout`. + type: boolean + custom_busmap: + description: > + Switch to enable the use of custom busmaps in rule :mod:`cluster_network`. If activated the rule looks for provided busmaps at ``data/busmaps/base_s_{clusters}_{base_network}.csv`` which should have the same format as ``resources/busmap_base_s_{clusters}.csv``, i.e. the index should contain the buses of ``networks/base_s.nc``. {base_network} is the name of the selected base_network in electricity, e.g. ``gridkit``, ``osm-prebuilt``, or ``osm-raw``. + type: boolean + drop_leap_day: + description: > + Switch to drop February 29 from all time-dependent data in leap years + type: boolean + + # ---------------------------------------------------------------------------------- + # docs in https://pypsa-eur.readthedocs.io/en/latest/configuration.html#co2-budget + co2_budget: + title: CO2 Budget + description: > + CO2 budget as a fraction of 1990 emissions. Overwritten if ``Co2Lx`` or ``cb`` are set in ``{sector_opts}`` wildcard"doc/configtables/othertoplevel.csv + type: object + additionalProperties: {"type": number} + + # ---------------------------------------------------------------------------------- + # docs in https://pypsa-eur.readthedocs.io/en/latest/configuration.html#electricity + electricity: + additionalProperties: false + properties: + + voltages: + description: Voltage levels to consider + type: array + items: + type: number + enum: [220.0, 300.0, 330.0, 380.0, 400.0, 500.0, 750.0] + + base_network: + description: "Specify the underlying base network, i.e. GridKit (based on ENTSO-E web map extract, OpenStreetMap (OSM) prebuilt or raw (built from raw OSM data), takes longer." + type: string + enum: ["entsoegridkit", "osm-prebuilt", "osm-raw"] + + osm-prebuilt-version: + description: "Choose the version of the prebuilt OSM network." + type: number + examples: 0.6 + + gaslimit_enable: + description: > + Add an overall absolute gas limit configured in ``electricity: gaslimit``. + type: boolean + + gaslimit: + description: Global gas usage limit + type: boolean + + co2limit_enable: + description: > + Add an overall absolute carbon-dioxide emissions limit configured in ``electricity: co2limit`` in :mod:`prepare_network`. **Warning:** This option should currently only be used with electricity-only networks, not for sector-coupled networks." + type: boolean + + co2limit: + description: > + Cap on total annual system carbon dioxide emissions (in :math:`t_{CO_2-eq}/a`). + type: number + + co2base: + description: > + Reference value of total annual system carbon dioxide emissions if relative emission reduction target is specified in ``{opts}`` wildcard (in :math:`t_{CO_2-eq}/a`). + type: number + + operational_reserve: + description: > + Settings for reserve requirements following `GenX `_ + type: object + additionalProperties: false + properties: + activate: + description: > + Whether to take operational reserve requirements into account during optimisation + type: boolean + epsilon_load: + description: > + share of total load + type: number + epsilon_vres: + description: > + share of total renewable supply + type: number + contingency: + description: > + fixed reserve capacity + type: integer + max_hours: + type: object + additionalProperties: false + properties: + battery: + description: > + Maximum state of charge capacity of the battery in terms of hours at full + output capacity ``p_nom``. + Cf. `PyPSA documentation `_. + type: integer + H2: + description: > + Maximum state of charge capacity of the hydrogen storage in terms of hours + at full output capacity ``p_nom``. Cf. `PyPSA documentation `_. + type: integer + extendable_carriers: + type: object + additionalProperties: false + properties: + Generator: + description: > + Defines existing or non-existing conventional and renewable power plants + to be extendable during the optimization. Conventional generators can + only be built/expanded where already existent today. If a listed + conventional carrier is not included in the ``conventional_carriers`` + list, the lower limit of the capacity expansion is set to 0. + type: array + items: + description: Any extendable carrier + type: string + StorageUnit: + description: > + Adds extendable storage units (battery and/or hydrogen) at every node/bus + after clustering without capacity limits and with zero initial capacity. + type: array + items: + type: string + enum: [battery, H2] + minItems: 0 + Store: + description: > + Adds extendable storage units (battery and/or hydrogen) at every node/bus + after clustering without capacity limits and with zero initial capacity. + type: array + items: + type: string + enum: [battery, H2] + minItems: 0 + Link: + description: Adds extendable links (H2 pipelines only) at every connection where there are lines or HVDC links without capacity limits and with zero initial capacity. Hydrogen pipelines require hydrogen storage to be modelled as ``Store``. + type: array + items: + type: string + powerplants_filter: + description: > + Filter query for the default powerplant database. Use `pandas.query `_ strings here, e.g. ``Country not in ['Germany']``" + type: string + custom_powerplants: + description: > + Filter query for the custom powerplant database. Use `pandas.query `_ strings here, e.g. ``Country not in ['Germany']``" + type: boolean + everywhere_powerplants: + description: List of conventional power plants to add to every node in the model with zero initial capacity. To be used in combination with ``extendable_carriers`` to allow for building conventional powerplants irrespective of existing locations. + type: array + items: + type: string + enum: [nuclear, oil, OCGT, CCGT, coal, lignite, geothermal, biomass] + minItems: 0 + conventional_carriers: + description: List of conventional power plants to include in the model from ``resources/powerplants_s_{clusters}.csv``. If an included carrier is also listed in ``extendable_carriers``, the capacity is taken as a lower bound. + type: array + items: + type: string + enum: [nuclear, oil, OCGT, CCGT, coal, lignite, geothermal, biomass] + renewable_carriers: + description: List of renewable generators to include in the model. + type: array + items: + type: string + enum: [solar, solar-hsat, onwind, offwind-ac, offwind-dc, offwind-float, hydro] + estimate_renewable_capacities: + type: object + additionalProperties: false + properties: + enable: + description: > + Activate routine to estimate renewable capacities in rule :mod:`add_electricity`. This option should not be used in combination + with pathway planning ``foresight: myopic`` or ``foresight: perfect`` as + renewable capacities are added differently in + :mod:`add_existing_baseyear`. + type: boolean + from_opsd: + descriptions: > + Add renewable capacities from `OPSD database `_. + The value is depreciated but still can be used. + type: boolean + year: + description: > + Renewable capacities are based on existing capacities reported by IRENA + (IRENASTAT) for the specified year + type: integer + expansion_limit: + description: > + Artificially limit maximum IRENA capacities to a factor. For example, an ``expansion_limit: 1.1`` means 110% of capacities . If false are + chosen, the estimated renewable potentials determine by the workflow are + used. + type: [boolean, number] + technology_mapping: + description: > + Mapping between PyPSA-Eur and powerplantmatching technology names. + type: object + additionalProperties: false + properties: + Offshore: + description: > + List of PyPSA-Eur carriers that is considered as (IRENA, OPSD) onshore technology. + type: array + items: + type: string + enum: [offwind-ac, offwind-dc, offwind-float] + Onshore: + description: > + List of PyPSA-Eur carriers that is considered as (IRENA, OPSD) offshore technology." + type: array + items: + type: string + enum: [onwind] + PV: + description: > + List of PyPSA-Eur carriers that is considered as (IRENA, OPSD) PV technology. + type: array + items: + type: string + enum: [solar] + autarky: + type: object + additionalProperties: false + properties: + enable: + description: > + Require each node to be autarkic by removing all lines and links. + type: boolean + by_country: + description: > + Require each country to be autarkic by removing all cross-border lines + and links. ``electricity: autarky`` must be enabled. + type: boolean + transmission_limit: + description: > + Limit on transmission expansion. The first part can be ``v`` (for setting a limit on line volume) or ``c`` (for setting a limit on line cost). The second + part can be ``opt`` or a float bigger than one (e.g. 1.25). If ``opt`` is + chosen line expansion is optimised according to its capital cost (where the + choice ``v`` only considers overhead costs for HVDC transmission lines, + while ``c`` uses more accurate costs distinguishing between overhead and + underwater sections and including inverter pairs). The setting ``v1.25`` will + limit the total volume of line expansion to 25% of currently installed + capacities weighted by individual line lengths. The setting ``c1.25`` will + allow to build a transmission network that costs no more than 25 % more than + the current system." + type: string + examples: ['vopt', 'v1.25', 'copt', 'c1.25'] + + # ---------------------------------------------------------------------------------- + # docs in https://pypsa-eur.readthedocs.io/en/latest/configuration.html#atlite + atlite: + additionalProperties: false + properties: + + cutout_directory: + description: Directory to store cutouts. + type: string + + default_cutout: + description: Defines a default cutout. + type: string + + nprocesses: + description: Number of parallel processes in cutout preparation. + type: integer + + show_progress: + description: > + Whether progressbar for atlite conversion processes should be shown. False saves time. + type: boolean + + cutouts: + type: object + patternProperties: + "^.*$": + type: object + properties: + module: + type: array + items: + type: string + enum: ['era5', 'sarah'] + x: + description: > + Range of longitudes to download weather data for. If not defined, it defaults to the spatial bounds of all bus shapes. Float interval within [-180, 180]. + type: array + items: + type: number + minItems: 2 + maxItems: 2 + y: + description: > + Range of latitudes to download weather data for. If not defined, it defaults to the spatial bounds of all bus shapes. + Float interval within [-180, 180]. + type: array + items: + type: number + minItems: 2 + maxItems: 2 + dx: + description: > + Grid resolution for longitudes. Larger then 0.25. + type: number + minimum: 0 + examples: 0.25 + dy: + description: > + Grid resolution for latitudes. Larger then 0.25. + type: number + minimum: 0 + examples: 0.25 + time: + description: > + Time span to download weather data for. If not defined, it defaults to the time interval spanned by the snapshots. Please choose interval within 1979 and 2018 as valid pandas date time strings. + type: array + items: + type: string + minItems: 2 + maxItems: 2 + + # ---------------------------------------------------------------------------------- + # docs in https://pypsa-eur.readthedocs.io/en/latest/configuration.html#renewable + renewable: + + # ------------------------------------ + onwind: + additionalProperties: false + properties: + + cutout: + description: Specifies the directory where the relevant weather data ist stored. Should be listed in the configuration ``atlite.cutouts``. You can also reference an existing folder in the directory ``cutouts``. Source module must be ERA5. + type: string + examples: europe-2013-sarah3-era5 + + resource: + type: object + additionalProperties: false + properties: + method: + description: A superordinate technology type. + type: string + enum: [wind] + turbine: + description: Specifies the turbine type and its characteristic power curve. Must be one of turbine types included in `atlite `_. Can be a string or a dictionary with years as keys which denote the year another turbine model becomes available. + type: string + smooth: + description: Switch to apply a gaussian kernel density smoothing to the power curve. + type: boolean + add_cutout_windspeed: + type: boolean + + capacity_per_sqkm: + description: Allowable density of wind turbine placement (in :math:`MW/km^2`). + type: number + + correction_factor: + description: Correction factor for the wind speed. A value of 1.0 means no correction. + type: number + + corine: + type: object + additionalProperties: false + properties: + grid_codes: + description: Specifies areas according to CORINE Land Cover codes which are generally eligible for wind turbine placement. Must be any subset of the `CORINE Land Cover code list `_. + type: array + items: + type: integer + distance: + description: Distance to keep from areas specified in ``distance_grid_codes`` (in m). + type: integer + distance_grid_codes: + description: Specifies areas according to CORINE Land Cover codes to which wind turbines must maintain a distance specified in the setting ``distance``. Must be any subset of the `CORINE Land Cover code list `_. + type: array + items: + type: integer + luisa: + type: boolean + natura: + description: Switch to exclude `Natura 2000 `_ natural protection areas. Area is excluded if ``true``." + type: boolean + excluder_resolution: + description: Resolution on which to perform geographical elibility analysis (in m). + type: integer + clip_p_max_pu: + description: To avoid too small values in the renewables` per-unit availability time series values below this threshold are set to zero (in p.u.). + type: numberi + + # ------------------------------------ + offwind-ac: + $ref: "#/definitions/offwind-x" + + # ------------------------------------ + offwind-dc: + $ref: "#/definitions/offwind-x" + + # ------------------------------------ + offwind-float: + $ref: "#/definitions/offwind-x" + + # ------------------------------------ + solar: + $ref: "#/definitions/solar-x" + + # ------------------------------------ + solar-hsat: + $ref: "#/definitions/solar-x" + + # ------------------------------------ + hydro: + additionalProperties: false + properties: + + cutout: + description: Specifies the directory where the relevant weather data ist stored. Should be listed in the configuration ``atlite.cutouts``. You can also reference an existing folder in the directory ``cutouts``. Source module must be ERA5. + type: string + examples: europe-2013-sarah3-era5 + + carriers: + description: Specifies the types of hydro power plants to build per-unit availability time series for. 'ror' stands for run-of-river plants, 'PHS' represents pumped-hydro storage, and 'hydro' stands for hydroelectric dams. + type: array + items: + type: string + enum: [ror, PHS, hydro] + + PHS_max_hours: + description: Maximum state of charge capacity of the pumped-hydro storage (PHS) in terms of hours at full output capacity ``p_nom`` in h. Cf. `PyPSA documentation `_. + type: number + + hydro_max_hours: + description: Maximum state of charge capacity of the pumped-hydro storage (PHS) in terms of hours at full output capacity ``p_nom`` or heuristically determined. Cf. `PyPSA documentation `_. + oneOf: + - type: string + enum: + - energy_capacity_totals_by_country + - estimate_by_large_installations + - type: number + + flatten_dispatch: + description: Consider an upper limit for the hydro dispatch. The limit is given by the average capacity factor plus the buffer given in ``flatten_dispatch_buffer`` + type: boolean + + flatten_dispatch_buffer: + description: If ``flatten_dispatch`` is true, specify the value added above the average capacity factor. + type: number + + clip_min_inflow: + description: To avoid too small values in the inflow time series, values below this threshold are set to zero. + type: number + + eia_norm_year: + description: Year for which the EIA data is normalized. If set to ``None``, no normalization is applied. + type: boolean, integer + + eia_correct_by_capacity: + description: Correct EIA annual hydro generation data by installed capacity. + type: boolean + + eia_approximate_missing: + description: Approximate hydro generation data for years not included in EIA dataset through a regression based on annual runoff. + type: boolean + + # ---------------------------------------------------------------------------------- + # docs in https://pypsa-eur.readthedocs.io/en/latest/configuration.html#conventional + conventional: + additionalProperties: true + properties: + + unit_commitment: + description: Allow the overwrite of ramp_limit_up, ramp_limit_start_up, ramp_limit_shut_down, p_min_pu, min_up_time, min_down_time, and start_up_cost of conventional generators. Refer to the CSV file „unit_commitment.csv“. + type: boolean + + dynamic_fuel_price: + description: Consider the monthly fluctuating fuel prices for each conventional generator. Refer to the CSV file ""data/validation/monthly_fuel_price.csv" + type: boolean + + patternProperties: + description: For any carrier/technology overwrite attributes as listed below. + "^.*$": + type: object + additionalProperties: false + patternProperties: + "^.*$": + description: For any attribute, can specify a float or reference to a file path to a CSV file giving floats for each country (2-letter code). + type: + - string + - number + + # ---------------------------------------------------------------------------------- + # docs in https://pypsa-eur.readthedocs.io/en/latest/configuration.html#lines + lines: + additionalProperties: false + properties: + + types: + description: Specifies line types to assume for the different voltage levels of the ENTSO-E grid extraction. Should normally handle voltage levels 220, 300, and 380 kV. Values should specify a `line type in PyPSA `_. Keys should specify the corresponding voltage level (e.g. 220., 300. and 380. kV) + + type: object + additionalProperties: false + properties: + 220.: + type: string + 300.: + type: string + 330.: + type: string + 380.: + type: string + 400.: + type: string + 500.: + type: string + 750.: + type: string + + s_max_pu: + description: Correction factor for line capacities (``s_nom``) to approximate :math:`N-1` security and reserve capacity for reactive power flows" + type: number + + s_nom_max: + description: Global upper limit for the maximum capacity of each extendable line (in MW). + type: number + + max_extension: + description: Upper limit for the extended capacity of each extendable line (in MW). + type: integer + + length_factor: + description: Correction factor to account for the fact that buses are *not* connected by lines through air-line distance. + type: number + + reconnect_crimea: + description: Whether to reconnect Crimea to the Ukrainian grid. + type: boolean + + under_construction: + description: > + Specifies how to handle lines which are currently under construction. + One of {'zero': set capacity to zero, 'remove': remove completely, 'keep': keep with full capacity} + type: string + enum: ["keep", "zero", "remove"] + + dynamic_line_rating: + type: object + additionalProperties: false + properties: + activate: + description: Whether to take dynamic line rating into account. + type: boolean + cutout: + description: Specifies the directory where the relevant weather data ist stored. Should be listed in the configuration ``atlite.cutouts``. You can also reference an existing folder in the directory ``cutouts``. Source module must be ERA5. + type: string + examples: europe-2013-sarah3-era5 + correction_factor: + description: Factor to compensate for overestimation of wind speeds in hourly averaged wind data. + type: number + max_voltage_difference: + description: Maximum voltage angle difference in degrees or 'false' to disable. + type: boolean + max_line_rating: + description: Maximum line rating relative to nominal capacity without DLR, e.g. 1.3 or 'false' to disable. + type: boolean + + # ---------------------------------------------------------------------------------- + links: + additionalProperties: false + properties: + p_max_pu: + description: Correction factor for link capacities ``p_nom``. + type: number + minimum: 0.0 + maximum: 1.0 + + p_nom_max: + description: Global upper limit for the maximum capacity of each extendable DC link (in MW). + type: number + + max_extension: + description: Upper limit for the extended capacity of each extendable DC link (in MW). + type: number + + length_factor: + description: Correction factor to account for the fact that buses are *not* connected by links through air-line distance. + type: number + + under_construction: + description: > + Specifies how to handle lines which are currently under construction. + One of {'zero': set capacity to zero, 'remove': remove completely, 'keep': + keep with full capacity} + type: string + enum: ['zero', 'remove', 'keep'] + +definitions: + offwind-x: + additionalProperties: false + properties: + + cutout: + description: Specifies the directory where the relevant weather data ist stored. Should be listed in the configuration ``atlite.cutouts``. You can also reference an existing folder in the directory ``cutouts``. Source module must be ERA5. + type: string + examples: europe-2013-sarah3-era5 + + resource: + type: object + additionalProperties: false + properties: + method: + description: A superordinate technology type. + type: string + enum: [wind] + turbine: + description: Specifies the turbine type and its characteristic power curve. Must be one of turbine types included in `atlite `_. Can be a string or a dictionary with years as keys which denote the year another turbine model becomes available. + type: string + smooth: + description: Switch to apply a gaussian kernel density smoothing to the power curve. + type: boolean + add_cutout_windspeed: + type: boolean + + capacity_per_sqkm: + description: Allowable density of wind turbine placement (in :math:`MW/km^2`). + type: number + + correction_factor: + description: Correction factor for the wind speed. A value of 1.0 means no correction. + type: number + + corine: + description: Specifies areas according to CORINE Land Cover codes which are generally eligible for wind turbine placement. Must be any subset of the `CORINE Land Cover code list `_. + type: array + items: + type: integer + minItems: 2 + maxItems: 2 + + luisa: + type: boolean + + natura: + description: Switch to exclude `Natura 2000 `_ natural protection areas. Area is excluded if ``true``." + type: boolean + + ship_threshold: + description: Ship density threshold from which areas are excluded. + type: number + minimum: 0 + + max_depth: + description: Maximum sea water depth at which wind turbines can be build. Maritime areas with deeper waters are excluded in the process of calculating the AC-connected offshore wind potential (in m). + type: number + minimum: 0 + + max_shore_distance: + description: Maximum distance to the shore above which wind turbines cannot be build. Such areas close to the shore are excluded in the process of calculating the AC-connected offshore wind potential (in m). + type: integer + minimum: 0 + + excluder_resolution: + description: Resolution on which to perform geographical elibility analysis (in m). + type: number + minimum: 0 + + clip_p_max_pu: + description: To avoid too small values in the `renewables` per-unit availability time series values below this threshold are set to zero (in p.u.). + type: number + minimum: 0 + + landfall_length: + description: Fixed length of the cable connection that is onshorelandfall in km. If 'centroid', the length is calculated as the distance to centroid of the onshore bus (in km). + type: integer + minimum: 0 + + solar-x: + additionalProperties: false + properties: + + cutout: + description: Specifies the directory where the relevant weather data ist stored. Should be listed in the configuration ``atlite.cutouts``. You can also reference an existing folder in the directory ``cutouts``. Source module must be ERA5. + type: string + examples: europe-2013-sarah3-era5 + + resource: + type: object + properties: + method: + description: A superordinate technology type. + type: string + enum: [pv] + panel: + description: Specifies the solar panel technology and its characteristic attributes. Choose panels as defined in `atlite `_. Can be a string or a dictionary with years as keys which denote the year another turbine model becomes available. + type: object + orientation: + type: object + properties: + slope: + description: Specifies the tilt angle (or slope) of the solar panel. A slope of zero corresponds to the face of the panel aiming directly overhead. A positive tilt angle steers the panel towards the equator. Realistically any angle in [0., 90.]. + type: number + azimuth: + description: Specifies the `azimuth `_ orientation of the solar panel. South corresponds to 180°. Any angle in [0., 360.] + type: number + + capacity_per_sqkm: + description: Allowable density of solar panel placement (in :math:`MW/km^2`).\ + type: number + + corine: + description: Specifies areas according to CORINE Land Cover codes which are generally eligible for wind turbine placement. Must be any subset of the `CORINE Land Cover code list `_. + type: array + items: + type: integer + + luisa: + type: boolean + + natura: + description: Switch to exclude `Natura 2000 `_ natural protection areas. Area is excluded if ``true``. + type: boolean + + excluder_resolution: + description: Resolution on which to perform geographical elibility analysis (in m). + type: integer + + clip_p_max_pu: + description: To avoid too small values in the renewables` per-unit availability time series values below this threshold are set to zero. + type: number + diff --git a/config/schemas/general.yaml b/config/schemas/general.yaml deleted file mode 100644 index 5d3270d12..000000000 --- a/config/schemas/general.yaml +++ /dev/null @@ -1,76 +0,0 @@ -# SPDX-FileCopyrightText: Contributors to PyPSA-Eur -# -# SPDX-License-Identifier: CC0-1.0 - -$schema: "https://json-schema.org/draft/2020-12/schema" -type: object -properties: - version: - $ref: "#/version" - tutorial: - $ref: "#/tutorial" - logging: - $ref: "#/logging" - private: - $ref: "#/private" - remote: - $ref: "#/remote" - -# Properties -# ---------- - -version: - title: "Version" - $$target: ["#/version"] - type: string - description: "Version of PyPSA-Eur. Descriptive only." - examples: ['v2025.1.0'] - -tutorial: - title: "Tutorial" - $$target: ["#/tutorial"] - type: boolean - description: "Switch to retrieve the tutorial data set instead of the full data set." -logging: - title: "Logging" - $$target: ["#/logging"] - description: "Logging configuration." - additionalProperties: false - properties: - level: - type: string - enum: ["DEBUG", "INFO", "WARNING", "ERROR"] - description: "Restrict console outputs to all infos, warning or errors only." - format: - type: string - description: "Custom format for log messages. See LogRecord attributes." - examples: ["%(levelname)s:%(name)s:%(message)s"] - -private: - title: "Private" - $$target: ["#/private"] - additionalProperties: false - properties: - keys: - additionalProperties: false - properties: - entsoe_api: - type: ["string", "null"] - description: "Optionally specify the ENTSO-E API key. See the guidelines to get ENTSO-E API key." - -remote: - title: "Remote" - $$target: ["#/remote"] - additionalProperties: false - properties: - ssh: - type: string - description: "Optionally specify the SSH of a remote cluster to be synchronized." - path: - type: string - description: "Optionally specify the file path within the remote cluster to be synchronized." - test_deprecation: - type: string - description: "Deprecated property. Use 'xx' instead." - deprecated: true - diff --git a/doc/configtables/atlite.csv b/doc/configtables/atlite.csv deleted file mode 100644 index 61e0d6b77..000000000 --- a/doc/configtables/atlite.csv +++ /dev/null @@ -1,14 +0,0 @@ -,Unit,Values,Description -cutout_directory,--,str,"Directory to store cutouts." -default_cutout,--,str,"Defines a default cutout." -nprocesses,--,int,"Number of parallel processes in cutout preparation" -show_progress,bool,true/false,"Whether progressbar for atlite conversion processes should be shown. False saves time." -cutouts,,, --- {name},--,"Convention is to name cutouts like ``--`` (e.g. ``europe-2013-sarah3-era5``).","Name of the cutout netcdf file. The user may specify multiple cutouts under configuration ``atlite: cutouts:``. Reference is used in configuration ``renewable: {technology}: cutout:``. The cutout ``base`` may be used to automatically calculate temporal and spatial bounds of the network." --- -- module,--,"Subset of {'era5','sarah'}","Source of the reanalysis weather dataset (e.g. `ERA5 `_ or `SARAH-3 `_)" --- -- x,°,"Float interval within [-180, 180]","Range of longitudes to download weather data for. If not defined, it defaults to the spatial bounds of all bus shapes." --- -- y,°,"Float interval within [-90, 90]","Range of latitudes to download weather data for. If not defined, it defaults to the spatial bounds of all bus shapes." --- -- dx,°,"Larger than 0.25","Grid resolution for longitude" --- -- dy,°,"Larger than 0.25","Grid resolution for latitude" --- -- time,,"Time interval within ['1979', '2018'] (with valid pandas date time strings)","Time span to download weather data for. If not defined, it defaults to the time interval spanned by the snapshots." --- -- features,,"String or list of strings with valid cutout features ('inlfux', 'wind').","When freshly building a cutout, retrieve data only for those features. If not defined, it defaults to all available features." diff --git a/doc/configtables/co2_budget.csv b/doc/configtables/co2_budget.csv deleted file mode 100644 index 8f11f9c6a..000000000 --- a/doc/configtables/co2_budget.csv +++ /dev/null @@ -1,2 +0,0 @@ -,Unit,Values,Description -co2_budget,--,Dictionary with planning horizons as keys.,CO2 budget as a fraction of 1990 emissions. Overwritten if ``Co2Lx`` or ``cb`` are set in ``{sector_opts}`` wildcard"doc/configtables/othertoplevel.csv diff --git a/doc/configtables/conventional.csv b/doc/configtables/conventional.csv deleted file mode 100644 index 12902f53d..000000000 --- a/doc/configtables/conventional.csv +++ /dev/null @@ -1,5 +0,0 @@ -,Unit,Values,Description -unit_commitment ,bool,"{true, false}","Allow the overwrite of ramp_limit_up, ramp_limit_start_up, ramp_limit_shut_down, p_min_pu, min_up_time, min_down_time, and start_up_cost of conventional generators. Refer to the CSV file „unit_commitment.csv“." -dynamic_fuel_price ,bool,"{true, false}","Consider the monthly fluctuating fuel prices for each conventional generator. Refer to the CSV file ""data/validation/monthly_fuel_price.csv""." -{name},--,string,For any carrier/technology overwrite attributes as listed below. --- {attribute},--,string or float,"For any attribute, can specify a float or reference to a file path to a CSV file giving floats for each country (2-letter code)." diff --git a/doc/configtables/countries.csv b/doc/configtables/countries.csv deleted file mode 100644 index 709b472c5..000000000 --- a/doc/configtables/countries.csv +++ /dev/null @@ -1,2 +0,0 @@ - ,Unit,Values,Description -countries,--,"Subset of {'AL', 'AT', 'BA', 'BE', 'BG', 'CH', 'CZ', 'DE', 'DK', 'EE', 'ES', 'FI', 'FR', 'GB', 'GR', 'HR', 'HU', 'IE', 'IT', 'LT', 'LU', 'LV', 'MD', 'ME', 'MK', 'NL', 'NO', 'PL', 'PT', 'RO', 'RS', 'SE', 'SI', 'SK', 'UA', 'XK'}","European countries defined by their `Two-letter country codes (ISO 3166-1) `_ which should be included in the energy system model." diff --git a/doc/configtables/electricity.csv b/doc/configtables/electricity.csv deleted file mode 100644 index c5c2291e0..000000000 --- a/doc/configtables/electricity.csv +++ /dev/null @@ -1,45 +0,0 @@ -,Unit,Values,Description -voltages,kV,"Any subset of {220., 300., 330., 380., 400., 500., 750.}",Voltage levels to consider -base_network, --, "Any value in {'entsoegridkit', 'osm-prebuilt', 'osm-raw}", "Specify the underlying base network, i.e. GridKit (based on ENTSO-E web map extract, OpenStreetMap (OSM) prebuilt or raw (built from raw OSM data), takes longer." -osm-prebuilt-version, --, "float, any value in range 0.1-0.6", "Choose the version of the prebuilt OSM network. Defaults to latest Zenodo release." -gaslimit_enable,bool,true or false,Add an overall absolute gas limit configured in ``electricity: gaslimit``. -gaslimit,MWhth,float or false,Global gas usage limit -co2limit_enable,bool,true or false,"Add an overall absolute carbon-dioxide emissions limit configured in ``electricity: co2limit`` in :mod:`prepare_network`. **Warning:** This option should currently only be used with electricity-only networks, not for sector-coupled networks." -co2limit,:math:`t_{CO_2-eq}/a`,float,Cap on total annual system carbon dioxide emissions -co2base,:math:`t_{CO_2-eq}/a`,float,Reference value of total annual system carbon dioxide emissions if relative emission reduction target is specified in ``{opts}`` wildcard. -operational_reserve,,,Settings for reserve requirements following `GenX `_ -,,, --- activate,bool,true or false,Whether to take operational reserve requirements into account during optimisation --- epsilon_load,--,float,share of total load --- epsilon_vres,--,float,share of total renewable supply --- contingency,MW,float,fixed reserve capacity -max_hours,,, --- battery,h,float,Maximum state of charge capacity of the battery in terms of hours at full output capacity ``p_nom``. Cf. `PyPSA documentation `_. --- H2,h,float,Maximum state of charge capacity of the hydrogen storage in terms of hours at full output capacity ``p_nom``. Cf. `PyPSA documentation `_. -extendable_carriers,,, --- Generator,--,Any extendable carrier,"Defines existing or non-existing conventional and renewable power plants to be extendable during the optimization. Conventional generators can only be built/expanded where already existent today. If a listed conventional carrier is not included in the ``conventional_carriers`` list, the lower limit of the capacity expansion is set to 0." --- StorageUnit,--,"Any subset of {'battery','H2'}",Adds extendable storage units (battery and/or hydrogen) at every node/bus after clustering without capacity limits and with zero initial capacity. --- Store,--,"Any subset of {'battery','H2'}",Adds extendable storage units (battery and/or hydrogen) at every node/bus after clustering without capacity limits and with zero initial capacity. --- Link,--,Any subset of {'H2 pipeline'},Adds extendable links (H2 pipelines only) at every connection where there are lines or HVDC links without capacity limits and with zero initial capacity. Hydrogen pipelines require hydrogen storage to be modelled as ``Store``. -powerplants_filter,--,"use `pandas.query `_ strings here, e.g. ``Country not in ['Germany']``",Filter query for the default powerplant database. -,,, -custom_powerplants,--,"use `pandas.query `_ strings here, e.g. ``Country in ['Germany']``",Filter query for the custom powerplant database. -,,, -everywhere_powerplants,--,"Any subset of {nuclear, oil, OCGT, CCGT, coal, lignite, geothermal, biomass}","List of conventional power plants to add to every node in the model with zero initial capacity. To be used in combination with ``extendable_carriers`` to allow for building conventional powerplants irrespective of existing locations." -,,, -conventional_carriers,--,"Any subset of {nuclear, oil, OCGT, CCGT, coal, lignite, geothermal, biomass}","List of conventional power plants to include in the model from ``resources/powerplants_s_{clusters}.csv``. If an included carrier is also listed in ``extendable_carriers``, the capacity is taken as a lower bound." -,,, -renewable_carriers,--,"Any subset of {solar, onwind, offwind-ac, offwind-dc, offwind-float, hydro}",List of renewable generators to include in the model. -estimate_renewable_capacities,,, --- enable,,bool,Activate routine to estimate renewable capacities in rule :mod:`add_electricity`. This option should not be used in combination with pathway planning ``foresight: myopic`` or ``foresight: perfect`` as renewable capacities are added differently in :mod:`add_existing_baseyear`. --- from_opsd,--,bool,Add renewable capacities from `OPSD database `_. The value is depreciated but still can be used. --- year,--,bool,Renewable capacities are based on existing capacities reported by IRENA (IRENASTAT) for the specified year --- expansion_limit,--,float or false,"Artificially limit maximum IRENA capacities to a factor. For example, an ``expansion_limit: 1.1`` means 110% of capacities . If false are chosen, the estimated renewable potentials determine by the workflow are used." --- technology_mapping,,,Mapping between PyPSA-Eur and powerplantmatching technology names --- -- Offshore,--,"Any subset of {offwind-ac, offwind-dc, offwind-float}","List of PyPSA-Eur carriers that is considered as (IRENA, OPSD) onshore technology." --- -- Offshore,--,{onwind},"List of PyPSA-Eur carriers that is considered as (IRENA, OPSD) offshore technology." --- -- PV,--,{solar},"List of PyPSA-Eur carriers that is considered as (IRENA, OPSD) PV technology." -autarky,,, --- enable,bool,true or false,Require each node to be autarkic by removing all lines and links. --- by_country,bool,true or false,Require each country to be autarkic by removing all cross-border lines and links. ``electricity: autarky`` must be enabled. -transmission_limit,str,"Values like 'vopt', 'v1.25', 'copt', 'c1.25'","Limit on transmission expansion. The first part can be ``v`` (for setting a limit on line volume) or ``c`` (for setting a limit on line cost). The second part can be ``opt`` or a float bigger than one (e.g. 1.25). If ``opt`` is chosen line expansion is optimised according to its capital cost (where the choice ``v`` only considers overhead costs for HVDC transmission lines, while ``c`` uses more accurate costs distinguishing between overhead and underwater sections and including inverter pairs). The setting ``v1.25`` will limit the total volume of line expansion to 25% of currently installed capacities weighted by individual line lengths. The setting ``c1.25`` will allow to build a transmission network that costs no more than 25 % more than the current system." diff --git a/doc/configtables/enable.csv b/doc/configtables/enable.csv deleted file mode 100644 index bb50e69ae..000000000 --- a/doc/configtables/enable.csv +++ /dev/null @@ -1,8 +0,0 @@ -,Unit,Values,Description -retrieve,str or bool,"{auto, true, false}","Switch to include (true) or exclude (false) the retrieve_* rules of snakemake into the workflow; 'auto' sets true|false based on availability of an internet connection to prevent issues with snakemake failing due to lack of internet connection." -retrieve_databundle,bool,"{true, false}","Switch to retrieve databundle from zenodo via the rule :mod:`retrieve_databundle` or whether to keep a custom databundle located in the corresponding folder." -retrieve_cost_data,bool,"{true, false}","Switch to retrieve technology cost data from `technology-data repository `_." -build_cutout,bool,"{true, false}","Switch to enable the building of cutouts via the rule :mod:`build_cutout`." -retrieve_cutout,bool,"{true, false}","Switch to enable the retrieval of cutouts from zenodo with :mod:`retrieve_cutout`." -custom_busmap,bool,"{true, false}","Switch to enable the use of custom busmaps in rule :mod:`cluster_network`. If activated the rule looks for provided busmaps at ``data/busmaps/base_s_{clusters}_{base_network}.csv`` which should have the same format as ``resources/busmap_base_s_{clusters}.csv``, i.e. the index should contain the buses of ``networks/base_s.nc``. {base_network} is the name of the selected base_network in electricity, e.g. ``gridkit``, ``osm-prebuilt``, or ``osm-raw``." -drop_leap_day,bool,"{true, false}","Switch to drop February 29 from all time-dependent data in leap years" diff --git a/doc/configtables/foresight.csv b/doc/configtables/foresight.csv deleted file mode 100644 index a19ec1393..000000000 --- a/doc/configtables/foresight.csv +++ /dev/null @@ -1,2 +0,0 @@ -,Unit,Values,Description -foresight,string,"{overnight, myopic, perfect}","See :ref:`Foresight Options` for detail explanations." diff --git a/doc/configtables/hydro.csv b/doc/configtables/hydro.csv deleted file mode 100644 index 8903aa0fa..000000000 --- a/doc/configtables/hydro.csv +++ /dev/null @@ -1,11 +0,0 @@ -,Unit,Values,Description -cutout,--,Must be 'europe-2013-sarah3-era5',Specifies the directory where the relevant weather data ist stored. -carriers,--,"Any subset of {'ror', 'PHS', 'hydro'}","Specifies the types of hydro power plants to build per-unit availability time series for. 'ror' stands for run-of-river plants, 'PHS' represents pumped-hydro storage, and 'hydro' stands for hydroelectric dams." -PHS_max_hours,h,float,Maximum state of charge capacity of the pumped-hydro storage (PHS) in terms of hours at full output capacity ``p_nom``. Cf. `PyPSA documentation `_. -hydro_max_hours,h,"Any of {float, 'energy_capacity_totals_by_country', 'estimate_by_large_installations'}",Maximum state of charge capacity of the pumped-hydro storage (PHS) in terms of hours at full output capacity ``p_nom`` or heuristically determined. Cf. `PyPSA documentation `_. -flatten_dispatch,bool,"{true, false}",Consider an upper limit for the hydro dispatch. The limit is given by the average capacity factor plus the buffer given in ``flatten_dispatch_buffer`` -flatten_dispatch_buffer,--,float,"If ``flatten_dispatch`` is true, specify the value added above the average capacity factor." -clip_min_inflow,MW,float,"To avoid too small values in the inflow time series, values below this threshold are set to zero." -eia_norm_year,--,"Year in EIA hydro generation dataset; or False to disable","To specify a specific year by which hydro inflow is normed that deviates from the snapshots' year" -eia_correct_by_capacity,--,boolean,"Correct EIA annual hydro generation data by installed capacity." -eia_approximate_missing,--,boolean,"Approximate hydro generation data for years not included in EIA dataset through a regression based on annual runoff." diff --git a/doc/configtables/lines.csv b/doc/configtables/lines.csv deleted file mode 100644 index 79fa2e16d..000000000 --- a/doc/configtables/lines.csv +++ /dev/null @@ -1,14 +0,0 @@ -,Unit,Values,Description -types,--,"Values should specify a `line type in PyPSA `_. Keys should specify the corresponding voltage level (e.g. 220., 300. and 380. kV)","Specifies line types to assume for the different voltage levels of the ENTSO-E grid extraction. Should normally handle voltage levels 220, 300, and 380 kV" -s_max_pu,--,"Value in [0.,1.]","Correction factor for line capacities (``s_nom``) to approximate :math:`N-1` security and reserve capacity for reactive power flows" -s_nom_max,MW,"float","Global upper limit for the maximum capacity of each extendable line." -max_extension,MW,"float","Upper limit for the extended capacity of each extendable line." -length_factor,--,float,"Correction factor to account for the fact that buses are *not* connected by lines through air-line distance." -under_construction,--,"One of {'zero': set capacity to zero, 'remove': remove completely, 'keep': keep with full capacity}","Specifies how to handle lines which are currently under construction." -reconnect_crimea,--,"true or false","Whether to reconnect Crimea to the Ukrainian grid" -dynamic_line_rating,,, --- activate,bool,"true or false","Whether to take dynamic line rating into account" --- cutout,--,"Should be a folder listed in the configuration ``atlite: cutouts:`` (e.g. 'europe-2013-sarah3-era5') or reference an existing folder in the directory ``cutouts``. Source module must be ERA5.","Specifies the directory where the relevant weather data ist stored." --- correction_factor,--,"float","Factor to compensate for overestimation of wind speeds in hourly averaged wind data" --- max_voltage_difference,deg,"float","Maximum voltage angle difference in degrees or 'false' to disable" --- max_line_rating,--,"float","Maximum line rating relative to nominal capacity without DLR, e.g. 1.3 or 'false' to disable" diff --git a/doc/configtables/links.csv b/doc/configtables/links.csv deleted file mode 100644 index 56342c7db..000000000 --- a/doc/configtables/links.csv +++ /dev/null @@ -1,6 +0,0 @@ -,Unit,Values,Description -p_max_pu,--,"Value in [0.,1.]","Correction factor for link capacities ``p_nom``." -p_nom_max,MW,"float","Global upper limit for the maximum capacity of each extendable DC link." -max_extension,MW,"float","Upper limit for the extended capacity of each extendable DC link." -length_factor,--,float,"Correction factor to account for the fact that buses are *not* connected by links through air-line distance." -under_construction,--,"One of {'zero': set capacity to zero, 'remove': remove completely, 'keep': keep with full capacity}","Specifies how to handle lines which are currently under construction." diff --git a/doc/configtables/offwind.csv b/doc/configtables/offwind.csv deleted file mode 100644 index 7dc8a4435..000000000 --- a/doc/configtables/offwind.csv +++ /dev/null @@ -1,18 +0,0 @@ -,Unit,Values,Description -cutout,--,"Should be a folder listed in the configuration ``atlite: cutouts:`` (e.g. 'europe-2013-sarah3-era5') or reference an existing folder in the directory ``cutouts``. Source module must be ERA5.","Specifies the directory where the relevant weather data ist stored." -resource,,, --- method,--,"Must be 'wind'","A superordinate technology type." --- turbine,--,"One of turbine types included in `atlite `_. Can be a string or a dictionary with years as keys which denote the year another turbine model becomes available.","Specifies the turbine type and its characteristic power curve." --- smooth,--,"{True, False}","Switch to apply a gaussian kernel density smoothing to the power curve." -capacity_per_sqkm,:math:`MW/km^2`,float,"Allowable density of wind turbine placement." -correction_factor,--,float,"Correction factor for capacity factor time series." -excluder_resolution,m,float,"Resolution on which to perform geographical elibility analysis." -corine,--,"Any *realistic* subset of the `CORINE Land Cover code list `_","Specifies areas according to CORINE Land Cover codes which are generally eligible for AC-connected offshore wind turbine placement." -luisa,--,"Any subset of the `LUISA Base Map codes in Annex 1 `_","Specifies areas according to the LUISA Base Map codes which are generally eligible for AC-connected offshore wind turbine placement." -natura,bool,"{true, false}","Switch to exclude `Natura 2000 `_ natural protection areas. Area is excluded if ``true``." -ship_threshold,--,float,"Ship density threshold from which areas are excluded." -max_depth,m,float,"Maximum sea water depth at which wind turbines can be build. Maritime areas with deeper waters are excluded in the process of calculating the AC-connected offshore wind potential." -min_shore_distance,m,float,"Minimum distance to the shore below which wind turbines cannot be build. Such areas close to the shore are excluded in the process of calculating the AC-connected offshore wind potential." -max_shore_distance,m,float,"Maximum distance to the shore above which wind turbines cannot be build. Such areas close to the shore are excluded in the process of calculating the AC-connected offshore wind potential." -clip_p_max_pu,p.u.,float,"To avoid too small values in the renewables` per-unit availability time series values below this threshold are set to zero." -landfall_length,km,float,"Fixed length of the cable connection that is onshorelandfall in km. If 'centroid', the length is calculated as the distance to centroid of the onshore bus." diff --git a/doc/configtables/onwind.csv b/doc/configtables/onwind.csv deleted file mode 100644 index 676494f4e..000000000 --- a/doc/configtables/onwind.csv +++ /dev/null @@ -1,19 +0,0 @@ -,Unit,Values,Description -cutout,--,"Should be a folder listed in the configuration ``atlite: cutouts:`` (e.g. 'europe-2013-sarah3-era5') or reference an existing folder in the directory ``cutouts``. Source module must be ERA5.","Specifies the directory where the relevant weather data ist stored." -resource,,, --- method,--,"Must be 'wind'","A superordinate technology type." --- turbine,--,"One of turbine types included in `atlite `_. Can be a string or a dictionary with years as keys which denote the year another turbine model becomes available.","Specifies the turbine type and its characteristic power curve." --- smooth,--,"{True, False}","Switch to apply a gaussian kernel density smoothing to the power curve." -capacity_per_sqkm,:math:`MW/km^2`,float,"Allowable density of wind turbine placement." -corine,,, --- grid_codes,--,"Any subset of the `CORINE Land Cover code list `_","Specifies areas according to CORINE Land Cover codes which are generally eligible for wind turbine placement." --- distance,m,float,"Distance to keep from areas specified in ``distance_grid_codes``" --- distance_grid_codes,--,"Any subset of the `CORINE Land Cover code list `_","Specifies areas according to CORINE Land Cover codes to which wind turbines must maintain a distance specified in the setting ``distance``." -luisa,,, --- grid_codes,--,"Any subset of the `LUISA Base Map codes in Annex 1 `_","Specifies areas according to the LUISA Base Map codes which are generally eligible for wind turbine placement." --- distance,m,float,"Distance to keep from areas specified in ``distance_grid_codes``" --- distance_grid_codes,--,"Any subset of the `LUISA Base Map codes in Annex 1 `_","Specifies areas according to the LUISA Base Map codes to which wind turbines must maintain a distance specified in the setting ``distance``." -natura,bool,"{true, false}","Switch to exclude `Natura 2000 `_ natural protection areas. Area is excluded if ``true``." -clip_p_max_pu,p.u.,float,"To avoid too small values in the renewables` per-unit availability time series values below this threshold are set to zero." -correction_factor,--,float,"Correction factor for capacity factor time series." -excluder_resolution,m,float,"Resolution on which to perform geographical elibility analysis." diff --git a/doc/configtables/run.csv b/doc/configtables/run.csv deleted file mode 100644 index 371cd3fe1..000000000 --- a/doc/configtables/run.csv +++ /dev/null @@ -1,12 +0,0 @@ -,Unit,Values,Description -name,--,str/list,"Specify a name for your run. Results will be stored under this name. If ``scenario: enable:`` is set to ``true``, the name must contain a subset of scenario names defined in ``scenario: file:``. If the name is 'all', all defined scenarios will be run." -prefix,--,str,"Prefix for the run name which is used as a top-layer directory name in the results and resources folders." -scenarios,,, --- enable,bool,"{true, false}","Switch to select whether workflow should generate scenarios based on ``file``." --- file,str,,"Path to the scenario yaml file. The scenario file contains config overrides for each scenario. In order to be taken account, ``run: scenarios`` has to be set to ``true`` and ``run: name`` has to be a subset of top level keys given in the scenario file. In order to automatically create a `scenario.yaml` file based on a combination of settings, alter and use the ``config/create_scenarios.py`` script in the ``config`` directory." -disable_progressbar,bool,"{true, false}","Switch to select whether progressbar should be disabled." -shared_resources,,, --- policy,bool/str,,"Boolean switch to select whether resources should be shared across runs. If a string is passed, this is used as a subdirectory name for shared resources. If set to 'base', only resources before creating the elec.nc file are shared." --- exclude,str,"For the case shared_resources=base, specify additional files that should not be shared across runs." -shared_cutouts,bool,"{true, false}","Switch to select whether cutouts should be shared across runs." -use_shadow_directory,bool,"{true, false}","Set to ``true`` (default) if snakemake shadow directories (``shallow``) should be used. Set to ``false`` if problems occcur." diff --git a/doc/configtables/scenario.csv b/doc/configtables/scenario.csv deleted file mode 100644 index fa6836bac..000000000 --- a/doc/configtables/scenario.csv +++ /dev/null @@ -1,5 +0,0 @@ -,Unit,Values,Description -clusters,--,cf. :ref:`clusters`,"List of ``{clusters}`` wildcards to run." -opts,--,cf. :ref:`opts`,"List of ``{opts}`` wildcards to run." -sector_opts,--,cf. :ref:`sector_opts`,"List of ``{sector_opts}`` wildcards to run." -planning_horizons,--,cf. :ref:`planning_horizons`,"List of ``{planning_horizon}`` wildcards to run." diff --git a/doc/configtables/snapshots.csv b/doc/configtables/snapshots.csv deleted file mode 100644 index 4be0439b1..000000000 --- a/doc/configtables/snapshots.csv +++ /dev/null @@ -1,4 +0,0 @@ -,Unit,Values,Description -start,--,str or datetime-like; e.g. YYYY-MM-DD,Left bound of date range -end,--,str or datetime-like; e.g. YYYY-MM-DD,Right bound of date range -inclusive,--,"One of {'neither', 'both', ‘left’, ‘right’}","Make the time interval closed to the ``left``, ``right``, or both sides ``both`` or neither side ``None``." diff --git a/doc/configtables/solar.csv b/doc/configtables/solar.csv deleted file mode 100644 index 933c18460..000000000 --- a/doc/configtables/solar.csv +++ /dev/null @@ -1,15 +0,0 @@ -,Unit,Values,Description -cutout,--,"Should be a folder listed in the configuration ``atlite: cutouts:`` (e.g. 'europe-2013-sarah3-era5') or reference an existing folder in the directory ``cutouts``. Source module can be ERA5 and/or SARAH-3.","Specifies the directory where the relevant weather data ist stored that is specified at ``atlite/cutouts`` configuration. Both ``sarah`` and ``era5`` work." -resource,,, --- method,--,"Must be 'pv'","A superordinate technology type." --- panel,--,"One of {'Csi', 'CdTe', 'KANENA'} as defined in `atlite `_ . Can be a string or a dictionary with years as keys which denote the year another turbine model becomes available.","Specifies the solar panel technology and its characteristic attributes." --- orientation,,, --- -- slope,°,"Realistically any angle in [0., 90.]","Specifies the tilt angle (or slope) of the solar panel. A slope of zero corresponds to the face of the panel aiming directly overhead. A positive tilt angle steers the panel towards the equator." --- -- azimuth,°,"Any angle in [0., 360.]","Specifies the `azimuth `_ orientation of the solar panel. South corresponds to 180.°." -capacity_per_sqkm,:math:`MW/km^2`,float,"Allowable density of solar panel placement." -correction_factor,--,float,"A correction factor for the capacity factor (availability) time series." -corine,--,"Any subset of the `CORINE Land Cover code list `_","Specifies areas according to CORINE Land Cover codes which are generally eligible for solar panel placement." -luisa,--,"Any subset of the `LUISA Base Map codes in Annex 1 `_","Specifies areas according to the LUISA Base Map codes which are generally eligible for solar panel placement." -natura,bool,"{true, false}","Switch to exclude `Natura 2000 `_ natural protection areas. Area is excluded if ``true``." -clip_p_max_pu,p.u.,float,"To avoid too small values in the renewables` per-unit availability time series values below this threshold are set to zero." -excluder_resolution,m,float,"Resolution on which to perform geographical elibility analysis." diff --git a/doc/configuration.rst b/doc/configuration.rst index d36835022..04e3c60bb 100644 --- a/doc/configuration.rst +++ b/doc/configuration.rst @@ -9,14 +9,25 @@ Configuration ########################################## -PyPSA-Eur has several configuration options which are documented in this section and are collected in a ``config/config.yaml`` file. This file defines deviations from the default configuration (``config/config.default.yaml``); confer installation instructions at :ref:`defaultconfig`. +PyPSA-Eur has several configuration options which are documented in this section and are +collected in a ``config/config.yaml`` file. This file defines deviations from the +default configuration (``config/config.default.yaml``); confer installation +instructions at :ref:`defaultconfig`. + +.. Note:: + Configurations are validated against a JSON schema, located at + ``config/config.schema.yaml``. Which means it is also possible to get tooltips and + auto completion for all config settings in your editor. For VSCode, + add ``"json.validate.enable": true`` to your settings. .. _toplevel_cf: Top-level configuration ======================= -"Private" refers to local, machine-specific settings or data meant for personal use, not to be shared. "Remote" indicates the address of a server used for data exchange, often for clusters and data pushing/pulling. +"Private" refers to local, machine-specific settings or data meant for personal use, +not to be shared. "Remote" indicates the address of a server used for data exchange, +often for clusters and data pushing/pulling. .. literalinclude:: ../config/config.default.yaml :language: yaml @@ -26,21 +37,21 @@ Top-level configuration .. dropdown:: Details - .. jsonschema:: ../config/schemas/general.yaml#/version + .. jsonschema:: ../config/config.schema.yaml#/properties/version :lift_description: - .. jsonschema:: ../config/schemas/general.yaml#/tutorial + .. jsonschema:: ../config/config.schema.yaml#/properties/tutorial :lift_description: - .. jsonschema:: ../config/schemas/general.yaml#/logging + .. jsonschema:: ../config/config.schema.yaml#/properties/logging :lift_description: :hide_key: /**/additionalProperties - .. jsonschema:: ../config/schemas/general.yaml#/private + .. jsonschema:: ../config/config.schema.yaml#/properties/private :lift_description: :hide_key: /**/additionalProperties - .. jsonschema:: ../config/schemas/general.yaml#/remote + .. jsonschema:: ../config/config.schema.yaml#/properties/remote :lift_description: :hide_key: /**/additionalProperties @@ -50,21 +61,28 @@ Top-level configuration ``run`` ============= -It is common conduct to analyse energy system optimisation models for **multiple scenarios** for a variety of reasons, -e.g. assessing their sensitivity towards changing the temporal and/or geographical resolution or investigating how -investment changes as more ambitious greenhouse-gas emission reduction targets are applied. +It is common conduct to analyse energy system optimisation models for +**multiple scenarios** for a variety of reasons, e.g. assessing their sensitivity +towards changing the temporal and/or geographical resolution or investigating how +investment changes as more ambitious greenhouse-gas emission reduction targets are +applied. -The ``run`` section is used for running and storing scenarios with different configurations which are not covered by :ref:`wildcards`. It determines the path at which resources, networks and results are stored. Therefore the user can run different configurations within the same directory. If a run with a non-empty name should use cutouts shared across runs, set ``shared_cutouts`` to `true`. +The ``run`` section is used for running and storing scenarios with different +configurations which are not covered by :ref:`wildcards`. It determines the path at +which resources, networks and results are stored. Therefore the user can run different +configurations within the same directory. If a run with a non-empty name should use +cutouts shared across runs, set ``shared_cutouts`` to `true`. .. literalinclude:: ../config/config.default.yaml :language: yaml :start-at: run: :end-before: # docs -.. csv-table:: - :header-rows: 1 - :widths: 22,7,22,33 - :file: configtables/run.csv +.. dropdown:: Details + + .. jsonschema:: ../config/config.schema.yaml#/properties/run + :lift_description: + :hide_key: /**/additionalProperties .. _foresight_cf: @@ -76,10 +94,11 @@ The ``run`` section is used for running and storing scenarios with different con :start-at: foresight: :end-at: foresight: -.. csv-table:: - :header-rows: 1 - :widths: 22,7,22,33 - :file: configtables/foresight.csv +.. dropdown:: Details + + .. jsonschema:: ../config/config.schema.yaml#/properties/foresight + :lift_description: + :hide_key: /**/additionalProperties .. note:: If you use myopic or perfect foresight, the planning horizon in @@ -112,7 +131,8 @@ that snakemake's `expand(...) function `__ uses. -An exemplary dependency graph (starting from the simplification rules) then looks like this: +An exemplary dependency graph (starting from the simplification rules) then looks like +this: .. image:: img/scenarios.png @@ -121,10 +141,11 @@ An exemplary dependency graph (starting from the simplification rules) then look :start-at: scenario: :end-before: # docs -.. csv-table:: - :header-rows: 1 - :widths: 22,7,22,33 - :file: configtables/scenario.csv +.. dropdown:: Details + + .. jsonschema:: ../config/config.schema.yaml#/properties/scenario + :lift_description: + :hide_key: /**/additionalProperties .. _countries: @@ -136,27 +157,30 @@ An exemplary dependency graph (starting from the simplification rules) then look :start-at: countries: :end-before: # docs -.. csv-table:: - :header-rows: 1 - :widths: 22,7,22,33 - :file: configtables/countries.csv +.. dropdown:: Details + + .. jsonschema:: ../config/config.schema.yaml#/properties/countries + :lift_description: + :hide_key: /**/additionalProperties .. _snapshots_cf: ``snapshots`` ============= -Specifies the temporal range to build an energy system model for as arguments to `pandas.date_range `__ +Specifies the temporal range to build an energy system model for as arguments to +`pandas.date_range `__ .. literalinclude:: ../config/config.default.yaml :language: yaml :start-at: snapshots: :end-before: # docs -.. csv-table:: - :header-rows: 1 - :widths: 22,7,22,33 - :file: configtables/snapshots.csv +.. dropdown:: Details + + .. jsonschema:: ../config/config.schema.yaml#/properties/snapshots + :lift_description: + :hide_key: /**/additionalProperties .. _enable_cf: @@ -170,14 +194,15 @@ Switches for some rules and optional features. :start-after: #enable :end-before: # docs -.. csv-table:: - :header-rows: 1 - :widths: 22,7,22,33 - :file: configtables/enable.csv +.. dropdown:: Details + + .. jsonschema:: ../config/config.schema.yaml#/properties/enable + :lift_description: + :hide_key: /**/additionalProperties .. _CO2_budget_cf: -``co2 budget`` +``co2_budget`` ============== .. literalinclude:: ../config/config.default.yaml @@ -185,10 +210,11 @@ Switches for some rules and optional features. :start-at: co2_budget: :end-before: # docs -.. csv-table:: - :header-rows: 1 - :widths: 22,7,22,33 - :file: configtables/co2_budget.csv +.. dropdown:: Details + + .. jsonschema:: ../config/config.schema.yaml#/properties/co2_budget + :lift_description: + :hide_key: /**/additionalProperties .. note:: this parameter is over-ridden if ``Co2Lx`` or ``cb`` is set in @@ -204,27 +230,31 @@ Switches for some rules and optional features. :start-at: electricity: :end-before: # docs -.. csv-table:: - :header-rows: 1 - :widths: 22,7,22,33 - :file: configtables/electricity.csv +.. dropdown:: Details + + .. jsonschema:: ../config/config.schema.yaml#/properties/electricity + :lift_description: + :hide_key: /**/additionalProperties .. _atlite_cf: ``atlite`` ========== -Define and specify the ``atlite.Cutout`` used for calculating renewable potentials and time-series. All options except for ``features`` are directly used as `cutout parameters `__. +Define and specify the ``atlite.Cutout`` used for calculating renewable potentials and +time-series. All options except for ``features`` are directly used as +`cutout parameters `__. .. literalinclude:: ../config/config.default.yaml :language: yaml :start-at: atlite: :end-before: # docs -.. csv-table:: - :header-rows: 1 - :widths: 22,7,22,33 - :file: configtables/atlite.csv +.. dropdown:: Details + + .. jsonschema:: ../config/config.schema.yaml#/properties/atlite + :lift_description: + :hide_key: /**/additionalProperties .. _renewable_cf: @@ -239,10 +269,11 @@ Define and specify the ``atlite.Cutout`` used for calculating renewable potentia :start-at: renewable: :end-before: offwind-ac: -.. csv-table:: - :header-rows: 1 - :widths: 22,7,22,33 - :file: configtables/onwind.csv +.. dropdown:: Details + + .. jsonschema:: ../config/config.schema.yaml#/properties/renewable/onwind + :lift_description: + :hide_key: /**/additionalProperties .. note:: Notes on ``capacity_per_sqkm``. ScholzPhd Tab 4.3.1: 10MW/km^2 and assuming 30% fraction of the already restricted @@ -261,10 +292,11 @@ Define and specify the ``atlite.Cutout`` used for calculating renewable potentia :start-at: offwind-ac: :end-before: solar: -.. csv-table:: - :header-rows: 1 - :widths: 22,7,22,33 - :file: configtables/offwind.csv +.. dropdown:: Details + + .. jsonschema:: ../config/config.schema.yaml#/definitions/offwind-x + :lift_description: + :hide_key: /**/additionalProperties .. note:: Notes on ``capacity_per_sqkm``. ScholzPhd Tab 4.3.1: 10MW/km^2 and assuming 20% fraction of the already restricted @@ -276,7 +308,7 @@ Define and specify the ``atlite.Cutout`` used for calculating renewable potentia from 10.1016/j.energy.2018.08.153 until done more rigorously in #153 -``solar`` +``solar-x`` --------------- .. literalinclude:: ../config/config.default.yaml @@ -284,10 +316,11 @@ Define and specify the ``atlite.Cutout`` used for calculating renewable potentia :start-at: solar: :end-before: hydro: -.. csv-table:: - :header-rows: 1 - :widths: 22,7,22,33 - :file: configtables/solar.csv +.. dropdown:: Details + + .. jsonschema:: ../config/config.schema.yaml#/definitions/solar-x + :lift_description: + :hide_key: /**/additionalProperties .. note:: Notes on ``capacity_per_sqkm``. ScholzPhd Tab 4.3.1: 170 MW/km^2 and assuming 1% of the area can be used for solar PV panels. @@ -306,10 +339,11 @@ Define and specify the ``atlite.Cutout`` used for calculating renewable potentia :start-at: hydro: :end-before: # docs -.. csv-table:: - :header-rows: 1 - :widths: 22,7,22,33 - :file: configtables/hydro.csv +.. dropdown:: Details + + .. jsonschema:: ../config/config.schema.yaml#/properties/renewable/hydro + :lift_description: + :hide_key: /**/additionalProperties .. _lines_cf: @@ -328,10 +362,11 @@ overwrite the existing values. :start-at: conventional: :end-before: # docs -.. csv-table:: - :header-rows: 1 - :widths: 22,7,22,33 - :file: configtables/conventional.csv +.. dropdown:: Details + + .. jsonschema:: ../config/config.schema.yaml#/properties/conventional + :lift_description: + :hide_key: /**/additionalProperties ``lines`` ============= @@ -341,10 +376,11 @@ overwrite the existing values. :start-at: lines: :end-before: # docs -.. csv-table:: - :header-rows: 1 - :widths: 22,7,22,33 - :file: configtables/lines.csv +.. dropdown:: Details + + .. jsonschema:: ../config/config.schema.yaml#/properties/lines + :lift_description: + :hide_key: /**/additionalProperties .. _links_cf: @@ -356,10 +392,11 @@ overwrite the existing values. :start-at: links: :end-before: # docs -.. csv-table:: - :header-rows: 1 - :widths: 22,7,22,33 - :file: configtables/links.csv +.. dropdown:: Details + + .. jsonschema:: ../config/config.schema.yaml#/properties/links + :lift_description: + :hide_key: /**/additionalProperties .. _transformers_cf: diff --git a/scripts/__init__.py b/scripts/__init__.py index 1769785c2..d57164a38 100644 --- a/scripts/__init__.py +++ b/scripts/__init__.py @@ -1,5 +1,3 @@ # SPDX-FileCopyrightText: Contributors to PyPSA-Eur # # SPDX-License-Identifier: MIT - -# coding: utf-8