{
"cells": [
{
"cell_type": "markdown",
"metadata": {},
"source": [
"# Using the ``ws3`` optimization modelling function (advanced) \n",
"\n",
"The `ws3.forest.ForestMdoel` class includes a number of methods to automate formulation and solution of optimization problems. In this notebook, we will demonstrate how to use these methods to formulate various common forms of objective functions and constraints, how to combine these in various ways, and how to solve these problems using the built-in solvers."
]
},
{
"cell_type": "markdown",
"metadata": {},
"source": [
"## Set up environment"
]
},
{
"cell_type": "markdown",
"metadata": {},
"source": [
"Below we (optionally) install the `ws3` package from the local source code in this repository using the `-e` flag to ensure that the package is installed in editable mode (i.e., any changes you make to the source code immediately affect `ws3` behaviour the next time you run the notebook). This is is not necessary if you have installed `ws3` using pip or another method.\n",
"\n",
"Note that the code in this notebook has been tested with the version of the `ws3` package that is included in this repository. "
]
},
{
"cell_type": "markdown",
"metadata": {},
"source": [
"Set auto-reload to reload modules when they are changed."
]
},
{
"cell_type": "code",
"execution_count": 1,
"metadata": {},
"outputs": [],
"source": [
"%load_ext autoreload\n",
"%autoreload 2"
]
},
{
"cell_type": "code",
"execution_count": 2,
"metadata": {},
"outputs": [
{
"name": "stdout",
"output_type": "stream",
"text": [
"Found existing installation: ws3 1.1.0.dev0\n",
"Uninstalling ws3-1.1.0.dev0:\n",
" Successfully uninstalled ws3-1.1.0.dev0\n",
"Note: you may need to restart the kernel to use updated packages.\n",
"Obtaining file:///home/gep/tmp/ws3\n",
" Installing build dependencies ... \u001b[?25ldone\n",
"\u001b[?25h Checking if build backend supports build_editable ... \u001b[?25ldone\n",
"\u001b[?25h Getting requirements to build editable ... \u001b[?25ldone\n",
"\u001b[?25h Installing backend dependencies ... \u001b[?25ldone\n",
"\u001b[?25h Preparing editable metadata (pyproject.toml) ... \u001b[?25ldone\n",
"\u001b[?25hRequirement already satisfied: dill in /home/gep/tmp/ws3/.venv/lib/python3.12/site-packages (from ws3==1.1.0.dev0) (0.4.0)\n",
"Requirement already satisfied: fiona in /home/gep/tmp/ws3/.venv/lib/python3.12/site-packages (from ws3==1.1.0.dev0) (1.10.1)\n",
"Requirement already satisfied: gurobipy in /home/gep/tmp/ws3/.venv/lib/python3.12/site-packages (from ws3==1.1.0.dev0) (12.0.3)\n",
"Requirement already satisfied: highspy in /home/gep/tmp/ws3/.venv/lib/python3.12/site-packages (from ws3==1.1.0.dev0) (1.11.0)\n",
"Requirement already satisfied: libcbm in /home/gep/tmp/ws3/.venv/lib/python3.12/site-packages (from ws3==1.1.0.dev0) (2.8.1)\n",
"Requirement already satisfied: matplotlib in /home/gep/tmp/ws3/.venv/lib/python3.12/site-packages (from ws3==1.1.0.dev0) (3.10.5)\n",
"Requirement already satisfied: numpy>=1.21 in /home/gep/tmp/ws3/.venv/lib/python3.12/site-packages (from ws3==1.1.0.dev0) (2.2.6)\n",
"Requirement already satisfied: pandas>=1.3 in /home/gep/tmp/ws3/.venv/lib/python3.12/site-packages (from ws3==1.1.0.dev0) (2.3.1)\n",
"Requirement already satisfied: profilehooks in /home/gep/tmp/ws3/.venv/lib/python3.12/site-packages (from ws3==1.1.0.dev0) (1.13.0)\n",
"Requirement already satisfied: pulp in /home/gep/tmp/ws3/.venv/lib/python3.12/site-packages (from ws3==1.1.0.dev0) (3.2.2)\n",
"Requirement already satisfied: rasterio in /home/gep/tmp/ws3/.venv/lib/python3.12/site-packages (from ws3==1.1.0.dev0) (1.4.3)\n",
"Requirement already satisfied: scipy>=1.7 in /home/gep/tmp/ws3/.venv/lib/python3.12/site-packages (from ws3==1.1.0.dev0) (1.16.1)\n",
"Requirement already satisfied: python-dateutil>=2.8.2 in /home/gep/tmp/ws3/.venv/lib/python3.12/site-packages (from pandas>=1.3->ws3==1.1.0.dev0) (2.9.0.post0)\n",
"Requirement already satisfied: pytz>=2020.1 in /home/gep/tmp/ws3/.venv/lib/python3.12/site-packages (from pandas>=1.3->ws3==1.1.0.dev0) (2025.2)\n",
"Requirement already satisfied: tzdata>=2022.7 in /home/gep/tmp/ws3/.venv/lib/python3.12/site-packages (from pandas>=1.3->ws3==1.1.0.dev0) (2025.2)\n",
"Requirement already satisfied: six>=1.5 in /home/gep/tmp/ws3/.venv/lib/python3.12/site-packages (from python-dateutil>=2.8.2->pandas>=1.3->ws3==1.1.0.dev0) (1.17.0)\n",
"Requirement already satisfied: attrs>=19.2.0 in /home/gep/tmp/ws3/.venv/lib/python3.12/site-packages (from fiona->ws3==1.1.0.dev0) (25.3.0)\n",
"Requirement already satisfied: certifi in /home/gep/tmp/ws3/.venv/lib/python3.12/site-packages (from fiona->ws3==1.1.0.dev0) (2025.8.3)\n",
"Requirement already satisfied: click~=8.0 in /home/gep/tmp/ws3/.venv/lib/python3.12/site-packages (from fiona->ws3==1.1.0.dev0) (8.2.1)\n",
"Requirement already satisfied: click-plugins>=1.0 in /home/gep/tmp/ws3/.venv/lib/python3.12/site-packages (from fiona->ws3==1.1.0.dev0) (1.1.1.2)\n",
"Requirement already satisfied: cligj>=0.5 in /home/gep/tmp/ws3/.venv/lib/python3.12/site-packages (from fiona->ws3==1.1.0.dev0) (0.7.2)\n",
"Requirement already satisfied: numexpr>=2.8.7 in /home/gep/tmp/ws3/.venv/lib/python3.12/site-packages (from libcbm->ws3==1.1.0.dev0) (2.11.0)\n",
"Requirement already satisfied: numba in /home/gep/tmp/ws3/.venv/lib/python3.12/site-packages (from libcbm->ws3==1.1.0.dev0) (0.61.2)\n",
"Requirement already satisfied: pyyaml in /home/gep/tmp/ws3/.venv/lib/python3.12/site-packages (from libcbm->ws3==1.1.0.dev0) (6.0.2)\n",
"Requirement already satisfied: mock in /home/gep/tmp/ws3/.venv/lib/python3.12/site-packages (from libcbm->ws3==1.1.0.dev0) (5.2.0)\n",
"Requirement already satisfied: openpyxl in /home/gep/tmp/ws3/.venv/lib/python3.12/site-packages (from libcbm->ws3==1.1.0.dev0) (3.1.5)\n",
"Requirement already satisfied: contourpy>=1.0.1 in /home/gep/tmp/ws3/.venv/lib/python3.12/site-packages (from matplotlib->ws3==1.1.0.dev0) (1.3.3)\n",
"Requirement already satisfied: cycler>=0.10 in /home/gep/tmp/ws3/.venv/lib/python3.12/site-packages (from matplotlib->ws3==1.1.0.dev0) (0.12.1)\n",
"Requirement already satisfied: fonttools>=4.22.0 in /home/gep/tmp/ws3/.venv/lib/python3.12/site-packages (from matplotlib->ws3==1.1.0.dev0) (4.59.0)\n",
"Requirement already satisfied: kiwisolver>=1.3.1 in /home/gep/tmp/ws3/.venv/lib/python3.12/site-packages (from matplotlib->ws3==1.1.0.dev0) (1.4.8)\n",
"Requirement already satisfied: packaging>=20.0 in /home/gep/tmp/ws3/.venv/lib/python3.12/site-packages (from matplotlib->ws3==1.1.0.dev0) (25.0)\n",
"Requirement already satisfied: pillow>=8 in /home/gep/tmp/ws3/.venv/lib/python3.12/site-packages (from matplotlib->ws3==1.1.0.dev0) (11.3.0)\n",
"Requirement already satisfied: pyparsing>=2.3.1 in /home/gep/tmp/ws3/.venv/lib/python3.12/site-packages (from matplotlib->ws3==1.1.0.dev0) (3.2.3)\n",
"Requirement already satisfied: llvmlite<0.45,>=0.44.0dev0 in /home/gep/tmp/ws3/.venv/lib/python3.12/site-packages (from numba->libcbm->ws3==1.1.0.dev0) (0.44.0)\n",
"Requirement already satisfied: et-xmlfile in /home/gep/tmp/ws3/.venv/lib/python3.12/site-packages (from openpyxl->libcbm->ws3==1.1.0.dev0) (2.0.0)\n",
"Requirement already satisfied: affine in /home/gep/tmp/ws3/.venv/lib/python3.12/site-packages (from rasterio->ws3==1.1.0.dev0) (2.4.0)\n",
"Building wheels for collected packages: ws3\n",
" Building editable for ws3 (pyproject.toml) ... \u001b[?25ldone\n",
"\u001b[?25h Created wheel for ws3: filename=ws3-1.1.0.dev0-py3-none-any.whl size=4136 sha256=5df49d1809d2f15004f3046010971c142390fb47fb3bfa7620b09e11903424a7\n",
" Stored in directory: /tmp/pip-ephem-wheel-cache-fjqbp0j3/wheels/fa/4b/10/3fe4b92a02fb87987a6fe53a10fad0a22a781bf98cd7b63f17\n",
"Successfully built ws3\n",
"Installing collected packages: ws3\n",
"Successfully installed ws3-1.1.0.dev0\n",
"Note: you may need to restart the kernel to use updated packages.\n"
]
}
],
"source": [
"clobber_ws3 = True\n",
"if clobber_ws3:\n",
" %pip uninstall -y ws3\n",
" %pip install -e .."
]
},
{
"cell_type": "markdown",
"metadata": {},
"source": [
"Use `pip` to install Python packages listed in `requirements.txt` (some extra packages needed for example notebooks to run correctly)."
]
},
{
"cell_type": "code",
"execution_count": 3,
"metadata": {},
"outputs": [
{
"name": "stdout",
"output_type": "stream",
"text": [
"Requirement already satisfied: seaborn in /home/gep/tmp/ws3/.venv/lib/python3.12/site-packages (from -r requirements.txt (line 1)) (0.13.2)\n",
"Requirement already satisfied: geopandas in /home/gep/tmp/ws3/.venv/lib/python3.12/site-packages (from -r requirements.txt (line 2)) (1.1.1)\n",
"Requirement already satisfied: ipywidgets in /home/gep/tmp/ws3/.venv/lib/python3.12/site-packages (from -r requirements.txt (line 3)) (8.1.7)\n",
"Requirement already satisfied: numpy!=1.24.0,>=1.20 in /home/gep/tmp/ws3/.venv/lib/python3.12/site-packages (from seaborn->-r requirements.txt (line 1)) (2.2.6)\n",
"Requirement already satisfied: pandas>=1.2 in /home/gep/tmp/ws3/.venv/lib/python3.12/site-packages (from seaborn->-r requirements.txt (line 1)) (2.3.1)\n",
"Requirement already satisfied: matplotlib!=3.6.1,>=3.4 in /home/gep/tmp/ws3/.venv/lib/python3.12/site-packages (from seaborn->-r requirements.txt (line 1)) (3.10.5)\n",
"Requirement already satisfied: pyogrio>=0.7.2 in /home/gep/tmp/ws3/.venv/lib/python3.12/site-packages (from geopandas->-r requirements.txt (line 2)) (0.11.1)\n",
"Requirement already satisfied: packaging in /home/gep/tmp/ws3/.venv/lib/python3.12/site-packages (from geopandas->-r requirements.txt (line 2)) (25.0)\n",
"Requirement already satisfied: pyproj>=3.5.0 in /home/gep/tmp/ws3/.venv/lib/python3.12/site-packages (from geopandas->-r requirements.txt (line 2)) (3.7.1)\n",
"Requirement already satisfied: shapely>=2.0.0 in /home/gep/tmp/ws3/.venv/lib/python3.12/site-packages (from geopandas->-r requirements.txt (line 2)) (2.1.1)\n",
"Requirement already satisfied: comm>=0.1.3 in /home/gep/tmp/ws3/.venv/lib/python3.12/site-packages (from ipywidgets->-r requirements.txt (line 3)) (0.2.3)\n",
"Requirement already satisfied: ipython>=6.1.0 in /home/gep/tmp/ws3/.venv/lib/python3.12/site-packages (from ipywidgets->-r requirements.txt (line 3)) (9.4.0)\n",
"Requirement already satisfied: traitlets>=4.3.1 in /home/gep/tmp/ws3/.venv/lib/python3.12/site-packages (from ipywidgets->-r requirements.txt (line 3)) (5.14.3)\n",
"Requirement already satisfied: widgetsnbextension~=4.0.14 in /home/gep/tmp/ws3/.venv/lib/python3.12/site-packages (from ipywidgets->-r requirements.txt (line 3)) (4.0.14)\n",
"Requirement already satisfied: jupyterlab_widgets~=3.0.15 in /home/gep/tmp/ws3/.venv/lib/python3.12/site-packages (from ipywidgets->-r requirements.txt (line 3)) (3.0.15)\n",
"Requirement already satisfied: decorator in /home/gep/tmp/ws3/.venv/lib/python3.12/site-packages (from ipython>=6.1.0->ipywidgets->-r requirements.txt (line 3)) (5.2.1)\n",
"Requirement already satisfied: ipython-pygments-lexers in /home/gep/tmp/ws3/.venv/lib/python3.12/site-packages (from ipython>=6.1.0->ipywidgets->-r requirements.txt (line 3)) (1.1.1)\n",
"Requirement already satisfied: jedi>=0.16 in /home/gep/tmp/ws3/.venv/lib/python3.12/site-packages (from ipython>=6.1.0->ipywidgets->-r requirements.txt (line 3)) (0.19.2)\n",
"Requirement already satisfied: matplotlib-inline in /home/gep/tmp/ws3/.venv/lib/python3.12/site-packages (from ipython>=6.1.0->ipywidgets->-r requirements.txt (line 3)) (0.1.7)\n",
"Requirement already satisfied: pexpect>4.3 in /home/gep/tmp/ws3/.venv/lib/python3.12/site-packages (from ipython>=6.1.0->ipywidgets->-r requirements.txt (line 3)) (4.9.0)\n",
"Requirement already satisfied: prompt_toolkit<3.1.0,>=3.0.41 in /home/gep/tmp/ws3/.venv/lib/python3.12/site-packages (from ipython>=6.1.0->ipywidgets->-r requirements.txt (line 3)) (3.0.51)\n",
"Requirement already satisfied: pygments>=2.4.0 in /home/gep/tmp/ws3/.venv/lib/python3.12/site-packages (from ipython>=6.1.0->ipywidgets->-r requirements.txt (line 3)) (2.19.2)\n",
"Requirement already satisfied: stack_data in /home/gep/tmp/ws3/.venv/lib/python3.12/site-packages (from ipython>=6.1.0->ipywidgets->-r requirements.txt (line 3)) (0.6.3)\n",
"Requirement already satisfied: wcwidth in /home/gep/tmp/ws3/.venv/lib/python3.12/site-packages (from prompt_toolkit<3.1.0,>=3.0.41->ipython>=6.1.0->ipywidgets->-r requirements.txt (line 3)) (0.2.13)\n",
"Requirement already satisfied: parso<0.9.0,>=0.8.4 in /home/gep/tmp/ws3/.venv/lib/python3.12/site-packages (from jedi>=0.16->ipython>=6.1.0->ipywidgets->-r requirements.txt (line 3)) (0.8.4)\n",
"Requirement already satisfied: contourpy>=1.0.1 in /home/gep/tmp/ws3/.venv/lib/python3.12/site-packages (from matplotlib!=3.6.1,>=3.4->seaborn->-r requirements.txt (line 1)) (1.3.3)\n",
"Requirement already satisfied: cycler>=0.10 in /home/gep/tmp/ws3/.venv/lib/python3.12/site-packages (from matplotlib!=3.6.1,>=3.4->seaborn->-r requirements.txt (line 1)) (0.12.1)\n",
"Requirement already satisfied: fonttools>=4.22.0 in /home/gep/tmp/ws3/.venv/lib/python3.12/site-packages (from matplotlib!=3.6.1,>=3.4->seaborn->-r requirements.txt (line 1)) (4.59.0)\n",
"Requirement already satisfied: kiwisolver>=1.3.1 in /home/gep/tmp/ws3/.venv/lib/python3.12/site-packages (from matplotlib!=3.6.1,>=3.4->seaborn->-r requirements.txt (line 1)) (1.4.8)\n",
"Requirement already satisfied: pillow>=8 in /home/gep/tmp/ws3/.venv/lib/python3.12/site-packages (from matplotlib!=3.6.1,>=3.4->seaborn->-r requirements.txt (line 1)) (11.3.0)\n",
"Requirement already satisfied: pyparsing>=2.3.1 in /home/gep/tmp/ws3/.venv/lib/python3.12/site-packages (from matplotlib!=3.6.1,>=3.4->seaborn->-r requirements.txt (line 1)) (3.2.3)\n",
"Requirement already satisfied: python-dateutil>=2.7 in /home/gep/tmp/ws3/.venv/lib/python3.12/site-packages (from matplotlib!=3.6.1,>=3.4->seaborn->-r requirements.txt (line 1)) (2.9.0.post0)\n",
"Requirement already satisfied: pytz>=2020.1 in /home/gep/tmp/ws3/.venv/lib/python3.12/site-packages (from pandas>=1.2->seaborn->-r requirements.txt (line 1)) (2025.2)\n",
"Requirement already satisfied: tzdata>=2022.7 in /home/gep/tmp/ws3/.venv/lib/python3.12/site-packages (from pandas>=1.2->seaborn->-r requirements.txt (line 1)) (2025.2)\n",
"Requirement already satisfied: ptyprocess>=0.5 in /home/gep/tmp/ws3/.venv/lib/python3.12/site-packages (from pexpect>4.3->ipython>=6.1.0->ipywidgets->-r requirements.txt (line 3)) (0.7.0)\n",
"Requirement already satisfied: certifi in /home/gep/tmp/ws3/.venv/lib/python3.12/site-packages (from pyogrio>=0.7.2->geopandas->-r requirements.txt (line 2)) (2025.8.3)\n",
"Requirement already satisfied: six>=1.5 in /home/gep/tmp/ws3/.venv/lib/python3.12/site-packages (from python-dateutil>=2.7->matplotlib!=3.6.1,>=3.4->seaborn->-r requirements.txt (line 1)) (1.17.0)\n",
"Requirement already satisfied: executing>=1.2.0 in /home/gep/tmp/ws3/.venv/lib/python3.12/site-packages (from stack_data->ipython>=6.1.0->ipywidgets->-r requirements.txt (line 3)) (2.2.0)\n",
"Requirement already satisfied: asttokens>=2.1.0 in /home/gep/tmp/ws3/.venv/lib/python3.12/site-packages (from stack_data->ipython>=6.1.0->ipywidgets->-r requirements.txt (line 3)) (3.0.0)\n",
"Requirement already satisfied: pure-eval in /home/gep/tmp/ws3/.venv/lib/python3.12/site-packages (from stack_data->ipython>=6.1.0->ipywidgets->-r requirements.txt (line 3)) (0.2.3)\n",
"Note: you may need to restart the kernel to use updated packages.\n"
]
}
],
"source": [
"%pip install -r requirements.txt"
]
},
{
"cell_type": "markdown",
"metadata": {},
"source": [
"Import required packages."
]
},
{
"cell_type": "code",
"execution_count": 4,
"metadata": {},
"outputs": [],
"source": [
"import matplotlib.pyplot as plt\n",
"import ws3\n",
"import ws3.forest\n",
"import functools\n",
"import pandas as pd"
]
},
{
"cell_type": "markdown",
"metadata": {},
"source": [
"## Set up ``ForestModel`` instance"
]
},
{
"cell_type": "markdown",
"metadata": {},
"source": [
"Set some reasonable model parameters."
]
},
{
"cell_type": "code",
"execution_count": 5,
"metadata": {},
"outputs": [],
"source": [
"base_year = 2020 # base year for the problem\n",
"horizon = 10 # number of periods in the simulation horizon\n",
"period_length = 10 # period length (in years)\n",
"max_age = 1000 # maximum age of a stand (in years)\n",
"tvy_name = \"totvol\" # name for total volume yield component\n"
]
},
{
"cell_type": "markdown",
"metadata": {},
"source": [
"Create a new `ForestModel` object and import a model dataset from the `data` directory."
]
},
{
"cell_type": "code",
"execution_count": 6,
"metadata": {},
"outputs": [],
"source": [
"fm = ws3.forest.ForestModel(model_name=\"tsa24_clipped\",\n",
" model_path=\"data/woodstock_model_files_tsa24_clipped\",\n",
" base_year=base_year,\n",
" horizon=horizon,\n",
" period_length=period_length,\n",
" max_age=max_age)\n",
"fm.import_landscape_section()\n",
"fm.import_areas_section(convert_periods_to_years=period_length)\n",
"fm.import_yields_section(convert_periods_to_years=period_length)\n",
"fm.import_actions_section(convert_periods_to_years=period_length)\n",
"fm.import_transitions_section(convert_periods_to_years=period_length)\n",
"fm.initialize_areas()\n",
"fm.add_null_action()\n",
"fm.reset_actions()\n",
"\n",
"fm.actions[\"harvest\"].is_harvest = True # set harvest action to be a harvest action (needed for `cmp_c_z` to work correctly)\n"
]
},
{
"cell_type": "markdown",
"metadata": {},
"source": [
"## Explore optimization modelling functions"
]
},
{
"cell_type": "markdown",
"metadata": {},
"source": [
"### Define a base scenario (maximizing harvest volume)\n",
"\n",
"We will start by defining a basic optimization problem, where we simply maximize the sum of harvest volume across all time periods. \n",
"\n",
"The optimization functions in `ws3` are very flexible, but this flexibility comes at a cost: the user has to define various functions that generate the linear programming (LP) optimization problem matrix coefficients.\n",
"\n",
"We will start by defining a function `cmp_c_z` (you can use any name you want for coefficient functions) that returns the objective function coefficient for a single column in the matrix. Note that `ws3` is using a Model I formulation of the LP problem, where each column of the matrix represents a unique feasible combination of actions across all time periods (for a given combination of development type and initial age class). Internally `ws3` handles iterating through each development type/age class combination, and generating dynamic programming state trees, where each unique _path_ from the root node of a tree through to a leaf node is represented by a unique column in the matrix. Each path has one node per time period in the simulation horizon.\n",
"\n",
"The `cmp_c_z` function will be used by `ws3` to generate the coefficients for each column in the matrix. The `cmp_c_z` function takes three arguments: the first argument is a `ForestModel instance`, the second argument is a `path` (a list of node objects), and the third argument is an `expr` (a string expression that evaluates to a number, which we pass to the `ForestModel.compile_product` method).\n",
"\n",
"See the [ws3 documentation](https://ws3.readthedocs.org) for more information about what types of expressions `ws3` can resolve in this context. For our example we will use a simple expression that multiplies total merchantable volume in the `totvol` yield component by 0.85 to simulate an 85% fibre utilization rate (i.e., 15% of total merchnantable volume is left behind as harvest residues in slash piles or spread across cut blocks).\n"
]
},
{
"cell_type": "markdown",
"metadata": {},
"source": [
"The Model I LP optimization problem can be formulated as follows:\n",
"\n",
"$$\n",
"\\begin{align}\n",
" \\text{max} \\quad & \\sum_{i\\in I}\\sum_{j \\in J_{i}}c_{ij}x_{ij} & \\\\\n",
" \\text{s.t.} \\quad & \\nonumber \\\\\n",
" &(1-\\varepsilon_{p})y_p \\leq \\sum_{i\\in I}\\sum_{j\\in J_{i}}\\mu_{ijpt}x_{ij} \\leq (1+\\varepsilon_{p})y_p, & \\forall p\\in O', t\\in T'_p \\\\\n",
" &v^{-}_{ot}\\leq\\sum_{i\\in Z}\\sum_{j\\in J_{i}}\\mu_{ijot}x_{ij} \\leq v^{+}_{ot}, & \\forall o\\in O, t\\in T \\\\\n",
" &\\sum_{j\\in J_{i}}x_{ij} = 1, \\forall i\\in Z \\\\\n",
" &0 \\leq x_{ij} \\leq 1, & \\forall i \\in Z, j \\in J_{i} \n",
"\\end{align}\n",
"$$\n",
"\n",
"where\n",
"\n",
"$$\n",
"\\begin{align*}\n",
" I := & \\,\\, \\text{set of spatial zones}\\\\\n",
" J_{i} := & \\,\\, \\text{set of available prescriptions for zone $i \\in I$}\\\\\n",
" O := & \\,\\, \\text{set of forest outputs}\\\\\n",
" O' \\subseteq O := & \\,\\, \\text{set of targeted forest outputs}\\\\\n",
" T := & \\,\\, \\text{set of time periods in the planning horizon}\\\\\n",
" T'_p \\subseteq O := & \\,\\, \\text{subset of $T$ on which even-flow constraints for output $p \\in O^{\\prime}$ are applied}\\\\\n",
" \\varepsilon_{p} := & \\,\\, \\text{admissible level of variation on yield of targeted output $p \\in O^{\\prime}$} \\\\\n",
" \\mu_{ijot} := & \\,\\, \\text{quantity of output $o \\in O$ produced in period $t \\in T$ by prescription $j \\in J_{i}$}\\\\\n",
" & \\,\\, \\text{in zone $i \\in I$}\\\\\n",
" \\mu_{ijpt} := & \\,\\, \\text{quantity of output $p \\in O'$ produced in period $t \\in T$ by prescription $j \\in J_{i}$}\\\\\n",
" & \\,\\, \\text{in zone $i \\in I$}\\\\\n",
" v^{-}_{ot} := & \\,\\, \\text{lower bound on yield of output $o \\in O$ in period $t \\in T$} \\\\\n",
" v^{+}_{ot} := & \\,\\, \\text{upper bound on yield of output $o \\in O$ in period $t \\in T$} \\\\\n",
" c_{ij} := & \\,\\, \\text{objective function contribution of prescription $j \\in J_{i}$ in zone $i \\in I$} \\\\\n",
" x_{ij} := & \\,\\, \\text{proportion of zone $i \\in Z$ on which prescription $j \\in J_{i}$ is applied} \\\\\n",
" y_p = & \\sum_{i\\in I}\\sum_{j\\in J_i}\\mu_{ijpt^R_p}x_{ij}\\text{, i.e. total yield of targeted output $p \\in O'$ at reference period $t^R_p$} \n",
"\\end{align*}\n",
"$$"
]
},
{
"cell_type": "markdown",
"metadata": {},
"source": [
"\n",
"The objective function (1) maximizes the sum of $c_{ij}x_{ij}$ products, which represent yield of a user-defined output---the output can be anything, but will typically be harvest volume or harvested area.\n",
"\n",
"The variables $x_{ij}$ are linear, with domain $\\{x_{ij} \\in \\mathbb{R}|0 \\leq x_{ij} \\leq 1\\}$ specified in (5).\n",
"\n",
"The set $O^{\\prime} \\subseteq O$ represents targeted outputs, for which we enforce even-flow constraints. Even-flow constraints are defined in (2), and are expressed in terms of $y_p$, which represents total yield of targeted output $p \\in O^{\\prime}$ in reference period $t^R_p$. Note that even-flow constraints are defined over time periods $T'_p$, which is any subset of $T$ (need not be contiguous)---$T'_p$ can be unique for each output $p \\in O^{\\prime}$.\n",
"\n",
"General constraints (3) set upper and lower bounds on periodic yield of any output $o \\in O$---we can use these constraints to set minimum or maximum periodic levels of any indicators that we can formulate from data in the model (e.g., set an upper bount on harvest volume in the first period, or set a lower bound on growing stock in the final period).\n",
"\n",
"Coverage constraints (4) are accounting constraints that force prescriptions to cover the entire zone---doing nothing for the entire planning horizon is considered a prescription that could generate some outputs. This maintains the structure of the model, and these are automatically defined and set by `ws3` (i.e., the user does not need to define these constraints as part of optimization model input)."
]
},
{
"cell_type": "code",
"execution_count": 7,
"metadata": {},
"outputs": [],
"source": [
"def cmp_c_z(fm, path, expr):\n",
" \"\"\"\n",
" Compile objective function coefficient (given ForestModel instance, \n",
" root-to-leaf state tree node path, and an expression that resolves to the correct product unit).\n",
" \n",
" This function iterates over the specified node path in a state tree, \n",
" checks if each node corresponds to a harvest operation, and adds up the compiled product values for these nodes.\n",
" \n",
" Parameters:\n",
" fm (ForestModel): The ForestModel instance containing the necessary information.\n",
" path (list of Node objects): A list of root-to-leaf nodes forming a path through a state tree.\n",
" expr (str): An expression resolving to the correct product unit.\n",
" \n",
" Returns:\n",
" float: The compiled objective function coefficient.\n",
" \"\"\"\n",
" result = 0. # Initialize the result variable\n",
" for t, n in enumerate(path, start=1): # Iterate over the node path with index and value\n",
" d = n.data() # Get the data from the current node\n",
" if fm.is_harvest(d[\"acode\"]): # Check if the current node corresponds to a harvest operation\n",
" result += fm.compile_product(t, expr, d[\"acode\"], [d[\"dtk\"]], d[\"age\"], coeff=False) # Add up the compiled product values\n",
" return result # Return the final compiled objective function coefficient\n"
]
},
{
"cell_type": "markdown",
"metadata": {},
"source": [
"Note that a decision variables in the Model I problem represents a proportion of the total area in a given tree that is assigned to a given path (sequence of actions), and that the sum of all decision variables corresponding to a given tree is automatically constrained to sum to 1. As such, the objective function coefficients should represent absolute yield (e.g., $m^3$ for harvest volume, not $m^3 ha^{-1}$)."
]
},
{
"cell_type": "markdown",
"metadata": {},
"source": [
"Next we define the `coeff_funcs` dictionary, which maps matrix row names to the functions that we defined that generate the correct coefficients for each column of the matrix in that row. In this simple we only map row `z` names to the `cmp_c_z` function that we defined above. This tells the `ForestModel.add_problem` method to use the `cmp_c_z` function to compile the objective function coefficients (the objective function is named `z` by default in the `ForestModel.add_problem` method arg signature definition, so if we map a function to name `z` in `coeff_funcs` it will automatically pick that up as the objective function coefficient function).\n",
"\n",
"Note that the `add_problem` method assumes that all coefficient functions passed to `coeff_funcs` will have exactly two arguments (a `ForestModel` instance and a `Path` instance). If this is not the case then you will need to define a wrapper function that rewrites the function signature (see the example below using `functools.partial`)."
]
},
{
"cell_type": "code",
"execution_count": 8,
"metadata": {},
"outputs": [],
"source": [
"expr = \"0.85 * totvol\"\n",
"coeff_funcs = {\"z\":functools.partial(cmp_c_z, expr=expr)}\n"
]
},
{
"cell_type": "markdown",
"metadata": {},
"source": [
"Now we are ready to call the `ForestModel.add_problem` method, which will build the optimization problem (including the objective function coefficients from the function we provided) and add the problem to the model under the name `'scenario-1'`. The `add_problem` method returns an instance of the `Problem` class that we can use to solve the LP problem and access the optimal solution (which we will compile into a `ws3` action schedule so we can simulate it out and plot results in a human-readable way). \n",
"\n",
"We pass `None` value to the `cflw_e` and `cgen_data` arguments because there are no flow or general constraints in this problem.\n",
"\n",
"We pass `'null'` and `'harvest'` values to the `acodes` argument because these are the action we want to include in the generation of the Model 1 state trees in this problem. This allows us to define complex `ForestModel` base models, which potentially define a wide range of actions, without being required to always include all the defined actions in all the optimization problems. It is required to define a _null_ action in the `ForestModel` instance before calling the `add_problem` method (the `ForestModel.add_null_action` method makes it easy to correctly define a null action), and you must include the name of the null action in the list of action codes passed to the `acodes` argument of the `add_problem` method. Including a null action allows the optimization problem to simulate doing nothing (i.e., just letting the forest grow). If you want to include all the actions defined in the `ForestModel`, pass `None` value to the `acodes` argument of the `add_problem` method.\n",
"\n",
"We pass `None` to the `mask` argument because we want to include all the development types in this problem. You can filter which developments are included in a given problem by passing a valid mask (either in tuple format or as a Woodstock-style mask string). See the [ws3 documentation](https://ws3.readthedocs.org) for more information about themes and masks (including how to define aggregate landscape codes to match multiple values within one theme in a mask).\n",
"\n",
"Note also that the objective function sense gets defined at this point by passing the `sense` argument to the `add_problem` method. The `sense` argument can be either `ws3.opt.SENSE_MINIMIZE` or `ws3.opt.SENSE_MAXIMIZE`."
]
},
{
"cell_type": "code",
"execution_count": 9,
"metadata": {},
"outputs": [],
"source": [
"problem = fm.add_problem(name=\"scenario-1\",\n",
" coeff_funcs=coeff_funcs, \n",
" cflw_e=None, \n",
" cgen_data=None, \n",
" acodes=(\"null\", \"harvest\"),\n",
" sense=ws3.opt.SENSE_MAXIMIZE, \n",
" mask=None)"
]
},
{
"cell_type": "markdown",
"metadata": {},
"source": [
"Now that we have a `Problem` object instance, we can call the `solve` method to try to solve the problem. \n",
"\n",
"This will use the default bindings to the open source HiGHS solver (see the [HiGHS documentation](https://www.highs.dev/) for details on HiGHS) to find a solution that maximizes the objective. "
]
},
{
"cell_type": "code",
"execution_count": 10,
"metadata": {},
"outputs": [
{
"name": "stdout",
"output_type": "stream",
"text": [
"Running HiGHS 1.11.0 (git hash: 364c83a): Copyright (c) 2025 HiGHS under MIT licence terms\n",
"LP has 32 rows; 305 cols; 305 nonzeros\n",
"Coefficient ranges:\n",
" Matrix [1e+00, 1e+00]\n",
" Cost [2e+01, 4e+04]\n",
" Bound [1e+00, 1e+00]\n",
" RHS [1e+00, 1e+00]\n",
"Presolving model\n",
"24 rows, 115 cols, 115 nonzeros 0s\n",
"0 rows, 0 cols, 0 nonzeros 0s\n",
"Presolve : Reductions: rows 0(-32); columns 0(-305); elements 0(-305) - Reduced to empty\n",
"Solving the original LP from the solution after postsolve\n",
"Using EKK primal simplex solver\n",
" Iteration Objective Infeasibilities num(sum)\n",
" 0 -2.2455249290e+05 Pr: 0(0); Du: 222(1.63573e+06) 0s\n",
" 19 -2.2455284502e+05 Pr: 0(0) 0s\n",
"Required 19 simplex iterations after postsolve\n",
"Model status : Optimal\n",
"Simplex iterations: 19\n",
"Objective value : -2.2455284502e+05\n",
"P-D objective error : 6.4803823015e-17\n",
"HiGHS run time : 0.00\n"
]
}
],
"source": [
"problem.solve(verbose=True)"
]
},
{
"cell_type": "markdown",
"metadata": {},
"source": [
"We can use the `Problem.status` method to check the status of the solution (i.e., to confirm that the problem was solved to optimality)."
]
},
{
"cell_type": "code",
"execution_count": 11,
"metadata": {},
"outputs": [
{
"name": "stdout",
"output_type": "stream",
"text": [
"Hooray! We have an optimal solution!\n"
]
}
],
"source": [
"if (problem.status() == ws3.opt.STATUS_OPTIMAL):\n",
" print(\"Hooray! We have an optimal solution!\")\n"
]
},
{
"cell_type": "markdown",
"metadata": {},
"source": [
"We can use the `Problem.z` method to check the value of the objective function at the optimal solution."
]
},
{
"cell_type": "code",
"execution_count": 12,
"metadata": {},
"outputs": [
{
"name": "stdout",
"output_type": "stream",
"text": [
"The optimal value of the objective function is: 224552.84502455403\n"
]
}
],
"source": [
"print(\"The optimal value of the objective function is: {}\".format(problem.z()))\n"
]
},
{
"cell_type": "markdown",
"metadata": {},
"source": [
"This matches the value reported by HiGHS in the solver `stdout` console output in a previous step."
]
},
{
"cell_type": "markdown",
"metadata": {},
"source": [
"Next, we need to extract the optimal sequence of actions from the `Problem` instance and compile it into a format that can be used as input to the `ForestModel.apply_schedule` method. We can use the `ForestModel.compile_schedule` method to do this. Internally this dispatches the call to private method `ForestModel._cmp_sch_m1`, which is aware of the Model I optimization problem structure and correctly walks through all the `Node` objects in all the `Path` objects in all the `Tree` objects in the `Problem` instance that was passed in as an argument, extracting the required data (i.e., `DevelopmentType` key, age, actionned area, action code, period, existing/future `DevelopmentType` status) from the `data` dictionary of each `Node` object and assembling this information into a correctly formatted list of tuples that can be consumed by `ForestModel.apply_action`."
]
},
{
"cell_type": "code",
"execution_count": 13,
"metadata": {},
"outputs": [
{
"data": {
"text/plain": [
"[(('tsa24_clipped', '1', '2401002', '204', '2401002'),\n",
" 85,\n",
" 282.1296355046733,\n",
" 'harvest',\n",
" 1,\n",
" '_existing'),\n",
" (('tsa24_clipped', '1', '2401002', '204', '2401002'),\n",
" 91,\n",
" 73.1021561503533,\n",
" 'harvest',\n",
" 1,\n",
" '_existing'),\n",
" (('tsa24_clipped', '1', '2401002', '204', '2401002'),\n",
" 93,\n",
" 28.37956666951611,\n",
" 'harvest',\n",
" 1,\n",
" '_existing'),\n",
" (('tsa24_clipped', '1', '2401002', '204', '2401002'),\n",
" 95,\n",
" 94.94675966211176,\n",
" 'harvest',\n",
" 1,\n",
" '_existing'),\n",
" (('tsa24_clipped', '1', '2401002', '204', '2401002'),\n",
" 105,\n",
" 32.175418531537815,\n",
" 'harvest',\n",
" 1,\n",
" '_existing'),\n",
" (('tsa24_clipped', '1', '2401002', '204', '2401002'),\n",
" 113,\n",
" 4.184826329641321,\n",
" 'harvest',\n",
" 1,\n",
" '_existing'),\n",
" (('tsa24_clipped', '1', '2401002', '204', '2401002'),\n",
" 115,\n",
" 50.030816858894816,\n",
" 'harvest',\n",
" 1,\n",
" '_existing'),\n",
" (('tsa24_clipped', '1', '2401002', '204', '2401002'),\n",
" 125,\n",
" 78.16612132001225,\n",
" 'harvest',\n",
" 1,\n",
" '_existing'),\n",
" (('tsa24_clipped', '1', '2401002', '204', '2401002'),\n",
" 135,\n",
" 72.24421919373785,\n",
" 'harvest',\n",
" 1,\n",
" '_existing'),\n",
" (('tsa24_clipped', '1', '2401002', '204', '2401002'),\n",
" 145,\n",
" 96.38442685503642,\n",
" 'harvest',\n",
" 1,\n",
" '_existing'),\n",
" (('tsa24_clipped', '1', '2401002', '204', '2401002'),\n",
" 153,\n",
" 9.591469412607397,\n",
" 'harvest',\n",
" 1,\n",
" '_existing'),\n",
" (('tsa24_clipped', '1', '2401002', '204', '2401002'),\n",
" 155,\n",
" 34.32629241113743,\n",
" 'harvest',\n",
" 1,\n",
" '_existing'),\n",
" (('tsa24_clipped', '1', '2402000', '100', '2402000'),\n",
" 165,\n",
" 0.638005468748551,\n",
" 'harvest',\n",
" 1,\n",
" '_existing'),\n",
" (('tsa24_clipped', '1', '2402002', '204', '2402002'),\n",
" 93,\n",
" 48.21816452980633,\n",
" 'harvest',\n",
" 1,\n",
" '_existing'),\n",
" (('tsa24_clipped', '1', '2402002', '204', '2402002'),\n",
" 95,\n",
" 33.89498244313859,\n",
" 'harvest',\n",
" 1,\n",
" '_existing'),\n",
" (('tsa24_clipped', '1', '2402002', '204', '2402002'),\n",
" 115,\n",
" 3.195378954654358,\n",
" 'harvest',\n",
" 1,\n",
" '_existing'),\n",
" (('tsa24_clipped', '1', '2403000', '100', '2403000'),\n",
" 93,\n",
" 14.811643286926836,\n",
" 'harvest',\n",
" 1,\n",
" '_existing'),\n",
" (('tsa24_clipped', '1', '2402002', '204', '2402002'),\n",
" 88,\n",
" 32.64168183055375,\n",
" 'harvest',\n",
" 2,\n",
" '_existing'),\n",
" (('tsa24_clipped', '1', '2403002', '204', '2403002'),\n",
" 83,\n",
" 2.243990590272984,\n",
" 'harvest',\n",
" 2,\n",
" '_existing'),\n",
" (('tsa24_clipped', '1', '2401002', '204', '2401002'),\n",
" 168,\n",
" 103.76740323520823,\n",
" 'harvest',\n",
" 10,\n",
" '_existing'),\n",
" (('tsa24_clipped', '1', '2401002', '204', '2401002'),\n",
" 170,\n",
" 4.173147018452507,\n",
" 'harvest',\n",
" 10,\n",
" '_existing'),\n",
" (('tsa24_clipped', '1', '2401002', '204', '2421002'),\n",
" 90,\n",
" 282.1296355046733,\n",
" 'harvest',\n",
" 10,\n",
" '_existing'),\n",
" (('tsa24_clipped', '1', '2401002', '204', '2421002'),\n",
" 90,\n",
" 73.1021561503533,\n",
" 'harvest',\n",
" 10,\n",
" '_existing'),\n",
" (('tsa24_clipped', '1', '2401002', '204', '2421002'),\n",
" 90,\n",
" 28.37956666951611,\n",
" 'harvest',\n",
" 10,\n",
" '_existing'),\n",
" (('tsa24_clipped', '1', '2401002', '204', '2421002'),\n",
" 90,\n",
" 94.94675966211176,\n",
" 'harvest',\n",
" 10,\n",
" '_existing'),\n",
" (('tsa24_clipped', '1', '2401002', '204', '2421002'),\n",
" 90,\n",
" 32.175418531537815,\n",
" 'harvest',\n",
" 10,\n",
" '_existing'),\n",
" (('tsa24_clipped', '1', '2401002', '204', '2421002'),\n",
" 90,\n",
" 4.184826329641321,\n",
" 'harvest',\n",
" 10,\n",
" '_existing'),\n",
" (('tsa24_clipped', '1', '2401002', '204', '2421002'),\n",
" 90,\n",
" 50.030816858894816,\n",
" 'harvest',\n",
" 10,\n",
" '_existing'),\n",
" (('tsa24_clipped', '1', '2401002', '204', '2421002'),\n",
" 90,\n",
" 78.16612132001225,\n",
" 'harvest',\n",
" 10,\n",
" '_existing'),\n",
" (('tsa24_clipped', '1', '2401002', '204', '2421002'),\n",
" 90,\n",
" 72.24421919373785,\n",
" 'harvest',\n",
" 10,\n",
" '_existing'),\n",
" (('tsa24_clipped', '1', '2401002', '204', '2421002'),\n",
" 90,\n",
" 96.38442685503642,\n",
" 'harvest',\n",
" 10,\n",
" '_existing'),\n",
" (('tsa24_clipped', '1', '2401002', '204', '2421002'),\n",
" 90,\n",
" 9.591469412607397,\n",
" 'harvest',\n",
" 10,\n",
" '_existing'),\n",
" (('tsa24_clipped', '1', '2401002', '204', '2421002'),\n",
" 90,\n",
" 34.32629241113743,\n",
" 'harvest',\n",
" 10,\n",
" '_existing'),\n",
" (('tsa24_clipped', '1', '2401002', '204', '2421002'),\n",
" 110,\n",
" 0.422054121206099,\n",
" 'harvest',\n",
" 10,\n",
" '_existing'),\n",
" (('tsa24_clipped', '1', '2402000', '100', '2422000'),\n",
" 90,\n",
" 0.638005468748551,\n",
" 'harvest',\n",
" 10,\n",
" '_existing'),\n",
" (('tsa24_clipped', '1', '2402002', '204', '2422002'),\n",
" 80,\n",
" 32.64168183055375,\n",
" 'harvest',\n",
" 10,\n",
" '_existing'),\n",
" (('tsa24_clipped', '1', '2402002', '204', '2422002'),\n",
" 90,\n",
" 48.21816452980633,\n",
" 'harvest',\n",
" 10,\n",
" '_existing'),\n",
" (('tsa24_clipped', '1', '2402002', '204', '2422002'),\n",
" 90,\n",
" 33.89498244313859,\n",
" 'harvest',\n",
" 10,\n",
" '_existing'),\n",
" (('tsa24_clipped', '1', '2402002', '204', '2422002'),\n",
" 90,\n",
" 3.195378954654358,\n",
" 'harvest',\n",
" 10,\n",
" '_existing'),\n",
" (('tsa24_clipped', '1', '2403000', '100', '2423000'),\n",
" 90,\n",
" 14.811643286926836,\n",
" 'harvest',\n",
" 10,\n",
" '_existing'),\n",
" (('tsa24_clipped', '1', '2403002', '204', '2423002'),\n",
" 80,\n",
" 2.243990590272984,\n",
" 'harvest',\n",
" 10,\n",
" '_existing'),\n",
" (('tsa24_clipped', '1', '2403002', '204', '2423002'),\n",
" 99,\n",
" 59.81429119367274,\n",
" 'harvest',\n",
" 10,\n",
" '_existing'),\n",
" (('tsa24_clipped', '1', '2403002', '204', '2423002'),\n",
" 108,\n",
" 32.366198551219505,\n",
" 'harvest',\n",
" 10,\n",
" '_existing')]"
]
},
"execution_count": 13,
"metadata": {},
"output_type": "execute_result"
}
],
"source": [
"schedule = fm.compile_schedule(problem)\n",
"schedule"
]
},
{
"cell_type": "markdown",
"metadata": {},
"source": [
"As you can see, the schedule is just a list of 6-element tuples. \n",
"\n",
"The first element in each tuple is the `DevelopmentType` key (a tuple of landscape theme strings).\n",
"\n",
"The other elements in the tuple specify the age, actionned area, action code, period, and existing/future `DevelopmentType` status. "
]
},
{
"cell_type": "markdown",
"metadata": {},
"source": [
"Now we that we have a compiled schedule, we can use it as input for the `ForestModel.apply_schedule` method using the following parameters:\n",
"- `force_integral_area`: Set to `False` to avoid forcing integral area calculations\n",
"- `override_operability`: Set to `False` to avoid overriding operability calculations\n",
"- `fuzzy_age`: Set to `False` to disable fuzzy age calculations\n",
"- `recourse_enabled`: Set to `False` to disable recourse-enabled mode\n",
"- `verbose`: Set to `False` for quiet operation\n",
"- `compile_c_ycomps`: Set to `True` to enable compilation of complex yield components\n",
"\n",
"See the [ws3 documentation](https://ws3.readthedocs.org) for the `ForestModel.apply_schedule` and `ForestModel.apply_action` methods for more information about these and other parameters that are available to controls exactly how actions get applied to the model. Ultimately, the `apply_schedule` method is a wrapper around the `apply_action` method. The `apply_action` method will handle the details of applying individual actions to the model. One of the main functions of `ws3` (and any forest estate model) is to simulate forest response to sequences of actions interleaved with periods of growth. Given the core role of the `apply_action` method, it is not surprising that it has a large number of parameters that can be used to control exactly how actions are applied.\n",
"\n",
"This effectively resets the current schedule and model state to the initial state, and runs a sequential multi-period simulation of alternating actions and periods of growth. "
]
},
{
"cell_type": "code",
"execution_count": 14,
"metadata": {},
"outputs": [
{
"data": {
"text/plain": [
"0.0"
]
},
"execution_count": 14,
"metadata": {},
"output_type": "execute_result"
}
],
"source": [
"\n",
"fm.apply_schedule(\n",
" schedule, \n",
" force_integral_area=False, \n",
" override_operability=False,\n",
" fuzzy_age=False,\n",
" recourse_enabled=False,\n",
" verbose=False,\n",
" compile_c_ycomps=True\n",
")"
]
},
{
"cell_type": "markdown",
"metadata": {},
"source": [
"At this point, our `ForestModel` object has simulated sequential application of the optimal schedule of activities we created in a previous step."
]
},
{
"cell_type": "markdown",
"metadata": {},
"source": [
"Next, we compile some relevant performance indicators to summarize what is going in this optimal solution (i.e., periodic harvested area, periodic harvest volume, periodic growing stock).\n",
"\n",
"First, we compile the harvested area and volume indicators. We use the `ForestModel.ompile_product` method to compile these indicators. The first argument is the period for which we want to compile a product output, while the second argument is the expression that will be resolved by `ws3` to compute a yield coefficient. The `compile_product` method compiles the product of actionned area and whatever yield coefficient the provided expression resolves to (expressed in _units of output product per unit of area_, e.g., $m^3/ha$ for harvested volume or $ha/ha$ for harvested area). So, when we use an expression value of `1.` for the second argument of the `compile_product` method, we are telling `ws3` that we want to _pass through_ the actionned area indicator that it is calculating internally. We use the `acode` argument to specify which action code to use (i.e., `harvest` to compile harvested area and harvested volume indicators).\n",
"\n",
"We use the `ForestModel.inventory` method to compile the growing stock indicator. The first argument is the period for which we want to compile an inventory output, while the second argument is the expression that will be resolved by `ws3` to compute a yield coefficient (in this case we use the total volume of trees multiplied by an assumed utilization rate of 85%). \n",
"\n",
"See the [ws3 documentation](https://ws3.readthedocs.org) for more information on expression evaluation, and what types of expressions are supported by `ws3` that can be provided as input to `compile_product` and `inventory` method calls.\n",
"\n",
"Once we have compiled our raw indictor outputs into lists (with one value period, including a data column of period index values), we stuff all of this into a dictionary and create a new `pandas.DataFrame` to hold our compiled data. "
]
},
{
"cell_type": "code",
"execution_count": 15,
"metadata": {},
"outputs": [
{
"data": {
"text/html": [
"
\n",
"\n",
"
\n",
" \n",
"
\n",
"
\n",
"
period
\n",
"
oha
\n",
"
ohv
\n",
"
ogs
\n",
"
\n",
" \n",
" \n",
"
\n",
"
0
\n",
"
1
\n",
"
956.419884
\n",
"
102585.020390
\n",
"
30405.125309
\n",
"
\n",
"
\n",
"
1
\n",
"
2
\n",
"
34.885672
\n",
"
4798.494437
\n",
"
28607.304394
\n",
"
\n",
"
\n",
"
2
\n",
"
3
\n",
"
0.000000
\n",
"
0.000000
\n",
"
32154.392350
\n",
"
\n",
"
\n",
"
3
\n",
"
4
\n",
"
0.000000
\n",
"
0.000000
\n",
"
38166.885368
\n",
"
\n",
"
\n",
"
4
\n",
"
5
\n",
"
0.000000
\n",
"
0.000000
\n",
"
47379.394949
\n",
"
\n",
"
\n",
"
5
\n",
"
6
\n",
"
0.000000
\n",
"
0.000000
\n",
"
59578.656570
\n",
"
\n",
"
\n",
"
6
\n",
"
7
\n",
"
0.000000
\n",
"
0.000000
\n",
"
77531.535059
\n",
"
\n",
"
\n",
"
7
\n",
"
8
\n",
"
0.000000
\n",
"
0.000000
\n",
"
103522.146540
\n",
"
\n",
"
\n",
"
8
\n",
"
9
\n",
"
0.000000
\n",
"
0.000000
\n",
"
134548.020901
\n",
"
\n",
"
\n",
"
9
\n",
"
10
\n",
"
1191.848650
\n",
"
117169.330197
\n",
"
25643.073440
\n",
"
\n",
" \n",
"
\n",
"
"
],
"text/plain": [
" period oha ohv ogs\n",
"0 1 956.419884 102585.020390 30405.125309\n",
"1 2 34.885672 4798.494437 28607.304394\n",
"2 3 0.000000 0.000000 32154.392350\n",
"3 4 0.000000 0.000000 38166.885368\n",
"4 5 0.000000 0.000000 47379.394949\n",
"5 6 0.000000 0.000000 59578.656570\n",
"6 7 0.000000 0.000000 77531.535059\n",
"7 8 0.000000 0.000000 103522.146540\n",
"8 9 0.000000 0.000000 134548.020901\n",
"9 10 1191.848650 117169.330197 25643.073440"
]
},
"execution_count": 15,
"metadata": {},
"output_type": "execute_result"
}
],
"source": [
"oha = [fm.compile_product(period, \"1.\", acode=\"harvest\") for period in fm.periods]\n",
"ohv = [fm.compile_product(period, \"totvol * 0.85\", acode=\"harvest\") for period in fm.periods]\n",
"ogs = [fm.inventory(period, \"totvol\") for period in fm.periods]\n",
"data = {\"period\":fm.periods,\n",
" \"oha\":oha,\n",
" \"ohv\":ohv,\n",
" \"ogs\": ogs}\n",
"df = pd.DataFrame(data)\n",
"df"
]
},
{
"cell_type": "markdown",
"metadata": {},
"source": [
"Plot this data as bar charts using `matplotlib`."
]
},
{
"cell_type": "code",
"execution_count": 16,
"metadata": {},
"outputs": [
{
"data": {
"text/plain": [
"(,\n",
" array([,\n",
" ,\n",
" ], dtype=object))"
]
},
"execution_count": 16,
"metadata": {},
"output_type": "execute_result"
},
{
"data": {
"image/png": "iVBORw0KGgoAAAANSUhEUgAAA+IAAAF2CAYAAADqciI3AAAAOnRFWHRTb2Z0d2FyZQBNYXRwbG90bGliIHZlcnNpb24zLjEwLjUsIGh0dHBzOi8vbWF0cGxvdGxpYi5vcmcvWftoOwAAAAlwSFlzAAAPYQAAD2EBqD+naQAAbzxJREFUeJzt3XlcV1X+x/E3iCwugGiAGCqZIy64QRFuWTLikkq5pFGakpZBuZSmjZJbqZQLLknWqDUD49LCmDokqaUJoqLmkpqVpumANQqkKaDc3x8+uD+/AooKX9Bez8fjPh5+z/l8zzn3Ksf74d57ro1hGIYAAAAAAIBV2Jb3AAAAAAAA+DMhEQcAAAAAwIpIxAEAAAAAsCIScQAAAAAArIhEHAAAAAAAKyIRBwAAAADAikjEAQAAAACwIhJxAAAAAACsiEQcAAAAAAArIhHHn9KyZctkY2OjY8eOlfdQStXKlSvl5uamc+fOmWU2NjaKjIwstT4SExNVrVo1/frrr6XWJoDSVV5z3KRJk2RjY2PVPktbt27dNHTo0HLpOzY2VnXr1lVOTk659A9UNF999ZVsbGz01VdflfdQyl3Bsfj4449vuY3t27fL3t5eP//8cymOrGTy8vLk7e2td9991+p9V1Qk4negghOsnTt3FlnfsWNHNWvWzMqjKn1//PGHJk2axORbQpcvX9Ybb7yhl156SdWqVSuzfrp06aL7779f06dPL7M+8OfGHIfysnXrVq1fv16vvfZaqbY7atQotW7dWm5ubqpSpYoaN26sSZMmWfzSVJKeffZZ5ebm6r333ivV/oGiHD16VJGRkfrLX/6iKlWqqEqVKmrSpIkiIiK0d+/e8h5ehbBv3z716dNH9erVk6Ojo+rUqaO//vWvmj9/vkXcW2+9pYSEhPIZ5E3429/+pgEDBqhevXql1ubmzZvVs2dPeXt7y9HRUZ6enurSpYu2bt1qEVe5cmWNHj1ab775pi5evFhq/d/JSMRRYf3xxx+aPHkyJ6kl9Pnnn+vw4cMaNmxYmff1/PPP67333tPvv/9e5n0BdyvmuIrn7bffVqdOnXT//feXars7duxQ+/btNXnyZMXExOiRRx7RjBkz1KVLF+Xn55txjo6OGjRokGbPni3DMEp1DMDV1qxZo2bNmukf//iHgoODNWfOHMXExKhr165at26dWrZsWS5XTa/VoUMHXbhwQR06dLB638nJyQoICNC3336roUOHasGCBXruuedka2urmJgYi9g7IRHfs2ePvvzyS73wwgul2u73338vW1tbvfDCC1q4cKFeffVVpaenq0OHDkpMTLSIHTx4sH777TfFx8eX6hjuVHblPQBUbIZh6OLFi3Jycirvodxxzp8/r6pVq1qtv6VLl6pt27aqU6dOmffVu3dvvfTSS1q1apWGDBlS5v0BZYU5DgVOnz6ttWvXKjY2ttTb/uabbwqVNWjQQK+++qq2b9+uhx56yCzv16+foqOjtWnTJj366KOlPhbgxx9/VP/+/VWvXj1t2LBBtWvXtqifOXOm3n33XdnaXv96nTXOc2xtbeXo6FimfRTnzTfflIuLi3bs2CFXV1eLutOnT5fLmG7H0qVLVbduXYv5pjQ899xzeu655yzKXnzxRd13332aO3euunTpYpa7urqqc+fOWrZsGeeP4or4n8bSpUv16KOPyt3dXQ4ODmrSpIkWLVpUKK5+/fp67LHH9MUXXyggIEBOTk5677331KxZMz3yyCOF4vPz81WnTh316dPHomzu3Llq2rSpHB0d5eHhoeeff15nz561+O7OnTsVEhKiWrVqycnJST4+PuYP5bFjx3TPPfdIkiZPniwbGxvZ2Nho0qRJ5vcPHTqkPn36yM3NTY6OjgoICNDq1asLjfHAgQN69NFH5eTkpHvvvVfTpk2zuAJxPXv37tWzzz6r++67z7zdZsiQIfrf//5nEVfwXOR3332np556SjVq1FC7du3M+n/+85/y9/eXk5OT3Nzc1L9/f504ccKijS1btqhv376qW7euHBwc5O3trVGjRunChQs3HOfFixeVmJio4ODgYmMSEhLUrFkzOTg4qGnTpoV+S/nzzz/rxRdfVKNGjeTk5KSaNWuqb9++RT5j6u7urubNm+vf//73DccGWANz3M3Pce+8845sbGyKvOo1fvx42dvbW+zTqlWrzHmsVq1aevrpp3Xy5Mnr9nHs2DHZ2Nho2bJlhequ3d+CefT777/X008/LRcXF91zzz2aOHGiDMPQiRMn1KtXLzk7O8vT01OzZs0q1GZOTo7eeOMN3X///eY8Onbs2BI9c7127VpdunSp0Dxa8KjEN998o5dffln33HOPXF1d9fzzzys3N1eZmZkaOHCgatSooRo1amjs2LEluppdv359SVJmZqZFub+/v9zc3JhfUWaio6N1/vx5LV26tFASLkl2dnZ6+eWX5e3tbZY9++yzqlatmn788Ud169ZN1atXV1hYmKQrCfkrr7wib29vOTg4qFGjRnrnnXcsfg6eeOIJtW7d2qKfHj16yMbGxmJeS01NlY2Njf7zn/9IKvoZ8YLHk7777js98sgjqlKliurUqaPo6OhC+/Lzzz+rZ8+eqlq1qtzd3TVq1Ch98cUXJXru/Mcff1TTpk0LJeHSlfOgAjY2Njp//rw+/PBDcy5/9tlnzfrdu3era9eucnZ2VrVq1dSpUydt27atUJuZmZkaNWqU6tevLwcHB917770aOHCgfvvtt2LHmJOTo8cee0wuLi5KTk6+7v4kJCTo0UcfLbSOR8H/i1999ZX5/6Kfn595fD799FP5+fnJ0dFR/v7+2r1793X7kaQqVaronnvuKTS/SdJf//pXffPNNzpz5swN27nbcUX8DpaVlVXkD2deXl6hskWLFqlp06bq2bOn7Ozs9Pnnn+vFF19Ufn6+IiIiLGIPHz6sAQMG6Pnnn9fQoUPVqFEjPfnkk5o0aZLS09Pl6elpxn7zzTc6deqU+vfvb5Y9//zzWrZsmQYPHqyXX35ZR48e1YIFC7R7925t3bpVlStX1unTp9W5c2fdc889GjdunFxdXXXs2DF9+umnkqR77rlHixYt0vDhw/X444/riSeekCQ1b95c0pUTz4Krv+PGjVPVqlW1cuVKhYaG6pNPPtHjjz8uSUpPT9cjjzyiS5cumXGLFy8u8dWvpKQk/fTTTxo8eLA8PT114MABLV68WAcOHNC2bdsKTWZ9+/ZVw4YN9dZbb5n/Ab355puaOHGi+vXrp+eee06//vqr5s+frw4dOmj37t3mBL9q1Sr98ccfGj58uGrWrKnt27dr/vz5+uWXX7Rq1arrjjMtLU25ubmF/pO7+u/p008/1Ysvvqjq1atr3rx56t27t44fP66aNWtKunLrZHJysvr37697771Xx44d06JFi9SxY0d99913qlKlikWb/v7+Ff42LNzZmOPKdo7r16+fxo4dq5UrV2rMmDEWdStXrlTnzp1Vo0YNSTL394EHHtD06dOVkZGhmJgYbd261WIeKw1PPvmkGjdurBkzZmjt2rWaNm2a3Nzc9N577+nRRx/VzJkzFRcXp1dffVUPPPCAectqfn6+evbsqW+++UbDhg1T48aNtW/fPs2ZM0fff//9Deer5ORk1axZs9hnJ1966SV5enpq8uTJ2rZtmxYvXixXV1clJyerbt26euutt7Ru3Tq9/fbbatasmQYOHGjx/UuXLikzM1O5ubnav3+/JkyYoOrVq+vBBx8s1Ffr1q0LPV8JlJY1a9bo/vvvV2Bg4E1979KlSwoJCVG7du30zjvvqEqVKjIMQz179tSmTZsUHh6uli1b6osvvtCYMWN08uRJzZkzR5LUvn17/fvf/1Z2dracnZ1lGIa2bt0qW1tbbdmyRT179pR05aKEra2t2rZte92xnD17Vl26dNETTzyhfv366eOPP9Zrr70mPz8/de3aVdKVXxA8+uij+u9//6sRI0bI09NT8fHx2rRpU4n2t169ekpJSdH+/fuvuy7JP/7xDz333HN68MEHzccDGzRoIOnKXN6+fXs5Oztr7Nixqly5st577z117NhRX3/9tfl3cO7cObVv314HDx7UkCFD1Lp1a/32229avXq1fvnlF9WqVatQvxcuXFCvXr20c+dOffnll3rggQeKHePJkyd1/PjxYs8Tf/jhBz311FN6/vnn9fTTT+udd95Rjx49FBsbq9dff10vvviiJGn69Onq16+fDh8+XOiOiezsbOXm5uq3337TRx99pP379+v1118v1Je/v78Mw1BycrIee+yxYsf8p2DgjrN06VJD0nW3pk2bWnznjz/+KNROSEiIcd9991mU1atXz5BkJCYmWpQfPnzYkGTMnz/fovzFF180qlWrZra/ZcsWQ5IRFxdnEZeYmGhR/tlnnxmSjB07dhS7n7/++qshyXjjjTcK1XXq1Mnw8/MzLl68aJbl5+cbbdq0MRo2bGiWjRw50pBkpKammmWnT582XFxcDEnG0aNHi+3fMIo+bv/6178MScbmzZvNsjfeeMOQZAwYMMAi9tixY0alSpWMN99806J83759hp2dnUV5UX1Nnz7dsLGxMX7++efrjvODDz4wJBn79u0rVCfJsLe3N3744Qez7Ntvvy3091lU/ykpKYYk46OPPipU99ZbbxmSjIyMjOuODbhZzHHWm+OCgoIMf39/i7Lt27db/Nzn5uYa7u7uRrNmzYwLFy6YcWvWrDEkGVFRUWZZwVxY4OjRo4YkY+nSpYX6vnbfC747bNgws+zSpUvGvffea9jY2BgzZswwy8+ePWs4OTkZgwYNMsv+8Y9/GLa2tsaWLVss+omNjTUkGVu3br3usWjXrl2hY2EY///vMSQkxMjPzzfLg4KCDBsbG+OFF14oNN6HH364UDsF82nB1qhRI2PTpk1FjmXYsGGGk5PTdccL3IqsrCxDkhEaGlqo7uzZs8avv/5qblfPq4MGDTIkGePGjbP4TkJCgiHJmDZtmkV5nz59DBsbG/PcY8eOHYYkY926dYZhGMbevXsNSUbfvn2NwMBA83s9e/Y0WrVqZX7etGmTIcniZ+Xhhx8udG6Sk5NjeHp6Gr179zbLZs2aZUgyEhISzLILFy4Yvr6+hdosyvr1641KlSoZlSpVMoKCgoyxY8caX3zxhZGbm1sotmrVqhbzUYHQ0FDD3t7e+PHHH82yU6dOGdWrVzc6dOhglkVFRRmSjE8//bRQGwXzTsGxWLVqlfH7778bDz/8sFGrVi1j9+7d190PwzCML7/80pBkfP7554XqCv5fTE5ONsu++OILQ5Lh5ORkcQ763nvvFXvsQkJCzPnN3t7eeP755y3+z7h6/yUZM2fOvOG473bcmn4HW7hwoZKSkgptBVdUrnb11ZGCq0wPP/ywfvrpJ2VlZVnE+vj4KCQkxKLsL3/5i1q2bKkVK1aYZZcvX9bHH3+sHj16mO2vWrVKLi4u+utf/6rffvvN3Pz9/VWtWjXzt5AFV0/WrFlT5NWt6zlz5ow2btyofv366ffffzf7+N///qeQkBAdOXLEvF1y3bp1euihhyyuONxzzz3m7VQ3cvVxu3jxon777Tfz2Zpdu3YVir92AYxPP/1U+fn56tevn8Xx8PT0VMOGDS1+K3t1X+fPn9dvv/2mNm3ayDCMG94GVHCrfMHVq2sFBwebv52Vrlx1c3Z21k8//VRk/3l5efrf//6n+++/X66urkXua0Ff17tlCrgdzHFlP8c9+eSTSktL048//miWrVixQg4ODurVq5ekK7fYnz59Wi+++KLFs5rdu3eXr6+v1q5de1P7dyNXP2tYqVIlBQQEyDAMhYeHm+Wurq5q1KiRxRy2atUqNW7cWL6+vhZ/NwXPWd/oKtj//ve/YudQSQoPD7e4CyowMLDQuArGe/W4CjRp0kRJSUlKSEjQ2LFjVbVq1UKrpheoUaOGLly4oD/++OO6YwZuVnZ2tiQV+XaVjh076p577jG3hQsXFooZPny4xed169apUqVKevnlly3KX3nlFRmGYd5i3qpVK1WrVk2bN2+WdOXKd8Gt17t27dIff/whwzD0zTffqH379jfcj2rVqunpp582P9vb2+vBBx+0+NlLTExUnTp1zKvt0pUFEUv6esK//vWvSklJUc+ePfXtt98qOjpaISEhqlOnTpGPCV3r8uXLWr9+vUJDQ3XfffeZ5bVr19ZTTz2lb775xvz7+OSTT9SiRQvzbqerXXv3ZVZWljp37qxDhw7pq6++UsuWLW84lhudJzZp0kRBQUHm54Ir9Y8++qjq1q1bqLyoOW7GjBlav369/v73v+uhhx5Sbm6uLl26VCiO88f/x63pd7AHH3xQAQEBhcpr1KhR6B/31q1b9cYbbyglJaXQf+xZWVlycXExP/v4+BTZ35NPPqnXX39dJ0+eVJ06dfTVV1/p9OnTevLJJ82YI0eOKCsry+LZmasVLG7x8MMPq3fv3po8ebLmzJmjjh07KjQ0VE899ZQcHByuu98//PCDDMPQxIkTNXHixGL7qVOnjn7++ecib71q1KjRdfsocObMGU2ePFnLly8vtDDHtSf3UuFjd+TIERmGoYYNGxbZfuXKlc0/Hz9+XFFRUVq9enWhZ02L6qsoRjHPJV49iRaoUaOGRT8XLlzQ9OnTtXTpUp08edKiraL6L6i/098ZjIqLOa7s57i+fftq9OjRWrFihV5//XUZhqFVq1aZzzNKMp8hL6pNX1/fIhciux3XzlcuLi5ydHQsdGumi4uLxXodR44c0cGDB81n769VksWViptDixuXJIvnaAvKr53DJcnZ2dl8/rxXr16Kj49Xr169tGvXLrVo0aLIcTC/orRVr15dkor8JVDB21AyMjIsktwCdnZ2uvfeey3Kfv75Z3l5eZntFmjcuLFZL135JVVQUJC2bNki6Uoi3r59e7Vr106XL1/Wtm3b5OHhoTNnzpQoEb/33nsL/XzUqFHD4rVrP//8sxo0aFAo7mbeivDAAw/o008/VW5urr799lt99tlnmjNnjvr06aM9e/aoSZMmxX73119/1R9//FHk3Nm4cWPl5+frxIkTatq0qX788Uf17t27RGMaOXKkLl68qN27d6tp06Yl3hep5OeJ15vfJBU5x139C4Gnn35arVu31rPPPlvovefMb/+PRPxP4Mcff1SnTp3k6+ur2bNn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aNBAr776qk6ePClnZ2d98skn171N8mqOjo7q3LmzvvzyS02ZMqXE47vaY489pn/84x9ycXFRkyZNlJKSoi+//NK8nelqp0+f1t69ewu9FgooD8xxtzbHFXB3d9cjjzyi2bNn6/fffy/0y4eCE+fBgwfr4Ycf1oABA8zXl9WvX1+jRo26bvvPPfecZsyYoeeee04BAQHavHmzvv/++5L+lZTYM888o5UrV+qFF17Qpk2b1LZtW12+fFmHDh3SypUrzXfHF6d79+6ys7PTl19+ab6CqDR89dVXevnll9WnTx81bNhQubm52rJliz799FMFBAQUehY3LS1NZ86cMRfLA0pbw4YNFR8frwEDBqhRo0YKCwtTixYtZBiGjh49qvj4eNna2hb5qNu1evTooUceeUR/+9vfdOzYMbVo0ULr16/Xv//9b40cOdJiodgqVarI399f27ZtM98hLl25In7+/HmdP3++VBPx559/XgsWLNCAAQM0YsQI1a5dW3Fxceaikze6c+all17SH3/8occff1y+vr7Kzc1VcnKyVqxYofr162vw4MFmrL+/v7788kvNnj1bXl5e8vHxUWBgoKZNm6akpCS1a9dOL774ouzs7PTee+8pJyfH4r3nY8aM0ccff6y+fftqyJAh8vf315kzZ7R69WrFxsYWenxFkiIjI5Wdna2//e1vcnFxKfJVYVfr1auXPvvss0J3CNyurl276t5771VgYKDc3d11/PhxLV26VKdOnbJYALVAUlKS2rZtW+T55Z9OGa7IjjJS8CqV4l6L8/DDDxd6tc/q1auN5s2bG46Ojkb9+vWNmTNnGkuWLCn0ept69eoZ3bt3v27/bdu2NSQZzz33XLExixcvNvz9/Q0nJyejevXqhp+fnzF27Fjj1KlThmEYxq5du4wBAwYYdevWNRwcHAx3d3fjscceM3bu3GnRTnJysuHv72/Y29sXetXNjz/+aAwcONDw9PQ0KleubNSpU8d47LHHjI8//tiijb179xoPP/yw4ejoaNSpU8eYOnWq8fe//71Er/b55ZdfjMcff9xwdXU1XFxcjL59+5qvXSjqtTu//vprke188sknRrt27YyqVasaVatWNXx9fY2IiAjj8OHDZsx3331nBAcHG9WqVTNq1aplDB061HzNWFGv/rnWp59+atjY2BjHjx+3KJdkREREFIqvV6+e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",
"text/plain": [
""
]
},
"metadata": {},
"output_type": "display_data"
}
],
"source": [
"fig, ax = plt.subplots(1, 3, figsize=(12, 4))\n",
"ax[0].bar(df.period, df.oha)\n",
"ax[0].set_ylim(0, None)\n",
"ax[0].set_title(\"Harvested area (ha)\")\n",
"ax[1].bar(df.period, df.ohv)\n",
"ax[1].set_ylim(0, None)\n",
"ax[1].set_title(\"Harvested volume (m3)\")\n",
"ax[2].bar(df.period, df.ogs)\n",
"ax[2].set_ylim(0, None)\n",
"ax[2].set_title(\"Growing Stock (m3)\")\n",
"fig, ax"
]
},
{
"cell_type": "markdown",
"metadata": {},
"source": [
"So, the optimal solution seems to be to harvest a lot of volume in the first period, then just let the forest grow for 90 years, then liquidate all operable growing stock in the final period. \n",
"\n",
"This is typical behaviour for a forest estate model when there are no even flow or growing stock constraints defined. This is a good example of why it is essential for the forest analyst formulating and solving LP optimization problems in a forest estate modelling environment to understand the four inherent assumptions of linear programming (i.e., proportionality, additivity, divisibility, and certainty). In this case, the _certainty_ assumption is relevant to understanding the behaviour of the model. The model is _certain_ that time ends after perido 10, and is therefore _certain_ that there is no reason to maintain any growing stock (hence the determination that the optimal policy is to liquidate all remaining operable growing stock before time ends). \n",
"\n",
"The analyst needs to understand the effect of these assumptions on model output, and to detect when externalities need to be dealt with to mitigate any perverse effects of model structure and formulation. This is why experienced analysts might set a lower bound constraint on final-period growing stock, as a proxy for future time steps (beyond the final period in the model) that that model does not (_cannot_ because of the certainty assumption) see. This is a common practice in forest estate modelling, so we will go ahead and model this in the next step.\n",
"\n"
]
},
{
"cell_type": "markdown",
"metadata": {},
"source": [
"### Adding a Lower Bound Constraint on Final Period Growing Stock\n",
"\n",
"Next we will set such a lower bound constraint on final period growing stock, and re-run the model.\n",
"\n",
"Before settting this new constraint, we need to define new function that correctly calculates the optimization problem matrix coefficients for the new constraint rows."
]
},
{
"cell_type": "code",
"execution_count": 17,
"metadata": {},
"outputs": [],
"source": [
"def cmp_c_ci(fm, path, yname, mask=None): # product, named actions\n",
" \"\"\"\n",
" Compile constraint coefficient for inventory indicator.\n",
"\n",
" This function takes a ForestModel instance and other parameters to evaluate \n",
" an expression along a specified leaf-to-root-node path. It returns a dictionary \n",
" where keys are timestamps (t) and values are the results of evaluating the given \n",
" expression at each timestamp, with optional filtering based on the provided mask.\n",
"\n",
" Parameters:\n",
" fm (ForestModel): The ForestModel instance to use for evaluation.\n",
" path: A list of nodes representing one path in one tree in the optimization problem. \n",
" yname (str): The name of the yield component used for output coefficient lookup. \n",
" mask (tuple or string, optional): An optional dictionary that specifies which data types \n",
" should be used for filtering.\n",
"\n",
" Returns:\n",
" dict: A dictionary where keys are timestamps and values are the constraint coefficients for the matrix.\n",
" \"\"\"\n",
" result = {}\n",
" # Iterate over each node in the specified path\n",
" for t, n in enumerate(path, start=1):\n",
" d = n.data()\n",
" if mask and not fm.match_mask(mask, d[\"_dtk\"]): continue # filter by mask\n",
" result[t] = fm.inventory(t, yname=yname, age=d[\"_age\"], dtype_keys=[d[\"_dtk\"]])\n",
" return result\n",
"\n"
]
},
{
"cell_type": "markdown",
"metadata": {},
"source": [
"Now we can use the `functools.partial` function to create a new version of the `cmp_c_i` function that takes two arguments (i.e., a `ForestModel` instance and a tuple of `Node` objects), and map this to constraint name `cgen_gs` in the `coeff_funcs` dictionary (which already contains a mapping to the objective function coefficient function, from a previous step)."
]
},
{
"cell_type": "code",
"execution_count": 18,
"metadata": {},
"outputs": [],
"source": [
"coeff_funcs['cgen_gs'] = functools.partial(cmp_c_ci, yname=tvy_name, mask=None)"
]
},
{
"cell_type": "markdown",
"metadata": {},
"source": [
"Next we need to create the `cgen_data` argument for the `ForestModel.add_problem` method, which is a data structure that contains periodic lower-bound and upper-bound right-hand-side (RHS) values that we will be used to define the new end-of-horizon minimum growing stock constraint."
]
},
{
"cell_type": "markdown",
"metadata": {},
"source": [
"We can use the `ForestModel.inventory` method to query the model for initial growing stock level, so we can set the ending inventory constraint to 90% of this initial value."
]
},
{
"cell_type": "code",
"execution_count": 19,
"metadata": {},
"outputs": [
{
"data": {
"text/plain": [
"{'cgen_gs': {'lb': {10: 135984.04613242325}, 'ub': {10: 999999999.0}}}"
]
},
"execution_count": 19,
"metadata": {},
"output_type": "execute_result"
}
],
"source": [
"gs_lb_rhs = fm.inventory(0, \"totvol\") * 0.90 # 90% of initial growing stock level\n",
"cgen_data = {\"cgen_gs\":{\"lb\":{10:gs_lb_rhs}, \"ub\":{10:999999999.}}}\n",
"cgen_data"
]
},
{
"cell_type": "markdown",
"metadata": {},
"source": [
"The `cgen_data` argument to `ForestestModel.add_problem` is a dictionary that contains constraint names as keys and dictionaries with keys `lb` (lower bound RHS values) and `ub` (upper bound RHS values) as values. The RHS values are also dictionaries, where each key is a period and value is the RHS value for that age. In this case we will only define RHS values for period 10. We set the he lower bound RHS value for period 10 as 90% of initial growing stock level and the upper bound RHS value for period 10 as 999999999 (an arbitrary large number, as we want the upper bound to be a non-binding constraint). We will use these values to define the new end-of-horizon minimum growing stock.\n",
"\n",
"We can now add the new constraint using the `add_problem` method. The call to `add_problem` is almost identical to that of `add_problem` for the first scenario. The only difference is that we pass the new `cgen_data` object(containing lower-bound and upper-bound constraint RHS values) instead of passing `None` and that the `coeff_funcs` dictionary now also includes a key-value pair for the new coefficient function we defined to track periodic growing stock inventory."
]
},
{
"cell_type": "code",
"execution_count": 20,
"metadata": {},
"outputs": [],
"source": [
"problem = fm.add_problem(name=\"scenario-2\",\n",
" coeff_funcs=coeff_funcs, \n",
" cflw_e=None, \n",
" cgen_data=cgen_data, # this was set to None in the previous scenario \n",
" acodes=(\"null\", \"harvest\"),\n",
" sense=ws3.opt.SENSE_MAXIMIZE, \n",
" mask=None)"
]
},
{
"cell_type": "markdown",
"metadata": {},
"source": [
"Now we can solve our upgraded problem, compile and simulate the optimal solution, and display results. Note that we need to call `ForestModel.reset()` before applying the new action schedule (other wise `ws3` will just attempt to apply the actions on top of previously applied actions, which will simulate the wrong scenario and give you incorrect results)."
]
},
{
"cell_type": "code",
"execution_count": 21,
"metadata": {},
"outputs": [
{
"data": {
"text/plain": [
"(,\n",
" array([,\n",
" ,\n",
" ], dtype=object))"
]
},
"execution_count": 21,
"metadata": {},
"output_type": "execute_result"
},
{
"data": {
"image/png": "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bGws2YiINIGFOBERERFV6MGDB0hLS0NaWhqAJ4uiXbp0CQCgpaWFwMBALFmyBHv37sXly5cxatQoWFhYwMvLCwBgZ2eH/v37Y/z48Th79ixOnz6NgIAA+Pj4wMLCAgDw4YcfQk9PD35+fkhPT8fOnTsRHh6OoKAgMY9p06YhLi4Oq1atwvXr17FgwQKcP38eAQEB1c6FiKiu4GJtRERERFSh8+fPo0+fPuLrp4tjAJg5cyby8/MxYcIE5ObmokePHoiLi4OBgYEYExUVhYCAAPTr1w/a2trw9vbG2rVrxX6ZTIbDhw/D398fTk5OaNKkCYKDgyXPGu/WrRuio6Mxd+5cfPHFF7CxsUFsbCwcHByeKxciorqAhTgRERERVah3794QBEHSplQqIZPJADw5E71o0SIsWrSown2YmpoiOjq60nHatWuHkydPVhozbNgwDBs2rML+6uRCRFQX8NJ0IiIiIiIiIg1iIU5ERERERESkQSzEiYiIiIiIiDSIhTgRERERERGRBrEQJyIiIiIiItIgFuJEREREREREGsRCnIiIiIiIiEiDWIgTERERERERaRALcSIiIiIiIiINYiFOREREREREpEEsxImIiIiIiIg0iIU4ERERERERkQaxECciIiIiIiLSIBbiRERERERERBrEQpyIiIiIiIhIg1iIExEREREREWkQC3EiIiIiIiIiDWIhTkRERERERKRBLMSJiIiIiIiINIiFOBEREREREZEGsRAnIiIiIiIi0qAaKcTv3r2Ljz76CI0bN4ahoSEcHR1x/vx5sV8QBAQHB6NZs2YwNDSEm5sbbt68KdlHTk4OfH19YWxsDBMTE/j5+eHBgwc1kS4RERERERGRxqi9EL9//z66d++OevXq4eeff8bVq1exatUqNGrUSIwJDQ3F2rVrERkZiZSUFBgZGcHDwwMFBQVijK+vL9LT0xEfH4/9+/cjMTEREyZMUHe6RERERERERBqlq+4dLl++HJaWlti6davYZm1tLf5ZEASEhYVh7ty5GDJkCADgu+++g7m5OWJjY+Hj44Nr164hLi4O586dg7OzMwBg3bp1GDhwIFauXAkLCwt1p01ERERERESkEWo/I7537144Oztj2LBhMDMzQ8eOHbF582axPzMzEwqFAm5ubmKbTCaDi4sLkpOTAQDJyckwMTERi3AAcHNzg7a2NlJS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D4BfMonozbZu3ToMHToUkydPhp2dHT7//HNMnDgRixcvFmNmzpyJKVOmYMKECejcuTMePHiAuLg4GBgYiDFRUVGwtbVFv379MHDgQPTo0UPy+EaZTIbDhw8jMzMTTk5O+OyzzxAcHCx5DGS3bt3EObp9+/b44YcfEBsbCwcHB818GERE1aQlCIJQ20nUBKVSCZlMhry8vGqf/Wk1+4Da87i1zFPt+ySimvfsHLJ//37MmTMHN2/ehLW1NYKCgjB+/HgxXhAEzJ8/H5s2bUJubi569OiBr7/+Gu+8844Yk5OTg4CAAOzbtw/a2trw9vbG2rVr0aBBAzHm0qVL8Pf3x7lz59CkSRNMmTIFs2bNkuQWExODuXPn4tatW7CxsUFoaCgGDhz4wsdWXeqeIzk/Er26XnQeqete1+OiV5sm/v/VVB30Kh7L835fqe48ovuyiRERvQkGDRqEQYMGVdivpaWFRYsWYdGiRRXGmJqaIjo6utJx2rVrh5MnT1YaM2zYMAwbNqzyhImIiIiozuKl6UREREREREQaxEKciIiIiIiISINYiBMRERERERFpEAtxIiIiIiIiIg1iIU5ERERERESkQSzEiYiIiIiIiDSIhTgRERERERGRBrEQJyIiIiIiItIgFuJEREREREREGsRCnIiIiIiIiEiDWIgTERERERERaRALcSIiIiIiIiINYiFOREREREREpEEsxImIiIiIiIg0iIU4ERERERERkQaxECciIiIiIiLSIBbiRERERERERBrEQpyIiIiIiIhIg1iIExEREREREWkQC3EiIiIiIiIiDWIhTkRERERERKRBLMSJiIiIiIiINIiFOBEREREREZEGsRAnIiIiIiIi0iAW4kREREREREQaxEKciIiIiIiISINYiBMRERERERFpEAtxIiIiIiIiIg1iIU5ERERERESkQSzEiYiIiIiIiDSIhTgRERERERGRBrEQJyIiIqKXcvfuXXz00Udo3LgxDA0N4ejoiPPnz4v9giAgODgYzZo1g6GhIdzc3HDz5k3JPnJycuDr6wtjY2OYmJjAz88PDx48kMRcunQJPXv2hIGBASwtLREaGloml5iYGNja2sLAwACOjo44ePBgzRw0EdFLYCFORERERC/s/v376N69O+rVq4eff/4ZV69exapVq9CoUSMxJjQ0FGvXrkVkZCRSUlJgZGQEDw8PFBQUiDG+vr5IT09HfHw89u/fj8TEREyYMEHsVyqVcHd3h5WVFVJTU7FixQosWLAAmzZtEmOSkpIwcuRI+Pn54eLFi/Dy8oKXlxeuXLmimQ+DiKiadGs7ASIiIiJ6dS1fvhyWlpbYunWr2GZtbS3+WRAEhIWFYe7cuRgyZAgA4LvvvoO5uTliY2Ph4+ODa9euIS4uDufOnYOzszMAYN26dRg4cCBWrlwJCwsLREVFoaioCFu2bIGenh7atm2LtLQ0rF69WizYw8PD0b9/f8yYMQMAsHjxYsTHx2P9+vWIjIzU1EdCRFQlnhEnIiIiohe2d+9eODs7Y9iwYTAzM0PHjh2xefNmsT8zMxMKhQJubm5im0wmg4uLC5KTkwEAycnJMDExEYtwAHBzc4O2tjZSUlLEmF69ekFPT0+M8fDwQEZGBu7fvy/GPD2OKkY1DhFRXcFCnIiIiIhe2O+//44NGzbAxsYGhw4dwqRJkzB16lRs374dAKBQKAAA5ubmkveZm5uLfQqFAmZmZpJ+XV1dmJqaSmLK28fTY1QUo+p/VmFhIZRKpWQjItIEXppORERERC+stLQUzs7OWLp0KQCgY8eOuHLlCiIjIzF69Ohazq5yISEhWLhwYW2nQURvIBbiRERERPTCmjVrBnt7e0mbnZ0dfvzxRwCAXC4HAGRlZaFZs2ZiTFZWFjp06CDGZGdnS/bx+PFj5OTkiO+Xy+XIysqSxKheVxWj6n/WnDlzEBQUJL5WKpWwtLSs+qCJ/r9Wsw+odX+3lnmqdX9Ud9X4penLli2DlpYWAgMDxbaCggL4+/ujcePGaNCgAby9vctMmrdv34anpyfq168PMzMzzJgxA48fP67pdImIiIjoOXTv3h0ZGRmSths3bsDKygrAk4Xb5HI5EhISxH6lUomUlBS4uroCAFxdXZGbm4vU1FQx5ujRoygtLYWLi4sYk5iYiOLiYjEmPj4ebdq0EVdod3V1lYyjilGN8yx9fX0YGxtLNiIiTajRQvzcuXPYuHEj2rVrJ2mfPn069u3bh5iYGJw4cQL37t3DBx98IPaXlJTA09MTRUVFSEpKwvbt27Ft2zYEBwfXZLpERERE9JymT5+OM2fOYOnSpfj1118RHR2NTZs2wd/fHwDEEzJLlizB3r17cfnyZYwaNQoWFhbw8vIC8OQMev/+/TF+/HicPXsWp0+fRkBAAHx8fGBhYQEA+PDDD6Gnpwc/Pz+kp6dj586dCA8Pl5zRnjZtGuLi4rBq1Spcv34dCxYswPnz5xEQEKDxz4WIqDI1Vog/ePAAvr6+2Lx5s+Q5knl5efj222+xevVq9O3bF05OTti6dSuSkpJw5swZAMDhw4dx9epV/Oc//0GHDh0wYMAALF68GBERESgqKqqplImIiIjoOXXu3Bl79uzB999/DwcHByxevBhhYWHw9fUVY2bOnIkpU6ZgwoQJ6Ny5Mx48eIC4uDgYGBiIMVFRUbC1tUW/fv0wcOBA9OjRQ/KMcJlMhsOHDyMzMxNOTk747LPPEBwcLHnWeLdu3cRfBLRv3x4//PADYmNj4eDgoJkPg4iommrsHnF/f394enrCzc0NS5YsEdtTU1NRXFwsebSEra0tWrZsieTkZHTt2hXJyclwdHSUrHrp4eGBSZMmIT09HR07dqyptImIiIjoOQ0aNAiDBg2qsF9LSwuLFi3CokWLKowxNTVFdHR0peO0a9cOJ0+erDRm2LBhGDZsWOUJExHVshopxHfs2IELFy7g3LlzZfoUCgX09PRgYmIiaX/2ERZVPZ7iWYWFhSgsLBRf8/ETREREREREVBep/dL0O3fuYNq0aYiKipJcblTTQkJCIJPJxI0rXhIREREREVFdpPZCPDU1FdnZ2ejUqRN0dXWhq6uLEydOYO3atdDV1YW5uTmKioqQm5sred/Tj5aozuMpnjVnzhzk5eWJ2507d9R9aEREREREREQvTe2FeL9+/XD58mWkpaWJm7OzM3x9fcU/16tXT/JoiYyMDNy+fVvyCIvLly9LnicZHx8PY2PjMs+pVOHjJ4iIiIiIiOhVoPZCvGHDhnBwcJBsRkZGaNy4MRwcHCCTyeDn54egoCAcO3YMqampGDNmDFxdXdG1a1cAgLu7O+zt7fHxxx/jl19+waFDhzB37lz4+/tDX19f3SkTET2XZcuWiY/jUSkoKIC/vz8aN26MBg0awNvbu8yVPbdv34anpyfq168PMzMzzJgxA48fP5bEHD9+HJ06dYK+vj7efvttbNu2rcz4ERERaNWqFQwMDODi4oKzZ8/WxGESERERUQ2p0eeIV2TNmjUYNGgQvL290atXL8jlcuzevVvs19HRwf79+6GjowNXV1d89NFHGDVqVKUrbRIRacK5c+ewceNGtGvXTtI+ffp07Nu3DzExMThx4gTu3buHDz74QOwvKSmBp6cnioqKkJSUhO3bt2Pbtm0IDg4WYzIzM+Hp6Yk+ffogLS0NgYGBGDduHA4dOiTG7Ny5E0FBQZg/fz4uXLiA9u3bw8PDQ3IFERERERHVbTX2+LKnHT9+XPLawMAAERERiIiIqPA9VlZWOHjwYA1nRkRUfQ8ePICvry82b94seSxjXl4evv32W0RHR6Nv374AgK1bt8LOzg5nzpxB165dcfjwYVy9ehVHjhyBubk5OnTogMWLF2PWrFlYsGAB9PT0EBkZCWtra6xatQoAYGdnh1OnTmHNmjXw8PAAAKxevRrjx4/HmDFjAACRkZE4cOAAtmzZgtmzZ2v4EyEiIiKiF1ErZ8SJiF5F/v7+8PT0hJubm6Q9NTUVxcXFknZbW1u0bNkSycnJAIDk5GQ4OjpKHs3o4eEBpVKJ9PR0MebZfXt4eIj7KCoqQmpqqiRGW1sbbm5uYgwRERER1X0aOSNORPSq27FjBy5cuIBz586V6VMoFNDT04OJiYmk3dzcHAqFQox5ughX9av6KotRKpV49OgR7t+/j5KSknJjrl+/XmHuhYWFKCwsFF8rlcoqjpaIiIiIahLPiBMRVeHOnTuYNm0aoqKiYGBgUNvpPLeQkBDIZDJxs7S0rO2UiIiIiN5oLMSJiKqQmpqK7OxsdOrUCbq6utDV1cWJEyewdu1a6OrqwtzcHEVFRcjNzZW8LysrC3K5HAAgl8vLrKKuel1VjLGxMQwNDdGkSRPo6OiUG6PaR3nmzJmDvLw8cbtz584LfQ5EREREpB4sxImIqtCvXz9cvnwZaWlp4ubs7AxfX1/xz/Xq1UNCQoL4noyMDNy+fRuurq4AAFdXV1y+fFmyunl8fDyMjY1hb28vxjy9D1WMah96enpwcnKSxJSWliIhIUGMKY++vj6MjY0lGxERERHVHt4jTkRUhYYNG8LBwUHSZmRkhMaNG4vtfn5+CAoKgqmpKYyNjTFlyhS4urqia9euAAB3d3fY29vj448/RmhoKBQKBebOnQt/f3/o6+sDAD799FOsX78eM2fOxNixY3H06FHs2rULBw4cEMcNCgrC6NGj4ezsjC5duiAsLAz5+fniKupEREREVPexECciUoM1a9ZAW1sb3t7eKCwshIeHB77++muxX0dHB/v378ekSZPg6uoKIyMjjB49GosWLRJjrK2tceDAAUyfPh3h4eFo0aIFvvnmG/HRZQAwYsQI/PXXXwgODoZCoUCHDh0QFxdXZgE3IiIiIqq7WIgTEb2A48ePS14bGBggIiICERERFb7HysoKBw8erHS/vXv3xsWLFyuNCQgIQEBAQLVzJSIiIqK6hfeIExEREREREWkQC3EiIiIiIiIiDWIhTkRERERERKRBLMSJiIiIiIiINIiFOBEREREREZEGsRAnIiIiIiIi0iA+voyIiIiIiF4rrWYfUPs+by3zVPs+6c3FM+JEREREREREGsRCnIiIiIiIiEiDWIgTERERERERaRALcSIiIiIiIiINYiFOREREREREpEEsxImIiIiIiIg0iIU4ERERERERkQaxECciIiIiIiLSIBbiRERERERERBrEQpyIiIiIiIhIg1iIExEREREREWkQC3EiIiIiUptly5ZBS0sLgYGBYltBQQH8/f3RuHFjNGjQAN7e3sjKypK87/bt2/D09ET9+vVhZmaGGTNm4PHjx5KY48ePo1OnTtDX18fbb7+Nbdu2lRk/IiICrVq1goGBAVxcXHD27NmaOEwiopfCQpyIiIiI1OLcuXPYuHEj2rVrJ2mfPn069u3bh5iYGJw4cQL37t3DBx98IPaXlJTA09MTRUVFSEpKwvbt27Ft2zYEBweLMZmZmfD09ESfPn2QlpaGwMBAjBs3DocOHRJjdu7ciaCgIMyfPx8XLlxA+/bt4eHhgezs7Jo/eCKi58BCnIiIiIhe2oMHD+Dr64vNmzejUaNGYnteXh6+/fZbrF69Gn379oWTkxO2bt2KpKQknDlzBgBw+PBhXL16Ff/5z3/QoUMHDBgwAIsXL0ZERASKiooAAJGRkbC2tsaqVatgZ2eHgIAADB06FGvWrBHHWr16NcaPH48xY8bA3t4ekZGRqF+/PrZs2aLZD4OIqAosxImIiIjopfn7+8PT0xNubm6S9tTUVBQXF0vabW1t0bJlSyQnJwMAkpOT4ejoCHNzczHGw8MDSqUS6enpYsyz+/bw8BD3UVRUhNTUVEmMtrY23NzcxJhnFRYWQqlUSjYiIk3Qre0EiIiIiOjVtmPHDly4cAHnzp0r06dQKKCnpwcTExNJu7m5ORQKhRjzdBGu6lf1VRajVCrx6NEj3L9/HyUlJeXGXL9+vdy8Q0JCsHDhwuofKBGRmvCMOBERERG9sDt37mDatGmIioqCgYFBbafzXObMmYO8vDxxu3PnTm2nRERvCBbiRERERPTCUlNTkZ2djU6dOkFXVxe6uro4ceIE1q5dC11dXZibm6OoqAi5ubmS92VlZUEulwMA5HJ5mVXUVa+rijE2NoahoSGaNGkCHR2dcmNU+3iWvr4+jI2NJRsRkSawECciIiKiF9avXz9cvnwZaWlp4ubs7AxfX1/xz/Xq1UNCQoL4noyMDNy+fRuurq4AAFdXV1y+fFmyunl8fDyMjY1hb28vxjy9D1WMah96enpwcnKSxJSWliIhIUGMISKqK3iPOBERERG9sIYNG8LBwUHSZmRkhMaNG4vtfn5+CAoKgqmpKYyNjTFlyhS4urqia9euAAB3d3fY29vj448/RmhoKBQKBebOnQt/f3/o6+sDAD799FOsX78eM2fOxNixY3H06FHs2rULBw4cEMcNCgrC6NGj4ezsjC5duiAsLAz5+fkYM2aMhj4Nqo5Wsw9UHfQcbi3zVOv+iDSBhTgR1Vn8j5qI6PWwZs0aaGtrw9vbG4WFhfDw8MDXX38t9uvo6GD//v2YNGkSXF1dYWRkhNGjR2PRokVijLW1NQ4cOIDp06cjPDwcLVq0wDfffAMPDw8xZsSIEfjrr78QHBwMhUKBDh06IC4urswCbkREtY2FOBERERGp1fHjxyWvDQwMEBERgYiIiArfY2VlhYMHD1a63969e+PixYuVxgQEBCAgIKDauRIR1QbeI05ERERERESkQSzEiYiIiIiIiDSIhTgRERERERGRBrEQJyIiIiIiItIgFuJEREREREREGsRCnIiIiIiIiEiDWIgTERERERERaRALcSIiIiIiIiINYiFOREREREREpEEsxImIiIiIiIg0SLe2EyAiIiIiotrXavYBte/z1jJPte+T6HXAM+JEREREREREGsQz4kRERESvGHWfueRZSyIizVL7GfGQkBB07twZDRs2hJmZGby8vJCRkSGJKSgogL+/Pxo3bowGDRrA29sbWVlZkpjbt2/D09MT9evXh5mZGWbMmIHHjx+rO10iIiIiIiIijVL7GfETJ07A398fnTt3xuPHj/HFF1/A3d0dV69ehZGREQBg+vTpOHDgAGJiYiCTyRAQEIAPPvgAp0+fBgCUlJTA09MTcrkcSUlJ+O9//4tRo0ahXr16WLp0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",
"text/plain": [
""
]
},
"metadata": {},
"output_type": "display_data"
}
],
"source": [
"problem.solve()\n",
"sch = fm.compile_schedule(problem)\n",
"fm.reset()\n",
"fm.apply_schedule(\n",
" sch, \n",
" force_integral_area=False, \n",
" override_operability=False,\n",
" fuzzy_age=False,\n",
" recourse_enabled=False,\n",
" verbose=False,\n",
" compile_c_ycomps=True\n",
")\n",
"oha = [fm.compile_product(period, \"1.\", acode=\"harvest\") for period in fm.periods]\n",
"ohv = [fm.compile_product(period, \"totvol * 0.85\", acode=\"harvest\") for period in fm.periods]\n",
"ogs = [fm.inventory(period, \"totvol\") for period in fm.periods]\n",
"data = {\n",
" \"period\":fm.periods,\n",
" \"oha\":oha,\n",
" \"ohv\":ohv,\n",
" \"ogs\":ogs\n",
"}\n",
"df = pd.DataFrame(data)\n",
"fig, ax = plt.subplots(1, 3, figsize=(12, 4))\n",
"ax[0].bar(df.period, df.oha)\n",
"ax[0].set_ylim(0, None)\n",
"ax[0].set_title(\"Harvested area (ha)\")\n",
"ax[1].bar(df.period, df.ohv)\n",
"ax[1].set_ylim(0, None)\n",
"ax[1].set_title(\"Harvested volume (m3)\")\n",
"ax[2].bar(df.period, df.ogs)\n",
"ax[2].set_ylim(0, None)\n",
"ax[2].set_title(\"Growing Stock (m3)\")\n",
"fig, ax"
]
},
{
"cell_type": "markdown",
"metadata": {},
"source": [
"That is a bit better. At least we are not liquidating our growing stock at the ned of the simulation horizon anymore. It would be nice to reduce variation in the periodic harvest volume, however. We achieve this by adding an _even flow_ constraint to the model. \n"
]
},
{
"cell_type": "markdown",
"metadata": {},
"source": [
"In the next section, We are going extend and resolve our model a few more times after this, but first we can define a new `run_scenario` function that will take care of this and avoid having this notebook fill up with mostly cut-and-paste repeated blocks of code. The function includes cleaned up code blocks that replicate all the things we manually implemented in previous steps, but all linked together.\n",
"\n",
"Note how we defined two Python closures inside `run_scenario` (`compile_scenario` and `plot_scenario`) to handle compiling and plotting solutions. Before moving on to adding even flow constraints to our model, we will test out our new `run_scenario` function and explore how its arguments affect how the model is built and what data is output to the console."
]
},
{
"cell_type": "code",
"execution_count": 22,
"metadata": {},
"outputs": [],
"source": [
"def run_scenario(forest_model, scenario_name, sense, acodes, coeff_funcs, cflw_e, cgen_data, \n",
" solver=ws3.opt.SOLVER_HIGHS, verbose=False, workers=1):\n",
" \"\"\"\n",
" Runs a forest management scenario using the provided forest model.\n",
"\n",
" Parameters:\n",
" forest_model (object): The forest model to use for this scenario.\n",
" scenario_name (str): A name for this scenario.\n",
" sense (str): The optimization sense for this scenario (\"minimize\" or \"maximize\").\n",
" coeff_funcs (list of functions): Functions that define the coefficients for this scenario.\n",
" cflw_e (float): The cost of flow-out for this scenario.\n",
" cgen_data (dict): Data for generation in this scenario.\n",
" acodes (list of str): Codes for acres to include in this scenario.\n",
" solver (str, optional): The solver to use for this scenario. Defaults to ws3.opt.SOLVER_PULP.\n",
"\n",
" Returns:\n",
" fig: A matplotlib figure with plots of harvested area, volume, and growing stock.\n",
" df: A pandas DataFrame containing the compiled scenario data.\n",
" problem: The optimization problem object used in this scenario.\n",
" \"\"\"\n",
"\n",
" # Helper function to compile scenario data\n",
" def compile_scenario(fm):\n",
" \"\"\"\n",
" Compiles scenario data for a given forest model.\n",
"\n",
" Parameters:\n",
" fm (object): The forest model to use for compilation.\n",
"\n",
" Returns:\n",
" df: A pandas DataFrame containing the compiled scenario data.\n",
" \"\"\"\n",
" # Compile product harvest area and volume for each period in the forest model\n",
" oha = [fm.compile_product(period, \"1.\", acode=\"harvest\") for period in fm.periods]\n",
" ohv = [fm.compile_product(period, \"totvol * 0.85\", acode=\"harvest\") for period in fm.periods]\n",
"\n",
" # Get the growing stock inventory for each period in the forest model\n",
" ogs = [fm.inventory(period, \"totvol\") for period in fm.periods]\n",
"\n",
" # Create a dictionary to hold the compiled data and convert it to a DataFrame\n",
" data = {\"period\": fm.periods,\n",
" \"oha\": oha,\n",
" \"ohv\": ohv,\n",
" \"ogs\": ogs}\n",
" df = pd.DataFrame(data)\n",
"\n",
" return df\n",
"\n",
" # Helper function to plot scenario data\n",
" def plot_scenario(df):\n",
" \"\"\"\n",
" Plots the harvested area, volume, and growing stock for a given scenario.\n",
"\n",
" Parameters:\n",
" df (pandas DataFrame): The compiled scenario data to plot.\n",
" \"\"\"\n",
" fig, ax = plt.subplots(1, 3, figsize=(12, 4))\n",
"\n",
" # Plot harvested area\n",
" ax[0].bar(df.period, df.oha)\n",
" ax[0].set_ylim(0, None)\n",
" ax[0].set_title(\"Harvested Area (ha)\")\n",
"\n",
" # Plot harvested volume\n",
" ax[1].bar(df.period, df.ohv)\n",
" ax[1].set_ylim(0, None)\n",
" ax[1].set_title(\"Harvested Volume (m3)\")\n",
"\n",
" # Plot growing stock\n",
" ax[2].bar(df.period, df.ogs)\n",
" ax[2].set_ylim(0, None)\n",
" ax[2].set_title(\"Growing Stock (m3)\")\n",
"\n",
" return fig, ax\n",
"\n",
" # Create the optimization problem for this scenario\n",
" problem = forest_model.add_problem(name=scenario_name,\n",
" coeff_funcs=coeff_funcs,\n",
" cflw_e=cflw_e,\n",
" cgen_data=cgen_data,\n",
" acodes=acodes,\n",
" sense=sense,\n",
" mask=None,\n",
" verbose=verbose,\n",
" workers=workers)\n",
"\n",
" # Set the solver and solve the optimization problem\n",
" problem.solver(solver)\n",
" forest_model.reset()\n",
" problem.solve(verbose=verbose)\n",
"\n",
" if problem.status() != ws3.opt.STATUS_OPTIMAL:\n",
" print(\"Model not optimal.\")\n",
" df = None\n",
" fig = None\n",
" else:\n",
" # Compile schedule from optimization problem\n",
" schedule = forest_model.compile_schedule(problem)\n",
"\n",
" # Apply compiled schedule to the forest model\n",
" forest_model.apply_schedule(schedule,\n",
" force_integral_area=False,\n",
" override_operability=False,\n",
" fuzzy_age=False,\n",
" recourse_enabled=False,\n",
" verbose=False,\n",
" compile_c_ycomps=True)\n",
"\n",
" # Re-compile scenario data with new schedule applied\n",
" df = compile_scenario(forest_model)\n",
"\n",
" # Plot the compiled scenario data\n",
" fig, ax = plot_scenario(df)\n",
" return fig, df, problem\n",
"\n"
]
},
{
"cell_type": "markdown",
"metadata": {},
"source": [
"Now we can easily formulate and solve an optimization problem, compile an action schedule from the optimal solution and simulate it in `ws3`, and plot results."
]
},
{
"cell_type": "code",
"execution_count": 23,
"metadata": {},
"outputs": [
{
"data": {
"text/plain": [
"(,\n",
" period oha ohv ogs\n",
" 0 1 956.419884 102585.020390 30405.125309\n",
" 1 2 34.885672 4798.494437 28607.304394\n",
" 2 3 0.000000 0.000000 32154.392350\n",
" 3 4 0.000000 0.000000 38166.885368\n",
" 4 5 0.000000 0.000000 47379.394949\n",
" 5 6 0.000000 0.000000 59578.656570\n",
" 6 7 0.000000 0.000000 77531.535059\n",
" 7 8 0.000000 0.000000 103522.146540\n",
" 8 9 0.000000 0.000000 134548.020901\n",
" 9 10 266.188474 23379.503408 135984.046132,\n",
" )"
]
},
"execution_count": 23,
"metadata": {},
"output_type": "execute_result"
},
{
"data": {
"image/png": "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RsLBwQF9+/bFgAED0K1bN8nrG+VyOQ4dOoT09HS4uLjgk08+QXBwsOQ1kF26dBHH6LZt22Lnzp2Ijo6Gk5OTbg4GEVEl6QmCINR0EtVBrVZDLpcjNze30ld/ms3Yr/U8bnztpfV1ElH1e3IM2bdvH2bOnInr16/D3t4eQUFBGD9+vBgvCALmzJmDdevWIScnB926dcM333yDN998U4zJzs5GQEAA9u7dC319fQwZMgQrV65E3bp1xZgLFy7A398fZ86cQcOGDTF58mR89tlnktx27NiBWbNm4caNG2jRogVCQ0MxYMCAKu9bZWl7jOT4SPTiquo4Utu9rPtFLzZd/PzVVR30Iu7Ls56vVHYcMXzexIiIXgUDBw7EwIEDy+3X09PDvHnzMG/evHJjLC0tERUV9dTttGnTBidOnHhqzLBhwzBs2LCnJ0xEREREtRZvTSciIiIiIiLSIRbiRERERERERDrEQpyIiIiIiIhIh1iIExEREREREekQC3EiIiIiIiIiHWIhTkRERERERKRDLMSJiIiIiIiIdIiFOBEREREREZEOsRAnIiIiIiIi0iEW4kREREREREQ6xEKciIiIiIiISIdYiBMRERERERHpEAtxIiIiIiIiIh1iIU5ERERERESkQyzEiYiIiIiIiHSIhTgRERERERGRDrEQJyIiIiIiItIhFuJEREREREREOsRCnIiIiIiIiEiHWIgTERERERER6RALcSIiIiIiIiIdYiFOREREREREpEMsxImIiIiIiIh0iIU4ERERERERkQ6xECciIiIiIiLSIRbiRERERERERDrEQpyIiIiIiIhIh1iIExEREREREekQC3EiIiIiIiIiHWIhTkRERERERKRDLMSJiIiIiIiIdIiFOBERERE9l1u3buG9995DgwYNYGpqCmdnZ5w9e1bsFwQBwcHBaNSoEUxNTeHh4YHr169L1pGdnQ1fX1+Ym5vDwsICfn5+uHfvniTmwoUL6N69O0xMTGBra4vQ0NBSuezYsQMODg4wMTGBs7MzDhw4UD07TUT0HFiIExEREVGV3blzB127doWRkRF++eUXXL58GUuXLkX9+vXFmNDQUKxcuRIRERFISkqCmZkZlEol8vPzxRhfX1+kpqYiNjYW+/btQ3x8PCZMmCD2q9VqeHp6ws7ODsnJyVi8eDHmzp2LdevWiTEJCQkYMWIE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",
"text/plain": [
""
]
},
"metadata": {},
"output_type": "display_data"
}
],
"source": [
"acodes = [\"null\", \"harvest\"]\n",
"run_scenario(fm, \"scenario-2\", ws3.opt.SENSE_MAXIMIZE, acodes, coeff_funcs, None, cgen_data)\n"
]
},
{
"cell_type": "markdown",
"metadata": {},
"source": [
"This new function will allow us to easily run several different scenarios. We can also easily add new scenarios to the model by simply changing the input parameters and observing how it affects model output and behaviour."
]
},
{
"cell_type": "markdown",
"metadata": {},
"source": [
"Note that our new `run_scenario` function includes a `verbose` arg that we can use to to print out more information as `ws3` formulates and solves a new optimization problem."
]
},
{
"cell_type": "code",
"execution_count": 24,
"metadata": {},
"outputs": [
{
"name": "stdout",
"output_type": "stream",
"text": [
"add_problem: build problem\n",
"generate trees using 1 workers\n",
"process trees\n",
"_bld_p_m1: build problem\n",
"_bld_p_m1: done building problem\n",
"add_problem: compile flow constraints\n",
"add_problem: compile general constraints\n",
"Running HiGHS 1.11.0 (git hash: 364c83a): Copyright (c) 2025 HiGHS under MIT licence terms\n",
"LP has 34 rows; 305 cols; 585 nonzeros\n",
"Coefficient ranges:\n",
" Matrix [1e+00, 5e+04]\n",
" Cost [2e+01, 4e+04]\n",
" Bound [1e+00, 1e+00]\n",
" RHS [1e+00, 1e+09]\n",
"Presolving model\n",
"25 rows, 218 cols, 350 nonzeros 0s\n",
"22 rows, 151 cols, 280 nonzeros 0s\n",
"Dependent equations search running on 21 equations with time limit of 1000.00s\n",
"Dependent equations search removed 0 rows and 0 nonzeros in 0.00s (limit = 1000.00s)\n",
"22 rows, 151 cols, 280 nonzeros 0s\n",
"Presolve : Reductions: rows 22(-12); columns 151(-154); elements 280(-305)\n",
"Solving the presolved LP\n",
"Using EKK parallel dual simplex solver - SIP with concurrency of 8\n",
" Iteration Objective Infeasibilities num(sum)\n",
" 0 0.0000000000e+00 Ph1: 0(0) 0s\n",
" 39 -1.3076301824e+05 Pr: 0(0); Du: 0(4.26326e-13) 0s\n",
"Solving the original LP from the solution after postsolve\n",
"Model status : Optimal\n",
"Simplex iterations: 39\n",
"Objective value : -1.3076301824e+05\n",
"P-D objective error : 5.5642106547e-17\n",
"HiGHS run time : 0.00\n"
]
},
{
"data": {
"text/plain": [
"(,\n",
" period oha ohv ogs\n",
" 0 1 956.419884 102585.020390 30405.125309\n",
" 1 2 34.885672 4798.494437 28607.304394\n",
" 2 3 0.000000 0.000000 32154.392350\n",
" 3 4 0.000000 0.000000 38166.885368\n",
" 4 5 0.000000 0.000000 47379.394949\n",
" 5 6 0.000000 0.000000 59578.656570\n",
" 6 7 0.000000 0.000000 77531.535059\n",
" 7 8 0.000000 0.000000 103522.146540\n",
" 8 9 0.000000 0.000000 134548.020901\n",
" 9 10 266.188474 23379.503408 135984.046132,\n",
" )"
]
},
"execution_count": 24,
"metadata": {},
"output_type": "execute_result"
},
{
"data": {
"image/png": "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RsLBwQF9+/bFgAED0K1bN8nrG+VyOQ4dOoT09HS4uLjgk08+QXBwsOQ1kF26dBHH6LZt22Lnzp2Ijo6Gk5OTbg4GEVEl6QmCINR0EtVBrVZDLpcjNze30ld/ms3Yr/U8bnztpfV1ElH1e3IM2bdvH2bOnInr16/D3t4eQUFBGD9+vBgvCALmzJmDdevWIScnB926dcM333yDN998U4zJzs5GQEAA9u7dC319fQwZMgQrV65E3bp1xZgLFy7A398fZ86cQcOGDTF58mR89tlnktx27NiBWbNm4caNG2jRogVCQ0MxYMCAKu9bZWl7jOT4SPTiquo4Utu9rPtFLzZd/PzVVR30Iu7Ls56vVHYcMXzexIiIXgUDBw7EwIEDy+3X09PDvHnzMG/evHJjLC0tERUV9dTttGnTBidOnHhqzLBhwzBs2LCnJ0xEREREtRZvTSciIiIiIiLSIRbiRERERERERDrEQpyIiIiIiIhIh1iIExEREREREekQC3EiIiIiIiIiHWIhTkRERERERKRDLMSJiIiIiIiIdIiFOBEREREREZEOsRAnIiIiIiIi0iEW4kREREREREQ6xEKciIiIiIiISIdYiBMRERERERHpEAtxIiIiIiIiIh1iIU5ERERERESkQyzEiYiIiIiIiHSIhTgRERERERGRDrEQJyIiIiIiItIhFuJEREREREREOsRCnIiIiIiIiEiHWIgTERERERER6RALcSIiIiIiIiIdYiFOREREREREpEMsxImIiIiIiIh0iIU4ERERERERkQ6xECciIiIiIiLSIRbiRERERERERDrEQpyIiIiIiIhIh1iIExEREREREekQC3EiIiIiIiIiHWIhTkRERERERKRDLMSJiIiIiIiIdIiFOBERERE9l1u3buG9995DgwYNYGpqCmdnZ5w9e1bsFwQBwcHBaNSoEUxNTeHh4YHr169L1pGdnQ1fX1+Ym5vDwsICfn5+uHfvniTmwoUL6N69O0xMTGBra4vQ0NBSuezYsQMODg4wMTGBs7MzDhw4UD07TUT0HFiIExEREVGV3blzB127doWRkRF++eUXXL58GUuXLkX9+vXFmNDQUKxcuRIRERFISkqCmZkZlEol8vPzxRhfX1+kpqYiNjYW+/btQ3x8PCZMmCD2q9VqeHp6ws7ODsnJyVi8eDHmzp2LdevWiTEJCQkYMWIE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",
"text/plain": [
""
]
},
"metadata": {},
"output_type": "display_data"
}
],
"source": [
"acodes = [\"null\", \"harvest\"]\n",
"run_scenario(fm, \"scenario-2\", ws3.opt.SENSE_MAXIMIZE, acodes, coeff_funcs, None, cgen_data, verbose=True)\n"
]
},
{
"cell_type": "markdown",
"metadata": {},
"source": [
"The `run_scenario` function also includes a `workers` argument that we pass to `ForestModel.add_problem` and `Problem.solve` to control how many parallel workers to use when formulating and solving the optimization problem."
]
},
{
"cell_type": "code",
"execution_count": 25,
"metadata": {},
"outputs": [
{
"name": "stdout",
"output_type": "stream",
"text": [
"add_problem: build problem\n",
"generate trees using 4 workers\n"
]
},
{
"name": "stdout",
"output_type": "stream",
"text": [
"process trees\n",
"_bld_p_m1: build problem\n",
"_bld_p_m1: done building problem\n",
"add_problem: compile flow constraints\n",
"add_problem: compile general constraints\n",
"Running HiGHS 1.11.0 (git hash: 364c83a): Copyright (c) 2025 HiGHS under MIT licence terms\n",
"LP has 34 rows; 305 cols; 585 nonzeros\n",
"Coefficient ranges:\n",
" Matrix [1e+00, 5e+04]\n",
" Cost [2e+01, 4e+04]\n",
" Bound [1e+00, 1e+00]\n",
" RHS [1e+00, 1e+09]\n",
"Presolving model\n",
"25 rows, 218 cols, 350 nonzeros 0s\n",
"22 rows, 151 cols, 280 nonzeros 0s\n",
"Dependent equations search running on 21 equations with time limit of 1000.00s\n",
"Dependent equations search removed 0 rows and 0 nonzeros in 0.00s (limit = 1000.00s)\n",
"22 rows, 151 cols, 280 nonzeros 0s\n",
"Presolve : Reductions: rows 22(-12); columns 151(-154); elements 280(-305)\n",
"Solving the presolved LP\n",
"Using EKK parallel dual simplex solver - SIP with concurrency of 8\n",
" Iteration Objective Infeasibilities num(sum)\n",
" 0 0.0000000000e+00 Ph1: 0(0) 0s\n",
" 42 -1.3076301824e+05 Pr: 0(0); Du: 0(1.5703e-12) 0s\n",
"Solving the original LP from the solution after postsolve\n",
"Model status : Optimal\n",
"Simplex iterations: 42\n",
"Objective value : -1.3076301824e+05\n",
"P-D objective error : 2.2256842619e-16\n",
"HiGHS run time : 0.00\n"
]
},
{
"data": {
"text/plain": [
"(,\n",
" period oha ohv ogs\n",
" 0 1 956.419884 102585.020390 30405.125309\n",
" 1 2 34.885672 4798.494437 28607.304394\n",
" 2 3 0.000000 0.000000 32154.392350\n",
" 3 4 0.000000 0.000000 38166.885368\n",
" 4 5 0.000000 0.000000 47379.394949\n",
" 5 6 0.000000 0.000000 59578.656570\n",
" 6 7 0.000000 0.000000 77531.535059\n",
" 7 8 0.000000 0.000000 103522.146540\n",
" 8 9 0.000000 0.000000 134548.020901\n",
" 9 10 257.521626 23379.503408 135984.046132,\n",
" )"
]
},
"execution_count": 25,
"metadata": {},
"output_type": "execute_result"
},
{
"data": {
"image/png": "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RsLBwQF9+/bFgAED0K1bN8nrG+VyOQ4dOoT09HS4uLjgk08+QXBwsOQ1kF26dBHH6LZt22Lnzp2Ijo6Gk5OTbg4GEVEl6QmCINR0EtVBrVZDLpcjNze30ld/ms3Yr/U8bnztpfV1ElH1e3IM2bdvH2bOnInr16/D3t4eQUFBGD9+vBgvCALmzJmDdevWIScnB926dcM333yDN998U4zJzs5GQEAA9u7dC319fQwZMgQrV65E3bp1xZgLFy7A398fZ86cQcOGDTF58mR89tlnktx27NiBWbNm4caNG2jRogVCQ0MxYMCAKu9bZWl7jOT4SPTiquo4Utu9rPtFLzZd/PzVVR30Iu7Ls56vVHYcMXzexIiIXgUDBw7EwIEDy+3X09PDvHnzMG/evHJjLC0tERUV9dTttGnTBidOnHhqzLBhwzBs2LCnJ0xEREREtRZvTSciIiIiIiLSIRbiRERERERERDrEQpyIiIiIiIhIh1iIExEREREREekQC3EiIiIiIiIiHWIhTkRERERERKRDLMSJiIiIiIiIdIiFOBEREREREZEOsRAnIiIiIiIi0iEW4kREREREREQ6xEKciIiIiIiISIdYiBMRERERERHpEAtxIiIiIiIiIh1iIU5ERERERESkQyzEiYiIiIiIiHSIhTgRERERERGRDrEQJyIiIiIiItIhFuJEREREREREOsRCnIiIiIiIiEiHWIgTERERERER6RALcSIiIiIiIiIdYiFOREREREREpEMsxImIiIiIiIh0iIU4ERERERERkQ6xECciIiIiIiLSIRbiRERERERERDrEQpyIiIiIiIhIh1iIExEREREREekQC3EiIiIiIiIiHWIhTkRERERERKRDLMSJiIiIiIiIdIiFOBERERE9l1u3buG9995DgwYNYGpqCmdnZ5w9e1bsFwQBwcHBaNSoEUxNTeHh4YHr169L1pGdnQ1fX1+Ym5vDwsICfn5+uHfvniTmwoUL6N69O0xMTGBra4vQ0NBSuezYsQMODg4wMTGBs7MzDhw4UD07TUT0HFiIExEREVGV3blzB127doWRkRF++eUXXL58GUuXLkX9+vXFmNDQUKxcuRIRERFISkqCmZkZlEol8vPzxRhfX1+kpqYiNjYW+/btQ3x8PCZMmCD2q9VqeHp6ws7ODsnJyVi8eDHmzp2LdevWiTEJCQkYMWIE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",
"text/plain": [
""
]
},
"metadata": {},
"output_type": "display_data"
}
],
"source": [
"acodes = [\"null\", \"harvest\"]\n",
"run_scenario(fm, \"scenario-2\", ws3.opt.SENSE_MAXIMIZE, acodes, coeff_funcs, None, cgen_data, verbose=True, workers=4)\n"
]
},
{
"cell_type": "markdown",
"metadata": {},
"source": [
"### Adding harvest volume even-flow constraints\n",
"\n",
"Even flow constraints are defined in terms of proportional variations in periodic flows, relative to a reference period.\n",
"\n",
"To define an even flow constraint on harvest volume, we need a coefficient function that compiles harvest volume by period. We wil start by defining a more generic coefficient function `cmp_c_caa`, that can compile coefficients for any product depending on the value of `expr` that is passed to the function, and then later specialize this function using `functools.partial` to compile harvested volume. "
]
},
{
"cell_type": "code",
"execution_count": 26,
"metadata": {},
"outputs": [],
"source": [
"def cmp_c_caa(fm, path, expr, acodes, mask=None): # product, named actions\n",
" \"\"\"\n",
" Compile constraint coefficient for product indicator (given ForestModel \n",
" instance, leaf-to-root-node path, expression to evaluate, list of action codes, \n",
" and optional mask).\n",
" \"\"\"\n",
" result = {}\n",
" for t, n in enumerate(path, start=1):\n",
" d = n.data()\n",
" if mask and not fm.match_mask(mask, d[\"dtk\"]): continue\n",
" if d[\"acode\"] in acodes:\n",
" result[t] = fm.compile_product(t, expr, d[\"acode\"], [d[\"dtk\"]], d[\"age\"], coeff=False)\n",
" return result\n"
]
},
{
"cell_type": "code",
"execution_count": 27,
"metadata": {},
"outputs": [],
"source": [
"coeff_funcs[\"cflw_hv\"] = functools.partial(cmp_c_caa, expr=\"totvol * 0.85\", acodes=[\"harvest\"])\n"
]
},
{
"cell_type": "markdown",
"metadata": {},
"source": [
"Next we need to define the `cflw_e` argument for the `add_problem` method, which defines periodic _epsilon_ values for the flow constraint (i.e., the allowable proportional variation level). See the mathematical model formulation at the top of this notebook for more details on how the epsilon parameter is used in the flow constraint definition.\n",
"\n",
"Note that we need to use the same constraint name here as we used above to define the `cflw_hv` coefficient function mapping so that `ws3` can link left-hand-side (LHS) and right-hand-side (RHS) values when it builds each constraint."
]
},
{
"cell_type": "code",
"execution_count": 28,
"metadata": {},
"outputs": [],
"source": [
"cflw_e = {\"cflw_hv\":({p:0.05 for p in fm.periods}, 1)}\n"
]
},
{
"cell_type": "markdown",
"metadata": {},
"source": [
"Now we can run our model again with `run_scenario`, passing in the new harvest volume flow constraint parameters."
]
},
{
"cell_type": "code",
"execution_count": 29,
"metadata": {},
"outputs": [
{
"data": {
"text/plain": [
"(,\n",
" period oha ohv ogs\n",
" 0 1 81.490393 11505.674653 137557.296765\n",
" 1 2 88.328985 12080.958385 136215.193742\n",
" 2 3 75.802288 12080.958385 133278.227164\n",
" 3 4 79.588800 10930.390920 132205.401813\n",
" 4 5 79.657228 10930.390920 133028.457906\n",
" 5 6 79.744249 10930.390920 134576.453980\n",
" 6 7 80.687348 10930.390920 136326.683219\n",
" 7 8 79.987614 10930.390920 137283.043147\n",
" 8 9 79.434817 10930.390920 137053.561019\n",
" 9 10 68.242127 10930.390920 135984.046132,\n",
" )"
]
},
"execution_count": 29,
"metadata": {},
"output_type": "execute_result"
},
{
"data": {
"image/png": "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HKwjR46YTw7/4osvVFhYqH79+ln93fj4+KhJkyZXPPv0559/ysHB4ZK3w/Tt21fu7u5W40vS448/bvXgteDgYOXn55t/Rxf75ptvtHLlSk2bNk0NGzY0P/O/I7fiein6t1rSz3nnzp11yy23mNu8efOKxfz9areVK1eqWrVqeuGFF6za//Wvf8kwDPOy7DvuuEM1a9bUhg0bJF0441x0ufL27dt15swZGYah77//Xh07drzicdjynSYpKUn169c3z3JLkrOzs4YOHXrF/UsXLjtOSUnRww8/rB9//FFxcXEKCwtT/fr1S7y15u9Kkzs///xztW3b1rzK6GJ/v/w6JydHXbt21b59+/Tdd98Vu0qwJFf6jtiiRQuFhISYr4vy2wMPPKCGDRsWa7/4cy7yxhtvaPXq1Xr//fd1zz33KD8/v8SVHchv1ricuwLcfffdCgoKKtZeu3btYj+YP/zwg1555RWlpKTozJkzVn05OTlWXwwCAgJKHO+xxx7Tyy+/rKNHj6p+/fr67rvvdPz4casln/bv36+cnByre0UuVvQghvvuu0+9e/fWq6++qhkzZqhz584KDw/XwIED5eTkdNnj/uWXX2QYhsaPH3/JJZaOHz+u+vXr69ChQyVertS0adPLjlEkOztbK1euVHR0tH755RezvX379vr888/1888/6/bbb7d6z98/v/3790vSZR9ElpOTo9q1a+uvv/7SlClTtHDhQh09etTqfqK/FwKXYlzi/uQGDRoUS8S1a9cutozFhx9+qGnTpmnfvn1WX/5L+rkoGuvv+wXKAjnu+uc46cIl3UuXLtWXX36pgQMHatOmTTp48KCGDx8u6cJT/8+cOVPiPps3b67CwkIdOXJELVu2tHnMy7n4C5sk8+/u4vszi9oLCwuVk5OjOnXqaP/+/TIMQ02aNClxvxcX5td7XpKK3SMvybzvvnv37urVq5datWqlmjVrKjo62iqO3IrrpVatWpIuXD78d++8845OnTqlrKwsqwK1iIODgxo0aGDVdujQIfn6+pr7LdK8eXOzX7rwS/qQkBBzNYCNGzeqY8eO6tChg86fP6/NmzfL29tbJ06csKmItuU7zaFDh9S4ceNicUUnRWxx11136YsvvlB+fr5+/PFHLV26VDNmzFCfPn2Unp6uFi1aXPK9pcmdv/76q3r37m3TnGJiYnT27Fnt2LGj1Hn3Ut8RyyK/XVzMP/7447rzzjv1xBNPFFvXmvxmjSK6Evv111/VpUsXNWvWTNOnT5efn58cHR21cuVKzZgxo9gDaC51L91jjz2msWPHasmSJYqJidGnn34qd3d3q6fuFRYWysvL65JnaYsepFO0WPzmzZv11VdfadWqVXryySc1bdo0bd68+ZJnAorGkKQXX3yx2NmkIqVJkJezZMkS5eXladq0aZo2bVqx/oSEBL366qtWbX///Irm++abb17yt4VFx/v8889r4cKFiomJUUhIiNzd3WVnZ6f+/ftf8UFBderUkVRyYpMu/AdWkosT6scff6wnnnhC4eHhGjVqlLy8vFStWjVNmTKlxOVWisYq6V4doLyQ465N0UNpEhMTNXDgQCUmJqpatWpW94Ffi0t9UTp//nyJeelSuepKOaywsNB8IFFJsZf7zKULOfTcuXM6depUsYLgWuZ1KY0bN9Ydd9yhhISEYkU0uRXXi7u7u+rVq6fdu3cX6yv6hdylHmbq5OR0TauNdOjQwVwjeOPGjfr3v/8tDw8PtWrVShs3bpS3t7ck2VREX+2/u6vl6Oiou+66S3fddZduv/12DRkyREuWLNErr7xyXca7nF69eumTTz7RG2+8oY8++simv5Or/Y54tZ+zo6OjHn74Yb3xxhv666+/rP7fJb9Zo4iuxL766ivl5eVp+fLlVr9psvXBCkUCAgJ09913a/HixYqOjtYXX3yh8PBwq7MqjRs31rfffqv27dvb9GCbe+65R/fcc49ee+01JSYmKiIiQp988omeeuqpS37xKrokpnr16sWeovp3/v7+5pngi2VkZFxxbtKFIrlVq1YlJsl33nlHiYmJxYrovyt6uISbm9sV5/vZZ59p8ODBVgX72bNnS3y64d81bNhQLi4uOnDgwBVjLzf+rbfeqi+++MLq87/UfxJFYxX9xhmoCOS4q89x0oUvxn369NFHH32krKwsLVmyRA888ID5gLVbbrlFNWrUKHGf+/btk729fbGzFRerXbt2iTns0KFDVpc4XqvGjRvLMAwFBAQUu0LIFs2aNZN0Ia+VdMvA9fDXX3+V+ITxAwcOyN7e/qqOA7iSHj166L333tOWLVusbgW5Gv7+/vr222+L/fJp3759Zn+Rjh07Kj8/X//973919OhRs1ju1KmTWUTffvvtZjF9rfz9/fXTTz/JMAyrfHvxlYVXo+gKqf/7v/8z20rK56XJnY0bNy7xFxslCQ8PV9euXfXEE0+oVq1aJa5E8XcX57fy8tdff8kwDJ06dcrq/0u+O1rjnuhKrOi3SH+/NHjhwoWl3tdjjz2mzZs364MPPtAff/xhdZmjJPXr10/nz5/XpEmTir333Llz5hepkydPFvstVtFZ2qIvFEVPov77ly8vLy917txZ77zzjlUCK/L777+bf37wwQe1efNmbdmyxar/UmeRLnbkyBFt2LBB/fr1U58+fYptQ4YM0S+//KLU1NTL7icwMFCNGzfWW2+9VeLlUxfPt1q1asU+lzlz5uj8+fNXnG/16tUVFBSkbdu2XTH2Ukr6WUlNTVVKSkqJ8WlpaXJ3dy+zyziBq0GOu7ocd7GIiAgVFBTo6aef1u+//251T3W1atXUtWtXffnll1ZnqLKyspSYmKgOHTpc9gnSjRs31ubNm5Wfn2+2rVixwqZlp0rj0UcfVbVq1fTqq68W++wNwzDvCbyUovsBryWHluTcuXMlnv3ZsmWLdu3aVeItC2lpaWrZsqXVbQhAWRk9erRq1KihJ598UllZWcX6S3M298EHH9T58+c1d+5cq/YZM2bIzs7OfFK2dOFMd/Xq1TV16lR5enqa3x06duyozZs3a/369TadhbZVWFiYjh49anX/8tmzZ/Xuu+/a9P5169aV+FmsXLlSkvVtM66ursVyeWlyZ+/evc3Lxf+upDkMGjRIs2fPVnx8vF566aUrHkv9+vXl5+dX5vlNKnnN7OzsbH3++efy8/MrdvtTWlqa7OzsrO7Brso4E12Jde3aVY6OjurZs6eefvppnT59Wu+++668vLxK/IJ2Of369dOLL76oF198UZ6ensXOktx33316+umnNWXKFKWnp6tr166qXr269u/fryVLlmjWrFnq06ePPvzwQ7399tt65JFH1LhxY506dUrvvvuu3Nzc9OCDD0q6cMllixYttHjxYt1+++3y9PRUq1at1KpVK82bN08dOnRQ69atNXToUN16663KyspSSkqK/ve//+nHH3+UdOE/iv/85z/q1q2bhg8fbi7/4u/vX+xe4L9LTEw0l24oyYMPPigHBwclJCRcdpkIe3t7vffee+revbtatmypIUOGqH79+jp69KjWrVsnNzc3ffXVV5IuXFb5n//8R+7u7mrRooVSUlL07bffmpfhXEmvXr3073//+6qXRXnooYf0xRdf6JFHHlGPHj104MABxcfHq0WLFiX+AiA5Odlc5xGoKOS4q8txfz+uBg0a6Msvv5SLi4u55FaRyZMnKzk5WR06dNBzzz0nBwcHvfPOO8rLyytxbdaLPfXUU/rss8/UrVs39evXT7/++qs+/vhj8yqdstK4cWNNnjxZY8eO1cGDBxUeHq5atWrpwIEDWrp0qYYNG6YXX3zxku+/9dZb1apVK3377bfFHmJ2LU6fPi0/Pz899thjatmypVxdXbVr1y4tXLhQ7u7uxe57Lygo0Pr1680lZYCy1qRJEyUmJmrAgAFq2rSpIiIi1LZtWxmGoQMHDigxMVH29vbF7n8uSc+ePXX//ffr3//+tw4ePKi2bdtq9erV+vLLLxUTE2P177xGjRoKDAzU5s2brb47dOrUSbm5ucrNzS3TIvrpp5/W3LlzNWDAAA0fPlz16tVTQkKCnJ2dJV35ntznn39eZ86c0SOPPKJmzZopPz9fmzZt0uLFi9WoUSMNGTLEjA0MDNS3336r6dOny9fXVwEBAQoODrY5d44aNUqfffaZ+vbtqyeffFKBgYE6ceKEli9frvj4eLVt27bY/KKjo2WxWPTvf/9b7u7uJS4ndbFevXpp6dKlxc7MX6vu3burQYMGCg4OlpeXlw4fPqyFCxfq2LFjVg/rLJKcnKz27dvb/N32pnedn/6NixQt/3KppVPuu+++Ysu/LF++3GjTpo3h7OxsNGrUyJg6darxwQcfFFsCxd/f3+jRo8dlx2/fvr0hyXjqqacuGbNgwQIjMDDQcHFxMWrVqmW0bt3aGD16tHHs2DHDMAxj+/btxoABA4yGDRsaTk5OhpeXl/HQQw8Z27Zts9rPpk2bjMDAQMPR0bHYUjC//vqrMWjQIMPHx8eoXr26Ub9+feOhhx4yPvvsM6t97Ny507jvvvsMZ2dno379+sakSZOM999//4rLv7Ru3dpo2LDhZT+Lzp07G15eXkZBQYHV0gMl2bFjh/Hoo48aderUMZycnAx/f3+jX79+xpo1a8yYkydPGkOGDDHq1q1r1KxZ0wgLCzP27dt3ySVi/i4rK8twcHAw/vOf/1i1l/QzYRgXlqy4eImYwsJC4/XXXzf8/f0NJycn44477jBWrFhRLM4wDGPv3r2GJOPbb7+94ryA0iDHXXC9c9zfjRo1ypBk9OvXr8T+7du3G2FhYUbNmjWNGjVqGPfff7/VkiiGUfJyNIZxYamZ+vXrG05OTkb79u2Nbdu2XXKJq7/n0Ev9PLzyyiuGJOP333+3av/888+NDh06GK6uroarq6vRrFkzIyoqylyu63KmT59utaSZYfz/S1y9+eabJR7rleabl5dnDB8+3GjTpo3h5uZmVK9e3fD39zciIyNL/Pv55ptvrJZVBK6XX375xXj22WeN2267zXB2djZcXFyMZs2aGc8884yRnp5uFTt48GDD1dW1xP2cOnXKGDFihOHr62tUr17daNKkifHmm29aLetZpCjP/H15o9tuu82QZLUUlGFceokrW77TGIZh/Pbbb0aPHj0MFxcX45ZbbjH+9a9/GZ9//rkhydi8efPlPh7jm2++MZ588kmjWbNmRs2aNQ1HR0fjtttuM55//nkjKyvLKnbfvn1Gp06dDBcXF0OS1Xc2W3KnYRjGn3/+aURHRxv169c3HB0djQYNGhiDBw82/vjjD6vP4u85Z/To0YYkY+7cuZc9nu3btxuSjI0bN1q1X+r/RUlGVFSUVVtJ+XDu3LlGhw4djLp16xoODg7GLbfcYvTs2dPYsGFDsX1mZ2cbjo6OxnvvvXfZuVYldoZxne7kB1AqkZGR+vnnn80nYF4vMTEx2rBhg3lZDgDc6HJycnTrrbcqLi5OkZGRFTKH8PBw2dnZlXhZJ4BrN3PmTI0YMUL/+9//VL9+/YqeTrnq0qWLfH199Z///KdCxp85c6bi4uL066+/2vRckaqAIhqoJA4fPqzbb79da9asUfv27a/LGH/++af8/f316aefmpemAsDNYOrUqVq4cKF++umna3oS8dXYu3evWrdurfT0dLVq1apcxwZuRn9/MvTZs2d1xx136Pz58/r5558rcGYVIzU1VR07dtT+/futHvpWHgoKCtS4cWONGTOG21UuQhENAAAAoNLo3r27GjZsqHbt2iknJ0cff/yx9uzZo4SEBA0cOLCipwfwYDEAAAAAlUdYWJjee+89JSQk6Pz582rRooU++eSTYisvABWFM9EAAAAAANiIdaIBAAAAALARRTQAAAAAADaqdPdEFxYW6tixY6pVqxbL7wC4KoZh6NSpU/L19S33p/Reb+RIANeC/AgAJStNfqx0RfSxY8fk5+dX0dMAcBM4cuSIGjRoUNHTKFPkSABlgfwIACWzJT9WuiK6Vq1aki5M3s3NrYJnA+BGZLFY5OfnZ+aTmwk5EsC1ID8CQMlKkx8rXRFddPmNm5sbCRDANbkZL+cjRwIoC+RHACiZLfnx5roZBgAAAACA64giGgAAAAAAG1FEAwAA3IQ2bNignj17ytfXV3Z2dlq2bNklY5955hnZ2dlp5syZVu0nTpxQRESE3Nzc5OHhocjISJ0+fdoqZufOnerYsaOcnZ3l5+enuLi4YvtfsmSJmjVrJmdnZ7Vu3VorV6606jcMQ7GxsapXr55cXFwUGhqq/fv3X/WxA8D1RBENAABwE8rNzVXbtm01b968y8YtXbpUmzdvlq+vb7G+iIgI7dmzR8nJyVqxYoU2bNigYcOGmf0Wi0Vdu3aVv7+/0tLS9Oabb2rChAlasGCBGbNp0yYNGDBAkZGR2rFjh8LDwxUeHq7du3ebMXFxcZo9e7bi4+OVmpoqV1dXhYWF6ezZs2XwSQBA2bIzDMOo6ElczGKxyN3dXTk5OTwUAsBVuZnzyM18bACuHzs7Oy1dulQPPPCAVQ45evSogoODtWrVKvXo0UMxMTGKiYmRJO3du1ctWrTQ1q1bFRQUJElKSkrSgw8+qP/973/y9fXV/Pnz9e9//1uZmZlydHSUJI0ZM0bLli3Tvn37JEmPPfaYcnNztWLFCnM+99xzj9q1a6f4+HgZhiFfX1/961//0osvvihJysnJkbe3txYtWqT+/fvbdIzkRwDXojQ5hDPRAAAAVVBhYaH++c9/atSoUWrZsmWx/pSUFHl4eJgFtCSFhobK3t5eqampZkynTp3MAlqSwsLClJGRoZMnT5oxoaGhVvsOCwtTSkqKJOnAgQPKzMy0inF3d1dwcLAZAwCVSaVb4goAAADX39SpU+Xg4KAXXnihxP7MzEx5eXlZtTk4OMjT01OZmZlmTEBAgFWMt7e32Ve7dm1lZmaabRfHXLyPi99XUkxJ8vLylJeXZ762WCyXjAWAssSZaAAAgCpmx44dmjVrlhYtWnTDrhk9ZcoUubu7m5ufn19FTwlAFUERDQAAUMWkpKTo+PHjatiwoRwcHOTg4KBDhw7pX//6lxo1aiRJ8vHx0fHjx63ed+7cOZ04cUI+Pj5mTFZWllVM0esrxVzcf/H7SoopydixY5WTk2NuR44cKc1HAABXjSIawE3vcsu8FBQU6KWXXlLr1q3l6uoqX19fDRo0SMeOHbPaR3kt8wIA5aF///7auXOn0tPTzc3X11ejRo3SqlWrJEkhISHKzs5WWlqa+b61a9eqsLBQwcHBZsyGDRtUUFBgxiQnJ6tp06aqXbu2GbNmzRqr8ZOTkxUSEiJJCggIkI+Pj1WMxWJRamqqGVMSJycnubm5WW0AUB4oogHc9C63zMuZM2e0fft2jR8/Xtu3b9cXX3yhjIwMPfzww1Zx5bXMCwCUldOnT5sFsnThAV47d+6UJHl6eqpVq1ZWW/Xq1eXj46OmTZtKkpo3b65u3bpp6NCh2rJli3744QdFR0erf//+5nJYAwcOlKOjoyIjI7Vnzx4tXrxYs2bN0siRI815DB8+XElJSZo2bZr27dunCRMmaNu2bYqOjpZ04cnhMTExmjx5spYvX65du3Zp0KBB8vX1VXh4ePl9YABgK6OSycnJMSQZOTk5FT0VADeoy+URScbSpUsv+/4tW7YYkoxDhw4ZhmEYP/30kyHJ2Lp1qxnzzTffGHZ2dsbRo0cNwzCMt99+26hdu7aRl5dnxrz00ktG06ZNzdf9+vUzevToYTVWcHCw8fTTT5fJsQHAxdatW2dIKnErKYf4+/sbM2bMsGr7888/jQEDBhg1a9Y03NzcjCFDhhinTp2yivnxxx+NDh06GE5OTkb9+vWNN954o9i+P/30U+P22283HB0djZYtWxpff/21VX9hYaExfvx4w9vb23BycjK6dOliZGRklOp4yY8ArkVpcghP5y6FRmO+LtP9HXyjR5nuD0DZyMnJkZ2dnTw8PCRdeZmXRx555JLLvEydOlUnT55U7dq1lZKSYnV2pijm4svLb1RlnR+lknMkeRiwXefOnWUYhlVb0TqoJTl48GCxNk9PTyUmJl52nDZt2mjjxo2Xjenbt6/69u17yX47OztNnDhREydOvOx+ylp55S4ANxeKaAC4yNmzZ/XSSy9pwIAB5v115bXMS0lYwgUAAFxOefyCmV84WeOeaAD4fwoKCtSvXz8ZhqH58+dX9HQksYQLAABAZcOZaADQ/19AHzp0SGvXrrV6ymt5LfNSkrFjx1pdAm6xWCikAeAGw60oVRNnb0vvRvm3wploAFVeUQG9f/9+ffvtt6pTp45Vf3kt81ISlnABAACoXCiiAdz0SlrmJT09XYcPH1ZBQYH69Omjbdu2KSEhQefPn1dmZqYyMzOVn58vqfyWeQEAAEDlx+XcAG5627Zt0/3332++LipsBw8erAkTJmj58uWSpHbt2lm9b926dercubMkKSEhQdHR0erSpYvs7e3Vu3dvzZ4924x1d3fX6tWrFRUVpcDAQNWtW1exsbFWa0nfe++9SkxM1Lhx4/Tyyy+rSZMmWrZsmVq1anWdjhwAAJTkRrlsGJUTRTSAm15Jy7xc7HJ9RcprmRcAAABUblzODQAAAACAjTgTDQAAANzguDwZKD8U0QAAAAAqDX4hgMqOIhoAAADAFbHuMXAB90QDAAAAAGAjimgAAAAAAGzE5dwAcJPj3jIAAICyw5loAAAAAABsRBENAAAAAICNKKIBAAAAALARRTQAAAAAADaiiAYAAAAAwEYU0QAAAAAA2IgiGgAAAAAAG1FEAwAAAABgI4fSBJ8/f14TJkzQxx9/rMzMTPn6+uqJJ57QuHHjZGdnJ0kyDEOvvPKK3n33XWVnZ6t9+/aaP3++mjRpcl0OoEijMV+X6f4OvtGjTPcHAAAAALjxlepM9NSpUzV//nzNnTtXe/fu1dSpUxUXF6c5c+aYMXFxcZo9e7bi4+OVmpoqV1dXhYWF6ezZs2U+eQAAAAAAylOpzkRv2rRJvXr1Uo8eF87SNmrUSP/973+1ZcsWSRfOQs+cOVPjxo1Tr169JEkfffSRvL29tWzZMvXv37+Mpw+UD650AAAAACCV8kz0vffeqzVr1ujnn3+WJP3444/6/vvv1b17d0nSgQMHlJmZqdDQUPM97u7uCg4OVkpKShlOGwAAAACA8leqM9FjxoyRxWJRs2bNVK1aNZ0/f16vvfaaIiIiJEmZmZmSJG9vb6v3eXt7m31/l5eXp7y8PPO1xWIp1QEAAAAAAFBeSlVEf/rpp0pISFBiYqJatmyp9PR0xcTEyNfXV4MHD76qCUyZMkWvvvrqVb0XkG6eS63L+jgkLhsHrkZ55ZTyGOdGHKO8xrlZxrjUOACA66dURfSoUaM0ZswY897m1q1b69ChQ5oyZYoGDx4sHx8fSVJWVpbq1atnvi8rK0vt2rUrcZ9jx47VyJEjzdcWi0V+fn6lPQ6UEl8Uqq6b5ZcOAAAAQEUo1T3RZ86ckb299VuqVaumwsJCSVJAQIB8fHy0Zs0as99isSg1NVUhISEl7tPJyUlubm5WGwAAAAAAlVGpzkT37NlTr732mho2bKiWLVtqx44dmj59up588klJkp2dnWJiYjR58mQ1adJEAQEBGj9+vHx9fRUeHn495g8AAAAAQLkpVRE9Z84cjR8/Xs8995yOHz8uX19fPf3004qNjTVjRo8erdzcXA0bNkzZ2dnq0KGDkpKS5OzsXOaTBwAAAACgPJXqcu5atWpp5syZOnTokP766y/9+uuvmjx5shwdHc0YOzs7TZw4UZmZmTp79qy+/fZb3X777WU+cQAAAFzahg0b1LNnT/n6+srOzk7Lli0z+woKCvTSSy+pdevWcnV1la+vrwYNGqRjx45Z7ePEiROKiIiQm5ubPDw8FBkZqdOnT1vF7Ny5Ux07dpSzs7P8/PwUFxdXbC5LlixRs2bN5OzsrNatW2vlypVW/YZhKDY2VvXq1ZOLi4tCQ0O1f//+svswAKAMlaqIBgAAwI0hNzdXbdu21bx584r1nTlzRtu3b9f48eO1fft2ffHFF8rIyNDDDz9sFRcREaE9e/YoOTlZK1as0IYNGzRs2DCz32KxqGvXrvL391daWprefPNNTZgwQQsWLDBjNm3apAEDBigyMlI7duxQeHi4wsPDtXv3bjMmLi5Os2fPVnx8vFJTU+Xq6qqwsDCdPXv2OnwyAHBtSnU5NwAAAG4M3bt3V/fu3Uvsc3d3V3JyslXb3Llzdffdd+vw4cNq2LCh9u7dq6SkJG3dulVBQUGSLtza9+CDD+qtt96Sr6+vEhISlJ+frw8++ECOjo7mEqjTp083i+1Zs2apW7duGjVqlCRp0qRJSk5O1ty5cxUfHy/DMDRz5kyNGzdOvXr1kiR99NFH8vb21rJly8xVYQCgsuBMNAAAAJSTkyM7Ozt5eHhIklJSUuTh4WEW0JIUGhoqe3t7paammjGdOnWyurUvLCxMGRkZOnnypBkTGhpqNVZYWJhSUlIkSQcOHFBmZqZVjLu7u4KDg82YkuTl5clisVhtAFAeKKIBAACquLNnz+qll17SgAEDzOVGMzMz5eXlZRXn4OAgT09PZWZmmjHe3t5WMUWvrxRzcf/F7ysppiRTpkyRu7u7ufn5+ZXqmAHgalFEAwAAVGEFBQXq16+fDMPQ/PnzK3o6Nhs7dqxycnLM7ciRIxU9JQBVBPdEAwAAVFFFBfShQ4e0du1a8yy0JPn4+Oj48eNW8efOndOJEyfk4+NjxmRlZVnFFL2+UszF/UVt9erVs4pp167dJefu5OQkJyen0hwuAJQJzkQDAABUQUUF9P79+/Xtt9+qTp06Vv0hISHKzs5WWlqa2bZ27VoVFhYqODjYjNmwYYMKCgrMmOTkZDVt2lS1a9c2Y9asWWO17+TkZIWEhEiSAgIC5OPjYxVjsViUmppqxgBAZUIRDQAAcBM6ffq00tPTlZ6eLunCA7x27twp6UIB3adPH23btk0JCQk6f/68MjMzlZmZqfz8fElS8+bN1a1bNw0dOlRbtmzRDz/8oOjoaPXv31++vr6SpIEDB8rR0VGRkZHas2ePFi9erFmzZmnkyJHmPIYPH66kpCRNmzZN+/bt04QJE7Rt2zZFR0dLkuzs7BQTE6PJkydr+fLl2rVrlwYNGiRfX1+Fh4eX3wcGADbicu5KqNGYr8t0fwff6FGm+wMAAJXftm3bdP/995uvLy5sjx07puXLl0tSsUum161bp86dO0uSEhISFB0drS5dusje3l69e/fW7NmzzVh3d3etXr1aUVFRCgwMVN26dRUbG2u1lvS9996rxMREjRs3Ti+//LKaNGmiZcuWqVWrVmbM6NGjlZubq2HDhik7O1sdOnRQUlKSnJ2dy/IjAYAyQRENAABwE+rcubMMw7Bqs1gscnd3l7+/f7G+knh6eioxMfGyMW3atNHGjRsvG9O3b1/17dv3kv12dnaaOHGiJk6ceMU5AUBF43JuAAAAAABsRBENAAAAAICNKKIB3PQ2bNignj17ytfXV3Z2dlq2bJlVv2EYio2NVb169eTi4qLQ0FDt37/fKubEiROKiIiQm5ubPDw8FBkZqdOnT1vF7Ny5Ux07dpSzs7P8/PwUFxdXbC5LlixRs2bN5OzsrNatW2vlypVlfrwAAAC4fiiiAdz0cnNz1bZtW82bN6/E/ri4OM2ePVvx8fFKTU2Vq6urwsLCdPbsWTMmIiJCe/bsUXJyslasWKENGzZYPTjHYrGoa9eu8vf3V1pamt58801NmDBBCxYsMGM2bdqkAQMGKDIyUjt27FB4eLjCw8O1e/fu63fwAAAAKFM8WAzATa979+7q3r17iX2GYWjmzJkaN26cevXqJUn66KOP5O3trWXLlql///7au3evkpKStHXrVgUFBUmS5syZowcffFBvvfWWfH19lZCQoPz8fH3wwQdydHRUy5YtlZ6erunTp5vF9qxZs9StWzeNGjVKkjRp0iQlJydr7ty5io+PL4dPAgAAANeKM9EAqrQDBw4oMzNToaGhZpu7u7uCg4OVkpIiSUpJSZGHh4dZQEtSaGio7O3tlZqaasZ06tRJjo6OZkxYWJgyMjJ08uRJM+bicYpiisYpSV5eniwWi9UGAACAikMRDaBKy8zMlCR5e3tbtXt7e5t9mZmZ8vLysup3cHCQp6enVUxJ+7h4jEvFFPWXZMqUKXJ3dzc3Pz+/0h4iAAAAyhBFNABUYmPHjlVOTo65HTlypKKnBAAAUKVRRAOo0nx8fCRJWVlZVu1ZWVlmn4+Pj44fP27Vf+7cOZ04ccIqpqR9XDzGpWKK+kvi5OQkNzc3qw0AAAAVhyIaQJUWEBAgHx8frVmzxmyzWCxKTU1VSEiIJCkkJETZ2dlKS0szY9auXavCwkIFBwebMRs2bFBBQYEZk5ycrKZNm6p27dpmzMXjFMUUjQMAAIDKjyIawE3v9OnTSk9PV3p6uqQLDxNLT0/X4cOHZWdnp5iYGE2ePFnLly/Xrl27NGjQIPn6+io8PFyS1Lx5c3Xr1k1Dhw7Vli1b9MMPPyg6Olr9+/eXr6+vJGngwIFydHRUZGSk9uzZo8WLF2vWrFkaOXKkOY/hw4crKSlJ06ZN0759+zRhwgRt27ZN0dHR5f2RAAAA4CqxxBWAm962bdt0//33m6+LCtvBgwdr0aJFGj16tHJzczVs2DBlZ2erQ4cOSkpKkrOzs/mehIQERUdHq0uXLrK3t1fv3r01e/Zss9/d3V2rV69WVFSUAgMDVbduXcXGxlqtJX3vvfcqMTFR48aN08svv6wmTZpo2bJlatWqVTl8CgAAACgLFNEAbnqdO3eWYRiX7Lezs9PEiRM1ceLES8Z4enoqMTHxsuO0adNGGzduvGxM37591bdv38tPGAAAAJUWl3MDAAAAAGAjimgAAAAAAGxEEQ0AAAAAgI0oogEAAAAAsBFFNAAAAAAANqKIBgAAAADARhTRAAAAAADYiCIaAAAAAAAbUUQDAAAAAGAjimgAAAAAAGzkUNETAHDzaTTm6zLd38E3epTp/gAAAICrxZloAAAAAABsRBENAAAAAICNKKIBAAAAALARRTQAAAAAADaiiAYAAAAAwEYU0QAAAAAA2IgiGgAAAAAAG1FEAwAAAABgI4poAACAm9CGDRvUs2dP+fr6ys7OTsuWLbPqNwxDsbGxqlevnlxcXBQaGqr9+/dbxZw4cUIRERFyc3OTh4eHIiMjdfr0aauYnTt3qmPHjnJ2dpafn5/i4uKKzWXJkiVq1qyZnJ2d1bp1a61cubLUcwGAyoIiGgAA4CaUm5urtm3bat68eSX2x8XFafbs2YqPj1dqaqpcXV0VFhams2fPmjERERHas2ePkpOTtWLFCm3YsEHDhg0z+y0Wi7p27Sp/f3+lpaXpzTff1IQJE7RgwQIzZtOmTRowYIAiIyO1Y8cOhYeHKzw8XLt37y7VXACgsnCo6AkAAACg7HXv3l3du3cvsc8wDM2cOVPjxo1Tr169JEkfffSRvL29tWzZMvXv31979+5VUlKStm7dqqCgIEnSnDlz9OCDD+qtt96Sr6+vEhISlJ+frw8++ECOjo5q2bKl0tPTNX36dLPYnjVrlrp166ZRo0ZJkiZNmqTk5GTNnTtX8fHxNs0FACoTzkQDAABUMQcPHlRmZqZCQ0PNNnd3dwUHByslJUWSlJKSIg8PD7OAlqTQ0FDZ29srNTXVjOnUqZMcHR3NmLCwMGVkZOjkyZNmzMXjFMUUjXPgwIErzqUkeXl5slgsVhsAlAeKaAAAgCrm+PHjkiRvb2+rdm9vb2VmZkqSMjMz5eXlZdXv4OAgT09Pq5iS9lHUd7mYi/uvNJeSTJkyRe7u7ubm5+d3haMGgLJBEQ0AAIAbztixY5WTk2NuR44cqegpAagiKKIBAACqmKIzzFlZWVbtWVlZ8vHxkST5+PiYZ6yLnDt3TidOnLCKKWkfRX2Xi7m4/0pzKYmTk5Pc3NysNgAoDxTRAAAAVUyjRo3k4+OjNWvWmG0Wi0WpqakKCQmRJIWEhCg7O1tpaWlmzNq1a1VYWKjg4GAzZsOGDSooKDBjkpOT1bRpU9WuXduMuXicopiicQICAq44FwCoTCiiAQAAbkKnT59Wenq60tPTJV14gNfOnTslSXZ2doqJidHkyZO1fPly7dq1S4MGDZKvr6/Cw8MlSc2bN1e3bt00dOhQbdmyRT/88IOio6PVv39/+fr6SpIGDhwoR0dHRUZGas+ePVq8eLFmzZqlkSNHmvMYPny4kpKSNG3aNO3bt08TJkzQtm3bFB0dbfNcAKAyYYkrAACAm9C2bdt0//33m68vLmwlafTo0crNzdWwYcOUnZ2tDh06KCkpSc7OzmZMQkKCoqOj1aVLF9nb26t3796aPXu22e/u7q7Vq1crKipKgYGBqlu3rmJjY63Wkr733nuVmJiocePG6eWXX1aTJk20bNkytWrVqlRzAYDKgiIaAADgJtS5c2cZhmHVZrFY5O7uLunCGeCJEydq4sSJl9yHp6enEhMTLztOmzZttHHjxsvG9O3bV3379r1kvy1zAYDKgsu5AQAAAACwEUU0AAAAAAA2oogGAAAAAMBGpS6ijx49qscff1x16tSRi4uLWrdurW3btpn9hmEoNjZW9erVk4uLi0JDQ7V///4ynTQAAAAAABWhVEX0yZMn1b59e1WvXl3ffPONfvrpJ02bNs1cB1CS4uLiNHv2bMXHxys1NVWurq4KCwvT2bNny3zyAAAAAACUp1I9nXvq1Kny8/PTwoULzbaAgADzz4ZhaObMmRo3bpx69eolSfroo4/k7e2tZcuWqX///mU0bQAAAAAAyl+pzkQvX75cQUFB6tu3r7y8vHTHHXfo3XffNfsPHDigzMxMhYaGmm3u7u4KDg5WSkpKifvMy8uTxWKx2gAAAAAAqIxKVUT/9ttvmj9/vpo0aaJVq1bp2Wef1QsvvKAPP/xQkpSZmSlJ8vb2tnqft7e32fd3U6ZMkbu7u7n5+fldzXEAAAAAAHDdlaqILiws1J133qnXX39dd9xxh4YNG6ahQ4cqPj7+qicwduxY5eTkmNuRI0euel8AcDXOnz+v8ePHKyAgQC4uLmrcuLEmTZokwzDMGFsemnjixAlFRETIzc1NHh4eioyM1OnTp61idu7cqY4dO8rZ2Vl+fn6Ki4srl2MEAABA2ShVEV2vXj21aNHCqq158+Y6fPiwJMnHx0eSlJWVZRWTlZVl9v2dk5OT3NzcrDYAKE9Tp07V/PnzNXfuXO3du1dTp05VXFyc5syZY8bY8tDEiIgI7dmzR8nJyVqxYoU2bNigYcOGmf0Wi0Vdu3aVv7+/0tLS9Oabb2rChAlasGBBuR4vAAAArl6piuj27dsrIyPDqu3nn3+Wv7+/pAsPGfPx8dGaNWvMfovFotTUVIWEhJTBdAGg7G3atEm9evVSjx491KhRI/Xp00ddu3bVli1bJBV/aGKbNm300Ucf6dixY1q2bJkkae/evUpKStJ7772n4OBgdejQQXPmzNEnn3yiY8eOSZISEhKUn5+vDz74QC1btlT//v31wgsvaPr06RV16AAAACilUhXRI0aM0ObNm/X666/rl19+UWJiohYsWKCoqChJkp2dnWJiYjR58mQtX75cu3bt0qBBg+Tr66vw8PDrMX8AuGb33nuv1qxZo59//lmS9OOPP+r7779X9+7dJdn20MSUlBR5eHgoKCjIjAkNDZW9vb1SU1PNmE6dOsnR0dGMCQsLU0ZGhk6ePFni3Hj4IgAAQOVSqiWu7rrrLi1dulRjx47VxIkTFRAQoJkzZyoiIsKMGT16tHJzczVs2DBlZ2erQ4cOSkpKkrOzc5lPHgDKwpgxY2SxWNSsWTNVq1ZN58+f12uvvWbmNlsempiZmSkvLy+rfgcHB3l6elrFXLws4MX7zMzMVO3atYvNbcqUKXr11VfL4CgBAABQFkpVREvSQw89pIceeuiS/XZ2dpo4caImTpx4TRMDgPLy6aefKiEhQYmJiWrZsqXS09MVExMjX19fDR48uELnNnbsWI0cOdJ8bbFYWMUAAACgApW6iAaAm82oUaM0ZswY9e/fX5LUunVrHTp0SFOmTNHgwYOtHppYr149831ZWVlq166dpAsPVjx+/LjVfs+dO6cTJ06Y7/fx8SnxwYtFfSVxcnKSk5PTtR8kAAAAykSp7okGgJvRmTNnZG9vnQ6rVaumwsJCSbY9NDEkJETZ2dlKS0szY9auXavCwkIFBwebMRs2bFBBQYEZk5ycrKZNm5Z4KTcAAAAqH4poAFVez5499dprr+nrr7/WwYMHtXTpUk2fPl2PPPKIJNsemti8eXN169ZNQ4cO1ZYtW/TDDz8oOjpa/fv3l6+vryRp4MCBcnR0VGRkpPbs2aPFixdr1qxZVpdrAwAAoHLjcm4AVd6cOXM0fvx4Pffcczp+/Lh8fX319NNPKzY21oyx5aGJCQkJio6OVpcuXWRvb6/evXtr9uzZZr+7u7tWr16tqKgoBQYGqm7duoqNjbVaSxoAAACVG0U0gCqvVq1amjlzpmbOnHnJGFsemujp6anExMTLjtWmTRtt3LjxaqcKAACACsbl3AAAAAAA2IgiGgAAAAAAG1FEAwAAAABgI4poAAAAAABsRBENAAAAAICNKKIBAAAAALARRTQAAAAAADaiiAYAAAAAwEYU0QAAAAAA2IgiGgAAAAAAG1FEAwAAAABgI4poAAAAAABsRBENAABQBZ0/f17jx49XQECAXFxc1LhxY02aNEmGYZgxhmEoNjZW9erVk4uLi0JDQ7V//36r/Zw4cUIRERFyc3OTh4eHIiMjdfr0aauYnTt3qmPHjnJ2dpafn5/i4uKKzWfJkiVq1qyZnJ2d1bp1a61cufL6HDgAXCOKaAAAgCpo6tSpmj9/vubOnau9e/dq6tSpiouL05w5c8yYuLg4zZ49W/Hx8UpNTZWrq6vCwsJ09uxZMyYiIkJ79uxRcnKyVqxYoQ0bNmjYsGFmv8ViUdeuXeXv76+0tDS9+eabmjBhghYsWGDGbNq0SQMGDFBkZKR27Nih8PBwhYeHa/fu3eXzYQBAKVBEAwAAVEGbNm1Sr1691KNHDzVq1Eh9+vRR165dtWXLFkkXzkLPnDlT48aNU69evdSmTRt99NFHOnbsmJYtWyZJ2rt3r5KSkvTee+8pODhYHTp00Jw5c/TJJ5/o2LFjkqSEhATl5+frgw8+UMuWLdW/f3+98MILmj59ujmXWbNmqVu3bho1apSaN2+uSZMm6c4779TcuXPL/XMBgCuhiAYAAKiC7r33Xq1Zs0Y///yzJOnHH3/U999/r+7du0uSDhw4oMzMTIWGhprvcXd3V3BwsFJSUiRJKSkp8vDwUFBQkBkTGhoqe3t7paammjGdOnWSo6OjGRMWFqaMjAydPHnSjLl4nKKYonEAoDJxqOgJAAAAoPyNGTNGFotFzZo1U7Vq1XT+/Hm99tprioiIkCRlZmZKkry9va3e5+3tbfZlZmbKy8vLqt/BwUGenp5WMQEBAcX2UdRXu3ZtZWZmXnackuTl5SkvL898bbFYbD52ALgWnIkGAACogj799FMlJCQoMTFR27dv14cffqi33npLH374YUVPzSZTpkyRu7u7ufn5+VX0lABUERTRAAAAVdCoUaM0ZswY9e/fX61bt9Y///lPjRgxQlOmTJEk+fj4SJKysrKs3peVlWX2+fj46Pjx41b9586d04kTJ6xiStrHxWNcKqaovyRjx45VTk6OuR05cqRUxw8AV4siGgAAoAo6c+aM7O2tvwpWq1ZNhYWFkqSAgAD5+PhozZo1Zr/FYlFqaqpCQkIkSSEhIcrOzlZaWpoZs3btWhUWFio4ONiM2bBhgwoKCsyY5ORkNW3aVLVr1zZjLh6nKKZonJI4OTnJzc3NagOA8kARDQAAUAX17NlTr732mr7++msdPHhQS5cu1fTp0/XII49Ikuzs7BQTE6PJkydr+fLl2rVrlwYNGiRfX1+Fh4dLkpo3b65u3bpp6NCh2rJli3744QdFR0erf//+8vX1lSQNHDhQjo6OioyM1J49e7R48WLNmjVLI0eONOcyfPhwJSUladq0adq3b58mTJigbdu2KTo6utw/FwC4Eh4sBgAAUAXNmTNH48eP13PPPafjx4/L19dXTz/9tGJjY82Y0aNHKzc3V8OGDVN2drY6dOigpKQkOTs7mzEJCQmKjo5Wly5dZG9vr969e2v27Nlmv7u7u1avXq2oqCgFBgaqbt26io2NtVpL+t5771ViYqLGjRunl19+WU2aNNGyZcvUqlWr8vkwAKAUKKIBAACqoFq1amnmzJmaOXPmJWPs7Ow0ceJETZw48ZIxnp6eSkxMvOxYbdq00caNGy8b07dvX/Xt2/eyMQBQGXA5NwAAAAAANqKIBgAAAADARhTRAAAAAADYiCIaAAAAAAAbUUQDAAAAAGAjimgAAAAAAGxEEQ0AAAAAgI0oogEAAAAAsBFFNAAAAAAANqKIBgAAAADARhTRAAAAAADYiCIaAAAAAAAbUUQDAAAAAGAjimgAAAAAAGxEEQ0Ako4eParHH39cderUkYuLi1q3bq1t27aZ/YZhKDY2VvXq1ZOLi4tCQ0O1f/9+q32cOHFCERERcnNzk4eHhyIjI3X69GmrmJ07d6pjx45ydnaWn5+f4uLiyuX4AAAAUDYoogFUeSdPnlT79u1VvXp1ffPNN/rpp580bdo01a5d24yJi4vT7NmzFR8fr9TUVLm6uiosLExnz541YyIiIrRnzx4lJydrxYoV2rBhg4YNG2b2WywWde3aVf7+/kpLS9Obb76pCRMmaMGCBeV6vAAAALh6DhU9AQCoaFOnTpWfn58WLlxotgUEBJh/NgxDM2fO1Lhx49SrVy9J0kcffSRvb28tW7ZM/fv31969e5WUlKStW7cqKChIkjRnzhw9+OCDeuutt+Tr66uEhATl5+frgw8+kKOjo1q2bKn09HRNnz7dqtgGAABA5cWZaABV3vLlyxUUFKS+ffvKy8tLd9xxh959912z/8CBA8rMzFRoaKjZ5u7uruDgYKWkpEiSUlJS5OHhYRbQkhQaGip7e3ulpqaaMZ06dZKjo6MZExYWpoyMDJ08efJ6HyYAAADKAEU0gCrvt99+0/z589WkSROtWrVKzz77rF544QV9+OGHkqTMzExJkre3t9X7vL29zb7MzEx5eXlZ9Ts4OMjT09MqpqR9XDzG3+Xl5clisVhtAAAAqDhczg2gyissLFRQUJBef/11SdIdd9yh3bt3Kz4+XoMHD67QuU2ZMkWvvvpqhc4BAAAA/z/ORAOo8urVq6cWLVpYtTVv3lyHDx+WJPn4+EiSsrKyrGKysrLMPh8fHx0/ftyq/9y5czpx4oRVTEn7uHiMvxs7dqxycnLM7ciRI1dziAAAACgjFNEAqrz27dsrIyPDqu3nn3+Wv7+/pAsPGfPx8dGaNWvMfovFotTUVIWEhEiSQkJClJ2drbS0NDNm7dq1KiwsVHBwsBmzYcMGFRQUmDHJyclq2rSp1ZPAL+bk5CQ3NzerDQAAABWHIhpAlTdixAht3rxZr7/+un755RclJiZqwYIFioqKkiTZ2dkpJiZGkydP1vLly7Vr1y4NGjRIvr6+Cg8Pl3ThzHW3bt00dOhQbdmyRT/88IOio6PVv39/+fr6SpIGDhwoR0dHRUZGas+ePVq8eLFmzZqlkSNHVtShAwAAoJS4JxpAlXfXXXdp6dKlGjt2rCZOnKiAgADNnDlTERERZszo0aOVm5urYcOGKTs7Wx06dFBSUpKcnZ3NmISEBEVHR6tLly6yt7dX7969NXv2bLPf3d1dq1evVlRUlAIDA1W3bl3FxsayvBUAAMANhCIaACQ99NBDeuihhy7Zb2dnp4kTJ2rixImXjPH09FRiYuJlx2nTpo02btx41fMEAABAxeJybgAAAAAAbEQRDQAAAACAja6piH7jjTfMB+4UOXv2rKKiolSnTh3VrFlTvXv3LrakCwAAAAAAN6KrLqK3bt2qd955R23atLFqHzFihL766istWbJE69ev17Fjx/Too49e80QBAAAAAKhoV1VEnz59WhEREXr33Xet1jbNycnR+++/r+nTp+uBBx5QYGCgFi5cqE2bNmnz5s1lNmkAAAAAACrCVRXRUVFR6tGjh0JDQ63a09LSVFBQYNXerFkzNWzYUCkpKSXuKy8vTxaLxWoDAAAAAKAyKvUSV5988om2b9+urVu3FuvLzMyUo6OjPDw8rNq9vb2VmZlZ4v6mTJmiV199tbTTAAAAAACg3JXqTPSRI0c0fPhwJSQkyNnZuUwmMHbsWOXk5JjbkSNHymS/AAAAuLyjR4/q8ccfV506deTi4qLWrVtr27ZtZr9hGIqNjVW9evXk4uKi0NBQ7d+/32ofJ06cUEREhNzc3OTh4aHIyEidPn3aKmbnzp3q2LGjnJ2d5efnp7i4uGJzWbJkiZo1ayZnZ2e1bt1aK1euvD4HDQDXqFRFdFpamo4fP64777xTDg4OcnBw0Pr16zV79mw5ODjI29tb+fn5ys7OtnpfVlaWfHx8Stynk5OT3NzcrDYAAABcXydPnlT79u1VvXp1ffPNN/rpp580bdo0q+fdxMXFafbs2YqPj1dqaqpcXV0VFhams2fPmjERERHas2ePkpOTtWLFCm3YsEHDhg0z+y0Wi7p27Sp/f3+lpaXpzTff1IQJE7RgwQIzZtOmTRowYIAiIyO1Y8cOhYeHKzw8XLt37y6fDwMASqFUl3N36dJFu3btsmobMmSImjVrppdeekl+fn6qXr261qxZo969e0uSMjIydPjwYYWEhJTdrAEAAHBNpk6dKj8/Py1cuNBsCwgIMP9sGIZmzpypcePGqVevXpKkjz76SN7e3lq2bJn69++vvXv3KikpSVu3blVQUJAkac6cOXrwwQf11ltvydfXVwkJCcrPz9cHH3wgR0dHtWzZUunp6Zo+fbpZbM+aNUvdunXTqFGjJEmTJk1ScnKy5s6dq/j4+PL6SADAJqU6E12rVi21atXKanN1dVWdOnXUqlUrubu7KzIyUiNHjtS6deuUlpamIUOGKCQkRPfcc8/1OgYAAACU0vLlyxUUFKS+ffvKy8tLd9xxh959912z/8CBA8rMzLR6YKy7u7uCg4PNB8ampKTIw8PDLKAlKTQ0VPb29kpNTTVjOnXqJEdHRzMmLCxMGRkZOnnypBnz9wfWhoWFXfLBtBIPpwVQca56nehLmTFjhh566CH17t1bnTp1ko+Pj7744ouyHgYAAADX4LffftP8+fPVpEkTrVq1Ss8++6xeeOEFffjhh5JkPhTW29vb6n0XPzA2MzNTXl5eVv0ODg7y9PS0iilpHxePcamYSz2YVrrwcFp3d3dz8/PzK9XxA8DVKvXTuf/uu+++s3rt7OysefPmad68ede6awAAAFwnhYWFCgoK0uuvvy5JuuOOO7R7927Fx8dr8ODBFTy7Kxs7dqxGjhxpvrZYLBTSAMpFmZ+JBgAAQOVXr149tWjRwqqtefPmOnz4sCSZD4XNysqyirn4gbE+Pj46fvy4Vf+5c+d04sQJq5iS9nHxGJeKudSDaSUeTgug4lBEAwAAVEHt27dXRkaGVdvPP/8sf39/SRceMubj46M1a9aY/RaLRampqeYDY0NCQpSdna20tDQzZu3atSosLFRwcLAZs2HDBhUUFJgxycnJatq0qfkk8JCQEKtximJ4MC2AyogiGgAAoAoaMWKENm/erNdff12//PKLEhMTtWDBAkVFRUmS7OzsFBMTo8mTJ2v58uXatWuXBg0aJF9fX4WHh0u6cOa6W7duGjp0qLZs2aIffvhB0dHR6t+/v3x9fSVJAwcOlKOjoyIjI7Vnzx4tXrxYs2bNsroUe/jw4UpKStK0adO0b98+TZgwQdu2bVN0dHS5fy4AcCXXfE80AAAAbjx33XWXli5dqrFjx2rixIkKCAjQzJkzFRERYcaMHj1aubm5GjZsmLKzs9WhQwclJSXJ2dnZjElISFB0dLS6dOkie3t79e7dW7Nnzzb73d3dtXr1akVFRSkwMFB169ZVbGys1VrS9957rxITEzVu3Di9/PLLatKkiZYtW6ZWrVqVz4cBAKVAEQ0AAFBFPfTQQ3rooYcu2W9nZ6eJEydq4sSJl4zx9PRUYmLiZcdp06aNNm7ceNmYvn37qm/fvpefMABUAlzODQAAAACAjSiiAQAAAACwEUU0AAAAAAA2oogGAAAAAMBGFNEAAAAAANiIIhoAAAAAABtRRAMAAAAAYCOKaAAAAAAAbEQRDQAAAACAjSiiAQAAAACwEUU0AAAAAAA2oogGAAAAAMBGFNEAAAAAANiIIhoAAAAAABtRRAMAAAAAYCOKaAAAAAAAbEQRDQAAAACAjSiiAQAAAACwEUU0AAAAAAA2oogGAAAAAMBGFNEA8DdvvPGG7OzsFBMTY7adPXtWUVFRqlOnjmrWrKnevXsrKyvL6n2HDx9Wjx49VKNGDXl5eWnUqFE6d+6cVcx3332nO++8U05OTrrtttu0aNGicjgiAAAAlBWKaAC4yNatW/XOO++oTZs2Vu0jRozQV199pSVLlmj9+vU6duyYHn30UbP//Pnz6tGjh/Lz87Vp0yZ9+OGHWrRokWJjY82YAwcOqEePHrr//vuVnp6umJgYPfXUU1q1alW5HR8AAACuDUU0APw/p0+fVkREhN59913Vrl3bbM/JydH777+v6dOn64EHHlBgYKAWLlyoTZs2afPmzZKk1atX66efftLHH3+sdu3aqXv37po0aZLmzZun/Px8SVJ8fLwCAgI0bdo0NW/eXNHR0erTp49mzJhRIccLAACA0qOIBoD/JyoqSj169FBoaKhVe1pamgoKCqzamzVrpoYNGyolJUWSlJKSotatW8vb29uMCQsLk8Vi0Z49e8yYv+87LCzM3EdJ8vLyZLFYrDYAAABUHIeKngAAVAaffPKJtm/frq1btxbry8zMlKOjozw8PKzavb29lZmZacZcXEAX9Rf1XS7GYrHor7/+kouLS7Gxp0yZoldfffWqjwsAAABlizPRAKq8I0eOaPjw4UpISJCzs3NFT8fK2LFjlZOTY25Hjhyp6CkBAABUaRTRAKq8tLQ0HT9+XHfeeaccHBzk4OCg9evXa/bs2XJwcJC3t7fy8/OVnZ1t9b6srCz5+PhIknx8fIo9rbvo9ZVi3NzcSjwLLUlOTk5yc3Oz2gAAAFBxKKIBVHldunTRrl27lJ6ebm5BQUGKiIgw/1y9enWtWbPGfE9GRoYOHz6skJAQSVJISIh27dql48ePmzHJyclyc3NTixYtzJiL91EUU7QPAAAAVH7cEw2gyqtVq5ZatWpl1ebq6qo6deqY7ZGRkRo5cqQ8PT3l5uam559/XiEhIbrnnnskSV27dlWLFi30z3/+U3FxccrMzNS4ceMUFRUlJycnSdIzzzyjuXPnavTo0XryySe1du1affrpp/r666/L94ABAABw1SiiAcAGM2bMkL29vXr37q28vDyFhYXp7bffNvurVaumFStW6Nlnn1VISIhcXV01ePBgTZw40YwJCAjQ119/rREjRmjWrFlq0KCB3nvvPYWFhVXEIQEAAOAqUEQDQAm+++47q9fOzs6aN2+e5s2bd8n3+Pv7a+XKlZfdb+fOnbVjx46ymCIAAAAqAPdEAwAAAABgI4poAAAA6I033pCdnZ1iYmLMtrNnzyoqKkp16tRRzZo11bt372KrDBw+fFg9evRQjRo15OXlpVGjRuncuXNWMd99953uvPNOOTk56bbbbtOiRYuKjT9v3jw1atRIzs7OCg4O1pYtW67HYQLANaOIBgAAqOK2bt2qd955R23atLFqHzFihL766istWbJE69ev17Fjx/To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",
"text/plain": [
""
]
},
"metadata": {},
"output_type": "display_data"
}
],
"source": [
"run_scenario(fm, \"scenario-3\", ws3.opt.SENSE_MAXIMIZE, acodes, coeff_funcs, cflw_e, cgen_data)\n"
]
},
{
"cell_type": "markdown",
"metadata": {},
"source": [
"Ta da! That is starting to look more like a sustainable harvesting solution. The combination of ending inventory constraint and even-flow harest volume constraint is effectively stabilizing both log production and growing stock inventory. There is a bit of a spike in the harvested area in the final time step, though, which we can try to mitigate by adding a flow constraint on harvest area (we will leave all the previously defined constraints in the model, including the harvest volume flow constraint we added in the previous step).\n"
]
},
{
"cell_type": "markdown",
"metadata": {},
"source": [
"### Adding harvest area even-flow constraints\n",
"\n",
"We can use the same `cmp_c_caa` coefficient function that we used above to define the harvest volume flow constraint, but just use a different value for the `expr` arg (`1.` instead of `totvol * 0.85`) in the call to `functools.partial`. We will use the same espilon value of `0.05` that we used above to define the harvest volume flow constraint."
]
},
{
"cell_type": "code",
"execution_count": 30,
"metadata": {},
"outputs": [
{
"data": {
"image/png": "iVBORw0KGgoAAAANSUhEUgAAA9EAAAF2CAYAAABpthsMAAAAOnRFWHRTb2Z0d2FyZQBNYXRwbG90bGliIHZlcnNpb24zLjEwLjUsIGh0dHBzOi8vbWF0cGxvdGxpYi5vcmcvWftoOwAAAAlwSFlzAAAPYQAAD2EBqD+naQAAbYZJREFUeJzt3X18zvX////7ZnZibDPaZswsyflJbbWWk8jeRpKVk7DepEUnWxlF9GYJJSvnZOkEvdtKCkkai0KZYSwnIRXx5rOpsIPJNvb6/eG718/RhmPMNtvterm8LhfH8/k4Xs/n6zAPx2Ovk6edYRiGAAAAAADAVdmX9QQAAAAAALhZUEQDAAAAAGAjimgAAAAAAGxEEQ0AAAAAgI0oogEAAAAAsBFFNAAAAAAANqKIBgAAAADARhTRAAAAAADYiCIaAAAAAAAbUUTjprJw4ULZ2dnp0KFDZT2VEnfkyBE5Ozvrhx9+MNs6duyoFi1alNgYf/31l1xdXbVq1aoS2yeAklNWOe67776TnZ2dvvvuu1IdtyTFxcWpSZMmys/PL/Wxf/rpJzk4OGj37t2lPjZQHlWEnFJSCj6Lzz777Jr3sWXLFjk6Our3338vwZnZJi8vT35+fnr77bdLfezyjCK6FBV8Odq2bVuR/SVdMJWVs2fPavz48eUmcY4aNUp2dnZ69NFHy3oqVzRhwgQFBwerbdu2N2yMWrVq6cknn9S4ceNu2BiovMhxpaNVq1aqX7++DMO4bEzbtm3l7e2t8+fPl+LMyo7FYtGUKVP00ksvyd6+5L7avPvuu7rvvvvk7e0tJycnBQQEaPDgwYV+ydGsWTN1795dsbGxJTY2cDkHDx5UdHS0br/9dlWrVk3VqlVTs2bNFBUVpZ07d5b19MqFXbt2qXfv3vL395ezs7Pq1q2rf/3rX5o9e7ZV3Ouvv67ly5eXzSSL4T//+Y/69+8vf3//Etvnhg0b9NBDD8nPz0/Ozs7y8fFR165drU7mSFLVqlU1YsQIvfbaazp37lyJjX+zo4hGiTt79qxeffXVclFEG4ahjz/+WA0aNNCXX36p06dPl/WUivTHH39o0aJFevrpp2/4WE8//bS2b9+udevW3fCxgIqorHNcRESEjhw5oo0bNxbZf+jQIaWkpOjRRx+Vg4NDKc+ubHzwwQc6f/68+vfvX6L73bFjhwICAjRq1CjNmzdPjz32mL7++mvdddddOnbsmFXs008/rWXLlunXX38t0TkAl1q5cqVatGih//73vwoNDdX06dM1c+ZMdevWTatWrVKbNm3K5GzlP3Xo0EF///23OnToUOpjb9q0SUFBQfrxxx81ZMgQzZkzR08++aTs7e01c+ZMq9iboYhOT0/XN998U+LfEX/++WfZ29vr6aef1ty5c/Xiiy8qIyNDHTp0UFJSklXs4MGD9eeffyoxMbFE53Azqxz/u1ZChmHo3LlzcnFxKeuplKnvvvtO//vf/7Ru3TqFhYVp6dKlGjRo0FXfd+7cOTk6OpboGY0r+eijj+Tg4KAePXrc8LGaNm2qFi1aaOHChbr//vtv+HjAjVCZc9yAAQM0ZswYJSYmFvkF9eOPP5ZhGIqIiCiD2ZWNBQsW6KGHHpKzs3OJ7reoyxfDw8MVFBSkDz/8UKNHjzbbQ0NDVbNmTS1atEgTJkwo0XkAkvTrr7+qX79+8vf319q1a1WnTh2r/ilTpujtt9++6neX7Oxsubq63sipyt7evsT/Pdrqtddek7u7u7Zu3SoPDw+rvuPHj5fJnK7HggULVL9+fd1zzz0lut8nn3xSTz75pFXbs88+q1tvvVUzZsxQ165dzXYPDw916dJFCxcu1BNPPFGi87hZcSa6nFuwYIHuv/9+eXl5ycnJSc2aNdO8efMKxTVo0EAPPvigVq9eraCgILm4uOidd95RixYt1KlTp0Lx+fn5qlu3rnr37m3VNmPGDDVv3lzOzs7y9vbWU089pZMnT1q9d9u2bQoLC1Pt2rXl4uKigIAA8x/UoUOHdMstt0iSXn31VdnZ2cnOzk7jx483379v3z717t1bnp6ecnZ2VlBQkFasWFFojnv27NH9998vFxcX1atXT5MmTSr2vW4JCQlq1qyZOnXqpNDQUCUkJBSKKbhX5ZNPPtHYsWNVt25dVatWTRaLRZKUmpqqrl27yt3dXdWqVdN9991X6FKX33//Xc8++6waN24sFxcX1apVS3369LH5vsbly5crODhY1atXL7L/p59+UqdOnVStWjXVrVtXcXFxVv25ubmKjY1VYGCg3N3d5erqqvbt2+vbb78tcn//+te/9OWXX17xclCgNJDjip/j/Pz81KFDB3322WfKy8sr1J+YmKiGDRsqODhY0sWzqd26dZObm5uqV6+uzp07a/PmzVcdp0GDBnr88ccLtXfs2FEdO3Y0Xxfk0E8//VSvvvqq6tatqxo1aqh3797KyspSTk6OYmJi5OXlperVq2vw4MHKyckptN+PPvpIgYGBcnFxkaenp/r166cjR45cdZ4HDx7Uzp07FRoaatV+6NAh2dnZ6a233tLcuXN16623qlq1aurSpYuOHDkiwzA0ceJE1atXTy4uLurZs6dOnDhh0+ciSadOnbJqr1q1qjp27KgvvvjiqvsArkVcXJyys7O1YMGCQgW0JDk4OOj555+Xn5+f2fb444+revXq+vXXX/XAAw+oRo0a5i/YsrOz9cILL8jPz09OTk5q3Lix3nrrLavvBo888ojuvPNOq3F69OghOzs7q7yWmpoqOzs7ff3115KKvie64Jaeq32nkS5+r3rooYfk6uoqLy8vDR8+XKtXr7bpPutff/1VzZs3L1RAS5KXl5f5Zzs7O2VnZ2vRokVmLr8059maO0+dOqXhw4erQYMGcnJyUr169TRw4ED9+eefl51jTk6OHnzwQbm7u2vTpk1XPJ7ly5fr/vvvl52dnVV7wf+L3333nfn/YsuWLc3PZ+nSpWrZsqWcnZ0VGBioHTt2XHEcSapWrZpuueWWQvlNuvjd8fvvv7cpT1YGnIkuA1lZWUX+wyrqy9C8efPUvHlzPfTQQ3JwcNCXX36pZ599Vvn5+YqKirKK3b9/v/r376+nnnpKQ4YMUePGjfXoo49q/PjxysjIkI+Pjxn7/fff69ixY+rXr5/Z9tRTT2nhwoUaPHiwnn/+eR08eFBz5szRjh079MMPP6hq1ao6fvy4unTpoltuuUWjR4+Wh4eHDh06pKVLl0qSbrnlFs2bN0/PPPOMHn74YT3yyCOSLt7DJ1380ti2bVvVrVtXo0ePlqurqz799FOFh4fr888/18MPPyxJysjIUKdOnXT+/Hkzbv78+cU665STk6PPP/9cL7zwgiSpf//+Gjx4cKHPosDEiRPl6OioF198UTk5OXJ0dNS6devUrVs3BQYG6pVXXpG9vb35pX/jxo26++67JUlbt27Vpk2b1K9fP9WrV0+HDh3SvHnz1LFjR/3000+qVq3aZeeZl5enrVu36plnnimy/+TJk+rataseeeQR9e3bV5999pleeukltWzZUt26dZN08X7A9957T/3799eQIUN0+vRpvf/++woLC9OWLVvUpk0bq30GBgZq+vTp2rNnT4W4RxXlCznuxue4iIgIDR06VKtXr9aDDz5otu/atUu7d+82783ds2eP2rdvLzc3N40aNUpVq1bVO++8o44dO2r9+vVmoV0SJk+eLBcXF40ePVq//PKLZs+erapVq8re3l4nT57U+PHjtXnzZi1cuFABAQFW9w+/9tprGjdunPr27asnn3xSf/zxh2bPnq0OHTpox44dRX4ZLlDwBfSfX/QLJCQkKDc3V88995xOnDihuLg49e3bV/fff7++++47vfTSS+Z8X3zxRX3wwQeF9vHXX3/pwoULOnz4sHmWuXPnzoXiAgMD9cUXX8hiscjNza04Hx9wVStXrtRtt91W7H+358+fV1hYmNq1a6e33npL1apVk2EYeuihh/Ttt98qMjJSbdq00erVqzVy5EgdPXpU06dPlyS1b9/e6mfaMAz98MMPsre318aNG/XQQw9JkjZu3Ch7e/urPtfFlu802dnZuv/++/V///d/GjZsmHx8fJSYmHjZEwP/5O/vr5SUFO3evfuK33H++9//6sknn9Tdd9+toUOHSpIaNmwoyfbceebMGbVv31579+7VE088oTvvvFN//vmnVqxYof/973+qXbt2oXH//vtv9ezZU9u2bdM333yju+6667JzPHr0qA4fPnzZ/PbLL79owIABeuqpp/TYY4/prbfeUo8ePRQfH6+XX35Zzz77rKSL+blv377av39/oSsVLBaLcnNz9eeff+rDDz/U7t279fLLLxcaKzAwUIZhaNOmTVb/71RaBkrNggULDElX3Jo3b271nrNnzxbaT1hYmHHrrbdatfn7+xuSjKSkJKv2/fv3G5KM2bNnW7U/++yzRvXq1c39b9y40ZBkJCQkWMUlJSVZtS9btsyQZGzduvWyx/nHH38YkoxXXnmlUF/nzp2Nli1bGufOnTPb8vPzjXvvvddo1KiR2RYTE2NIMlJTU82248ePG+7u7oYk4+DBg5cdv8Bnn31mSDIOHDhgGIZhWCwWw9nZ2Zg+fbpV3LfffmtIMm699Varzzs/P99o1KiRERYWZuTn55vtZ8+eNQICAox//etfVm3/lJKSYkgyPvzwwyvO85dffiny78gwDOO+++4rtI+cnBzDx8fH6NWrl9l2/vx5Iycnx+q9J0+eNLy9vY0nnnii0H43bdpkSDIWL158xbkBxUGOK70cd+LECcPJycno37+/Vfvo0aMNScb+/fsNwzCM8PBww9HR0fj111/NmGPHjhk1atQwOnToYLYV5MFvv/3WbPP39zcGDRpUaOz77rvPuO+++wq9t0WLFkZubq7Z3r9/f8POzs7o1q2b1ftDQkIMf39/8/WhQ4eMKlWqGK+99ppV3K5duwwHB4dC7f80duxYQ5Jx+vRpq/aDBw8akoxbbrnFOHXqlNk+ZswYQ5LRunVrIy8vz2q+jo6OVn93BZycnMyf4Vq1ahmzZs0qci6JiYmF/l6BkpCVlWVIMsLDwwv1nTx50vjjjz/M7dK8OmjQIEOSMXr0aKv3LF++3JBkTJo0yaq9d+/ehp2dnfHLL78YhmEYW7duNSQZq1atMgzDMHbu3GlIMvr06WMEBweb73vooYeMO+64w3xdVE6x9TvN1KlTDUnG8uXLzba///7baNKkSaF9FmXNmjVGlSpVjCpVqhghISHGqFGjjNWrV1vlpwKurq5F5jlbc2dsbKwhyVi6dGmhfRR8dyz4LJYsWWKcPn3auO+++4zatWsbO3bsuOJxGIZhfPPNN4Yk48svvyzUV/D/4qZNm8y21atXG5IMFxcX4/fffzfb33nnnct+dmFhYWZ+c3R0NJ566inj77//LhR37NgxQ5IxZcqUq867MuBy7jIwd+5cJScnF9oKzmRc6tKzEgVnd+677z799ttvysrKsooNCAhQWFiYVdvtt9+uNm3aaPHixWbbhQsX9Nlnn6lHjx7m/pcsWSJ3d3f961//0p9//mlugYGBql69uvnbv4KzAStXrizyrNKVnDhxQuvWrVPfvn11+vRpc4y//vpLYWFhOnDggI4ePSpJWrVqle655x7zTK908QxQce7xS0hIUFBQkG677TZJUo0aNdS9e/ciL+mWpEGDBll93unp6Tpw4IAGDBigv/76y5xvdna2OnfurA0bNpiXXl76vry8PP3111+67bbb5OHhoe3bt19xnn/99ZckqWbNmkX2V69eXY899pj52tHRUXfffbd+++03s61KlSpydHSUdPGS1RMnTuj8+fMKCgoqcvyCsa50qRFwrchxNz7H1axZUw888IBWrFih7OxsSRfvE//kk08UFBSk22+/XRcuXNCaNWsUHh6uW2+91XxvnTp1NGDAAH3//ffmbSslYeDAgapatar5Ojg4WIZhFLp/Ljg4WEeOHDGfHL506VLl5+erb9++Vn83Pj4+atSo0VXPPv31119ycHC47O0wffr0kbu7u9X4kvTYY49ZPXgtODhYubm55t/Rpb7++mutWrVKU6dOVf369c3P/J/IrbhRCv6tFvVz3rFjR91yyy3mNnfu3EIx/7zabdWqVapSpYqef/55q/YXXnhBhmGYl2Xfcccdql69ujZs2CDp4hnngsuVt2/frrNnz8owDH3//fdq3779VY/Dlu80SUlJqlu3rnmWW5KcnZ01ZMiQq+5funjZcUpKih566CH9+OOPiouLU1hYmOrWrVvkrTX/VJzc+fnnn6t169bmVUaX+ufl11lZWerSpYv27dun7777rtBVgkW52nfEZs2aKSQkxHxdkN/uv/9+1a9fv1D7pZ9zgTfeeENr1qzR+++/r3vuuUe5ublFruxAfrPG5dxl4O6771ZQUFCh9po1axb6wfzhhx/0yiuvKCUlRWfPnrXqy8rKsvpiEBAQUOR4jz76qF5++WUdPXpUdevW1Xfffafjx49bLfl04MABZWVlWd0rcqmCBzHcd9996tWrl1599VVNnz5dHTt2VHh4uAYMGCAnJ6crHvcvv/wiwzA0bty4yy6xdPz4cdWtW1e///57kZcrNW7c+IpjFDh16pRWrVql6Oho/fLLL2Z727Zt9fnnn+vnn3/W7bffbvWef35+Bw4ckKQrPogsKytLNWvW1N9//63JkydrwYIFOnr0qNX9RP8sBC7HuMz9yfXq1SuUiGvWrFloGYtFixZp6tSp2rdvn9WX/6J+LgrG+ud+gZJAjrvxOU66eEn3smXL9MUXX2jAgAHatGmTDh06pGHDhkm6+NT/s2fPFrnPpk2bKj8/X0eOHFHz5s1tHvNKLv3CJsn8u7v0/syC9vz8fGVlZalWrVo6cOCADMNQo0aNitzvpYX5jZ6XpEL3yEsy77vv1q2bevbsqRYtWqh69eqKjo62iiO34kapUaOGpIuXD//TO++8o9OnTyszM9OqQC3g4OCgevXqWbX9/vvv8vX1NfdboGnTpma/dPGX9CEhIeZqABs3blT79u3Vrl07XbhwQZs3b5a3t7dOnDhhUxFty3ea33//XQ0bNiwUV3BSxBZ33XWXli5dqtzcXP34449atmyZpk+frt69eys9PV3NmjW77HuLkzt//fVX9erVy6Y5xcTE6Ny5c9qxY0ex8+7lviOWRH67tJh/7LHHdOedd+rxxx8vtK41+c0aRXQ59uuvv6pz585q0qSJpk2bJj8/Pzk6OmrVqlWaPn16oQfQXO5eukcffVRjxozRkiVLFBMTo08//VTu7u5WT93Lz8+Xl5fXZc/SFjxIp2Cx+M2bN+vLL7/U6tWr9cQTT2jq1KnavHnzZc8EFIwhSS+++GKhs0kFipMgr2TJkiXKycnR1KlTNXXq1EL9CQkJevXVV63a/vn5Fcz3zTffvOxvCwuO97nnntOCBQsUExOjkJAQubu7y87OTv369bvqg4Jq1aolqejEJl38D6wolybUjz76SI8//rjCw8M1cuRIeXl5qUqVKpo8eXKRy60UjFXUvTpAaSHHXZ+Ch9IkJiZqwIABSkxMVJUqVazuA78el/uidOHChSLz0uVy1dVyWH5+vvlAoqJir/SZSxdz6Pnz53X69OlCBcH1zOtyGjZsqDvuuEMJCQmFimhyK24Ud3d31alTR7t37y7UV/ALucs9zNTJyem6Vhtp166duUbwxo0b9Z///EceHh5q0aKFNm7cKG9vb0myqYi+1n9318rR0VF33XWX7rrrLt1+++0aPHiwlixZoldeeeWGjHclPXv21CeffKI33nhDH374oU1/J9f6HfFaP2dHR0c99NBDeuONN/T3339b/b9LfrNGEV2Offnll8rJydGKFSusftNk64MVCgQEBOjuu+/W4sWLFR0draVLlyo8PNzqrErDhg31zTffqG3btjY92Oaee+7RPffco9dee02JiYmKiIjQJ598oieffPKyX7wKLompWrVqoaeo/pO/v795JvhS+/fvv+rcpItFcosWLYpMku+8844SExMLFdH/VPBwCTc3t6vO97PPPtOgQYOsCvZz584V+XTDf6pfv75cXFx08ODBq8Zeafxbb71VS5cutfr8L/efRMFYBb9xBsoCOe7ac5x08Ytx79699eGHHyozM1NLlizR/fffbz5g7ZZbblG1atWK3Oe+fftkb29f6GzFpWrWrFlkDvv999+tLnG8Xg0bNpRhGAoICCh0hZAtmjRpIuliXivqloEb4e+//y7yCeMHDx6Uvb39NR0HcDXdu3fXe++9py1btljdCnIt/P399c033xT65dO+ffvM/gLt27dXbm6uPv74Yx09etQsljt06GAW0bfffrtZTF8vf39//fTTTzIMwyrfXnpl4bUouELq//7v/8y2ovJ5cXJnw4YNi/zFRlHCw8PVpUsXPf7446pRo0aRK1H806X5rbT8/fffMgxDp0+ftvr/ku+O1rgnuhwr+C3SPy8NXrBgQbH39eijj2rz5s364IMP9Oeff1pd5ihJffv21YULFzRx4sRC7z1//rz5RerkyZOFfotVcJa24AtFwZOo//nly8vLSx07dtQ777xjlcAK/PHHH+afH3jgAW3evFlbtmyx6r/cWaRLHTlyRBs2bFDfvn3Vu3fvQtvgwYP1yy+/KDU19Yr7CQwMVMOGDfXWW28VefnUpfOtUqVKoc9l9uzZunDhwlXnW7VqVQUFBWnbtm1Xjb2con5WUlNTlZKSUmR8Wlqa3N3dS+wyTuBakOOuLcddKiIiQnl5eXrqqaf0xx9/WN1TXaVKFXXp0kVffPGF1RmqzMxMJSYmql27dld8gnTDhg21efNm5ebmmm0rV660admp4njkkUdUpUoVvfrqq4U+e8MwzHsCL6fgfsDryaFFOX/+fJFnf7Zs2aJdu3YVectCWlqamjdvbnUbAlBSRo0apWrVqumJJ55QZmZmof7inM194IEHdOHCBc2ZM8eqffr06bKzszOflC1dPNNdtWpVTZkyRZ6enuZ3h/bt22vz5s1av369TWehbRUWFqajR49a3b987tw5vfvuuza9/9tvvy3ys1i1apUk69tmXF1dC+Xy4uTOXr16mZeL/1NRcxg4cKBmzZql+Ph4vfTSS1c9lrp168rPz6/E85tU9JrZp06d0ueffy4/P79Ctz+lpaXJzs7O6h7syowz0eVYly5d5OjoqB49euipp57SmTNn9O6778rLy6vIL2hX0rdvX7344ot68cUX5enpWegsyX333aennnpKkydPVnp6urp06aKqVavqwIEDWrJkiWbOnKnevXtr0aJFevvtt/Xwww+rYcOGOn36tN599125ubnpgQcekHTxkstmzZpp8eLFuv322+Xp6akWLVqoRYsWmjt3rtq1a6eWLVtqyJAhuvXWW5WZmamUlBT973//048//ijp4n8U//3vf9W1a1cNGzbMXP7F39+/0L3A/5SYmGgu3VCUBx54QA4ODkpISLjiMhH29vZ677331K1bNzVv3lyDBw9W3bp1dfToUX377bdyc3PTl19+KeniZZX//e9/5e7urmbNmikl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Jycnubm5WW0AUBooogEAACqhtm3bav/+/VZtP//8s/z9/SVdfMiYj4+P1q5da/ZbLBalpqYqJCREkhQSEqJTp04pLS3NjFm3bp3y8/MVHBxsxmzYsEF5eXlmTHJysho3bmw+CTwkJMRqnIKYgnEAoDyhiAYAAKiEhg8frs2bN+v111/XL7/8osTERM2fP19RUVGSJDs7O8XExGjSpElasWKFdu3apYEDB8rX11fh4eGSLp657tq1q4YMGaItW7bohx9+UHR0tPr16ydfX19J0oABA+To6KjIyEjt2bNHixcv1syZMzVixAhzLsOGDVNSUpKmTp2qffv2afz48dq2bZuio6NL/XMBgKthiSsAAIBK6K677tKyZcs0ZswYTZgwQQEBAZoxY4YiIiLMmFGjRik7O1tDhw7VqVOn1K5dOyUlJcnZ2dmMSUhIUHR0tDp37ix7e3v16tVLs2bNMvvd3d21Zs0aRUVFKTAwULVr11ZsbKzVWtL33nuvEhMTNXbsWL388stq1KiRli9frhYtWpTOhwEAxUARDQAAUEk9+OCDevDBBy/bb2dnpwkTJmjChAmXjfH09FRiYuIVx2nVqpU2btx4xZg+ffqoT58+V54wAJQDXM4NAAAAAICNKKIBAAAAALARRTQAAAAAADaiiAYAAAAAwEYU0QAAAAAA2IgiGgAAAAAAG1FEAwAAAABgI4poAAAAAABsRBENAAAAAICNKKIBAAAAALARRTQAAAAAADaiiAYAAAAAwEYU0QAAAAAA2IgiGgAAAAAAG1FEAwAAAABgI4poAAAAAABsRBENAAAAAICNKKIBAAAAALARRTQAAAAAADaiiAYAAAAAwEYU0QDwD2+88Ybs7OwUExNjtp07d05RUVGqVauWqlevrl69eikzM9PqfYcPH1b37t1VrVo1eXl5aeTIkTp//rxVzHfffac777xTTk5Ouu2227Rw4cJSOCIAAACUFIpoALjE1q1b9c4776hVq1ZW7cOHD9eXX36pJUuWaP369Tp27JgeeeQRs//ChQvq3r27cnNztWnTJi1atEgLFy5UbGysGXPw4EF1795dnTp1Unp6umJiYvTkk09q9erVpXZ8AAAAuD4U0QDw/5w5c0YRERF69913VbNmTbM9KytL77//vqZNm6b7779fgYGBWrBggTZt2qTNmzdLktasWaOffvpJH330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",
"text/plain": [
""
]
},
"metadata": {},
"output_type": "display_data"
}
],
"source": [
"coeff_funcs[\"cflw_ha\"] = functools.partial(cmp_c_caa, expr=\"1.\", acodes=[\"harvest\"])\n",
"cflw_e[\"cflw_ha\"] = ({p:0.05 for p in fm.periods}, 1)\n",
"\n",
"fig, df, p = run_scenario(fm, \"scenario-4\", ws3.opt.SENSE_MAXIMIZE, acodes, coeff_funcs, cflw_e, cgen_data)\n"
]
},
{
"cell_type": "markdown",
"metadata": {},
"source": [
"Looking good! That spike in harvest area in period 10 is gone, but everything else still looks OK. This illustrates a typical approach that professional analysts would use to to add new constraints and re-run the model. \n",
"\n",
"We will now use this approach to add a constraint that forces harvest area in period 1 to be a maximum of 40 hectares to simulate a \"what if\" question approach to forest resource analysis (in this case asking the question, \"What if we capped harvest volume to about half the maximum sustainable harvest rate?\"). Note that in a realistic analysis that uses the optimization modelling functions, you do not need to include all the performance indicators you want to track in the model in the optimization model. You can limit optimization model indicators to the indicators that you need to define the objective function and constraints, and then define and compile any number of additional performance indicators that you apply to your `ws3` simulation in a _post hoc_ analysis phase (after solving the optimization model and running the simulation in `ws3`).\n"
]
},
{
"cell_type": "markdown",
"metadata": {},
"source": [
"Before running the next iteration of our model in the next section, we will calculate the mean yield ($m^3/ha$) for the last scenario we ran so we can observe the impact of reducing harvest level on yield."
]
},
{
"cell_type": "code",
"execution_count": 31,
"metadata": {},
"outputs": [
{
"data": {
"text/plain": [
"0 140.587682\n",
"1 140.587682\n",
"2 155.386386\n",
"3 137.338148\n",
"4 137.220378\n",
"5 137.075846\n",
"6 135.471071\n",
"7 136.652859\n",
"8 137.604713\n",
"9 132.681064\n",
"dtype: float64"
]
},
"execution_count": 31,
"metadata": {},
"output_type": "execute_result"
}
],
"source": [
"df_yield_1 = df[\"ohv\"] / df[\"oha\"]\n",
"df_yield_1"
]
},
{
"cell_type": "markdown",
"metadata": {},
"source": [
"### Adding an upper bound constraint on period-1 harvest area\n",
"\n",
"Now that we are on a roll and have everything all set up to update and re-run the model with a few lines of code, we can add an upper bound constraint on period 1 harvest area (maximum 40 hectares, about half the area harvested in the current solution). Even though we only constrain period 1 harvest area, the harvest area flow constraints should force a reduced harvest area in all other periods as well. "
]
},
{
"cell_type": "code",
"execution_count": 32,
"metadata": {},
"outputs": [
{
"data": {
"image/png": "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nZ0dfHx8MGfOHMhkMjEuLi4OoaGhGDBgAAwMDBAQEIClS5eK9XK5HHv27EFISAg8PDzQvHlzzJgxQ2uy2RdffBHx8fGYPn06PvroI7Rv3x5bt26Fq6urGDN16lQUFBRgwoQJyMvLQ69evZCQkABjY+Oa+nqIiJ5YlWfnJiIiIqL6z8vLC4IgaJWp1WrI5XKYmJhg9+7djz2GpaUl4uPjK41xd3fHoUOHKo0ZOnQohg4dWmG9RCLB7NmzMXv27Mf2iYiorlV7YjEiIiIiIiKiZwWTaCIiIiIiIiIdMYkmIiIiIiIi0hGTaCIiIiIiIiIdcWIxIiIiInomtf5wp96PeWmen96PSUT1C+9EExEREREREemISTQRERERERGRjphEExEREREREemISTQRERERERGRjphEExEREREREemISTQRERERERGRjphEExEREREREemISTQRERERERGRjphEExEREREREemISTQRERERERGRjphEExEREREREemISTQRERERERGRjphEE9Ezb+bMmZBIJFqbs7OzWH/v3j2EhISgWbNmaNy4MQICApCbm6t1jJycHPj5+cHU1BRWVlaYMmUK7t+/rxVz4MABdOvWDTKZDO3atcOaNWtq4/SIiIiISI+YRBMRAejUqROuXr0qbocPHxbrwsPDsX37dmzatAkHDx7ElStXMGTIELG+uLgYfn5+KCwsREpKCtauXYs1a9ZgxowZYkx2djb8/PzQr18/ZGZmIiwsDOPGjcPu3btr9TyJiIiIqHqM6roDRET1gZGREWxsbMqU5+fnY9WqVYiPj0f//v0BALGxsejYsSPS0tLQo0cP7NmzB2fPnsXevXthbW2NLl26YM6cOZg2bRpmzpwJqVSKmJgYODk5YcGCBQCAjh074vDhw1i0aBGUSmWtnisRERERPTneiSYiAnD+/HnY2dmhTZs2CAwMRE5ODgAgIyMDRUVF8Pb2FmOdnZ3RqlUrpKamAgBSU1Ph5uYGa2trMUapVEKtVuPMmTNizMPHKI0pPUZFNBoN1Gq11kZEREREdYdJNBE98zw9PbFmzRokJCRgxYoVyM7ORu/evXHr1i2oVCpIpVI0adJE6zPW1tZQqVQAAJVKpZVAl9aX1lUWo1arcffu3Qr7FhUVBblcLm4ODg7VPV0iIiIiqgY+zk1EzzxfX1/xz+7u7vD09ISjoyM2btwIExOTOuwZEBkZiYiICHFfrVYzkSYiIiKqQ1W6E71ixQq4u7vDwsICFhYWUCgU+OWXX8R6XWawJSKq75o0aYLnnnsOFy5cgI2NDQoLC5GXl6cVk5ubK75DbWNjU2asK91/XIyFhUWlibpMJhPH3NKNiIiIiOpOlZJoe3t7zJs3DxkZGTh27Bj69++PwYMHi+/8PW4GWyKip8Ht27dx8eJF2NrawsPDA40aNUJSUpJYn5WVhZycHCgUCgCAQqHAqVOncO3aNTEmMTERFhYWcHFxEWMePkZpTOkxiIiIiOjpUKXHuQcNGqS1/+mnn2LFihVIS0uDvb39Y2ewJSKqjz744AMMGjQIjo6OuHLlCj755BMYGhpixIgRkMvlCA4ORkREBCwtLWFhYYF3330XCoVCHNd8fHzg4uKCt956C/Pnz4dKpcL06dMREhICmUwGAJg4cSKWLVuGqVOnYuzYsdi3bx82btyInTt31uWpExEREVEVPfE70cXFxdi0aRMKCgqgUCgeO4Mtk2giqq/+/vtvjBgxAtevX0eLFi3Qq1cvpKWloUWLFgCARYsWwcDAAAEBAdBoNFAqlVi+fLn4eUNDQ+zYsQOTJk2CQqGAmZkZgoKCMHv2bDHGyckJO3fuRHh4OJYsWQJ7e3usXLmSy1sRERERPWWqnESfOnUKCoUC9+7dQ+PGjbFlyxa4uLggMzPzsTPYlkej0UCj0Yj7XL6FiGrb+vXrK603NjZGdHQ0oqOjK4xxdHTErl27Kj2Ol5cXTpw48UR9JCIiIqL6ocpLXHXo0AGZmZlIT0/HpEmTEBQUhLNnzz5xB7h8CxERERERET0tqpxES6VStGvXDh4eHoiKikLnzp2xZMkSnWawLU9kZCTy8/PF7fLly1U+CSIiIiLSlpycjEGDBsHOzg4SiQRbt24V64qKijBt2jS4ubnBzMwMdnZ2GDVqFK5cuaJ1jNatW0MikWht8+bN04o5efIkevfuDWNjYzg4OGD+/Pll+rJp0yY4OzvD2NgYbm5uZZ7cEQQBM2bMgK2tLUxMTODt7Y3z58/r78sgItKjKifRjyopKYFGo9FpBtvycPkWIiIiIv0rKChA586dy30V5c6dOzh+/Dg+/vhjHD9+HJs3b0ZWVhZeffXVMrGzZ8/G1atXxe3dd98V69RqNXx8fODo6IiMjAx88cUXmDlzJr755hsxJiUlBSNGjEBwcDBOnDgBf39/+Pv74/Tp02LM/PnzsXTpUsTExCA9PR1mZmZQKpW4d++enr8VIqLqq9I70ZGRkfD19UWrVq1w69YtxMfH48CBA9i9e7dOM9gSERERUe3w9fWFr69vuXVyuRyJiYlaZcuWLcMLL7yAnJwctGrVSiw3Nzev8KnCuLg4FBYWYvXq1ZBKpejUqRMyMzOxcOFCTJgwAQCwZMkSDBw4EFOmTAEAzJkzB4mJiVi2bBliYmIgCAIWL16M6dOnY/DgwQCAdevWwdraGlu3bsXw4cOr/V0QEelTle5EX7t2DaNGjUKHDh0wYMAAHD16FLt378ZLL70E4MEMtq+88goCAgLQp08f2NjYYPPmzTXScSIiIiLSn/z8fEgkkjKTxM6bNw/NmjVD165d8cUXX+D+/ftiXWpqKvr06QOpVCqWKZVKZGVl4ebNm2LMw6u3lMakpqYCALKzs6FSqbRi5HI5PD09xRgiovqkSneiV61aVWm9LjPYEhEREVH9cu/ePUybNg0jRozQerXuvffeQ7du3WBpaYmUlBRERkbi6tWrWLhwIQBApVLByclJ61jW1tZiXdOmTaFSqcSyh2NKV28p/W9lMeXhCi9EVFeeeJ1oIiIiInr6FRUVYdiwYRAEAStWrNCqi4iIEP/s7u4OqVSKt99+G1FRUZDJZLXdVS1RUVGYNWtWnfaBiJ5N1Z5YjIiIiIieTqUJ9F9//YXExMTHTvDq6emJ+/fv49KlSwAAGxsb5ObmasWU7pe+R11RzMP1D3+uvJjycIUXIqorTKKJiIiInkGlCfT58+exd+9eNGvW7LGfyczMhIGBAaysrAAACoUCycnJKCoqEmMSExPRoUMHNG3aVIx5ePWW0pjS1VucnJxgY2OjFaNWq5Gens4VXoioXuLj3EREREQN0O3bt3HhwgVxPzs7GydPngTwIIF+6623cPz4cezYsQPFxcXi+8eWlpaQSqVITU1Feno6+vXrB3Nzc6SmpiI8PBxvvvmmmCCPHDkSs2bNQnBwMKZNm4bTp09jyZIlWLRokdju5MmT0bdvXyxYsAB+fn5Yv349jh07Ji6DJZFIEBYWhrlz56J9+/ZwcnLCxx9/DDs7O/j7+9fSt0VEpDsm0UREREQN0LFjx9CvXz9x/+H3m69cuYJt27YBALp06aL1uf3798PLywsymQzr16/HzJkzodFo4OTkhPDwcK3jyOVy7NmzByEhIfDw8EDz5s0xY8YMcXkrAHjxxRcRHx+P6dOn46OPPkL79u2xdetWuLq6ijFTp05FQUEBJkyYgLy8PPTq1QsJCQkwNjbW99dCRFRtTKKJiIiIGiAvLy8IgqBVplarIZfL4ejoWKbuUd26dUNaWtpj23F3d8ehQ4cqjRk6dCiGDh1aYb1EIsHs2bMxe/bsx7ZHRFTX+E40ERERERERkY6YRBMRERERERHpiEk0ERERERERkY6YRBMRERERERHpiEk0ERERERERkY6YRBMRERERERHpiEk0ERERERERkY6YRBMRERERERHpiEk0ERERERERkY6YRBMRERERERHpiEk0ERERERERkY6YRBMRERERERHpiEk0ERERERERkY6YRBMRERERERHpiEk0ERERERERkY6YRBMRERERERHpiEk0ERERERERkY6YRBMRERERERHpqEpJdFRUFJ5//nmYm5vDysoK/v7+yMrK0orx8vKCRCLR2iZOnKjXThMRERERERHVhSol0QcPHkRISAjS0tKQmJiIoqIi+Pj4oKCgQCtu/PjxuHr1qrjNnz9fr50mIiIiIiIiqgtVSqITEhIwevRodOrUCZ07d8aaNWuQk5ODjIwMrThTU1PY2NiIm4WFhV47TURUk+bNmweJRIKwsDCx7N69ewgJCUGzZs3QuHFjBAQEIDc3V+tzOTk58PPzg6mpKaysrDBlyhTcv39fK+bAgQPo1q0bZDIZ2rVrhzVr1tTCGRERERGRvlTrnej8/HwAgKWlpVZ5XFwcmjdvDldXV0RGRuLOnTvVaYaIqNYcPXoUX3/9Ndzd3bXKw8PDsX37dmzatAkHDx7ElStXMGTIELG+uLgYfn5+KCwsREpKCtauXYs1a9ZgxowZYkx2djb8/PzQr18/ZGZmIiwsDOPGjcPu3btr7fyIiIiIqHqMnvSDJSUlCAsLQ8+ePeHq6iqWjxw5Eo6OjrCzs8PJkycxbdo0ZGVlYfPmzeUeR6PRQKPRiPtqtfpJu0REVC23b99GYGAgvv32W8ydO1csz8/Px6pVqxAfH4/+/fsDAGJjY9GxY0ekpaWhR48e2LNnD86ePYu9e/fC2toaXbp0wZw5czBt2jTMnDkTUqkUMTExcHJywoIFCwAAHTt2xOHDh7Fo0SIolco6OWciIiIiqponvhMdEhKC06dPY/369VrlEyZMgFKphJubGwIDA7Fu3Tps2bIFFy9eLPc4UVFRkMvl4ubg4PCkXSIiqpaQkBD4+fnB29tbqzwjIwNFRUVa5c7OzmjVqhVSU1MBAKmpqXBzc4O1tbUYo1QqoVarcebMGTHm0WMrlUrxGOXRaDRQq9VaGxERERHVnSdKokNDQ7Fjxw7s378f9vb2lcZ6enoCAC5cuFBufWRkJPLz88Xt8uXLT9IlIqJqWb9+PY4fP46oqKgydSqVClKpFE2aNNEqt7a2hkqlEmMeTqBL60vrKotRq9W4e/duuf3iLxqJiIiI6pcqJdGCICA0NBRbtmzBvn374OTk9NjPZGZmAgBsbW3LrZfJZLCwsNDaiIhq0+XLlzF58mTExcXB2Ni4rrujhb9oJCIiIqpfqvROdEhICOLj4/Hzzz/D3NxcvLsil8thYmKCixcvIj4+Hi+//DKaNWuGkydPIjw8HH369CkzSQ8RUX2RkZGBa9euoVu3bmJZcXExkpOTsWzZMuzevRuFhYXIy8vTuhudm5sLGxsbAICNjQ2OHDmiddzS2bsfjnl0Ru/c3FxYWFjAxMSk3L7JZDLIZLJqnyMRERER6UeV7kSvWLEC+fn58PLygq2trbht2LABACCVSrF37174+PjA2dkZ77//PgICArB9+/Ya6TwRkT4MGDAAp06dQmZmprh1794dgYGB4p8bNWqEpKQk8TNZWVnIycmBQqEAACgUCpw6dQrXrl0TYxITE2FhYQEXFxcx5uFjlMaUHoOIiIiI6r8q3YkWBKHSegcHBxw8eLBaHSIiqm3m5uZaqwwAgJmZGZo1ayaWBwcHIyIiApaWlrCwsMC7774LhUKBHj16AAB8fHzg4uKCt956C/Pnz4dKpcL06dMREhIi3kmeOHEili1bhqlTp2Ls2LHYt28fNm7ciJ07d9buCRMRERHRE3viJa6IiJ4lixYtgoGBAQICAqDRaKBUKrF8+XKx3tDQEDt27MCkSZOgUChgZmaGoKAgzJ49W4xxcnLCzp07ER4ejiVLlsDe3h4rV67k8lZERERET5EnXuKKiKghO3DgABYvXizuGxsbIzo6Gjdu3EBBQQE2b94svutcytHREbt27cKdO3fw77//4ssvv4SRkfbvKr28vHDixAloNBpcvHgRo0eProWzIaJnUXJyMgYNGgQ7OztIJBJs3bpVq14QBMyYMQO2trYwMTGBt7c3zp8/rxVz48YNBAYGwsLCAk2aNEFwcDBu376tFXPy5En07t0bxsbGcHBwwPz588v0ZdOmTXB2doaxsTHc3Nywa9euKveFiKi+YBJNRERE1AAVFBSgc+fOiI6OLrd+/vz5WLp0KWJiYpCeng4zMzMolUrcu3dPjAkMDMSZM2eQmJiIHTt2IDk5GRMmTBDr1Wo1fHx84OjoiIyMDHzxxReYOXMmvvnmGzEmJSUFI0aMQHBwME6cOAF/f3/4+/vj9OnTVeoLEVF9wce5iYiIiBogX19f+Pr6llsnCAIWL16M6dOnY/DgwQCAdevWwdraGlu3bsXw4cPx+++/IyEhAUePHkX37t0BAF999RVefvllfPnll7Czs0NcXBwKCwuxevVqSKVSdOrUCZmZmVi4cKGYbC9ZsgQDBw7ElClTAABz5sxBYmIili1bhpiYGJ36QkRUn/BONBEREdEz5tKlS1CpVPD29hbL5HI5PD09kZqaCgBITU1FkyZNxAQaALy9vWFgYID09HQxpk+fPpBKpWKMUqlEVlYWbt68KcY83E5pTGk72dnZj+0LEVF9wjvRRERERM+Y0uX4rK2ttcqtra2hUqkAACqVClZWVlr1RkZGsLS01IpxcnIqc4zSuqZNm0KlUj22ncf1pTwajQYajUbcV6vVlZwxEZH+8E40ERERET11oqKiIJfLxc3BwaGuu0REzwgm0URERETPmNI7zLm5uVrlubm54soDNjY24h3rUvfv38eNGze0Yso7RmldZTEP1z+uL+WJjIxEfn6+uF2+fPkxZ01EpB9MoomIiIieMa1bt4aNjQ2SkpLEMrVajfT0dCgUCgCAQqFAXl4eMjIyxJh9+/ahpKQEnp6eYkxycjKKiorEmMTERHTo0AFNmzYVYx5upzSmtB0nJ6fH9qU8MpkMFhYWWhsRUW1gEk1ERETUAN2+fRuZmZnIzMwE8GACr5MnTwIAJBIJwsLCMHfuXGzbtg2nTp3CqFGjYGdnB39/fwBAx44dMXDgQIwfPx5HjhzBr7/+itDQUAwfPhx2dnYAgJEjR0IqlSI4OBhnzpzBhg0bsGTJEkRERIj9mDx5MhISErBgwQKcO3cOM2fOxLFjxxAaGqpzX4iI6hNOLEZERETUAB07dgz9+vUT9x9ObAFg6tSpKCgowIQJE5CXl4devXohISEBxsbGYkxcXBxCQ0MxYMAAGBgYICAgAEuXLhXr5XI59uzZg5CQEHh4eKB58+aYMWOG1lrSL774IuLj4zF9+nR89NFHaN++PbZu3QpXV9cq9YWIqL5gEk1ERETUAHl5eUEQBK0ytVoNuVwO4MEd4NmzZ2P27NkVHsPS0hLx8fGVtuPu7o5Dhw5VGjN06FAMHTq0wnpd+kJEVF/wcW4iIiIiIiIiHTGJJiIiIiIiItIRk2giIiIiIiIiHTGJJiIiIiIiItIRk2giIiIiIiIiHTGJJiIiIiIiItIRk2giIiIiIiIiHTGJJiIiIiIiItIRk2giIiIiIiIiHTGJJiIiIiIiItIRk2giIiIiIiIiHTGJJiIiIiIiItJRlZLoqKgoPP/88zA3N4eVlRX8/f2RlZWlFXPv3j2EhISgWbNmaNy4MQICApCbm6vXThMRERERERHVhSol0QcPHkRISAjS0tKQmJiIoqIi+Pj4oKCgQIwJDw/H9u3bsWnTJhw8eBBXrlzBkCFD9N5xIiIiIiIiotpmVJXghIQErf01a9bAysoKGRkZ6NOnD/Lz87Fq1SrEx8ejf//+AIDY2Fh07NgRaWlp6NGjh/56TkRERERERFTLqvVOdH5+PgDA0tISAJCRkYGioiJ4e3uLMc7OzmjVqhVSU1Or0xQRERERERFRnavSneiHlZSUICwsDD179oSrqysAQKVSQSqVokmTJlqx1tbWUKlU5R5Ho9FAo9GI+2q1+km7RERERERERFSjnvhOdEhICE6fPo3169dXqwNRUVGQy+Xi5uDgUK3jEREREREREdWUJ0qiQ0NDsWPHDuzfvx/29vZiuY2NDQoLC5GXl6cVn5ubCxsbm3KPFRkZifz8fHG7fPnyk3SJiIiIiIiIqMZVKYkWBAGhoaHYsmUL9u3bBycnJ616Dw8PNGrUCElJSWJZVlYWcnJyoFAoyj2mTCaDhYWF1kZERERERERUH1XpneiQkBDEx8fj559/hrm5ufies1wuh4mJCeRyOYKDgxEREQFLS0tYWFjg3XffhUKh4MzcRERERERE9NSrUhK9YsUKAICXl5dWeWxsLEaPHg0AWLRoEQwMDBAQEACNRgOlUonly5frpbNEREREREREdanKj3OXt5Um0ABgbGyM6Oho3LhxAwUFBdi8eXOF70MTEdUHK1asgLu7u/hKiUKhwC+//CLW37t3DyEhIWjWrBkaN26MgIAA5Obmah0jJycHfn5+MDU1hZWVFaZMmYL79+9rxRw4cADdunWDTCZDu3btsGbNmto4PSIiIiLSo2qtE01E1BDY29tj3rx5yMjIwLFjx9C/f38MHjwYZ86cAQCEh4dj+/bt2LRpEw4ePIgrV65gyJAh4ueLi4vh5+eHwsJCpKSkYO3atVizZg1mzJghxmRnZ8PPzw/9+vVDZmYmwsLCMG7cOOzevbvWz5eIiIiIntwTrxNNRNRQDBo0SGv/008/xYoVK5CWlgZ7e3usWrUK8fHx6N+/P4AHr7B07NgRaWlp6NGjB/bs2YOzZ89i7969sLa2RpcuXTBnzhxMmzYNM2fOhFQqRUxMDJycnLBgwQIAQMeOHXH48GEsWrQISqWy1s+ZiIiIiJ4M70QTET2kuLgY69evR0FBARQKBTIyMlBUVARvb28xxtnZGa1atUJqaioAIDU1FW5ubrC2thZjlEol1Gq1eDc7NTVV6xilMaXHICIiIqKnA+9EExEBOHXqFBQKBe7du4fGjRtjy5YtcHFxQWZmJqRSKZo0aaIVb21tLa5QoFKptBLo0vrSuspi1Go17t69CxMTk3L7pdFooNFoxH21Wl2t8yQiIiKi6uGdaCIiAB06dEBmZibS09MxadIkBAUF4ezZs3XdLURFRUEul4ubg4NDXXeJiIiI6JnGJJqICIBUKkW7du3g4eGBqKgodO7cGUuWLIGNjQ0KCwuRl5enFZ+bmyuuPGBjY1Nmtu7S/cfFWFhYVHgXGgAiIyORn58vbpcvX67uqRIRERFRNTCJJiIqR0lJCTQaDTw8PNCoUSMkJSWJdVlZWcjJyYFCoQAAKBQKnDp1CteuXRNjEhMTYWFhARcXFzHm4WOUxpQeoyIymUxceqt0IyIiIqK6wySaiJ55kZGRSE5OxqVLl3Dq1ClERkbiwIEDCAwMhFwuR3BwMCIiIrB//35kZGRgzJgxUCgU6NGjBwDAx8cHLi4ueOutt/Dbb79h9+7dmD59OkJCQiCTyQAAEydOxJ9//ompU6fi3LlzWL58OTZu3Ijw8PC6PHUieoa1bt0aEomkzBYSEgIA8PLyKlM3ceJErWPk5OTAz88PpqamsLKywpQpU3D//n2tmAMHDqBbt26QyWRo164d1qxZU6Yv0dHRaN26NYyNjeHp6YkjR47U2HkTEVUXJxYjomfetWvXMGrUKFy9ehVyuRzu7u7YvXs3XnrpJQDAokWLYGBggICAAGg0GiiVSixfvlz8vKGhIXbs2IFJkyZBoVDAzMwMQUFBmD17thjj5OSEnTt3Ijw8HEuWLIG9vT1WrlzJ5a2IqM4cPXoUxcXF4v7p06fx0ksvYejQoWLZ+PHjtcYyU1NT8c/FxcXw8/ODjY0NUlJScPXqVYwaNQqNGjXCZ599BgDIzs6Gn58fJk6ciLi4OCQlJWHcuHGwtbUVx78NGzYgIiICMTEx8PT0xOLFi6FUKpGVlQUrK6ua/hqIiKqMSTQRPfNWrVpVab2xsTGio6MRHR1dYYyjoyN27dpV6XG8vLxw4sSJJ+ojEZG+tWjRQmt/3rx5aNu2Lfr27SuWmZqainM7PGrPnj04e/Ys9u7dC2tra3Tp0gVz5szBtGnTMHPmTEilUsTExMDJyQkLFiwAAHTs2BGHDx/GokWLxCR64cKFGD9+PMaMGQMAiImJwc6dO7F69Wp8+OGHNXHqRETVwse5iYiIiJ5xhYWF+P777zF27FhIJBKxPC4uDs2bN4erqysiIyNx584dsS41NRVubm5ay/cplUqo1WqcOXNGjPH29tZqS6lUIjU1VWw3IyNDK8bAwADe3t5iTEU0Gg3UarXWRkRUG3gnmoiIiOgZt3XrVuTl5WH06NFi2ciRI+Ho6Ag7OzucPHkS06ZNQ1ZWFjZv3gwAUKlUWgk0AHFfpVJVGqNWq3H37l3cvHkTxcXF5cacO3eu0j5HRUVh1qxZT3S+RETVwSSaiIiI6Bm3atUq+Pr6ws7OTiybMGGC+Gc3NzfY2tpiwIABuHjxItq2bVsX3dQSGRmJiIgIcV+tVsPBwaEOe0REzwom0URERETPsL/++gt79+4V7zBXxNPTEwBw4cIFtG3bFjY2NmVm0c7NzQUA8T1qGxsbsezhGAsLC5iYmMDQ0BCGhoblxlT0LnYpmUwmroBARFSb+E40ERER0TMsNjYWVlZW8PPzqzQuMzMTAGBrawsAUCgUOHXqFK5duybGJCYmwsLCAi4uLmJMUlKS1nESExOhUCgAAFKpFB4eHloxJSUlSEpKEmOIiOobJtFEREREz6iSkhLExsYiKCgIRkb/94DixYsXMWfOHGRkZODSpUvYtm0bRo0ahT59+sDd3R0A4OPjAxcXF7z11lv47bffsHv3bkyfPh0hISHiHeKJEyfizz//xNSpU3Hu3DksX74cGzduRHh4uNhWREQEvv32W6xduxa///47Jk2ahIKCAnG2biKi+oaPcxMRERE9o/bu3YucnByMHTtWq1wqlWLv3r1YvHgxCgoK4ODggICAAEyfPl2MMTQ0xI4dOzBp0iQoFAqYmZkhKChIa11pJycn7Ny5E+Hh4ViyZAns7e2xcuVKcXkrAHjjjTfw77//YsaMGVCpVOjSpQsSEhLKTDZGRFRfMIkmIiIiekb5+PhAEIQy5Q4ODjh48OBjP+/o6Ihdu3ZVGuPl5YUTJ05UGhMaGorQ0NDHtkdEVB/wcW4iIiIiIiIiHTGJJiIiIiIiItIRk2giIiIiIiIiHTGJJiIiIiIiItIRk2giIiIiIiIiHTGJJiIiIiIiItJRlZPo5ORkDBo0CHZ2dpBIJNi6datW/ejRoyGRSLS2gQMH6qu/RERERERERHWmykl0QUEBOnfujOjo6ApjBg4ciKtXr4rbDz/8UK1OEhEREREREdUHRlX9gK+vL3x9fSuNkclksLGxeeJOEREREREREdVHNfJO9IEDB2BlZYUOHTpg0qRJuH79ek00Q0RERERERFSrqnwn+nEGDhyIIUOGwMnJCRcvXsRHH30EX19fpKamwtDQsEy8RqOBRqMR99Vqtb67RERERERERKQXek+ihw8fLv7Zzc0N7u7uaNu2LQ4cOIABAwaUiY+KisKsWbP03Q0iIiIiIiIivavxJa7atGmD5s2b48KFC+XWR0ZGIj8/X9wuX75c010iIiIiIiIieiJ6vxP9qL///hvXr1+Hra1tufUymQwymaymu0FERERERERUbVVOom/fvq11Vzk7OxuZmZmwtLSEpaUlZs2ahYCAANjY2ODixYuYOnUq2rVrB6VSqdeOExEREREREdW2KifRx44dQ79+/cT9iIgIAEBQUBBWrFiBkydPYu3atcjLy4OdnR18fHwwZ84c3m0mIiIiIiKip16Vk2gvLy8IglBh/e7du6vVISIiIiIiIqL6qsYnFiMiIiIiIiJqKJhEExEREREREemISTQRERERERGRjphEExEREREREemISTQRERERERGRjphEExEREREREemISTQRERERERGRjphEE9EzLyoqCs8//zzMzc1hZWUF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EZVLr0m0jY0NACA3N1erPDc3V6x7lEwmg4WFhdZGREREREREVB/pNYl2cnKCjY0NkpKSxDK1Wo309HQoFAp9NkVERERERERU66o8O/ft27dx4cIFcT87OxuZmZmwtLREq1atEBYWhrlz56J9+/ZwcnLCxx9/DDs7O/j7++uz30RERERERES1rspJ9LFjx9CvXz9xPyIiAgAQFBSENWvWYOrUqSgoKMCECROQl5eHXr16ISEhAcbGxvrrNREREREREVEdqHIS7eXlBUEQKqyXSCSYPXs2Zs+eXa2OEREREREREdU3dT47NxEREREREdHTgkk0ERERERERkY6YRBMRERERERHpiEk0ERERERERkY6YRBMRERERERHpiEk0ERERERERkY6YRBMRERERERHpiEk0ERERERERkY6YRBMRERERERHpiEk0ERERERERkY6YRBMRERERERHpiEk0ERERERERkY6YRBMRERERERHpiEk0ERERERERkY6YRBMRERERERHpiEk0ERERERERkY6YRBPRMy85ORmDBg2CnZ0dJBIJtm7dqlUvCAJmzJgBW1tbmJiYwNvbG+fPn9eKuXHjBgIDA2FhYYEmTZogODgYt2/f1oo5efIkevfuDWNjYzg4OGD+/Pk1fWpEREREpGdMoonomVdQUIDOnTsjOjq63Pr58+dj6dKliImJQXp6OszMzKBUKnHv3j0xJjAwEGfOnEFiYiJ27NiB5ORkTJgwQaxXq9Xw8fGBo6MjMjIy8MUXX2DmzJn45ptvavz8iIiIiEh/mEQT0TPP19cXc+fOxWuvvVamThAELF68GNOnT8fgwYPh7u6OdevW4cqVK+Id699//x0JCQlYuXIlPD090atXL3z11VdYv349rly5AgCIi4tDYWEhVq9ejU6dOmH48OF47733sHDhwto8VSIiUVRUFJ5//nmYm5vDysoK/v7+yMrK0orx8vKCRCLR2iZOnKgVk5OTAz8/P5iamsLKygpTpkzB/fv3tWIOHDiAbt26QSaToV27dlizZk2Z/kRHR6N169YwNjaGp6cnjhw5ovdzJiLSBybRRESVyM7Ohkqlgre3t1gml8vh6emJ1NRUAEBqaiqaNGmC7t27izHe3t4wMDBAenq6GNOnTx9IpVIxRqlUIisrCzdv3qywfY1GA7VarbUREenDwYMHERISgrS0NCQm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TURERERERKQjJtFEREREREREOmISTURERERERKQjJtFEREREREREOmISTURERERERKQjJtFEREREREREOmISTURERERERKQjJtFEREREREREOmISTURERERERKQjJtFEREREREREOmISTURERERERKQjJtFEREREREREOmISTURERERERKQjJtFEREREREREOqqxJDo6OhqtW7eGsbExPD09ceTIkZpqiojoqcLxkYiofBwfiehpUCNJ9IYNGxAREYFPPvkEx48fR+fOnaFUKnHt2rWaaI6I6KnB8ZGIqHwcH4noaVEjSfTChQsxfvx4jBkzBi4uLoiJiYGpqSlWr15dE80RET01OD4SEZWP4yMRPS2M9H3AwsJCZGRkIDIyUiwzMDCAt7c3UlNTy8RrNBpoNBpxPz8/HwCgVqur1G6J5s4T9rh85bVfG23UVjtPYxu11U5DaaO22qnLvyuPixcEQa/9qK6qjo+AfsbIp/H/eW21w7G+/rVRW+00lDYqaudxsRwfH+DPb922UVvtNJQ2aqudhn4uj4vVaXwU9Oyff/4RAAgpKSla5VOmTBFeeOGFMvGffPKJAIAbN27c9L5dvnxZ30NctVR1fBQEjpHcuHGrmY3jIzdu3LiVv+kyPur9TnRVRUZGIiIiQtwvKSnBjRs30KxZM0gkkjrs2ZNRq9VwcHDA5cuXYWFhUdfdqRaeS/3UUM6lJs9DEATcunULdnZ2ej1uXeAYWT81lPMAeC71VU2dC8fH+os/v/VPQzkPgOeii6qMj3pPops3bw5DQ0Pk5uZqlefm5sLGxqZMvEwmg0wm0ypr0qSJvrtV6ywsLJ76H9BSPJf6qaGcS02dh1wu1/sxq6uq4yPAMbK+ayjnAfBc6quaOBeOj/Ubf37rn4ZyHgDP5XF0HR/1PrGYVCqFh4cHkpKSxLKSkhIkJSVBoVDouzkioqcGx0ciovJxfCSip0mNPM4dERGBoKAgdO/eHS+88AIWL16MgoICjBkzpiaaIyJ6anB8JCIqH8dHInpa1EgS/cYbb+Dff//FjBkzoFKp0KVLFyQkJMDa2rommqtXZDIZPvnkkzKPFz2NeC71U0M5l4ZyHlX1LI+PQMP5/95QzgPgudRXDelcdMXxseH8P28o59JQzgPgueibRBDq2RoHRERERERERPWU3t+JJiIiIiIiImqomEQTERER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",
"text/plain": [
""
]
},
"metadata": {},
"output_type": "display_data"
}
],
"source": [
"coeff_funcs[\"cgen_ha\"] = functools.partial(cmp_c_caa, expr=\"1.\", acodes=[\"harvest\"])\n",
"cgen_data[\"cgen_ha\"] = {\"lb\":{1:0.}, \"ub\":{1:40.}}\n",
"\n",
"fig, df, p = run_scenario(fm, \"scenario-5\", ws3.opt.SENSE_MAXIMIZE, acodes, coeff_funcs, cflw_e, cgen_data)\n"
]
},
{
"cell_type": "markdown",
"metadata": {},
"source": [
"As expected, harvest area is down to about 40 hectares per period (and respecting even flow constraints). Not surprisingly (if you understand how forests work), this induced a similar reduction in the harvest area. Also not surprisingly, harvesting fewer trees each year results in an accumulation of growing stock in the forest (compare with the previous scenarios, where the growsing stock inventory was relatively constant throughout the simulation horizon)."
]
},
{
"cell_type": "markdown",
"metadata": {},
"source": [
"Now lets recalculate our mean yield metric."
]
},
{
"cell_type": "code",
"execution_count": 33,
"metadata": {},
"outputs": [
{
"data": {
"text/plain": [
"0 161.535231\n",
"1 146.150923\n",
"2 146.150923\n",
"3 161.535231\n",
"4 161.535231\n",
"5 161.535231\n",
"6 161.535231\n",
"7 161.535231\n",
"8 178.538939\n",
"9 161.535231\n",
"dtype: float64"
]
},
"execution_count": 33,
"metadata": {},
"output_type": "execute_result"
}
],
"source": [
"df_yield_2 = df[\"ohv\"] / df[\"oha\"]\n",
"df_yield_2"
]
},
{
"cell_type": "markdown",
"metadata": {},
"source": [
"Now lets calculate some statistics comparing these yield results from the last two scenarios we ran."
]
},
{
"cell_type": "code",
"execution_count": 34,
"metadata": {},
"outputs": [
{
"data": {
"text/plain": [
"(0 20.947548\n",
" 1 5.563241\n",
" 2 -9.235463\n",
" 3 24.197082\n",
" 4 24.314853\n",
" 5 24.459385\n",
" 6 26.064160\n",
" 7 24.882371\n",
" 8 40.934226\n",
" 9 28.854167\n",
" dtype: float64,\n",
" 0 14.899988\n",
" 1 3.957132\n",
" 2 -5.943547\n",
" 3 17.618617\n",
" 4 17.719564\n",
" 5 17.843687\n",
" 6 19.239650\n",
" 7 18.208453\n",
" 8 29.747692\n",
" 9 21.747012\n",
" dtype: float64,\n",
" np.float64(21.098157013702718),\n",
" np.float64(15.503824824706948))"
]
},
"execution_count": 34,
"metadata": {},
"output_type": "execute_result"
}
],
"source": [
"df_diff_abs = df_yield_2 - df_yield_1\n",
"df_diff_rel = (df_diff_abs / df_yield_1) * 100.\n",
"df_diff_abs, df_diff_rel, df_diff_abs.mean(), df_diff_rel.mean()"
]
},
{
"cell_type": "markdown",
"metadata": {},
"source": [
"So on average yield is 21 $m^3/ha$ (16%) more in the reduced harvest scenario compared to the refernece scenario. This is not surprising as reducing even-flow harvest level will tend to lengthen rotation length, so stands have time to accumulate more merchantable yield (trees grow larger if given more time!) before they get harvested. "
]
},
{
"cell_type": "markdown",
"metadata": {},
"source": [
"### Defining an infeasible optimization model\n",
"\n",
"Next, we deliberately define an infeasible pair of constraintints on the harvest area. This is done by setting the lower bound of the harvest area constraint to be 50 hectares per period and the upper bound to 40 hectares per period (which is obviously mathematically impossible). "
]
},
{
"cell_type": "code",
"execution_count": 35,
"metadata": {},
"outputs": [
{
"name": "stdout",
"output_type": "stream",
"text": [
"add_problem: build problem\n",
"generate trees using 1 workers\n",
"process trees\n",
"_bld_p_m1: build problem\n",
"_bld_p_m1: done building problem\n",
"add_problem: compile flow constraints\n",
"_cmp_cflw_m1: phase 1\n",
"_cmp_cflw_m1: phase 2\n",
"_cmp_cflw_m1: phase 3\n",
"add_problem: compile general constraints\n",
"Running HiGHS 1.11.0 (git hash: 364c83a): Copyright (c) 2025 HiGHS under MIT licence terms\n",
"LP has 76 rows; 305 cols; 3813 nonzeros\n",
"Coefficient ranges:\n",
" Matrix [3e-02, 5e+04]\n",
" Cost [2e+01, 4e+04]\n",
" Bound [1e+00, 1e+00]\n",
" RHS [1e+00, 1e+09]\n",
"Presolving model\n",
"63 rows, 297 cols, 3441 nonzeros 0s\n",
"Model not optimal.\n",
"Problem status detected on presolve: Infeasible\n",
"Model status : Infeasible\n",
"Objective value : 0.0000000000e+00\n",
"HiGHS run time : 0.00\n"
]
},
{
"data": {
"text/plain": [
"(None, None, )"
]
},
"execution_count": 35,
"metadata": {},
"output_type": "execute_result"
}
],
"source": [
"cgen_data[\"cgen_ha\"] = {\"lb\":{1:50.}, \"ub\":{1:40.}}\n",
"run_scenario(fm, \"scenario-6\", ws3.opt.SENSE_MAXIMIZE, acodes, coeff_funcs, cflw_e, cgen_data, verbose=True)\n"
]
},
{
"cell_type": "markdown",
"metadata": {},
"source": [
"Our `run_scenario` function does not have very advanced error handling implemented, but you can still see from the solver output that the problem in infeasible (so no solution compiled or displayed for this case).\n",
"\n",
"You would not typically _deliberately_ define an infeasible constraint, but it is a good exercise to do so just to make sure you understand what infeasible solutions are (and how you end up with one)."
]
}
],
"metadata": {
"kernelspec": {
"display_name": ".venv",
"language": "python",
"name": "python3"
},
"language_info": {
"codemirror_mode": {
"name": "ipython",
"version": 3
},
"file_extension": ".py",
"mimetype": "text/x-python",
"name": "python",
"nbconvert_exporter": "python",
"pygments_lexer": "ipython3",
"version": "3.12.3"
}
},
"nbformat": 4,
"nbformat_minor": 2
}