Menu
Build, compile, and run MDOODZ simulations — CMake configuration, make targets (build, build-dev, run, clean), dependency installation (SuiteSparse, HDF5, BLAS/LAPACK), OpenMP parallelisation, env.cmake setup, and common troubleshooting.
Install with Codex or Claude Copy this prompt, paste it into Codex, Claude, or another assistant, and let it review the skill page and install it for you.
Based on SOC occupation classification
MDOODZ mechanical anisotropy module — director-based fabric tracking, anisotropy factors (δ_n, δ_s), viscous transverse isotropy, ViscosityConciseAniso, finite strain evolution, anisotropic rifting methodology, and anisotropy scenario examples.
MDOODZ performance benchmarking — running benchmarks, interpreting perf.csv, grid scaling studies, thread scaling, comparing machines, and the benchmark.sh script.
Code-to-physics glossary for MDOODZ — variable names, struct fields, function names mapped to physical meaning, equations, SI units, grid naming conventions, creep mechanism abbreviations, and solver process stages.
Debugging a failing MDOODZ model — the three failure families (CHOLMOD non-positive-definite, Powell-Hestenes non-convergence, first-iteration NaN), the error-string lookup table, the eta-contrast reality, the two anisotropy recipes, the single-variable bisection cookbook, and the known MDLIB anisotropy bugs with their fix commits. Use when a run crashes, won't factor, won't converge, NaNs, or stalls mid-production.
MDOODZ logging system — LOG_INFO/WARN/ERR/DBG/TIME macros, .txt configuration parameters (log_dest, log_level, log_timestamp, log_ts_mode, log_metadata), colored console output, ANSI-stripped log files, phase timing instrumentation, and metadata prefixes.
MDOODZ partial melting module — melt model indices, solidus/liquidus parameterizations, melt fraction computation, melt weakening, per-phase melt configuration, kinetic relaxation, and melting scenario examples.
| name | skill-build-and-run |
| description | Build, compile, and run MDOODZ simulations — CMake configuration, make targets (build, build-dev, run, clean), dependency installation (SuiteSparse, HDF5, BLAS/LAPACK), OpenMP parallelisation, env.cmake setup, and common troubleshooting. |
MDOODZ uses CMake (minimum 3.16) with a convenience makefile wrapper. The C standard is C11.
| Target | Command | Description |
|---|---|---|
| Build (optimised) | make build SET=<Name> | Builds with -O3 and OpenMP enabled |
| Build (custom txt) | make build SET=<Name> TXT=Custom.txt | Uses a non-default parameter file |
| Build (dev) | make build-dev OMP=ON OPT=ON SET=<Name> | Explicit control over flags |
| Run | make run SET=<Name> | Execute compiled simulation |
| Run (copy txt) | make run-copy SET=<Name> | Copy .txt from SETS/ then run |
| Clean (one set) | make clean SET=<Name> | Remove build artifacts for one scenario |
| Clean (all) | make clean-all | Remove all build and exec directories |
| Install deps | make deps | Clone and build HDF5 + SuiteSparse from helper repo |
| Run tests | make run-tests | Run CTest suite |
# 1. Build a scenario (optimised + OpenMP)
make build SET=RiftingChenin
# 2. Run it
make run SET=RiftingChenin
# Output files appear in cmake-exec/RiftingChenin/
| Option | Default | Description |
|---|---|---|
-DOPT=ON | OFF | Enable optimisation (-O3 -ftree-vectorize -funroll-loops) |
-DOMP=ON | OFF | Enable OpenMP parallelisation |
-DJULIA=ON | OFF | BinaryBuilder mode for Julia integration |
-DTEST=ON | OFF | Build test suite (enables CTest) |
-DVIS=ON | OFF | Build visual tests |
Debug mode (default when OPT=OFF): -g -Wall -O0 -fno-inline -fno-omit-frame-pointer
| Library | Purpose | Required |
|---|---|---|
| SuiteSparse | Sparse direct solver (CHOLMOD, UMFPACK, AMD, COLAMD, CCOLAMD, CAMD) | Yes |
| HDF5 | Output file I/O | Yes |
| BLAS/LAPACK | Basic linear algebra (used by SuiteSparse) | Yes |
| zlib | Compression for HDF5 output | Yes |
| pcg-c-basic | Random number generation | Auto-fetched via CMake FetchContent |
| OpenMP | Shared-memory parallelisation | Optional (recommended) |
Using the built-in helper:
make deps # Clones and builds HDF5 + SuiteSparse
macOS (Homebrew):
brew install suite-sparse hdf5 open-blas lapack
Ubuntu/Debian:
sudo apt install libsuitesparse-dev libhdf5-dev libblas-dev liblapack-dev zlib1g-dev
Fedora/RHEL:
sudo dnf install suitesparse-devel hdf5-devel blas-devel lapack-devel zlib-devel
If dependencies are in non-standard locations, create env.cmake from the template:
cp env.cmake.example env.cmake
Edit env.cmake to set custom paths:
set(CMAKE_PREFIX_PATH "/path/to/suitesparse;/path/to/hdf5")
set(C_COMPILER gcc) # or specify a full path
This file is gitignored and user-specific.
Build with OpenMP:
make build-dev OMP=ON OPT=ON SET=RiftingChenin
Control thread count at runtime:
export OMP_NUM_THREADS=8
make run SET=RiftingChenin
Key parallelised operations: particle interpolation, rheology evaluation, matrix assembly, CHOLMOD factorisation.
| Problem | Likely Cause | Solution |
|---|---|---|
SuiteSparse not found | Missing or wrong path | Install SuiteSparse or set path in env.cmake. Check FindSuiteSparse.cmake. |
HDF5 not found | Missing HDF5 | Install HDF5 dev package or run make deps |
HDF5 version mismatch | Mixed HDF5 installations | Ensure a single consistent HDF5 version; set HDF5_DIR in env.cmake |
| Segfault on startup | Bad .txt file or missing file | Verify .txt exists, Nb_phases matches ID blocks, Nx/Nz > 0 |
| NaN in output | Unstable parameters | Check dt, min_eta/max_eta, material properties, try safe_mode = 1 |
| Compilation warnings | Debug mode is verbose | Normal with -Wall; use -DOPT=ON for clean optimised build |
| Slow execution | No OpenMP or optimisation | Rebuild with OMP=ON OPT=ON |
When a simulation segfaults or produces corrupted results, always try ASAN first before GDB. ASAN detects heap-buffer-overflows, use-after-free, and stack overflows that cause silent memory corruption in Release mode — often crashing many steps later in unrelated code (e.g., inside cs_di_compress or CHOLMOD).
cmake -DCMAKE_C_FLAGS='-fsanitize=address -fno-omit-frame-pointer -g' \
-DCMAKE_CXX_FLAGS='-fsanitize=address -fno-omit-frame-pointer -g' \
-DCMAKE_BUILD_TYPE=Debug ..
cmake --build . -j4
ASAN_OPTIONS='detect_leaks=0' ./MyTest # disable leak check for faster runs
| Location | Bug | Fix |
|---|---|---|
AdvectionRoutines.c EvaluateCourantCriterion | Thermal loop used Vz-grid bounds (Nx+1, Nz) to iterate centre-grid arrays mesh->T of size (Nx-1)*(Nz-1) | Changed bounds to (Nx-1, Nz-1) |
Solvers.c DirectStokesDecoupledComp | BCp.type[k] != 30 && != 31 let type=0 cells through with eqn_p=-1 → wild pointer i = -1 - neq | Changed guard to BCp.type[k] == -1 |
Solvers.c KillerSolver, KSPStokesDecoupled | Same guard bug as above; also D1cm0->x[k] used cell index k instead of equation index i | Same fix + [k] → [i] |
CMakeLists.txt, Deps.cmake, FindSuiteSparse.cmakemakefileenv.cmake.exampleMDLIB/CMakeLists.txtSETS/AddSet.cmakeMDOODZ does not build natively on Windows (MSVC/MINGW64). Use WSL (Windows Subsystem for Linux).
wsl --install -d Ubuntuwsl bash -c "sudo apt install build-essential cmake libsuitesparse-dev libhdf5-dev libblas-dev liblapack-dev zlib1g-dev"
From a Windows terminal (PowerShell, CMD, or Git Bash), prefix all commands with wsl bash -c:
# Build
wsl bash -c "cd /mnt/c/Users/<user>/MDOODZ7.0 && make build SET=MyModel"
# Run (with log capture)
wsl bash -c "cd /mnt/c/Users/<user>/MDOODZ7.0 && make run SET=MyModel > logs.txt 2>&1"
# Check logs
wsl bash -c "cd /mnt/c/Users/<user>/MDOODZ7.0 && grep -i 'nan\|diverge\|Ending' logs.txt"
/mnt/c/ path accesses the Windows filesystem from WSL. Performance is slower than WSL-native paths (~/)./mnt/c/ — no manual sync needed.~/mdoodz/), edits on Windows are not auto-synced. Manually copy changed files before rebuilding.