---
name: siesta
description: >
  Generate and manage SIESTA DFT calculations. Use when the user requests
  SIESTA, numeric atomic orbital (NAO) DFT, or linear-scaling DFT for large systems.
compatibility: >
  Requires SIESTA installed on the HPC target. Pseudopotential files (.psf or .psml)
  must be available for all elements.
---

# SIESTA

## When to Use

- User explicitly requests SIESTA
- User needs linear-scaling O(N) DFT for very large systems (1000+ atoms)
- User wants numeric atomic orbital (NAO) basis sets
- User needs TDDFT or electron transport (TranSIESTA)

## Prerequisites

1. SIESTA binary accessible on HPC (`siesta --version`)
2. Pseudopotentials available (.psf or .psml format)
3. Structure loaded in viewer — verify with `catgo_view(action="get_state")`

## Workflow Steps

### 1. Verify structure

```
catgo_view(action="get_state")
```

### 2. Create workflow

```
catgo_workflow_engine(action="create", params={"name": "SIESTA relaxation"})
```

### 3. Add SIESTA task via shell

CatGo does not yet have a native SIESTA engine. Use `task_type: "shell"`.

```
catgo_workflow_engine(action="add_task", params={
  "workflow_id": "wf_xxx",
  "task_type": "shell",
  "name": "siesta_relax",
  "command": "siesta < input.fdf > siesta.out 2>&1",
  "input_files": {
    "input.fdf": "<FDF input content>",
    "Si.psf": "{{pseudo_dir}}/Si.psf"
  },
  "system_name": "Si_bulk"
})
```

When a `@register_engine("siesta")` is added, use `task_type: "geo_opt"` with `software: "siesta"`.

## Input File Template — SCF

```
SystemName    TiO2_rutile
SystemLabel   tio2

NumberOfAtoms   <natoms>
NumberOfSpecies <nspecies>

%block ChemicalSpeciesLabel
  1  22  Ti
  2   8  O
%endblock ChemicalSpeciesLabel

PAO.BasisSize     DZP
PAO.EnergyShift   100 meV

LatticeConstant   1.0 Ang
%block LatticeVectors
  <a1x> <a1y> <a1z>
  <a2x> <a2y> <a2z>
  <a3x> <a3y> <a3z>
%endblock LatticeVectors

AtomicCoordinatesFormat Ang
%block AtomicCoordinatesAndAtomicSpecies
  <x> <y> <z>  <species_index>
%endblock AtomicCoordinatesAndAtomicSpecies

# Mesh and K-points
MeshCutoff        300 Ry
%block kgrid_Monkhorst_Pack
  <k1>  0  0  0.0
  0  <k2>  0  0.0
  0  0  <k3>  0.0
%endblock kgrid_Monkhorst_Pack

# SCF
MaxSCFIterations  200
DM.MixingWeight   0.1
DM.Tolerance      1.0d-4
XC.functional     GGA
XC.authors        PBE

# Electronic temperature
ElectronicTemperature  300 K
```

## Relaxation Parameters

Add for geometry optimization:

```
MD.TypeOfRun      CG           # Conjugate gradient
MD.NumCGsteps     200
MD.MaxForceTol    0.02 eV/Ang
MD.VariableCell   .false.      # .true. for bulk cell optimization
```

For slabs, constrain atoms via `%block GeometryConstraints`.

## Parameter Guidance

| Parameter | Typical value | Notes |
|---|---|---|
| PAO.BasisSize | SZ / DZ / DZP / TZP | Single/double/triple-zeta + polarization |
| PAO.EnergyShift | 50-200 meV | Basis confinement; lower = more diffuse, more accurate |
| MeshCutoff | 200-400 Ry | Real-space grid fineness; 300 Ry usually sufficient |
| DM.MixingWeight | 0.05-0.3 | SCF mixing; lower for metals/difficult convergence |
| DM.Tolerance | 1.0d-4 | Density matrix convergence criterion |
| MaxSCFIterations | 200 | Increase for difficult systems |

## Common Pitfalls

1. **MeshCutoff in Ry, not eV** — 300 Ry = 4082 eV. Do not confuse with plane-wave cutoff.
2. **Basis set quality** — SZ is fast but inaccurate; DZP is the practical minimum for publishable results
3. **Ghost atoms** — PAO.EnergyShift too large can cause basis-set superposition error (BSSE)
4. **Pseudopotential format** — use .psf (Siesta native) or .psml (PSML standard). Not UPF.
5. **Linear scaling** — enable with `SolutionMethod OrderN` only for >1000 atoms with a gap. Metals need diagonalization.
6. **Coordinate format** — verify `AtomicCoordinatesFormat` matches your data (Ang vs Fractional vs Bohr)
7. **Memory for diagonalization** — large systems with `SolutionMethod diagon` need significant memory; consider OrderN or parallelization