Metadata-Version: 2.4
Name: ws4
Version: 0.2.0
Summary: WS4: Wood Supply Simulation System (Spatially explicit)
Author-email: FRESH Lab <noreply@example.org>
License-Expression: Apache-2.0
Project-URL: Homepage, https://github.com/UBC-FRESH/ws4
Project-URL: Documentation, https://ubc-fresh.github.io/ws4/
Project-URL: Repository, https://github.com/UBC-FRESH/ws4
Project-URL: Issues, https://github.com/UBC-FRESH/ws4/issues
Keywords: forestry,forest estate model,simulation,optimization,spatial
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Science/Research
Classifier: Operating System :: POSIX :: Linux
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Scientific/Engineering
Classifier: Typing :: Typed
Requires-Python: >=3.11
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: pydantic>=2.7
Requires-Dist: typer>=0.12
Requires-Dist: rich>=13.7
Requires-Dist: pandas>=2.2
Requires-Dist: numpy>=1.26
Requires-Dist: pyarrow>=15
Requires-Dist: pyyaml>=6
Provides-Extra: geo
Requires-Dist: geopandas>=0.14; extra == "geo"
Requires-Dist: pyogrio>=0.9; extra == "geo"
Requires-Dist: shapely>=2.0; extra == "geo"
Requires-Dist: rtree>=1.0; extra == "geo"
Provides-Extra: carbon
Requires-Dist: libcbm==2.10.2; extra == "carbon"
Provides-Extra: lidar
Requires-Dist: geopandas>=0.14; extra == "lidar"
Requires-Dist: pyogrio>=0.9; extra == "lidar"
Requires-Dist: rasterio>=1.3; extra == "lidar"
Provides-Extra: opt
Requires-Dist: numba>=0.59; extra == "opt"
Requires-Dist: networkx>=3.2; extra == "opt"
Requires-Dist: ray>=2.9; extra == "opt"
Requires-Dist: scipy>=1.11; extra == "opt"
Requires-Dist: threadpoolctl>=3.1; extra == "opt"
Provides-Extra: web
Requires-Dist: fastapi>=0.110; extra == "web"
Requires-Dist: uvicorn>=0.29; extra == "web"
Requires-Dist: mapbox-vector-tile>=2.1; extra == "web"
Requires-Dist: mercantile>=1.2; extra == "web"
Requires-Dist: shapely>=2.0; extra == "web"
Requires-Dist: pyproj>=3.6; extra == "web"
Dynamic: license-file

# WS4 — Wood Supply Simulation System (Spatially explicit)

A CLI-first, HPC-ready forest estate model for multi-core Linux environments.

WS4 makes spatial structure part of the model: fragments are the decision units, blocks are a runtime
aggregate, and adjacency, patch structure, and road access are enforced during simulation and
optimization rather than allocated afterwards.

## Key invariants

- **Launch control files start a run; they do not build one.**
- **Blocks** are a runtime aggregate of **fragments**; block geometry is not a compile-time input.
- **Compilation happens at the fragment level** (tracks, curves, treatments, features/products).
- **Runtime aggregation**: product and feature attributes are summed to the block level on the fly.
- **Block treatment operability** is the set intersection across a block's constituent fragments. If
  fragments differ in eligibility/operability, the block's available treatment set can be narrow or
  empty.

The design favors columnar datasets (Parquet/Arrow), vectorized kernels, and parallel evaluation.

## Documentation

- `AGENTS.md` — the working contract for coding agents.
- `ROADMAP.md` — the plan of record and issue tracker map.
- `notes/design/ws4-scope.md` — problem statement, users, scope, and success criteria.
- `notes/design/ws4-architecture.md` — the architecture design.
- `notes/adr/` — architecture decision records.

## Quick start

```bash
# (in a virtualenv)
pip install -e .[geo,opt]

# Build a canonical dataset (from an XML recipe + fragments)
ws4 build --xml path/to/model.xml --fragments path/to/fragments.shp --out build/compiled

# Simulate a given schedule
ws4 simulate --dataset build/compiled --schedule schedules/baseline.csv --years 200 --out out/sim

# Optimize using weighted goal programming (metaheuristic)
ws4 optimize --dataset build/compiled --targets config/targets.yaml --weights config/weights.yaml --threads 32 --time-limit 02:00:00 --out out/runA
```
