OVERVIEW

PLUM is a global-scale, socio-economic model of agricultural land use change. It is designed to allow efficient and powerful simulation of key processes in the land system for both human activity and the biophysical environment. The concept of the model is based on the understanding that changes in land use occur based on changes in demand for agricultural products and changes in the productivity of the land. The model implements crucial socio-economic drivers such as population, income level, consumption, diet, technological change, trade, food production and climate changes influencing crop yield through for instance increase of CO₂ fertilisation and water availability. PLUMv2 was developed to inform policy making about interaction between policy measures and individual response to climate change within various global economy scenarios.

PLUM was developed by Kerstin Engström team and collaborators in 2016. It is open-source (except GAMS license) and mainly implemented in java and the post processing is usually implemented in the R software.

WHAT IS PLUM?

PLUM is an ecological-environmental socio-economic model framework that simulates the environmental consequences of human activities and agricultural trades. It represents interactions between land use and policy measures to assess sustainability issues such as climate change, biodiversity and human diet over this century. The objective of PLUM is to explore the long-term dynamics and impacts of global changes and trades on the food system and the environment. The Lund–Potsdam–Jena General Ecosystem Simulator (LPJ-GUESS; Smith, Warlind, et al., 2014) global vegetation model was coupled to PLUMv2, a new and reconceptualised version of the Parsimonious Land Use Model (Engström et al., 2016).

For the purpose of popularization of the model concept, the model has been divided into four components:

The climate system
The vegetation system
The land management system
The market system including:
- International and domestic market
- Diet, nutrition and consumption

DOCUMENTATION

Repository

Documents

Publications

AVAILABILITY OF MODELS

Most of the components of the models are available for download but LPJ-GUESS output has to be downloaded separately and the model requires a licensed software (GAMS).

FUTURE DEVELOPMENT

To couple the CRAFTY model with PLUMv2 to investigate the role of land owner management decisions to land use changes.

FAQ

Is there source code available for download?

Source code is normally made available on request. Conditions apply in the case of model versions still under active development. See contacts.

Is there a simple demo version I can try out?

Not yet

What language is the source code written in?

Java and GAMS

Will it compile/run on Windows? Linux? Mac?

The software is designed to be portable and has been compiled and run on a variety of Linux/Unix systems as well as Windows PCs and Macs.

How long will a simulation take to run?

A global run at half-degree resolution with a time step of 1 year for up to 2100 might take around 10 hours on a modern (2020) state-of-the-art PC. If you are planning to do global runs you may need to consider going to an HPC platform (supercomputer cluster).

CONTACTS

For general enquiries and request: Peter Alexander

FRAMEWORK DESCRIPTION

BACKGROUND

The PLUM framework addresses a set of global socio-economic and environmental challenges such as climate change, land-use change, biodiversity loss, modified nutrient cycles, and water scarcity. These highly complex and diverse challenges are characterised by long-term dynamics and are often emerging from global issues linked to human activities. The agricultural sector uses 38 % of all terrestrial land (ice and desert-free, FAOSTAT, 2020) and provides the global population with food, fuel and fibre. In the wake of rapid population growth (UN, 2020), increasing consumption per capita, and increasing demand for livestock products in countries with growing economies, total food demand is projected to rise by 52–116 % by 2100 from 2005 levels (Popp et al., 2017).

Land use and model changes

Over the last decades, the number of publications and models related to land-use change modelling has continued to increase. Several alternative paradigms for modelling land use change processes were developed. According to Verburg et al. (2019) study, publications in this period indicate three trends: 1. The frequent application of easily available land use models in case-studies aimed at informing spatial planning 2. The incremental improvement of existing models and modelling concepts 3. The development of agent-based models for specific case-studies

Objective and scope of PLUMv2

PLUMv2 is a novel land use model that uses more detailed biophysically derived yield data and responses to inputs, with greater spatial specificity than previously possible. A further novel aspect of this model is that PLUMv2 does not assume market equilibrium, commodity prices are adjusted to account for over- or undersupply, while trade mechanisms also allow for representation of international tariffs and transport costs. This offers a more accurate representa- tion of the trade-offs, responses and cross-scale interactions that are likely to be important in determining the system dynamics as a whole (Rounsevell et al., 2014). PLUMv2 has been mainly implemented to investigate (see the publication list for more details):

The potential for adaptation to climate change within the agricultural system
The impacts of climate change on the food system and the impacts of the land use change on climate change magnitude and resulting impacts on ecosystem services
The development of probabilistic land-use futures and assess climate or socio-economic scenarios
The importance of scenario parameters (such as rate of consumption increase and technological change) for land-use change
The resilience of the food system
The interaction between adaptation and mitigation strategies

Model history

PLUMv1 also called PLUM is fully dissociated from PLUMv2 where only few concepts have been transferred to the two models. PLUMv2 was first implemented by Kerstin Engström team and collaborators in 2016 (Engström et al., 2016).

Baseline scenarios

PLUM model integrates and interacts with two mains based scenario types:

Representative Concentration Pathways (RCPs) (van Vuuren et al., 2011)
Shared Socio-economic Pathways (SSPs) (Kriegler et al., 2012; O’Neill et al., 2015)

RCPs simulate the greenhouse gas atmospheric concentrations and their relating radiative forcing, while SSPs projections are focused on socio-economic parameters by country such as Gross Domestic Product (GDP) and population. Future population growth and economic development input into the PLUMv2 model are derived from the SSPs which cover a wide range of possible storylines for the future evolution of the climate and society.

SSP1 characterises a world shifting to a more sustainable pathway, with low population growth and strong techno- logical and economic developments.
SSP2 a “middle-of-the-road” pathway intermediate between the other four SSPs.
SSP3 describes a path- way with strong population growth and intensive resource usage, low technological development, and lessening glob- alization.
SSP4 is a pathway of inequality with the potential for competition over resources and resource intensification.
SSP5 is a pathway dependent on fossil fuels with low population growth, strong globalization, and high economic and technological growth.

SSPs are paired with RCPs based on what sort of climate change could be expected under each SSP’s storyline: SSP1 with RCP4.5, SSP2 with RCP7.0, SSP3 and 4 with RCP6.0, and SSP5 with RCP8.5. RCP numbering refers to each scenario’s average global radiative forcing (Wm⁻²) predicted for 2100.

The model also integrated the results of a dynamic vegetation model LPJ-GUESS (see LPJ-GUESS for more details). Moreover, PLUM when used to assess impacts of shocks on the food system, was parameterized using historical data (Hamilton et al., 2020, Cottrell et al., 2019). Finally, the model run is based on a series of exogenous input based on 2010 historical data (see State of the world in 2010 for more details).

PLUMv2 in comparison with other models

A benchmark study was conducted between PLUMv2 and other Integrated Assessment Models (IAMs) (Prestele et al., 2016). This study compared the predictions from 11 models (see Glossary for more details): AIM, FARM, GCAM, MAGNET, PLUM, CAPS, CLUMondo, GLOBIOM, IMAGE, LandSHIFT, and MAgPIE. It showed that an important source of uncertainty originated from the difference of input data and a discordance between model on land-use and land-cover type definition.

Geographic detail

PLUMv2 can distinguish itself from other Integrated Assessment Models (IAMs) by the fine and disaggregated spatial scale used for the simulations. For more detail see Spatial resolution.

State of the world in 2010

To apply PLUM, all model settings are adjusted so that the model reproduces the state-of-the-world in 2010. The model calculates the state in 2010 over the period starting in 1970, using exogenous data to calibrate internal parameters. Historical crop distributions are sourced from the MIRCA2000 dataset (Portmann et al., 2010) and are held constant throughout the historical period. Demand data from 1961 to 2010 FAOSTAT, 2020) is used to derive the demand relationships. Historical nitrogen use is estimated from the world inorganic fertiliser use (IFA, 2017) plus nitrogen applied to cropland from manure. A time series of historical manure nitrogen rate applied to cropland is determined by scaling the data of 2000 (Bouwman, Boumans, & Batjes, 2002) by the livestock production index FAOSTAT, 2020) Historical irrigation water extracted is estimated from global irrigation water extraction of 2010, scaled by the irrigated cropland area FAOSTAT, 2020) for other years.

For the input parameters for LPJ-GUESS runs, the historical land use areas (cropland and pasture fractions), irrigation, and synthetic nitrogen fertiliser application levels are sourced from the LUH2 dataset (Hurtt et al., 2020). Historical manure application rates (simplified upon import to LPJ-GUESS as pure nitrogen addition) come from Zhang et al. (2017).

A calibration run is essential to the well fonctionnement of PLUMv2. This initialisation is conducted based on the historical data described above for 2010 to obtain land uses, including intensities, that generate the observed country-level commodity production and are close to the LUH2 land covers, in the initialisation year. Intensity data (i.e. for fertiliser, irrigation or management input levels), is not provided to the initialisation process. The initialisation process is repeated using the resulting data until a stable solution is reached to ensure that modelled land use changes occur only because of future scenario shifts.

MODEL IMPLEMENTATION

PLUMv2 is implemented in Java and GAMS language. GAMS is used as an optimiser for solving the complex underlying equations of the model. For each timestep, GAMS is called to optimise the land use of each country depending mainly on:

Crop parameters (yield, fertiliser and irrigation level, waste)
Cost parameters (commodity price, fertiliser and irrigation cost, production cost, conversion cost)
Meat and dairy parameters (prices, meat efficiency, feed availability and price,
Economic parameters (demand, import, export and subsidies)

The demand is also recalculated in a dynamic way using GAMS tosolve the equations between the domestic prices of commodities, the level of gross domestic product (subsidence and discretionary income) and the population. The elastic demand is included in the decision to change or not the land use or its intensity of management.

PLUMv2 INPUTS

A series of parameters are set prior to the run into the Config files such as: time step, which RPC scenario to use and year to end projection. Also, a series of input data is exogenous supplied on an annual basi such as population, GDP, consumption by commodities, baseline prices in 2010 (see State of the world in 2010 for more details). Finally, files including climate and vegetation parameters supplied on an annual basis are integrated to PLUM from the LPJ-GUESS outputs and the climate model outputs (see LPJ-GUESS, The climate system and The vegetation system for more details).

Commodities

Commodity	Description from FAO categories *not exhaustive list
Cereal C3	Include wheat and barley
Cereal C4	Include maize, millet, sorghum
Oil crops	Include soybeans, coconuts, olives, sunflower, rapeseed, oil palm fruit
Pulses	Include beans, chickpeas, lentils, vetches, lupins, peas
Starchy roots	Include potatoes, sweet potatoes, cassava, taro, yams, yautia
Sugar	Include sugar cane, sugar beet, honey
Fruits and vegetables	Include apples, pears, peaches, raspberries, courgette, butternut
Energy crops	Include miscanthus
Ruminant livestock products	Include dairy and meat product
Monogastric livestock products	Include meat products

Land covers

Land use
Cropland
Pasture
Managed forest
Unmanaged forest
Urban
Barren
Other natural

Crop types

Crop types
Wheat
Maize
Rice
Oil crops
Pulses
Starchy roots
Energy crops
Set aside
Monogastrics
Ruminants
Fruits and vegetables
Sugar
Pasture

Indices

Indices	Description
i	spatial locations within a country
j	crop and pasture land use types (wheat, maize, rice, oilcrops, pulses, starchy roots, energy crops and pasture)
j-crops	crop land use types, i.e. excluding pasture.
k	all agricultural commodities, including animal products
k-noncereals	agricultural crop commodities excluding cereals, i.e. oilcrops, pulses, starchy roots and energy crops
k-cereals	agricultural cereal commodities, i.e. wheat, maize and rice
k-feeds	crops for use as livestock feed, i.e. wheat, maize and oilcrops
k-feeds_and_pasturefeed	feed crops plus pasture
l	land cover types (cropland, pasture and natural)

Variables

Variables	Description
areai,j	area for crop j at location i (ha)
fi,j	fertiliser intensity factor for crop j at location i (unitless)
wi,j	irrigation intensity factor for crop j at location i (unitless)
mi,j	management intensity factor for crop j at location i (unitless)
ruminant_feedk	ruminant feed use for commodity k (t)
monogastric_feedk	monogastric feed use for commodity k (t)
importk	imports for commodity k (t)
exportk	exports for commodity k (t)

All variables are positive. The intensity values (f, w and m) are indexes in range 0 to 1. The model variable units are in millions of tonnes for the commodities, thousand of $ for the cost (however the cost are more an index than a real cost), area are in million hectares, CO₂ in million tonnes, and livestock are in tonnes equivalent feed (for instance, 1 kg of beef = 25 kg of feed).

Parameters

Parameters	Description
demandk	demand for commodity k (t)
export_pck	export price for commodity k ($/t)
import_pck	import price for commodity k ($/t)
base_lu_costj	base land use costs for crop j ($/ha)
f_cost	cost per tonne of fertiliser ($/t)
w_cost_indexi	irrigation cost index at location i (unitless, 0-1 range)
w_cost	irrigation cost ($/m2)
m_costj	management intensity cost for crop j ($)
f_max	maximum fertiliser rate, i.e. at f=1(t/ha)
w_maxi,j	maximum irrigation rate, i.e. at w=1, for crop j at location i (m2/ha)
irrigiation_eff	Irrigation efficiency (%)
crop_dmk	crop dry matter for commodity k (%)
suitable_areai	area suitable for agriculture at location i (ha)
water_availi	water availability at location i (m3/ha)
min/max_net_importk	minimum and maximum net imports for commodity k (t)
lc_change_unit_costl	land cover change unit cost for cover type l ($/ha)

Input parameters example

The following table shows an example of initial set of input parameters.

Parameters	Central value
Irrigation cost, w_cost ($/m2)	0.5
Fertiliser cost, f_cost ($/t)	1800
Other intensity cost, m_cost ($)	600
Land cover change cost, lc_change_cost: Natural to agricultural ($/ha)	60
Land cover change cost, lc_change_cost: Managed forest to agricultural ($/ha)	160
Land cover change cost, lc_change_cost: Agricultural land to natural land ($/ha)	200
Land cover change cost, lc_change_cost: Pasture to cropland ($/ha)	220
Land cover change cost, lc_change_cost: Cropland to pasture ($/ha)	370
Minimum natural or managed forest cover	10%
Pasture harvest fraction	50%
Seed and waste rate	10%
Technology yield change rate, ?	0.20%
Intial price shift factor	1%
International market price sensitivity, ?	30%
International import tariff, i_tariff	20%
Transport cost, t_cost ($/t)	50%
Transportation losses, t_cost	5%

Other parameters are set depending on the location considered such as the irrigation cost index (w_cost_index) used to determine unit irrigation water cost, which derived from an aridity index (CGIAR-CSI, 2008).

Irrigation cost index

Constraints

Annual change limit	Variable name	Value
Import	MAX_IMPORT_CHANGE	0.05 * time step
Demand fraction	ANNUAL_MAX_DEMAND_FRACT_CHANGE	0.5
Technology level	TECHNOLOGY_CHANGE_ANNUAL_RATE	0.002

PLUMv2 OUTPUTS

Output files

The output files of a simple run (excluding: shocks, multiple scenario runs, repeat runs with monte carlo chain)

Filename	Description
animals	Year, Country, FAOItem, Heads(M)
cluster.asc	cluster files, needed to not repeat clustering initialisation
countryCropUsages.ser
countryDemand	Year, Country, Commodity, Demand, BioenergyDemand
countryDemandOpt	Country, Year, gdpPc, population, status, utility, hungerFactor, commodity, price, subsistence, discretionary, plumNotRebase, plumRebased, rebasedKcal
demand	Year, Commodity, Amount (Mt))
domestic	Year, Country, Crop, Area, Production, Production_cost, Import_price, Export_price, Net_imports, Net_import_cost, Prod_shock, Rum_feed_amount, Mon_feed_amount
fbs	Year, Crop, Production, Imports, Export, TransportLosses, StockVar, Supply, MonogastricsFeed, RuminantsFeed, SeedAndOtherLosses, FoodAnd1stGen, ProdArea
internationalMarket.ser
lc	Year, Cropland, Pasture, ManForest, UnmanForest, Natural, AbPasture, Suitable, EnergyCrop, FertCrop, IrrigCrop
log	log console PLUMrun
prices	Year, Crop, Imports (Mt), Exports (Mt), New export price, Stock Levels (Mt)
landUseRaster.ser

LPJ-GUESS vegetation outputs

A subfolder is created for each year (name = Year) including the following files

Filename	Description
CropFract	Lon, La,t Year, CerealsC3, Oilcrops, StarchyRoots, Pulses, Maize, Miscanthus, Rice, Pasture, FruitVeg, Sugar
Done /error
Fert	Lon, La,t Year, CerealsC3, Oilcrops, StarchyRoots, Pulses, Maize, Miscanthus, Rice, Pasture, FruitVeg, Sugar
Irrig	Lon, La,t Year, CerealsC3, Oilcrops, StarchyRoots, Pulses, Maize, Miscanthus, Rice, Pasture, FruitVeg, Sugar
IrrigConstraint.asc
LandCoverFract	Lon, Lat, Year, CROPLAND, PASTURE, NATURAL, BARREN, URBAN,
LandUse	Lon, Lat, area, suitable, protected, pa_fraction, managedForest, unmanagedForest, otherNatural, cropland, pasture, barren, urban, wheat_A, wheat_FI, wheat_FQ, wheat_II, wheat_IQ, wheat_OI, wheat_Y, maize_A, maize_FI, maize_FQ, maize_II, maize_IQ, maize_OI, maize_Y, fruitveg_A, fruitveg_FI, fruitveg_FQ, fruitveg_II, fruitveg_IQ, fruitveg_OI, fruitveg_Y, oilcrops_A, oilcrops_FI, oilcrops_FQ, oilcrops_II, oilcrops_IQ, oilcrops_OI, oilcrops_Y, energycrops_A, energycrops_FI, energycrops_FQ, energycrops_II, energycrops_IQ, energycrops_OI, energycrops_Y, sugar_A, sugar_FI, sugar_FQ, sugar_II, sugar_IQ, sugar_OI, sugar_Y, pasture_A, pasture_FI, pasture_FQ, pasture_II, pasture_IQ, pasture_OI, pasture_Y, pulses_A, pulses_FI, pulses_FQ, pulses_II, pulses_IQ, pulses_OI, pulses,_Y, setaside_A, setaside_FI, setaside_FQ, setaside_II, setaside_IQ, setaside_OI, setaside_Y rice_A, rice_FI rice_FQ, rice_II rice_IQ, rice_OI rice_Y, starchyRoots_A, starchyRoots_FI, starchyRoots_FQ, starchyRoots_II, starchyRoots_IQ, starchyRoots_OI, starchyRoots_Y

SPATIAL RESOLUTION

0.5° grid cell level

The finer scale used in PLUMv2 is 0.5° grid involving a computationally challenging task of finding a solution to the non-linear land use optimisation problem For instance, China’s 942 Mha of land, for example, is represented by around 3,800 0.5° grid cells.

Land cover cluster level

An aggregated level of clustered grid cells is created during the calibration run of the model and is used for the optimisation of the model. The clustering method and details are described in Land use clustering.

Map representing the cluster level. LEgend describing the ID number of each cluster

Contry level

The country level of the model is used for instance to calculate and optimise the country production, supply and demand for each commodity (import, export and prices).

Food production unit level

For the calculation of the water availability, a similar method was used. Runoff aggregated into food production units (FPUs; Kummu, Ward, de Moel, & Varis, 2010) was adjusted to account for domestic and industrial water uses, environmental limitations on water extraction and to reproduce Elliott et al. (2014) in a baseline year of 2010.

Map representing the food production unit (FPU) level. Legend describing the ID of each FPU

MODULAR STRUCTURE

Over the years, various components of the PLUM framework have been replaced by expert models developed outside PLUM, which be used either as stand-alone models or within the PLUM framework into the Land System Modular Model (LandSyMM).LandSyMM couples a dynamic global vegetation model (LPJ-GUESS; Smith et al., (2014)), a climate system emulator (IMOGEN; Huntingford et al., (2010)), and a socio-economic land-use model (PLUMv2; Rounsevell et al., (2014); Engström et al., (2016); Alexander et al., (2018)). Additionally, LandSyMM interacts with the Modified, Implicit, Directly Additive Demand System (MAIDADS; Preckel et al., (2010); Gouel and Guimbard (2018)) to capture the relationship at the country level between food demand and income.

LPJ-GUESS

A key aim of the coupled LPJ-GUESS and PLUMv2 modelled framework was to allow the feedback for land use change on climate as well as the climate impacts on land use, to be considered. The latter version of PLUM includes the LPJ-GUESS model output, simulating carbon, water, and crop and vegetation dynamics. LPJ-GUESS model includes nitrogen cycling and has been shown to realistically simulate yield responses to nitrogen and CO₂ fertilisation (Olin, Schurgers, et al., 2015). LPJ-GUESS was used with four crop functional types (CFTs): winter-sown C3 cereals (TeWW), spring-sown C3 cereals (TeSW), C4 cereals (TeCo) and rice (TrRi) (Olin, Lindeskog, et al., 2015). Potential yields under six alternative combi- nations of fertiliser and irrigation rates were determined. Three rates of fertilisation were considered: zero fertiliser, 200 and 1,000 kgN/ha, with each either rain-fed or fully irrigated with the potential heat units scheme for plant development (Olin, Lindeskog, et al., 2015). The yields used by PLUMv2 were calculated as the product of the calibration factors and associated CFT yield output from LPJ-GUESS. The calibration factors guarantee the smooth transition from historical period to the future. While global totals are conserved in almost all cases, harmonization can produce notable differences at the regional scale.

PLUMv2 crop type	FAOSTAT crop type	LPJ-GUESS crop type Cereals
Cereals C3	Wheat barley pats	Higher of TeSW or TeWW for each grid cell
Cereals C4	Maize Millet Sorghum	TecO
Rice	Rice paddy	TrRi
Oil crops	Oil crops primary	Higher of TeSW or TeWW for each grid cell
Pulses	Pulses total	TeSW
Starchy roots	Roots and tubers total	TeSW
Energy crops	Miscanthus*	TeCo

*from the Biofuel Ecophysiological Traits and Yields Database (LeBauer et al., 2010)

IMOGEN

The IMOGEN system is designed to undertake global and regional assessment of climate change impacts on the physical and biogeochemical behaviour of the land surface. It operates with a range of CO₂ emission or concentration scenarios (plus pathways in non-CO₂ atmospheric greenhouse gas concentrations). An IMOGEN simulation representing, for instance, years 1860 (pre-industrial) to 2100 can be completed in only a couple of days on a fast single processor. The IMOGEN system is related to PLUMv2 through an emulator enabling the account for feedback between vegetation systems (LPJ-GUESS) and the climate system (on-going development).

MAIDADS

MAIDADS is designed to capture consumer preferences across a wide range of expenditure levels.It captures the nonlinearity of the relationship between food demand and income. This model is applied to the 1996 International Consumption Project data. As these data span a wide range of expenditure levels, MAIDADS offers a viable alternative to the estimation of a “global demand system.” In the context of PLUM, the MAIDADS system uses income levels, food prices and empirically-estimated price and income elasticities to estimate subsistence and discretionary consumption levels.

MODEL COMPONENTS

LandSyMM structural overview. The focus of the schematic is on the cross-scale interactions between models (PLUMv2 interactions with LPJ-GUESS, IMOGEN and MAIDADS) and the embodied interactions between the country- and world-level calculations for each time step of the model. GDP: Gross Domestic Product; RCPs: representative concentration pathways; SSPs: shared socio-economic pathways; CO₂: carbon dioxide

THE CLIMATE SYSTEM

Climate, temperature, CO₂ forcing

The RCP scenarios are used indirectly by PLUMv2 via the LPJ-GUESS. LPJ-GUESS used the climate input from the fifth Coupled Model Intercomparison Project (CMIP5; Taylor et al., 2012) outputs of the IPSL-CM5A-MR climate model (Dufresne et al., 2013). The CMIP5 runs includes land use change but not yet the trajectories output by PLUM. As the models are not climate coupled yet but rather use offline forcings, PLUMv2 results do not consider the effects of simulated land use change on climate. At the moment, PLUMv2 uses just one climate model, and as such the only uncertainty explored in this work is uncertainty related to scenario choice.

Water availability

See section Water availability for irrigation for more details.

THE VEGETATION SYSTEM

Yield response

Crop yields from LPJ-GUESS output (after harmonisation with FAO yield, see LPJ-GUESS for more details) is updated to match the climate at the location and time considered. LPJ-GUESS output provides yield potentials at different levels of irrigation and nitrogen fertilisation. For each location, the yield is calculated annually as a function of the fertiliser rate (0, 200 or 1000 kg of nitrogen per hectare), irrigation rate and management intensity. An exponential interpolation is used to estimate the yield response to fertiliser between the value given by LPJ-GUESS. The GAMS section of the model optimises the level of nitrogen fertiliser, of irrigation and of other management intensities (such as mechanisation level, pesticide application, potassium fertiliser application) to apply to each crop at each location and to calculate the associated yield response.

Water availability for irrigation

Changes were also made to the calculations of water demand and supply for crop plants (see Sitch et al. (2003) for relation of demand and supply to plant water stress). The calculation of water supply (i.e., the amount of water that a plant could take up given current soil conditions and transpirative capacity) has been reworked. Previously, water supply was a linear function of modelled phenological stage (i.e., the current leaf area index divided by the maximum leaf area index, LAI, observed in the previous growing season). Water demand, on the other hand, is not a linear function of phenological stage. This sometimes resulted in water demand exceeding water supply even in moist soils and with evapotranspirative demand below the 5 mm day^-1 maximum plant transpiration rate (Sitch et al., 2003). We replaced the direct linear dependence of crop plants’ water supply on phenological stage with a linear dependence on the ratio of wdemand (today’s water demand) to wdemand_leafon (what wdemand would be if today’s plants had the highest LAI recently observed for this CFT in this grid cell). Maximum observed crop LAI was updated daily instead of at the end of each year, to ensure that the wdemand ≤ wdemand_leafon.
The calculated water availability is aggregated from the grid cell runoff from LPJ-GUESS into ‘Food Production Units’, and the amount for drinking and industry is removed, and then a proportion of the left amount is to be used for irrigation.

Livestock feed

All quantities (e.g. demand and trade amounts) for animal products were represented in dry matter feed equivalents based on feed conversion ratios (Alexander et al., 2016). PLUM calculates the demand for food crops both for human consumption and feed for monogastric livestock, plus any ruminants not raised on pasture. The composition of the livestock feed in PLUMv2 is assumed elastic. The proportion of which crop types are used as feed is flexible depending on the fluctuations of crop prices (depending on changes of demand and production of individual crops).

Energy crops

Demand for dedicated bioenergy crops such as Miscanthus is specified according to the SSP2 scenario from the MESSAGE-GLOBIOM model; demand for bioenergy from food crops is specified to double from 2010 by 2030 and thereafter remain constant. The

THE LAND USE SYSTEM

Baseline from historical data

Historical land use areas (cropland and pasture fractions), irrigation, manure application rates, crop distributions and synthetic nitrogen fertiliser application levels are exogenous input into PLUMv2 (see State of the world in 2010 for more details). These parameters are provided from the LPJ-GUESS run outputs.

Land use optimisation

Within any PLUMv2 runs, for each country and time step, the agricultural land use and level of imports or exports were determined through a least-cost optimisation that meets the national demands for food commodities. For example, an increased national demand for a commodity can be met in three ways increasing the land area for growing associated crops; increasing the levels of inputs to achieve higher yields, that is, intensification; or increasing the level of net imports, that is, reducing exports or increasing imports.

Land use clustering

To reduce computational requirements while retaining spatial accuracy, similar (in terms of land cover, climate, crop yield, fertiliser and irrigation levels) but potentially non-contiguous grid cells within a country were grouped into clusters. The cluster level is used for the optimisation calculations. The cluster method is explained in Alexander et al, (2018). A K-mean clustering approach (Macqueen, 1967) was used with randomly initialised centroid clusters for each country. The resulting number of clusters in each country was dependent on the size and homogeneity, for example, 176 in the USA and 140 in Russia. PLUMv2 used around 3,400 clusters globally, with a mean cluster size of 3.5 Mha.

HUMAN DIET, NUTRITION AND CONSUMPTION

Within the PLUMv2, the dietary requirement of each country is determined based on MAIDADS data and recalculated for each time step. The dietary requirement are updated to include the food waste level which represent a global average food waste at the household level of be 12 % and so, the food-supply target was set to a minimum of2635 kcal cap^-1 d^-1 on average per country (instead of the daily dietary energy requirement of 2350 kcal cap^-1 d^-1) (Henry et al., 2018).

INTERNATIONAL AND DOMESTIC MARKET

Demand projection

Demand is satisfied at the country level by either domestic production or imports. The balance between imports and exports of each commodity is determined mainly by considering commodity prices, management costs (fertiliser, irrigation, land conversion), and changing LPJ-GUESS simulated crop productivity due to climate change and CO₂ under a range of management intensity (irrigation/fertilisation levels). Based on Gouel and Guimbard (2018), with MAIDADS the demand for a good is the following function of prices p, and income, m:

\[ Demand= \text{Subsidence consumption level} + \text{Discretionaty consumption level}\] With, \[ \text{Subsidence consumption level}=\frac{\delta_{i}+\tau_{i}e^{\omega u_{c}}}{1+e^{\omega u_{c}}} \\ \text{Discretionaty consumption level} = \frac{1}{p_{ci}}*\text{Marginal budget share} * \left(mc - \sum_{j = 1}^{I} p_{cj} *\; \frac{\delta_{j}+\tau_{j}e^{\omega u_{c}}}{1+e^{\omega u_{c}}} \right) \\ \text{Marginal budget share}= \frac{\alpha_{i} + \beta_{i}e^{u_{c}}}{1+e^{u_{c}}}\] where $i \in \{1, ..., I\}$ indexes the good, $c \in \{1, ..., C\}$ indexes the countries, $\delta_i \ge 0$, $\tau_i \ge 0$, $\omega_i \ge 0$, $\alpha_i \ge 0$, $\beta_i \le 1$,

\[\sum_{i = 1}^{I} \alpha_{i} = \sum_{i = 1}^{I} \beta_{i} =1\] and the utility level, $u_{c}$, is defined implicitly by: \[\sum_{i = 1}^{I} \frac{\alpha_{i} + \beta_{i}e^{u_{c}}}{1 + e^{u_{c}}} * \log(demand_{ci} - \frac{\delta_{i}+\tau_{i}e^{\omega u_{c}}}{1+e^{\omega u_{c}}}) - u_{c} =\kappa\] The parameters can be interpreted as follows: $\delta_{i}$,$\tau_{i}$, and $\omega$ govern the behavior of the subsistence consumption levels; $\alpha_{i}$,$\beta_{i}$, and $\kappa$ govern the behavior of the discretionary consumption levels.
Changing these parameters will modify the diet preferences prescribed to country depending of their GDP. For instance, $\tau_{i}$ is linked to the diet preferences at high level of GDP while $\beta_{i}$ at lower GDP level.

See for name and description of Parameters, Indices, Variables.

Unit land use costs and productivity

For each grid cell, the cost of changing land cover is calculated and productivity is derived from the yield response. \[ lu\_unit\_cost_{i.j} = base\_lu_\_cost_j + f\_cost_j * f_{i.,j} * f\_max + m\_cost_j * m_{i,j} \\ + w\_cost +w\_cost\_index_i * w\_max_{i,j} * irrigation\_eff\] See for name and description of Parameters, Indices, Variables.

Demand constraints

For each country, the commodity supply and demand is constrained by the production area, the yield and for some commodities the animal feed availability (export, import). For instance, the net supply of a commodity is calculated by the total production of the country of this commodity (yield*area) minus the feed (if the commodity considered is used for animal feed) plus the import and minus the export of the commodity. The demand of cereal crops is set superior or equal to the sum of the net supply of each cereal commodity. The change rate of demand is also limited for every time step of the model (see contraints).

International import/export constraints

At the country level, the import of each commodity minus their export is set inferior to the maximum net import parameter (parameter to be set initially) and superior to the minimum net import parameter (parameter to be set initially). The import and export of pasture is set to zero.

Other constraints

At the country level, the irrigation water is constrained by the available water for the country at the food production unit. Only suitable areas can be allocated to food or feed production or pasture.

Model optimisation

PLUM is based on least-cost optimization principles by adjusting commodity prices instead of assuming market equilibrium, allowing short-term over- and undersupply of commodities relative to demand (rather than assuming market equilibrium in every year). Instead, the model is implemented to minimise the total country cost and the function of optimisation is given by:

\[ Total\ country\ cost = \sum_i \sum_j=cost\ area_{i,j} * lu_{unit_{cost\ i,j}} + \\ \sum_i \sum_l lc\_change_{i,l}*lc\_change\_unit\_cost_l+\\ \sum_kimport_k*import\_pc_k-\sum_kexport_k*export\_pc_k \] Where lc_change is calculated for natural area, crop area and pasture area per country.

International market price adjustment

The international export price (export_pc_k,t) of a commodity k at time t, is given by:

\[ export\_pc_{k.t} = export\_pc_{k,t-1}*e^{frac{z_{k,t-1}{$\lambda}}} \] Where z_k,t is the excess demand normalised by the number of market participants at time t-1 and $is the parameter controlling the rate of market adjustment to market signals (set at 0.3).

The quantity of each commodity available for import is dependent on the global export at time t but is also reduced by a factor of transport losses rate.

The import price of each commodity is calculated at every time step from the international export price and accounts for transport losses, and import tariff. The import tariff can be set to simulate policy measures.

The calculations of domestic price has been updated to:

Trade barriers and market distorsions

To better represent the real market dynamics, PLUMv2 considers existing trade barriers for importation of commodities. Trade barriers implemented are based on by country MFN weighted average in percentage for food, from World for 2010 from World Integrated Trade Solution and were reallocated to fit the PLUMv2 geopolitical country limits. Within PLUMv2, the trade barriers are used within the import price calculations (trade barriers is refered as import tariff in this case) and to create trade maps. Market distorsions is optional in PLUMv2 and even if it is implemented, it is not yet used.

SCENARIOS

The term scenario is used at a different level of the PLUM model. It can represent:

The RCP scenarios which drive the variations over time of greenhouse gas atmospheric concentration, CO₂ forcing
The SSP scenarios which drive the variations over time for each country of their gross domestic product, their population and their diet.
The scenario that will set the scene or storyline of the model run

The lastest is described in this section and required to be adapted to each case and focus on the research questions of the model user.

Shocks scenarios

Yield shocks
The yield shocks methodology was applied to PLUMv2 by Rosyln Henry (in review, Henry et al.) and is based on the work of Cottrell et al., 2019. The concept of this scenario is to shock the yield capacity of some crops within some countries over time. The shocks are mainly driven in the real world by geopolitical and extreme-weather events (e.i. flood, drought, locust infection, plant disease or conflicts). The frequency of these events are increasing due to climate change and it is essential to integrate this component into the model for climate change impacts assessment. However, yield shocks are not randomly spread spatially or temporally over the globe, some regions are shock hotspots, exposed frequently to shocks across multiple sectors. The PLUMv2 yield shock scenario is based on historical data to estimate the probability and magnitude of the yield shocks for each country from 1970 to 2010. These parameters are implemented into PLUMv2 as an option. The yield shock is focusing on crop yield but has consequences over the whole food systems through the livestock feed supply/demand.

Market shocks (tariff barriers and subsidies)
Scenarios have been created (in review, Warren et al.) to represent a range of shocks including market shocks, diet changes, farming shock described below. These shocks are driven in the real world by speculation, price spike, tax barrier policies, geopolitical tensions.

Diet changes
Diet change due to increase of income, development of a country or an environmental trend, can have a major impact for the food system and its resilience to future shocks. A scenario was created to implement the potential switch from animal based protein to more plant based protein is the diet of some countries.

Farming shocks
Darming in the major exporter of agricultural commodities is more and more mordernised and a scenarion was created to assess the impacts on the food system and the climate of a major incident which would reduce this modernisation dramatically such as a cyber attack. The crops yield and cost of production in this scenario is impacted for a shorrt period of time (2 years) and the whole agricultural sector is reset to 2010 modern tools from then.

Income shocks
An infinity of scenarios could be created to predict specific projection possibilities. The newly explored range of shocks is the income shocks. During the beginning of the Coronavirus pandemy, policy choices and food system resilience enabled to maintain food security within most of the country around the world and avoid food price spikes. However. the average income reduced rapidly and changed the percentage of the subsidence and discretionary income household spent for food and their diet choice.

Mitigation and adaptation policies

Climate change mitigation
The PLUMv2 enables the implementation of climate change mitigation policy which can influence the land use of the country or a group of countries.

Impacts on biodiversity
To assess the impact of the food systems changes on biodiversity, it is possible within the PLUMv2 to implement a land use conversion from natural land and “protected areas” into agricultural land within a specific maximum rate every year. The protected areas are defined from the World Database on Protected Areas (WDPA; IUCN & UNEP-WCMC, 2015). Terrestrial protected areas with a WDPA status of “established,” specified on a 0.5° grid, were prevented from being converted to agricultural use. Moreover, some protected areas were created based on deforestation limitation policy such as China’s National Forest Protection Program which was implemented with a maximum rate of deforestation of 1.1% of these areas (Ren et al., 2015). The protected areas include the within the Conservation International hotspots, a set of 35 regions covering less than 3% of the Earth’s land area but containing half the world’s endemic plant species and over 40% of the world’s endemic vertebrate animal species (Myers et al., 2000; Mittermeier et al., 2004). Lost of these areas for agricultural land is a major risk of biodiversity loss.

UNCERTAINTIES AND SENSITIVITY ANALYSIS

Parameters uncertainty

The impact of parameter uncertainty on the historical model results was tested using a stochastic approach. Uniform distributions of model parameters were sampled over a range of 50% above and below the central parameter values using a Sobol sequence method with n = 50 (Chalaby, Dutang, Savicky, & Wuertz, 2015). A benchmarking process was undertaken using the central parameter values compared to the widely used LUH2 data set (Hurtt, Chini, Frolking, et al., 2017). The benchmarking results demonstrate that the model reproduces a net global expansion and intensification in the period 1970–2010 with a reasonable degree of accuracy (Alexander et al., 2018). However, various elements of uncertainty related to PLUM parameter values, global climate model selection, and model design remain to be explored.

Results uncertainty and sensitivity analysis

Unlike similar modelling frameworks the PLUMv2 has rapid runtimes and thus allows for multiple model iterations to explore across parameter space within plausible uncertainty ranges (Engström et al., 2016). The methodology used for this is the Monte Carlo approach. The Monte Carlo approach using the Sobol sequence sampling method can generate parameterisations that systematically explore joint parameter uncertainty space. Furthermore the sampled values are selected with respect to previously sampled values this avoids sample clustering or gaps and thus reduces sampling discrepancies. For instance, this method was used within the study published by Henry et al., 2018. The Monte Carlo approach within PLUMv2 is based on three different type of distribution:

Unique value: a file is feed tothe model with prescribed values for the model (ex: trade barriers)
Uniform distribution: Parameters a and b are prescribed for a probability density function as below:

\[ \begin{cases} \frac{1}{b-a}\;for\;x\;\in[a.b] \\ 0\;otherwise \end{cases} \]

Beta distribution: Parameters $\alpha$ and $\beta$ are prescribed for a probability density function as below:

\[ \begin{cases} \frac{x^{\alpha-1}(1-x^{\beta-1})}{B(\alpha,\beta)} \\ where\;B(\alpha,\beta)=\frac{\Gamma(\alpha)\Gamma(\beta)}{\Gamma(\alpha)+\Gamma(\beta)} \\ \Gamma\;is\;the\;Gamma\;function\;where\; \Gamma(n)=(n-1)! \end{cases} \]

AMENDMENTS TO THE MODEL

2021

Changed the demand system to integrate not only historical drive for food preferences but can take as an input a target diet (Based on diet preferences by country GDP). The diet preferences are still function of the price of the different commodities and of the country GDP.
Integrate a possibility to Shock the GDP of the country (example of pandemic shock).

2020

Updated the calculations for domestic price to better consider the consumer behaviour and role into food demand (see International market price adjustment for more details)
Updated versioning system for running PLUM on Eddie to allow to tag the results with the version of the model used

2019

Addition of DEMAND_PRICE_IMPORT_AND_PROD_COST

INSTALLATION

INSTALLATION and RUNNING ON LAPTOP

Set-up

Install Java JDK developer
Install Eclipse
Create GitLab account to access webpage: https://git.ecdf.ed.ac.uk/lul/plumv2 and set up SSH key
Download PLUMv2 directory or link GitLab in Eclipse: File> import> add HTTP key from your GitLab account and add your UNN username and password. It should look like that in eclipse:
Access EDDIE to download files output LPJ-GUESS

To access EDDIE with the University of Edinburgh read this instructions
Download VPN system Forticlient
In MobaXterm run:

ssh <YOUR UUN>@eddie.ecdf.ed.ac.uk

and fill your UNiversity password d) Then export file to your own machine: /exports/csce/eddie/geos/groups/LURG/models/PLUM/LPJ/LPJGPLUM_remap6p7_20190225/60.tar.gz e) Attention issues can be prompt due to permission access restrictions in this case: Contact IT team (require Peter Alexander authorisation) f) Add to a separate folder than PLUM folder g) Find file debug_config.properties in PLUM folder and change path for YIELD_DIR to this folder path

Install GAMS version 27.4 (DC11948), ask the GAMS provider the specific version or get the .exe file.
Then in eclipse, right click on Project> property> libraries> add external jars> C:64\24.7.jar. For detailed instructions of the process
In eclipse, build the project: File>export> General>Ant buildfiles> next> un-check “create target to compile project using Eclipse compiler”> Finish
In eclipse: Fix build path: right click on project> properties>build path> apply

Calibration run

First you need to run a calibration run (year 2010) and create the clusters level (cluster.asc). The clustering function enables the grouping of grid cells (0.5 degree) within a country with similar properties (fertiliser, irrigation, crop yield response) which will evolve the same way over the years. This step is essential to speed up the whole process and can be done once as an initial calibration run and will not need to be run again because the code will use the cluster file map as canvas.

Change on the properties file: debug_config.properties in the main folder of plum:

IS_CALIBRATION_RUN = true 
GENERATE_NEW_YIELD_CLUSTERS = true

Run Plumv2 application in eclipse (chose MainModel)
Open log.txt file in main PLUm directory and search for “exception” which will guide you toward any error in the run (see HELP WITH SOME POTENTIAL ERRORS)

Final step: run the model

Change debug_config.properties file:

BASE_DIR=C:/Users/jmaire/Development/plumv2 ## this specifies where the cluster can find the plum model
OUTPUT_DIR=C:/Users/jmaire/Development/plumv2/output
YIELD_DIR=C:/Users/jmaire/Development/LPJ-GUESS/rcp60 ## this specifies where PLUM can find the LPJ yield data to use
YIELD_FILENAME=yield.out ## need this so it doesn't use 'potential yield file'
DEBUG_LIMIT_COUNTRIES=false
DEBUG_COUNTRY_NAME=Mongolia
IS_CALIBRATION_RUN = false ## was set at true
GENERATE_NEW_YIELD_CLUSTERS = false ## was set at true
NUM_YIELD_CLUSTERS=8000
SERIALIZED_LAND_USE_FILE=C:/Users/jmaire/Development/plumv2/landUseRaster.ser ## this specifies where PLUM can find the calibration run land use file to use 'c_newds_rh' is the calibration run folder
CLUSTERED_YIELD_FILE=/C:/Users/jmaire/Development/plumv2/cluster.asc ## this specifies where PLUM can find the calibration run yield clusters file to use 'c_newds_rh' is the calibration run folder
END_TIMESTEP=90 ## this specifies how long to run the simulation for 90 year = up to 2100 ## was set at 0
TIMESTEP_SIZE=10 ## this specifies to run on an annual basis or decade basis
INTERPOLATE_OUTPUT_YEARS = false
CHANGE_YIELD_DATA_YEAR=false
ORIG_LEAST_COST_MIN=true ## this says to use the least cost land use optimisation approach
DEBUG_JUST_DEMAND_OUTPUT=false  ## this says only run the demand part of PLUM
PRICE_ELASTIC_DEMAND=true ## this says to use the demand system style of demand
GAMS_COUNTRY_TO_SAVE=Brazil
SSP_SCENARIO=SSP2_v9_130325 ## this specifies what SSP to use
DONT_REBASE_DEMAND=false
DEMAND_RECALC_MAX_ITERATIONS=0

Attention change the comment symbol from ## (R software) to // (java)

RUNNING ON HIGH-PERFORMANCE COMPUTER

Running Plumv2 on EDDIE

Eddie is the available high-performance computing of the University of Edinburgh. See the University webpage for details.

Log-on

To access EDDIE with the University of Edinburgh read this instructions. Then download VPN system Forticlient. Finally, in MobaXterm (on Windowns) run:

ssh <YOUR UUN>@eddie.ecdf.ed.ac.uk

and fill your UNiversity password

Build a new version

Go to PLUM dir

cd /exports/csce/eddie/geos/groups/LURG/models/PLUM

Built a new version

cd /exports/csce/eddie/geos/groups/LURG/models/PLUM/plumv2
git pull
qsub -N comp /exports/csce/eddie/geos/groups/LURG/models/PLUM/plumv2/scripts/compilePlum.sh

Then check output directory /exports/csce/eddie/geos/groups/LURG/models/PLUM/output/qlogs to make sure no errors.

Change your build link

cd /exports/csce/eddie/geos/groups/LURG/models/PLUM/build
rm juliette
ln -s 599+ juliette

Run an existing build

qsub -hold_jid comp -N calib2 /exports/csce/eddie/geos/groups/LURG/models/PLUM/plumv2/scripts/runPlum.sh -s aBuildToRun -b latest

Where “aBuildToRun” would be directory in /exports/csce/eddie/geos/groups/LURG/models/PLUM/output/. It is required to run a into a specific folder for the calibration run and it might be necessary to run ScenarioRun first (Generate an ensemble).

Generate an ensemble

To create a set of scenario to run as an ensemble for instance for a Monte Carlo set of scenarios, on your personal laptop run the R script MonteCarloStuff.R. Change line 86 to your own directory. Adjust the csv file …/Plumv2/data/sims/ssp_params.csv. Then, run for example the following line in R.

generateScenarios ("ssp_params.csv", "ssp_sims11.csv", 50, ensemblePrefix="ssp11/")

If running the R script on a Windows computer, convert the created file using Notepad++ (not the same as notepad) and go to Edit > EOL conversion > Unix. Save the file. Ftp the created file /PLUM folder called in the example ssp_sims11.csv to Eddie.

Create the scenarios for an ensemble

Check working directory is /exports/csce/eddie/geos/groups/LURG/models/PLUM using cd command . Check the /exports/csce/eddie/geos/groups/LURG/models/PLUM/output/common_properties file (that it is pointing toward the good calibration folder and the required time step). Calibration run is required (see Calibration run in Installation and running on laptop or use the already available calibration. Create a folder in /exports/csce/eddie/geos/groups/LURG/models/PLUM/output with the same name as the ‘ensemblePrefix’ e.g. here that would be ‘ssp11’. Then run:

/exports/csce/eddie/geos/groups/LURG/models/PLUM/plumv2/scripts/createScenarios.sh ssp_sims11.csv -O

“ssp_sims11.csv” in the case of this example.
If the directories exist it will not do anything unless you specify -O.
This script created the appropriate config.properties file within each sub folders.

Run a whole ensemble

/exports/csce/eddie/geos/groups/LURG/models/PLUM/plumv2/scripts/scheduleScenarios.sh -t ssp_sims11.csv -b latest

“ssp_sims11.csv” in the case of this example, -t = filename, -b = build, -p = prune (for details open scheduleScenarios.sh file in text editor)

Concatenate results

Check /exports/csce/eddie/geos/groups/LURG/models/PLUM/output/qlogs for information on the runs and use qstat to look at the statue of the runs (qw=queuing, r=running).

Go to your ensemble directory

cd /exports/csce/eddie/geos/groups/LURG/models/PLUM/output/ssp11/

Run concat script, to produce a file called lc_concat.txt

/exports/csce/eddie/geos/groups/LURG/models/PLUM/plumv2/scripts/concatOutputLc.sh ssp11/

Create the following files:

country_demand_concat.txt
country_opt_concat.txt
domestic_concat.txt
LandUseSummary.xlxs
lc_concat.txt
price_concat.txt

Check log file for errors

The log file written by PLUMv2 is call log.txt. On the eddie terminal type and change “ssp11” with the name of the output folder created.:

find -O3 '/exports/csce/eddie/geos/groups/LURG/models/PLUM/output/ssp11/' -name "*log.txt" -exec grep -i " Error" '{}' \; -print
OR
find -O3 '/exports/csce/eddie/geos/groups/LURG/models/PLUM/output/ssp11/' -name "*log.txt" -exec grep -i " Critical" '{}' \; -print

Plot results

Get the concatenated results file (lc_concat.txt) and point ProcessClusterRes.R to it.

To facilitate usage on the EDDIE. Add script folder to $PATH on EDDIE. In home directory find file .bash_profile. Open with the texte editor and changed the path to

PATH=$PATH:$HOME/bin:/exports/csce/eddie/geos/groups/LURG/models/gams/gams24.7_linux_x64_64_sfx:/exports/csce/eddie/geos/groups/LURG/models/PLUM/plumv2/scripts

Creation of new scenarios (shocks, storylines)

General instructions

Create a parameter distribution file. For each ensemble, need same parameters. Change parameter values according to required settings. For yield shocks include YIELD_SHOCKS_MULTIPLIER and set to 1 for same frequency of historic shocks, 2 for double the frequency etc. Set to 0 for no yield shocks. If you want to manually specify shocks then set to 0 and create a yield shock file manually in the run directories.
Run the ‘MonteCarloStuff.R’ R script using parameter distribution file, this generates an ensemble list. Name the ensemble list file in the 2nd argument of the call to generateScenarios

generateScenarios(nameOfParameterDistributionFile, NameofEnsembleListFile, 
                  NumberOfScenariosOfEachEnsemble, NameForEnsembleRuns/FolderNameOnCluster)
E.G. generateScenarios("params.csv", "ensembleRuns.csv", 5, ensemblePrefix="ensembleRuns/")

Open the ensemble list file using Notepad++ NOT excel and go to Edit > EOL conversion > Unix. Save the file.
Add the ensemble list file to /exports/csce/eddie/geos/groups/LURG/models/PLUM/ on the cluster.
Make a folder in /exports/csce/eddie/geos/groups/LURG/models/PLUM/output with the same name as the ‘ensemblePrefix’ e.g. here that would be ‘ensembleRuns’
On the cluster command line change your directory using

cd /exports/csce/eddie/geos/groups/LURG/models/PLUM

Check the common_properties file (/exports/csce/eddie/geos/groups/LURG/models/PLUM/output/) is pointing to the right calibration run, and the no. of timesteps.
On the cluster command line submit

qsub /exports/csce/eddie/geos/groups/LURG/models/PLUM/plumv2/scripts/createScenarios.sh fc_trialrun.csv –ys1 –O

[note: when copy and paste, the formatting goes bad for –ys1 –O … its best ot retype the flags]

This says run the createScenarios.sh script taking the ensemble list file and the –ys flag says setting yield shocks = TRUE if you don’t include the –ys flag it won’t create a yieldShocks.csv file in the directories for plum to use. Use flag –ys1 to make all the runs use the same shocks, otherwise the default is that between ensembles the shock files will differ. The –O flag says if scenarios already exist in the output directory then overwrite them.

–ys1: single yieldshock.csv file for all the runs and all scenarios
–ys: individual yieldshock.csv file per scenario (same between runs of same scenario)
If want to use own created yieldshock.csv, run the createScenarios line without any –ys/-ys1. Then, copy and paste in own file to folders on cluster.

Check that your scenarios have been generated in the output directory. Check yieldShocks.csv are there if you specified they should be. (use Compare in Notepad ++)

YIELD_SHOCK_MAGNIFIER: tells plum how big to make the shock. 1=as in yieldshock.csv; 2= double those in yieldshock.csv
SHOCKS_FREQUENCY_MULTIPLIER: for shock file creation, the number of shocks/frequency.

On the cluster command line submit

/exports/csce/eddie/geos/groups/LURG/models/PLUM/plumv2/scripts/scheduleScenarios.sh -t fc_trialrun.csv –b frances

Check your runs are running using qstat, if they have failed check the qlogs directory in the output folder to see why
Concatenate the output! Run this in command line of cluster, after cd to the directory where the run outputs are(i.e. fc_trailruns/).

/exports/csce/eddie/geos/groups/LURG/models/PLUM/roslyns_build_area/plumv2/scripts/concatOutputLc.sh fc_trialruns/

This code gets all the output files for 2030,50, 100 including the geo-spatial land use information…good for make maps for comparisons. Run in command line of cluster:

find -O3 . -name "2030" -o -name "2050" -o -name "2100" | xargs tar -czvf test.tar.gz

For maps, might only want the median run (s1):

find -O3 . -name "2018" -o -name "2100" | grep 's1/' | xargs tar -czvf test.tar.gz

Shocks generation:

This was set up originally with the SSPs in mind however can be manually modified to ignore that. It’s horrible code I’m afraid and should really be refactored! In the file ./data/shockProbabilities.csv. This specifies the likelihood of a certain shock occurring under an SSP. Default looks like this:

ssp	protectionism	automation	diet	climate	cyber	financial
SSP1	0	1	0	0	0	0
SSP2	0	1	0	0	0	0
SSP3	0	1	0	0	0	0
SSP4	0	1	0	0	0	0
SSP5	0	1	0	0	0	0

However, if you want to set up an ensemble with just protectionism for example you can change it to this. When the createShocks script runs this will always generate a protectionism shock (assuming the parameter in the scenario table SHOCKS_POSSIBLE=TRUE).

ssp	protectionism	automation	diet	climate	cyber	financial
SSP1	1	0	0	0	0	0
SSP2	1	0	0	0	0	0
SSP3	1	0	0	0	0	0
SSP4	1	0	0	0	0	0
SSP5	1	0	0	0	0	0

The file ./data/shockDistributions.csv has the parameter distributions that we discussed a long time ago about how big a parameter change is and whether the change under a given shock multiplies the existing parameter value or is added to it. So if the existing parameter value prior to the shock is 0.02 and the value pulled from the distribution is 2 then if multiplicative the new parameter value under the shock or by the end of the trend will be 0.04 and if additive then it will be 2.02. To create a shock ensemble for e.g. protectionism first set the ./data/shockProbabilities.csv table as above, with protectionism at 100% probability. Set up a params file as normal, see example paramsExample.csv. For the shock runs set SHOCKS_POSSIBLE=TRUE and set SHOCK_START_YEAR and SHOCK_END_YEAR. These three parameters trigger/are used in the script to generate a shocks file for a run. When running createScenarios.sh on cluster use the flag –s. e.g. createScenarios.sh trendRunsExample.csv –s This triggers the calling of the R script createShockFiles.R. This script creates two files in each run directory. ‘shocks.csv’ – this file contains parameter values for the parameters we are changing over time read in by PLUM. Each row is a year. E.g. the years prior to the shock will have the original parameter value and as shocks/trends are applied the value changes so PLUM knows to change the setting. ‘shocksRecord.csv’ – this file contains the shock value alone so the value that is applied in addition to the default value. This file isn’t used by PLUM it’s just to keep a record of the values that are being pulled from the distributions.

This is all set up to generate shocks/trends from random distributions so two ‘protectionist’ runs will have different parameter values for the trends. I haven’t had time to change the R script so that it generates the same values across scenarios however you could alter the R script to do it in a similar way as createYieldShockMaps.R where it takes an argument from the command line. Alternatively if you wanted to do it quickly in the meantime you could change the distribution values in the shockDistributions.csv so that the min and max values are the same so it only ever pulls the same value for parameters.

For running the storylines

Calibration run:

qsub /exports/csce/eddie/geos/groups/LURG/models/PLUM/plumv2/scripts/runPlum.sh -s calib_fc -b frances

Run this to check if fruitveg problem still there:

qsub /exports/csce/eddie/geos/groups/LURG/models/PLUM/plumv2/scripts/runPlum.sh -s fc_STP1/BAU_noshocks/s1 -b frances

STEP 1: Edit paramsExample.csv for the scenarios required
STEP 2: Run the MonteCarloStuff.R on your PC to create *.csv file
STEP 3: Copy the *.csv file to the cluster; amend shockProbabilities.csv file and run:

createScenarios.sh *.csv –s

STEP 4: Make additional changes to the shock.csv files within each folder of the generate output folder on the cluster.
STEP 5: Run the scenarios on the cluster (after change the CD to PLUM):

/exports/csce/eddie/geos/groups/LURG/models/PLUM/plumv2/scripts/scheduleScenarios.sh -t trendRunsExample.csv -b frances

BASH USEFUL COMMANDS

Unix commands you can’t live without:

ls: list file and subfolder
cd: change current working directory
mkdir: create new directory
rm: remove or unlink file
grep: search the given files for lines containing a match to a given pattern list (find string within files)
vi: to open text editor (modify a file). Migh prefer to use the command nano in stead

Really useful:

history: print history list
head: print the first part of files given to it via standard input
tail: print the last part of files given to it via standard input
cat: (short for “concatenate“) create single or multiple files, view contain of file, concatenate files and redirect output in terminal or files
|: is vertasile, could mean pipe or it could mean a logical OR
ln: create a hard link or a symbolic link (symlink) to an existing file or directory
find: find a file or files. Can add filter or apply command to the select file(s). ($ find -name "*.js")
xargs: reads streams of data from standard input, then generates and executes command lines; meaning it can take output of a command and passes it as argument of another command. If no command is specified, xargs executes echo by default
df: (short for “disk free”) display information related to file systems about total space and available space. If no file name is given, it displays the space available on all currently mounted file systems
echo: display a line of text/string on standard output or a file or the value of a variable
-N : if set after qsub, it gives an identifying name to the job

Eddie scheduler:

qsub: submit a script by sending a Queue Job Request to a batch server
qstat: request the status of jobs, queues, or a batch server
qdel : delete the called queueing job

HELP WITH SOME POTENTIAL ERRORS

On your Laptop

Might need to change BASE_DIR path in debug_config.properties to:

BASE_DIR=C:/Users/jmaire/Development/plumv2

If error can’t run any thing, run only Modelmain.java to set as main class file
Remove error search marketplace for .csv follow these instructions: Windows>Preferences> add in files types> *.csv> add in associate editor Text editor>apply
Set up home directory if not set-up in windows, follow these instructions, answer 6
In windows> search>Edit the environment system variables>environment variables> edit path> add GAMS path: C:64\24.7 > restart eclipse as windows updates not always link to eclipse.

On Eddie

First scenario run will always use median parameter values from the distribution file.
Currently uses Roslyn’s version of plum (roslyns_build_area)…bear in mind for the future when it might be changed to use Peter’s version (just changing the file path).
If need to cancel a lot of runs, use this line… with first and last job numbers:

/exports/csce/eddie/geos/groups/LURG/models/PLUM/roslyns_build_area/plumv2/scripts/stopRange.sh 2435600 2435609

Can change the ‘common_properties’ file before running the scenario creation, just remember to change back again. Also, double check the created config.properties file in case anything is amiss.
For code on looking at the output, look at PLUMscripts/debugging.rmd from bitbucket.

GLOSSARY

ACRONYMS

Acronyms	Definition
LUC	Land Use Change
LULCC	Land Use/Land Cover Change
BVOCs	Biogenic Volatile Organic Compounds
PFTs	Plant Function Types
CI	Conservation International
IAM	Integrated Assessment Model
DGVM	Dynamic Global Vegetation Model
CGE	Computable General Equilibrium = AGE (applied general equilibrium)
SSPs	Shared Socio-Economic Pathways
SPAs	Shared Climate Policy Assumptions
RCPs	Representative Concentration Pathways
RAPs	Representative Agricultural Pathways
BECCS	Bioenergy Crop Production Combined With Carbon Capture And Sequestration
CDR	Carbon Dioxide Removal
IAV	Impacts, Adaptation, And Vulnerability
FPUs	Food Production Units

MODELS NAMES

Acronyms	Definition
LPJ-GUESS	Lund-Postdam-Jena General Ecosystem Simulator
LandSyMM	Land System Modular Model
PLUM	Parsimonious Land Use Model
CRAFTY	Competition for Resources between Agent Functional Types
AIM/CGE	Asia-Pacific Integrated Assessment/Computable General Equilibrium (Fujimori et al., 2014, 2016)
GCAM	Global Change Assessment Model (Wise et al., 2014)
IMAGE	Integrated Assessment of Global Environmental Change (Stehfest et al., 2014)
MESSAGE-GLOBIOM	Coupled the energy model MESSAGE, the land use model GLOBIOM (Kindermann et al., 2006; Havlík et al., 2014; Riahi et al., 2012)
REMIND/MAgPIE	Regional Model of Investments and Development/ Model of Agricultural Production and its Impact on the Environment (Popp et al., 2011, 2014)
LPJmL	Lund-Postdam-Jena management land (global vegetation and hydrology model)
MAIDADS	Modified, Implicit, Directly Additive Demand System (Preckel, Cranfield & Hertel (2010), Gouel and Guimbard 2018)
IMOGEN	Intermediate complexity model to evaluate terrestrial impacts of a changing climate (Huntingford et al., 2010)
CLUMondo	Conversion of Land Use change Mondo (Van Asselen and Verburg, 2013)
FARM	Future Agricultural Resources Model(Nelson et al., 2014, Sands et al., 2014)
MAGNET	Modular Applied GeNeral Equilibrium Tool (Van Meijl et al., 2006, Woltjer et al 2014)
CAPS	(Meiyappan et al., 2014)
LandSHIFT	(Schaldach et al., 2011

TERMINOLOGY

CO₂ fertilisation: The speeding-up of photosynthesis, known as carbon dioxide (CO₂) fertilisation, is well-known to be an important consequence of higher CO₂ concentrations in the atmosphere, along with increased water use efficiency. Under higher CO₂, plants do not lose so much water through their leaves, so can be less impacted by drier conditions and can better utilise the nitrogen present in the soil which correspond to higher yield under similar fertiliser application regime.
Oligopolistic market: The primary idea behind an oligopolistic market (an oligopoly) is that a few companies rule over many in a particular market or industry, offering similar goods and services. Because of a limited number of players in an oligopolistic market, competition is limited, allowing every firm to operate successfully.
Monopsony power: A monopsony occurs when a firm has market power in employing factors of production (e.g. labour). A monopsony means there is one buyer and many sellers. It often refers to a monopsony employer – who has market power in hiring workers. This is a similar concept to monopoly where there is one seller and many buyers
Subsistence level: A level of income that provides only enough money for basic needs. In PLUMv2, the subsistence level is defined based on the income within the country.
Discretionary income: A level of income that provides enough money so there is an amount of an individual’s income that is left for spending, investing, or saving after paying taxes and paying for personal necessities, such as food, shelter, and clothing. In PLUMv2, the discretionary level of income is calculated based on the income and the commodity prices in the international market.
Markup: Price markup is the difference between the selling price of a good or service and cost. It is often expressed as a percentage over the cost. A markup is added into the total cost incurred by the producer of a good or service in order to cover the costs of doing business and create a profit.

Documentation Parsimonious Land Use Model (PLUM)

Juliette Maire (Juliette.Maire@ed.ac.uk)

22/07/2020