PHONOPY(1)

📦
version 2.48.0 · 6 versions
, in ubuntu stonking

🫶 PHONOPY(1) — phonopy 2.48.0, explained by your bestie 🫶

okay so bestie, you opened the manual page for phonopy, the phonopy command-line-tool, version 2.48.0, and it is long. like, unnecessarily long. but don't panic 💖 we're getting through every single flag together, no skipping, no summarising, because every one of these little guys matters. grab a strawberry drink 🍓 and let's go.

🌸 NAME

phonopy — the manual page for phonopy 2.48.0 ✨

💅 DESCRIPTION

here's the usage line in all its glory, and yes, it is giving "the whole keyboard got dumped into one line":

usage: phonopy [-h] [--abacus] [--abinit] [--aims] [--castep] [--cp2k]
       [--crystal] [--dftb+] [--elk] [--fleur] [--lammps] [--qlm] [--qe]
       [--siesta] [--turbomole] [--vasp] [--wien2k] [--pwmat] [--alm]
       [--amplitude DISPLACEMENT_DISTANCE] [--amax
       DISPLACEMENT_DISTANCE_MAX] [--anime ANIME [ANIME ...]]  [--band
       BAND_PATHS [BAND_PATHS ...]] [--band-connection]
       [--band-const-interval] [--band-labels BAND_LABELS [BAND_LABELS
       ...]]  [--band-format BAND_FORMAT] [--band-points BAND_POINTS]
       [--bi BAND_INDICES [BAND_INDICES ...]] [-c FILE] [--classical]
       [--cutoff-freq CUTOFF_FREQUENCY] [--cutoff-radius CUTOFF_RADIUS]
       [-d] [--dim SUPERCELL_DIMENSION [SUPERCELL_DIMENSION ...]]
       [--dm-decimals DYNAMICAL_MATRIX_DECIMALS] [--dos] [--eigvecs] [-f
       CREATE_FORCE_SETS [CREATE_FORCE_SETS ...]]  [--factor
       FREQUENCY_CONVERSION_FACTOR] [--fc FILE] [--fc-calc
       FC_CALCULATOR] [--fc-calc-opt FC_CALCULATOR_OPTIONS]
       [--fc-decimals FORCE_CONSTANTS_DECIMALS] [--fc-format FC_FORMAT]
       [--fc-spg-symmetry] [--fc-symmetry] [--fits-debye-model]
       [--full-fc] [--fz CREATE_FORCE_SETS_ZERO [CREATE_FORCE_SETS_ZERO
       ...]]  [--fmax FMAX] [--fmin FMIN] [--fpitch FPITCH] [--gc]
       [--gv] [--gv-delta-q GV_DELTA_Q] [--hdf5] [--hdf5-compression
       HDF5_COMPRESSION] [--irreps IRREPS_QPOINT [IRREPS_QPOINT ...]]
       [--include-fc] [--include-fs] [--include-disp] [--include-all]
       [--legend] [--legacy-plot] [--lcg] [--loglevel LOGLEVEL] [--mass
       MASSES [MASSES ...]] [--mass-ase-iupac2016] [--magmom MAGMOMS
       [MAGMOMS ...]] [--mesh-format MESH_FORMAT] [--modulation
       MODULATION [MODULATION ...]]  [--mp MESH_NUMBERS [MESH_NUMBERS
       ...]]  [--mlp-params MLP_PARAMS] [--moment] [--moment-order
       MOMENT_ORDER] [--nac] [--nac-method NAC_METHOD] [--nodiag]
       [--nomeshsym] [--nosym] [--nowritemesh] [-p] [--pa PRIMITIVE_AXES
       [PRIMITIVE_AXES ...]]  [--pd PROJECTION_DIRECTION
       [PROJECTION_DIRECTION ...]]  [--pdos PDOS [PDOS ...]] [--pm]
       [--pr] [--pt] [--pypolymlp] [--qpoints QPOINTS [QPOINTS ...]]
       [--qpoints-format QPOINTS_FORMAT] [--q-direction NAC_Q_DIRECTION
       [NAC_Q_DIRECTION ...]] [-q] [--random-seed RANDOM_SEED] [--rd
       RANDOM_DISPLACEMENTS] [--rd-auto-factor
       RD_NUMBER_ESTIMATION_FACTOR] [--rd-temperature TEMPERATURE]
       [--readfc] [--readfc-format READFC_FORMAT] [--read-qpoints]
       [--relax-atomic-positions] [-s] [--sp] [--show-irreps] [--sigma
       SIGMA] [--sscha SSCHA_ITERATIONS] [--symfc] [--symmetry] [-t]
       [--td] [--tdm] [--tdm-cif TEMPERATURE] [--temperature
       TEMPERATURE] [--tmax TMAX] [--tmin TMIN] [--tolerance
       SYMMETRY_TOLERANCE] [--trigonal] [--tstep TSTEP] [-v]
       [--wien2k-p1] [--writefc] [--writefc-format WRITEFC_FORMAT]
       [--writedm] [--xyz-projection] [filename ...]

Phonopy command-line-tool 👑

one tool. a hundred-ish ways to tell it what you want. iconic honestly.

🎀 positional arguments

  • filename — this is your Phonopy configure file. buuut if that file gets recognized as a phonopy.yaml-like file, then it gets read as a phonopy.yaml-like file instead. same slot, two personalities 💅

✨ options

deep breath. here we go.

  • -h, --help — shows this help message and then dips. the classic escape hatch 🙈
heads up bestie: a whole pile of these are just "which DFT code are we talking to" switches. pick your fave, no judgement.
  • --abacus — Invoke ABACUS mode
  • --abinit — Invoke Abinit mode
  • --aims — Invoke FHI-aims mode
  • --castep — Invoke CASTEP mode
  • --cp2k — Invoke CP2K mode
  • --crystal — Invoke CRYSTAL mode
  • --dftb+ — Invoke dftb+ mode
  • --elk — Invoke elk mode
  • --fleur — Invoke Fleur mode
  • --lammps — Invoke Lammps mode
  • --qlm — Invoke Questaal/LMTO mode
  • --qe — Invoke Quantum espresso (QE) mode
  • --siesta — Invoke Siesta mode
  • --turbomole — Invoke TURBOMOLE mode
  • --vasp — Invoke Vasp mode
  • --wien2k — Invoke Wien2k mode
  • --pwmat — Invoke PWmat mode
  • --alm — Use ALM for generating force constants. force constants, but make it ALM 🫶
  • --amplitude, --amin DISPLACEMENT_DISTANCE — Distance of displacements — and also the minimum distance of displacements in random displacements. two jobs, one flag, main character energy ✨
  • --amax DISPLACEMENT_DISTANCE_MAX — Minimum distance of displacements in random displacements
  • --anime ANIME [ANIME ...] — Same as ANIME tag
  • --band BAND_PATHS [BAND_PATHS ...] — Same behavior as BAND tag
  • --band-connection — Treat band crossings. letting the bands actually touch, as they deserve 💀
  • --band-const-interval — Band paths are sampled with similar interval.
  • --band-labels BAND_LABELS [BAND_LABELS ...] — Show labels at band segments
  • --band-format BAND_FORMAT — Band structure output file-format
  • --band-points BAND_POINTS — Number of points calculated on a band segment in the band structure mode
  • --bi, --band-indices BAND_INDICES [BAND_INDICES ...] — Band indices to be included to calculate thermal properties
  • -c, --cell FILE — Read unit cell
  • --classical — Compute thermodynamic properties using classical statistics.
  • --cutoff-freq, --cutoff-frequency CUTOFF_FREQUENCY — Thermal properties are not calculated below this cutoff frequency.
  • --cutoff-radius CUTOFF_RADIUS — Out of cutoff radius, force constants are set zero.
  • -d, --displacement — Create supercells with displacements
  • --dim SUPERCELL_DIMENSION [SUPERCELL_DIMENSION ...] — Same behavior as DIM tag
  • --dm-decimals DYNAMICAL_MATRIX_DECIMALS — Decimals of values of decimals 😭 that's literally what it says, bestie. it's about how many decimals the dynamical matrix values get.
  • --dos — Calculate (P)DOS
  • --eigvecs, --eigenvectors — Output eigenvectors
  • -f, --force-sets CREATE_FORCE_SETS [CREATE_FORCE_SETS ...] — Create FORCE_SETS
  • --factor FREQUENCY_CONVERSION_FACTOR — Frequency unit conversion factor
  • --fc, --force-constants FILE — Create FORCE_CONSTANTS from vaspurn.xml. vasprun.xml has to be passed as argument.
  • --fc-calc, --fc-calculator FC_CALCULATOR — Force constants calculator
  • --fc-calc-opt, --fc-calculator-options FC_CALCULATOR_OPTIONS — Options for force constants calculator as comma separated string with the style of key = values
  • --fc-decimals FORCE_CONSTANTS_DECIMALS — Decimals of values of force constants
  • --fc-format FC_FORMAT — Force constants input/output file-format
  • --fc-spg-symmetry — Enforce space group symmetry to force constants
  • --fc-symmetry, --sym-fc — Symmetrize force constants. symmetry check: passed 💅
  • --fits-debye-model — Fits total DOS to a Debye model
  • --full-fc — Calculate full supercell force constants matrix
  • --fz, --force-sets-zero CREATE_FORCE_SETS_ZERO [CREATE_FORCE_SETS_ZERO ...] — Create FORCE_SETS. disp.yaml in the current directory and vapsrun.xml's for VASP or case.scf(m) for Wien2k as arguments are required. The first argument is that of the perfect supercell to subtract residual forces
  • --fmax FMAX — Maximum frequency used for DOS or moment calculation
  • --fmin FMIN — Minimum frequency used for DOS or moment calculation
  • --fpitch FPITCH — Frequency pitch used for DOS or moment calculation
  • --gc, --gamma-center — Set mesh as Gamma center
  • --gv, --group-velocity — Calculate group velocities at q-points
  • --gv-delta-q GV_DELTA_Q — Delta-q distance used for group velocity calculation
  • --hdf5 — Use hdf5 for force constants
  • --hdf5-compression HDF5_COMPRESSION — hdf5 compression filter (default: "gzip") and "none" for no compression
  • --irreps, --irreps-qpoint IRREPS_QPOINT [IRREPS_QPOINT ...] — A q-point where characters of irreps are calculated
  • --include-fc — Include force constants in phonopy.yaml
  • --include-fs — Include force sets in phonopy.yaml
  • --include-disp — Include displacements in phonopy.yaml
  • --include-all — Include all output file data in phonopy.yaml
  • --legend — Legend of plots is shown in thermal displacements
  • --legacy-plot — Legacy style band structure plot
  • --lcg, --little-cogroup — Show irreps of little co-group (or point-group of wave vector q) instead of little group
  • --loglevel LOGLEVEL — Log level
  • --mass MASSES [MASSES ...] — Same as MASS tag
  • --mass-ase-iupac2016 — Import atomic weights from ASE according to IUPAC 2016
  • --magmom MAGMOMS [MAGMOMS ...] — Same as MAGMOM tag
  • --mesh-format MESH_FORMAT — Mesh output file-format
  • --modulation MODULATION [MODULATION ...] — Same as MODULATION tag
  • --mp, --mesh MESH_NUMBERS [MESH_NUMBERS ...] — Same behavior as MP tag
  • --mlp-params MLP_PARAMS — Parameters for machine learning potentials as comma separated string with the style of key = values
  • --moment — Calculate moment of phonon states distribution
  • --moment-order MOMENT_ORDER — Order of moment of phonon states distribution
  • --nac — Non-analytical term correction
  • --nac-method NAC_METHOD — Non-analytical term correction method: Gonze (default) or Wang
  • --nodiag — Set displacements parallel to axes
  • --nomeshsym — Symmetry is not imposed for mesh sampling.
  • --nosym — Symmetry is not imposed.
  • --nowritemesh — Do not write mesh.yaml or mesh.hdf5
  • -p, --plot — Plot data 📈
  • --pa, --primitive-axis, --primitive-axes PRIMITIVE_AXES [PRIMITIVE_AXES ...] — Same as PRIMITIVE_AXES tag
  • --pd, --projection-direction PROJECTION_DIRECTION [PROJECTION_DIRECTION ...] — Same as PROJECTION_DIRECTION tag
  • --pdos PDOS [PDOS ...] — Same as PDOS tag
  • --pm — Set plus minus displacements
  • --pr, --pretend-real — Use imaginary frequency as real for thermal property calculation. For a testing purpose only, when a small amount of imaginary branches obtained.
  • --pt, --projected-thermal-property — Output projected thermal properties
  • --pypolymlp — Use pypolymlp for generating force constants
  • --qpoints QPOINTS [QPOINTS ...] — Calculate at specified q-points
  • --qpoints-format QPOINTS_FORMAT — Q-points output file-format
  • --q-direction NAC_Q_DIRECTION [NAC_Q_DIRECTION ...] — Direction of q-vector perturbation used for NAC at q->0, and group velocity for degenerate phonon mode in q-points mode
  • -q, --quiet — Print out smallest information. minimal words, maximum mystery 🤫
  • --random-seed RANDOM_SEED — Random seed by a 32 bit unsigned integer
  • --rd, --random-displacements RANDOM_DISPLACEMENTS — the number of supercells you want built with random displacements, or the literal string "auto" if you'd rather let phonopy do the thinking 🎲
  • --rd-auto-factor RD_NUMBER_ESTIMATION_FACTOR — a factor used to estimate how many supercells with random displacements you're gonna need 📐
  • --rd-temperature TEMPERATURE — a temperature to generate those random displacements at 🌡️
  • --readfc — read force constants straight from a file 📂
  • --readfc-format READFC_FORMAT — tells it what file-format those incoming force constants are in 🔤
  • --read-qpoints — read QPOITNS (yes, that spelling is the original's, we don't fix icons in this house 💅)
  • --relax-atomic-positions — relax your atomic positions using polynomial MLPs 🛋️
  • -s, --save — save the plot data as a pdf, so you can stare at it forever 🖼️
  • --sp, --save-params — saves the parameters that can run phonopy into phonopy_params.yaml 📝
  • --show-irreps — shows the IR-Reps along with their characters ✨
  • --sigma SIGMA — the smearing width for DOS 🌫️
  • --sscha SSCHA_ITERATIONS — how many iterations happen in an SSCHA calculation 🔁
  • --symfc — use symfc to generate force constants 🧮
  • --symmetry — check the crystal symmetry 🔍
  • -t, --thermal-property — output thermal properties 🔥
  • --td, --thermal-displacements — output thermal displacements 🌊
  • --tdm, --thermal-displacement-matrix — output thermal displacement matrices 📊
  • --tdm-cif, --thermal-displacement-matrix-cif TEMPERATURE — writes a cif with aniso_U for whichever temperature you specify 🧊
  • --temperature TEMPERATURE — (Deprecated!) a temperature used to generate random displacements ⚠️
  • --tmax TMAX — the maximum calculated temperature 🔺
  • --tmin TMIN — the minimum calculated temperature 🔻
  • --tolerance SYMMETRY_TOLERANCE — the symmetry tolerance used when searching 🎯
  • --trigonal — sets the displacements of all trigonal axes 🔺✨
  • --tstep TSTEP — the calculated temperature step 👣
  • -v, --verbose — shows you the detailed information, the whole tea ☕
  • --wien2k-p1 — assumes Wien2k structs that have displacements are P1 🧪
  • --writefc — writes FORCE_CONSTANTS ✍️
  • --writefc-format WRITEFC_FORMAT — the file-format your force constants get written out in 🔡
  • --writedm — writes dynamical matrices. 🚨 it has to be used together with the QPOINTS setting (or --qpoints) — no solo runs, this one needs its plus-one 👯
  • --xyz-projection — projects PDOS x, y, z directions in Cartesian coordinates 📈

and that's a wrap bestie — that's every last flag shipped with this version, no crumbs left behind 🍓 This whole manual is for phonopy 2.48.0, dated February 2026, and it lives at the top of the page as PHONOPY(1). Now go displace something, you absolute icon 👑🦋💜

📦 where this page comes from