A package for manipulating xyz files and chemical structures
Project description
xyz-py
xyz-py is a python module for working with and manipulating chemical structures.
Installation
For convenience, xyz-py is available on PyPI and so can be installed using pip
pip install xyz-py
Functionality
To use the functions included in xyz-py, first import it into your python file
import xyz_py as xyzp
and then call them as
xyzp.function_name(arguments)
To find information on any of the functions included in xyz-py, use the help command from within a python environment, e.g.
help(xyzp.function_name)
```Module xyz_py
=============
Functions
---------
`add_numbers(labels: list, style: str = 'per_element')`
: Add numbers to a list of atomic labels
Parameters
----------
labels (list) :
atomic labels
style (str, optional) :
{'per_element', 'sequential'}
'per_element' : Number by element e.g. Dy1, Dy2, N1, N2, etc.
'sequential' : Number the atoms 1->N regardless of element
Returns
-------
labels_wn (list) :
atomic labels with numbers
`calculate_rmsd(coords_1: list, coords_2: list, mask_1: list = [], mask_2: list = [], order_1: list = [], order_2: list = [])`
: Calculates RMSD between two structures
RMSD = sqrt(mean(deviations**2))
Where deviations are defined as norm([x1,y1,z1]-[x2,y2,z2])
If coords_1 and coords_2 are not the same length, then a mask array can be
provided for either/both and is applied prior to the calculation
coords_1 and coords_2 can also be reordered if new orders are specified
- note this occurs BEFORE masking
Parameters
----------
coords_1 (list) :
list of lists of xyz coordinates of each atom
coords_2 (list) :
list of lists of xyz coordinates of each atom
mask_1 (list) :
list of 0 (exclude) and 1 (include) for each element in coords_1
mask_2 (list) :
list of 0 (exclude) and 1 (include) for each element in coords_2
order_1 (list) :
list of new indices for coords_1 - applied BEFORE masking
order_2 (list) :
list of new indices for coords_2 - applied BEFORE masking
Returns
-------
rmsd (float) :
Root mean square of norms of deviation between two structures
`combine_xyz(labels_1: list, labels_2: list, coords_1: list, coords_2: list)`
: Combine two sets of labels and coordinates
Parameters
----------
labels_1 (list) :
Atomic labels
coords_1 (list) :
list of lists of xyz coordinates of each atom
labels_2 (list) :
Atomic labels
coords_2 (list) :
list of lists of xyz coordinates of each atom
Returns
-------
labels (list) :
Combined atomic labels
coords (list) :
Combined list of lists of xyz coordinates of each atom
`contains_metal(form_string: str)`
: Indicates if a metal is found in a chemical formula string
Parameters
----------
form_string (str) :
Chemical formula as string
Returns
-------
metal_found (int) :
Combined atomic labels
`count_elements(labels: list)`
: Count number of each element in a list of elements
Parameters
----------
labels (list) :
atomic labels
Returns
-------
ele_count (dict) :
dictionary of elements (keys) and counts (vals)
`count_n_atoms(form_str: str)`
: Count number of atoms in a chemical formula
Parameters
----------
form_str (str) :
chemical formula string
Returns
-------
n_atoms (int) :
number of atoms in chemical formula
`formdict_to_formstr(form_dict: dict, include_one: bool = False)`
: Converts dictionary of {atomic label:quantity} pairs into
a single formula string
Parameters
----------
form_dict (dict) :
dictionary of {atomic label:quantity} pairs
include_one (bool, optional) :
Include 1 in final chemical formula e.g. C1H4
Returns
-------
form_string (str) :
Chemical formula as string
`formstr_to_formdict(form_str: str)`
: Converts formula string into dictionary of {atomic label:quantity} pairs
Parameters
----------
form_string (str) :
Chemical formula as string
Returns
-------
form_dict (dict) :
dictionary of {atomic label:quantity} pairs
`get_adjacency(labels: list, coords: list, adjust_cutoff: dict = {}, save: bool = False, f_name: str = 'adjacency.dat')`
: Calculate adjacency matrix using ASE built in cutoffs with option to
modify them
Parameters
----------
labels (list) :
Atomic labels
coords (list) :
list of lists of xyz coordinates of each atom
adjust_cutoff (dict, optional) :
dictionary of atoms (keys) and new cutoffs (values)
Returns
-------
adjacency (numpy array) :
Adjacency matrix with same order as labels/coords
`get_angles(labels: list, coords: list, neigh_list=None, f_name: str = 'angles.dat', save: bool = False, verbose: bool = True, style: bool = 'indices')`
: Calculate and save list of atoms between which there is a bond angle.
Using ASE. Only unique angles are saved.
e.g. 0-1-2 but not 2-1-0
Parameters
----------
labels (list) :
Atomic labels
coords (list) :
list of lists of xyz coordinates of each atom
neigh_list (ASE neighbourlist object, optional) :
neighbourlist of system
f_name (str, optional) :
filename to save angle list to
save (bool, optional) :
Save angle list to file
verbose (bool, optional) :
Print number of angles to screen
style (str, optional) :
{'index','label'}
indices : Angle list contains atom number
labels : Angle list contains atom label
Returns
-------
angles (list) :
list of unique angles (atom trios)
`get_bonds(labels: list, coords: list, neigh_list=None, f_name: str = 'bonds.dat', save: bool = False, verbose: bool = True, style: bool = 'indices')`
: Calculate and save list of atoms between which there is a bond.
Using ASE. Only unique angles are saved.
e.g. 0-1 and not 1-0
Parameters
----------
labels (list) :
Atomic labels
coords (list) :
list of lists of xyz coordinates of each atom
Keyword arguments:
neigh_list (ASE neighbourlist object, optional) :
neighbourlist of system
f_name (str, optional) :
filename to save bond list to
save (bool, optional) :
Save bond list to file
verbose (bool, optional :
Print number of bonds to screen
style (str, optional :
{'index','label'}
indices : Bond list contains atom number
labels : Bond list contains atom label
Returns
-------
bonds (list) :
list of unique bonds (atom pairs)
`get_dihedrals(labels: list, coords: list, neigh_list=None, f_name: str = 'dihedrals.dat', save: bool = False, verbose: bool = True, style: bool = 'indices')`
: Calculate and save list of atoms between which there is a dihedral.
Using ASE. Only unique angles are saved.
e.g. 0-1-2-3 but not 3-2-1-0
Parameters
----------
labels (list) :
Atomic labels
coords (list) :
list of lists of xyz coordinates of each atom
neigh_list (ASE neighbourlist object, optional) :
neighbourlist of system
f_name (str, optional) :
filename to save angle list to
save (bool, optional) :
Save angle list to file
verbose (bool, optional) :
Print number of dihedrals to screen
style (str, optional) :
{'index','label'}
indices : Dihedral list contains atom number
labels : Dihedral list contains atom label
Returns
-------
dihedrals (list) :
list of unique dihedrals (atom quads)
`get_neighborlist(labels: list, coords: list, adjust_cutoff: dict = {})`
: Calculate ASE neighbourlist with cutoffs
Parameters
----------
labels (list) :
Atomic labels
coords (list) :
list of lists of xyz coordinates of each atom
adjust_cutoff (dict, optional) :
dictionary of atoms (keys) and new cutoffs (values)
Returns
-------
neigh_list (ASE neighbourlist object) :
Neighbourlist for system
`index_elements(labels: list, shift: int = 0)`
: Return dictionary of element (keys) and indices (values) from list
of labels
Parameters
----------
labels (list) :
atomic labels
shift (int, optional):
additive shift to apply to all indices
Returns
-------
ele_index (dict) :
dictionary of element (keys) and indices (values)
`lab_to_num(labels: list)`
: Convert atomic label to atomic number
Parameters
----------
labels (list) :
Atomic labels
Returns
-------
numbers (list) :
Atomic numbers
`load_xyz(f_name: str, atomic_numbers: bool = False)`
: Load labels and coordinates from a .xyz file
Parameters
----------
f_name (str) :
File name
atomic_numbers (bool, optional) :
If true, will read xyz file with atomic numbers and convert
to labels
Returns
-------
_labels (list) :
atomic labels
_coords (list) :
list of 3 element lists containing xyz coordinates of each atom
`minimise_rmsd(coords_1: list, coords_2: list, mask_1: list = [], mask_2: list = [], order_1: list = [], order_2: list = [])`
: Minimising the RMSD between two structures
If coords_1 and coords_2 are not the same length, then a mask array can be
provided for either/both and is applied prior to the calculation
coords_1 and coords_2 can also be reordered if new orders are specified
- note this occurs BEFORE masking
Parameters
----------
coords_1 (list) :
list of lists of xyz coordinates of each atom
coords_2 (list) :
list of lists of xyz coordinates of each atom
mask_1 (list) :
list of 0 (exclude) and 1 (include) for each element in coords_1
mask_2 (list) :
list of 0 (exclude) and 1 (include) for each element in coords_2
order_1 (list) :
list of new indices for coords_1 - applied BEFORE masking
order_2 (list) :
list of new indices for coords_2 - applied BEFORE masking
Returns
-------
rmsd (float) :
Root mean square of norms of deviation between two structures
`num_to_lab(numbers: list, numbered: bool = True)`
: Convert atomic number to atomic labels
Parameters
----------
numbers (list) :
Atomic numbers
numbered (bool, optional) :
Add indexing number to end of atomic labels
Returns
-------
labels (list) :
Atomic labels
`reflect_coords(coords: list)`
: Reflect coordinates through xy plane
Parameters
----------
coords (list) :
list of lists of xyz coordinates of each atom
Returns
-------
coords (list) :
list of lists of xyz coordinates of each atom
`remove_broken(labels: list, coords: list, formulae: list, adjust_cutoff: dict = {}, verbose: bool = False, save: bool = False, frag_f_name: str = 'fragments.xyz', clean_f_name: str = 'clean.xyz', mask: list = [], skip: list = [])`
: Removes structures from coords which do not match formula in formulae
Uses ASE to generate adjacency matrix and draw out bonding in coords
allowing formulae of fragments to be found.
Parameters
----------
labels (list) :
list of atomic labels
coords (list) :
list of lists of xyz coordinates of each atom
formulae (list) :
list of chemical formulae stored as dictionaries with atomic
symbol (key) count (val) pairs
adjust_cutoff (dict, optional) :
dictionary of atoms (keys) and new cutoffs (values)
verbose (bool, optional) :
print molecule count to screen
save (bool, optional) :
Save molecules and incomplete fragments to separate xyz files
frag_f_name (str, optional) :
Name for xyz file containing fragmented structures
clean_f_name (str, optional) :
Name for xyz file containing full molecules
mask (list, optional) :
list of 0 (exclude) and 1 (include) for each element
- if used, final lists will exclude masked elements
skip (list, optional) :
List of atomic indices which shall not be visited when tracing
bonding network
Returns
-------
labels_clean (list) :
list of atomic labels for full molecules
coords_clean (list) :
list of lists of xyz coordinates of each atom for full molecules
labels_fragments (list) :
list of atomic labels for fragments
coords_fragments (list) :
list of lists of xyz coordinates of each atom for fragments
mol_indices (dict) :
dictionary containing indices of complete molecules -
keys = molecular formula,
vals = list of lists of atomic indices
for each atom
`remove_numbers(labels: list)`
: Remove numbers from a list of atomic labels
Parameters
----------
labels (list) :
atomic labels
Returns
-------
labels_nn (list) :
atomic labels without numbers
`rotate_coords(coords: list, alpha: float, beta: float, gamma: float)`
: Rotates coordinates by alpha, beta, gamma using the zyz convention
https://easyspin.org/easyspin/documentation/eulerangles.html
Parameters
----------
coords_1 (list) :
list of lists of xyz coordinates of each atom
alpha (float) :
alpha angle in radians
beta (float) :
beta angle in radians
gamma (float) :
gamma angle in radians
Returns
-------
rot_coords (list) :
list of lists of xyz coordinates of each atom after rotation
`save_xyz(f_name: str, labels: list, coords: list, with_numbers: bool = False, verbose: bool = True, mask: list = [], atomic_numbers: bool = False)`
: Add numbers to a list of atomic labels
Parameters
----------
f_name (str) :
File name
labels (list) :
atomic labels
coords (list) :
list of 3 element lists containing xyz coordinates of each atom
with_numbers (bool, optional) :
If True, add/overwrite numbers to labels before printing
verbose (bool, optional) :
Print information on filename to screen
mask (list, optional) :
n_atom list of 0 (exclude) and 1 (include) indicating which
atoms to print
atomic_numbers (bool, optional) :
If true, will save xyz file with atomic numbers
Returns
-------
None
Release history Release notifications | RSS feed
Download files
Download the file for your platform. If you're not sure which to choose, learn more about installing packages.
Source Distribution
xyz_py-0.0.20.tar.gz
(16.8 kB
view hashes)
Built Distribution
xyz_py-0.0.20-py3-none-any.whl
(16.6 kB
view hashes)
