Module Boundaries

This page defines the responsibilities and boundaries of each ws3 module.

Forest Module (ws3.forest)

Responsibility: Model state, development types, actions, and schedule management.

Owns: - ws3.forest.ForestModel — Central coordinator for all model data - ws3.forest.DevelopmentType — Forest stratum (age, area, yield curves, transitions) - ws3.forest.Action — Management intervention definition - ws3.forest.GreedyAreaSelector — Default area selection strategy

Key methods on ForestModel: - ws3.forest.ForestModel.__init__() — Constructor - ws3.forest.ForestModel.import_areas_section() — Load area data - ws3.forest.ForestModel.import_yields_section() — Load yield curves - ws3.forest.ForestModel.import_actions_section() — Load action definitions - ws3.forest.ForestModel.import_transitions_section() — Load transition rules - ws3.forest.ForestModel.register_curve() — Register a Curve with the model - ws3.forest.ForestModel.add_problem() — Create and compile an optimization problem - ws3.forest.ForestModel.compile_schedule() — Compile schedule from problem solution - ws3.forest.ForestModel.apply_schedule() — Apply schedule to model state - ws3.forest.ForestModel.compile_product() — Evaluate yield products - ws3.forest.ForestModel.inventory() — Query inventory at a period

Does not own: - Curve construction (delegated to ws3.core) - Optimization solving (delegated to ws3.opt) - Spatial allocation (delegated to ws3.spatial)

Dependencies: - ws3.core for Curve, Node, Tree classes - ws3.opt for Problem, Variable, Constraint classes - ws3.common for constants and utilities

Optimization Module (ws3.opt)

Responsibility: Optimization problem formulation and solving.

Owns: - ws3.opt.Problem — Optimization problem (variables, constraints, objective) - ws3.opt.Variable — Decision variable definition - ws3.opt.Constraint — Constraint definition - Solver dispatch (Gurobi, PuLP, HiGHS)

Key methods on Problem: - ws3.opt.Problem.__init__() — Constructor (name, sense, solver) - ws3.opt.Problem.add_var() — Add a variable - ws3.opt.Problem.add_constr() — Add a constraint - ws3.opt.Problem.z() — Set/get objective function coefficients - ws3.opt.Problem.solve() — Solve the problem - ws3.opt.Problem.status() — Get solution status - ws3.opt.Problem.merge() — Merge another problem into this one

Does not own: - Model state (reads from ws3.forest) - Schedule compilation (reads from ws3.forest)

Dependencies: - ws3.forest for model data (via ForestModel.add_problem)

Core Module (ws3.core)

Responsibility: Core data structures — curves and dynamic programming state trees.

Owns: - ws3.core.Curve — Growth/yield curve with interpolation - ws3.core.Interpolator — Linear interpolation between curve points - ws3.core.Node — State tree node for dynamic programming - ws3.core.Tree — Dynamic programming state tree

Key methods on Curve: - ws3.core.Curve.__init__() — Constructor (label, points, is_volume, period_length, …) - ws3.core.Curve.add_points() — Add data points - ws3.core.Curve.simplify() — Simplify curve by removing redundant points - ws3.core.Curve.points() — Get current (x,y) point list - ws3.core.Curve.__call__() — Interpolate y at given x

Key methods on Node: - ws3.core.Node.data() — Get/set node data - ws3.core.Node.parent() — Get parent node - ws3.core.Node.children() — Get child nodes - ws3.core.Node.is_root(), ws3.core.Node.is_leaf() — Tree position queries

Does not own: - Model state (no ForestModel reference) - Optimization (no Problem reference)

Dependencies: - ws3.common for default constants

Spatial Module (ws3.spatial)

Responsibility: Spatial allocation of harvest schedules to rasterized forest inventory.

Owns: - ws3.spatial.ForestRaster — Raster-based spatial allocation

Key methods on ForestRaster: - ws3.spatial.ForestRaster.__init__() — Constructor (hdt_map, hdt_func, src_path, snk_path, …) - ws3.spatial.ForestRaster.allocate_schedule() — Allocate schedule to raster - ws3.spatial.ForestRaster.commit() — Close output file handles - ws3.spatial.ForestRaster.cleanup() — Commit and close input file handle

Does not own: - Optimization (reads schedule from ws3.forest) - Model state (reads development type mapping from ws3.forest)

Dependencies: - ws3.forest for ForestModel instance and development type mapping - rasterio for GeoTIFF I/O

Common Module (ws3.common)

Responsibility: Shared constants, utilities, and geospatial helpers.

Owns: - Global constants (PERIOD_LENGTH_DEFAULT, HORIZON_DEFAULT, MIN_AGE_DEFAULT, MAX_AGE_DEFAULT, etc.) - Utility functions (hex_id, is_num, reproject, clean_vector_data)

Does not own: - Curve objects (defined in ws3.core) - Model-specific logic

Dependencies: - None (leaf module)

Integration Module (ws3.integration)

Responsibility: Integration with external tools (fhops, FEMIC, FreshForge).

Owns: - ws3.integration.FHOPSIntegrator — Harvest cost curve generation - ws3.integration.FEMICIntegrator — Carbon pool accounting - ws3.integration.FreshForgeIntegrator — Workflow automation

Key methods: - ws3.integration.FEMICIntegrator.get_carbon_pools() — List carbon pools

Does not own: - Core model logic - Optimization

Dependencies: - ws3.forest (optional, for ForestModel integration)

Module Interaction Pattern

        graph LR
  FM["ForestModel"] --> OPT["Problem (opt)"]
  FM --> SPA["ForestRaster (spatial)"]
  FM --> CORE["Curve/Node/Tree (core)"]
  FM --> COM["Constants (common)"]
  OPT --> CORE
  OPT --> COM
  SPA --> FM
  INT["Integration"] --> FM