scenario.json Reference

The scenario.json file is the main configuration for a simulation run. It is generated by the Hydrata server when building a scenario package, and it can also be written by hand for standalone use.

Input files are named by these fields and resolved relative to the package's inputs/ directory, so a field holds a file name rather than a path.

Full field reference

The Required column is what the validator itself insists on. Only three fields have no default, though a model that actually runs needs an elevation and at least one source of water.

Field	Type	Required	Description
epsg	string	Yes	Coordinate reference system, for example "EPSG:28355"
boundary	string	Yes	File name of the boundary GeoJSON
duration	integer	Yes	Simulation duration in seconds
format_version	string	No	Wire-format version. Must be "1.0" if present; any other value is rejected.
id	integer	No	Scenario id. Defaults to 0.
run_id	integer	No	Run id for this execution. Defaults to 0.
project	integer	No	Project id. Defaults to 0.
name	string	No	Human-readable scenario name
description	string	No	Optional description
control_server	string	No	Base URL of the Hydrata server, for progress reporting
elevation	string	No	File name of the elevation raster
friction	string	No	File name of the friction polygon GeoJSON
friction_raster	string	No	File name of a Manning's-n raster, used instead of or alongside friction polygons
inflow	string	No	File name of the inflow GeoJSON (LineString hydrographs)
rainfall	string	No	File name of the rainfall GeoJSON (polygons)
structure	string	No	File name of the structure GeoJSON
mesh_region	string	No	File name of the mesh region GeoJSON
breakline	string	No	File name of the breakline GeoJSON. Dormant: nothing creates breaklines today.
catchment	string	No	File name of the catchment GeoJSON
nodes	string	No	File name of the network nodes GeoJSON
links	string	No	File name of the network links GeoJSON
hydrology_status	string	No	Status of hydrology pre-processing
resolution	number	No	Base mesh triangle edge length in metres
max_rmse_tolerance	number	No	Retained tolerance field. Defaults to 1.
model_start	string	No	Simulation start time, ISO 8601. Hydrata derives it from the earliest timestamp across the run's series.
store_mesh	boolean	No	Write the generated mesh out alongside the results. Defaults to false.
default_near_spacing	number	No	Fallback near-spacing in metres for breakline grading. Defaults to 2.0.
schema_version	integer	No	Cross-tool manifest marker, emitted as 1. Not read by the solver.
compute_manifest	object	No	Cross-tool compute manifest block, described below. Not read by the solver.

Fields the server adds

friction_raster, schema_version and compute_manifest are written by Hydrata but are not declared on the validated config model. They survive validation because the model allows extra keys, and the solver ignores them. compute_manifest restates the run's identity and parameters in the shape Hydrata's other compute tools use:

"compute_manifest": {
    "schema_version": 1,
    "tool": "anuga",
    "identity": {"scenario_id": 1, "run_id": 7, "project_id": 42},
    "params": {"epsg": "EPSG:28355", "duration": 7200, "resolution": 10,
               "model_start": "2024-01-01T00:00:00Z"},
    "inputs": [{"ref_type": "package_relpath", "path": "package.zip"}]
}

Retired fields

An older mesh-simplification flag was removed from the platform, along with the adaptive mesher it selected. A package that still carries the key is accepted and ignored rather than rejected, because extra keys are allowed, so an archived package from before the change still runs.

Example

{
    "format_version": "1.0",
    "id": 1,
    "run_id": 7,
    "project": 42,
    "epsg": "EPSG:28355",
    "name": "100-year ARI flood",
    "description": "Design storm event",
    "control_server": "https://hydrata.com/",
    "elevation": "dem.tif",
    "boundary": "boundary.geojson",
    "friction": "friction.geojson",
    "inflow": "inflow.geojson",
    "rainfall": "rainfall.geojson",
    "structure": null,
    "mesh_region": "mesh_regions.geojson",
    "resolution": 10,
    "max_rmse_tolerance": 1,
    "model_start": "2024-01-01T00:00:00Z",
    "duration": 7200,
    "default_near_spacing": 2.0,
    "schema_version": 1
}

Validation

Validation is a Pydantic model, not a JSON Schema document. The model is ScenarioConfig in run_anuga/config.py, and loading a config validates it:

import json
from run_anuga.config import ScenarioConfig

with open("scenario.json") as f:
    config = ScenarioConfig(**json.load(f))

A missing required field or a format_version other than "1.0" raises a validation error. Unknown keys are allowed and carried through, which is what lets the server add manifest fields and lets old packages keep working.