菜单
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.
用 Codex 或 Claude 帮你安装 复制这段 Prompt，粘贴到 Codex、Claude 或其他助手里，让它检查 Skill 页面并帮你完成安装。
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.