Limitations and Boundaries

This guide honestly documents what ws3 can and cannot do, helping you set realistic expectations and avoid common pitfalls.

Core Limitations

1. Aspatial Core

ws3’s core optimization is aspatial. It optimizes harvest by development type but does not inherently consider spatial arrangement.

Implication: You cannot optimize for contiguous harvest blocks or minimize edge effects without external spatial allocation.

Workaround: Use ws3.spatial for post-optimization spatial allocation, or integrate with SpaDES for spatially-explicit simulation.

2. Deterministic Growth

Standard ws3 uses deterministic growth curves. Stochastic growth is not natively supported in the core optimization.

Implication: You cannot directly optimize for risk-adjusted outcomes without external scenario analysis.

Workaround: Run multiple scenarios with different growth parameters and compare outcomes.

3. Single-Objective Optimization

The core solver optimizes a single objective function (volume, NPV, or area control). Multi-objective optimization requires external frameworks.

Implication: You cannot directly trade off volume vs. carbon vs. revenue in a single optimization.

Workaround: Use weighted sums or run separate optimizations for each objective and compare.

4. No Built-in Carbon Accounting

Carbon accounting requires libCBM integration. Without it, ws3 has no understanding of carbon stocks or fluxes.

Implication: You cannot optimize for carbon sequestration without libCBM.

Workaround: Install libCBM and use callback system to track carbon.

External Dependencies

libCBM

Requirement: Carbon accounting Limitation: Requires separate installation and configuration Alternative: Use simplified carbon models if libCBM is unavailable

Gurobi

Requirement: Commercial license for optimization Limitation: Not free for commercial use Alternative: Use open-source solvers (GLPK, CBC) with reduced performance

SpaDES

Requirement: R installation and spades_ws3 package Limitation: Adds complexity to workflow Alternative: Use aspatial analysis for initial planning

Platform Limitations

Linux/macOS

Fully supported and tested.

Windows

Partially supported. Some users report issues with: - Path handling in certain configurations - Reticulate (Python-R bridge) stability - Parallel processing with multiprocessing

Recommendation: Use WSL2 or Docker for Windows users.

Data Limitations

Minimum Data Requirements

ws3 requires: - Development types with area, age, species, site index - Growth curves for each species/site index combination - Actions with transitions

Insufficient data leads to: Infeasible problems or unrealistic results.

Data Quality

ws3 does not validate data quality beyond basic checks. Garbage in, garbage out applies.

Recommendation: Use Loading a Woodstock Model to check data before running optimization.

Performance Boundaries

Model Size

ws3 can handle models with: - Up to ~1000 development types (tested) - Planning horizons up to 100 periods (tested) - Multiple objectives and constraints

Beyond these limits: Performance degrades or solver may fail.

Recommendation: For very large models, consider: - Aggregating similar development types - Reducing planning horizon - Using decomposition strategies

Solver Performance

Typical solve times: - Small models (<100 DTs): <1 second - Medium models (100-500 DTs): 1-10 seconds - Large models (>500 DTs): 10-60 seconds - Very large models (>1000 DTs): 1-10 minutes

These are estimates. Actual times depend on constraint complexity and solver efficiency.

Known Issues

Issue 1: Floating-point precision

Description: Area conservation may not be exact due to floating-point arithmetic.

Impact: Small discrepancies (e.g., 0.001 ha) in area balances.

Workaround: Round results to reasonable precision (0.01 ha).

Issue 2: Solver warm-start

Description: Re-solving with small changes may not reuse previous solution efficiently.

Impact: Repeated solves may be slower than expected.

Workaround: Use area control mode for rapid scenario testing.

Issue 3: Callback state persistence

Description: Callback state (e.g., libCBM) may not persist across simulation restarts.

Impact: Need to re-initialize callbacks after restart.

Workaround: Save and restore callback state manually.

Unsupported Features

The following features are explicitly not supported:

  1. Dynamic land use change — ws3 assumes fixed forest area

  2. Market price fluctuations — Prices are static

  3. Climate change adaptation — No dynamic parameter adjustment

  4. Multi-agent optimization — Single decision-maker only

  5. Real-time optimization — Batch processing only

When to Use ws3

ws3 is a good fit when you need: - Strategic harvest scheduling over long horizons - Optimization of harvest volume, revenue, or area control - Integration with carbon accounting (via libCBM) - Scenario analysis across multiple objectives

ws3 may not be the right tool when you need: - Spatially-explicit optimization (use SpaDES or custom spatial models) - Real-time decision support (ws3 is batch-oriented) - Short-term operational planning (consider tactical models) - Multi-scale integration (consider fhops or custom frameworks)

Reporting Issues

If you encounter issues not covered here:

  1. Check the Troubleshooting guide for common problems

  2. Search GitHub issues for similar reports

  3. Create a new issue with: - Minimal reproducible example - Expected vs. actual behavior - System information (Python version, OS, ws3 version) - Full error traceback

Further Reading