Using Granum

1. Install

Download the Education edition for your system from the download section and unpack it. Each package holds the program, the chat agent tigrim, a quick start and the licence.

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

The engines and the GPU

Granum picks the fastest engine it finds: CUDA on an NVIDIA GPU, then wgpu (Metal or DirectX 12), then the CPU with all its cores. Very small specimens run on the CPU, where they are quicker. The CUDA engine compiles its kernels when it starts, so it needs the NVIDIA driver and the NVRTC library, but not a full CUDA installation:

• Windows: install the CUDA toolkit (12.x or 13.x), or set TELLUSDEM_NVRTC to the full path of the NVRTC DLL; Granum looks for nvrtc64_*.dll on the PATH and in %CUDA_PATH%\bin.
• macOS: nothing to install; Granum uses Metal.

The run log names the engine in use, for example engine: GPU: NVIDIA GeForce RTX 4090 (CUDA).

2. A first test

1. Open an example. Choose File → Examples → Drained triaxial test on a uniform sand. The examples cover triaxial tests on spheres and angular clumps, the oedometer, unconfined compression of cemented sand, deposition, the angle of repose, a strip footing, the clay and cement-admixed clay tests, and two staged models.
2. Check the input. The Input workspace has four steps: Particles (materials and grading), Specimen (box size and packing), Test (stresses, strain and rate) and Solver (time step, damping, frames). As soon as the input is valid, the specimen appears in 3D and Granum lists its estimates: the number of particles, the time step, the steps to the end of the test and the expected contact overlap. Read the warnings before you run.
3. Run. Press Run test. The grains move in the view each time the solver keeps a frame, and the log shows each stage.
4. Read the results. The Output workspace plays the frames, colours the grains by displacement, velocity, spin, coordination or size, draws force chains and bonds with an optional section cut, and plots the test's curves with the current frame marked. The summary lists the values an engineer reads from the test, such as φ′ at peak and at large strain, the dilatancy angle and E₅₀, with quality checks.
5. Save. File → Save project writes a .tellusdem project file; its results are kept beside it in .results.bin. The Output workspace writes a PDF report with its picture and curve; animations and further pictures come from the chat assistant or the MCP tools.

3. Staged models

Problems other than laboratory tests, such as an excavation beside a wall, an embankment built in lifts or a footing loaded in steps, are built as in a finite element program. Choose File → New model; the steps become Materials, Geometry, Staged construction and Solver.

• Regions fill boxes of the domain with grains of a material and grading, or mark a zone without grains that a later phase excavates.
• Structures are rigid footings, plates, walls or piles, as boxes or vertical cylinders.
• Phases run in order. In each one you set gravity (any g-level), the regions placed or excavated, each side of the domain (fixed, off, moving or held at a stress), each structure (fixed, moving, displaced, or loaded by a force or pressure), bonding and curing, and how the phase ends (equilibrium, time or steps). What a phase does not mention keeps its state.
• Pore pressure. A phase can be undrained or consolidating on a coarse pore-pressure grid; the permeability and a time scale make months of consolidation run in seconds.
• Monitors record settlement plates, deep points, inclinometers and piezometers over time.

Pore pressure and monitors are set in the project file (or by an agent with set_model); the app's Staged construction step does not show them yet.

The examples Model: excavation beside a rigid wall and Model: footing on a sand layer loaded in steps are good starting points.

4. The chat assistant

The chat assistant is an AI agent inside the app. You write what you want in plain language, and it builds the model, runs it and shows the curves and pictures under its reply, with a PDF report when you ask. It works on a copy of your model, and the model it leaves is applied to yours as one step that Undo reverses.

Set it up once

1. Open the assistant with Chat assistant (top right), then press Settings.
2. tigrim should read found: it is the agent program that ships next to Granum. If not, press Browse and choose tigrim (tigrim.exe on Windows) from the Granum folder.
3. Choose the language model. The agent works with any OpenAI-compatible API; we tested it with OpenRouter, which gives one key for many models.

   API URL   https://openrouter.ai/api/v1
   Model     deepseek/deepseek-v4.1-flash
   API key   sk-or-v1-...   (from openrouter.ai → Keys)

   A fast, inexpensive model is enough for most work; a stronger model plans long staged models better. To attach photos or sketches, choose a model that takes images.
4. Python for the agent (optional) lets the agent do hand checks with numpy. Leave it empty to have it found automatically.
5. Press Done. The key is kept in your Granum settings folder, not in project files.

Use it

• Write the request and press Enter (Shift+Enter for a new line). You can add images.
• While it works, the panel shows its steps; Stop ends the run. Clear starts a new conversation.
• Curves, pictures and reports appear under the reply; Open report and Show in folder open the PDF.
• Everything the agent did is in the model afterwards, so you can inspect, change and rerun it by hand.

5. Connect an AI agent (MCP)

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

Claude Code

claude mcp add granum -- /Applications/Granum.app/Contents/MacOS/granum --mcp
# for all your projects:
claude mcp add -s user granum -- /Applications/Granum.app/Contents/MacOS/granum --mcp

Start claude and type /mcp: granum should be listed as connected.

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. Then restart Claude Desktop.

{
  "mcpServers": {
    "granum": {
      "command": "/Applications/Granum.app/Contents/MacOS/granum",
      "args": ["--mcp"]
    }
  }
}

Cursor and other MCP clients

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

Options

"args": ["--mcp", "--open", "/Users/me/granum/wall.tellusdem", "--autosave", "/Users/me/granum/wall.tellusdem"]

6. MCP tools

The agent sees these tools with their descriptions and argument lists, so it needs no other instructions. Units are mm, kPa, MPa (particle modulus) and kg/m³, with z upwards.

7. Working with an agent

Say what you want as you would to a colleague: the soil, the test or structure, the stresses and what you want to see. The agent chooses sensible defaults for what you leave out and tells you which ones. Some requests that work well:

• "Drained triaxial tests on a 0.5–1 mm angular sand at 50, 100 and 200 kPa. Give φ′ at peak and at large strain."
• "Cement-admixed clay with 15 % cement, cured 28 days, unconfined compression. Show where the bonds break."
• "Strip footing 40 mm wide on dense sand at 50 g, half model. Plot load against settlement and give N_γ."
• "Excavate 3 m beside a rigid wall in two stages and plot the wall's horizontal movement against depth."
• "Write a PDF report of this test with the main pictures and your assessment of its limits."

8. Editions and limits

All laboratory tests, the three engines, the clay and cemented-clay model, staged models, pore pressure and the MCP server are in every edition. Dynamic granular flow (hopper and drum structures, turning walls, free-falling weights and sinks) is in the Academic Research and Professional editions only. If you publish work done with Granum, please cite Youwai (2026), doi:10.5281/zenodo.23652515.

9. Troubleshooting

Granum runs on the CPU although I have an NVIDIA GPU.

The CUDA engine needs NVRTC; see Install. Without it Granum falls back to wgpu (DirectX 12), which also uses the GPU. Specimens of a few thousand grains or fewer run on the CPU on purpose.

"The Education edition is limited to 50,000 particles per model."

Make the specimen smaller or the grains larger; laboratory tests need far fewer particles. For research models, ask for an Academic Research licence.

The chat says "tigrim not found".

Keep tigrim beside the program, or set its path under Settings → tigrim → Browse.

The chat answers with an error from the provider.

Check the API URL, the model name exactly as the provider lists it, and that the key has credit.

Claude Code does not list granum under /mcp.

Use the full path to the program, include --mcp, and run claude mcp list to see the error. On macOS, open Granum.app once first so that macOS allows it to run.

The run warns about large overlaps or a high inertial number.

Raise the particle modulus, or load more slowly. Results from a run with these warnings are not quasi-static and should not be used.

Other questions: tellusfem@gmail.com.