Metadata-Version: 2.4
Name: fresh-daugherty
Version: 0.1.0a1
Summary: Open, reproducible ws3-based reproduction of Daugherty (1991): dynamic inconsistency in LP-based forest planning models
Author: UBC FRESH Lab
License-Expression: MIT
Project-URL: Homepage, https://github.com/UBC-FRESH/fresh-daugherty
Project-URL: Documentation, https://ubc-fresh.github.io/fresh-daugherty/
Project-URL: Repository, https://github.com/UBC-FRESH/fresh-daugherty
Project-URL: Issues, https://github.com/UBC-FRESH/fresh-daugherty/issues
Project-URL: Changelog, https://github.com/UBC-FRESH/fresh-daugherty/blob/main/CHANGE_LOG.md
Keywords: forestry,optimization,dynamic-programming,dynamic-inconsistency,forest-planning
Classifier: Development Status :: 2 - Pre-Alpha
Classifier: Intended Audience :: Science/Research
Classifier: Programming Language :: Python :: 3
Classifier: Topic :: Scientific/Engineering
Requires-Python: >=3.11
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: numpy
Requires-Dist: pandas
Requires-Dist: pydantic>=2
Requires-Dist: pyyaml
Requires-Dist: rich
Requires-Dist: typer
Requires-Dist: ws3
Requires-Dist: highspy
Requires-Dist: pulp
Provides-Extra: docs
Requires-Dist: sphinx>=7; extra == "docs"
Requires-Dist: sphinx-rtd-theme>=2; extra == "docs"
Provides-Extra: dev
Requires-Dist: build>=1.2; extra == "dev"
Requires-Dist: pytest>=8; extra == "dev"
Requires-Dist: ruff>=0.5; extra == "dev"
Requires-Dist: sphinx>=7; extra == "dev"
Requires-Dist: sphinx-rtd-theme>=2; extra == "dev"
Requires-Dist: twine>=5; extra == "dev"
Provides-Extra: quality
Requires-Dist: ruff>=0.5; extra == "quality"
Provides-Extra: release
Requires-Dist: build>=1.2; extra == "release"
Requires-Dist: twine>=5; extra == "release"
Provides-Extra: test
Requires-Dist: pytest>=8; extra == "test"
Dynamic: license-file

# fresh-daugherty

An open, transparent, and fully reproducible reproduction of the modelling
methods and case study of **Daugherty (1991)**, built on
[`ws3`](https://github.com/UBC-FRESH/ws3):

> Daugherty, P. J. (1991). *Credibility of Long Term Forest Planning: Dynamic
> Inconsistency in Linear Programming Based Forest Planning Models.* PhD
> thesis, University of California, Berkeley.

## Why this exists

Daugherty (1991) proves that linear-programming forest-planning models solved
as **open-loop** formulations admit **dynamically inconsistent** plans — plans
that fail Bellman's principle of optimality: a future planner, re-solving from
the realized state under the same goals, would not follow the plan's tail.
Such plans are not a credible basis for policy, and trade-off / shadow-price
analysis derived from them is biased.

The thesis was never published peer-reviewed and is effectively inaccessible
(archival hard copy only). As a result, the modelling trap it documents is
repeatedly rediscovered, and the literature contains many LP forest-planning
models presented (and cited) as rational dynamic-programming models that do
not satisfy the Bellman time-stationarity condition. This project reproduces
the thesis stack openly — open source, reproducible, transparent — so the
result becomes citable and the trap detectable, and backs a short
peer-reviewed paper.

## What it does

- Reproduces the Daugherty (1991) open-loop harvest-scheduling LP in ws3
  (Model I, and Model II via a ws3 extension).
- A sequential-replanning simulator that measures the occurrence and
  magnitude of dynamic inconsistency (changes in decisions and in projected
  output levels over time).
- The consistent-solution (subgame-perfect) construct.
- The case-study experiments across initial forest conditions, harvest
  policies (harvest-flow constraints), and interest rates.

## Status

`v0.1.0a1`. The reproduction pipeline (case-study instance, open-loop Model I
LP, sequential-replanning simulator, experiment grid) is implemented and
tested; the dynamic-inconsistency result is reproduced. See `ROADMAP.md` and
`planning/v0.1.0a1-plan.md`.

## Quick Start

```bash
pip install -e ".[dev]"
fresh-daugherty --help
```

## Related

- [`fresh-fuchs`](https://github.com/UBC-FRESH/fresh-fuchs) — the stochastic,
  risk-aware forest landscape-planning model whose inner-LP dynamic
  inconsistency motivated this reproduction (documented in its
  `planning/dynamic-inconsistency-note.md`).
- [`ws3`](https://github.com/UBC-FRESH/ws3) — the wood-supply engine this
  reproduction is built on (and extends with a Model II LP formulation).

## Companion reference

The Model I/II/III formulations are documented in an accessible, citable
source (cited alongside the thesis):

> Gunn, E. A. (2007). *Models for Strategic Forest Management.* Chapter 16 in
> A. Weintraub, C. Romero, T. Bjørndal & R. Epstein (eds.), *Handbook of
> Operations Research in Natural Resources*, Springer, pp. 317-341.

Gunn (2007, pp. 331-332) cites Daugherty (1991) and describes the
dynamic-inconsistency phenomenon directly (the "declining non-declining
yield").

## License

MIT, Copyright (c) 2026 UBC FRESH Lab.
