Build compound flood models on desktop or HPC.

Windows and macOS use the same AutoCF interface and scientific workflow. Installation differs by platform. HPC uses a command-line package for Apptainer or Singularity.

Choose where to begin

Controls that stay available

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.

Settings controls on both desktops

Command-line installer

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

Install-AutoCF.cmd

Install on macOS

The macOS 1.0.0 package supports Apple Silicon only. Docker Desktop supplies the Linux container engine used by AutoCF.

1. Verify the download

In Terminal, calculate the checksum of the published DMG. Stop and obtain a fresh copy if it differs.

shasum -a 256 "$HOME/Downloads/AutoCF-1.0.0-macOS-arm64.dmg"

Expected SHA-256:

3858cebd06d18139fbe7ff67ace54d48f1cd2bde42d2be263ac9bc0ee76e3c5e

2. Install Docker Desktop

1. Download Docker Desktop for Apple Silicon.Use the official Docker installation page and review its license terms for your organization.
2. Copy Docker to Applications.Open Docker.dmg, drag Docker into Applications, then start the installed copy.
3. Complete first-run setup.Accept the agreement, choose recommended settings, and enter the Mac password if requested.
4. Wait for Engine running.An empty Containers page is normal. Keep Docker Desktop running whenever AutoCF builds, simulates, evaluates, or performs attribution.

3. Install and approve AutoCF

1. Open the verified AutoCF DMG.Drag AutoCF.app into Applications and wait for the copy to finish.
2. Eject the disk image.Run only the installed copy from Applications; never keep projects inside the mounted DMG.
3. Try the first launch.If macOS blocks the app, select Done or Cancel.
4. Approve AutoCF.Open Apple menu → System Settings → Privacy & Security, find the blocked-app message, select Open Anyway, authenticate, and confirm Open. Apple normally keeps this option available for about one hour after the blocked launch.

4. Install the managed runtime

1. Confirm Docker is ready.Wait for Engine running before opening AutoCF.
2. Open AutoCF Settings.Set Execution backend to Docker / Podman and SFINCS compute to Automatic or CPU. Automatic resolves to the validated CPU runtime on this macOS package.
3. Select Check system status.If the engine is not running, return to Docker Desktop and wait.
4. Select Install / repair runtime.Keep AutoCF, Docker Desktop, and the internet connection open. The first build can take several minutes and use several gigabytes.
5. Wait for success.Jobs and Logs must end with Completed successfully or AutoCF runtime installation: PASS.
6. Check once more.Confirm Container engine: docker, AutoCF runtime: INSTALLED, and SFINCS backend: CPU container.

The SFINCS software panel can record a source or existing folder, but this is optional. Normal Build & Run operations use the executable inside the managed Docker runtime.

Terminal checks

uname -m
docker version
docker info
"/Applications/Docker.app/Contents/Resources/bin/docker" info
"/Applications/Docker.app/Contents/Resources/bin/docker" image inspect autocf/runtime:2

uname -m must report arm64. A JSON response from image inspect means the AutoCF runtime image exists.

Updating AutoCF

1. Protect projects.Keep project folders and YAML files under Documents or another user-owned location, then quit AutoCF.
2. Verify and replace.Check the replacement DMG, copy the new app over AutoCF in Applications, and approve it again if macOS asks.
3. Verify the runtime.Start Docker Desktop, run Check system status, then run Install / repair runtime once for the new package.

Replacing AutoCF.app does not delete projects stored outside Applications.

Shared desktop GUI

Windows and macOS use the same menus, pages, controls, YAML schema, and output layout. The remainder of this manual applies to both platforms.

Your first model

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.

Every Project control

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.

Study area

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

Domain and map controls

Draw AOI

Ocean boundary and forcing points

Evaluation observations

Draft actions

Terrain

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

Every Terrain control

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.

NBS & adaptations

Forcing

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

Atmosphere

Ocean

Rivers

Prepared-layer viewer

Displayed layer chooses rainfall, wind, pressure, ocean, or river previews. The left/right time buttons step frames, the time field shows the timestamp, and Opacity changes only the overlay display.

SFINCS model

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

Basic tab

Advanced sfincs.inp tab

Generated sfincs.inp tab

This read-only preview updates from Basic and Advanced values plus event dates. HydroMT adds resolved file paths during build.

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 field appears only when input is requested. Cancel terminates the active AutoCF job and its managed backend processes.

Evaluation

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

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.

Status tab

Setup tab

Simulations and report tabs

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

The factorial is NONE, C, P, R, CP, CR, PR, and CPR, where C is coastal (ocean + wind + pressure), P is precipitation, and R is river discharge. The completed parent run supplies CPR, so only seven additional simulations are prepared.

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 GUI is recommended on Windows and macOS. YAML remains the portable model recipe; the Windows launcher provides direct command-line operations.

Windows launcher

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

Normal macOS operation does not require Terminal commands. For cluster execution, use the separate HPC guide.

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.

Controls

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