Chemical Bonding

Chemical bonding interactions are represented in the bonds attribute of a Crystal as a graph where the nodes of the graph correspond to the crystal's atoms.

Bonding Rules

Xtals uses an array of BondingRule structs stored at rc for deciding if two atoms are an appropriate distance to be chemically bonded. The default rules are based on the Cordero covalent radii, modified based on the work of Thomas Manz. Each BondingRule is composed of two chemical species symbols and a floating point value, the maximum distance for inferring a bond between the indicated species.

BondingRule(:C, :C, 1.77)

The global bonding rules are accessible at rc[:bonding_rules] and may be augmented with add_bonding_rules or written to/read from disk with write_bonding_rules and read_bonding_rules. The default rules are determined from rc[:covalent_radii] at module load, but are not recalculated upon changes to the covalent radii. If rc[:covalent_radii] is altered and new bonding rules should be calculated, the user must do rc[:bonding_rules] = bondingrules().

Adding Bonds to Crystals

By default, bonding information is not added to a Crystal. Use infer_bonds! or infer_geometry_based_bonds to automatically infer plausible bonds using the global bonding rules, or another specified set of rules. remove_bonds! clears the bonding information from a Crystal.

Bonds may also be inferred at the time of loading crystal data, using the infer_bonds keyword argument. See Crystal for more details.

Bonds from Input File

Some chemical information formats, like .cif and .mol, can store not only the cartesian coordinates of atoms, but also the graph of bonds between atoms in molecules and crystals. The read_bonds_from_file keyword argument for Crystal enables loading these bonds when reading the data. read_mol also returns bond information.

Detailed Docs

Xtals.BondingRule — Type

bonding_rule = BondingRule(:Ca, :O, 2.0)
bonding_rules = [BondingRule(:H, :*, 1.2),
                 BondingRule(:*, :*, 1.9)]

A rule for determining if two atoms within a crystal are bonded.

Attributes

species_i::Symbol: One of the atoms types for this bond rule
species_j::Symbol: The other atom type for this bond rule
max_dist: The maximum distance between the atoms for bonding to occur

source

Xtals.add_bonding_rules — Function

add_bonding_rules(bonding_rules)

Adds bonding_rules to the beginning of the global bonding rules list

Arguments

bonding_rules::Array{BondingRule} : the array of bonding rules to add

source

Xtals.read_bonding_rules — Function

read_bonding_rules("file.csv")

Reads a CSV file of bonding rules and returns a BondingRule array.

Arguments

filename::String : name of file in data directory containing bonding rules

Returns

rules::Array{BondingRule} : the bonding rules read from file

source

Xtals.write_bonding_rules — Function

write_bonding_rules("file.csv")

Writes bonding rules to a CSV file that can be loaded with read_bonding_rules

Arguments

filename::String : The name of the output file
bonding_rules::Array{BondingRule} : (Optional) The rules to write to file. If not specified, the global rules are written.

source

Xtals.infer_bonds! — Function

infer_bonds!(crystal, include_bonds_across_periodic_boundaries, bonding_rules=nothing)

Populate the bonds in the crystal object based on the bonding rules. If a pair doesn't have a suitable rule then they will not be considered bonded.

:* is considered a wildcard and can be substituted for any species. It is a good idea to include a bonding rule between two :* to allow any atoms to bond as long as they are close enough.

The bonding rules are hierarchical, i.e. the first bonding rule takes precedence over the latter ones.

Arguments

crystal::Crystal: The crystal that bonds will be added to
include_bonds_across_periodic_boundaries::Bool: Whether to check across the periodic boundary when calculating bonds
bonding_rules::Union{Array{BondingRule, 1}, Nothing}=nothing: The array of bonding rules that will be used to fill the bonding information. They are applied in the order that they appear. if nothing, default bonding rules will be applied; see get_bonding_rules

source

Xtals.remove_bonds! — Function

remove_bonds!(crystal)

Remove all bonds from a crystal structure, crystal::Crystal.

source

Xtals.infer_geometry_based_bonds! — Function

infer_geometry_based_bonds!(crystal, include_bonds_across_periodic_boundaries::Bool)

Infers bonds by first finding which atoms share a Voronoi face, and then bond the atoms if the distance between them is less than the sum of the covalent radius of the two atoms (plus a tolerance).

Arguments

crystal::Crystal: The crystal structure
include_bonds_across_periodic_boundaries::Bool: Whether to check across the periodic boundaries
r::Float: voronoi radius, Å
pad::Float: amount to pad covalent radii, Å
covalent_radii::Dict{Symbol,Float64}: See covalent_radii

source

Xtals.write_bond_information — Function

write_bond_information(crystal, filename)
write_bond_information(crystal, center_at_origin=false)
write_bond_information(xtal, filename, :cross_boundary => p -> p, "bonds.vtk") # cross boundary bonds only
write_bond_information(xtal, filename, :distance => d -> d < 1.0, "bonds.vtk") # distance less than 1.0

Writes the bond information from a crystal to the selected filename.

Arguments

crystal::Crystal: The crystal to have its bonds written to a vtk file
filename::String: The filename the bond information will be saved to. If left out, will default to crystal name.
center_at_origin::Bool: (optional) center the coordinates at the origin of the crystal
bond_filter::Pair{Symbol, Function}: (optional) a key-value pair of an edge attribute and a predicate function. Bonds with attributes that cause the predicate to return false are excluded from writing.

source

Xtals.read_mol — Function

atoms, bonds = read_mol("molecule.mol")

read a .mol file, which contains info about both atoms and bonds. see here for the anatomy of a .mol file.

Arguments

filename::AbstractString: the path to and filename of the .mol file (must pass extension)

Returns

atoms::Atoms{Cart}: the set of atoms read from the .mol file.
bonds::MetaGraph: the bonding graph of the atoms read from the .mol file.
bond_types::Array{Int, 1}: the array of bond types.

source