Regional Lab Profile#

regional_lab is the regional catalog profile of testbed. It expands one or more recipes over a site catalog and records which cases were planned, skipped, completed, or failed.

Regional-lab files use [workflow].mode = "testbed" with [testbed].profile = "regional_lab".

Use it when the question is: “How do I run the same modelling recipe across many sites consistently?”

Functional Role#

The regional-lab profile is about campaign orchestration, not about one solver method. A regional-lab recipe can point to simulation or comparison launchers. The accepted launcher names are simulation and comparison.

Architecturally, regional_lab is not a separate campaign engine. It is a profile that keeps regional concepts such as sites, clusters, maturity/status, coverage gaps, and recipes, while delegating execution to the same child-runner contract used by testbed. Internally, the catalog-loading primitives are shared with testbed so CSV/JSONL parsing, required fields, path fields, tags, and basic row filters follow one contract. A planned site x recipe case is also projected onto the testbed case vocabulary: case_id remains the executable case identifier, recipe.id becomes the case axis, and recipe.launcher becomes the per-case runner.

The launcher performs this type of expansion:

site catalog
    -> global selection filters
    -> optional cluster rules
    -> recipe selection filters
    -> case plan
    -> optional config-path validation
    -> execution or dry planning
    -> report and manifest

It is appropriate for:

multi-basin campaigns;
repeated deployment across clusters or regions;
separating site inventory from run recipes;
resuming partially completed campaigns;
documenting what was skipped and why.

Typical Command#

hmp run path/to/regional_lab.toml

Public examples are currently thinner than for overview and simulation. The runtime contract is nevertheless explicit: the profile expects a top-level [regional_lab] section.

Minimal Shape#

[workflow]

mode = "testbed"

[testbed]
profile = "regional_lab"

[regional_lab]
lab_id = "headwater_campaign"
output_root = "outputs/headwater_campaign"
execute = false
continue_on_error = true
validate_config_paths = true
resume_from_report = true
skip_completed_cases = true

[regional_lab.catalog]
path = "site_catalog.csv"
format = "csv"
site_id_field = "site_id"
site_label_field = "site_label"
cluster_id_field = "cluster_id"
region_field = "region_id"
enabled_field = "enabled"
x_field = "x"
y_field = "y"
area_km2_field = "area_km2"
tags_field = "tags"

[regional_lab.selection]
regions = ["brittany"]
tags = ["headwater"]
limit = 10

[[regional_lab.recipe]]
id = "mf6_reference"
label = "MODFLOW 6 reference run"
launcher = "simulation"
config_path_template = "sites/{site_id}/run_mf6_reference.toml"
enabled = true

Important Parameters#

Section / field	Role	Practical guidance
`workflow`	Selects the campaign entry point.	Must be `"testbed"` with `[testbed].profile = "regional_lab"`.
`[regional_lab].lab_id`	Names the campaign.	Use a stable identifier because reports and output folders are keyed by it.
`output_root`	Stores campaign reports and manifests.	Keep it outside individual site folders.
`execute`	Controls dry planning versus execution.	Use `false` first to validate expansion before launching many runs.
`continue_on_error`	Decides whether one failed site stops the campaign.	Use `true` for large campaigns where later sites should still run.
`validate_config_paths`	Checks that recipe-expanded config files exist.	Keep enabled unless generating configs in a separate step.
`resume_from_report`	Reuses previous campaign status.	Useful for interrupted regional campaigns.
`skip_completed_cases`	Avoids rerunning successful cases.	Keep enabled for resumable campaign execution.
`[regional_lab.catalog]`	Describes the site inventory table.	Map HydroModPy’s expected concepts to your CSV or JSONL field names.
`[regional_lab.selection]`	Filters the global site set.	Use regions, clusters, tags, statuses, maturity levels, or `limit`.
`[[regional_lab.recipe]]`	Declares one operation expanded over selected sites.	`launcher` is currently `simulation` or `comparison`.

Catalog Mental Model#

The catalog is not a model config. It is an inventory:

site_id,site_label,region_id,cluster_id,enabled,x,y,area_km2,tags
nancon,Nancon,brittany,headwater,true,127348,6835802,10,headwater;demo
vire,Vire,normandy,regional,true,400866,6923974,100,regional;mf6

Recipes then turn rows into concrete config paths:

config_path_template = "sites/{site_id}/run_mf6_reference.toml"

For site_id = "nancon", this becomes:

sites/nancon/run_mf6_reference.toml

Planning First#

For a new campaign, start with:

[regional_lab]
execute = false
validate_config_paths = true

This produces a plan without launching expensive simulations. Only switch execute to true once the selected sites, recipes, and config paths are correct.

Outputs To Inspect#

Inspect the campaign outputs in this order:

planned case list;
skipped case list and skip reasons;
execution report;
per-recipe status counts;
failed case messages;
links to child simulation or comparison outputs.