Repository navigation
Tutorials Walkthrough
The tutorial/ directory ships 7 primary C++ MPI showcase programs (pre-populated in the main toolbar TARGET: dropdown and bundled into GridLock-0.8.66-Tutorials-x86_64.AppImage) plus 5 focused C/C++ micro-demos accessible from --tutorial-mode (TutorialDialog) or Open ELF / Binary....
Every walkthrough below gives the exact compiler command, recommended -np rank count, verified source line numbers, and the exact GridLock panels to inspect.
-
Bug Demonstrated:
$N$ -rank circular blockingMPI_Sendstall (Rank 0 -> Rank 1 -> ... -> Rank N-1 -> Rank 0) with a 64 KB (16,384 * sizeof(int)) payload exceeding MPI eager buffering thresholds. -
Compile Manually (or let
▶ Run Targetcompile automatically):mpicxx -g -O0 tutorial/deadlock_ring.cpp -o tutorial/deadlock_ring
-
Reproduce & Diagnose in GridLock:
- Select
deadlock_ring (MPI)inTARGET:and setRANKS (-np):to8. - Click
▶ Run Target. Because lines34-35callMPI_Send(send_buf.data(), 16384, MPI_INT, next_rank, tag, MPI_COMM_WORLD)before line36(MPI_Recv), all 8 ranks block insideMPI_Send. - Click
⏸ Pause Rank(or set a breakpoint at line34before running). - Press
Alt+3(MPIperspective) and inspectMPI Diagnostics -> DEADLOCK ANALYZER:- Header badge reads
STATUS: CYCLE DETECTED. - Every rank (
Rank 0 .. Rank 7) showsMPI_Sendstalled atdeadlock_ring.cpp:34.
- Header badge reads
- Switch to
REVERSE(Alt+2) to see[R0-R7 (8)]and[DEADLOCK]badges stacked on theMPI_Sendbasic block. -
Fix: Replace the sequential
MPI_Send+MPI_Recvcalls at lines34-37withMPI_Sendrecv, save (Ctrl+S), rebuild (Ctrl+B), and re-run.
- Select
-
Behavior Demonstrated: Recursive inspection of
struct DeeplyNested data[3](lines4-10, containingint id,double values[5], and nested anonymouscoords { float x, y, z; }) where Rank 0 assignsi * (1.1f, 2.2f, 3.3f)while Ranks1..N-1assigni * (1.5f, 2.5f, 3.5f)at lines19-21. -
Compile:
mpicxx -g -O0 tutorial/inspection_demo.cpp -o tutorial/inspection_demo
-
Inspect in GridLock:
- Select
inspection_demo (MPI)inTARGET:and setRANKS (-np):to4(or8). -
Right-click the gutter at line
19(data[i].coords.x = ...) to openConditionalBreakpointDialog:- Set
Suspend:toAll(or selectRank 3inServer Rackand pickRank / Thread). - Type
rank == 3 && data[i].intoCondition:to trigger liveclangdmember completion (coords,id,values), complete it torank == 3 && data[i].coords.x > 0.0f, and clickDone.
- Set
- Also left-click line
23(printf(...)) so all ranks stop after populatingdata[0..2]. - Click
▶ Run Target, then⏭ Continue(F5) to reach line23. - Expand
data->[1]->coordsinVariables, and adddata[1].coords.xanddata[2].values[4]toWATCH(DifferentialGrid): Rank 0'sdata[1].coords.x(1.1) highlights in light red as the minority outlier against Ranks1..N-1(1.5).
- Select
-
Bug Demonstrated: Rank-parity branch mismatch on
MPI_COMM_WORLD: at line47(if (rank % 2 == 0)), even ranks (0, 2, 4, 6) enterMPI_Bcast(line50) while odd ranks (1, 3, 5, 7) take theelsebranch intoMPI_Barrier(line60). -
Compile:
mpicxx -g -O0 tutorial/collective_mismatch.cpp -o tutorial/collective_mismatch
-
Reproduce & Diagnose in GridLock:
- Select
collective_mismatch (MPI)and setRANKS (-np):to8. - Set a breakpoint at line
47(if (rank % 2 == 0)) or run directly and pause once stalled. - Open
MPI Diagnostics(Alt+3):DeadlockAnalyzerflagsSTATUS: COLL DIVERGENCE(Collective Divergence: Rank 0 in MPI_Bcast vs Rank 1 in MPI_Barrier). - Add
cfg.rank_branch_tagandcfg.broadcast_seedtoWATCH(100 + rankon even ranks vs200 + rankon odd ranks;0x4242=16962on Rank 0 vs0elsewhere). - Press
SpaceinDisassemblyViewto view the 2D CFG: even rank badges sit on theMPI_Bcastbasic block while odd rank badges sit on theMPI_Barrierbasic block.
- Select
-
Bug Demonstrated: 5-step periodic 1D 3-point Jacobi stencil (
for (int step = 0; step < 5; ++step, line43) wherefaulty_rank(Rank 2when-np >= 4) injectsstd::numeric_limits<double>::quiet_NaN()intosend_rightonstep == 3(lines48-50), poisoningRank 3'sleft_ghostviaMPI_Sendrecv(lines53-55) and propagatingnaninto interiordomaincells. -
Compile:
mpicxx -g -O0 tutorial/ghost_cell_drift.cpp -o tutorial/ghost_cell_drift
-
Reproduce & Diagnose in GridLock:
- Select
ghost_cell_drift (MPI)and setRANKS (-np):to8(or4). - Right-click the gutter at line
69(stencil_center = domain[domain.size() / 2];), setIgnore:to3hits (so execution runs steps0, 1, 2uninterrupted and pauses onstep == 3), and clickDone. - Add
step,left_ghost,right_ghost, andstencil_centertoWATCH(DifferentialGrid) and click▶ Run Target. - On
step == 3,WATCHimmediately shadesRank 3'sleft_ghost(nan) in light red against the numeric values on the other ranks. Click⏭ Continue(F5) once more (step == 4) to watchnanspread into interior stencil elements. - Open
Memory View(Alt+4), enterdomain.data()inAddr:, setBytes:to64andType:toDouble, and clickDiff Ranks(Base: 0,Target: 3) to inspect the IEEE-7540x7ff8000000000000quiet-NaNbytes.
- Select
-
Bug Demonstrated: Quadratic heap imbalance (
element_count = 4096 * (rank + 1) * (rank + 1)at lines55-56, from 32 KB on Rank 0 up to 2,048 KB on Rank 7) paired with linear stack recursion imbalance (target_stack_depth = 2 + rank * 2at lines62-63, callingrecurseWithStackFramewith a 256-bytedouble stack_scratch[32]array per frame). -
Compile:
mpicxx -g -O0 tutorial/heap_imbalance.cpp -o tutorial/heap_imbalance
-
Reproduce & Diagnose in GridLock:
- Select
heap_imbalance (MPI), setRANKS (-np):to8, and set a breakpoint at line41(const double leaf_checksum = ...at the recursion leaf). - Click
▶ Run Target. - Click through
RANK 0toRANK 7inServer Rackwhile watching:-
CALL STACK:Rank 0shows 2recurseWithStackFrameframes;Rank 7shows 16 frames. -
Bottom Status Bar:
STACKandHEAPgrow quadratically/linearly from Rank 0 to Rank 7. -
Memory View -> LIBRARY MEMORY MAP: Select different ranks in the profiler's rank dropdown (withTrack Heap Callers (LD_PRELOAD)enabled) to compareHeap / Call Siteattribution across ranks.
-
- Select
-
Bug Demonstrated: Rank 0 sends
struct TelemetryPacket pkt(56 bytes) to Rank 1 withsend_tag = 100(line53), while Rank 1 postsMPI_Recvfrom Rank 0 expectingexpected_tag = 200(line61). Worker ranks2..N-1finish local work and park atMPI_Finalize(line73). -
Compile:
mpicxx -g -O0 tutorial/tag_mismatch_stall.cpp -o tutorial/tag_mismatch_stall
-
Reproduce & Diagnose in GridLock:
- Select
tag_mismatch_stall (MPI)and setRANKS (-np):to4. - Set breakpoints at line
53(MPI_Send) and line61(MPI_Recv), or click▶ Run Targetand then⏸ Pause Rankonce Rank 1 hangs. - Focus
RANK 0vsRANK 1inServer Rackand inspectsend_tag(100) vsexpected_tag(200) inVariables(or right-clickpkt->Visualize in Pointer / Struct Graph...to inspectTelemetryPacketfields).
- Select
-
Behavior Demonstrated: Populates
struct alignas(16) SimdMatrixPacket(112bytes, lines21-27:uint8_t magic[4]={0xCA, 0xFE, rank, size},uint32_t packet_id,uint64_t flags,float matrix[4][4],double lane_Norms[4]), computeslocal_trace(line60), and reducesglobal_traceviaMPI_Allreduce(line62). -
Compile:
mpicxx -g -O0 tutorial/simd_struct_watch.cpp -o tutorial/simd_struct_watch
-
Inspect in GridLock:
- Select
simd_struct_watch (MPI), setRANKS (-np):to4, and set breakpoints at line62(MPI_Allreduce) and line64(std::printf). - Click
▶ Run Target. When paused at line62, addlocal_traceandpacket.packet_idtoWATCH. - Open
Memory View(HEX DUMP), enter&packetinAddr:, setBytes:to112, and clickRead:- Byte offsets
0x00..0x01showCA FE, followed by rank ID (0x02) and world size (0x03). - Set
Base:to0andTarget:to1, then clickDiff Ranksto highlight every rank-dependent header and matrix byte in red. - Set
Type:toFloat, clickExport, and save a.csvor.bindump of the packet.
- Byte offsets
- Click
⏭ Continue(F5) to stop at line64and verifyglobal_tracematches across all ranks.
- Select
Launch ./builddir/gridlock --tutorial-mode to open the modal Interactive Tutorials launcher (TutorialDialog), or open these 5 standalone targets directly:
| Source File | Compile Command | Ranks (-np) |
Key Lines & Purpose |
|---|---|---|---|
tutorial/deadlock_demo.c |
mpicc -g -O0 tutorial/deadlock_demo.c -o tutorial/deadlock_demo |
2 |
Lines 25 & 28: Mutual synchronous send (MPI_Ssend) deadlock between Rank 0 and Rank 1. |
tutorial/register_demo.cpp |
mpicxx -g -O0 tutorial/register_demo.cpp -o tutorial/register_demo |
1 or 2
|
Lines 24-31: Inline x86 assembly (mov / add into %eax); step with ↷ Step Inst while watching rax mutate in Registers. |
tutorial/memview_demo.cpp |
mpicxx -g -O0 tutorial/memview_demo.cpp -o tutorial/memview_demo |
1 or 2
|
Line 25: Allocates 256-byte heap block filled with 0xAA, 0xBB, and "Hello, MemView!" at +16; read memory_block in Memory View. |
tutorial/memview_diff_demo.cpp |
mpicxx -g -O0 tutorial/memview_diff_demo.cpp -o tutorial/memview_diff_demo |
2 |
Line 30: int array[10] where Rank 1 sets array[5] = 999 (line 16); inspect array (40 bytes) with Diff Ranks (0 vs 1). |
tutorial/mpi_mm.c |
mpicc -g -O0 tutorial/mpi_mm.c -o builddir/mpi_mm (built by default in Meson)
|
3 or 4
|
Lines 84, 99, 114, 130: Master/worker (FROM_MASTER=1, FROM_WORKER=2) 500x500 dense double matrix multiplication. |
GridLock Repository | Releases | Report an Issue | Roadmap | Accessibility | License (MIT)
Documentation mirrored from docs/ on master.
Getting Started
User Reference
- Keyboard Shortcuts
- UI & Debugging Manual
- MPI Diagnostics & HPC
- Memory, RE & Profiling
- Configuration & Themes
Internals & Plan