hello-qm/catgo-lrg/convergence-issues

Convergence Issues Troubleshooting Skill

When to Use

Use this skill when:

• A calculation finishes but did not converge (warnings in output)
• SCF (electronic) iterations hit NELM without converging
• Ionic relaxation oscillates or does not reach force threshold
• Energy keeps changing between ionic steps
• ORCA SCF or geometry optimization fails to converge

Diagnostic Step

Always start by checking the convergence history:

catgo_analyze(action: "convergence", params: {
  workflow_id: "<wf_id>",
  task_id: "<task_id>"
})

This returns SCF energy per iteration and forces per ionic step, making it easy to see whether the problem is electronic or ionic.

SCF (Electronic) Convergence

Symptoms

• "NELM reached" warning in VASP output
• Energy oscillates or diverges across SCF iterations
• ORCA prints "SCF NOT CONVERGED"

VASP SCF Fixes

Fix 1: Change mixing algorithm (ALGO)

catgo_workflow_engine(action: "modify_params", params: {
  workflow_id: "<wf_id>",
  task_id: "<task_id>",
  params: { "ALGO": "All" }
})

Fix 2: Adjust charge density mixing (AMIX/BMIX)

Default values work for most bulk systems. For surfaces, slabs, molecules in vacuum, or magnetic systems, reduce mixing:

catgo_workflow_engine(action: "modify_params", params: {
  workflow_id: "<wf_id>",
  task_id: "<task_id>",
  params: {
    "AMIX": 0.1,
    "BMIX": 0.01,
    "AMIX_MAG": 0.2,
    "BMIX_MAG": 0.01
  }
})

Lower AMIX = more conservative mixing = slower but more stable convergence.

Fix 3: Increase maximum SCF steps (NELM)

Default NELM is 60. If the SCF is converging but slowly:

catgo_workflow_engine(action: "modify_params", params: {
  workflow_id: "<wf_id>",
  task_id: "<task_id>",
  params: { "NELM": 200 }
})

Fix 4: Correct ISMEAR for your system type

Using ISMEAR=-5 (tetrahedron) for metals with few k-points causes convergence failures. Using ISMEAR=1 for insulators can cause incorrect occupations.

catgo_workflow_engine(action: "modify_params", params: {
  workflow_id: "<wf_id>",
  task_id: "<task_id>",
  params: { "ISMEAR": 0, "SIGMA": 0.05 }
})

Fix 5: Start from a converged WAVECAR

If a similar calculation has converged, use its WAVECAR as starting point. This is handled automatically by CatGo's workflow engine when chaining tasks.

ORCA SCF Fixes

Add keywords to orca_extra_keywords:

catgo_workflow_engine(action: "modify_params", params: {
  workflow_id: "<wf_id>",
  task_id: "<task_id>",
  params: { "orca_extra_keywords": "SlowConv SOSCF" }
})

Ionic (Geometry) Convergence

Symptoms

• NSW reached without forces dropping below EDIFFG
• Total energy oscillates between ionic steps
• Atoms move back and forth between two configurations

Fix 1: Adjust force convergence (EDIFFG)

VASP default EDIFFG=-0.05 eV/A is reasonable. If too tight:

catgo_workflow_engine(action: "modify_params", params: {
  workflow_id: "<wf_id>",
  task_id: "<task_id>",
  params: { "EDIFFG": -0.03 }
})

Negative EDIFFG = force criterion (recommended). Positive = energy criterion.

Fix 2: Increase maximum ionic steps (NSW)

catgo_workflow_engine(action: "modify_params", params: {
  workflow_id: "<wf_id>",
  task_id: "<task_id>",
  params: { "NSW": 300 }
})

Fix 3: Change ionic optimizer (IBRION)

If CG (IBRION=2) oscillates, switch to quasi-Newton:

catgo_workflow_engine(action: "modify_params", params: {
  workflow_id: "<wf_id>",
  task_id: "<task_id>",
  params: { "IBRION": 1 }
})

Fix 4: Reduce step size (POTIM)

If atoms jump too far each step:

catgo_workflow_engine(action: "modify_params", params: {
  workflow_id: "<wf_id>",
  task_id: "<task_id>",
  params: { "POTIM": 0.1 }
})

Default POTIM is 0.5 for IBRION=1/2.

Common Mistakes

• Fixing ionic convergence when the real problem is SCF (always check SCF first)
• Using tetrahedron smearing (ISMEAR=-5) for relaxation (only for static calcs)
• Setting EDIFFG too tight for the basis set quality
• Not checking if the structure is physically reasonable before tweaking params