Student projects — getting started with OOFEM and T3D

Resources for student projects in the Grassl Group — Concrete Mechanics for Performance Based Design at the University of Glasgow that use OOFEM.

The toolchain is distributed as Docker images so you can run OOFEM and its mesh tools on your own machine without compiling anything.

Outline

Docker images

Before anything below, install Docker:

After install, launch Docker Desktop once and wait for the whale icon in your menu bar / system tray to settle (no animation). Then open a terminal and confirm everything works:

In that terminal, type:

docker run hello-world

If you see “Hello from Docker!” you’re good. If you see “Cannot connect to the Docker daemon”, Docker Desktop is not running — open the app and wait for the whale icon to stop animating.

Every docker … command on this page goes in the same terminal.

There are two images. Which one you use depends on whether you need T3D.

Public image — ghcr.io/githubgrasp/oofem-public

Ships OOFEM, the converter / generator / aggregate mesh tools, Python, gnuplot, and ffmpeg. Multi-arch (Apple Silicon, Intel, Linux). No T3D. Pull anonymously:

docker pull ghcr.io/githubgrasp/oofem-public:latest

Use this for the worked examples — each is two commands and does not need T3D.

Path syntax for the -v mount. The "$PWD" in the docker run commands on this page is bash syntax. Equivalents on Windows:

macOS and Linux terminals are bash-compatible, so the commands work as written.

Private image — bundles T3D

T3D is licensed for academic use under terms that do not allow redistribution, so it is not in the public image. The private image that bundles T3D is distributed by your supervisor via OneDrive as a gzipped tarball named oofem-private-<date>-<arch>.tar.gz. Two architectures are provided — download the one that matches your machine:

How to check if you’re not sure:

Load it (Docker auto-decompresses the gzip):

docker load < oofem-private-<date>-<arch>.tar.gz

After loading, the image is tagged locally as oofem-private:dev.

Run a one-shot command in your current project folder (mount as /work):

docker run --rm -v "$PWD":/work -w /work oofem-private:dev oofem -f oofem.in

Or open an interactive shell, with your project folder mounted at /work:

docker run --rm -it -v "$PWD":/work -w /work oofem-private:dev bash

Inside, run t3d, t3d2oofem, oofem, extractor.py, etc. directly. Files you create are visible on the host.

A typical T3D-meshing workflow looks like:

docker run --rm -it -v "$PWD":/work -w /work oofem-private:dev bash
# inside the container:
t3d -d 0.1 -i mesh.in -o mesh.out
t3d2oofem oofem.t3d.ctrl mesh.out oofem.in
oofem -f oofem.in > std.out

Use this image for any project work that needs to mesh from .in files with T3D.

Run a worked example (public image, two commands)

git clone https://github.com/githubgrasp/oofem-examples.git
cd oofem-examples/<example-folder>
docker run --rm -v "$PWD":/work ghcr.io/githubgrasp/oofem-public:latest bash run.sh

Outputs (VTU files for ParaView, extracted data, OOFEM logs) appear in the example folder on your host.

Interactive shell (public image)

./test.sh ghcr.io/githubgrasp/oofem-public:latest

test.sh (in the oofem-examples repo root) opens a shell inside the container with your current host directory mounted at /work. Run oofem, extractor.py, gnuplot, etc. directly. Files you create are visible on the host.

T3D + X11 GUI (private image)

T3D works headlessly inside the container; the GUI is only needed for interactive mesh visualisation.

Combine the X11 flags with the work-folder mount from the previous section. For each platform, set up the X server first, then run:

Inside the container: t3d -X -i mesh.in -d 0.1.

Server access

For larger analyses, OOFEM typically runs on School servers (your supervisor will arrange an account). OOFEM is open source and can also be compiled locally if you prefer.

You’ll need VPN to connect, even on campus: VPN setup. Connect with ssh and transfer files with scp (built-in on Linux/macOS). On Windows use WinSCP for transfers and MobaXterm for terminal access.

Important: server data is not backed up. Keep copies on your own machine (OneDrive, etc.).

Editors

File structure on the server

Create a top-level folder (e.g. jobs/) with one subfolder per analysis to avoid overwriting outputs. Useful shell commands: cp, mv, rm (permanent!), pwd, cd, ls, mkdir, top. Run OOFEM from the folder that contains your input file.

OOFEM

oofem -f oofem.in > std.out &

oofem is the executable, oofem.in is your input, stdout is redirected to std.out. Results are written to the files specified in the input (typically VTU for ParaView).

T3D

T3D generates meshes (mostly tetrahedra; simple hexahedra possible). See the T3D homepage. T3D is inside the private Docker image (see above).

t3d -d 0.1 -i mesh.in -o mesh.out

-d is the target element size; -i/-o set input/output files.

T3D → OOFEM (t3d2oofem)

Convert a T3D mesh to an OOFEM input skeleton:

t3d2oofem oofem.t3d.ctrl mesh.out oofem.in

The control file (oofem.t3d.ctrl) governs elements, materials, and typical output blocks. You may still tweak the generated oofem.in.

ParaView

ParaView is the recommended post-processor (load OOFEM’s .pvd or .vtu outputs). Free for Windows, macOS, and Linux.

Extractor script

extractor.py reads OOFEM outputs and produces, e.g., load–displacement or element stress–strain curves:

extractor.py -f oofem.in > ld.dat

Configure what to extract at the end of oofem.in.

Worked examples

Curated reproducible examples covering fracture, transport, and heterogeneous materials live in the oofem-examples repo — the table at the top of its README lists each example with a one-line description. Each is two commands to run and uses the public image (no T3D needed). Some have an accompanying blog post on the blog index, but the repo is the authoritative list.

Pick the example closest to your project, get it running, then modify.

Troubleshooting