Repository navigation
User HPC Workflows
GridLock is designed to run locally on your Wayland workstation while seamlessly orchestrating and monitoring parallel execution state across remote supercomputing clusters.
Debugging an application running across hundreds of distributed nodes requires surgical precision. GridLock provides unified tools to monitor the health of the entire cluster while easily zooming into the state of a single rank.
When a parallel job halts, you often only care about the state of the specific rank that triggered a crash or hit a breakpoint.
Instead of overwhelming your network by fetching data for the entire cluster simultaneously, use the Scope Dropdown located at the top of the main toolbar.
- Selecting a specific rank (e.g.,
Rank 42) instantly isolates your current view. - The Source Code Editor, Variables Grid, and Call Stack will immediately synchronize to reflect only the memory and execution context of that specific rank.
- This allows you to inspect isolated anomalies smoothly without waiting for unnecessary data payloads from healthy ranks.
To provide a macro-level view of your cluster's health, GridLock features a real-time dashboard displaying a grid of diagnostic LEDs representing every active MPI rank in your allocation.
- Execution State: A green LED indicates a rank is running, while a yellow/red LED indicates a rank is paused or halted.
- Execution Timers: Each rank features a live execution timer. These timers are invaluable for spotting load imbalances and silent desyncs.
- Example: If you notice that Rank 0's timer has stopped (indicating it hit a synchronization barrier) while Rank 1's timer continues to run for several minutes, you have instantly identified a severe compute imbalance or a potential deadlock without needing to read a single line of code.
GridLock uses native SSH multiplexing to communicate with remote login nodes.
- Navigate to Preferences > HPC Settings.
- Add a new Remote Host (e.g.,
login.cluster.edu). - Provide the path to your private key (e.g.,
~/.ssh/id_ed25519).
Important
Password-based interactive SSH is not supported for automated debugging. You must configure passwordless key-based authentication.
Scientific software relies heavily on Spack. GridLock integrates a native Spack environment manager.
- Open the HPC Console dock.
- Navigate to the Spack tab.
- GridLock queries
spack env liston the remote node. - Select your target environment. GridLock automatically injects
spack env activate <env>into the pre-launch environment variables for the remote backend.
You rarely run MPI jobs on a login node. GridLock natively understands SLURM's sbatch and srun.
In your Run Configuration, you can define a SLURM template:
#!/bin/bash
#SBATCH --job-name=gridlock_debug
#SBATCH --nodes=4
#SBATCH --ntasks-per-node=8
#SBATCH --gpus=4
#SBATCH --time=00:30:00
srun --mpi=pmix {FILE}-
The
{FILE}Token: GridLock automatically replaces the{FILE}token with the compiled debuggee executable path. -
GPU Requests: Modify the
#SBATCH --gpus=Xdirective in the UI to dynamically allocate required resources. - GridLock automatically captures the resulting Job ID and attaches the debugger to the spawned
sruninstances across all nodes.
GridLock Repository | Releases | Report an Issue | Roadmap | Accessibility | License (MIT)
Documentation mirrored from docs/ on master.
User Guides
Architecture & Plan
Developer Docs