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, and on will evaluate to True, and 0, no, false, and off will evaluate to False.
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):

  • Command line arguments or option from -o
  • Job specific option from $JOBNAME.fap
  • Job type ~/.faps/JOB_TYPE.fap specified with -j
  • Site specific from site.ini
  • Default from defaults.ini

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.