faps module

faps – Frontend for Automated Adsorption Analysis of Porous Solids.

aka

shpes – Sorption analysis with a High throughput Python
frontend to Examine binding in Structures

Strucutre adsorption property analysis for high throughput processing. Run as a script, faps will automatically run complete analysis on a structure. Sensible defaults are implemented, but calculations can be easily customised. Faps also provides classes and methods for adapting the simulation or only doing select parts.

class faps.Atom(at_type=False, pos=False, parent=None, **kwargs)[source]

Bases: object

Base atom object.

atomic_number

The atomic number for the element, or closest match.

coordination

The actual coordination of the atom based on bonds in the parent. Counts all the bonds and returns an integer.

Returns:

int

Coordination of the atom

covalent_radius

Get the covalent radius from the library parameters.

del_fractional_coordinate()[source]

Remove the fractional coordinate; run after updating cell.

element

Guess the element from the type, fall back to type.

fpos(inv_cell)[source]

Fractional position within a given cell.

fractional

Retrieve the fractional coordinates or calculate from the parent.

from_cif(at_dict, cell, symmetry=None, idx=None)[source]

Extract an atom description from dictionary of cif items.

from_pdb(line, charges=False)[source]

Parse the ATOM line from a pdb file. Occupancy field may be used to specify the charge as in a ‘.pqr’ file.

from_siesta(line, cell)[source]

Parse line from SIESTA.STRUCT_OUT file.

from_vasp(line, at_type=None, cell=array([[ 1., 0., 0.], [ 0., 1., 0.], [ 0., 0., 1.]]))[source]

Set the atom data from vasp input. Only pass cell if fractional.

from_xyz(line)[source]

Parse line from generic xyz file.

get_atomic_number()[source]

The atomic number for the element, or closest match.

get_fractional_coordinate()[source]

Retrieve the fractional coordinates or calculate from the parent.

ifpos(inv_cell)[source]

In cell fractional position.

index

Return the index of the atom in the current parent structure.

ipos(cell, inv_cell)[source]

In cell cartesian position.

is_metal

Return True if element is in a predetermined set of metals.

set_atomic_number(value)[source]

Set the atom type based on the atomic number.

set_fractional_coordinate(value)[source]

Set the position using the fractional coordinates.

translate(vec)[source]

Move the atom by the given vector.

uff_coordination

The expected coordination based on the third character of the UFF name for the element. Based on _ipar from OB forcefielduff.cpp

vdw_radius

Get the vdw radius from the UFF parameters.

class faps.Cell[source]

Bases: object

Crystollagraphic cell representations and interconversion methods.

Setter methods can be defined for different file types, however .cell and .params will be self-consistent if set directly.

a

Magnitude of cell a vector.

alpha

Cell angle alpha.

b

Magnitude of cell b vector.

beta

Cell angle beta.

c

Magnitude of cell c vector.

cell

Get the 3x3 vector cell representation.

crystal_system

Return the IUCr designation for the crystal system.

from_lines(lines, scale=1.0)[source]

Extract cell from a 3-line POSCAR cell representation.

from_pdb(line)[source]

Extract cell from CRYST1 line in a pdb.

gamma

Cell angle gamma.

get_cell()[source]

Get the 3x3 vector cell representation.

get_params()[source]

Get the six parameter cell representation as a tuple.

imcon

Guess cell shape and return DL_POLY imcon key.

inverse

Inverted cell matrix for converting to fractional coordinates.

minimum_supercell(cutoff)[source]

Calculate the smallest supercell with a half-cell width cutoff.

minimum_width

The shortest perpendicular distance within the cell.

params

Get the six parameter cell representation as a tuple.

set_cell(value)[source]

Set cell and params from the cell representation.

set_params(value)[source]

Set cell and params from the cell parameters.

to_vector_strings(scale=1, bohr=False, fmt='%20.12f')[source]

Generic [Super]cell vectors in Angstrom as a list of strings.

volume

Calculate cell volume a.bxc.

class faps.Guest(ident=None, guest_path=None)[source]

Bases: object

Guest molecule and properties.

aligned_to(target, align=None, orient=None)[source]

Return the atomic positions of the guest with it located at position and aligned using the align and orient vectors. Align and orient are optional and the guest will be aligned using whatever is supplied.

Parameters:

target : tuple of int, list of float

The tuple contains the index of the atom to position the guest and the position.

align : tuple of int, list of float

The index of the atom used to align the guest followed by the alignment vector

orient : tuple of int, list of float

The index of the atom used to orient the guest followed by the orientation vector

Returns:

positions : list of list of float

The positions of the aligned atoms in a list

com

Centre of mass of the guest molecule.

is_linear(idx_1, idx_2=None, idx_3=None)[source]

Return whether the atoms at the three indexes are linear. If fewer than three indices are given, always return True.

Parameters:

idx_1 : int

Index of an atom in the guest.

idx_2 : int

Index of an atom in the guest. Optional.

idx_3 : int

Index of an atom in the guest. Optional.

Returns:

linear : bool

False if three atoms are given and they are not linear, True otherwise.

is_reversible(idx_1, idx_2=None, idx_3=None)[source]

Return whether swapping indexes will give you an equivalent guest. For example CO2 is linear and symmetric so each O atom is equivalent.

Parameters:

idx_1 : int

Index of an atom in the guest.

idx_2 : int

Index of an atom in the guest. Optional.

idx_3 : int

Index of an atom in the guest. Optional.

Returns:

reversible : bool

True if atoms are equivalent.

load_guest(ident, guest_path=None)[source]

Look in guests.lib in submit directory and default.

molar_volume

Molar volume at STP in dm3/mol

natoms

Number of atoms in the guest.

types

Ordered list of atom types.

weight

Unit cell weight.

class faps.PyNiss(options)[source]

Bases: object

PyNiss – Negotiation of Intermediate System States

A single property calculation for one structure. Instance with a set of options, then run the job_dispatcher() to begin the calculation. The calculation will pickle itself, or can be pickled at any time, by calling dump_state().

calc_surface_area(rprobe=0.0)[source]

Accessible surface area by uniform or Monte Carlo sampling.

calculate_properties()[source]

Calculate general structural properties.

calculate_pxrd()[source]

Run platon PXRD and update properties with no error trapping.

calculate_zeo_properties()[source]

Run the zeo++ and update properties with no error trapping.

dump_state()[source]

Write the .niss file holding the current system state.

email(csvs=None)[source]

Send an email, if one has not already been sent.

esp_grid

Estimate the esp grid based on resolution and memory.

esp_reduced

Has the esp been reduced to fit the memory requirements?

esp_to_cube()[source]

Make the cube for repeat input.

import_old()[source]

Try and import any data from previous stopped simulation.

job_dispatcher()[source]

Run parts explicity specified on the command line or do the next step in an automated run. Drop to interactive mode, if requested.

post_summary()[source]

Summarise any results for GCMC, properties...

postrun(jobid)[source]

Determine if we need the job handler to post submit itself.

re_init(new_options)[source]

Re initialize simulation (with updated options).

run_absl()[source]

Submit absl jobs to the queue.

run_charges()[source]

Select correct charge processing methods.

run_dft()[source]

Select correct method for running the dft/optim.

run_fastmc()[source]

Submit a fastmc job to the queue.

run_ff_opt()[source]

Prepare the system and run the selected force field optimisation.

run_optimise_gromacs()[source]

Run GROMACS to do a UFF optimisation.

run_optimise_gulp()[source]

Run GULP to do a UFF optimisation.

run_qeq_egulp()[source]

Run EGULP to calculate charge equilibration charges.

run_qeq_gulp(fitting=False)[source]

Run GULP to calculate charge equilibration charges.

run_repeat()[source]

Submit the repeat calc to the queue.

run_siesta()[source]

Make siesta input and run job.

run_vasp()[source]

Make inputs and run vasp job.

send_to_database()[source]

If using a database, store the results

status(initial=False)[source]

Print the current status to the terminal.

step_absl()[source]

Check the binding site step of the calculation.

step_charges()[source]

Check the charge step of the calculation.

step_dft()[source]

Check the DFT step of the calculation.

step_force_field()[source]

Check the force field step of the calculation.

step_gcmc()[source]

Check the GCMC step of the calculation.

step_properties()[source]

Run the properties calculations if required.

class faps.Structure(name)[source]

Bases: object

The current state of the structure; update as the calculations proceed.

Structure provides methods to produce input files for and take output from various computational chemistry packages but needs to be told what to do. Internal energy units are kcal/mol.

Methods are grouped: * Initial structure parsers * Output file parsers to update structure * Input file generation * Internal manipulation methods

absl_postproc(filepath, tp_point, options)[source]

Update structure properties from DL_POLY outputs.

atomic_numbers

Ordered list of atomic numbers.

bond_length_check(too_long=1.25, too_short=0.7)[source]

Check if all bonds fall within a sensible range of scale factors of the sum of the covalent radii. Return True if bad bonds are found, otherwise False.

charges_from_egulp(filename)[source]

Parse QEq charges from EGULP output.

charges_from_gulp(filename)[source]

Parse QEq charges from GULP output.

charges_from_repeat(filename, symmetry=False)[source]

Parse charges and update structure.

check_close_contacts(absolute=1.0, covalent=None)[source]

Check for atoms that are too close. Specify either an absolute distance in Angstrom or a scale factor for the sum of covalent radii. If a covalent factor is specified it will take priority over an absolute distance. Return True if close contacts found, else return False.

check_connectivity()[source]

Carry out pre-optimisation checks checks on the structure to determine if bonding information is included and if atom types are needed. No bonding is inferred. Return True if connectivity is bad.

Returns:bool
fastmc_postproc(filepath, tp_point, options)[source]

Update structure properties from gcmc OUTPUT.

fold_and_maxima(fold=True, find_maxima=True, tp_point=None, sigma=2.0, radius=0.31, cutoff=0.0, write=False)[source]

Determine the positions of maxima and produce an xyz xyz file.

from_cif(filename=None, string=None)[source]

Genereate structure from a .cif file.

from_file(basename, filetype, defaults)[source]

Select the correct file parser.

from_gromacs(filename)[source]

Update the structure from a gromacs optimisation G96 format file.

from_gulp_output(filename)[source]

Update the structure from the gulp optimisation output.

from_pdb(filename, charges=False)[source]

Read an initial structure from a pdb file.

from_siesta(filename)[source]

Update the structure from the siesta output.

from_vasp(filename='CONTCAR', update=False)[source]

Read a structure from a vasp [POS,CONT]CAR file.

from_xyz(filename, update=False, cell=None)[source]

Read a structure from an file.

gcmc_supercell

Supercell used for gcmc.

gen_neighbour_list(force=False)[source]

All atom pair distances.

gen_supercell(options)[source]

Cacluate the smallest satisfactory supercell and set attribute.

gen_types_from_bonds()[source]

Pass the bonding information into openbabel to get the atomic types. Modifies the atoms in place to set their uff_type attribute.

get_gcmc_supercell()[source]

Supercell used for gcmc.

natoms

Number of atoms in the unit cell.

order_by_types()[source]

Sort the atoms alphabetically and group them as in old versions. Update bonds to reflect new ordering.

remove_duplicates(tolerance=0.02)[source]

Find overlapping atoms and remove them.

set_gcmc_supercell(value)[source]

Set the supercell property for the structure.

sub_property(name, probe=None, value=None, delete=False)[source]
Helper:
Return all {probe:value} if no arguments given Return the value or None for a given probe Set area if value given Delete value if delete is True

Units are based on Angstrom

supercell(scale)[source]

Iterate over all the atoms of supercell where scale is an integer to scale uniformly or triplet with scale factors for each direction.

surface_area(probe=None, value=None, delete=False)[source]
Helper:
Return all {probe:area} if no arguments given Return the area or None for a given probe Set area if value given Delete value if delete is True

Areas in A^2

symmetry_tree

Tree of atoms that are symmetrically equivalent.

to_cif()[source]

Return a CIF file with bonding and atom types.

to_config_field(options, fastmc=False, include_guests=None, dummy=False)[source]

Return CONFIG and FIELD files in DL_POLY style

Parameters:

fastmc : boolean

When set to True, the FIELD file will contain the positions for MC guests and will give incorrect results with DL_POLY.

include_guests : dict or None

A dictionary with guests to be included in the config file with the framework. The guest type is the key and their positions are nested lists.

dummy : boolean

If dummy is set, the interaction parameters and charges for the guest are set to zero

Returns:

config : list

The config file as a list of newline terminated strings

field : list

The field file as a list of newline terminated strings

to_cssr(cartesian=False, no_atom_id=False)[source]

Return a Cerius2 cssr file with coordinates and cell as a list of strings. Set no_atom_id to produce labels to work with Zeo++.

to_egulp(typed_atoms=False)[source]

Generate input files for Eugene’s QEq code.

to_gromacs(metal_geometry='input')[source]

Generate GROMACS structure and topology.

metal_geometry will affect topology terms with metal atoms. ‘input’ will use the structure to generate the topology, and ‘fix’ will also apply a stiffer potential.

Return gro, top and itp files as lists of lines.

to_gulp(qeq_fit=False, optimise=False, terse=False, qeq_dict={})[source]

Return a GULP file to use for the QEq charges.

to_gulp_optimise(terse=False)[source]

Return a GULP file to optimise with UFF.

to_siesta(options)[source]

Return a siesta input file as a list of lines.

to_vasp(options)[source]

Return a vasp5 poscar as a list of lines.

to_zeoplusplus()[source]

Return a tuple containing a cssr file, radii file and mass file.

types

Ordered list of atom types.

update_absl(tp_point, options)[source]

Select the source for ABSL results and import.

update_charges(charge_method, options=None)[source]

Select the method for updating charges.

update_gcmc(tp_point, options)[source]

Select the source for GCMC results and import.

update_pos(opt_code, options=None)[source]

Select the method for updating atomic positions.

void_volume()[source]

Estimate the void volume based on VdW radii.

volume

Unit cell volume.

weight

Unit cell weight.

class faps.Symmetry(text)[source]

Bases: object

Apply symmetry operations to atomic coordinates.

rotate(vector)[source]

Apply only the rotation part of the symmetry operation to the vector.

trans_frac(pos, in_cell=True)[source]

Apply symmetry operation to the supplied position.

faps.angle_between(left, middle, right, cell=None)[source]

Calculate the angle between the atoms middle->left and middle->right.

If a Cell is specified, this will use the minimum image criterion to find the angle with the closest point.

Parameters:

left : Atom

one of the atoms

middle : Atom

vertex atom

left : Atom

second atom

cell : Cell or None

if a Cell object is passes the minimum image criterion will be used to calculate the angle

Returns:

angle: float

Angle between the atoms in degrees.

faps.cif_bond_dist(first_atom, second_atom, cell)[source]

Calculate the distance to the minimum image and which boundaries have been crossed for _geom_bond_site_symmetry_2.

Parameters:
  • first_atom – Atom within the cell boundary
  • second_atom – Atom to find the distance to
  • cell – Cell object
Returns:

distance, (dx, dy, dx)

faps.compress_files(files, directory='.')[source]

Gzip any big files to keep.

faps.compressed_open(filename)[source]

Return file objects for either compressed and uncompressed files

faps.count_ordered_types(atoms)[source]

Generate a list of atom types and their counts for POSCAR file.

faps.dihedral(atom_a, atom_b, atom_c, atom_d, cell=None)[source]

Calculate the dihedral angle along the path a, b, c, d.

If a Cell is specified, this will use the minimum image criterion to find the atoms that are closest for the vectors.

Parameters:

atom_a : Atom

the first atom

atom_b : Atom

one of the atoms

atom_c : Atom

one of the atoms

atom_d : Atom

one of the atoms

cell : Cell or None

if a Cell object is passes the minimum image criterion will be used to calculate the dihedral angle

Returns:

angle: float

Angle between the atoms in degrees.

faps.dot3(vec1, vec2)[source]

Calculate dot product for two 3d vectors.

faps.fix_vasp_wrapped_types(filename='CONTCAR')[source]

Output files from VASP with a long list of types sometimes get wrapped. Check if lines have been wrapped and put them all on a single line. Only works with VASP 5 outputs that include type names. Return True if the file has been modified.

Parameters:filename – name of the file to fix
Returns:bool
faps.format_tp_path(tp_point)[source]

Format the state point into a short string for use in directory naming, “Txxx.xPyy.yyPzz.zz”. Any pressures above 0.1 bar are fixed at 2 dp, anything below is allowed to float. This is to keep some backwards compatibility with old calculations.

Parameters:tp_point – (temperature, (pressure1, pressure2, ...))
Returns:string “Txxx.xPyy.yyPzz.zz”
faps.gfloat(text)[source]

Parse a gulp output float, where it could also be a rational fraction.

faps.incar_extend(incar, *args)[source]

Add the specified (key, value) pairs to the incar string list only if they are not already included in it. Only does startswith() matching, so can be fooled/broken.

faps.lorentz_berthelot(left, right)[source]

Lorentz-Berthelot mixing rules for (sigma, epsilon) tuples.

faps.main()[source]

Do a standalone calculation when run as a script.

faps.matrix_rotate(source, target)[source]

Create a rotation matrix that will rotate source on to target.

faps.min_dist(c_coa, f_coa, c_cob, f_cob_in, box)[source]

Calculate the closest distance assuming fractional, in-cell coords.

faps.min_distance(first_atom, second_atom, cell=None)[source]

Helper to find mimimum image criterion distance.

faps.minimum_image(atom1, atom2, box)[source]

Return the minimum image coordinates of atom2 with respect to atom1.

faps.mk_connectivity_ff(sym_tree)[source]

Write connectivity.ff for input tree.

faps.mk_dl_poly_control(options, dummy=False)[source]

CONTROL file for binding site energy calculation.

faps.mk_egulp_ini(options)[source]

Create a default ini file for egulp to do qeq calculation.

faps.mk_egulp_params(param_tuple)[source]

Convert an options tuple to an EGULP parameters file filling.

faps.mk_gcmc_control(temperature, pressures, options, guests, supercell=None)[source]

Standard GCMC CONTROL file.

faps.mk_gromacs_mdp(cell, mode='bfgs', verbose=False)[source]

Generate an energy minimsation file for GROMACS, with cell based cutoff.

Use mode argument to select from:
‘bfgs’ standard l-bfgs position optimisation ‘pcoupl’ zero kelivn cell semi anisotropic relaxation ‘sd’ steppest descent minimisation
faps.mk_incar(options, esp_grid=None)[source]

Basic vasp INCAR; use defaults as much as possible.

faps.mk_kpoints(kpoints)[source]

Defaults to gamma point only, or specified number.

faps.mk_repeat(cube_name='REPEAT_ESP.cube', symmetry=False)[source]

Standard REPEAT input file.

faps.mkdirs(directory)[source]

Create a directory if it does not exist.

faps.move_and_overwrite(src, dest)[source]

Move src to dest and overwrite if it is an existing file.

faps.name_from_types(sites, guest)[source]

Generate a string that gives the atoms represented in sites.

faps.other_bond_index(bond, index)[source]

Return the atom index for the other atom in a bond.

faps.parse_qeq_params(param_tuple)[source]

Convert an options tuple to a dict of values.

faps.prod(seq)[source]

Calculate the product of all members of a sequence.

faps.remove_files(files, directory='.')[source]

Delete any of the files if they exist using standard globbing, remove empty directories, or ignore silently if not found.

faps.same_guests(base, other)[source]

Test if the guests are the same index and order.

faps.state_points(temperatures, pressures, individual, nguests)[source]

Group temperatures and pressures and append given state point tuples.

faps.strip_blanks(lines)[source]

Strip lines and remove blank lines.

faps.subgroup(iterable, width, itype=None)[source]

Split an iterable into nested sub-itypes of width members.

faps.sys_argv_strip(argument)[source]

Remove an argument from the sys.argv if it is there.

faps.terminate(exit_code=0)[source]

Exit and announce if faps is terminating normally (default).

faps.try_int(text, default=0)[source]

Try to parse an integer but return a default if it fails.

Delete an existing dest file, symlink a new one if possible.

faps.ufloat(text)[source]

Convert string to float, ignoring the uncertainty part.

faps.unique(in_list, key=None)[source]

Unique values in list ordered by first occurance

faps.validate_gulp_output(filename)[source]

Check to see if gulp calculation has finished and return the energy.

faps.vecdist3(coord1, coord2)[source]

Calculate vector between two 3d points.

faps.welcome()[source]

Print any important messages.