convergence-issues

name	convergence_issues
description	Diagnose and fix SCF and ionic convergence failures in VASP and ORCA. Covers ALGO, mixing parameters, ISMEAR, NELM, EDIFFG, NSW, and IBRION settings.

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)

ALGO value	Method	Best for
Normal	Davidson	Simple semiconductors, insulators
Fast	Davidson + RMM-DIIS	Default, most systems
All	Davidson + RMM-DIIS (combined)	Difficult metals, surfaces
Damped	Damped velocity	Very difficult convergence
VeryFast	RMM-DIIS only	Large systems (>500 atoms)

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

System type	ISMEAR	SIGMA
Metal	1 (Methfessel-Paxton)	0.2
Semiconductor/insulator	0 (Gaussian)	0.05
Molecule in box	0 (Gaussian)	0.01
DOS calculation	-5 (tetrahedron)	N/A

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:

Problem	Fix keyword	Description
Slow convergence	SlowConv	Dampened SCF
Very slow	VerySlowConv	More conservative
Oscillating	SOSCF	Second-order SCF
Near-degenerate	SmearTemp 5000	Fermi smearing
Level shifting	Shift 0.3	Shift virtual orbitals up

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)

IBRION	Method	Best for
1	Quasi-Newton (RMM-DIIS)	Near-minimum structures
2	Conjugate gradient	Far from minimum (default)
3	Damped MD	Very distorted structures

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