Build coastal flood models with a guided workflow.

AutoCF Desktop helps you prepare, run, evaluate, and interpret SFINCS compound-flood models without assembling a scientific software environment by hand.

Choose where to begin

Install on Windows

Managed WSL2 is the recommended route. AutoCF installs and verifies the bundled scientific runtime from its Settings page.

Recommended installation

1. Copy the complete package to a local drive.Keep all files together and launch AutoCF-Desktop.exe.
2. Open AutoCF Settings.Select Managed WSL2 under Execution backend. Docker Desktop is an alternative when already installed and running.
3. Select Install / repair runtime.Approve the Windows permission prompt.
4. Restart only if AutoCF requests it.Reopen AutoCF and select Install / repair runtime again.
5. Select Check system status.Do not run a model until AutoCF reports that the runtime is installed.

Compute selection

Command-line installer

Double-click the bundled installer; if it enables WSL2, restart and run it again.

Install-AutoCF.cmd

Deploy AutoCF

Run AutoCF on a desktop workstation or a shared HPC cluster. Choose a target to see its deployment commands.

# a folder for your projects and finished runs
mkdir -p ~/AutoCF-Projects

docker run -d --platform linux/amd64 -p 8601:8601 \
  -v ~/AutoCF-Projects:/work \
  -v ~/.autocf:/root/.autocf \
  autocf/autocf:1.0

# then open http://localhost:8601

# once only: install WSL2, then reopen the terminal
wsl --install

# a folder for your projects and finished runs
mkdir "$env:USERPROFILE\AutoCF-Projects"

docker run -d -p 8601:8601 `
  -v "$env:USERPROFILE\AutoCF-Projects:/work" `
  autocf/autocf:1.0

# then open http://localhost:8601

# once only: pull the image onto shared storage
apptainer pull autocf_1.0.sif docker://autocf/autocf:1.0

# the simulation, on one A100
sbatch --job-name=autocf-run --partition=gpu \
  --gres=gpu:a100:1 --cpus-per-task=8 --mem=64G --time=04:00:00 \
  --wrap "apptainer exec --nv autocf_1.0.sif autocf run config.yaml"

# --nv passes the GPU through to the container

# build, evaluation, attribution and report need no GPU
sbatch --job-name=autocf-build --partition=cpu \
  --cpus-per-task=16 --mem=32G --time=01:00:00 \
  --wrap "apptainer exec autocf_1.0.sif autocf build config.yaml"

# or interactively, once the run has finished
apptainer exec autocf_1.0.sif autocf evaluate config.yaml
apptainer exec autocf_1.0.sif autocf attribute config.yaml
apptainer exec autocf_1.0.sif autocf report config.yaml

Your first model

AutoCF lets you save an incomplete draft. Full scientific validation is enforced before Build & Run.

1. SettingsChoose working directory, backend, compute mode, and CPU threads.
2. Project → Start new modelThe guided setup opens Event & Time first.
3. Event & TimeLoad IBTrACS and select Use selected event & continue, or enter dates manually.
4. Study AreaUpload/draw a polygon or select USGS watersheds; add forcing and observation points; save and continue.
5. TerrainChoose Source 1, optional gap fill, and verify vertical datums.
6. Roughness & InfiltrationSelect land cover, Manning mapping, and optional infiltration/adaptation polygons.
7. ForcingPrepare applicable rainfall, wind, pressure, ocean, and river inputs.
8. SFINCS ModelChoose regular or subgrid hydraulics and review the input preview.
9. Validate, Build & RunSave YAML, resolve validation issues, build, then simulate.
10. Evaluation and ResultsCreate flood-depth products, compare observations, and inspect outputs.

Project & workspace

A portable project folder holds its YAML recipe, study-area GeoJSON, runs, and cache.

Workspace layout

<working directory>/
  Ida_2021/
    Ida_2021.yml
    Ida_2021_study_area.geojson
    runs/
    cache/

Relative paths such as ./runs and ./cache resolve beside the YAML, making projects movable. Imported projects are not automatically migrated or renamed.

Event & time

Choose the event and simulation window before defining a new domain.

1. Load IBTrACS.The first NOAA catalog download needs internet and is cached.
2. Filter and preview.Use basin, coast, year, and storm. Previewing does not change the configuration.
3. Apply deliberately.Use selected event & continue applies the track/dates, creates the workspace, and opens Study Area.

You can enter the event name and UTC dates manually. Include appropriate pre-event spin-up; the correct duration is site dependent.

Study area

Define one valid polygon domain, its grid, forcing locations, and optional evaluation observations.

Build the domain

Grid cell size

Options are 30, 50, 100, 200, 500, and 1000 m. 200 m is a starting point, not a universal value. Smaller cells rapidly increase memory and runtime.

• Draw the ocean boundary and select water-level stations where applicable.
• Find USGS gauges or place river source points.
• Add water-level gauges/high-water marks for evaluation.
• Select Save study area & continue.

Terrain

Source 1 is authoritative and defines the model target datum. Source 2 may fill gaps and require conversion.

Datum engine

Review vertical_datum_provenance.json for engine, fallback, offset, samples, and spread. Terrain also writes topobathy_source_provenance.json. Enter acquisition dates when known; a product edition year is not necessarily an acquisition date.

Roughness & infiltration

Translate land cover into resistance, optionally represent infiltration, and define adaptation polygons.

1. Select land cover.ESA WorldCover is a 10 m global option; Annual NLCD supplies 30 m U.S. data.
2. Choose Manning mapping.Start with AutoCF defaults or document a calibrated class mapping.
3. Configure infiltration.Curve Number inputs can use GCN250 or NLCD × SSURGO. Values remain site dependent.
4. Add interventions if needed.Draw nature-based/adaptation polygons with scenario properties.
5. Prepare roughness / infiltration.Inspect prepared layers before continuing.

Forcing

Prepare the atmospheric, coastal, and river conditions that drive the event.

Select Prepare atmosphere forcing. Rainfall, wind, and pressure previews appear automatically when available. Remote acquisition needs internet.

SFINCS model

Choose the hydraulic representation and review common/advanced SFINCS controls before building.

Build & run

Build prepares inputs and creates the SFINCS project. Run executes it through the selected validated backend.

Pre-run checklist

• Save YAML changes.
• Open Validation in Jobs and Logs and select Validate configuration.
• Resolve domain, date, source, datum, and dependency issues.
• Confirm System status is ready.
• Keep internet available while remote inputs download.

Follow progress in Jobs and Logs. The response control appears only when needed. Cancel terminates the full Windows process tree, including WSL children.

Evaluation

Generate maximum flood-depth products and compare modeled water levels with gauges or high-water marks.

• Create a flood-depth map and GeoTIFF.
• Create gauge plots/error metrics when observations exist.
• Set time-matching tolerance and map color maximum deliberately.
• Run evaluation, then inspect the Plots tab.

Attribution & analysis

Separate coastal, precipitation, and river contributions with eight factorial scenarios, then connect hazard to exposure, duration, and equity.

1. StatusConfirm active YAML, parent result, and recommended next action.
2. SetupSelect buildings, population, CDC SVI, duration, depth/persistence thresholds; prepare seven counterfactual folders.
3. SimulationsRun missing scenarios. Completed outputs are reused unless recreation is explicitly selected.
4. ReportAfter eight outputs exist, generate impacts, Shapley attribution, duration, interactions, amplification, equity, and DIS.

Interpretation essentials

Absolute impact

Flooded area, buildings, or population from the full scenario depth.

Shapley attribution

Order-independent allocation of FULL-minus-NONE among interacting drivers; negative values are retained.

Flood duration

Time above thresholds, including area-hours, building-hours, and persistence.

Driver Impact Shift

100 × [impact Shapley share − flooded-area Shapley share]. Positive means consequence-heavy.

CDC SVI burden

U.S. tract vulnerability overlay; outside the U.S. it is not applicable.

Single-run tool

Use Analyze the parent run only for one completed flood map without driver attribution. Overture provides buildings/roads; WorldPop provides population.

Results & files

The Results page shows viewable products; the run folder preserves the full technical record.

Results lists PNG/JPG, CSV, and JSON below results/, grouping matching products into Figure, Table, and Overview tabs. NetCDF, GeoTIFF, GeoParquet, caches, logs, and scenario workspaces stay on disk.

<run>/
  data/
    model/main/                  # SFINCS workspace
    forcing/{netcdf,tables}/
    terrain/rasters/
    surface/{rasters,tables}/
    geospatial/vectors/
    validation/water_level/
    attribution/{scenarios,exposure}/
    previews/{terrain,surface,forcing}/
  results/
    simulation/{figures,tables,reports}/
    evaluation/{figures,tables,reports,rasters}/
    attribution/{figures,tables,reports,rasters}/
    exposure/{figures,tables,reports,vectors}/
  metadata/{run_state.json,artifact_catalog.json}
  logs/{build,simulation,analysis}/
  work/hydromt/

YAML & command line

The desktop is recommended; YAML and CLI support reproducibility and advanced workflows.

Windows commands

AutoCF.cmd examples\sfincs_agent_subgrid_config.yml build
AutoCF.cmd examples\sfincs_agent_subgrid_config.yml run
AutoCF.cmd examples\sfincs_agent_subgrid_config.yml evaluate
AutoCF.cmd examples\sfincs_agent_subgrid_config.yml impact

Portable paths

project:
  layout_version: 2
  name: ida_2021
  output_dir: ./runs
  cache_dir: ./cache
  overwrite: false

Impact section

impact:
  enabled: false
  flood_depth_thresholds_m: [0.15, 0.3, 0.6, 1.0, 2.0]
  analysis_resolution_m: 30.0
  buildings: {enabled: true, source: overture_maps}
  roads: {enabled: true, source: overture_maps}
  population:
    enabled: true
    source: worldpop_api_v2
    year: simulation
    resolution: 100m

Riva assistant

Riva answers workflow questions, searches installed documentation, and interprets saved results without asking a language model to calculate scientific values.

Ask about

• The current AutoCF page and next step.
• SFINCS/HydroMT-SFINCS terminology.
• RMSE, bias, Shapley, DIS, SVI, and duration.
• Leading drivers and gauge performance in the active model.

Privacy and local AI

Curated answers and deterministic result interpretation work without Qwen. Optional Install local AI downloads Qwen3.5-0.8B Q4_0 (563 MB) and llama.cpp locally. It needs no API key, is used only to synthesize selected documentation, and unloads during scientific jobs. Riva does not edit YAML or launch simulations.

Troubleshooting

Start with the visible status and Jobs and Logs. Preserve the exact error and stage when requesting help.

Glossary

AOI

Area of interest—the polygon model domain.

Topobathy

Continuous land elevation and underwater bathymetry.

Vertical datum

Reference surface for elevations or water levels.

Forcing

Rainfall, wind, pressure, coastal water levels, or river flow driving the model.

SFINCS

Deltares’ Super-Fast INundation of CoastS model.

Subgrid

Fine terrain information within coarser regular computational cells.

Counterfactual

Scenario omitting drivers to estimate contribution.

Shapley value

Order-independent attribution among interacting drivers.

DIS

How a driver’s consequence share differs from its flooded-area share.

CDC SVI

U.S. census-tract Social Vulnerability Index.

Ready to model?

Return to the first-model path or search for a topic.

Start tutorial