MHS-CBAU is a an approach to simulate a Business-As-Usual forest management in Canadian lanscapes that are simulated with the LANDIS-II model and its Magic Harvest extension. In essence, it is made to simulate harvesting in LANDIS-II simulations in Canadian landscapes.

MHS-CBAU works through a specific Python script (available in this repository) that is called by Magic Harvest during a LANDIS-II simulation. The Python script will make all forest management decisions, and then pass them to the Biomass Harvest extension of LANDIS-II which will execute the harvesting. To learn more about this method of using Magic Harvest and Biomass Harvest in tandem, please see this workshop.

To make the management decisions in the Canadian landscape where the situation is made, the Python script of MHS-CBAU needs several inputs; some are generated by LANDIS-II during the simulation, but some need to be created before the simulation. This repository contains all of the instructions and scripts to create these inputs for your study area, wherever it is in Canada.

The repository also contains a complete documentation in a web format and powerpoint format.

By following the instructions in this repository, you can get a parametrization for your landscape in Canada running in a reasonable time (a week or two !). The goal of this repository is to make it easy for you to get all of the parameters you need.

MHS-CBAU is also designed to be customisable : the scripts are all heavily commented so that you can edit them and add things like zoning (e.g. TRIAD), new tree species, new prescriptions, etc. You just need some knowledge in Python to edit the scripts. See https://futurecoder.io/ for some free and simple Python introductory courses.

I recommand you do the following :

1. Take a look at the Magic Harvest Workshop if you haven't already (important to understand how Magic Harvest works, which is essential to use MHS-CBAU). Estimated time of reading : 2-4 hours
2. Take a look at the MHS-CBAU workshop (important to understand the inputs of MHS-CBAU and its algorithm). Estimated time of reading : 2-4 hours
3. Use the scripts in this repository to generate the inputs for your own study area, using the MHS-CBAU workshop as a guide, or the step-by-step indicated below.
4. (Optional but recommanded) use a Python interactive terminal (I recommand to use Spyder) to test the MHS-CBAU Python script outside of a LANDIS-II simulation to see if it works properly, and produces outputs that make sense for your study area. To do this, simply run a LANDIS-II simulation without MHS-CBAU activated (doing it for a single timestep is enough). Then, use the outputs of LANDIS-II and the debug mode of the MHS-CBAU Python script to test the script as if it was running during the timestep of LANDIS-II for which you have generated outputs. More is shown in the MHS-CBAU workshop.
5. Insert the scripts and pre-generated intputs for MHS-CBAU in your LANDIS-II simulation files to start using MHS-CBAU during your simulations.

If you don't have the time to read the workshops (which I heavily recommand), here is the quick step-by-step to get everything ready for your LANDIS-II simulation :

1. Install the LANDIS-II extensions Biomass Harvest, Magic Harvest and Output Biomass Community in your computer.

See the Biomass Harvest repository, the Magic Harvest repository and the Output Biomass Communit repository for the installers.

2. Install Python on your computer

Python is programming langage that can be used either as programs, scripts or interpreted through a console (like R). All of the scripts present in this repository are in Python. You will need it to run certain scripts that will generate the inputs for your study area, but also for the scripts that will run during your LANDIS-II simulation. But you need to make sure that you have some of the Python packages installed to run the scripts.

If you have never used Python before and don't plan to use it for something else than MHS-CBAU, here is the quick way to get things ready.

• Go on https://www.python.org/downloads/, download and install the latest version of Python.
• Create a virtual environment containing the packages necessary for MHS-CBAU scripts to run :
  • Use python -m venv PythonEnv in any terminal to create the virtual environment in the folder PythonEnv where your terminal is currently pointing at.
  • Use the one of the following commands to activate the virtual environment in your OS and terminal of choice :
    • source PythonEnv/bin/activate if you're on Linux/MacOS/using Git-bash
    • PythonEnv\Scripts\activate.bat if you're using a command prompt on Windows
    • PythonEnv\Scripts\Activate.ps1 if you're using a Powershell prompt on Windows
  • Install the packages needed for MHS-CBAU with pip install numpy pandas rasterio tqdm

You will need to activate this environment before launching your LANDIS-II simulations in the future so that the MHS-CBAU scripts can run during the simulation (see the activation command that fits your OS or command prompt you will use to run LANDIS-II as written above). Note that you can move or copy/paste the "PythonEnv" folder containing the virtual environment you have just created in another folder of your computer to put it closer to your LANDIS-II simulation files.

If you are using a Dockerized version of LANDIS-II, you can easily install Python and these 4 packages in the base environment of your docker image (no need to create a virtual environment), which will make the packages available to the MHS-CBAU scripts.

💡 If you want to use Python for other things in the future, you can also install the package manager Anaconda to create virtual environments..

3. Generate the stand and management areas maps for your study area

These maps should be the same as the ones demanded by the Biomass Harvest extention.

The management area map should be of the same size and resolution as all of your other LANDIS-II maps for your study landscape. Pixels should contain a value that corresponds to the management area they are in. It's most likely that one of the values you will use will correspond to protected areas (areas without harvesting). Keep that value noted for later.

The stand map should also be of the same size and resolution as all of your other LANDIS-II maps for your study landscape. Pixels should contain either 0 (inactive cell), or a number corresponding to the unique identifier of a stand. Therefore, all pixels with the same value will be considered to be in the same cell. However, all of the pixels of a given stands should be in one management area, and not two. You will get errors from the Biomass Harvest extension if you don't respect this rule.

4. Create a shapefile defining the extent of your study landscape

You can use QGIS to do this. As much as possible, be certain that this extent is the same extent as the raster maps you are using in LANDIS-II.

5. Change the name of your species in LANDIS-II to the format of the National Forest Inventory of Canada (NFI)

This is to save you time, as the scripts and ready-made parameters in this repository use this format. If you don't use this format, you will have to edit some files down the road to avoid errors.

The format used by the NFI is described in this document, and is as follow : XXXX.YYY, with XXXX being the first four letters of the Genus in capsize letters (e.g. ABIE for Abies) and YYY being the first three letters of the species name (e.g. BAL for Balsamea). This gives you ABIE.BAL for Abies balsamea, PICE.MAR for Picea mariana, etc.

You will find all of the codes for almost all species in Canada in the document.

⚠ If you don't use this formatting, you will have to edit the name of the species in these 4 files further down the line : merchantableBiomassRatiosDictionnary.json; shadeToleranceSpeciesCanada.json; speciesTargetType.json; woodDensityDictionnary.json. See bellow for information about how these files are generated. You will have to make sure that all of the species you simulate in LANDIS-II have their names present in these files.

💡 You can use the folder /speciesCheckTest in this repository to check if all of your species are represented in the four files given above. Just put a .csv file where the first column contains the name of the species you are simulating in LANDIS, and run the python script in this folder using the command python speciesCheckTest.py from a terminal pointing to this folder. The script will analyse your species and indicate which of them might be missing from these four files.

6. Define the commercial species in your landscape

These commercial species will be the ones that will be planted in some cases after a clearcut in the MHS-CBAU algorithm. These species must be the most interesting species commercially for forest industries. For example : in Quebec, these would mostly be white spruce and black spruce (PICE.MAR and PICE.GLA according to the format of the NFI; see above).

7. Decide volume reduction factor gross to net (or use the default value of 7%)

LANDIS-II computes the aboveground biomass of the age cohorts (in weight of biomass). In contrast, MHS-CBAU works by estimating the merchantable volume of the age cohort from the above ground biomass. It compares these merchantable volume to "merchantable volume targets" for the timestep, which are based on reported harvested volumes in Canada (from the National Forestry Database of Canada).

MHS-CBAU converts the aboveground biomass of LANDIS-II to merchantable volume so using three convertion factors : a ratio of merchantable versus total aboveground biomass; the wood density of the species; and a further reduction factor that accounts for wood that is, in the end, not used by the industry because of defects or other reasons. While the merchantable biomass ratios and wood density will be automatically generated by the scripts of the repository (see below), you can adjust this reduction factor yourself.

I recommand using a reduction factor of 7% (0.07) based on the data we have from Quebec on this gross-to-net reduction (see here). You can also change this ratio by species.

8. Run the script to find the harvesting target per year in your study landscape

The scripts are located in scriptsToGenerateInputs/1.VolumeAndAreaTargetsCalculation.

You will find a README.txt file containing all of the instructions you will need to run the scripts.

The scripts will output a file named annualHarvestTargets.json. Keep this file at hand.

9. Run the scripts to generate the merchantable ratios and ecozones map for your study landscape

The scripts are located in scriptsToGenerateInputs/4.MerchantableBiomassDictionnary.

You will find a README.txt file containing all of the instructions you will need to run the scripts.

The scripts will output two files you need to keep at hand : EcozonesRaster.tif, and merchantableBiomassRatiosDictionnary.json.

10. Prepare the Output Biomass Community parameter file

The Output Biomass Community extension is vital to making the scripts of MHS-CBAU work. This extension outputs two files at each time step - a csv file and a raster file - which contain the composition of your LANDIS-II landscape in the same format as the initial condition raster and csv/text file you use to initialize LANDIS-II.

The MHS-CBAU script will read these file in order to get the current state of the landscape at each time step.

At the time of writing this, Output Biomass Community doesn't have any parameter except from the timestep at which it runs. Therefore, just write a text file with the following :

LandisData  "Output Biomass Community"

Timestep   X

Replace "X" with the timestep you are using for Magic Harvest and Biomass Harvest (it must be the same timestep).

The outputs of Output Biomass Community are very large, but the MHS-CBAU script has some lines to remove these files once the timestep is over. You can edit the parameter DELETE_COMMUNITIES_FILES in MHS-CBAU_MainScript.py to change this.

Be certain to write in your LANDIS-II scenario file that your scenario should use Output Biomass Community.

11. Copy and paste all of the necessary files to include MHS-CBAU in your LANDIS-II simulation

You're almost done ! It's all about copying/pasting some files and writting down some paths in them now.

The way you will copy and paste this files will depend on how your organize your LANDIS-II simulation files. Just make sure that all of the files noted here are available to your LANDIS-II simulation.

In my case, I usually create a folder in /inputs/disturbances/harvesting-MSH-CBAU/ in my LANDIS-II simulation files.

From here :

• Copy/paste the annual harvest targets (annualHarvestTargets.json) made from scriptsToGenerateInputs/1.VolumeAndAreaTargetsCalculation.
• Copy/paste the cut size distributions (cutSizesDistribution.json) present in scriptsToGenerateInputs/3.CutSizeProbabilitiesFromQuebecData. These cut sizes are from Quebec data because that's the best data I've found to derive them, but they should do for other study areas in Canada.
• Copy/paste the merchantable biomass ratios (merchantableBiomassRatiosDictionnary.json) and the map of ecozones (EcozonesRaster.tif) made from scriptsToGenerateInputs/4.MerchantableBiomassDictionnary.
• Copy/paste the wood density values (woodDensityDictionnary.json) present in scriptsToGenerateInputs/5.WoodDensityBiomassDictionnary. These are taken from the Global Wood Density Database.
• Copy/paste the target species types (speciesTargetType.json) present in scriptsToGenerateInputs/6.SpeciesTargetTypeDictionnary. These simply indicate if a species is a hardwood or softwood.
• Copy/paste the stand map and management area maps you have created for your study area.
• Copy/paste the Biomass Harvest template parameter file (biomassHarvestParameterFileTemplate.txt) present in /otherInputs. Open the file, and indicate the relative path to management area map and stand map (relative to the location of the scenario file of your LANDIS-II simulation; see warnings in the template for more).

💡 If you want to use a different time step than 5 for the harvesting, edit the timestep at the beginning of the file.

• Copy/paste the Magic Harvest parameter file (magicHarvestParameterFile.txt) present in /otherInputs. Open the file, and add the path to the folder where you will want the Biomass Harvest parameter file to be generated dynamically during the simulation by replacing the keyword INSERT_PATH_TO_PREPARED_BIOMASS_PARAMETER_FILE in the file (⚠ Note that this Biomass Harvest parameter file does not exist yet, as it will be generated during the simulation.

⚠ Do not put the name of the Biomass Harvest template parameter file from the previous step, as this one is just a template, and is not the one Magic Harvest will use to reload the parameters of Biomass Harvest).

💡 If you want to use a different time step than 5 for the harvesting, edit the timestep at the beginning of the file; but be certain that it is the same timestep indicated in the Biomass Harvest template parameter file (previous step).

• Copy/paste the file probabilityMatrixCutsVersusStandType.csv present in /otherInputs. If you want to know more about these parameter, check the file README - Origin of each file.txt in /otherInputs.
• Copy/paste the file shadeToleranceSpeciesCanada.json present in /otherInputs. If you want to know more about these parameter, check the file README - Origin of each file.txt in /otherInputs.
• Copy/paste the main Python script (MHS-CBAU_MainScript.py) and the script containing the functions (functionsMHS_CBAU.py).
• Open the Magic Harvest parameter file (magicHarvestParameterFile.txt) again, and write the relative path to MHS-CBAU_MainScript.py (relative to the LANDIS-II scenario file you will use for the simulation; see warnings in comments) by replacing the keyword PATH_TO_MHS-CBAU_MainScript in the file.
• Open the main Python script (MHS-CBAU_MainScript.py) and go to the section #%% INPUTS. In this section, you will find a list of inputs to fill in. Most of them are pre-filled with examples or default values. Use everything you have done in the previous steps to fill them. I have written extensive comments to help you fill each of them.
• Open the main scenario file of your LANDIS-II simulation to add Magic Harvest and Biomass Harvest as disturbance extensions. However, be certain that a) Magic Harvest is before Biomass Harvest, b) Magic Harvest and Biomass Harvest are before other disturbance extensions (e.g. fire, etc.), and c) that your the parameter DisturbancesRandomOrder is set to no. This is crucial so that Magic Harvest is called before Biomass Harvest at every timestep, and so that harvesting is done before other disturbances. If you don't do this, the harvesting will be done based on the wrong data ! Indicate the parameter file of Magic Harvest as the location of magicHarvestParameterFile.txt, and indicate the parameter file of Biomass Harvest as the location of biomassHarvestParameterFileTemplate.txt.

💡 If you also want to use the Forest Roads Simulation extension, be sure to call it right after Biomass Harvest in your LANDIS-II scenario file.

💡 Here is an example of what how your disturbance extensions should be called in your LANDIS-II scenario file :

>> Disturbance Extensions Initialization File
>> ---------------------- -------------------
"Magic Harvest" ./input/disturbances/harvesting-MSH-CBAU/magicHarvestParameterFile.txt
"Biomass Harvest" ./input/disturbances/harvesting-MSH-CBAU/biomassHarvestParameterFileTemplate.txt
"Forest Roads Simulation" ./input/disturbances/roads.txt
"Base Fire" ./input/disturbances/fire_Baseline.txt
"Base BDA" ./input/disturbances/budworm_BDA.txt

DisturbancesRandomOrder no

• Open the parameter file of the Succession Extension you're using (e.g. Biomass Succession), and add the following harvest prescriptions in the section where they should be indicated along with their biomass reduction factors : Clearcutting; Shelterwood; Seed-tree; Selection-Cutting; Commercial-thinning; Pre-commercial-thinning. You might want to put an asterisk (*) right after their name (e.g. Clearcutting*) to also catch the planting prescriptions (e.g. Clearcutting-Planting:PICE.GLA) that will be dynamically created during the simulation. This will prevent a lot of error messages that slow down your simulation.

🎉🎊 And with that, you're done ! Now, MHS-CBAU should work properly during your simulation. If it doesn't, please post in the issues section of this repository.

• LANDIS-II is made by the LANDIS-II foundation
• Wizard on the logo comes from Freepik