CLI Reference

This page provides documentation for our command line tools.

easyunfold

Tool for performing band unfolding

easyunfold [OPTIONS] COMMAND [ARGS]...

generate

Generate the kpoints for performing supercell calculations.

There are two modes of running supercell calculations:

1. Use the generated kpoints for unfolding for non-SCF calculations, e.g. with a fixed charged density from the SCF calculation.

2. Include the generated kpoints in SCF calculation but set their weights to zeros.

In both cases, the kpoints can be split into multiple calculations.

This command defaults to go down the first route where the kpoints generated are only those needed for the unfolding, all kpoints and written into the same file, but the user is free to manually split them into multiple calculations. The second approach can be activated with the --nk-per-split option and in the same time provide the --scf-kpoints. This will generate a serial of kpoints files containing the SCF kpoints followed by the actual kpoints needed for unfolding with zero weights.

easyunfold generate [OPTIONS] PC_FILE SC_FILE KPOINTS

Options

--time-reversal, --no-time-reversal

Whether to assume time-reversal symmetry.

Default:

True

-c, --code <code>

Name of the DFT code that the kpoints should be formatted to.

Default:

vasp

Options:

vasp | castep

-m, --matrix <matrix>

Transformation matrix, in the form “x y z” for a diagonal matrix, or “x1 y1 z1 x2 y2 z2 x3 y3 z3” for a 3x3 matrix. Automatically guessed if not provided.

--symprec <symprec>

Tolerance for determining the symmetry

Default:

1e-05

-o, --out-file <out_file>

Name of the output file

--no-expand

Do not expand the kpoints by symmetry

--nk-per-split <nk_per_split>

Number of band structure kpoints per split.

--separate-folders, --no-separate-folders

Whether to use separate folders for each split.

Default:

False

--scf-kpoints <scf_kpoints>

File (IBZKPT) to provide SCF kpoints for self-consistent calculations. Needed for hybrid functional calculations.

Arguments

PC_FILE

Required argument

SC_FILE

Required argument

KPOINTS

Required argument

unfold

Perform unfolding and plotting

There are multiple sub-command available under this command group.

easyunfold unfold [OPTIONS] COMMAND [ARGS]...

Options

-d, --data-file <data_file>

Default:

easyunfold.json

calculate

Perform the unfolding

Multiple wave function (e.g. the WAVECAR file if using VASP) files can be supplied for split-path calculations. Once the calculation is done, the wave function data are not longer needed as the spectral weights will be stored in the outputs json file.

easyunfold unfold calculate [OPTIONS] [WAVEFUNC]...

Options

--save-as <save_as>

--gamma

If the calculation is $Gamma$-only

--ncl

If the calculation has non-collinear spins.

Arguments

WAVEFUNC

Optional argument(s)

effective-mass

Compute and print effective masses by tracing the unfolded weights.

Note that this functionality only works for simple unfolded band structures, and it is likely to fail for complex cases.

Use the --plot-fit flag to generate the detected band edge verses the parabolic fit for visual confirmation if unsure.

easyunfold unfold effective-mass [OPTIONS]

Options

-m, --mpl-style-file <mpl_style_file>

Specify custom plotting mplstyle file

--intensity-threshold <intensity_threshold>

Intensity threshold for detecting valid bands.

Default:

0.1

--spin <spin>

Index of the spin channel.

Default:

0

--npoints <npoints>

Number of kpoints used for fitting from the extrema.

Default:

3

--extrema-detect-tol <extrema_detect_tol>

Tolerance for band extrema detection.

Default:

0.01

--nocc <nocc>

DEV: Use this band as the extrema at all kpoints.

--plot

--plot-fit

Generate plots of the band edge and parabolic fits.

--fit-label <fit_label>

Which branch to use for plot fitting. e.g. electrons:0

Default:

electrons:0

--band-filter <band_filter>

Only displace information for this band.

-o, --out-file <out_file>

Name of the output file.

Default:

unfold-effective-mass.png

--emin <emin>

Minimum energy in eV relative to the reference.

Default:

-5.0

--emax <emax>

Maximum energy in eV relative to the reference.

Default:

5.0

--manual-extrema <manual_extrema>

Manually specify the extrema to use for fitting, in the form “mode,k_index,band_index”

plot

Plot the spectral function

This command uses the stored unfolding data to plot the effective bands structure (EBS) using the spectral function.

easyunfold unfold plot [OPTIONS]

Options

--dpi <dpi>

DPI for the figure when saved as raster image.

Default:

300

--height <height>

Height of the figure

Default:

3.0

--width <width>

Width of the figure

Default:

4.0

--title <title>

Title to be used

--orbitals <orbitals>

Orbitals to be used for weighting, comma-separated (e.g. “s,p”). If different for different atom groups (specified with –atoms/–atoms-idx, then different groups should be separated by “|” (e.g. “px,py|s|p,d”).

--atoms-idx <atoms_idx>

Recommended to use –atoms if possible, otherwise use this. Indices of the atoms to be used for weighting (1-indexed), comma-separated and “-” can be used to define ranges (e.g. “1-20,21,22,23”). If using with plot-projections, different groups (i.e. colour projections) should be separated by “|” (e.g. “1-20|21,22,23|36”).

--poscar <poscar>

Path to POSCAR or CONTCAR file from which to read atom indices for weighting.

Default:

POSCAR

--atoms <atoms>

Atoms to be used for weighting, as a comma-separated list (e.g. “Na,Bi,S”). The POSCAR or CONTCAR file (matching –poscar) must be present, otherwise use –atoms-idx.

--procar <procar>

PROCAR file(s) for atomic weighting, can be passed multiple times if more than one PROCAR should be used. Default is to read PROCAR(.gz) in current directory

--total-only

Only plot the total density of states.

--no-total

Don’t plot the total density of states.

--scale <scale>

Scaling factor for the DOS plot.

--gaussian <gaussian>

Standard deviation of DOS gaussian broadening in eV.

Default:

0.05

--legend-cutoff <legend_cutoff>

Cut-off in % of total DOS that determines if a line is given a label.

Default:

3

--dos-atoms <dos_atoms>

Atoms to include (e.g. “O.1.2.3,Ru.1.2.3”) for DOS if included.

--dos-orbitals <dos_orbitals>

Orbitals to split into lm-decomposed (e.g. p -> px, py, pz) contributions (e.g. “S.p”) for DOS if included.

--dos-elements <dos_elements>

Elemental orbitals to plot (e.g. “C.s.p,O”) for DOS if included. If not specified, will be set to the orbitals of –atoms (if specified)

--zero-line

Plot horizontal line at zero energy.

Default:

False

--dos-label <dos_label>

Axis label for DOS if included.

--dos <dos>

Path to vasprun.xml(.gz) file from which to read the density of states (DOS) information. If set, the density of states will be plotted alongside the unfolded bandstructure. For GGA bandstructures, this should not be the vasprun.xml(.gz) from the bandstructure calculation (-> non-uniform kpoint mesh), but rather the preceding SCF or separate DOS calculation.

--no-symm-average

Do not include symmetry related kpoints for averaging.

Default:

False

--show

Show the plot interactively.

--cmap <cmap>

Name of the colour map to use.

Default:

PuRd

-o, --out-file <out_file>

Name of the output file.

Default:

unfold.png

--vscale <vscale>

A normalisation/scaling factor for the colour mapping. Equivalent to (1/intensity). Will be deprecated in future versions.

Default:

1.0

--intensity <intensity>

Scaling factor for the colour intensity.

Default:

1.0

--emax <emax>

Maximum energy in eV relative to the reference.

Default:

5.0

--emin <emin>

Minimum energy in eV relative to the reference.

Default:

-5.0

--eref <eref>

Reference energy in eV.

--sigma <sigma>

Smearing width for the energy in eV.

Default:

0.02

--npoints <npoints>

Number of bins for the energy.

Default:

2000

-m, --mpl-style-file <mpl_style_file>

Specify custom plotting mplstyle file

plot-projections

Plot the effective band structure with atomic projections.

easyunfold unfold plot-projections [OPTIONS]

Options

--dpi <dpi>

DPI for the figure when saved as raster image.

Default:

300

--height <height>

Height of the figure

Default:

3.0

--width <width>

Width of the figure

Default:

4.0

--title <title>

Title to be used

--orbitals <orbitals>

Orbitals to be used for weighting, comma-separated (e.g. “s,p”). If different for different atom groups (specified with –atoms/–atoms-idx, then different groups should be separated by “|” (e.g. “px,py|s|p,d”).

--atoms-idx <atoms_idx>

Recommended to use –atoms if possible, otherwise use this. Indices of the atoms to be used for weighting (1-indexed), comma-separated and “-” can be used to define ranges (e.g. “1-20,21,22,23”). If using with plot-projections, different groups (i.e. colour projections) should be separated by “|” (e.g. “1-20|21,22,23|36”).

--poscar <poscar>

Path to POSCAR or CONTCAR file from which to read atom indices for weighting.

Default:

POSCAR

--atoms <atoms>

Atoms to be used for weighting, as a comma-separated list (e.g. “Na,Bi,S”). The POSCAR or CONTCAR file (matching –poscar) must be present, otherwise use –atoms-idx.

--procar <procar>

PROCAR file(s) for atomic weighting, can be passed multiple times if more than one PROCAR should be used. Default is to read PROCAR(.gz) in current directory

--total-only

Only plot the total density of states.

--no-total

Don’t plot the total density of states.

--scale <scale>

Scaling factor for the DOS plot.

--gaussian <gaussian>

Standard deviation of DOS gaussian broadening in eV.

Default:

0.05

--legend-cutoff <legend_cutoff>

Cut-off in % of total DOS that determines if a line is given a label.

Default:

3

--dos-atoms <dos_atoms>

Atoms to include (e.g. “O.1.2.3,Ru.1.2.3”) for DOS if included.

--dos-orbitals <dos_orbitals>

Orbitals to split into lm-decomposed (e.g. p -> px, py, pz) contributions (e.g. “S.p”) for DOS if included.

--dos-elements <dos_elements>

Elemental orbitals to plot (e.g. “C.s.p,O”) for DOS if included. If not specified, will be set to the orbitals of –atoms (if specified)

--zero-line

Plot horizontal line at zero energy.

Default:

False

--dos-label <dos_label>

Axis label for DOS if included.

--dos <dos>

Path to vasprun.xml(.gz) file from which to read the density of states (DOS) information. If set, the density of states will be plotted alongside the unfolded bandstructure. For GGA bandstructures, this should not be the vasprun.xml(.gz) from the bandstructure calculation (-> non-uniform kpoint mesh), but rather the preceding SCF or separate DOS calculation.

--no-symm-average

Do not include symmetry related kpoints for averaging.

Default:

False

--show

Show the plot interactively.

--cmap <cmap>

Name of the colour map to use.

Default:

PuRd

-o, --out-file <out_file>

Name of the output file.

Default:

unfold.png

--vscale <vscale>

A normalisation/scaling factor for the colour mapping. Equivalent to (1/intensity). Will be deprecated in future versions.

Default:

1.0

--intensity <intensity>

Scaling factor for the colour intensity.

Default:

1.0

--emax <emax>

Maximum energy in eV relative to the reference.

Default:

5.0

--emin <emin>

Minimum energy in eV relative to the reference.

Default:

-5.0

--eref <eref>

Reference energy in eV.

--sigma <sigma>

Smearing width for the energy in eV.

Default:

0.02

--npoints <npoints>

Number of bins for the energy.

Default:

2000

-m, --mpl-style-file <mpl_style_file>

Specify custom plotting mplstyle file

--combined, --no-combined

Plot all projections in a combined graph.

Default:

False

--colours <colours>

Colours to be used for combined plot, comma separated (e.g. “r,b,y”). Default is pastel red, green, blue if <=3 projections, else red, green, blue, purple, orange, yellow.

--colourspace <colourspace>

Colourspace in which to perform interpolation for combined plot.

Default:

lab

Options:

rgb | hsv | lab | luvlch | lablch | xyz

status

Print the status

easyunfold unfold status [OPTIONS]