• Download or clone this entire repository either using, Github Desktop, git clone or downloading it as a .zip folder using this link.

The database to run the platform for the pilot country of Zambia is avaiable at the official Zenodo repository of the RE4AFAGRI platform).

Once downloaded, the database(s) (a zipped folder for each of the four models) should be extracted. The exact full path to the database (e.g. C:/Users/[yourusername]/Documents/RE4AFAGRI_database/... should be parsed onto the different model at the following positions:

• For WaterCROP: at lines 1, 4, 21, 55, 65, 68 - and subsequently for each crop - and 785 of the 'WaterCROP1_ETactual.mat' file at lines 9, 14, 20, 94 of the 'WaterCROP2_Irrigation_requirements.mat' file
• For M-LED: at line 10 of the MLED_hourly.R file, defining the db_folder parameter
• For OnSSET: include the OnSSET replication data folder unzipped in onsset\onsset_replication (more details below)
• For NEST: The database only raw data needed in the pre-processing phase. The data needed to run the model is already included in the Github repository

• Have 'Matlab' (version >= R2017a) installed on your local computer

• Open 'WaterCROP1_ETactual.mat' file in MATLAB and select the scenario to run; then run the code.

• Open 'WaterCROP2_Irrigation_requirements.mat' and run the code. The code will produce the input files produces netcdf files of irrigation water requirements and yield growth potential for all African countries.

• Open the MLED_hourly.r file in RStudio

• Move the WaterCrop output data (*.tif files) to the M-LED input folder specified in the line 10 of the MLED_hourly.r main script. Note that the exact path in which the files are stored does not matter, as long as they are in a sub-folder of the M-LED input folder path. An example path could be ./input_folder/watercrop/....

• After having run run lines 1-75 to configure the environment and the required dependencies (as discussed above), run line 80 to start running the scenarios specified in the MLED_hourly.r preamble in sequence.

• Move the MLED output data to... [GREGORY]

• In the root of the onsset folder first open MLED_extraction_to_OnSSET.ipynb and run all of the cells. This will extract the MLED demands and create OnSSET compatible input files for use in the next step. The process may take a few minutes. You should find them as .CSV files in the onsset\mled_processed_input_files folder with the names of the scenarios. If for any reason this step fails, then there are pre-processed input files available in the onsset_replication\mled_processed_input_files database download which you could use instead or if you wish to double check your results.

• Then, navigate into the onsset/onsset sub folder which also includes the .py Python files used by OnSSET.

• Open the OnSSET_Scenario_Running.ipynb Notebook and run all of the cells. This will take a few minutes and will run the different scenarios and calculate the least-cost electrification options for the entire country. It will output it's results into several folders as .CSV files both as full results files for every population cluster in the country as well as summary files (also used later by NEST).

• Move the OnSSET, M-LED and WaterCrop output data to... [ADRIANO]

• After having installed the folder by source (see Setting up the environment) run the script nest\message_ix_models\project\leap_re_nest\build.py

• around line 126, at * 4) add water structure* follow the instruction and run the command in the command prompt

To merge the results after having run some or all of the four RE4AFAGRI models, use the ./reporting/merge_outputs.R file in this repository. Specify the country name in line 8 using lowercase (e.g. "zambia") and the path to the clones RE4AFAGRI repository (containing each model's subfolder and the output data) in line 6.

Three output geojson files will be produced in the reporting folder, containing outputs for all scenarios and timesteps from M-LED and WaterCROP (both contained in the M-LED file, ./reporting/[countryname]_gadm2_mled_ALL_SCENARIOS.geojson), OnSSET (./reporting/[countryname]_gadm2_onsset_ALL_SCENARIOS.geojson), and NEST (./reporting/[countryname]_bcu_nest_ALL_SCENARIOS.geojson), respectively.

The files can be used for further processing and visualisation purposes in R, Python or other programming languages, or imported in GUI GIS softwares such as QGIS.

---

To define a new scenario in M-LED, the user can take two main type of actions:

• Edit the lines 55-75 of the MLED_hourly.r file, to specify:

  • SSP and RCP scenarios. This action will lead the model to read different input data, and therefore assuming different demographic and economic development trajectories, as well as different climate change impacts (mostly relevant for water and irrigation and crop yield and crop processing). For greater information on the SSP and RCP scenarios refer to this webpage.
  • Policy targets. This action will affect how demand in different sectors, and chiefly residential, SMEs and agricultural sector will evolve in the future as a result of a given 'policy push' to stimulate energy access and uptake of appliances such as crop processing machinery.
  • Scenario names. This action is useful to identify the output files and link them to underlying edits in the scenario assumptions.

• Moreover, a broader range of scenario modifications can be achieved by editing the scenario_.R files, adjusting parameters and assumption throughout the script, and in particular between lines 10-172.

---

WaterCROP already runs natively at a continental scale for sub-Saharan Africa, and thus this section is not relevant as outputs are already available for any SSA country.

To prepare a new country model in M-LED, the user is required to take a number of steps:

As discussed in the M-LED webpage, the geographical unit of reference in M-LED (and also in OnSSET) are population cluster polygons. For the five base country studies (Zambia, Zimbabwe, Nigeria, Kenya, and Rwanda), these are obtained from GRID3, which provides such settlement extents for 50 sub-Saharan African Countries. The steps presented here below are assuming the user to be willing to run M-LED for one of those additional 45 countries. On the other hand, these steps can only be used as a general reference for a user interested in running M-LED to a country which is not part of this set of 50 countries. Specific queries on this matter should be directly posted as a specific issue in this repository.

To prepare a population cluster file obtained from GRID3, the user should utilise the mled/country_scenarios/process_clusters.R file. Here, at row 37 the user should indicate the path to the geopackage or shapefile of the clusters data.

In addition, the following lines reading input data should be updated to the path of the relevant data (which should be separately obtained as detailed here below):

• 50: gridded population raster from GRID3, data download from WorldPop
• 69: night time light data in the calibration year 2020, data download

Finally, custom statistics for the country in question should be updated in lines:

• 45: total current national population according to the UN Population Division
• 46: total current national population according to the UN Population Division
• 110: total current national urbanisation rate according to the UN Population Division

The process_clusters.R script will then add a set of fields to the input settelement clusters file, such as the current polulation, the area, the nightlight value, and calibrated (to the national statistics inputed in the lines discussed here above) local urbanisation status and local electricity access rate.

Eventually, the process_clusters.R files will write a .gpkg file contained the processed cluster data which will be read by M-LED (see below the 'Adjusting the scenarios and the parameters' section).

While the base M-LED database already contains Africa-wide data for most of the variables required, a limited number of input data are country-specific only. Thus, besides the preparation of the cluster data, the user is also required to collect a number of custom datasets that will be imported by the scenario_<countryname>.R and used for sectoral demand estimation:

• NEST basin catchment areas file (row 212)
• Geocoordinates of healthcare facilities (row 337)
• Geocoordinates of schools (row 345)

• Start by duplicating one of the scenario_<countryname>.R files in the country_studies folder of M-LED. Which of the existing countries is used as a template is indifferent. Rename the file to scenario_<NEWcountryname>.R , e.g. to scenario_ethiopia>.R.

• Adjust all the parameter values of the newly created scenario_ethiopia>.R to match the values for the country by ensuring to use the correct units (hint: look at the comments in the existing country scenarios files and compare the orders of magnitude of the numerical parameters).

• Customise the residential, healthcare and educational loads from RAMP (rows 269-315)

X

X

X