Package 'mrwater'

Years to be returned

Initialization year (for weight by cropland)

LPJmL version required for respective inputs: natveg or crop

Switch between different climate scenarios or historical baseline "GSWP3-W5E5:historical"

Irrigation system used: system share as in initialization year, or drip, surface, sprinkler for full irrigation by selected system

Multicropping activated (TRUE) or not (FALSE) and Multiple Cropping Suitability mask selected (mask can be: "none": no mask applied (only for development purposes) "actual:total": currently multicropped areas calculated from total harvested areas and total physical areas per cell from readLandInG "actual:crop" (crop-specific), "actual:irrigation" (irrigation-specific), "actual:irrig_crop" (crop- and irrigation-specific) "total" "potential:endogenous": potentially multicropped areas given temperature and productivity limits "potential:exogenous": potentially multicropped areas given GAEZ suitability classification) (e.g. TRUE:actual:total; TRUE:none; FALSE)

Years to be returned

If NULL: total potential croparea is used; if !NULL: already irrigated area is subtracted; year specified here is the year of the initialization used for cropland area initialization in calcIrrigatedArea (e.g. NULL, 1995, 2010)

Initialization year for current cropland area

Land availability scenario consisting of two parts separated by ":": 1. available land scenario (currCropland, currIrrig, potCropland) 2. protection scenario (WDPA, or one of the scenarios available in calcConservationPriorities, e.g., 30by20, BH, BH_IFL, PBL_HalfEarth, or NA for no protection). For case of no land protection select "NA" in second part of argument or do not specify second part of the argument

Defines LPJmL version for crop/grass and natveg specific inputs

Switch between different climate scenarios

Number of cells to be returned (select "magpiecell" for 59199 cells or "lpjcell" for 67420 cells)

Degree of processing: raw, smoothed, harmonized, harmonized2020

grper (default): water available in growing period per year; total: total water available throughout the year; monthly: monthly water availability (for further processing, e.g. in calcEnvmtlFlow)

Years to be returned

LPJmL version required for respective inputs: natveg or crop

Climate model (e.g., "MRI-ESM2-0:ssp370") or historical baseline (e.g., "GSWP3-W5E5:historical")

Factor determining water requirement reduction in off season due to fallow period between harvest of first (main) season and sowing of second (off) season

Multicropping area mask to be used "none": no mask applied (only for development purposes) "actual:total": currently multicropped areas calculated from total harvested areas and total physical areas per cell from readLandInG "actual:crop" (crop-specific), "actual:irrigation" (irrigation-specific), "actual:irrig_crop" (crop- and irrigation-specific) "total" "potential:endogenous": potentially multicropped areas given temperature and productivity limits "potential:exogenous": potentially multicropped areas given GAEZ suitability classification

output to be returned by the function: combination of crop type ("crops" or "grass") and season ("main" (LPJmL growing period), "year" (entire year)), separated by ":" ("crops:main", "crops:year", "grass:main", "grass:year")

initialization year

LUH or LandInG Note: once migration to Toolbox data is complete, this function can be replaced with calcCropareaLandInG

crops to be reported: "kcr" for MAgPIE items, and "lpj" for LPJmL items

Years to be returned

If NULL: total potential croparea is used; if !NULL: already irrigated area is subtracted; year specified here is the year of the initialization used for cropland area initialization in calcIrrigatedArea (e.g. NULL, 1995, 2010)

Initialization year for current cropland area

Cropmix for which croparea share is calculated (options: "hist_irrig" for historical cropmix on currently irrigated area, "hist_total" for historical cropmix on total cropland, or selection of proxycrops as vector)

Land availability scenario consisting of two parts separated by ":": 1. available land scenario (currCropland, currIrrig, potCropland) 2. protection scenario (WDPA, or one of the scenarios available in calcConservationPriorities, e.g., 30by20, BH, BH_IFL, PBL_HalfEarth, or NA for no protection). For case of no land protection select "NA" in second part of argument or do not specify second part of the argument

Croparea initialization year

Cropmix for which croparea share is calculated (options: "hist_irrig" for historical cropmix on currently irrigated area, "hist_rainf" for historical cropmix on currently irrigated area, "hist_total" for historical cropmix on total cropland, or selection of proxycrops)

"biomass": returns the production quantity in terms of crop biomass (in tDM) "revenue": returns the revenue in terms of price x quantity of crop production (in USD)

EFP and non-agricultural water use scenario separated with a "." (e.g. "on.ssp2")

management in terms of irrigation and multiple cropping practices consisting of multiple cropping scenario ("single", actMC", "potMC") and ("potential", "counterfactual") separated by ":" (e.g. "single:potential", "actMC:counterfactual") Multiple cropping practices: "single": single cropping assumed everywhere "actMC": multiple cropping as reported by LandInG data "potMC": multiple cropping practiced everywhere where it is possible Irrigation assumption: "potential": irrigation practiced where possible according to irrigation potentials or practiced according to area information (see param 'area') "counterfactual": production and revenue for counterfactual case that irrigated areas were managed under rainfed conditions

area scenario "actual": current cropland and currently irrigated areas or potentially irrigated areas following land availability defined in landScen scenario: consisting of two parts separated by ":": 1. available land scenario (currCropland, currIrrig, potCropland) 2. protection scenario (WDPA, or one of the scenarios available in calcConservationPriorities, e.g., 30by20, BH, BH_IFL, PBL_HalfEarth, or NA for no protection). For case of no land protection select "NA" in second part of argument or do not specify second part of the argument

LPJmL version used

Switch between different climate scenarios or historical baseline "GSWP3-W5E5:historical"

Years for which irrigatable area is calculated

Initialization year for initial croparea

EFR method used including selected strictness of EFRs (e.g. Smakhtin:good, VMF:fair)

Strictness of accessibility restriction: discharge that is exceeded x percent of the time on average throughout a year (Qx). (e.g. Q75: 0.25, Q50: 0.5)

Rank and optimization method consisting of Unit according to which rank is calculated: USD_ha (USD per hectare) for relative area return, or USD_m3 (USD per cubic meter) for relative volumetric return; USD for absolute return (total profit); Price aggregation: "GLO" for global average prices, or "ISO" for country-level prices and boolean indicating fullpotential (TRUE, i.e. cell receives full irrigation requirements in total area) or reduced potential (FALSE, reduced potential of cell receives at later stage in allocation algorithm); separated by ":"

If TRUE: LPJmL yields calibrated to FAO country yield in iniyear Also needs specification of refYields, separated by ":". Options: FALSE (for single cropping analyses) or "TRUE:actual:irrig_crop" (for multiple cropping analyses) If FALSE: uncalibrated LPJmL yields are used

Rule to be applied for river basin discharge allocation across cells of river basin ("optimization", "upstreamfirst", "equality")

Threshold of yield improvement potential required (in USD per hectare)

Irrigation system used ("surface", "sprinkler", "drip", "initialization")

Selected cropmix (options: "hist_irrig" for historical cropmix on currently irrigated area, "hist_total" for historical cropmix on total cropland, "hist_rainf" for historical rainfed cropmix, or selection of proxycrops)

If TRUE: currently already irrigated areas in initialization year are reserved for irrigation, if FALSE: no irrigation areas reserved (irrigation potential)

Water transport distance allowed to fulfill locally unfulfilled water demand by surrounding cell water availability

If TRUE: non-renewable groundwater can be used. If FALSE: non-renewable groundwater cannot be used.

LPJmL version used for yields

Climate scenarios or historical baseline "GSWP3-W5E5:historical"

Crop yield gain through multiple cropping under rainfed conditions "multicropping_rf", multiple cropping under irrigated conditions "multicropping_ir", irrigation under single cropping conditions "irrigation_singlecropping" irrigation and multiple cropping "irrigation_multicropping"

Price aggregation: "GLO" for global average prices, or "ISO" for country-level prices, or "CONST" for same price for all crops

initialization year for food price and cropmix area

Years to be returned by the function

If TRUE: LPJmL yields calibrated to FAO country yield in iniyear Also needs specification of refYields, separated by ":". Options: FALSE (for single cropping analyses) or "TRUE:actual:irrig_crop" (for multiple cropping analyses) If FALSE: uncalibrated LPJmL yields are used

Multicropping activated (TRUE) or not (FALSE) and Multiple Cropping Suitability mask selected (mask can be: "none": no mask applied (only for development purposes) "actual:total": currently multicropped areas calculated from total harvested areas and total physical areas per cell from readLandInG "actual:crop" (crop-specific), "actual:irrigation" (irrigation-specific), "actual:irrig_crop" (crop- and irrigation-specific) "total" "potential:endogenous": potentially multicropped areas given temperature and productivity limits "potential:exogenous": potentially multicropped areas given GAEZ suitability classification) (e.g. TRUE:actual:total; TRUE:none; FALSE)

LPJmL version used

Years to be returned (Note: does not affect years of harmonization or smoothing)

Switch between different climate scenarios or historical baseline "GSWP3-W5E5:historical"

Method used: Quantile method (Q) or Coefficient of Variation (CV) combined with scalar value defining the strictness of accessibility restriction: discharge that is exceeded x percent of the time on average throughout a year is inaccessible (e.g. Q:1 all discharge accessible, Q:0.75 0.75-quantile is accessible everything that is more variable inaccessible) or base value for exponential curve, separated by : (CV:2)

LPJmL version required for respective inputs: natveg or crop

Years to be returned (Note: does not affect years of harmonization or smoothing)

Switch between different climate scenarios or historical baseline "GSWP3-W5E5:historical"

Method used: Quantile method (Q) or Coefficient of Variation (CV) combined with scalar value defining the strictness of accessibility restriction: discharge that is exceeded x percent of the time on average throughout a year (Qx, e.g. Q75: 0.25, Q50: 0.5) or base value for exponential curve separated by : (CV:2)

Years to be returned (Note: does not affect years of harmonization or smoothing)

LPJmL version used

Switch between different climate scenarios or historical baseline "GSWP3-W5E5:historical"

Method used: Quantile method (Q) or Coefficient of Variation (CV) combined with scalar value defining the strictness of accessibility restriction: discharge that is exceeded x percent of the time on average throughout a year (Qx, e.g. Q75: 0.25, Q50: 0.5) or base value for exponential curve separated by : (CV:2)

EFR method used including selected strictness of EFRs (Smakhtin:good, VMF:fair)

non-agricultural water use scenario

output to be displayed: irrigated area "IrrigArea" or available water volume "wat_ag_ww" "wat_ag_wc"

range of x-axis (gainthreshold) to be depicted on the curve

years for which irrigatable area is calculated

initialization year

LPJmL version required for respective inputs: natveg or crop

Switch between different climate scenarios or historical baseline "GSWP3-W5E5:historical"

EFR method used including selected strictness of EFRs (e.g. Smakhtin:good, VMF:fair)

Method used: Quantile method (Q) or Coefficient of Variation (CV) combined with scalar value defining the strictness of accessibility restriction: discharge that is exceeded x percent of the time on average throughout a year (Qx, e.g. Q75: 0.25, Q50: 0.5) or base value for exponential curve separated by : (CV:2)

Rank and optimization method consisting of Unit according to which rank is calculated: USD_ha (USD per hectare) for relative area return, or USD_m3 (USD per cubic meter) for relative volumetric return; USD for absolute return (total profit); Price aggregation: "GLO" for global average prices, or "ISO" for country-level prices and boolean indicating fullpotential (TRUE, i.e. cell receives full irrigation requirements in total area) or reduced potential (FALSE, reduced potential of cell receives at later stage in allocation algorithm); separated by ":"

If TRUE: LPJmL yields calibrated to FAO country yield in iniyear Also needs specification of refYields, separated by ":". Options: FALSE (for single cropping analyses) or "TRUE:actual:irrig_crop" (for multiple cropping analyses) If FALSE: uncalibrated LPJmL yields are used

Rule to be applied for river basin discharge allocation across cells of river basin ("optimization", "upstreamfirst", "equality")

Irrigation system used ("surface", "sprinkler", "drip", "initialization")

Land availability scenario consisting of two parts separated by ":": 1. available land scenario (currCropland, currIrrig, potCropland) 2. protection scenario (WDPA, or one of the scenarios available in calcConservationPriorities, e.g., 30by20, BH, BH_IFL, PBL_HalfEarth, or NA for no protection). For case of no land protection select "NA" in second part of argument or do not specify second part of the argument

Selected cropmix (options: "hist_irrig" for historical cropmix on currently irrigated area, "hist_total" for historical cropmix on total cropland, or selection of proxycrops)

Water transport distance allowed to fulfill locally unfulfilled water demand by surrounding cell water availability

If TRUE: non-renewable groundwater can be used. If FALSE: non-renewable groundwater cannot be used.

if TRUE: the currently already irrigated areas in initialization year are reserved for irrigation, if FALSE: no irrigation areas reserved (irrigation potential)

Multicropping activated (TRUE) or not (FALSE) and Multiple Cropping Suitability mask selected (mask can be: "none": no mask applied (only for development purposes) "actual:total": currently multicropped areas calculated from total harvested areas and total physical areas per cell from readLandInG "actual:crop" (crop-specific), "actual:irrigation" (irrigation-specific), "actual:irrig_crop" (crop- and irrigation-specific) "total" "potential:endogenous": potentially multicropped areas given temperature and productivity limits "potential:exogenous": potentially multicropped areas given GAEZ suitability classification) (e.g. TRUE:actual:total; TRUE:none; FALSE)

LPJmL version used

Years for which irrigatable area is calculated

Switch between different climate scenarios or historical baseline "GSWP3-W5E5:historical"

EFR method used including selected strictness of EFRs (e.g. Smakhtin:good, VMF:fair)

Water transport distance allowed to fulfill locally unfulfilled water demand

Strictness of accessibility restriction: discharge that is exceeded x percent of the time on average throughout a year (Qx). (e.g. Q75: 0.25, Q50: 0.5)

Rank and optimization method consisting of Unit according to which rank is calculated: USD_ha (USD per hectare) for relative area return, or USD_m3 (USD per cubic meter) for relative volumetric return; USD for absolute return (total profit); Price aggregation: "GLO" for global average prices, or "ISO" for country-level prices and boolean indicating fullpotential (TRUE, i.e. cell receives full irrigation requirements in total area) or reduced potential (FALSE, reduced potential of cell receives at later stage in allocation algorithm); separated by ":"

If TRUE: LPJmL yields calibrated to FAO country yield in iniyear Also needs specification of refYields, separated by ":". Options: FALSE (for single cropping analyses) or "TRUE:actual:irrig_crop" (for multiple cropping analyses) If FALSE: uncalibrated LPJmL yields are used

Rule to be applied for river basin discharge allocation across cells of river basin ("optimization", "upstreamfirst", "equality")

Threshold of yield improvement potential required (in USD per hectare)

Irrigation system used ("surface", "sprinkler", "drip", "initialization")

Initialization year of irrigation system

Land availability scenario consisting of two parts separated by ":": 1. available land scenario (currCropland, currIrrig, potCropland) 2. protection scenario (WDPA, or one of the scenarios available in calcConservationPriorities, e.g., 30by20, BH, BH_IFL, PBL_HalfEarth, or NA for no protection). For case of no land protection select "NA" in second part of argument or do not specify second part of the argument

Selected cropmix (options: "hist_irrig" for historical cropmix on currently irrigated area, "hist_total" for historical cropmix on total cropland, or selection of proxycrops)

If TRUE: currently already irrigated areas in initialization year are reserved for irrigation, if FALSE: no irrigation areas reserved (irrigation potential)

Multicropping activated (TRUE) or not (FALSE) and Multiple Cropping Suitability mask selected (mask can be: "none": no mask applied (only for development purposes) "actual:total": currently multicropped areas calculated from total harvested areas and total physical areas per cell from readLandInG "actual:crop" (crop-specific), "actual:irrigation" (irrigation-specific), "actual:irrig_crop" (crop- and irrigation-specific) "total" "potential:endogenous": potentially multicropped areas given temperature and productivity limits "potential:exogenous": potentially multicropped areas given GAEZ suitability classification) (e.g. TRUE:actual:total; TRUE:none; FALSE)

Combination of EFP ("on", "off") and non-ag. water use scenario ("ssp2", "ISIMIP", ...) separated by "."

If TRUE: cellular data returned. If FALSE: aggregated to basins

LPJmL version used

Years to be returned (Note: does not affect years of harmonization or smoothing)

Switch between different climate scenarios or historical baseline "GSWP3-W5E5:historical"

EFR method used including selected strictness of EFRs (Smakhtin:good, VMF:fair)

LPJmL version used

Years to be returned (Note: does not affect years of harmonization or smoothing)

Switch between different climate scenarios or historical baseline "GSWP3-W5E5:historical"

EFR method used including selected strictness of EFRs (Smakhtin:good, VMF:fair)

Method used: Quantile method (Q) or Coefficient of Variation (CV) combined with scalar value defining the strictness of accessibility restriction: discharge that is exceeded x percent of the time on average throughout a year (Qx, e.g. Q75: 0.25, Q50: 0.5) or base value for exponential curve separated by : (CV:2)

LPJmL version used for monthly discharge

Switch between different climate scenarios or historical baseline "GSWP3-W5E5:historical"

EFR method used including selected strictness of EFRs (e.g. Smakhtin:good, VMF:fair, PB:Rockstroem)

LPJmL version used

Climate model or historical baseline "GSWP3-W5E5:historical"

Years to be returned

Croparea initialization year

if !NULL: already irrigated area is subtracted; if NULL: total potential land area is used; year specified here is the year of the initialization used for cropland area initialization in calcIrrigatedArea

Irrigation system used: system share as in initialization year, or drip, surface, sprinkler for full irrigation by selected system

Land availability scenario consisting of two parts separated by ":": 1. available land scenario (currCropland, currIrrig, potCropland) 2. protection scenario (WDPA, or one of the scenarios available in calcConservationPriorities, e.g., 30by20, BH, BH_IFL, PBL_HalfEarth, or NA for no protection). For case of no land protection select "NA" in second part of argument or do not specify second part of the argument

Selected cropmix (options: "hist_irrig" for historical cropmix on currently irrigated area, "hist_total" for historical cropmix on total cropland, or selection of proxycrops)

Multicropping activated (TRUE) or not (FALSE) and Multiple Cropping Suitability mask selected (mask can be: "none": no mask applied (only for development purposes) "actual:total": currently multicropped areas calculated from total harvested areas and total physical areas per cell from readLandInG "actual:crop" (crop-specific), "actual:irrigation" (irrigation-specific), "actual:irrig_crop" (crop- and irrigation-specific) "total" "potential:endogenous": potentially multicropped areas given temperature and productivity limits "potential:exogenous": potentially multicropped areas given GAEZ suitability classification) (e.g. TRUE:actual:total; TRUE:none; FALSE)

Years to be returned

LPJmL version required for respective inputs: natveg or crop

Switch between different climate scenarios or historical baseline "GSWP3-W5E5:historical"

"wholeYear": grass et in the entire year (main + off season) "mainSeason": grass etP in the crop-specific growing period of LPJmL (main season)

Defines LPJmL version for crop/grass and natveg specific inputs

Switch between different climate scenarios

Degree of processing: raw, smoothed, harmonized, harmonized2020

threshold for cell yield over global average. crops in cells below threshold will be ignored

Number of cells to be returned (select "magpiecell" for 59199 cells or "lpjcell" for 67420 cells)

LPJmL version used

Switch between different climate scenarios or historical baseline "GSWP3-W5E5:historical"

Years to be returned (Note: does not affect years of harmonization or smoothing)

Initialization year of irrigation system

EFR method used including selected strictness of EFRs (Smakhtin:good, VMF:fair)

If TRUE: non-renewable groundwater can be used. If FALSE: non-renewable groundwater cannot be used.

Multicropping activated (TRUE) or not (FALSE) and Multiple Cropping Suitability mask selected (mask can be: "none": no mask applied (only for development purposes) "actual:total": currently multicropped areas calculated from total harvested areas and total physical areas per cell from readLandInG "actual:crop" (crop-specific), "actual:irrigation" (irrigation-specific), "actual:irrig_crop" (crop- and irrigation-specific) "total" "potential:endogenous": potentially multicropped areas given temperature and productivity limits "potential:exogenous": potentially multicropped areas given GAEZ suitability classification) (e.g. TRUE:actual:total; TRUE:none; FALSE)

Water transport distance allowed to fulfill locally unfulfilled water demand by surrounding cell water availability

select years

initialization year

years for which irrigatable area is calculated

initialization year

Land availability scenario consisting of two parts separated by ":": 1. available land scenario (currCropland, currIrrig, potCropland) 2. protection scenario (WDPA, or one of the scenarios available in calcConservationPriorities, e.g., 30by20, BH, BH_IFL, PBL_HalfEarth, or NA for no protection). For case of no land protection select "NA" in second part of argument or do not specify second part of the argument

LPJmL version required for respective inputs: natveg or crop

Switch between different climate scenarios or historical baseline "GSWP3-W5E5:historical"

Selected cropmix (options: "hist_irrig" for historical cropmix on currently irrigated area, "hist_total" for historical cropmix on total cropland, or selection of proxycrops)

If TRUE: LPJmL yields calibrated to FAO country yield in iniyear Also needs specification of refYields, separated by ":". Options: FALSE (for single cropping analyses) or "TRUE:actual:irrig_crop" (for multiple cropping analyses) If FALSE: uncalibrated LPJmL yields are used

Irrigation system used: system share as in initialization year, or drip, surface, sprinkler for full irrigation by selected system

Unit of yield improvement potential to be returned and level of price aggregation used, separated by ":". Unit: USD_ha (USD per hectare) for relative area return, or USD_m3 (USD per cubic meter) for relative volumetric return; USD for absolute return (total profit); Price aggregation: "GLO" for global average prices, or "ISO" for country-level prices

Threshold of yield improvement potential (in USD per hectare)

Multicropping activated (TRUE) or not (FALSE)

Data source to be used: Jaegermeyr (irrigation system share based on FAO 2014, ICID 2012 and Rohwer et al. 2007) or LPJmL (dominant irrigation system per country)

LPJmL version used for yields

Switch between different climate scenarios or historical baseline "GSWP3-W5E5:historical" for yields

Year(s) for which cell rank is calculated

Initialization year for price

if !NULL: already irrigated area is subtracted; if NULL: total potential land area is used; year specified here is the year of the initialization used for cropland area initialization in calcIrrigatedArea

Irrigation system used: system share as in initialization year, or drip, surface, sprinkler for full irrigation by selected system

Land availability scenario consisting of two parts separated by ":": 1. available land scenario (currCropland, currIrrig, potCropland) 2. protection scenario (WDPA, or one of the scenarios available in calcConservationPriorities, e.g., 30by20, BH, BH_IFL, PBL_HalfEarth, or NA for no protection). For case of no land protection select "NA" in second part of argument or do not specify second part of the argument

Rank and optimization method consisting of Unit according to which rank is calculated: tDM (tons per dry matter), USD_ha (USD per hectare) for relative area return, or USD_m3 (USD per cubic meter) for relative volumetric return; USD for absolute return (total profit); Price aggregation: "GLO" for global average prices, or "ISO" for country-level prices; and boolean indicating fullpotential (TRUE) or reduced potential (FALSE)

Selected cropmix for which yield improvement potential is calculated (options: "hist_irrig" for historical cropmix on currently irrigated area, "hist_total" for historical cropmix on total cropland, or selection of proxycrops) NULL returns all crops individually

If TRUE: LPJmL yields calibrated to FAO country yield in iniyear Also needs specification of refYields, separated by ":". Options: FALSE (for single cropping analyses) or "TRUE:actual:irrig_crop" (for multiple cropping analyses) If FALSE: uncalibrated LPJmL yields are used

Multicropping activated (TRUE) or not (FALSE)

LPJmL version used for yields

Climate scenarios or historical baseline "GSWP3-W5E5:historical"

Price aggregation: "GLO" for global average prices, or "ISO" for country-level prices, or "CONST" for same price for all crops

initialization year for food price and cropmix area

Years to be returned by the function

If TRUE: LPJmL yields calibrated to FAO country yield in iniyear Also needs specification of refYields, separated by ":". Options: FALSE (for single cropping analyses) or "TRUE:actual:irrig_crop" (for multiple cropping analyses) If FALSE: uncalibrated LPJmL yields are used

Multicropping activated (TRUE) or not (FALSE)

Year to be used for irrigation system share initialization

Years to be returned

LPJmL version required for respective inputs: natveg or crop

Climate model or historical baseline "GSWP3-W5E5:historical"

Multicropping activated (TRUE) or not (FALSE) and Multiple Cropping Suitability mask selected (mask can be: "none": no mask applied (only for development purposes) "actual:total": currently multicropped areas calculated from total harvested areas and total physical areas per cell from LandInG "actual:crop" (crop-specific), "actual:irrigation" (irrigation-specific), "actual:irrig_crop" (crop- and irrigation-specific) "total" "potential:endogenous": potentially multicropped areas given temperature and productivity limits "potential:exogenous": potentially multicropped areas given GAEZ suitability classification) (e.g. TRUE:actual:total; TRUE:none; FALSE)

LPJmL version used for yields

Climate scenarios or historical baseline "GSWP3-W5E5:historical"

Unit of yield improvement potential to be returned and level of price aggregation used, separated by ":". Unit: USD_ha (USD per hectare) for relative area return, or USD_m3 (USD per cubic meter) for relative volumetric return; USD for absolute return (total profit); for relative return according to area and volume. Price aggregation: "GLO" for global average prices, or "ISO" for country-level prices

initialization year for food price and cropmix area

Years to be returned by the function

if !NULL: already irrigated area is subtracted; if NULL: total potential land area is used; year specified here is the year of the initialization used for cropland area initialization in calcIrrigatedArea

Selected cropmix for which yield improvement potential is calculated (options: "hist_irrig" for historical cropmix on currently irrigated area, "hist_total" for historical cropmix on total cropland, or selection of proxycrops) NULL returns all crops individually

Land availability scenario consisting of two parts separated by ":": 1. available land scenario (currCropland, currIrrig, potCropland) 2. protection scenario (WDPA, or one of the scenarios available in calcConservationPriorities, e.g., 30by20, BH, BH_IFL, PBL_HalfEarth, or NA for no protection). For case of no land protection select "NA" in second part of argument or do not specify second part of the argument

Irrigation system used: system share as in initialization year, or drip, surface, sprinkler for full irrigation by selected system

If TRUE: LPJmL yields calibrated to FAO country yield in iniyear Also needs specification of refYields, separated by ":". Options: FALSE (for single cropping analyses) or "TRUE:actual:irrig_crop" (for multiple cropping analyses) If FALSE: uncalibrated LPJmL yields are used

Multicropping activated (TRUE) or not (FALSE)

sector to be reported: non-agricultural sector water use ("nonAg"), (committed) agricultural water use ("comAg"), or both ("total")

LPJmL version used

Switch between different climate scenarios or historical baseline "GSWP3-W5E5:historical"

Water transport distance allowed to fulfill locally unfulfilled water demand by surrounding cell water availability to determine missing water that is tagged as non-renewable groundwater

Multicropping activated (TRUE) or not (FALSE) and Multiple Cropping Suitability mask selected (mask can be: "none": no mask applied (only for development purposes) "actual:total": currently multicropped areas calculated from total harvested areas and total physical areas per cell from LandInG "actual:crop" (crop-specific), "actual:irrigation" (irrigation-specific), "actual:irrig_crop" (crop- and irrigation-specific) "total" "potential:endogenous": potentially multicropped areas given temperature and productivity limits "potential:exogenous": potentially multicropped areas given GAEZ suitability classification) (e.g. TRUE:actual:total; TRUE:none; FALSE)

Years to be returned

Initialization year

"total": total groundwater use (non-agricultural and agricultural), "nonAg": groundwater use in non-agricultural sector (industry, domestic, electricity), "comAg": groundwater use in agricultural sector (currently irrigated area)

LPJmL version used

Switch between different climate scenarios or historical baseline "GSWP3-W5E5:historical"

Water transport distance allowed to fulfill locally unfulfilled water demand by surrounding cell water availability to determine missing water that is tagged as non-renewable groundwater

Multicropping activated (TRUE) or not (FALSE) and Multiple Cropping Suitability mask selected (mask can be: "none": no mask applied (only for development purposes) "actual:total": currently multicropped areas calculated from total harvested areas and total physical areas per cell from LandInG "actual:crop" (crop-specific), "actual:irrigation" (irrigation-specific), "actual:irrig_crop" (crop- and irrigation-specific) "total" "potential:endogenous": potentially multicropped areas given temperature and productivity limits "potential:exogenous": potentially multicropped areas given GAEZ suitability classification) (e.g. TRUE:actual:total; TRUE:none; FALSE)

Years to be returned

Initialization year

TRUE (aggregated Potentially Irrigated Areas (PIAs)), FALSE (crop-specific PIAs)

LPJmL version used

Switch between different climate scenarios or historical baseline "GSWP3-W5E5:historical"

Years for which irrigatable area is calculated

Initialization year for initial croparea

EFR method used including selected strictness of EFRs (e.g. Smakhtin:good, VMF:fair)

Strictness of accessibility restriction: discharge that is exceeded x percent of the time on average throughout a year (Qx). (e.g. Q75: 0.25, Q50: 0.5)

Rank and optimization method consisting of Unit according to which rank is calculated: USD_ha (USD per hectare) for relative area return, or USD_m3 (USD per cubic meter) for relative volumetric return; USD for absolute return (total profit); Price aggregation: "GLO" for global average prices, or "ISO" for country-level prices and boolean indicating fullpotential (TRUE, i.e. cell receives full irrigation requirements in total area) or reduced potential (FALSE, reduced potential of cell receives at later stage in allocation algorithm); separated by ":"

If TRUE: LPJmL yields calibrated to FAO country yield in iniyear Also needs specification of refYields, separated by ":". Options: FALSE (for single cropping analyses) or "TRUE:actual:irrig_crop" (for multiple cropping analyses) If FALSE: uncalibrated LPJmL yields are used

Rule to be applied for river basin discharge allocation across cells of river basin ("optimization", "upstreamfirst", "equality")

Threshold of yield improvement potential required (in USD per hectare)

Irrigation system used ("surface", "sprinkler", "drip", "initialization")

Land availability scenario consisting of two parts separated by ":": 1. available land scenario (currCropland, currIrrig, potCropland) 2. protection scenario (WDPA, or one of the scenarios available in calcConservationPriorities, e.g., 30by20, BH, BH_IFL, PBL_HalfEarth, or NA for no protection). For case of no land protection select "NA" in second part of argument or do not specify second part of the argument

Selected cropmix (options: "hist_irrig" for historical cropmix on currently irrigated area, "hist_total" for historical cropmix on total cropland, or selection of proxycrops)

If TRUE: currently already irrigated areas in initialization year are reserved for irrigation, if FALSE: no irrigation areas reserved (irrigation potential)

If TRUE: non-renewable groundwater can be used. If FALSE: non-renewable groundwater cannot be used.

Multicropping activated (TRUE) or not (FALSE) and Multiple Cropping Suitability mask selected (mask can be: "none": no mask applied (only for development purposes) "actual:total": currently multicropped areas calculated from total harvested areas and total physical areas per cell from LandInG "actual:crop" (crop-specific), "actual:irrigation" (irrigation-specific), "actual:irrig_crop" (crop- and irrigation-specific) "total" "potential:endogenous": potentially multicropped areas given temperature and productivity limits "potential:exogenous": potentially multicropped areas given GAEZ suitability classification) (e.g. TRUE:actual:total; TRUE:none; FALSE)

Water transport distance allowed to fulfill locally unfulfilled water demand by surrounding cell water availability

EFP and non-agricultural water use scenario separated with a "." (e.g. "on.ssp2")

LPJmL version used

Switch between different climate scenarios or historical baseline "GSWP3-W5E5:historical"

Years for which irrigatable area is calculated

Initialization year for initial croparea

EFR method used including selected strictness of EFRs (e.g. Smakhtin:good, VMF:fair)

Strictness of accessibility restriction: discharge that is exceeded x percent of the time on average throughout a year (Qx). (e.g. Q75: 0.25, Q50: 0.5)

Rank and optimization method consisting of Unit according to which rank is calculated: USD_ha (USD per hectare) for relative area return, or USD_m3 (USD per cubic meter) for relative volumetric return; USD for absolute return (total profit); Price aggregation: "GLO" for global average prices, or "ISO" for country-level prices and boolean indicating fullpotential (TRUE, i.e. cell receives full irrigation requirements in total area) or reduced potential (FALSE, reduced potential of cell receives at later stage in allocation algorithm); separated by ":"

If TRUE: LPJmL yields calibrated to FAO country yield in iniyear Also needs specification of refYields, separated by ":". Options: FALSE (for single cropping analyses) or "TRUE:actual:irrig_crop" (for multiple cropping analyses) If FALSE: uncalibrated LPJmL yields are used

Rule to be applied for river basin discharge allocation across cells of river basin ("optimization", "upstreamfirst", "equality")

Threshold of yield improvement potential required (in USD per hectare)

Irrigation system used ("surface", "sprinkler", "drip", "initialization")

Land availability scenario consisting of two parts separated by ":": 1. available land scenario (currCropland, currIrrig, potCropland) 2. protection scenario (WDPA, or one of the scenarios available in calcConservationPriorities, e.g., 30by20, BH, BH_IFL, PBL_HalfEarth, or NA for no protection). For case of no land protection select "NA" in second part of argument or do not specify second part of the argument

Selected cropmix (options: "hist_irrig" for historical cropmix on currently irrigated area, "hist_total" for historical cropmix on total cropland, or selection of proxycrops)

If TRUE: currently already irrigated areas in initialization year are reserved for irrigation, if FALSE: no irrigation areas reserved (irrigation potential)

If TRUE: non-renewable groundwater can be used. If FALSE: non-renewable groundwater cannot be used.

Multicropping activated (TRUE) or not (FALSE) and Multiple Cropping Suitability mask selected (mask can be: "none": no mask applied (only for development purposes) "actual:total": currently multicropped areas calculated from total harvested areas and total physical areas per cell from LandInG "actual:crop" (crop-specific), "actual:irrigation" (irrigation-specific), "actual:irrig_crop" (crop- and irrigation-specific) "total" "potential:endogenous": potentially multicropped areas given temperature and productivity limits "potential:exogenous": potentially multicropped areas given GAEZ suitability classification) (e.g. TRUE:actual:total; TRUE:none; FALSE)

Water transport distance allowed to fulfill locally unfulfilled water demand by surrounding cell water availability

LPJmL version used

Years for which irrigatable area is calculated

Switch between different climate scenarios or historical baseline "GSWP3-W5E5:historical"

EFR method used including selected strictness of EFRs (e.g. Smakhtin:good, VMF:fair)

Strictness of accessibility restriction: discharge that is exceeded x percent of the time on average throughout a year (Qx). (e.g. Q75: 0.25, Q50: 0.5)

Rank and optimization method consisting of Unit according to which rank is calculated: USD_ha (USD per hectare) for relative area return, or USD_m3 (USD per cubic meter) for relative volumetric return; USD for absolute return (total profit); Price aggregation: "GLO" for global average prices, or "ISO" for country-level prices and boolean indicating fullpotential (TRUE, i.e. cell receives full irrigation requirements in total area) or reduced potential (FALSE, reduced potential of cell receives at later stage in allocation algorithm); separated by ":"

If TRUE: LPJmL yields calibrated to FAO country yield in iniyear Also needs specification of refYields, separated by ":". Options: FALSE (for single cropping analyses) or "TRUE:actual:irrig_crop" (for multiple cropping analyses) If FALSE: uncalibrated LPJmL yields are used

Rule to be applied for river basin discharge allocation across cells of river basin ("optimization", "upstreamfirst", "equality")

Threshold of yield improvement potential required (in USD per hectare)

Irrigation system used ("surface", "sprinkler", "drip", "initialization")

Initialization year of irrigation system

Land availability scenario consisting of two parts separated by ":": 1. available land scenario (currCropland, currIrrig, potCropland) 2. protection scenario (WDPA, or one of the scenarios available in calcConservationPriorities, e.g., 30by20, BH, BH_IFL, PBL_HalfEarth, or NA for no protection). For case of no land protection select "NA" in second part of argument or do not specify second part of the argument

Selected cropmix (options: "hist_irrig" for historical cropmix on currently irrigated area, "hist_total" for historical cropmix on total cropland, or selection of proxycrops)

If TRUE: currently already irrigated areas in initialization year are reserved for irrigation, if FALSE: no irrigation areas reserved (irrigation potential)

If TRUE: non-renewable groundwater can be used. If FALSE: non-renewable groundwater cannot be used.

Multicropping activated (TRUE) or not (FALSE) and Multiple Cropping Suitability mask selected ("endogenous": suitability for multiple cropping determined by rules based on grass and crop productivity "exogenous": suitability for multiple cropping given by GAEZ data set), separated by ":" (e.g. TRUE:endogenous; TRUE:exogenous; FALSE)

Water transport distance allowed to fulfill locally unfulfilled water demand by surrounding cell water availability

LPJmL version used

Switch between different climate scenarios or historical baseline "GSWP3-W5E5:historical"

Years to be returned (Note: does not affect years of harmonization or smoothing)

EFR method used including selected strictness of EFRs (e.g. Smakhtin:good, VMF:fair)

Method used: Quantile method (Q) or Coefficient of Variation (CV) combined with scalar value defining the strictness of accessibility restriction: discharge that is exceeded x percent of the time on average throughout a year (Qx, e.g. Q75: 0.25, Q50: 0.5) or base value for exponential curve separated by : (CV:2)

Water transport distance allowed to fulfill locally unfulfilled water demand

Rank and optimization method consisting of Unit according to which rank is calculated: USD_ha (USD per hectare) for relative area return, or USD_m3 (USD per cubic meter) for relative volumetric return; USD for absolute return (total profit); Price aggregation: "GLO" for global average prices, or "ISO" for country-level prices and boolean indicating fullpotential (TRUE, i.e. cell receives full irrigation requirements in total area) or reduced potential (FALSE, reduced potential of cell receives at later stage in allocation algorithm); separated by ":"

If TRUE: LPJmL yields calibrated to FAO country yield in iniyear Also needs specification of refYields, separated by ":". Options: FALSE (for single cropping analyses) or "TRUE:actual:irrig_crop" (for multiple cropping analyses) If FALSE: uncalibrated LPJmL yields are used

Rule to be applied for river basin discharge allocation ("optimization" or "upstreamfirst")

Threshold of yield improvement potential (in USD per hectare)

Irrigation system to be used for river basin discharge allocation algorithm ("surface", "sprinkler", "drip", "initialization")

Initialization year of irrigation system

Land availability scenario consisting of two parts separated by ":": 1. available land scenario (currCropland, currIrrig, potCropland) 2. protection scenario (WDPA, or one of the scenarios available in calcConservationPriorities, e.g., 30by20, BH, BH_IFL, PBL_HalfEarth, or NA for no protection). For case of no land protection select "NA" in second part of argument or do not specify second part of the argument

Selected cropmix (options: "hist_irrig" for historical cropmix on currently irrigated area, "hist_total" for historical cropmix on total cropland, or selection of proxycrops)

if TRUE: the currently already irrigated areas in initialization year are reserved for irrigation, if FALSE: no irrigation areas reserved (irrigation potential)

Multicropping activated (TRUE) or not (FALSE) and Multiple Cropping Suitability mask selected (mask can be: "none": no mask applied (only for development purposes) "actual:total": currently multicropped areas calculated from total harvested areas and total physical areas per cell from LandInG "actual:crop" (crop-specific), "actual:irrigation" (irrigation-specific), "actual:irrig_crop" (crop- and irrigation-specific) "total" "potential:endogenous": potentially multicropped areas given temperature and productivity limits "potential:exogenous": potentially multicropped areas given GAEZ suitability classification) (e.g. TRUE:actual:total; TRUE:none; FALSE)

Water use to be allocated in this river routing iteration (non_agriculture, committed_agriculture, committed_agriculture_fullMulticropping, potential_irrigation,

LPJmL version used

Switch between different climate scenarios or historical baseline "GSWP3-W5E5:historical"

Years to be returned (Note: does not affect years of harmonization or smoothing)

Initialization year of irrigation system

EFR method used including selected strictness of EFRs (Smakhtin:good, VMF:fair)

Multicropping activated (TRUE) or not (FALSE) and Multiple Cropping Suitability mask selected (mask can be: "none": no mask applied (only for development purposes) "actual:total": currently multicropped areas calculated from total harvested areas and total physical areas per cell from LandInG "actual:crop" (crop-specific), "actual:irrigation" (irrigation-specific), "actual:irrig_crop" (crop- and irrigation-specific) "total" "potential:endogenous": potentially multicropped areas given temperature and productivity limits "potential:exogenous": potentially multicropped areas given GAEZ suitability classification) (e.g. TRUE:actual:total; TRUE:none; FALSE)

Water transport distance allowed to fulfill locally unfulfilled water demand by surrounding cell water availability

if TRUE: the currently already irrigated areas in initialization year are reserved for irrigation, if FALSE: no irrigation areas reserved (irrigation potential). Only relevant for iteration = potential

(For case of iteration = "potential_irrigation" only:) Method used: Quantile method (Q) or Coefficient of Variation (CV) combined with scalar value defining the strictness of accessibility restriction: discharge that is exceeded x percent of the time on average throughout a year (Qx, e.g. Q75: 0.25, Q50: 0.5) or base value for exponential curve separated by : (CV:2)

Rank and optimization method consisting of Unit according to which rank is calculated: USD_ha (USD per hectare) for relative area return, or USD_m3 (USD per cubic meter) for relative volumetric return; USD for absolute return (total profit); Price aggregation: "GLO" for global average prices, or "ISO" for country-level prices and boolean indicating fullpotential (TRUE, i.e. cell receives full irrigation requirements in total area) or reduced potential (FALSE, reduced potential of cell receives at later stage in allocation algorithm); separated by ":"

(For case of iteration = "potential_irrigation" only:) Threshold of yield improvement potential (same unit as in rankmethod)

(For case of iteration = "potential_irrigation" only:) Selected cropmix (options: "hist_irrig" for historical cropmix on currently irrigated area, "hist_total" for historical cropmix on total cropland, or selection of proxycrops)

(For case of iteration = "potential_irrigation" only:) If TRUE: LPJmL yields calibrated to FAO country yield in iniyear Also needs specification of refYields, separated by ":". Options: FALSE (for single cropping analyses) or "TRUE:actual:irrig_crop" (for multiple cropping analyses) If FALSE: uncalibrated LPJmL yields are used

(For case of iteration = "potential_irrigation" only:) Irrigation system to be used for river basin discharge allocation algorithm ("surface", "sprinkler", "drip", "initialization")

Land availability scenario consisting of two parts separated by ":": 1. available land scenario (currCropland, currIrrig, potCropland) 2. protection scenario (WDPA, or one of the scenarios available in calcConservationPriorities, e.g., 30by20, BH, BH_IFL, PBL_HalfEarth, or NA for no protection). For case of no land protection select "NA" in second part of argument or do not specify second part of the argument

Years to be returned (Note: does not affect years of harmonization or smoothing)

LPJmL version used

Switch between different climate scenarios or historical baseline "GSWP3-W5E5:historical"

LPJmL version used

Switch between different climate scenarios or historical baseline "GSWP3-W5E5:historical"

Years to be returned (Note: does not affect years of harmonization or smoothing)

Initialization year of irrigation system

Water use to be allocated in this river routing iteration (non_agriculture, committed_agriculture, potential_irrigation, committed_agriculture_fullMulticropping).

Water transport distance allowed to fulfill locally unfulfilled water demand by surrounding cell water availability

EFR method used including selected strictness of EFRs (e.g. Smakhtin:good, VMF:fair)

Water accessibility rule. Available methods: Quantile method (Q) or Coefficient of Variation (CV); combined with scalar value defining the strictness of accessibility restriction: discharge that is exceeded x percent of the time on average throughout a year (Qx, e.g. Q75: 0.25, Q50: 0.5) or base value for exponential curve separated by : (CV:2)

Multicropping activated (TRUE) or not (FALSE) and Multiple Cropping Suitability mask selected (mask can be: "none": no mask applied (only for development purposes) "actual:total": currently multicropped areas calculated from total harvested areas and total physical areas per cell from LandInG "actual:crop" (crop-specific), "actual:irrigation" (irrigation-specific), "actual:irrig_crop" (crop- and irrigation-specific) "total" "potential:endogenous": potentially multicropped areas given temperature and productivity limits "potential:exogenous": potentially multicropped areas given GAEZ suitability classification) (e.g. TRUE:actual:total; TRUE:none; FALSE)

if TRUE: the currently already irrigated areas in initialization year are reserved for irrigation, if FALSE: no irrigation areas reserved (irrigation potential). Only relevant for iteration = potential

Rank and optimization method consisting of Unit according to which rank is calculated: USD_ha (USD per hectare) for relative area return, or USD_m3 (USD per cubic meter) for relative volumetric return; USD for absolute return (total profit); Price aggregation: "GLO" for global average prices, or "ISO" for country-level prices and boolean indicating fullpotential (TRUE, i.e. cell receives full irrigation requirements in total area) or reduced potential (FALSE, reduced potential of cell receives at later stage in allocation algorithm); separated by ":"

Threshold of yield improvement potential (in USD per hectare)

Selected cropmix (options: "hist_irrig" for historical cropmix on currently irrigated area, "hist_total" for historical cropmix on total cropland, or selection of proxycrops)

If TRUE: LPJmL yields calibrated to FAO country yield in iniyear Also needs specification of refYields, separated by ":". Options: FALSE (for single cropping analyses) or "TRUE:actual:irrig_crop" (for multiple cropping analyses) If FALSE: uncalibrated LPJmL yields are used

Irrigation system to be used for river basin discharge allocation algorithm ("surface", "sprinkler", "drip", "initialization")

Land availability scenario consisting of two parts separated by ":": 1. available land scenario (currCropland, currIrrig, potCropland) 2. protection scenario (WDPA, or one of the scenarios available in calcConservationPriorities, e.g., 30by20, BH, BH_IFL, PBL_HalfEarth, or NA for no protection). For case of no land protection select "NA" in second part of argument or do not specify second part of the argument

LPJmL version used

Switch between different climate scenarios or historical baseline "GSWP3-W5E5:historical"

Water transport distance allowed to fulfill locally unfulfilled water demand by surrounding cell water availability

Multicropping activated (TRUE) or not (FALSE) and Multiple Cropping Suitability mask selected (mask can be: "none": no mask applied (only for development purposes) "actual:total": currently multicropped areas calculated from total harvested areas and total physical areas per cell from LandInG "actual:crop" (crop-specific), "actual:irrigation" (irrigation-specific), "actual:irrig_crop" (crop- and irrigation-specific) "total" "potential:endogenous": potentially multicropped areas given temperature and productivity limits "potential:exogenous": potentially multicropped areas given GAEZ suitability classification) (e.g. TRUE:actual:total; TRUE:none; FALSE)

Years to be returned

Initialization year

EFR method used including selected strictness of EFRs (e.g. Smakhtin:good, VMF:fair)

Default: "committed_agriculture", Special case: "committed_agriculture_fullPotential". Special case should only be used for calculation of full multicropping potential committed agricultural area for case of Current Irrigation.

LPJmL version required for respective inputs: natveg or crop

Switch between different climate scenarios or historical baseline "GSWP3-W5E5:historical"

Years to be returned

Year of initialization for cropland area

Multicropping activated (TRUE) or not (FALSE) and Multiple Cropping Suitability mask selected (mask can be: "none": no mask applied (only for development purposes) "actual:total": currently multicropped areas calculated from total harvested areas and total physical areas per cell from LandInG "actual:crop" (crop-specific), "actual:irrigation" (irrigation-specific), "actual:irrig_crop" (crop- and irrigation-specific) "total" "potential:endogenous": potentially multicropped areas given temperature and productivity limits "potential:exogenous": potentially multicropped areas given GAEZ suitability classification) (e.g. TRUE:actual:total; TRUE:none; FALSE)

EFR method used including selected strictness of EFRs (e.g. Smakhtin:good, VMF:fair)

If TRUE: non-renewable groundwater can be used. If FALSE: non-renewable groundwater cannot be used.

Water transport distance allowed to fulfill locally unfulfilled water demand by surrounding cell water availability

LPJmL version required for respective inputs: natveg or crop

Switch between different climate scenarios or historical baseline "GSWP3-W5E5:historical"

Years to be returned

Year of initialization for cropland area

Multicropping activated (TRUE) or not (FALSE) and Multiple Cropping Suitability mask selected (mask can be: "none": no mask applied (only for development purposes) "actual:total": currently multicropped areas calculated from total harvested areas and total physical areas per cell from LandInG "actual:crop" (crop-specific), "actual:irrigation" (irrigation-specific), "actual:irrig_crop" (crop- and irrigation-specific) "total" "potential:endogenous": potentially multicropped areas given temperature and productivity limits "potential:exogenous": potentially multicropped areas given GAEZ suitability classification) (e.g. TRUE:actual:total; TRUE:none; FALSE)

Years to be returned

Number of cells to be returned (select "magpiecell" for 59199 cells or "lpjcell" for 67420 cells)

Data source to be used (e.g. WATERGAP2020)

water use types (domestic, industry, electricity) and option to return withdrawals or consumption separated by ":" (e.g. "all:withdrawal") options for first argument: "total" (returns the sum over different water use types) or "all" ( returns all water use types (domestic, industry, electricity)) options for second argument: "all", "withdrawal", "consumption"

grper (default): non-agricultural water demand in growing period per year; total: non-agricultural water demand throughout the year

Type of time smoothing: average (average over 8-year time span around baseline year) or spline (time smoothing using spline method with 4 degrees of freedom) or NULL (no smoothing)

Defines LPJmL version for crop/grass and natveg specific inputs

Switch between different climate scenarios for calcGrowingPeriod

Years to be returned (Note: does not affect years of harmonization or smoothing)

LPJmL version required for respective inputs: natveg or crop

Switch between different climate scenarios or historical baseline "GSWP3-W5E5:historical"

Range of gainthreshold for calculation of potentially irrigated areas (in USD per hectare)

LPJmL version required for respective inputs: natveg or crop

Years for which irrigatable area is calculated

Initialization year for cropland area

Switch between different climate scenarios or historical baseline "GSWP3-W5E5:historical"

If TRUE: LPJmL yields calibrated to FAO country yield in iniyear Also needs specification of refYields, separated by ":". Options: FALSE (for single cropping analyses) or "TRUE:actual:irrig_crop" (for multiple cropping analyses) If FALSE: uncalibrated LPJmL yields are used

Unit of yield improvement potential used as threshold, consisting of unit and price aggregation level separated by ":". Unit: tDM (tons per dry matter), USD_ha (USD per hectare) for area return, or USD_m3 (USD per cubic meter) for volumetric return. Price aggregation: "GLO" for global average prices, or "ISO" for country-level prices

Irrigation system used: system share as in initialization year, or drip, surface, sprinkler for full irrigation by selected system

Land availability scenario consisting of two parts separated by ":": 1. available land scenario (currCropland, currIrrig, potCropland) 2. protection scenario (WDPA, or one of the scenarios available in calcConservationPriorities, e.g., 30by20, BH, BH_IFL, PBL_HalfEarth, or NA for no protection). For case of no land protection select "NA" in second part of argument or do not specify second part of the argument

Selected cropmix (options: "hist_irrig" for historical cropmix on currently irrigated area, "hist_total" for historical cropmix on total cropland, or selection of proxycrops)

Multicropping activated (TRUE) or not (FALSE)

Non-agricultural water use and EFP scenario, separated by "." (e.g. "on.ssp2")

Years for which yield gain potential is calculated

Initialization year

LPJmL version used

Switch between different climate scenarios or historical baseline "GSWP3-W5E5:historical"

EFR method used including selected strictness of EFRs (e.g. Smakhtin:good, VMF:fair)

If TRUE: LPJmL yields calibrated to FAO country yield in iniyear Also needs specification of refYields, separated by ":". Options: FALSE (for single cropping analyses) or "TRUE:actual:irrig_crop" (for multiple cropping analyses) If FALSE: uncalibrated LPJmL yields are used

Irrigation system used ("surface", "sprinkler", "drip", "initialization")

Strictness of accessibility restriction: discharge that is exceeded x percent of the time on average throughout a year (Qx). (e.g. Q75: 0.25, Q50: 0.5)

Rank and optimization method consisting of Unit according to which rank is calculated: USD_ha (USD per hectare) for relative area return, or USD_m3 (USD per cubic meter) for relative volumetric return; USD for absolute return (total profit); Price aggregation: "GLO" for global average prices, or "ISO" for country-level prices and boolean indicating fullpotential (TRUE, i.e. cell receives full irrigation requirements in total area) or reduced potential (FALSE, reduced potential of cell receives at later stage in allocation algorithm); separated by ":"

Threshold of yield improvement potential required (in USD per hectare)

Rule to be applied for river basin discharge allocation across cells of river basin ("optimization", "upstreamfirst", "equality")

Water transport distance allowed to fulfill locally unfulfilled water demand by surrounding cell water availability

If TRUE: non-renewable groundwater can be used. If FALSE: non-renewable groundwater cannot be used.

Land availability scenario consisting of two parts separated by ":": 1. available land scenario (currCropland, currIrrig, potCropland) 2. protection scenario (WDPA, or one of the scenarios available in calcConservationPriorities, e.g., 30by20, BH, BH_IFL, PBL_HalfEarth, or NA for no protection). For case of no land protection select "NA" in second part of argument or do not specify second part of the argument

Selected cropmix (options: "hist_irrig" for historical cropmix on currently irrigated area, "hist_total" for historical cropmix on total cropland, or selection of proxycrops)

Multicropping activated (TRUE) or not (FALSE) and Multiple Cropping Suitability mask selected (mask can be: "none": no mask applied (only for development purposes) "actual:total": currently multicropped areas calculated from total harvested areas and total physical areas per cell from LandInG "actual:crop" (crop-specific), "actual:irrigation" (irrigation-specific), "actual:irrig_crop" (crop- and irrigation-specific) "total" "potential:endogenous": potentially multicropped areas given temperature and productivity limits "potential:exogenous": potentially multicropped areas given GAEZ suitability classification) (e.g. TRUE:actual:total; TRUE:none; FALSE)

TRUE: no water limitation to potentially irrigated area FALSE: irrigatable area limited by water availability

LPJmL version required for respective inputs: natveg or crop

Switch between different climate scenarios or historical baseline "GSWP3-W5E5:historical"

Years to be returned

Year of initialization for cropland area

Land availability scenario consisting of two parts separated by ":": 1. available land scenario (currCropland, currIrrig, potCropland) 2. protection scenario (WDPA, or one of the scenarios available in calcConservationPriorities, e.g., 30by20, BH, BH_IFL, PBL_HalfEarth, or NA for no protection). For case of no land protection select "NA" in second part of argument or do not specify second part of the argument

Selected cropmix (options: "hist_irrig" for historical cropmix on currently irrigated area, "hist_total" for historical cropmix on total cropland, or selection of proxycrops)

If TRUE: LPJmL yields calibrated to FAO country yield in iniyear Also needs specification of refYields, separated by ":". Options: FALSE (for single cropping analyses) or "TRUE:actual:irrig_crop" (for multiple cropping analyses) If FALSE: uncalibrated LPJmL yields are used

Multicropping activated (TRUE) or not (FALSE) and Multiple Cropping Suitability mask selected (mask can be: "none": no mask applied (only for development purposes) "actual:total": currently multicropped areas calculated from total harvested areas and total physical areas per cell from LandInG "actual:crop" (crop-specific), "actual:irrigation" (irrigation-specific), "actual:irrig_crop" (crop- and irrigation-specific) "total" "potential:endogenous": potentially multicropped areas given temperature and productivity limits "potential:exogenous": potentially multicropped areas given GAEZ suitability classification) (e.g. TRUE:actual:total; TRUE:none; FALSE)

Unit of yield improvement potential to be returned and level of price aggregation used, separated by ":". Unit: USD_ha (USD per hectare) for relative area return, or USD_m3 (USD per cubic meter) for relative volumetric return; USD for absolute return (total profit); Price aggregation: "GLO" for global average prices, or "ISO" for country-level prices

Irrigation system used: system share as in initialization year, or drip, surface, sprinkler for full irrigation by selected system

Range of gainthreshold for calculation of potentially irrigated areas (in USD per hectare)

LPJmL version used for yields

Climate scenarios or historical baseline "GSWP3-W5E5:historical"

Crop yield gain through multiple cropping under rainfed conditions "multicropping_rf", multiple cropping under irrigated conditions "multicropping_ir", irrigation under single cropping conditions "irrigation_singlecropping" irrigation and multiple cropping "irrigation_multicropping"

Price aggregation: "GLO" for global average prices, or "ISO" for country-level prices, or "CONST" for same price for all crops

initialization year for food price and cropmix area

Years to be returned by the function

Selected cropmix for which yield improvement potential is calculated (options: "hist_irrig" for historical cropmix on currently irrigated area, "hist_total" for historical cropmix on total cropland, or selection of proxycrops) NULL returns all crops individually

If TRUE: LPJmL yields calibrated to FAO country yield in iniyear Also needs specification of refYields, separated by ":". Options: FALSE (for single cropping analyses) or "TRUE:actual:irrig_crop" (for multiple cropping analyses) If FALSE: uncalibrated LPJmL yields are used

Multicropping activated (TRUE) or not (FALSE) and Multiple Cropping Suitability mask selected (mask can be: "none": no mask applied (only for development purposes) "actual:total": currently multicropped areas calculated from total harvested areas and total physical areas per cell from LandInG "actual:crop" (crop-specific), "actual:irrigation" (irrigation-specific), "actual:irrig_crop" (crop- and irrigation-specific) "total" "potential:endogenous": potentially multicropped areas given temperature and productivity limits "potential:exogenous": potentially multicropped areas given GAEZ suitability classification) (e.g. TRUE:actual:total; TRUE:none; FALSE)

LPJmL version used

Switch between different climate scenarios or historical baseline "GSWP3-W5E5:historical" for yields

Year to be used for cropland of yield calibration

Years to be returned by the function

If TRUE: LPJmL yields calibrated to FAO country yield in iniyear Also needs specification of refYields, separated by ":". Options: FALSE (for single cropping analyses) or "TRUE:actual:irrig_crop" (for multiple cropping analyses) If FALSE: uncalibrated LPJmL yields are used

Multicropping activated (TRUE) or not (FALSE) and Multiple Cropping Suitability mask selected (mask can be: "none": no mask applied (only for development purposes) "actual:total": currently multicropped areas calculated from total harvested areas and total physical areas per cell from LandInG "actual:crop" (crop-specific), "actual:irrigation" (irrigation-specific), "actual:irrig_crop" (crop- and irrigation-specific) "total" "potential:endogenous": potentially multicropped areas given temperature and productivity limits "potential:exogenous": potentially multicropped areas given GAEZ suitability classification) (e.g. TRUE:actual:total; TRUE:none; FALSE)

LPJmL version used for yields

Climate scenarios or historical baseline "GSWP3-W5E5:historical"

Price aggregation: "GLO" for global average prices, or "ISO" for country-level prices, or "CONST" for same price for all crops

initialization year for food price and cropmix area

Years to be returned by the function

If TRUE: LPJmL yields calibrated to FAO country yield in iniyear Also needs specification of refYields, separated by ":". Options: FALSE (for single cropping analyses) or "TRUE:actual:irrig_crop" (for multiple cropping analyses) If FALSE: uncalibrated LPJmL yields are used

Multicropping activated (TRUE) or not (FALSE) and Multiple Cropping Suitability mask selected (mask can be: "none": no mask applied (only for development purposes) "actual:total": currently multicropped areas calculated from total harvested areas and total physical areas per cell from LandInG "actual:crop" (crop-specific), "actual:irrigation" (irrigation-specific), "actual:irrig_crop" (crop- and irrigation-specific) "total" "potential:endogenous": potentially multicropped areas given temperature and productivity limits "potential:exogenous": potentially multicropped areas given GAEZ suitability classification) (e.g. TRUE:actual:total; TRUE:none; FALSE)

magpie object provided by the read function

MAgPIE object provided by the read function

MAgPIE object provided by the read function

If TRUE: LPJmL yields calibrated to FAO country yield in iniyear Also needs specification of refYields, separated by ":". Options: FALSE (for single cropping analyses) or "TRUE:actual:irrig_crop" (for multiple cropping analyses) If FALSE: uncalibrated LPJmL yields are used

Multicropping activated (TRUE) or not (FALSE) and Multiple Cropping Suitability mask selected ("endogenous": suitability for multiple cropping determined by rules based on grass and crop productivity "exogenous": suitability for multiple cropping given by GAEZ data set), separated by ":" (e.g. TRUE:endogenous; TRUE:exogenous; FALSE)

Rank and optimization method consisting of Unit according to which rank is calculated: USD_ha (USD per hectare) for relative area return, or USD_m3 (USD per cubic meter) for relative volumetric return; USD for absolute return (total profit); Price aggregation: "GLO" for global average prices, or "ISO" for country-level prices and boolean indicating fullpotential (TRUE, i.e. cell receives full irrigation requirements in total area) or reduced potential (FALSE, reduced potential of cell receives at later stage in allocation algorithm); separated by ":"

EFR method used including selected strictness of EFRs (Smakhtin:good, VMF:fair)

Method used: Quantile method (Q) or Coefficient of Variation (CV) combined with scalar value defining the strictness of accessibility restriction: discharge that is exceeded x percent of the time on average throughout a year (Qx, e.g. Q75: 0.25, Q50: 0.5) or base value for exponential curve separated by : (CV:2)

Water transport distance allowed to fulfill locally unfulfilled water demand by surrounding cell water availability

If TRUE: non-renewable groundwater can be used. If FALSE: non-renewable groundwater cannot be used.

Rule to be applied for river basin discharge allocation across cells of river basin ("optimization", "upstreamfirst")

Rank and optimization method consisting of Unit according to which rank is calculated: USD_ha (USD per hectare) for relative area return, or USD_m3 (USD per cubic meter) for relative volumetric return; USD for absolute return (total profit); Price aggregation: "GLO" for global average prices, or "ISO" for country-level prices and boolean indicating fullpotential (TRUE, i.e. cell receives full irrigation requirements in total area) or reduced potential (FALSE, reduced potential of cell receives at later stage in allocation algorithm); separated by ":"

Threshold of yield improvement potential required for water allocation in upstreamfirst algorithm (in same unit as in rankmethod)

Land protection scenario (WDPA, or one of the scenarios available in calcConservationPriorities, e.g., 30by20, BH, BH_IFL, PBL_HalfEarth, or NA for no protection).

If TRUE: LPJmL yields calibrated to FAO country yield in iniyear Also needs specification of refYields, separated by ":". Options: FALSE (for single cropping analyses) or "TRUE:actual:irrig_crop" (for multiple cropping analyses) If FALSE: uncalibrated LPJmL yields are used

Multicropping activated (TRUE) or not (FALSE) and Multiple Cropping Suitability mask selected (mask can be: "none": no mask applied (only for development purposes) "actual:total": currently multicropped areas calculated from total harvested areas and total physical areas per cell from LandInG "actual:crop" (crop-specific), "actual:irrigation" (irrigation-specific), "actual:irrig_crop" (crop- and irrigation-specific) "total" "potential:endogenous": potentially multicropped areas given temperature and productivity limits "potential:exogenous": potentially multicropped areas given GAEZ suitability classification) (e.g. TRUE:actual:total; TRUE:none; FALSE)

Selected cropmix (options: "hist_irrig" for historical cropmix on currently irrigated area, "hist_total" for historical cropmix on total cropland, or selection of proxycrops)

Switch between different climate scenarios or historical baseline "GSWP3-W5E5:historical"

LPJmL version required for respective inputs: natveg or crop

Rule to be applied for river basin discharge allocation across cells of river basin ("optimization", "upstreamfirst")

if TRUE: the currently already irrigated areas in initialization year are reserved for irrigation, if FALSE: no irrigation areas reserved (irrigation potential)

If TRUE: non-renewable groundwater can be used. If FALSE: non-renewable groundwater cannot be used.

Water transport distance allowed to fulfill locally unfulfilled water demand by surrounding cell water availability

Land protection scenario (WDPA, or one of the scenarios available in calcConservationPriorities, e.g., 30by20, BH, BH_IFL, PBL_HalfEarth, or NA for no protection

If TRUE: LPJmL yields calibrated to FAO country yield in iniyear Also needs specification of refYields, separated by ":". Options: FALSE (for single cropping analyses) or "TRUE:actual:irrig_crop" (for multiple cropping analyses) If FALSE: uncalibrated LPJmL yields are used

Multicropping activated (TRUE) or not (FALSE) and Multiple Cropping Suitability mask selected (mask can be: "none": no mask applied (only for development purposes) "actual:total": currently multicropped areas calculated from total harvested areas and total physical areas per cell from LandInG "actual:crop" (crop-specific), "actual:irrigation" (irrigation-specific), "actual:irrig_crop" (crop- and irrigation-specific) "total" "potential:endogenous": potentially multicropped areas given temperature and productivity limits "potential:exogenous": potentially multicropped areas given GAEZ suitability classification) (e.g. TRUE:actual:total; TRUE:none; FALSE)

Selected cropmix (options: "hist_irrig" for historical cropmix on currently irrigated area, "hist_total" for historical cropmix on total cropland, or selection of proxycrops)

Switch between different climate scenarios or historical baseline "GSWP3-W5E5:historical"

LPJmL version required for respective inputs: natveg or crop

Water transport distance allowed to fulfill locally unfulfilled water demand by surrounding cell water availability

If TRUE: non-renewable groundwater can be used. If FALSE: non-renewable groundwater cannot be used.

Rule to be applied for river basin discharge allocation across cells of river basin ("optimization", "upstreamfirst")

Rank and optimization method consisting of Unit according to which rank is calculated: USD_ha (USD per hectare) for relative area return, or USD_m3 (USD per cubic meter) for relative volumetric return; USD for absolute return (total profit); Price aggregation: "GLO" for global average prices, or "ISO" for country-level prices and boolean indicating fullpotential (TRUE, i.e. cell receives full irrigation requirements in total area) or reduced potential (FALSE, reduced potential of cell receives at later stage in allocation algorithm); separated by ":"

Multicropping activated (TRUE) or not (FALSE) and Multiple Cropping Suitability mask selected ("endogenous": suitability for multiple cropping determined by rules based on grass and crop productivity "exogenous": suitability for multiple cropping given by GAEZ data set), separated by ":" (e.g. TRUE:endogenous; TRUE:exogenous; FALSE)

Rank and optimization method consisting of Unit according to which rank is calculated: USD_ha (USD per hectare) for relative area return, or USD_m3 (USD per cubic meter) for relative volumetric return; USD for absolute return (total profit); Price aggregation: "GLO" for global average prices, or "ISO" for country-level prices and boolean indicating fullpotential (TRUE, i.e. cell receives full irrigation requirements in total area) or reduced potential (FALSE, reduced potential of cell receives at later stage in allocation algorithm); separated by ":"

Data source to be used: Jaegermeyr (irrigation system share based on FAO 2014, ICID 2012 and Rohwer et al. 2007) or LPJmL (dominant irrigation system per country)

Data source to be read from including path separated by ":", subtype separated by "."

Data to be read in: "systemShare": irrigation system share as provided in SI of Jägermeyr et al. (2015), based on FAO 2014, ICID 2012 and Rohwer et al. 2007); "systemSuitability": biophysical and technical irrigation system suitability by crop type (CFT) as provided in Table 2 of Jägermeyr et al. (2015) based on Sauer et al. (2010) and Fischer et al. (2012).

Data source to be read from

magpie object to be transformed

magpie object to be transformed

magpie object for which coordinatese should be remapped

direction of transformation (coord2lpj or lpj2coord)

River structure including information on neighboring cells

Water transport distance allowed to fulfill locally unfulfilled water demand by surrounding cell water availability

Vector of years for which neighbor allocation shall be applied

Vector of scenarios for which neighbor allocation shall be applied

List of arrays required for the algorithm: yearlyRunoff, lakeEvap reserved flows from previous water allocation round (prevReservedWC, prevReservedWW) missing water at this stage of water allocation (missingWW, missingWC) discharge

magpie object to be summed up over first dimension

regional resolution (can be country iso-code, "GLO" for global, or region name and respective mapping "EUR:H12")

River structure with information on upstreamcells, downstreamcells and neighboring cells and distances

Current cell for which water shall be allocated

Downstream cells of c

Currently active iteration of river discharge allocation. Arguments: "main" for case of main river cells "neighbor" for case of neighboring cells of main river cells

Water transport distance allowed to fulfill locally unfulfilled water demand by surrounding cell water availability

List of objects that are inputs to the function irrigGain, gainthreshold,

List of objects that are inputs to the function and are updated by the function

River structure

Array that contains (runoff - lake evap)

Array that contains water reserved for consumptive use

List of objects that are inputs to the function: previously reserved withdrawals and consumption in current cell; currently requested withdrawal in current cell

List of objects that are inputs to the function and are updated by the function: discharge (including up- and downstream cells) currently requested consumption (including upstream cells)

Water transport distance allowed to fulfill locally unfulfilled water demand

River structure list

List of neighboring cells for all river cells

river basin name as listed in mapping file RiverBasinMapping.csv