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).

Can be run within a single defect folder, or in the top-level directory (either specifying defect or looping through all defect folders).

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).

-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.

Can be run within a single defect folder, or in the top-level directory (either specifying defect or looping through all defect folders).

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).

-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.

Can be run within a single defect folder, or in the top-level directory (either specifying defect or looping through all defect folders).

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).

-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 running from the top-level folder.

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

-s, --style-file <style_file>#

Path to a mplstyle file to use for the plot(s). Default is ‘shakenbreak.mplstyle’.

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, 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)).

-v, --verbose#

Print information about calculations which have fully converged

Default:

False