Parameter File

The parameter file is a free-format file. The keywords for this file are listed in Tables 1.1 through 1.10.

Some keywords correspond directly to variables stored in the parameters module. Others indirectly determine the values of these variables. The variable, if any, corresponding to each keyword is also shown in Tables 1.1 through 1.12. The default values of the variables and the relationships between their values and the keywords in the parameter file are given in Section 1.2.

Table 1.1: Parameter file keywords controlling general parameters. Argument types are represented by, I for a integer, R for a real number, P for a physical value, L for a logical value, D for a keyword that may simply be defined (present) or not, and S for a text string.

Keyword	Type	Corresponding	Description
		Variable
General Parameters
COMMENT	S	comment	A comment string that may be used to lable the output.
IPRINT	I	iprint	Controls the verbosity of output.
STOP	D	-	If present, execution will halt the next time the parameter file is read.
CONTINUATION	S	continuation	The model file from which to continue a calculation.
REUSE	S	reuse	The model file from which to read data to initialise a new run.
CHECKPOINT	S	checkpoint	The model file to which model data should be written.
TASK	S	task	The job to be performed.
CALCULATE_STRESS	L	calculate_stress	If TRUE this forces the claculation of the stress tensor for any task.
RUN_TIME	I	run_time	The maximum run time for the job. If this is $\leq 0$ no limit will be imposed.
NUM_BACKUP_ITER*	I	num_backup_iter	The number of geometry optimisation, MD or phonon iterations between writing backup restart files.
BACKUP_INTERVAL*	I	backup_interval	The interval in seconds between backups in geometry optimisation, MD or phonon.
PRINT_CLOCK	L	print_clock	Flag to indicate if timing information should be printed during the run.
LENGTH_UNIT	S	length_unit	The unit of length for output.
MASS_UNIT	S	mass_unit	The unit of mass for output.
TIME_UNIT	S	time_unit	The unit of time for output.
CHARGE_UNIT	S	charge_unit	The unit of charge for output.
ENERGY_UNIT	S	energy_unit	The unit of energy for output.
FORCE_UNIT	S	force_unit	The unit of force for output.
VELOCITY_UNIT	S	velocity_unit	The unit of velocity for output.
PRESSURE_UNIT	S	pressure_unit	The unit of pressure for output.
INV_LENGTH_UNIT	S	inv_length_unit	The unit of inverse length for output.
FREQUENCY_UNIT	S	frequency_unit	The unit of frequency for output.
FORCE_CONSTANT_UNIT	S	force_constant_unit	The unit of force constant for output.
VOLUME_UNIT	S	volume_unit	The unit of volume for output.

Table 1.2: Parameter file keywords controlling exchange-correlation, pseudopotential and basis set. Argument types are represented by, I for a integer, R for a real number, P for a physical value, L for a logical value, D for a keyword that may simply be defined (present) or not, and S for a text string.

Keyword	Type	Corresponding	Description
		Variable
General Parameters Continued
PAGE_WVFNS	I	page_wvfns	Controls the paging of large wavefunctions to disc in order to save memory.
RAND_SEED	I	rand_seed	Controls the initialisation of the random number sequence.
DATA_DISTRIBUTION	S	data_distribution	Controls the parallelisation strategy used by the code.
OPT_STRATEGY*	S	opt_strategy	Controls the optimisation strategy used by the code.
OPT_STRATEGY_BIAS*	I	opt_strategy_bias	Expert control for the optimisation strategy used by the code.
DEVEL_CODE	S	devel_code	A code for developers use to control specific debugging output.
Exchange-Correlation Parameters
XC_FUNCTIONAL	S	xc_functional	The functional to use for the exchange-correlation potential. See Section 1.2.31 for details.
XC_VXC_DERIV_EPSILON	R	xc_vxc_deriv_epsilon	The fraction used to determine the size of the increment used in the numerical calculation of the second derivatives of the GGA functions.
Pseudopotentials
PSPOT_NONLOCAL_TYPE	S	pspot_nonlocal_type	This defines the representation (real or reciprocal space) used for application of the non-local pseudopotential projectors.
PSPOT_BETA_PHI_TYPE	S	pspot_beta_phi_type	This defines the representation (real or reciprocal space) used for calculating the $<\beta\vert\phi>$ overlaps.

Table 1.3: Parameter file keywords controlling the basis set. Argument types are represented by, I for a integer, R for a real number, P for a physical value, L for a logical value, D for a keyword that may simply be defined (present) or not, and S for a text string.

Keyword	Type	Corresponding	Description
		Variable
Basis Set Parameters
BASIS_PRECISION*	S	basis_precision	The accuracy of the basis set. See Section 1.2.36 for options.
CUT_OFF_ENERGY*	P	cut_off_energy	The cut off energy for the plane-wave basis set.
GRID_SCALE	R	grid_scale	The grid size as a multiple of the diameter of the plane-wave sphere.
FINE_GMAX	P	fine_gmax	Defines the size of the fine grid.
FINITE_BASIS_CORR	S	finite_basis_corr	Perform finite basis set correction when cell parameters change? See Section 1.2.39 for options.
BASIS_DE_DLOGE	P	basis_de_dloge	The derivative of total energy w.r.t. log of basis cut off energy. Only used if FINITE_BASIS_CORR = MANUAL
FINITE_BASIS_NPOINTS	I	finite_basis_npoints	The number of points used to estimate the derivative of total energy w.r.t. log of basis cut off energy. Only used if FINITE_BASIS_CORR = AUTO
FINITE_BASIS_SPACING	P	finite_basis_spacing	The energy difference between cut off energies at which total energy is evaluated to estimate the derivative of total energy w.r.t. log of basis cut off energy. Only used if FINITE_BASIS_CORR = AUTO
FIXED_NPW	L	fixed_npw	Flag to indicate if the basis set should be fixed during variable cell calculations.

Table 1.4: Parameter file keywords controlling electronic and electronic minimisation parameters. Argument types are represented by, I for a integer, R for a real number, P for a physical value, L for a logical value, D for a keyword that may simply be defined (present) or not, and S for a text string. Groups of parameters which are mutually exclusive are indicated by integers in the Group column.

Keyword	Type	Corresponding	Description
		Variable
Electronic Parameters
NELECTRONS*	I	nelectrons	The number of electrons in the system.
CHARGE*	I	-	The total system charge.
SPIN*	I	-	The total z-component of the electronic spin.
NUP*	I	nup	The number of spin up electrons.
NDOWN*	I	ndown	The number of spin down electrons.
SPIN_POLARISED*	L	-	Should the system be treated as spin polarised?
NBANDS$\dagger$	I	nbands	The number of bands.
NEXTRA_BANDS$\dagger$	I	-	The number of extra bands above $\lceil\frac{\tt nelectrons}{2} \rceil$.
PERC_EXTRA_BANDS$\dagger$	R	-	The number of extra bands as a percentage above $\lceil\frac{\tt nelectrons}{2} \rceil$.
ELEC_TEMP	P	elec_temp	The electron temperature for which results will be calculated. Only used if metals_method=`EDFT'.
EXCITED_STATE_SCISSORS	P	excited_state_scissors	Apply a correction to the band gap.
Electronic Minimisation Parameters
ELECTRONIC_MINIMISER	S	-	The method of electronic minimisation to use. Possible values: ``SD'', ``CG'', ``RMM/DIIS''.
MAX_SD_STEPS	I	max_sd_steps	The maximum number of steepest descent steps in an SCF cycle.
MAX_CG_STEPS	I	max_cg_steps	The maximum number of conjugate gradient steps in an SCF cycle.
MAX_DIIS_STEPS	I	max_diis_steps	The maximum number of RMM/DIIS steps in an SCF cycle.
METALS_METHOD	S	metals_method	The method to be used for the treatment of metals or partial occupancies. See Section 1.2.54 for possible values.
ELEC_ENERGY_TOL	P	elec_energy_tol	The convergence tolerance for finding the ground state energy as an energy per atom.
ELEC_EIGENVALUE_TOL	P	elec_eigenvalue_tol	The convergence criteria for an eigenvalue during a band by band minimisation.

Table 1.5: Parameter file keywords controlling electronic minimisation continued. Argument types are represented by, I for a integer, R for a real number, P for a physical value, L for a logical value and S for a text string.

Keyword	Type	Corresponding	Description
		Variable
Electronic Minimisation Parameters Continued
ELEC_CONVERGENCE_WIN	I	elec_convergence_win	The number of over which convergence of the minimiser is assessed.
MAX_SCF_CYCLES	I	max_scf_cycles	The maximum number of SCF cycles in an electronic minimisation.
SPIN_FIX	I	spin_fix	The number of iterations to fix the spin during an electronic relaxation. If , the spin is fixed permanently. Only used if fix_occupancy is FALSE.
FIX_OCCUPANCY	L	fix_occupancy	Fix the occupancies of the bands, ie. treat as a zero temperature insulator.
SMEARING_SCHEME	S	smearing_scheme	The smearing scheme to use for the fermi-surface of a metal. See Section 1.2.61 for details.
SMEARING_WIDTH	P	smearing_width	The width of the smearing of the fermi-surface of a metal.
EFERMI_TOL	P	efermi_tol	The tolerance within which to find the fermi energy of a metal.
NUM_OCC_CYCLES	I	num_occ_cycles	The number of occupancy minimisation cycles per electronic step during ensemble DFT minimisation.
ELEC_DUMP_FILE	S	elec_dump_file	The filename of the file into which to periodically dump the wavefunction and density during electronic minimisation as a backup.
NUM_DUMP_CYCLES	I	num_dump_cycles	The number of SCF cycles between wavefunction dumps.
ELEC_RESTORE_FILE	S	elec_restore_file	Restore the wavefunction and density from this file on first call to electronic minimisation.

Table 1.6: Parameter file keywords controlling density mixing, and population analysis. Argument types are represented by, I for a integer, R for a real number, L for a logical value and S for a text string.

Keyword	Type	Corresponding	Description
		Variable
Density Mixing Parameters
MIXING_SCHEME	S	mixing_scheme	The mixing scheme to use in the density mixing procedure.
MIX_HISTORY_LENGTH	I	mix_history_length	The number of charge densities to store in the density mixing history.
MIX_CHARGE_AMP	R	mix_charge_amp	The mixing amplitude for the charge density
MIX_CHARGE_GMAX	P	mix_charge_gmax	The maximum wavevector for which to mix the charge density.
MIX_SPIN_AMP	R	mix_spin_amp	The mixing amplitude for the spin density
MIX_SPIN_GMAX	P	mix_spin_gmax	The maximum wavevector for which to mix the spin density.
MIX_CUT_OFF_ENERGY	P	mix_cut_off_energy	The cut off energy for the densities within the mixing scheme.
MIX_METRIC_Q	P	mix_metric_q	The metric for the densities within the density mixing scheme.
Population Analysis
POPN_CALCULATE	L	popn_calculate	Perform a population analysis on the final ground state?
POPN_BOND_CUTOFF	P	popn_bond_cutoff	The maximum distance between two atoms for which a bond population will be output.
PDOS_CALCULATE_WEIGHTS	L	pdos_calculate_weights	Calculate the band weights for a partial density of states analysis?

Table 1.7: Parameter file keywords controlling geometry optimisation. Argument types are represented by, I for a integer, R for a real number, P for a physical value, L for a logical value and S for a text string.

Keyword	Type	Corresponding	Description
		Variable
Geometry Optimisation Parameters
GEOM_METHOD	S	geom_method	The method to use for geometry optimisation
GEOM_MAX_ITER	I	geom_max_iter	The maximum number of geometry optimisation iterations perform.
GEOM_ENERGY_TOL	P	geom_energy_tol	The convergence tolerance for the total energy per atom when finding ground state structure.
GEOM_FORCE_TOL	P	geom_force_tol	The convergence tolerance for the maximum force on the ions when finding the ground state ionic positions.
GEOM_DISP_TOL	P	geom_disp_tol	The convergence tolerance for the maximum ionic displacement in a step when finding the ground state ionic positions.
GEOM_STRESS_TOL	P	geom_stress_tol	The convergence tolerance for the maximum stress when finding the ground state cell parameters
GEOM_CONVERGENCE_WIN	I	geom_convergence_win	The number of geometry optimisation iterations during which the convergence criteria must be met for convergence to be accepted.
GEOM_MODULUS_EST	P	geom_modulus_est	An estimate of the bulk modulus of the system.
GEOM_FREQUENCY_EST	P	geom_frequency_test	An estimate of the average phonon frequency at the gamma point.

Table 1.8: Parameter file keywords controlling band structure and molecular dynamics. Argument types are represented by, I for a integer, R for a real number, P for a physical value, L for a logical value and S for a text string.

Keyword	Type	Corresponding	Description
		Variable
Band Structure Parameters
BS_MAX_ITER	I	bs_max_iter	The maximum number of iterations when calculating the band structure.
BS_EIGENVALUE_TOL	P	bs_eigenvalue_tol	The convergence criteria for an eigenvalue during a band structure calculation.
BS_MAX_CG_STEPS	I	bs_max_cg_steps	The maximum number of conjugate gradient steps in the band structure minimisation before resetting.
BS_NEXTRA_BANDS*	I	-	The number of extra bands above the number of valence bands at each k-point when calculating the band structure.
BS_PERC_EXTRA_BANDS*	R	-	The precentage of extra bands above the number of valence bands at each k-point when calculating the band structure.
BS_NBANDS*	I	bs_nbands	The number of bands at each k-point when calculating the band structure.
BS_XC_FUNCTIONAL	S	bs_xc_functional	The exchange-correlation functional to use for band-structure calculations.
Molecular Dynamics
MD_NUM_ITER	I	md_num_iter	The number of MD time steps.
MD_DELTA_T	P	md_delta_t	The time step for molecular dynamics
MD_ENSEMBLE	S	md_ensemble	The ensemble for the molecular dynamics run.
MD_TEMPERATURE	P	md_temperature	The temperature for the molecular dynamics run.
MD_THERMOSTAT	S	md_thermostat	The thermostat for the molecular dynamics run.
MD_NOSE_T	T	md_nose_t	The value for the characteristic Nosé-Hoover time. Only used if Nosé-Hoover thermostat has been chosen.
MD_LANGEVIN_T	P	md_langevin_t	The damping time for the Langevin thermostat. Only used if the Langevin thermostat has been chosen.

Table 1.9: Parameter file keywords controlling molecular dynamics continued. Argument types are represented by, I for a integer, R for a real number, P for a physical value, L for a logical value and S for a text string.

Keyword	Type	Corresponding	Description
		Variable
Molecular Dynamics Continued
MD_EXTRAP	S	md_extrap	The extrapolation scheme to use for molecular dynamics.
MD_EXTRAP_FIT	L	md_extrap_fit	Use best fit extrapolation parameters?
MD_DAMPING_SCHEME	S	md_damping_scheme	Controls the scheme used for damped MD geometry optimisation.
MD_DAMPING_RESET	I	md_damping_reset	Reset the damping factors after this number of iterations if convergence has not been achieved.
MD_OPT_DAMPED_DELTA_T	L	md_opt_damped_delta_t	Use optimised time step for damped molecular dynamics?
MD_ELEC_ENERGY_TOL	P	md_elec_energy_tol	The convergence tolerance for finding the ground state energy during an MD run as an energy per atom.
MD_ELEC_EIGENVALUE_TOL	P	md_elec_eigenvalue_tol	The convergence criteria for an eigenvalue when performing DIIS/DM minimisation during an MD run.
MD_ELEC_CONVERGENCE_WIN	I	md_elec_convergence_win	The number of iterations over which convergence is assessed during an electronic minimsation in an MD run.

Table 1.10: Parameter file keywords controlling optics and transition state searches. Argument types are represented by, I for a integer, R for a real number, P for a physical value, L for a logical value and S for a text string.

Keyword	Type	Corresponding	Description
		Variable
Optics
OPTICS_NEXTRA_BANDS*	I	-	The number of extra bands above the number of valence bands at each k-point when calculating an optical spectrum.
OPTICS_PERC_EXTRA_BANDS*	R	-	The precentage of extra bands above the number of valence bands at each k-point when calculating an optical spectrum.
OPTICS_NBANDS*	I	optics_nbands	The number of bands at each k-point when calculating an optical spectrum.
OPTICS_XC_FUNCTIONAL	S	optics_xc_functional	The functional to use for calculating optical spectra.
Transition State Search
TSSEARCH_METHOD	S	tssearch_method	Determines the method used in the transitionstate search algorithm
TSSEARCH_LSTQST_PROTOCOL	S	tssearch_lstqst_protocol	Determines the protocol used when performing and LST/QST search.
TSSEARCH_QST_MAX_ITER	I	tssearch_qst_max_iter	The maximum number of iterations in a QST search.
TSSEARCH_CG_MAX_ITER	I	tssearch_cg_max_iter	The maximum number of conjugate gradients iterations in the transistion state search.
TSSEARCH_FORCE_TOL	P	tssearch_force_tol	The force tolerance within which the transition state will be found.
TSSEARCH_DISP_TOL	P	tssearch_disp_tol	The displacement tolerance within which the transition state will be found.

Table 1.11: Parameter file keywords controlling phonon calculations. Argument types are represented by, I for a integer, R for a real number, P for a physical value, L for a logical value and S for a text string.

Keyword	Type	Corresponding	Description
		Variable
Phonon
PHONON_MAX_CYCLES	I	phonon_max_cycles	The maximum number of cycles in the minimisation algorithm.
PHONON_MAX_CG_STEPS	I	phonon_max_cg_steps	The maximum number of conjugate-gradient steps in a cycle of the phonon LR minimiser.
PHONON_ENERGY_TOL	P	phonon_energy_tol	The convergence tolerance for the phonon LR minimiser in units of force constant.
PHONON_CONVERGENCE_WIN	I	phonon_convergence_win	The number of over which convergence of the phonon LR minimiser is assessed.
PHONON_PRECONDITIONER	S	phonon_preconditioner	The preconditioner to use in the minimisation algorithm.
PHONON_USE_KPOINT_ SYMMETRY	L	phonon_use_kpoint_ symmetry	Use the irreducible k-point set of the (reduced) symmetry for phonon calculations?
PHONON_METHOD	S	phonon_method	The method to use to calculate the dynamical matrix.
PHONON_DOS_SPACING	P	phonon_dos_spacing	The resolution of the phonon density of states calculation.
PHONON_FINITE_DISP	P	phonon_finite_disp	The amplitude of the perturbation used in a finite displacement phonon calculation.
PHONON_CALC_LO_TO_ SPLITTING	L	phonon_calc_lo_to_ splitting	Whether to calculate the NS term of the dynamical matrix.
PHONON_SUM_RULE	L	phonon_sum_rule	Enforce phonon sum rule at q=0?
CALCULATE_BORN_CHARGES	L	calculate_born_charges	Calculate Born effective charges? (N.B. Also affects Efield calculations)
BORN_CHARGE_SUM_RULE	L	born_charge_sum_rule	Enforce Born charge sum rule?

Table 1.12: Parameter file keywords controlling electric field linear response calculations and deprectaed keywords. Argument types are represented by, I for a integer, R for a real number, P for a physical value, L for a logical value and S for a text string.

Keyword	Type	Corresponding	Description
		Variable
Electric Field Linear Response
EFIELD_MAX_CYCLES	I	efield_max_cycles	The maximum number of cycles in the minimisation algorithm.
EFIELD_MAX_CG_STEPS	I	efield_max_cg_steps	The maximum number of conjugate-gradient steps in a cycle of the efield LR minimiser.
EFIELD_ENERGY_TOL	P	efield_energy_tol	The convergence tolerance for the efield LR minimiser in units of force constant.
EFIELD_CONVERGENCE_WIN	I	efield_convergence_win	The number of over which convergence of the efield LR minimiser is assessed.
EFIELD_CALC_ION_ PERMITTIVITY	L	efield_calc_ion_ permittivity	Calculate the ionic permittivity when performing an efield calculation?
EFIELD_IGNORE_MOLEC_MODES	S	efield_ignore_molec_modes	Indicates if lowest modes should be ignored for molecules.
Deprecated
PHONON_CONST_BASIS	L	-	No-longer used.