Phonopy

• a valid initial structure (unit cell / primitive context)
• force data on displaced supercells (or precomputed force constants)

If either is missing, stop and ask for it.

Backend abstraction

Force provider may be one of:

• DFT backend (for example VASP or QE)
• ML force field backend (for example DeePMD/LAMMPS)

The role split should be:

1. phonopy skill: displacement generation, dataset/force-constant assembly, phonon analysis
2. backend skill: compute forces for each displaced supercell

Expected workflow

1. Read and validate initial structure.
2. Confirm phonon objective (band, dos, thermal, combinations).
3. Choose supercell and displacement settings.
4. Generate displaced supercells (phonopy -d style).
5. Route displaced structures to selected backend for force evaluation.
6. Collect forces and build FORCE_SETS or force constants.
7. Run requested phonon analysis and export outputs.
8. Report assumptions, convergence caveats, and next steps.

For concrete command patterns, see references/commands-and-workflow.md.

Parameters to collect

Must provide

• initial structure file (placeholder examples like structure.ext mean real files such as POSCAR, .cif, or other backend-compatible structure formats)
• backend choice for force evaluation
• supercell setting (matrix or size)
• displacement amplitude (--amplitude policy)
• target phonon outputs (band, dos, thermal)

Usually should be explicit

• primitive matrix choice
• symmetry tolerance settings
• q-point mesh for DOS/thermal calculations
• band path definition source (if band requested)

Task-specific

For band:

• high-symmetry path definition
• number of points per segment

For dos/thermal:

• mesh density
• temperature range/step for thermal properties

Required behavior

1. Validate structure periodicity and cell.
2. Make backend boundary explicit before running force steps.
3. Keep traceable mapping between each displacement and force file.
4. Check force dataset completeness before force-constant build.
5. Report non-analytic corrections / long-range settings status when relevant.
6. Flag unresolved scientific choices instead of guessing silently.

Defaulting policy

Allowed only for low-risk defaults with explicit labels.

Reasonable defaults:

• finite-displacement workflow as baseline
• moderate displacement amplitude for first pass
• standard mesh/band resolution for exploratory analysis

Do not silently invent:

• backend force results
• production-level convergence settings
• band path conventions when crystal standard is unclear

Expected output

Provide:

1. generated displacement task layout
2. force-data assembly status (FORCE_SETS/force constants)
3. requested phonon outputs (band/DOS/thermal files)
4. explicit assumptions and unresolved decisions
5. handoff guidance if backend execution/submission is pending

GPUMD integration

GPUMD has its own built-in harmonic phonon capability via compute_phonon, which directly outputs phonon dispersions and DOS without phonopy. Use phonopy when:

• you need finite-displacement phonons with a DFT force backend (not NEP)
• you need thermal properties (free energy, heat capacity, entropy)
• you want to cross-validate GPUMD compute_phonon results
• you need Phono3py for anharmonic / thermal conductivity analysis

GPUMD force-constant output can also serve as input for phonopy-based post-processing when the force provider is a NEP potential evaluated through GPUMD or ASE.

Common failure points

• missing or inconsistent force files for displacements
• supercell too small for stable phonon results
• inconsistent units/conventions across backend outputs
• imaginary modes caused by insufficient convergence or setup choices
• unclear band path convention for non-standard cells