shakenbreak.cli module

Commands

ShakeNBreak has eight main commands: snb-generate, snb-generate_all, snb-run, snb-parse, snb-analyse, snb-plot, snb-regenerate, snb-groundstate and snb-mag. Their functionality and options are described below.

See the Structure generation and Analysis & plotting Tutorials pages for an overview of their usage.

snb

ShakeNBreak: Defect structure-searching.

snb [OPTIONS] COMMAND [ARGS]...

analyse

Generate csv file mapping each distortion to its final energy (in eV) and its mean displacement (in Angstrom and relative to ref_struct).

snb analyse [OPTIONS]

Options

-d, --defect <defect>

Name of defect species (folder) to analyse and plot (e.g. ‘vac_1_Cd_0’), if run from top-level directory or above. Default is current directory name (assumes running from within defect folder).

-a, --all

Analyse all defects present in specified directory

Default:

False

-p, --path <path>

Path to the top-level directory containing the defect folder(s). Defaults to current directory.

--code <code>

Code used to run the geometry optimisations. Options: ‘vasp’, ‘cp2k’, ‘espresso’, ‘castep’, ‘fhi-aims’.

Default:

vasp

-ref, --ref_struct <ref_struct>

Structure to use as a reference for comparison (to compute atomic displacements). Given as a key from defect_structures_dict (e.g. ‘-0.4’ for ‘Bond_Distortion_-40.0%’).

Default:

Unperturbed

-v, --verbose

Print information about identified energy lowering distortions and renamed/saved-over files.

Default:

False

generate

Generate the trial distortions and input files for structure-searching for a given defect.

snb generate [OPTIONS]

Options

-d, --defect <defect>

Required Path to defect structure

-b, --bulk <bulk>

Required Path to bulk structure

-c, --charge <charge>

Defect charge state

-min, --min-charge <min_charge>

Minimum defect charge state for which to generate distortions

-max, --max-charge <max_charge>

Maximum defect charge state for which to generate distortions

-p, --padding <padding>

If –charge or –min-charge & –max-charge are not set, defect charges will be set to the range: 0 - {Defect oxidation state}, with a –padding on either side of this range.

-idx, --defect-index <defect_index>

Index of defect site in defect structure (if substitution/interstitial) or bulk structure (if vacancy), in case auto site-matching fails

-def-coords, --defect-coords <defect_coords>

Fractional coordinates of defect site in defect structure, in case auto site-matching fails. In the form ‘x y z’ (3 arguments)

--code <code>

Code to generate relaxation input files for. Options: ‘VASP’, ‘CP2K’, ‘espresso’, ‘CASTEP’, ‘FHI-aims’.

Default:

VASP

-n, --name <name>

Defect name for folder and metadata generation. Defaults to doped scheme (see tutorials).

-conf, --config <config>

Config file for advanced distortion settings. See example in SnB_input_files/example_generate_config.yaml

-inp, --input_file <input_file>

Input file for the code specified with –code, with relaxation parameters to override defaults (e.g. INCAR for VASP).

-v, --verbose

Print information about identified defects and generated distortions

Default:

False

generate_all

Generate the trial distortions and input files for structure-searching for all defects in a given directory.

snb generate_all [OPTIONS]

Options

-d, --defects <defects>

Path root directory with defect folders/files. Defaults to current directory (‘./’)

-s, --structure_file <structure_file>

File termination/name from which toparse defect structure from. Only required if defects are stored in individual directories.

Default:

POSCAR

-b, --bulk <bulk>

Path to bulk structure

-p, --padding <padding>

For any defects where charge is not set in the –config file, charges will be set to the range: 0 - {Defect oxidation state}, with a –padding on either side of this range.

--code <code>

Code to generate relaxation input files for. Options: ‘VASP’, ‘CP2K’, ‘espresso’, ‘CASTEP’, ‘FHI-aims’.

Default:

VASP

-conf, --config <config>

Config file for advanced distortion settings. See example in /SnB_input_files/example_generate_all_config.yaml

-inp, --input_file <input_file>

Input file for the code specified with –code, with relaxation parameters to override defaults (e.g. INCAR for VASP).

-v, --verbose

Print information about identified defects and generated distortions

Default:

False

groundstate

Generate folders with the identified ground state structures. A folder (named directory) is created with the ground state structure (named groundstate_filename) for each defect present in the specified path (if path is the top-level directory) or for the current defect if run within a defect folder. If the name of the structure/output files is not specified, the code assumes CONTCAR (e.g. geometry optimisations performed with VASP). If using a different code, please specify the name of the structure/output files.

snb groundstate [OPTIONS]

Options

-d, --directory <directory>

Folder name where the ground state structure will be written to. If using with doped, then typically recommended to set to vasp_nkred_std or vasp_std.

Default:

Groundstate

-gsf, --groundstate_filename <groundstate_filename>

File name to save the ground state structure as.

Default:

POSCAR

-sf, --structure_filename <structure_filename>

File name of the output structures/files.

Default:

CONTCAR

-p, --path <path>

Path to the top-level directory containing the defect folders. Defaults to current directory.

-nv, --non_verbose

Don’t print information about ground state structures and generated folders.

Default:

False

mag

Checks if the magnetisation (spin polarisation) values of all atoms in the VASP calculation are below a certain threshold, by pulling this data from the OUTCAR. Returns a shell exit status of 0 if magnetisation is below the threshold and 1 if above.

snb mag [OPTIONS]

Options

-o, --outcar <outcar>

Path to OUTCAR(.gz) file

-t, --threshold <threshold>

Atoms with absolute magnetisation below this value are considered un-magnetised / non-spin-polarised. The threshold for total magnetisation is 10x this value.

Default:

0.01

-v, --verbose

Print information about the magnetisation of the system.

Default:

False

parse

Parse final energies of defect structures from relaxation output files. Parsed energies are written to a yaml file in the corresponding defect directory.

snb parse [OPTIONS]

Options

-d, --defect <defect>

Name of defect species (folder) to parse (e.g. ‘vac_1_Cd_0’), if run from top-level directory or above. Default is current directory name (assumes running from within defect folder).

-a, --all

Parse energies for all defects present in the specified/current directory

Default:

False

-p, --path <path>

Path to the top-level directory containing the defect folder. Defaults to current directory (‘./’).

--code <code>

Code used to run the geometry optimisations. Options: ‘vasp’, ‘cp2k’, ‘espresso’, ‘castep’, ‘fhi-aims’.

Default:

vasp

-v, --verbose

Print information about renamed/saved-over files.

Default:

False

plot

Generate energy vs distortion plots. Optionally, the structural similarity between configurations can be illustrated with a colorbar.

snb plot [OPTIONS]

Options

-d, --defect <defect>

Name of defect species (folder) to analyse and plot (e.g. ‘vac_1_Cd_0’), if run from top-level directory or above. Default is current directory name (assumes running from within defect folder).

-a, --all

Analyse all defects present in current/specified directory

Default:

False

-min, --min_energy <min_energy>

Minimum energy difference (in eV) between the ground-state distortion and the Unperturbed structure to generate the distortion plot, when –all is set.

Default:

0.05

-p, --path <path>

Path to the top-level directory containing the defect folder(s). Defaults to current directory.

--code <code>

Code used to run the geometry optimisations. Options: ‘vasp’, ‘cp2k’, ‘espresso’, ‘castep’, ‘fhi-aims’.

Default:

vasp

-cb, --colorbar

Whether to add a colorbar indicating structural similarity between each structure and the unperturbed one.

Default:

False

-m, --metric <metric>

If the option –colorbar is specified, determines the criteria used for the structural comparison. Can choose between the summed of atomic displacements (‘disp’) or the maximum distance between matched sites (‘max_dist’, default).

Default:

max_dist

-f, --format <format>

Format to save the plot as.

Default:

png

-u, --units <units>

Units for energy, either ‘eV’ or ‘meV’.

Default:

eV

-max, --max_energy <max_energy>

Maximum energy (in chosen units), relative to the unperturbed structure, to show on the plot.

Default:

0.5

-nt, --no-title

Don’t add defect name as plot title.

Default:

False

-v, --verbose

Print information about identified energy lowering distortions and renamed/saved-over files.

Default:

False

regenerate

Identify defect species undergoing energy-lowering distortions and test these distortions for the other charge states of the defect. Considers all identified energy-lowering distortions for each defect in each charge state, and screens out duplicate distorted structures found for multiple charge states. Defect folder names should end with charge state after an underscore (e.g. vac_1_Cd_0 or Va_Cd_0 etc).

snb regenerate [OPTIONS]

Options

-p, --path <path>

Path to the top-level directory containing the defect folders. Defaults to current directory.

--code <code>

Code to generate relaxation input files for. Options: ‘vasp’, ‘cp2k’, ‘espresso’, ‘castep’, ‘fhi-aims’.

Default:

vasp

-f, --filename <filename>

Name of the file containing the defect structures.

Default:

CONTCAR

-min, --min_energy <min_energy>

Minimum energy difference (in eV) between the ground-state defect structure, relative to the Unperturbed structure, to consider it as having found a new energy-lowering distortion.

Default:

0.05

-meta, --metastable

Also include metastable energy-lowering distortions that have been identified, as these can become ground-state distortions for other charge states.

Default:

False

-v, --verbose

Print information about identified energy lowering distortions.

Default:

False

run

Loop through distortion subfolders for a defect, when run within a defect folder, or for all defect folders in the current (top-level) directory if the –all (-a) flag is set, and submit jobs to the HPC scheduler.

As well as submitting the initial geometry optimisations, can automatically continue and resubmit calculations that have not yet converged (and handle those which have failed), see: https://shakenbreak.readthedocs.io/en/latest/Generation.html#submitting-the-geometry-optimisations

snb run [OPTIONS]

Options

-s, --submit-command <submit_command>

Job submission command for the HPC scheduler (qsub, sbatch etc).

Default:

qsub

-j, --job-script <job_script>

Filename of the job script file to submit to HPC scheduler.

Default:

job

-n, --job-name-option <job_name_option>

Flag for specifying the job name option for the HPC scheduler (e.g. ‘-N’ for ‘qsub -N JOBNAME job’ (default)).

-a, --all

Loop through all defect folders (then through their distortion subfolders) in the current directory

Default:

False

-v, --verbose

Print information about calculations which have fully converged

Default:

False