The ws3 Textbook

This section teaches the concepts behind forest estate modelling, using ws3 as the working example. It is designed for students, new users, and anyone who wants a structured introduction to the theory and practice of wood supply simulation.

The chapters build on each other in a fixed prerequisite chain. Each chapter ends with a summary and exercises to reinforce the material.

Who Is This For?

• University students studying forest resource management, sustainable forest management, or forest economics.

• New ws3 users who want to understand why the model works the way it does, not just how to run it.

• Researchers from adjacent fields (ecology, economics, geography) who need a grounding in wood supply modelling concepts.

How to Use This Textbook

Read the chapters in order. Each chapter assumes you have completed the previous one. The prerequisite chain is:

         graph LR
CH01["ch01: Forest Estate Models"] --> CH02["ch02: Forest Inventory"]
CH01 --> CH03["ch03: Growth & Yield"]
CH02 --> CH04["ch04: Actions & Transitions"]
CH03 --> CH04
CH04 --> CH05["ch05: Optimization"]
CH04 --> CH06["ch06: Spatial Allocation"]
CH05 --> CH07["ch07: Financial Analysis"]
CH06 --> CH07
CH07 --> CH08["ch08: Uncertainty & Risk"]
CH08 --> CH09["ch09: Advanced Topics"]
CH07 --> CH10["ch10: Carbon Modelling"]
CH09 --> CH10
CH10 --> CH11["ch11: FEMIC Models"]
CH10 --> CH12["ch12: FHOPS Integration"]
CH11 --> CH13["ch13: FreshForge Workflows"]
CH12 --> CH13
CH13 --> CH14["ch14: SpaDES Integration"]
CH14 --> CH15["ch15: Disturbance Modelling"]
CH14 --> CH16["ch16: Supply Chain"]
CH15 --> CH16
    

Chapter Listing

Textbook: Introduction to Forest Estate Modelling

This textbook introduces the concepts, methods, and computational tools used in forest estate modelling — the discipline that ws3 serves. Each chapter builds on the previous ones, with learning objectives, worked ws3 examples, and exercises at the end.

The chapters are designed for:

• Students learning forest resource analysis and wood supply modelling.

• Practitioners who want a structured refresher on core concepts.

• Developers who need domain context before extending ws3.

Prerequisite Chain

        graph LR
  CH01["ch01: Forest Estate Models"] --> CH02["ch02: Forest Inventory"]
  CH01 --> CH03["ch03: Growth & Yield"]
  CH02 --> CH04["ch04: Actions & Transitions"]
  CH03 --> CH04
  CH04 --> CH05["ch05: Optimization"]
  CH04 --> CH06["ch06: Spatial Allocation"]
  CH05 --> CH07["ch07: Financial Analysis"]
  CH06 --> CH07
  CH07 --> CH08["ch08: Uncertainty & Risk"]
  CH08 --> CH09["ch09: Advanced Topics"]
  CH07 --> CH10["ch10: Carbon Modelling"]
  CH09 --> CH10
  CH10 --> CH11["ch11: FEMIC Models"]
  CH10 --> CH12["ch12: FHOPS Integration"]
  CH11 --> CH13["ch13: FreshForge Workflows"]
  CH12 --> CH13
  CH13 --> CH14["ch14: SpaDES Integration"]
  CH14 --> CH15["ch15: Disturbance Modelling"]
  CH14 --> CH16["ch16: Supply Chain"]
  CH15 --> CH16
    

Note

Chapters 02 and 03 can be studied in parallel after Chapter 01. Chapters 05 and 06 can also be studied in parallel after Chapter 04. Chapter 10 (Carbon Modelling) can be studied after Chapter 07 (Financial Analysis). Chapters 11-13 build on earlier chapters and cover the UBC-FRESH ecosystem. Chapters 14-16 cover integration with external systems and advanced topics.

Chapters 15 and 16 are now full synthesis chapters that connect spatial, disturbance, and supply-chain workflows.

Contents

Chapters

• Chapter 1: Forest Estate Models
  • Learning Objectives
  • What Is a Wood Supply Model?
  • Why Do We Need Them?
  • Key Concepts
  • How ws3 Implements This
  • Summary
  • Exercises
  • Further Reading
• Chapter 2: Forest Inventory and Data Preparation
  • Learning Objectives
  • What Is Forest Inventory Data?
  • Inventory Data Structure
  • Preparing Data for ws3
  • Data Validation
  • Common Data Issues
  • Exercises
  • Further Reading
• Chapter 3: Growth and Yield
  • Learning Objectives
  • What Are Growth Curves?
  • The Curve Class
  • Fitting Growth Curves
  • Validating Growth Curves
  • Common Growth Curve Shapes
  • Exercises
  • Further Reading
• Chapter 4: Actions and Transitions
  • Learning Objectives
  • What Are Actions?
  • Types of Actions
  • Defining Actions in ws3
  • Understanding Transitions
  • Complex Transitions
  • Actions and the Simulation Loop
  • Action Components
  • Defining a Complete Action Set
  • Common Mistakes
  • Exercises
  • Further Reading
• Chapter 5: Optimization
  • Learning Objectives
  • What Is Optimization in Forest Planning?
  • The Optimization Problem
  • Setting Up an Optimization Problem
  • Solving the Problem
  • Extracting Results
  • Multi-Period Optimization
  • Solver Comparison
  • Common Optimization Patterns
  • Exercises
  • Further Reading
• Chapter 6: Spatial Allocation
  • Learning Objectives
  • Aspatial vs. Spatial Models
  • Forest Raster Data
  • Creating a Forest Raster
  • Spatial Allocation via allocate_schedule
  • Spatial Constraints
  • Performance Considerations
  • Exercises
  • Further Reading
• Chapter 7: Financial Analysis
  • Learning Objectives
  • What Is Financial Analysis in Forest Planning?
  • Net Present Value
  • Using ws3’s Financial Functions
  • Rotation Economics
  • Sensitivity Analysis
  • Common Financial Mistakes
  • Exercises
  • Further Reading
• Chapter 8: Uncertainty and Risk
  • Learning Objectives
  • Why Does Uncertainty Matter?
  • Sources of Uncertainty
  • Scenario Analysis
  • Monte Carlo Simulation
  • Risk Assessment
  • Adaptive Management
  • Limitations of Deterministic Models
  • Exercises
  • Further Reading
• Chapter 9: Advanced Topics
  • Learning Objectives
  • Custom Growth Functions
  • Custom Area Selectors
  • Integrating with Other Tools
  • Parallel Computation
  • Limitations and Boundaries
  • Extending ws3: Best Practices
  • Exercises
  • Further Reading
• Chapter 10: Carbon Modelling
  • Learning Objectives
  • Why Carbon Matters in Forest Management
  • Carbon in the Forest System
  • Carbon Calculation Basics
  • Using ws3 for Carbon Calculations
  • Carbon Fluxes from Harvest
  • Carbon in Optimization
  • Carbon Reporting
  • Policy Context
  • Limitations
  • Exercises
  • Further Reading
• Chapter 11: Building Models with FEMIC
  • Learning Objectives
  • What Is FEMIC?
  • The Instance Concept
  • Pipelines
  • Workflows
  • The FEMIC-to-ws3 Bridge
  • FreshForge Integration
  • Configuration Files
  • Best Practices
  • Exercises
  • Further Reading
• Chapter 12: Harvest Cost Curves with FHOPS
  • Learning Objectives
  • What Is FHOPS?
  • The Productivity Concept
  • Generating Cost Curves
  • Cost Curve Structure
  • Integrating with ws3
  • The fhops CLI
  • CLI Configuration
  • Best Practices
  • Exercises
  • Further Reading
• Chapter 13: Workflow Automation with FreshForge
  • Learning Objectives
  • What Is FreshForge?
  • The Problem FreshForge Solves
  • Workflow Components
  • Creating Reusable Steps
  • Materialization
  • Transparency and Auditability
  • End-to-End Example
  • Best Practices
  • Exercises
  • Further Reading
• Chapter 14: Integrating ws3 with SpaDES
  • Learning Objectives
  • What Is SpaDES?
  • Architecture
  • Harvest Scheduling Modes
  • Configuring the Integration
  • Data Flow
  • Output and Monitoring
  • Limitations and Considerations
  • Exercises
  • Further Reading
• Chapter 15: Modelling Natural Disturbances
  • Learning Objectives
  • Why Model Disturbances?
  • Disturbance Modelling Paradigms
  • Disturbance Types
  • From Disturbance to Transition Logic
  • Integrating Disturbances with ws3
  • Scenario Design for Disturbance Planning
  • Resilience Metrics
  • Challenges
  • Worked Example: Simple Disturbance Stress Test
  • Link to Spatial and Supply-Chain Modules
  • Future Directions
  • Exercises
  • Further Reading
• Chapter 16: Value-Creation and Forest Supply Chain Modelling
  • Learning Objectives
  • Why This Chapter Exists
  • Conceptual Gap: AAC vs. Consumed Fibre
  • Phase 1: Build Compatible Inputs
  • Phase 2: Network Flow Optimization
  • Interpreting the Scenario Curves
  • How This Maps to ws3 Workflows
  • Limitations and Modelling Risks
  • Worked Interpretation Exercise
  • Exercises
  • Further Reading
• Chapter 17: Advanced Spatial Modeling
  • Learning Objectives
  • Introduction
  • Spatial Constraints Overview
  • Implementing Adjacency Constraints
  • Contiguous Area Requirements
  • Raster-Based Spatial Analysis
  • Case Study: Adjacency Constraints in TSA 24
  • Summary
  • Exercises
  • Related Resources
• Chapter 18: Carbon Accounting in Detail
  • Learning Objectives
  • Introduction
  • Forest Carbon Pools
  • Carbon Stock Estimation
  • Carbon Fluxes
  • Carbon Accounting with ws3
  • FEMIC Integration
  • Carbon Market Applications
  • Case Study: Carbon-Neutral Forest Management
  • Summary
  • Exercises
  • Related Resources

Chapter Structure

Every chapter follows the same structure:

• Learning Objectives — what you will be able to do after reading.

• Key Concepts — the core ideas, with definitions and diagrams.

• How It Works in ws3 — how the concept maps to the software.

• Worked Example — a step-by-step walkthrough with ws3 code.

• Summary — a concise recap of the main points.

• Exercises — problems to test your understanding.

Prerequisites for This Textbook

You should be comfortable with:

• Basic algebra and statistics (means, standard deviations, simple equations).

• Reading Python code (you do not need to be an expert programmer).

• A general interest in how forests are managed over time.

No prior experience with forest modelling or wood supply simulation is required. The textbook builds from first principles.