ws3 - Wood Supply Simulation System

ws3 (Wood Supply Simulation System) is a Python package for modeling landscape-level wood supply planning problems.

Read the tutorial here.

Table of Contents

• Installation
• Modules
• Usage
• License
• Acknowledgments
• Contact

---

Installation

We recommend installing ws3 package into a Python venv (virtual environment) to minimize interactions with system-level packages.

Optional CBM support available via pip install libcbm.

Optional Gurobi support available via pip install ws3[gurobi] or conda install -c gurobi gurobi.

Optional PuLP support available via pip install pulp.

In 000_venv_python_kernel_setup.ipynb we provide the instructions for how to set up a new venv-sandboxed Python kernel and make it available in your JupyterLab environment, assuming that you are running this notebook in a standard linux-based environment and a regular (non-root) using running commands in a bash terminal.

Modules

ws3 consists of the following main modules:

• common.py: Contains definitions for global attributes, functions, and classes that might be used anywhere in the package.
• core.py: Contains Interpolator class used by Curve class to interpolate between real data points.
• forest.py: Implements functions for building and running wood supply simulation models.
• opt.py: Implements functions for formulating and solving optimization problems.
• spatial.py: Implements the ForestRaster class, which can be used to allocate an aspatial disturbance schedule (for example, an optimal solution to a wood supply problem generated by an instance of the forest.ForestModel class) to a rasterized representation of the forest inventory.

Usage

Multiple examples are available to demonstrate the utilization of ws3. Below is an overview explaining each of these examples:

• 010_ws3_model_example-fromscratch.ipynb: This example builds a new ws3 model from scratch.
• 020_ws3_model_example-woodstock.ipynb: This example builds a ws3 model from Woodstock-format text input files.
• 030_ws3_libcbm_sequential-fromscratch.ipynb: This example creates the linkages between ws3 and libcbm from scratch (i.e., all code required to create these linkages is developed directly in this notebook).
• 031_ws3_libcbm_sequential-builtin.ipynb: This example replicates what 030_ws3_libcbm_sequential-fromscratch.ipynb does, but using ws3 built-in CBM linkage functions.
• 040_ws3_libcbm_neilsonhack-fromscratch.ipynb: This example shows how to implement the Neilson hack (i.e., generate carbon yield curves from a CBM for use in a forest estate model) using ws3 and libcbm.
• 050_dss_avoided_fire: This example shows the implementation of a notebook-based decision-support system (DSS) for evaluating the net system-level carbon emissions impact of an avoided fire type project.
• 060_dss_avoid_harvest.ipynb: This example shows the implementation of a notebook-based decision-support system (DSS) for evaluating the net system-level carbon emissions impact of an avoided harvesting type project.

Agent capabilities (optional)

ws3 ships a small set of operations designed to be driven by an AI coding agent, where the output is validated against real model state before it is returned.

Capability	Oracle
build_mask	The proposed mask resolves against the ForestModel to ≥1 development type
explain_exception	Every ws3 symbol the explanation cites actually exists
diagnose_import	The suggested fix is applied to a scratch copy and the section genuinely re-imports
rtfm	The capability name returned is real; cited doc URLs return HTTP 200
ws3_hint	Every cited ws3 symbol exists in the package; every cited doc URL returns HTTP 200
inspect_model	Live ForestModel metadata (base year, horizon/periods, period length, theme/action/dtype counts, total area at period 1) — read-only, validated against the actual in-memory model object

A capability returns validated output or nothing at all — never a plausible guess. The design rule is no oracle, no capability: if a proposal cannot be checked against real state, it does not become a capability.

pip install ws3[agent]
ws3-agent-mcp --model-path path/to/model --model-name my_model

import ws3.agent

if ws3.agent.available():
    result = ws3.agent.run('build_mask', 'mature spruce stands', context=fm)
    print(result.value if result.ok else result.errors)

In IPython / Jupyter, magics operate on a ForestModel named fm in scope:

%ws3_capabilities              # list all registered capabilities
%ws3_inspect_model             # metadata snapshot of `fm`
%ws3_hint "how do I add a theme"

Entirely optional. Core modelling never requires it, and import ws3 never loads it. Built on fresh-agent-core.

License

MIT License Copyright (c) 2025 Gregory Paradis.

Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:

• The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.
• The software is provided "as is", without warranty of any kind, express or implied, including but not limited to the warranties of merchantability, fitness for a particular purpose, and noninfringement. In no event shall the authors or copyright holders be liable for any claim, damages, or other liability, whether in an action of contract, tort, or otherwise, arising from, out of, or in connection with the software or the use or other dealings in the software.

Authors and Contributors

Primary Author:
Gregory Paradis — Lead developer and architect of the ws3 framework.

Additional Contributors:
Elaheh Ghasemi
Kathleen Coupland
Salar Ghotb

For full contribution history, see GitHub Contributors.

Getting Help

• Documentation: Full documentation
• Questions: GitHub Discussions
• Bug Reports: Issue Tracker
• Source Code: GitHub Repository