{"id":51278924,"url":"https://github.com/matthewdwilson/flooda5","last_synced_at":"2026-06-30T00:01:46.919Z","repository":{"id":365783746,"uuid":"1196570761","full_name":"MatthewDWilson/FloodA5","owner":"MatthewDWilson","description":"A 2D surface-water flood model built on the A5 pentagonal DGGS","archived":false,"fork":false,"pushed_at":"2026-06-18T20:52:36.000Z","size":93717,"stargazers_count":1,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-06-18T22:26:06.612Z","etag":null,"topics":["a5","dggs","flood-modelling","flooding"],"latest_commit_sha":null,"homepage":"","language":"Julia","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":null,"status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/MatthewDWilson.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":null,"code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2026-03-30T20:34:40.000Z","updated_at":"2026-06-18T20:07:36.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/MatthewDWilson/FloodA5","commit_stats":null,"previous_names":["matthewdwilson/flooda5"],"tags_count":null,"template":false,"template_full_name":null,"purl":"pkg:github/MatthewDWilson/FloodA5","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/MatthewDWilson%2FFloodA5","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/MatthewDWilson%2FFloodA5/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/MatthewDWilson%2FFloodA5/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/MatthewDWilson%2FFloodA5/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/MatthewDWilson","download_url":"https://codeload.github.com/MatthewDWilson/FloodA5/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/MatthewDWilson%2FFloodA5/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":34947088,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-05-26T15:22:16.424Z","status":"online","status_checked_at":"2026-06-29T02:00:05.398Z","response_time":58,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["a5","dggs","flood-modelling","flooding"],"created_at":"2026-06-30T00:01:45.649Z","updated_at":"2026-06-30T00:01:46.903Z","avatar_url":"https://github.com/MatthewDWilson.png","language":"Julia","funding_links":[],"categories":[],"sub_categories":[],"readme":"![Status: In Development](https://img.shields.io/badge/Status-In_Development-green)\n![Status: In Development](https://img.shields.io/badge/Status-Experimental-red)\n![Julia 1.12+](https://img.shields.io/badge/Julia-1.12%2B-blue)\n![License: Apache 2.0](https://img.shields.io/badge/License-Apache_2.0-blue)\n\n# FloodA5\n\nA 2D surface-water flood model built on the [A5 pentagonal Discrete Global Grid System\n(DGGS)](https://a5geo.org). FloodA5 discretises the landscape into equal-area pentagons,\nroutes water between them using the Bates et al. (2010) inertial shallow-water\nformulation, and resolves sub-cell terrain variability through pre-computed hypsometric\nstorage tables.\n\nNote: this model is still in an experimental phase and should not be used in production. \n\nKey characteristics:\n\n- **Uniform five-connectivity** — every interior cell has exactly five edge-sharing neighbours, \n  a regular topological structure for hydrodynamic routing.\n- **Sub-Grid Sampling (SGS)** — hypsometric volume curves built from LiDAR allow\n  partial wetting of cells and accurate routing through channels narrower than a cell.\n- **Geographic coordinates throughout** — mesh generation, geometry, and output all\n  use WGS 84 (EPSG:4326); no projected CRS selection required.\n- **LISFLOOD-FP compatible inputs** — reads `.bci`/`.bdy` boundary condition files\n  for cross-portability with existing LISFLOOD-FP workflows.\n- **Two visualisation backends** — a CesiumJS web viewer and a native GLMakie desktop\n  window, both updating live during simulation.\n\n---\n\n## Documentation\n\n| Document | Contents |\n|---|---|\n| [docs/METHODS.md](docs/METHODS.md) | Physics: A5 grid, SGS, Bates formulation, R-A flux, boundary conditions |\n| [docs/USER_GUIDE.md](docs/USER_GUIDE.md) | Full CLI reference, workflow walkthrough, worked examples |\n| [docs/DATA_FORMATS.md](docs/DATA_FORMATS.md) | GeoParquet schema, HDF5 layout, `.bci`/`.bdy` format |\n| [docs/ARCHITECTURE.md](docs/ARCHITECTURE.md) | Module map, extension points, developer orientation |\n| [docs/TEST_CASES.md](docs/TEST_CASES.md) | Square domain and Carlisle 2005 flood test cases |\n\n---\n\n## Quick Start\n\n### 1. Prerequisites\n\n**Julia 1.12 or later** — download from [julialang.org](https://julialang.org/downloads/).\n\n**Python 3.10 or later** with `pya5` and supporting packages — installed automatically\nby the setup script (see below).\n\nOptional: an NVIDIA CUDA GPU accelerates the point-in-polygon DEM sampling step at\nhigh resolutions.\n\n### 2. Install\n\n```bash\ngit clone https://github.com/MatthewDWilson/FloodA5.git\ncd FloodA5\njulia setup.jl\n```\n\n`setup.jl` activates the Julia project environment, installs all dependencies,\ninstalls Python packages into PyCall's bundled Python, runs a smoke test of the\nPython bridge, and checks for GPU availability. See [docs/USER_GUIDE.md](docs/USER_GUIDE.md)\nfor platform-specific notes.\n\n### 3. Run\n\n```bash\n# Generate a mesh, sample a DEM, and build SGS tables (save for reuse)\njulia --threads auto FloodModel.jl \\\n    --meshgen examples/example_aoi.geojson --meshres 14 \\\n    --dem your_dem.tif --meshout mesh.parquet --mesh-only\n\n# Run a 1-hour simulation with uniform 30 mm/hr rainfall\njulia --threads auto FloodModel.jl \\\n    --meshload mesh.parquet \\\n    --rainfall 30 --sim-duration 3600 \\\n    --output sim.h5 --vis makie\n```\n\n---\n\n## File Structure\n\n```\nFloodA5/\n├── FloodModel.jl              # Entry point, CLI, simulation loop\n├── setup.jl                   # One-time installation script\n├── mesh/\n│   ├── A5Grid.jl              # Julia module: mesh generation, cell API, SGS tables\n│   ├── a5_bridge.py           # Python bridge: pya5 calls, GeoParquet I/O\n│   └── a5_mesh_diagnostic.py  # Mesh diagnostic utilities\n├── surfacewater/\n│   └── flow2d.jl              # Physics kernels (Bates, Manning R-A, CFL)\n├── boundaryinputs/\n│   ├── sources.jl             # Water source types (rainfall, injection, hydrograph)\n│   ├── boundary_conditions.jl # Ghost-edge BC types and ghost edge geometry\n│   └── timeseries_io.jl       # .bdy / CSV hydrograph readers\n├── visualisation/\n│   ├── MakieVisualiser.jl     # Native desktop viewer (GLMakie)\n│   ├── VisualisationServer.jl # HTTP + WebSocket server for CesiumJS viewer\n│   ├── view_h5_output.jl      # Post-processing viewer for HDF5 output\n│   ├── visualise_mesh.jl      # Publication-quality mesh and SGS figures\n│   └── cesium/                # CesiumJS static files\n├── test/\n│   ├── carlisle/              # Carlisle 2005 flood domain and boundary files\n│   ├── square/                # Square domain test case\n│   ├── synthetic_dem/         # Synthetic DEM SGS validation suite\n│   └── *.jl                   # Unit and integration tests\n├── examples/\n│   └── example_aoi.geojson    # Example area of interest (centred at 0°N, 0°E)\n└── docs/                      # Documentation\n```\n\n---\n\n## Resolution Guide\n\nA5 cell size scales by approximately 4× with each resolution level. Choose a level\nappropriate to your domain and available DEM resolution.\n\n| Level | Approx. cell area | Cell spacing | Typical use |\n|-------|-------------------|--------------|-------------|\n| 10 | ~50 km² | ~7 km | Large catchment |\n| 12 | ~2 km² | ~1.4 km | Medium catchment |\n| 14 | ~13 ha | ~355 m | Urban / detailed |\n| 16 | ~8,000 m² | ~89 m | Small-scale urban |\n| 18 | ~500 m² | ~22 m | Fine urban / channel |\n| 20 | ~31 m² | ~5.6 m | Very high resolution |\n\nSGS provides the most benefit at resolution levels 14–16, where individual cells\ntypically span heterogeneous terrain (channels, roads, embankments). At resolution 18\nand finer, cells are small enough that the standard solver and SGS produce similar\nresults.\n\n---\n\n## Solvers\n\n**`--flow-model sgs`** (default) — Sub-Grid Sampling. WSE is derived from stored\nvolume via a pre-computed hypsometric curve. The edge flux uses a Manning hydraulic\nradius (R-A) formulation rather than the wide-channel approximation, giving\nphysically correct friction scaling in confined channels. Requires a DEM.\n\n**`--flow-model standard`** — Diffusive wave on mean cell elevation. Faster and\nuseful for initial exploration or validation without a DEM.\n\nBoth solvers use the Bates et al. (2010) inertial formulation with:\n- Wave-speed CFL timestep (Courant number 0.7)\n- Froude limiter (Fr ≤ 0.8)\n- Q-centred spatial momentum smoothing (θ = 0.9)\n- Consistent momentum state (q_prev matches actual transferred flux)\n\nSee [docs/METHODS.md](docs/METHODS.md) for full details.\n\n---\n\n## Visualisation\n\nFloodA5 includes two visualisation backends:\n\n**GLMakie** (`--vis makie`) — a native desktop window that updates live during\nsimulation. No browser, no token, no configuration required. This is the\nrecommended option.\n\n**CesiumJS** (`--vis cesium` or `--vis`) — a browser-based 3D viewer with\nGoogle Photorealistic Tiles support.\n\n\u003e **Note:** The CesiumJS viewer is currently paused in development and may have\n\u003e rough edges. `--vis makie` is recommended for all current use.\n\nBy default, domain-edge cells use a **zero-gradient (transmissive) outflow**\ncondition — water exits freely without reflection. This can be overridden:\n\n- `--closed-boundaries` — no outflow (closed walls; useful for mass-balance testing)\n- `--bc-file` — GeoJSON file assigning BC types per segment\n- `--inflow-bci` — LISFLOOD-FP `.bci` file for upstream hydrographs and BCs\n\nSee [docs/USER_GUIDE.md](docs/USER_GUIDE.md) for full details and\n[docs/TEST_CASES.md](docs/TEST_CASES.md) for a worked example using Carlisle `.bci`/`.bdy` files.\n\n---\n\n## Output\n\nSimulation output is written to HDF5 (`.h5`), with per-frame datasets for water\ndepth, stored volume, saturation fraction, and velocity. Read with Python (`h5py`,\n`xarray`) or Julia (`HDF5.jl`).\n\nPost-processing tools:\n\n```bash\n# Interactive viewer: map snapshot + cell time series\njulia --project=. visualisation/view_h5_output.jl sim.h5 --cell \u003ccell_id\u003e\n\n# Publication figures: mesh wire-frame, SGS cross-section, hypsometric curve\njulia --project=. visualisation/visualise_mesh.jl --mesh mesh.parquet \u003ccell_id\u003e\n```\n\nSee [docs/DATA_FORMATS.md](docs/DATA_FORMATS.md) for the full HDF5 schema.\n\n---\n\n## Testing\n\n```bash\n# SGS unit tests (5-cell chain, hypsometric lookups)\njulia --threads auto --project=. test/test_sgs_unit.jl\n\n# SGS synthetic DEM validation (T0–T4: mesh, routing, mass balance)\njulia --threads 1 --project=. test/synthetic_dem/test_sgs_synthetic.jl\n\n# Edge geometry tests\njulia --threads auto --project=. test/test_edge_geometry.jl\n\n# Inflow and boundary condition tests\njulia --threads auto --project=. test/test_inflow_point.jl\njulia --threads auto --project=. test/test_open_boundary.jl\n```\n\n\u003e **Note:** mesh generation must use `--threads 1` due to a thread-safety\n\u003e constraint in the Python bridge. Simulation runs are safe with any thread count.\n\n---\n\n## Platform Notes\n\nFloodA5 is developed on Windows. Linux and macOS should work but have received\nlimited testing — please open an issue if you encounter platform-specific problems.\n\nThe `.CondaPkg/` directory in the repository is a Windows-only artefact from\nthe CondaPkg.jl package manager. It can be ignored on Linux and macOS, where\n`setup.jl` installs Python packages via PyCall's bundled Conda directly.\n\n---\n\n## Licence\n\nApache 2.0 — matching the A5 DGGS library licence.\n\n---\n\n## Citation\n\nIf you use FloodA5in research, please cite the accompanying paper (in preparation).\nDetails will be added here on publication.\n\n---\n\n## References\n\n- Bates, P.D., Horritt, M.S., Fewtrell, T.J. (2010). A simple inertial formulation\n  of the shallow water equations for efficient two-dimensional flood inundation\n  modelling. *Journal of Hydrology* 387(1–2), 33–45.\n- Neal, J.C. et al. (2012). How much physical complexity is needed to model flood\n  inundation? *Hydrological Processes* 26(15), 2264–2282.\n- A5 DGGS: [a5geo.org](https://a5geo.org)\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fmatthewdwilson%2Fflooda5","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fmatthewdwilson%2Fflooda5","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fmatthewdwilson%2Fflooda5/lists"}