A very short summary of Magic Harvest

Authors: Clément Hardy¹
Affiliations: ¹Université du Québec en Outaouais (UQO)

The way MHS-CBAU works depends mainly on a specific LANDIS-II extension called Magic Harvest, that I also develloped. Before going into how MHS-CBAU works, here is a very short summary of how we use Magic Harvest to implement the simulation of forest management in LANDIS-II.

A metaphor : Magic and B. Harvest¶

Magic Harvest is a LANDIS-II extension. It’s one of the three necessary to use MHS-CBAU (see previous slides). It’s the one that really allows MHS-CBAU to exist, as it allows the user to run scripts or programs during the simulation to make management decisions.

It works in tandem with the Biomass Harvest extension of LANDIS-II. As a metaphor : Biomass harvest is like a forester. It has the tools to harvest trees (can harvest trees in LANDIS-II), and can do some management decisions too (but the algorithm is simple and limited). He can work solo !

In contrast, Magic Harvest is a forest engineer. Their main skill is making decisions; they have not tools to cut trees ! (The code of Magic Harvest cannot remove trees in LANDIS-II). So, Magic Harvest has to work in tandem with Biomass Harvest and cannot work solo. When they work in tandem, Magic Harvest can make the management decisions (where and how to harvest at this timestep), and Biomass Harvest will do the actual harvesting (removing trees in the internal variables of LANDIS-II).

Controlling Biomass Harvest with Magic Harvest and a Python script¶

As detailed in the Magic Harvest Workshop, Magic Harvest can work in tandem with Biomass Harvest with different degrees of control. As Biomass Harvest still has a decision algorithm implemented, Magic Harvest can make some of the decisions, or ALL of the decisions concerning harvesting at the time step.

Here, in MHS-CBAU, we use Magic Harvest in a “total control” mode. This is how it works, as a summary (more information are in the workshop) :

At every timestep, Magic Harvest runs BEFORE Biomass Harvest.
When it runs, it will call a custom command (for example : run a given Python script).
The command/script will make all of the management decisions, and return a management map of the same dimension as the landscape.
In this management map, we find pixels filled with a code corresponding to a given management prescription (e.g. clearcutting).
We will also return an edited version of the parameter text file of Biomass Harvest, which can contain additional prescriptions (e.g. prescriptions with a certain form a planting), and an edited harvest implementation table (that tells Biomass Harvest to harvest 100% of all pixels with a given code in the management map with the prescription associated with the code).
Then, Magic Harvest will make Biomass Harvest re-load its internal parameters using this management map and edited parameter text file for Biomass Harvest. This will override the decision algorithm of Biomass Harvest, which will harvest the pixels on the landscape exactly as Magic Harvest planned it.

Why does it need to be so complicated ? Can’t we use one extension instead of two to do harvesting in LANDIS-II ?

There is a good reason why this process is so convoluted, and why Magic Harvest is not a stand-alone extension.

Biomass Harvest have been develloped for a long time in LANDIS-II, and uses a complex system of “support libraries” (libraries of functions used in the code of LANDIS-II) to effectively harvest cells during the simulation.

The problem is that Biomass Harvest as a relatively limited decision algorithm. I develloped Magic Harvest as a way to allow LANDIS-II modellers to implement any decision algorithm they might want by using Python or R scripts that they could program themselves.

But the harvesting still has to ultimatly go through the complex system of support libraries for harvesting so that is is done during the simulation. Because of this, it was much easier to use Magic Harvest to control Biomass Harvest (which was already made to communicate with these support libraries) rather connecting Magic Harvest to these support libraries (which might have reduced the flexibility offered by Magic Harvest).

I would have liked to find a better solution, but it seemed to be the best choice to go with. Ultimatly, the approach that will result is stable, replicable, and sharable (by sharing your input files), ensuring that it remain compatible with the principle of replicability in science - even though it is a bit complex.