Model bundle structure

Applies to SWATGenX engine extensions · Updated August 2026

build_manifest.json, provenance.json, pfas_data/ and streamflow_data/ sidecars, plus the directory tree and portability rules of a SWAT+ bundle.

Packages are standard SWAT+ projects assembled by the hosted QSWAT+ 4.0.3 → SWAT+ Editor 4.0.1 pipeline from NHDPlus HR hydrography and national soils, land cover, terrain, and climate inputs. File counts and size scale with watershed size.

SWATGenX_v1/
├── SWATGenX_v1.sqlite          QGIS project database
├── swatplus_datasets.sqlite    shipped datasets DB (portable reference_db)
├── build_manifest.json         what was built, from which inputs
├── provenance.json             data lineage for every layer
├── Watershed/
│   ├── Rasters/                clipped DEM, land use, soils
│   ├── Shapes/                 subbasins, HRUs, rivers, aquifers
│   └── Text/
├── Scenarios/Default/
│   ├── TxtInOut/               SWAT+ text inputs (+ NetCDF when enabled)
│   │   ├── file.cio  codes.bsn  time.sim
│   │   ├── hru.hru   channel.cha  aquifer.aqu
│   │   ├── soils.sol landuse.lum  field.fld
│   │   └── … weather + print/output streams
│   └── Results/                shapefiles + output SQLite
└── streamflow_data/            observed USGS record (when gage-anchored)

Portability

New builds copy swatplus_datasets.sqlite into the model directory and set project_config.reference_db / project_name to relative paths so QGIS / Editor / Toolbox open the project on the user’s machine.
wgn_db stays absolute on purpose — weather-generator DB (~334 MB) comes from the user’s SWAT+ install rather than every ZIP.
build_manifest.json and provenance.json record inputs and lineage for audit.

Opening and running

Unzip keeping the tree intact. Open the project .sqlite in QGIS+QSWAT+ 4.0.3 or SWAT+ Editor 4.0.1. Run from Scenarios/Default/TxtInOut with a SWAT+ executable.
Coupled sites add a sibling MODFLOW_250m tree — see the MODFLOW coupling chapter. PFAS engine inputs (pfas.dat / pfas_hru.ini) are not auto-written by a normal build — see the PFAS fate and transport chapter.
Sidecar metadata (build_manifest.json, provenance.json, pfas_data/, streamflow_data/) is documented under Sidecar metadata below.
Older absolute reference_db paths: prefer a freshly generated bundle.

Compilation is not required to run a bundle. Parallel OpenMP modes are optional — see Engine I/O and run modes.

Sidecar metadata

Non-model metadata shipped inside a package: build_manifest.json and provenance.json at the model root, plus the pfas_data/ and streamflow_data/ observation folders.

Sidecars record what was built and from which inputs, and carry observation data for comparison. None of them are read by the SWAT+ engine.

`build_manifest.json`

Written at the end of a hosted build. Top-level keys:

Key	Description
schema_version	Manifest schema id (currently "1.1")
swatgenx_core_version / git_commit	Science-core version constant and short repo commit
engine_version	Deployed SWAT+ engine label
station_assignment_version / delineation_version / modflow_builder_version / calibration_stack_version / editor_version	Component version labels for the pipeline stages
data_vintages	Input archive labels: nhdplus_hr, prism, gssurgo, nsrdb
created_at / backfilled	Build UTC timestamp; whether the manifest was backfilled rather than written live
model_path / username / vpuid / level / site / model_name	Identity of the built model
config_schema_version / build_config / config_fingerprint / build_id	Normalized build configuration (delineation, lakes, resolutions, land use, couplings, add-ons), its hash, and the content-addressed build identity

`provenance.json`

Written with the package (plus a human-readable README.md). Top-level keys:

Key	Description
schema_version / generated_utc	Provenance schema id ("1.0") and write timestamp
model	Identity: vpuid, level, site_no, model_name, model_path
swatgenx	Code version: git_commit, git_describe, dirty flag
delineation	Delineation method + QSWAT+ options (thresholds, lakes, DEM flags)
data_sources	Nested product citations: hydrography, elevation, land_use, soils, climate, watershed_boundary
notes	Human note (e.g. VPU-varying NHDPlus HR vintages)

pfas_data/ — PFAS observation snap

Written when a build or add-on requests PFAS observation extraction. Observations for comparison — never read as engine input.

File	Description
pfas_stations_assignment.csv	Stations in the watershed: site_id, name, lat, lon, state, site_type, huc8, huc12, source_id + snapped channel, distance_m + n_analytes, n_water_analytes, max_water_ngL
{channel}_{site_id}.csv	Per-station observation summary: site_id, media, analyte, n_samples, n_detect, max_value, latest_value, latest_date, band, source_id, retrieved_at
stations.shp	EPSG:4326 station points with channel + distance_m attributes
README.md	Assignment table (site_id, name, channel, distance_m, huc12, source, n_analytes, max_water)

streamflow_data/ — observed USGS record

Written when the model is gage-anchored; consumed by the calibration stack. Full schema in the Calibration artifacts chapter.