GCBM Assistant

GCBM Assistant is a desktop application for configuring, running, compiling, and analyzing Generic Carbon Budget Model (GCBM) workflows.

This README is intentionally practical: a new user should be able to run the full flow from here. The full documentation site is:

• GCBM Assistant Docs

What You Can Do

• Configure simulation inputs from project folders and shapefiles.
• Run simulations with validation and live logs.
• Compile outputs into analysis-ready databases and optional spatial TIFFs.
• Analyze results with charts, spatial playback, and report views.

Table of Contents

1. Requirements
2. Install and Run
3. Windows Installer
4. End-to-End Workflow
5. Expected Artifacts
6. Documentation Map
7. Release and CI/CD
8. Troubleshooting

Requirements

• Python >=3.10 for source installs
• Windows is the primary installer packaging target (.exe)
• A prepared GCBM workspace (for example gcbm_training)

Install and Run

Source install

cd gcbm_assistant
uv pip install -e .
gcbm-assistant

Alternative launch:

python -m gcbm_assistant.app

Windows Installer

For non-technical users, use the installer build:

1. Download latest GCBM_Assistant_Setup_*.exe from Releases.
2. Run the installer and complete setup.
3. Launch using desktop shortcut.

Installer build assets are in installer/ and release automation is in .github/workflows/windows-installer.yml.

End-to-End Workflow

1) Simulation

1. Open Simulation.
2. Select project directory and confirm discovered input files.
3. Map required columns (age, classifiers, temperature source).
4. Validate configuration, then run simulation.

Playbook: Simulation playbook

2) Compilation

1. Open Compile.
2. Select simulation project output location.
3. Set compiled database output name.
4. Enable spatial TIFF output if map analysis is needed.
5. Run compilation and verify success.

Playbook: Compilation playbook

3) Visualization

1. Open Visualize.
2. Load compiled .db.
3. Add charts and apply classifier filters.
4. Optionally load spatial TIFF folder for map mode and year playback.
5. Export charts or PDF outputs as needed.

Playbook: Visualization playbook

Expected Artifacts

After successful workflow execution, you should see:

• Simulation stage:
  • gcbm_project/output/
• Compilation stage:
  • gcbm_project/processed_output/compiled_results.db (name may vary)
  • gcbm_project/processed_output/config/
  • gcbm_project/processed_output/spatial/*.tif (if enabled)
• Visualization stage:
  • exported chart/report files if requested by user

Reference: Data and output artifacts

Documentation Map

• Docs home
• Quickstart
• Simulation playbook
• Compilation playbook
• Visualization playbook
• Visualization feature reference
• Troubleshooting matrix
• Known issues
• Support matrix
• Release policy

Release and CI/CD

• Installer workflow: .github/workflows/windows-installer.yml
• Docs quality workflow (PR): .github/workflows/docs-quality.yml
• Docs pages deploy workflow (main): .github/workflows/docs-pages.yml

For private cross-repo checkout in installer builds, configure:

• CROSS_REPO_READ_TOKEN

Troubleshooting

Start with:

• Troubleshooting matrix

Common quick checks:

• Simulation fails: verify paths and required column mapping.
• Compilation succeeds but no charts: verify correct compiled DB.
• Map view blank: ensure spatial TIFF outputs exist and correct folder is loaded.
• CI checkout failures: verify token scope and org approval.