Metadata-Version: 2.5
Name: ws3
Version: 1.1.0a5
Dynamic: Summary
Author-email: Gregory Paradis <gregory.paradis@ubc.ca>
Maintainer-email: Kathleen Coupland <kathleen.coupland@ubc.ca>, Elaheh Ghasemi <elaheh.ghasemi@ubc.ca>, Salar Ghotb <salar.ghotb@ubc.ca>
License: MIT
License-File: LICENSE
Requires-Python: >=3.10
Requires-Dist: dill
Requires-Dist: fiona
Requires-Dist: highspy
Requires-Dist: matplotlib
Requires-Dist: numpy>=1.21
Requires-Dist: pandas>=1.3
Requires-Dist: profilehooks
Requires-Dist: pyyaml>=5.1
Requires-Dist: rasterio
Requires-Dist: scipy>=1.7
Provides-Extra: agent
Requires-Dist: fresh-agent-core>=0.1.0a1; extra == 'agent'
Provides-Extra: agent-mcp
Requires-Dist: fresh-agent-core[mcp]>=0.1.0a1; extra == 'agent-mcp'
Provides-Extra: cbm
Requires-Dist: libcbm; extra == 'cbm'
Provides-Extra: dev
Requires-Dist: coverage; extra == 'dev'
Requires-Dist: flake8; extra == 'dev'
Requires-Dist: fresh-agent-core>=0.1.0a1; extra == 'dev'
Requires-Dist: ipython; extra == 'dev'
Requires-Dist: mypy; extra == 'dev'
Requires-Dist: pytest; extra == 'dev'
Requires-Dist: pytest-cov; extra == 'dev'
Requires-Dist: ruff; extra == 'dev'
Provides-Extra: docs
Requires-Dist: nbsphinx>=0.9; extra == 'docs'
Requires-Dist: sphinx-rtd-theme>=2; extra == 'docs'
Requires-Dist: sphinx>=7; extra == 'docs'
Requires-Dist: sphinxcontrib-mermaid>=0.9; extra == 'docs'
Provides-Extra: github-mcp
Requires-Dist: github-mcp-server; extra == 'github-mcp'
Provides-Extra: gurobi
Requires-Dist: gurobipy; extra == 'gurobi'
Provides-Extra: pulp
Requires-Dist: pulp; extra == 'pulp'
Provides-Extra: release
Requires-Dist: build; extra == 'release'
Requires-Dist: twine; extra == 'release'
Provides-Extra: rv
Requires-Dist: pacal>=1.6.1; extra == 'rv'
Requires-Dist: setuptools; extra == 'rv'
Requires-Dist: sympy; extra == 'rv'
Description-Content-Type: text/markdown

[![tests](https://github.com/UBC-FRESH/ws3/actions/workflows/ci.yml/badge.svg)](https://github.com/UBC-FRESH/ws3/actions/workflows/ci.yml)
[![codecov](https://codecov.io/gh/UBC-FRESH/ws3/branch/main/graph/badge.svg)](https://codecov.io/gh/UBC-FRESH/ws3)
[![DOI](https://zenodo.org/badge/DOI/10.5281/zenodo.17331213.svg)](https://doi.org/10.5281/zenodo.17331213)

    
# 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](https://ubc-fresh.github.io/ws3/).


## Table of Contents

- [Installation](#installation) 
- [Modules](#modules)
- [Usage](#usage)
- [License](#license)
- [Acknowledgments](#acknowledgments)
- [Contact](#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**](https://github.com/UBC-FRESH/ws3/blob/dev/examples/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**](https://github.com/UBC-FRESH/ws3/blob/dev/examples/010_ws3_model_example-fromscratch.ipynb): This example builds a new `ws3` model from scratch.
- [**020_ws3_model_example-woodstock.ipynb**](https://github.com/UBC-FRESH/ws3/blob/dev/examples/020_ws3_model_example-woodstock.ipynb): This example builds a `ws3` model from Woodstock-format text input files.
- [**030_ws3_libcbm_sequential-fromscratch.ipynb**](https://github.com/UBC-FRESH/ws3/blob/dev/examples/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**](https://github.com/UBC-FRESH/ws3/blob/dev/examples/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**](https://github.com/UBC-FRESH/ws3/blob/dev/examples/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**](https://github.com/UBC-FRESH/ws3/blob/dev/examples/050_dss_avoided_fire.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 fire type project.
- [**060_dss_avoid_harvest.ipynb**](https://github.com/UBC-FRESH/ws3/blob/dev/examples/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.

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

```python
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:

```ipython
%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](https://github.com/UBC-FRESH/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](mailto:gregory.paradis@ubc.ca) — Lead developer and architect of the `ws3` framework.

**Additional Contributors:**  
[Elaheh Ghasemi](mailto:elaheh.ghasemi@ubc.ca)  
[Kathleen Coupland](mailto:kathleen.coupland@ubc.ca)  
[Salar Ghotb](mailto:salar.ghotb@ubc.ca)

For full contribution history, see [GitHub Contributors](https://github.com/UBC-FRESH/ws3/graphs/contributors).

## Getting Help

- **Documentation**: [Full documentation](https://ubc-fresh.github.io/ws3/)
- **Questions**: [GitHub Discussions](https://github.com/UBC-FRESH/ws3/discussions)
- **Bug Reports**: [Issue Tracker](https://github.com/UBC-FRESH/ws3/issues)
- **Source Code**: [GitHub Repository](https://github.com/UBC-FRESH/ws3)