Sustodian

When your high-throughput codes just aren't (Slurm Edition)

---

Sustodian is a quality-of-life improvement toolkit designed for high-throughput computing workflows utilizing Slurm, VASP, and Fireworks. It provides essential debugging and monitoring utilities to streamline your computational materials science workflows.

🚀 Features

Sustodian currently provides two main tools:

1. FindMyFW: Seamlessly map your running Slurm jobs to their corresponding Fireworks IDs and directories.
2. checkincar: Easily track and understand INCAR modifications and errors handled by Custodian during VASP calculations.

📦 Installation

Clone the repository and install it via pip:

git clone https://github.com/wuz75/sustodian.git
cd sustodian
pip install -e .

Now, the checkincar and sjob commands are available globally in your environment! You no longer need to set up any bash aliases to use them.

---

🛠️ Usage

FindMyFW

For Slurm and Fireworks Users

FindMyFW helps you locate the specific Firework associated with any of your running Slurm jobs. It can also identify JobIDs that are "empty" (i.e., not actively running any Fireworks). It is compatible with both rapidfire and singleshot launch methods (rapidfire is recommended).

How it works:
The tool parses your queue using scontrol show job <jobid> and examines the job's execution path. It identifies the most recent launcher_ directory and extracts the fw_id from the embedded FW.json file.

Commands:

• Run sjob from your terminal.
• Specific Job: When prompted, enter a single JobID to retrieve its execution directory and associated Fireworks ID (fw_id).
• All Running Jobs: Enter all at the prompt to retrieve directories and fw_ids for all your jobs currently in the "Running" (R) state.

---

checkincar

For VASP and Custodian Users

checkincar is an invaluable tool for debugging VASP calculations that are managed by Custodian. It reveals exactly which INCAR tags Custodian modified and prints the associated errors in an easy-to-read, human-friendly format.

How it works:
checkincar iterates through each error.#.tar.gz archive in your VASP calculation directory. It safely decompresses INCAR.gz and custodian.json.gz in memory, printing out the specific tag changes orchestrated by the Custodian error handler. It also works seamlessly for already completed jobs.

Commands:

• Navigate to the directory containing your VASP calculation (where your error tarballs reside) and run checkincar ./INCAR.

---

📄 License & Authors

Sustodian is licensed under the MIT License.

Author: wuz75 (waynezhao@berkeley.edu)