Reading data from crystal structure and chemical fragment files into PoreMatMod.jl

q = moiety(xyz_filename)

Generates a moiety (Crystal) from an .xyz file found in rc[:paths][:moieties].

Use set_path_to_data or set rc[:paths][:moieties] to change the path from which the XYZ file is read.

Atoms appended with '!' are tagged for replacement via substructure_replace.

Bonds are inferred automatically via infer_bonds!.

Arguments

• xyz_filename::Union{String,Nothing} the moiety input file name, an .xyz file; if set to nothing the moiety is the null set.
• bonding_rules::Union{Vector{BondingRule},Nothing} (optional) a list of rules to use for inferring the bonding network of the atoms loaded from the XYZ file. If set to nothing, the default rules are used.

crystal = Crystal(filename;
    check_neutrality=true, net_charge_tol=1e-4,
    check_overlap=true, convert_to_p1=true, 
    read_bonds_from_file=false, wrap_coords=true,
    include_zero_charges=true,
    remove_duplicates=false,
    species_col=["_atom_site_type_symbol", "_atom_site_label"]
    ) # read from file

crystal = Crystal(name, box, atoms, charges) # construct from matter, no bonds, P1-symmetry assumed

Read a crystal structure file (.cif or .cssr) and populate a Crystal data structure, or construct a Crystal data structure directly.

Arguments

• filename::String: the name of the crystal structure file (include ".cif" or ".cssr") read from PATH_TO_CRYSTALS.
• check_neutrality::Bool: check for charge neutrality
• net_charge_tol::Float64: when checking for charge neutrality, throw an error if the absolute value of the net charge is larger than this value.
• check_overlap::Bool: throw an error if overlapping atoms are detected.
• convert_to_p1::Bool: If the structure is not in P1 it will be converted to P1 symmetry using the symmetry rules from the _symmetry_equiv_pos_as_xyz list in the .cif file. (We do not use the space groups name to look up symmetry rules).
• read_bonds_from_file::Bool: Whether or not to read bonding information from cif file. If false, the bonds can be inferred later. note that, if the crystal is not in P1 symmetry, we cannot both read bonds and convert to P1 symmetry.
• wrap_coords::Bool: if true, enforce that fractional coords of atoms and charges are in [0,1]³ by mod(x, 1)
• include_zero_charges::Bool: if false, do not include in crystal.charges atoms which have zero charges, in order to speed up the electrostatic calculations. If true, include the atoms in crystal.charges that have zero charge, ensuring that the number of atoms is equal to the number of charges and that crystal.charges.coords.xf and crystal.atoms.coords.xf are the same.
• remove_duplicates::Bool: remove duplicate atoms and charges. an atom is duplicate only if it is the same species.
• species_col::Array{String}: which column to use for species identification for crystal.atoms.species. we use a priority list: we check for the first entry of species_col in the .cif file; if not present, we then use the second entry, and so on.
• infer_bonds::Union{Symbol, Missing}: if set, bonds are inferred according to the chosen method (:cordero or :voronoi). If set, must specify periodic_boundaries. By default, bonds are not inferred.
• periodic_boundaries::Union{Bool, Missing}: use with infer_bonds to specify treatment of the unit cell boundary. Set true to treat the unit cell edge as a periodic boundary (allow bonds across it); set false to restrict bonding to within the local unit cell.

across periodic unit cell boundaries; if false, bonds are only inferred within the local unit cell; if missing (default), bonds are not inferred.

Returns

• crystal::Crystal: A crystal containing the crystal structure information

Attributes

• name::AbstractString: name of crystal structure
• box::Box: unit cell (Bravais Lattice)
• atoms::Atoms: list of Atoms in crystal unit cell
• charges::Charges: list of point charges in crystal unit cell
• bonds::MetaGraph: Unweighted, undirected graph showing all of the atoms that are bonded within the crystal
• symmetry::SymmetryInfo: symmetry inforomation

infer_bonds!(crystal, include_bonds_across_periodic_boundaries; bonding_rules=rc[:bonding_rules])

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::Array{BondingRule, 1}: The array of bonding rules that will be used to fill the bonding information. They are applied in the order that they appear. rc[:bonding_rules] will be used if none provided.
• calculate_vectors::Bool: Optional. Set true to annotate all edges in the bonds graph with vector information.

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

strip_numbers_from_atom_labels!(crystal)

Strip numbers from labels for crystal.atoms. Precisely, for atom in crystal.atoms, find the first number that appears in atom. Remove this number and all following characters from atom. e.g. C12 –> C Ba12A_3 –> Ba

Arguments

• crystal::Crystal: The crystal containing the crystal structure information