# Claude Code Integration

```{admonition} ❌ ✅ Claude Code Generated
:class: warning
This guide was generated by Claude Code and has not yet been human-verified. Remove the ❌ after review.
```

The vasp-ase package includes deep integration with Claude Code, Anthropic's AI coding assistant.

## Installation

After installing vasp-ase, install the Claude Code skills globally:

```bash
vasp-claude install
```

This makes Claude aware of VASP-ASE in any project you work on.

### What Gets Installed

**Skills** (`~/.claude/skills/`):
- `vasp.md` - Main VASP knowledge and code patterns
- `job-watcher.md` - Job monitoring and troubleshooting
- `troubleshoot.md` - Common error diagnosis

**Commands** (`~/.claude/commands/`):
- `/vasp-help <topic>` - Parameter reference
- `/vasp-watch-job <dir>` - Monitor running job
- `/vasp-fix-job <dir>` - Diagnose and fix failed job
- `/vasp-examples` - List tutorials
- `/vasp-tutorial <n>` - View specific tutorial
- `/vasp-docs` - Documentation access

### Check Status

```bash
vasp-claude status
```

### Uninstall

```bash
vasp-claude uninstall
```

## Using Claude for VASP

Once installed, Claude automatically helps with VASP when you ask. Examples:

### Ask About Parameters

```
User: What's the difference between ISMEAR 0 and -5?

Claude: ISMEAR controls the smearing method:
- ISMEAR=0: Gaussian smearing, good for molecules and insulators
- ISMEAR=-5: Tetrahedron method, most accurate for DOS but requires ≥4 k-points
...
```

### Get Code Help

```
User: How do I run a DOS calculation?

Claude: Here's how to calculate DOS with vasp-ase:

from ase.build import bulk
from vasp import Vasp

# Step 1: SCF calculation
atoms = bulk('Si')
calc_scf = Vasp(
    atoms=atoms,
    xc='PBE',
    encut=400,
    kpts=(8, 8, 8),
    lcharg=True,
)
...
```

### Troubleshooting

```
User: My VASP job shows ZBRENT error

Claude: ZBRENT indicates electronic convergence failure. Try:
1. Increase NELM: nelm=200
2. Use different algorithm: algo='VeryFast'
3. Adjust mixing: amix=0.1, bmix=0.01
...
```

## Job Monitoring

### Watch a Running Job

```
User: /vasp-watch-job /scratch/my_calc

Claude: Checking job in /scratch/my_calc...

Status: RUNNING
Current step: Ionic step 15 of 100
Last energy: -245.3421 eV
Time per step: ~45 seconds
Estimated completion: ~1 hour
```

### Fix a Failed Job

```
User: /vasp-fix-job /scratch/failed_calc

Claude: Analyzing failed job...

Diagnosis: Electronic convergence failed (ZBRENT error)
- NELM reached maximum (60 steps)
- Energy oscillating, not converging

Suggested fixes:
  ALGO: Normal → VeryFast
  NELM: 60 → 200
  AMIX: 0.2 → 0.1
  BMIX: 0.1 → 0.01

CONTCAR found - will restart from last geometry.

Apply fixes and restart? [y/n]
```

## Project-Specific Setup

When working in the vasp-ase repository, additional commands are available:

| Command | Description |
|---------|-------------|
| `/docs` | Open documentation |
| `/examples` | List all examples |
| `/tutorial <n>` | View tutorial n |
| `/test` | Run tests |
| `/new-example` | Create new example |
| `/architecture` | Review codebase |
| `/lint` | Run code quality checks |
| `/build-docs` | Build Jupyter Book |

## Skills Reference

### VASP Calculation Skill

Claude knows how to:
- Create structures with ASE
- Set up VASP calculators
- Use parameter presets (VdW, DFT+U, HSE06)
- Run calculations with different runners
- Parse results

### Troubleshooting Skill

Claude can diagnose:
- Electronic convergence issues
- Ionic convergence problems
- Memory errors
- Magnetic convergence
- K-point and smearing issues

### Job Watcher Skill

Claude can:
- Check job status (running/completed/failed)
- Analyze OUTCAR for errors
- Suggest parameter fixes
- Restart from CONTCAR
- Set up continuous monitoring

## Best Practices

1. **Be specific**: "Calculate the band gap of Si with HSE06" is better than "run a calculation"

2. **Provide context**: Share error messages, OUTCAR snippets, or current parameters

3. **Use commands**: `/vasp-help encut` is faster than asking "what is ENCUT?"

4. **Let Claude watch jobs**: Ask Claude to monitor long-running calculations

5. **Review fixes**: Always review Claude's suggested fixes before applying

## Extending

You can add custom skills and commands in your project's `.claude/` directory:

```
my_project/.claude/
├── commands/
│   └── my-workflow.md
└── skills/
    └── my-material.md
```

See the [Claude Code documentation](https://docs.anthropic.com/claude-code) for details.
