CatGo Workflow Skill

Quick Start — Python API

from catgo.workflow import Workflow
from catgo.workflow.builtins import geo_opt, freq, gibbs_energy

wf = Workflow("RuO2 OER")

# Input structure
slab = wf.add_task("structure_input", structure=structure_json)

# Geometry optimization → Frequency → Gibbs Energy
opt = wf.add_task(geo_opt, structure=slab.output.structure, ENCUT=520, system_name="*OH")
frq = wf.add_task(freq, structure=opt.output.structure, system_name="*OH",
                   freeze_mode="layers", freeze_layers=4)
gib = wf.add_task(gibbs_energy, energy=opt.output.energy,
                   frequencies=frq.output.frequencies, system_name="*OH")

wf.submit()  # Engine picks it up automatically

HPC Confirmation Gate: By default, HPC tasks pause at PENDING_REVIEW after local preprocessing completes, so users can verify structures and parameters before spending HPC resources. Users confirm via the frontend "Confirm & Submit" button (per-task or "Confirm All"). To skip this gate, call wf.submit(auto_submit=True).

HPC Confirmation Required: Before calling wf.submit() or catgo_workflow_engine(action="submit"), you MUST ask the user which HPC cluster to use and confirm job parameters (partition, account, walltime, ntasks). These can be set per-task via add_task params. Never submit without user confirmation.

Available Task Types

HPC Calculations

• geo_opt — Geometry optimization (VASP/CP2K/ORCA/MLP)
• single_point — Single point energy (VASP/CP2K/ORCA)
• freq — Vibrational frequencies (VASP/CP2K/ORCA)
• cell_opt — Cell optimization (VASP/CP2K)
• md — Molecular dynamics (VASP/CP2K/LAMMPS/MLP)
• ts_search — Transition state search (Sella/ORCA NEB-TS)

Local Analysis

• gibbs_energy — G = E_DFT + ZPE - TS
• free_energy_diagram — Plot reaction energy diagram
• dos_analysis — Density of states analysis
• charge_analysis — Bader charge analysis

Structure Building

• structure_input — Provide input structure
• slab_gen — Generate surface slab
• adsorbate_place — Place adsorbate on surface

Key Parameters

VASP

• software="vasp", ENCUT, EDIFF, EDIFFG, NSW, ISIF, IBRION
• ISMEAR, SIGMA, ISPIN, NCORE, KPAR

Frequency

• freeze_mode: "none", "layers", "z_range", "element", "indices", "manual"
• freeze_layers: number of bottom layers to freeze
• freeze_z_below: freeze atoms below this z coordinate (Angstrom)

Gibbs Energy

• phase: "adsorbed" (harmonic) or "gas" (ideal gas)
• temperature: K (default 298.15)
• freq_cutoff: cm-1 (default 50, for adsorbed phase)

Output References

Connect tasks by passing .output.key:

opt.output.structure   # optimized structure
opt.output.energy      # DFT energy (eV)
frq.output.frequencies # vibrational frequencies
frq.output.zpe         # zero-point energy
gib.output.gibbs       # Gibbs free energy

Workflow Patterns

OER Overpotential

for ads in ["OH", "O", "OOH"]:
    opt = wf.add_task(geo_opt, structure=slab.output.structure,
                      system_name=f"*{ads}")
    frq = wf.add_task(freq, structure=opt.output.structure,
                      freeze_mode="layers", freeze_layers=4)
    gib = wf.add_task(gibbs_energy, energy=opt.output.energy,
                      frequencies=frq.output.frequencies, phase="adsorbed")

Convergence Test

for encut in [400, 500, 600, 700]:
    wf.add_task(single_point, structure=struct.output.structure,
                ENCUT=encut, system_name=f"ENCUT={encut}")