Options¶
Sensible defaults are provided by faps for most options, however it also aims to
offer many options for customising calculations. Defaults for all options can be
found in the defaults.ini
, which is located in the source code
directory; site-wide options such as the executable locations, directories and
queueing system and directories should be set in the site.ini.
When using the same options for many jobs the custom job types should be set up
in your ~/faps/$JOB_TYPE.fap
and referenced with the
-j
commandline option. Settings for an individual job can be
set in the $JOBNAME.fap
file or on the command line with -o
.
Configuration file format¶
Config files use a simple ini format of option = value
, or option:
value
. Values will requre a spcific type:
str
- Any string value, such as text or a path.
bool
- A case-insensitive true/false value;
1
,yes
,true
, andon
will evaluate toTrue
, and0
,no
,false
, andoff
will evaluate toFalse
. int
- An integer value, such as
1234
,0
,-12
. float
- A decimal value, such as
12.5
,7
,-33.98
.
Many options will take a list
of several values. Items can be separated by
commas and whitespace, and brackets are ignored. In some cases the values
also require a specifc type, this will be noted. The following are all valid
examples, float
: 0.1 0.2 0.3
; str
: (CO2, CH4)
; int
:
[1,2,1]
.
Lines starting with #
or ;
are comments and will be ignored.
Options should be one per line. If you wish to span multiple lines, subsequent
ones should be indented. Options are evaluated hierarchically and will silently
fall back to defaults in the order (use the -v
option to show which
options are used):
List of all available options¶
The following is an automatically generated list of most options. The default
value for each option is given here. For the most up-to-date list, see the
defaults.ini
file.
-
absl_compress_files
¶ Default:
OUTPUT */OUTPUT REVCON */REVCON */STATIS
[system:advanced] yes, on, 1 and False, no, off, 0 Files to keep and compress after a successful absl job.
-
absl_cutoff
¶ Default:
0.0
[gcmc:advanced] Binding sites are measured by their occupancy. Ignore maxima values when their occupancy falls below this value multiplied by the value at the highest maximums. Zero means use all values.
-
absl_delete_files
¶ Default:
REVIVE */REVIVE */*.out *.out CONFIG */CONFIG FIELD */FIELD CONTROL */CONTROL
[system:advanced] Files to delete after a successful absl job.
-
absl_exe
¶ Default:
./absl_faps
[system:advanced] Helper script name for absl job parts. faps will generate this script first so don’t change the name unless you know what you are doing. see dl_poly_exe for the executables.
-
absl_radius
¶ Default:
0.31
[gcmc:advanced] Binding site location ignores maxima found within a certain radius of a higher maximum. The radius here, in Angstrom, is converted to an approximate number of grid points.
-
absl_sigma
¶ Default:
2.0
[gcmc:advanced] Amount of smoothing to perform on the probability distribution. The value here is converted to a sigma for a gaussian kernel with by the equation sigma = sqrt(absl_sigma/grid_spacing)
-
absl_write_smooth_cube
¶ Default:
[gcmc:advanced] Should faps write out the smoothed probability cube files when running absl?
-
charge_method
¶ Default:
repeat
[control] Method to use for calculating atomic point charges.
-
dedicated_queue
¶ Default:
[system:advanced] Use a a specific queue when submitting jobs e.g. NRAP12345 on sharcnet. Leave blank for none.
-
default_cell
¶ Default:
(10.0, 10.0, 10.0, 90, 90, 90)
[structure:advanced] Cell parameters, in A, to use only when they are not specified in the input structure (e.g. for .xyz). Use either (a, b, c, alpha, beta, gamma) or ((ax, ay, az), (bx, by, bz), (cx, cy, cz)) notation.
-
dft_code
¶ Default:
vasp
[control] Method to use for dft calculation including optimization step and ESP generation.
-
dispersion
¶ Default:
True
[dft:advanced] Turn on empirical dispersion corrections in dft codes that support it.
-
dl_poly_exe
¶ Default:
DLPOLY.X
[system:advanced] Location of DL_POLY executable.
-
egulp_exe
¶ Default:
egulppot
[system:advanced] Location of Eugene’s QEq code.
-
egulp_grid
¶ Default:
[charges:advanced] Use egulp to generate a gridded potential.
-
egulp_grid_parameters
¶ Default:
1 none 0.25 0.25 0.25 1.0 2.0 0 3.0
[charges:advanced] When egulp is used to generate a gridded potential, use this line verbatim to pass options to the gridding input file.
-
egulp_potential
¶ Default:
[charges:advanced] Calculate the potential from the egulp point charges and save the cube file.
-
egulp_potential_difference
¶ Default:
[charges:advanced] Calculate the potential difference between egulp charges and input charges.
-
egulp_typed_atoms
¶ Default:
[charges:advanced] Use separate parameters for oxygen and hydrogen atoms in egulp.
-
email
¶ Default:
[control] Email addresses to send the results to after a successful job completion. Email contains .csv files, .cif file and contents of .flog file.
-
equation_of_state
¶ Default:
ideal
[gcmc] Equation of state to use to calculate the gas fugacities from the pressures.
-
esp_resolution
¶ Default:
0.1
[charges:advanced] Target resolution of the esp grid in Angstrom.
-
fastmc_compress_files
¶ Default:
*.cube
[system:advanced] files to keep and compress after a successful fastmc job.
-
fastmc_delete_files
¶ Default:
[system:advanced] files to delete after a successful fastmc job [str, list]
-
fastmc_exe
¶ Default:
gcmc.x
[system:advanced] Location of fastmc executable, must be the full path or be in the user’s $PATH. [str]
-
fastmc_keep_unfolded_cubes
¶ Default:
[system:advanced] Should the original, unfolded, probability density cube files be kept after folding (or deleted)?
-
fastmc_ncpu
¶ Default:
1
[control] Number of CPUs to run fastmc on. Make sure that you use the correct fastmc_exe for parallel runs.
-
ff_opt_code
¶ Default:
gulp
[control] Method to use to do force field optimisations.
-
find_maxima
¶ Default:
True
[gcmc:advanced] Calculate the location of the guests from the probability cube. This is required for ABSL so should be left active.
-
fold
¶ Default:
True
[gcmc:advanced] Fold probability plot cube from GCMC into the unit cell. Gives smoother distributions and smaller files
-
grompp_exe
¶ Default:
grompp_d
[system:advanced] Gromacs preprocessor executable, usually grompp or grompp_d for double precision calculations (preferred)
-
gromacs_compress_files
¶ Default:
*.itp *md.log* traject*.gro
[system:advanced] Files to keep and compress after a successful GROMACS job.
-
gromacs_delete_files
¶ Default:
*topol.tpr* g.log *traj.trr* *confout.gro* *ener.edr* *mdout.mdp* state.cpt
[system:advanced] Files to delete after a successful GROMACS job.
-
gromacs_exe
¶ Default:
./gromacs_faps
[system:advanced] Helper script name for gromacs job parts. faps will generate this script first so don’t change the name unless you know what you are doing. see mdrun_exe and grompp_exe for the executables.
-
gromacs_metal_geometry
¶ Default:
input
[force_field:advanced] Alter the force field used to model the metal geometry. {uff, input, fix} ‘uff’ Use regular UFF parameters for the complete topology. ‘input’ Use bond angles and distances from the input structure for the topology of the metals. ‘fix’ Use the input topology for metals and apply a rigid potential.
-
gromacs_verbose
¶ Default:
[force_field:advanced] Make gromacs produce more output like trajectories and energies. Check that the files to keep are in gromacs_delete_files.
-
guests
¶ Default:
CO2
[gcmc] Guest molecules to use in GCMC simulations. See documentation or guests.lib for list of built in guests.
-
gulp_terse
¶ Default:
True
[force_field:advanced] Reduce the standard output of GULP to a minimum with no movie files [bool]
-
gulp_exe
¶ Default:
gulp
[system:advanced] Location of GULP exe. [str]
-
import
¶ Default:
[control:advanced] Try to read in data from a previous calculation. This should probably be done through the commandline –import option.
-
infer_types_from_bonds
¶ Default:
True
[structure:advanced] If bonding information is found, but atoms are not typed for force field using _atom_type_description, then use openbabel to derive UFF types.
-
initial_structure_format
¶ Default:
cif
[structure:advanced] Filetype for input structure file.
-
interactive
¶ Default:
[control:advanced] Enable interactive interface. Opens a propmt after initialisation with access to internal objects, for very advanced use only.
-
kpoints
¶ Default:
(1, 1, 1)
[dft:advanced] Kpoint grid size for dft calculations. Ensure that gamma-point only exe is not used for calculations with more than one kpoint.
-
mc_code
¶ Default:
fastmc
[control] Method to use for Monte Carlo calculations.
-
mc_cutoff
¶ Default:
12.5
[gcmc:advanced] Lennard-Jones Potential cutoff, in Angstrom, to use in GCMC. This will also be used to determine the minimum supercell size for the simulation.
-
mc_eq_steps
¶ Default:
1000000
[gcmc] Number of steps to carry out for the GCMC equilibration phase. For parallel jobs each node will carry out this number of steps. Use negative values for MC cycles (steps per guest).
-
mc_history_freq
¶ Default:
0
[gcmc:advanced] How often to write the fastmc history. This file can get very large. Set to 0 to disable.
-
mc_jobcontrol
¶ Default:
[gcmc:advanced] Add the ‘jobcontrol’ directive in the fastmc input files so that GCMC must be stopped manually.
-
mc_numguests_freq
¶ Default:
1000
[gcmc:advanced] Number of steps between writes of the fastmc numguests.out file.
-
mc_pressure
¶ Default:
0.15
[gcmc] Pressure points to run GCMC simulations at, in bar. Each combination of temperature and pressure will be run individually to generate isotherms. For multiple pressure points and guests use nested lists to keep track of the order: ((g1p1, g2p1, ...), (g1p2, g2p2, ...), ...).
-
mc_probability_plot
¶ Default:
[gcmc] Turn on probability plots in GCMC. This is required for ABSL.
-
mc_probability_plot_spacing
¶ Default:
0.1
[gcmc:advanced] Distance between grid points (resolution) in Angstrom for GCMC probability density plots.
-
mc_prod_steps
¶ Default:
10000000
[gcmc] Number of steps to carry out for the GCMC production phase. For parallel jobs this is the totla number of steps, distributed over the nodes. Use negative values for MC cycles (steps per guest).
-
mc_state_points
¶ Default:
[gcmc] Individual state points to run GCMC simulations; These are separate from, and run in addition to, isotherms defined by tempearture and pressure combinations. Specify points (bar/Kelvin) as: (T1, (g1p1, g2p1, ...)), (T2, (g1p2, g2p2, ...), ...
-
mc_supercell
¶ Default:
(1, 1, 1)
[gcmc:advanced] Minimum supercell to use in the GCMC simulations. These values will only be used if the individual dimenstions are larger than the supercell calculated from the minimum image criterion of the Lennard-Jones cutoff.
-
mc_temperature
¶ Default:
298
[gcmc] Temperature(s) to use in GCMC simulations (Kelvin). These are combined with all requested pressures to produce isotherms at each temperature.
-
mc_zero_charges
¶ Default:
[gcmc:advanced] Do not use charges in the GCMC (set them all to zero) even if they have been calculated previously.
-
mdrun_exe
¶ Default:
mdrun_d
[system:advanced] Gromacs main executable, usually mdrun or mdrun_d for double precision calculations (preferred).
-
no_absl
¶ Default:
[control] Do not postprocess GCMC to find the binding sites with ABSL. ABSL Requires a probability density plot from GCMC.
-
no_charges
¶ Default:
[control] Skip the charge calculation step; If charges are not set in the input file or by other means they will all be zero.
-
no_dft
¶ Default:
[control] Skip the dft/optimization step; Structure will not be DFT optimized and charge calculation may fail if it depends on the ESP from this step.
-
no_force_field_opt
¶ Default:
True
[control] Do not pre-optimise with a molecular mechanics force field. Ususally requires topology defined in the input file.
-
no_gcmc
¶ Default:
[control] Do not run the GCMC simulations.
-
no_properties
¶ Default:
[control] Do not run the various structural property calculations, e.g. zeo++, surface areas.
-
no_submit
¶ Default:
[control:advanced] Do not submit jobs; just create input files. Things will go wrong if you do this but it can be used to create input files. Also accessible with the ‘-n’ commandline option.
-
optim_h
¶ Default:
True
[dft] Optimize positions of hydrogens in the DFT optimization step.
-
optim_all
¶ Default:
[dft] Optimize all atom positions in the DFT optimization step.
-
optim_cell
¶ Default:
[dft] Optimize the cell vectors in DFT optimization step.
-
order_atom_types
¶ Default:
[structure:advanced] Force re-ordering of atoms when reading files (default behaviour in faps version 1.3 and lower). Setting to a True will always force legacy atom ordering for compatibility with old simulations. False will prevent re-ordering unless it is needed (e.g. vasp fails with too many atom types)
-
plain
¶ Default:
[system:advanced] Do not colourise output. Ignored here can only be changed with commandline arguments.
-
platon_pxrd
¶ Default:
True
[properties:advanced] Use PLATON to calculate the PXRD pattern.
-
platon_exe
¶ Default:
platon
[system:advanced] location of the PLATON executable.
-
potcar_dir
¶ Default:
/share/apps/vasp/potcar/PBE
[system:advanced] Location of VASP POTCARs. Points to the root folder where the downloaded tarball has been extracted, with each element in a folder.
-
psf_dir
¶ Default:
/share/apps/siesta/psf/GGA_Abinit_2012
[system:advanced] Location of siesta psf pseudopotentials. All elements in the same folder named ElementSymbol.psf.
-
qeq_fit
¶ Default:
[charges:advanced] Fit charge equilibration parameters to calculated (or imput) charges.
-
qeq_parameters
¶ Default:
[charges] Custom parameter sets for QEq as (atom, electronegativity, 0.5*hardness). Predefined parameter sets can also be named anywhere here. Predefined sets are {mepo}.
-
queue
¶ Default:
wooki
[system:advanced] Queuing system to use for submitting and monitoring jobs.
-
quiet
¶ Default:
[system:advanced] Only output errors in the standard output. Log file is still written. This will be ignored here, use the commandline option ‘–quiet’ instead.
-
repeat_compress_files
¶ Default:
*.cube
[system:advanced] Files to keep and compress after a successful REPEAT job.
-
repeat_delete_files
¶ Default:
ESP_real_coul.dat fort.30 fort.40 REPEAT_param.inp
[system:advanced] Files to delete after a successful REPEAT job.
-
repeat_exe
¶ Default:
repeat.x
[system:advanced] Location of REPEAT executable.
-
repeat_ncpu
¶ Default:
1
[control] Number of CPUs to use for REPEAT calculation. Ensure that repeat_exe points to a parallel version if using more than one CPU.
-
run_all
¶ Default:
True
[control:advanced] Run all the steps without stopping. Setting this option to False will prevent postrun jobs from being submitted following each step in the calculation.
-
serial_memory
¶ Default:
12.0
[system:advanced] Maximum memory that can be used for serial calculations, in GB. If using serial repeat this can restrict the resolution of the ESP.
-
siesta_accuracy
¶ Default:
med
[dft] Overall acucracy setting for siesta calcualtions. Sets cutoffs and basis size to predefined values.
-
siesta_compress_files
¶ Default:
[system:advanced] Files to keep and compress after a successful SIESTA job.
-
siesta_delete_files
¶ Default:
*.ion *.xml INPUT_TMP* *.DM
[system:advanced] Files to delete after a successful SIESTA job.
-
siesta_exe
¶ Default:
siesta
[system:advanced] Location of siesta executable.
-
siesta_ncpu
¶ Default:
1
[control] Number of CPUs to use for siesta.
-
siesta_to_cube
¶ Default:
siesta2repeat
[system:advanced] Command used to convert siesta ESP to .cube file for REPEAT.
-
silent
¶ Default:
[system:advanced] Only emit critical messages in the standard output. Log file is still written. This will be ignored here, use the commandline option ‘–silent’ instead.
-
spin
¶ Default:
[dft] Turn on spin polarization in DFT calculations.
-
surface_area_probe
¶ Default:
[properties] Radii of probes for calculating surface areas using the built-in method. A probe of radius 0.0 will generate the VdW surface. Typical values for probe molecules are 1.42 (H2O), 1.72 (CO2) or 1.82 (N2) (A). These surfaces are used for hydriphilic surface determination, but are slow.
-
surface_area_resolution
¶ Default:
0.03
[properties:advanced] Approximate area per point (resolution), in A^2, to use when subdividing accessible surface areas using the built in method.
-
surface_area_save
¶ Default:
[properties:advanced] After determining the surface area with built-in method, save the valid points on the surface to a file.
-
surface_area_uniform_sample
¶ Default:
[properties:advanced] For the built-in surface area calculation use points with a uniform spacing (or do Monte Carlo sampling of the surface)?
-
symmetry
¶ Default:
[charges:advanced] When using REPEAT, treat symmetrical atoms as equivalent for charges. Needs testing, may not work for newest versions of REPEAT.
-
tar_after
¶ Default:
[control:advanced] Use tar to create an archive of all the output files when the job is finished.
-
tar_extract_before
¶ Default:
[control:advanced] If calculations exist in a tar file from a previous calculation, extract their contents before starting the next step (useful for import).
-
threaded_codes
¶ Default:
repeat
[system:advanced] List of codes that use OpenMP threaded parallelisation, as opposed to MPI parallelisation. Affects how the jobs are run or submitted in some systems.
-
threaded_memory
¶ Default:
12.0
[system:advanced] Maximum memory to use for threaded calculations, in GB. Affects how jobs are run in certain systems.
-
trjconv_exe
¶ Default:
trjconv_d
[system:advanced] Gromacs trajectory converter, usually trjconv or trjconv_d for double precision calculations (preferred).
-
update_opts
¶ Default:
True
[system:advanced] When restarting a job, e.g. after a step completes, re-read options and configuration files. Otherwise, previous configuration is kept.
-
vasp_compress_files
¶ Default:
LOCPOT CHGCAR vasprun.xml
[system:advanced] Files to keep and compress after a successful VASP job.
-
vasp_custom_incar
¶ Default:
[dft:advanced] Any options to add to the INCAR file. Text is copied verbatim and faps will not overwrite any keys that are specified here.
-
vasp_delete_files
¶ Default:
WAVECAR CHG DOSCAR EIGENVAL POTCAR PCDAT IBZKPT XDATCAR KPOINTS
[system:advanced] Files to delete after a successful VASP job.
-
vasp_exe
¶ Default:
vasp
[system:advanced] Name (location) of vasp executable.
-
vasp_ncpu
¶ Default:
12
[control] Number of cpus to run vasp on.
-
vasp_to_cube
¶ Default:
vasp_to_cube
[system:advanced] Command to convert LOCPOT from VASP to .cube for REPEAT.
-
verbose
¶ Default:
[system:advanced] Print extra debugging information to the standard output and log file. This will be ignored here, use the ‘–verbose’ on the commandline instead.
-
zeo++
¶ Default:
True
[control] Run zeo++ on the structure to calculate pore properties.
-
zeo++_exe
¶ Default:
network
[system:advanced] Command to use to run zeo++. Faps will generate the complete command lines.
Commandline options¶
A list of commandline options may be obtained by running faps -h at any time. Most options will be set in the config files but all options can be set at runtime with a commandline switch. The most useful flags are described here.
-
-v
,
--verbose
¶
Print additional debugging information to the terminal and the
$JOBNAME.flog
file.
-
-q
,
--quiet
¶
Only output errors and warnings to the terminal. All normal output is still logged to the
$JOBNAME.flog
file.
-
-s
,
--silent
¶
Do not produce any terminal output except for critical errors. All normal output is still logged to the
$JOBNAME.flog
file.
-
-p
,
--plain
¶
Do not colorise or wrap the terminal output. Default is to colour the information and wrap the text at 80 characters. File output is always plain.
-
-j
<$JOB_TYPE>
,
--job-type
=<$JOB_TYPE>
¶ Use the
~/.faps/$JOB_TYPE.fap
file to set options for the current job. This will override defaults but options will still be overridden by$JOBNAME.fap
and options set on the commandline.
-
-m
,
--import
¶
Faps will try to import data from an old or broken simulation and continue from there.
-
-n
,
--no-submit
¶
Faps will create input files but not submit any jobs. As steps may depend on each other, calculations may need to run to continue the simulations.
-
-o
<CMDOPTS>
,
--option
=<CMDOPTS>
¶ Allows any option from the config file to be specified for a single job or step. These will override all other config files. Options should be specified as
key=value
pairs with no spaces or boolean values are set to true when they appear on the commandline. For example faps -o vasp_ncpu=24 -o spin -o optim_h=false $JOBNAME, will override the number of vasp CPUs, turn on spin and turn off hydrogen optimisation.
-
-i
,
--interactive
¶
After loading any previous simulation, faps will immediately enter the expert only interactive mode. This is probably only for debugging and fixing calculations. No support for this.
-
-d
,
--daemon
¶
Fapswitch only: Start the program as a service; see the fapswitch documentation for how to use this.