GranumFL 0.1.0 · User manual

Using GranumFL

GranumFL couples discrete element grains with SPH water, so that saturated soil, debris flows and floods are modelled together. You can drive it by hand in the desktop app, through the chat assistant inside the app, or from an AI agent that speaks the Model Context Protocol (MCP). The MCP server is built into the program, and we recommend Claude Opus as the agent, because it is the model with which the agent trials of the paper passed every check.

1. Install

Download the Education edition from the download section. Each zip holds the program, the tigrim chat agent, the licence and a quick start.

macOS 11 or later

Move GranumFL.app to Applications. It runs on Intel and Apple silicon. The app is not notarised yet, so the first time right-click it and choose Open, or run:

xattr -dr com.apple.quarantine /Applications/GranumFL.app

Windows 10 and 11

Unzip GranumFL-Education anywhere and run granum.exe. If SmartScreen warns, choose More info and Run anyway. Keep tigrim.exe in the same folder.

The engines

The coupled solver runs on CUDA when an NVIDIA GPU is present, which needs the NVIDIA driver and NVRTC from the CUDA toolkit (or TELLUSDEM_NVRTC set to the NVRTC library). Otherwise it runs on the CPU, which gives the same answers more slowly, so on a Mac keep water cases small and runs short while you learn. The dry DEM laboratory tests can also use wgpu (Metal on a Mac, DirectX 12 on Windows).

2. The app

The bar at the top holds File, Undo and Redo, the Input and Output workspaces, Run and the Chat assistant. The left panel has three modes, and each mode leads you through numbered steps.

Mode	What it models	Steps
Lab test	Granum's laboratory tests on dry or bonded grains: triaxial, oedometer, unconfined compression, stress path, Brazilian, deposition, angle of repose and a model footing	Particles, Specimen, Test, Solver
Model	Staged soil models with regions, rigid structures and construction phases	Materials, Geometry, Staged construction, Solver
Water + grains	Coupled DEM–SPH cases: templates in a box, or a debris flow on real terrain	Case, Water, Grains & gate, Run; on terrain: Case, Terrain, Source & path, Water, Grains, Run

The 3D view shows the model as you build it, and Output plays the run back with the grains coloured by speed and the water in blue. A water case on terrain also has a Plan map with the result maps, the places and the path.

3. A first water case

Choose Water + grains and, under Case, pick a template. Each template reproduces a published benchmark or a classroom problem, and all of them fit the Education limits.

Template	What it shows
`dam_break`	A water column collapsing on a dry floor, compared with Martin and Moyce (1952)
`hydrostatic`	Water at rest, with the pressure compared with ρgh
`settling`	One grain settling in still water, compared with the Di Felice terminal velocity
`quick_condition`	Upward seepage through a sand bed to the quick condition
`debris_flow`	A saturated debris flow released by a gate down a 25° flume
`terrain`	A debris flow on a real site from an elevation model (Section 4)

Go through Water and Grains & gate. The panel shows the estimated numbers of grains and water particles and warns about settings that will give poor results, such as a water layer thinner than two particle spacings.
Under Run, set the duration and press Run. The run goes on in the background, so you can keep working.
Open Output to play the frames back and plot the grain and water fronts, the kinetic energies, the largest water speed or, for the quick condition, the pressure drop across the bed against time.

For a class. The dam break and the settling grain each compare the program with a closed-form or laboratory result, so students can see how close a particle model gets and why the particle spacing matters.

4. A debris flow on real terrain

Start a case from the terrain template and follow the steps on the left. The plan map has tools for each step: Pan, Crop, Source, Catchment, Path, Place and Measure.

Terrain. Open a GeoTIFF or an ESRI ASCII grid, or type a latitude and longitude and press Download GLO-30 to fetch the free Copernicus tile (about 30 m cells). Crop the area with the Crop tool or by a point and a size, choose the cell size and cut the terrain. WGS 84 and UTM coordinates are read from the file.
Source & path. Drag a rectangle with Source for the soil that fails, and set its thickness and whether it is saturated. Drag Catchment for storm water lying on the ground at the start. Click with Path where the flow starts to trace the steepest-descent path, then lay an erodible bed along it. Click with Place to name the roads, houses or reported impact points where you want records.
Water. Choose a surface preset (Manning's n), the water particle spacing (at least 1.25 grain diameters, 3 advised) and the expected speed.
Grains. Choose a soil preset or set the grain size, friction, rolling resistance and the apparent cohesion that holds the source until it is wetted. These are coarse-grained model parameters to calibrate against an observed runout, not laboratory values.
Run. Read the estimate and the warnings, then run. In the Education edition the case runs on your computer; larger sites need an Academic Research or Professional licence, which can export the case for a GPU server.

About GLO-30. Copernicus GLO-30 is a surface model, so trees and buildings are in its heights and can turn a traced path. In the paper's trials the path from the Nanai source missed Nanai Road for this reason. Use a bare-earth lidar model where one exists.

5. Reading the results

3D playback of the grains and the water, frame by frame.
Plan maps over the shaded terrain: debris thickness, thickness change, peak grain speed, peak water depth (measured by volume, so spray does not set it) and peak water speed.
Records at places: debris thickness, arrival time, peak speeds, water depth and the impact pressure ρv², as a table, a chart and a CSV file.
Runout along the path, with the travel angle H/L of the grains that moved more than 5 m.

Treat every result as a scenario, not a forecast. Check the runout against an observed event before you vary the parameters, and read the warnings that come with the run.

6. Why we recommend Claude Opus

GranumFL works with any agent that speaks MCP, but we recommend Claude Opus (currently Claude Opus 5.5) for site studies, because it is the model we tested. In the four agent trials of the paper, Claude Opus 5.5 was given only the engineer's request and the MCP tools. It set up, ran or edited the Patong debris-flow site in 5 to 20 tool calls, and it passed all 33 checks, which were scored from the model files it left rather than from its replies.

Beyond the checks, the agent also found problems that nobody asked it to look for. Two trials noticed that the traced path missed Nanai Road and traced it to the surface model. Another found that the grains' grid stopped short of the downstream places and that the water layers were thinner than two particle spacings. A further trial declined to read a 6 s coarse run as a final travel angle. Four trials with one model cannot give a success rate, so this shows that the tools are clear enough for a strong agent, not that every agent will succeed.

Which model for which job. Use Claude Opus to plan and check a site study, where it must combine terrain, source, path, water and warnings over many steps. A faster, cheaper model is usually enough for single laboratory tests or small edits.

There are two ways to work with Claude:

Claude Code or Claude Desktop starts GranumFL as an MCP server (Section 7). This is the way the trials were run.
The chat inside the app can use Claude Opus through OpenRouter (Section 8), so you can watch the model change in the 3D view.

7. Connect through MCP

Run the program with --mcp and it becomes an MCP server on standard input and output, with 53 tools. Register it with your agent using the full path to the program:

System	Path to the program
macOS	`/Applications/GranumFL.app/Contents/MacOS/granum`
Windows	`C:\path\to\GranumFL-Education\granum.exe`

Claude Code (recommended)

claude mcp add granumfl -- /Applications/GranumFL.app/Contents/MacOS/granum --mcp
# for all your projects:
claude mcp add -s user granumfl -- /Applications/GranumFL.app/Contents/MacOS/granum --mcp
# choose Claude Opus inside Claude Code:
/model opus

Start claude and type /mcp: granumfl should be listed as connected. Then ask in plain language (Section 10).

Claude Desktop

Edit claude_desktop_config.json (Settings → Developer → Edit Config). It lives in ~/Library/Application Support/Claude/ on macOS and %APPDATA%\Claude\ on Windows. Restart Claude Desktop, then choose Claude Opus in the model menu.

{
  "mcpServers": {
    "granumfl": {
      "command": "/Applications/GranumFL.app/Contents/MacOS/granum",
      "args": ["--mcp", "--autosave", "/Users/me/granumfl/site.tellusdem"]
    }
  }
}

Cursor and other MCP clients

Add the same entry to ~/.cursor/mcp.json or to the project's .cursor/mcp.json. Any client that starts a stdio MCP server takes the same command and arguments.

Options

Option	Effect
`--open file.tellusdem`	Start with that project loaded.
`--autosave file.tellusdem`	Save the project there after every tool that changes it, so you can open the agent's model in the app at any time. The terrain and results are written beside it.

Agent and app together. With --autosave, the agent's model is a normal project file. Open it in the app to look at the plan map, the source and the path the agent laid out, correct anything by hand, and let the agent continue from your version.

8. The chat assistant in the app

The chat assistant is an agent inside the app. You write what you want, and it builds the case, runs it and shows the maps and curves under its reply. It works on a copy of your model, and what it leaves is applied to yours as one step that Undo reverses.

Press Chat assistant (top right), then Settings.
tigrim should read found, because it ships next to the program. If not, press Browse and choose tigrim (tigrim.exe on Windows).
Enter the provider. The agent works with any OpenAI-compatible API. To use Claude Opus, use OpenRouter, which gives one key for many models:
```
API URL   https://openrouter.ai/api/v1
Model     anthropic/claude-opus-5.5
API key   sk-or-v1-...   (from openrouter.ai → Keys)
```
Claude Opus also reads images, so you can attach a photo of a scar or a sketch of the site. A cheaper model such as deepseek/deepseek-v4.1-flash is enough for laboratory tests.
Press Done. The key is kept in your settings folder, not in project files.

9. MCP tools

The agent sees each tool with its description and arguments, together with the server's instructions, so it needs no other prompt. Lengths are in metres for the site tools and in millimetres for the laboratory and model tools.

Group	Tools	What they do
Water case	`new_water_case` `get_water_case` `run_water` `load_water_results` `water_results` `export_water_case`	Start from a template, read and edit the case, run it here, load results from a GPU server, and read the runout and the records at places. Export is in the Professional edition.
Site	`site_open_dem` `site_download_dem` `site_cut_terrain` `site_add_place` `site_remove_place` `site_set_source` `site_set_catchment` `site_trace_path` `site_set_bed` `site_set_soil` `site_set_water` `site_info` `site_measure` `site_map`	Elevation model, crop and cut, places, source, catchment, path, bed, soil and water, checks and estimates, distances and slopes, and result maps as PNG (or GIS grids in the Professional edition).
Project	`new_project` `open_project` `save_project` `set_title` `get_model` `set_model` `validate`	Start from a template or a file, read or replace the whole model, and check it before a run.
Grains and tests	`add_material` `update_material` `delete_material` `set_grading` `set_specimen` `set_test` `set_bonds` `set_curing` `set_solver`	Grains, shapes, clay aggregates, gradings, the specimen, the test, bonds, cement curing and solver settings.
Staged models	`add_region` `update_region` `delete_region` `add_structure` `update_structure` `delete_structure` `add_phase` `update_phase` `delete_phase`	Soil regions, rigid structures and construction phases.
Run and results	`calculate` `get_results` `get_curve` `show_picture` `write_animation` `write_report` `get_compute` `set_compute`	Run a DEM model, read curves, render pictures and animations, and write a PDF report.

10. Working with an agent

Describe the job as you would to a colleague: the site, the soil, the water and what you want to know. The agent fills in sensible defaults for what you leave out and tells you which ones it chose. These requests work well:

"Set up a debris-flow model of the Nanai landslide in Patong: a saturated source of 80 × 50 × 3 m at 7.8834 N, 98.3061 E, Nanai Road and the DMR impact point as places, and an erodible bed of 1 m. Check it and tell me what to fix before a GPU run."
"Run a coarse trial of this case and give me the runout and the travel angle, and tell me whether the run is long enough to trust them."
"Make the bed 2 m deep and the source 100 × 60 m, add the school as a place, and check that the grid reaches every place."
"Run the dam break template and compare the front with Martin and Moyce."
"Draw the peak water depth map with the places and list the depth and arrival time at each place."

Check the agent. The agent uses the same tools and checks as you, but it can misjudge. Read the estimates and warnings it reports, open its model in the app, and treat its results as you would a junior engineer's work, checking them before they inform any decision about people or property.

11. Editions and limits

	Education (free)	Academic Research	Professional
Use	Teaching, non-commercial research	Non-commercial research	Commercial and consulting work
Water + grains case	50,000 grains and 50,000 water particles	No limit	No limit
DEM model	50,000 particles	No limit	No limit
Terrain	1 km² in plan	No limit	No limit
GPU-server export and GIS grids	No	Yes	Yes
Reports, maps and pictures	Education watermark	Education watermark	Clean
How to get it	Download	Contact us

If you publish work done with GranumFL, please cite Youwai (2026), doi:10.5281/zenodo.23858571.

12. Troubleshooting

"The Education edition is limited to 50,000 grains per case.": Make the source or the bed smaller, or the grains larger. For research sites, ask for an Academic Research licence.
"The Education edition is limited to 1 km².": Cut a smaller crop around the source and the places, for example 1.25 × 0.8 km.
A run stops early with a grain outside the grid.: The grains' grid surrounds the source and the bed by the grid margin. Raise Grid margin for the grains under Water so that it reaches every place downstream.
The water runs much too fast.: Check that a surface preset or Manning's n is set, and that the water layers are at least two particle spacings thick.
The run uses the CPU although I have an NVIDIA GPU.: The CUDA engine needs NVRTC (see Install). The run's log has a line that starts with engines:, which says whether the water and the grains ran on CUDA or on the CPU.
Claude Code does not list granumfl under /mcp.: Use the full path to the program, include --mcp, and run claude mcp list to see the error. On macOS, open GranumFL.app once first so that macOS allows it to run.
The chat answers with an error from the provider.: Check the API URL, the model name exactly as OpenRouter lists it (anthropic/claude-opus-5.5), and that the key has credit.