Ångström¶

Molecule¶

class angstrom.molecule.Molecule(atoms=None, coordinates=None, read=None)[source]¶

Molecule class.

Methods

`align`(mol_vector, align_vector[, center, mass])	Align molecule to given vector using molecule vector.
`center`([coor, mass])	Move linker to given coordinates using it’s center
`get_bonds`()	Estimate molecular bonding.
`get_center`([mass])	Get coordinates for molecule center.
`get_molecular_weight`()	Calculate molecular weight.
`read`(filename)	Read molecule file.
`reflect`(plane[, translate])	Get mirror image of a molecule by reflecting each atom through a plane of reflection.
`replicate`(replication[, center])	Build a supercell by replicating the cell.
`rotate`(axis_point1, axis_point2, angle[, …])	Rotate molecule around an axis defined by two point by a given angle in degrees.
`set_cell`(cellpar)	Set cell for molecule.
`translate`(vector)	Translate molecule by given vector.
`write`(filename[, bonds, cell, header, group])	Write molecule file.

align(mol_vector, align_vector, center=False, mass=True)[source]¶

Align molecule to given vector using molecule vector.

Parameters:	mol_vector : ndarray Molecule vector to be aligned. align_vector : ndarray Target vector to align the molecule. center : bool Keep the molecule at the same position after alignment (default: False). mass : bool Use atomic mass for calculating the center (default: True).
Returns:	None Modifies ‘coordinates’ attribute of the Molecule object.

center(coor=[0, 0, 0], mass=True)[source]¶

Move linker to given coordinates using it’s center

Parameters:	coor : ndarray Destination coordinate of the molecule. mass : bool Use atomic mass for calculating the center (default: True).
Returns:	None Modifies ‘coordinates’ attribute of the Molecule object by calling the ‘translate’ method.

get_bonds()[source]¶

Estimate molecular bonding.

Parameters:	None
Returns:	None Assigns ‘bonds’ attribute.

get_center(mass=True)[source]¶

Get coordinates for molecule center.

Parameters:	mass : bool Calculate center of mass (True) or geometric center (False).
Returns:	ndarray Molecule center coordinates.

get_molecular_weight()[source]¶

Calculate molecular weight.

Parameters:	None
Returns:	float Molecular weight of the Molecule object.

read(filename)[source]¶

Read molecule file.

Parameters:	filename : str Molecule file name (formats: xyz).
Returns:	None Assigns ‘coordinates’, ‘atoms’, and ‘header’, and ‘name’ attributes.

reflect(plane, translate=None)[source]¶

Get mirror image of a molecule by reflecting each atom through a plane of reflection.

Parameters:	plane : Plane Mirror plane defined by either 3 points or a string (ex: ‘xy’) for main planes. translate : float or None Translate the molecule after reflection by given amount on the axis normal to the plane.
Returns:	None Modifies ‘coordinates’ attribute of the Molecule object.

replicate(replication, center=True)[source]¶

Build a supercell by replicating the cell.

Parameters:	replication : list Replication in cell vectors -> [a, b, c].
Returns:	Molecule The replicated Molecule object.

rotate(axis_point1, axis_point2, angle, center=False, mass=True)[source]¶

Rotate molecule around an axis defined by two point by a given angle in degrees. The direction of rotation is counter-clockwise given that axis is defined as p2 - p1. To reverse direction you can multiply angle with -1 or reverse axis points. To rotate molecule on it’s local axis use center=True. This will prevent the molecule from moving after rotation.

Example (rotate around y-axis by 90 degrees):

>>> molecule.rotate([0, 0, 0], [0, 1, 0], np.pi)

This would rotate the molecule around y-axis by 90 degrees counter-clockwise.

Parameters:

axis_point1 : list: 3D coordinates for the first point that defines axis of rotation.
axis_point2 : list: 3D coordinates for the second point that defines axis of rotation.
angle : float: Degree of rotation (radians).
center : bool: Keep the molecule at the same position after rotation (default: False).
mass : bool: Use atomic mass for calculating the center (default: True).

Returns:

None: Modifies ‘coordinates’ attribute of the Molecule object.

set_cell(cellpar)[source]¶

Set cell for molecule.

Parameters:	cellpar : list Cell parameters -> [a, b, c, alpha, beta, gamma].
Returns:	None Assigns ‘cell’ attribute as a Cell object.

translate(vector)[source]¶

Translate molecule by given vector.

Parameters:	vector : ndarray Translation vector.
Returns:	None Modifies ‘coordinates’ attribute of the Molecule object.

write(filename, bonds=False, cell=None, header='angstrom', group=None)[source]¶

Write molecule file.

Parameters:	filename : str Molecule file name, file format extracted from file extension (formats: xyz \| pdb \| cif). bonds : bool Write atomic bonding (used in pdb format). cell : list Write unit cell parameters (used in cif format). header : str Molecule file header. group : list Atom grouping (used in pdb format).
Returns:	None Writes molecule information to given file name.

Cell¶

class angstrom.molecule.Cell(cellpar)[source]¶

Cell class for unit cell and periodic boundary operations.

Methods

`calculate_edges`()	Calculate coordinates of two points for each edge of the unit cell in the following order:
`calculate_vectors`()	Calculates cell vectors.
`calculate_vertices`()	Calculate coordinates of unit cell vertices in the following order:
`calculate_volume`()	Calculates cell volume and fractional volume.
`car2frac`(car_coor)	Convert cartesian coordinates to fractional coordinates.
`frac2car`(frac_coor)	Convert fractional coordinates to cartesian coordinates.
`supercell`(atoms, coordinates, replication[, …])	Builds a supercell for given replication in a, b, and c directions of the cell.
`to_list`()	Returns cell parameters as a list.

calculate_edges()[source]¶

Calculate coordinates of two points for each edge of the unit cell in the following order:

1. (a, 0, 0) - (0, 0, 0) | 2. (0, b, 0) - (0, 0, 0) | 3. (0, 0, c) - (0, 0, 0) 4. (a, b, 0) - (a, 0, 0) | 5. (a, 0, c) - (a, 0, 0) | 6. (a, b, 0) - (0, b, 0) 7. (0, b, c) - (0, b, 0) | 8. (0, b, c) - (0, 0, c) | 9. (a, 0, c) - (0, 0, c) 10. (a, b, c) - (a, b, 0) | 11. (a, b, c) - (0, b, c) | 12. (a, b, c) - (a, 0, c)

Parameters:	None
Returns:	None Assigns ‘edges’ attribute to the Cell object.

calculate_vectors()[source]¶

Calculates cell vectors.

Parameters:	None
Returns:	None Assigns ‘vectors’ attribute to the Cell object.

calculate_vertices()[source]¶

Calculate coordinates of unit cell vertices in the following order:

(0, 0, 0) - (a, 0, 0) - (0, b, 0) - (0, 0, c) - (a, b, 0) - (0, b, c) - (a, 0, c) - (a, b, c)

Parameters:	None
Returns:	None Assigns ‘vertices’ attribute to the Cell object.

calculate_volume()[source]¶

Calculates cell volume and fractional volume.

Parameters:	None
Returns:	None Assigns ‘volume’ and ‘frac_volume’ attributes to the Cell object.

car2frac(car_coor)[source]¶

Convert cartesian coordinates to fractional coordinates.

Parameters:	atoms : ndarray List of atom types.
Returns:	list Fractional coordinates.

Notes

Requires ‘to_frac’ attribute which is calculated for Cell objects during initialization.

frac2car(frac_coor)[source]¶

Convert fractional coordinates to cartesian coordinates.

Parameters:	atoms : ndarray List of atom types.
Returns:	list Cartesian coordinates.

Notes

Requires ‘to_car’ attribute which is calculated for Cell objects during initialization.

supercell(atoms, coordinates, replication, center=True)[source]¶

Builds a supercell for given replication in a, b, and c directions of the cell.

Parameters:	atoms : ndarray List of atom types. coordinates : ndarray List of atomic coordinates. replication : list Replication in cell vectors -> [a, b, c]. center : bool Keep the original cell at the center.
Returns:	Cell Supercell with replicated coordinates and atoms.

Notes

The X represents the original cell. The position of the original cell can be selected using the ‘center’ keyword argument:

center=True center=False ————- ————- | | | | | | | | ————- ————- | | X | | | | | | ————- ————- | | | | | X | | | ————- ————-

to_list()[source]¶: Returns cell parameters as a list.

Bonds¶

— Ångström — Molecular bonding estimation for Ångström Python package.

angstrom.molecule.bonds.get_bonds(atoms, coordinates, RADIUS_BUFFER=0.45, MIN_BOND_DISTANCE=0.16)[source]¶

Estimate molecular bonding by calculating interatomic distance. If two atoms are closer to each other than the sum of their covalent radii and RADIUS_BUFFER then the atoms are considered bonded. If atoms are closer to each other than MIN_BOND_DISTANCE then they are not bonded. The covalent radii for atoms are taken from Pyykkö et al.[1].

Parameters:	atoms : list List of atom names. coordinates : list List of atomic coordinates. RADIUS_BUFFER : float Atomic radius buffer (Å). MIN_BOND_DISTANCE : float Minimum bonding distance (Å).
Returns:	list List of bonded atoms as tuples sorted according to atom index of the first atom.

References

[1]	Pyykkö, Pekka, and Michiko Atsumi, Molecular single‐bond covalent radii for elements 1–118.

Chemistry–A European Journal 15.1 (2009): 186-197.

Write¶

— Ångström — Methods for writing chemical file formats.

angstrom.molecule.write.write_cif(fileobj, atoms, coordinates, cell=None, header='angstrom')[source]¶

Write given atomic coordinates to file in cif format.

Parameters:	fileobj : file object File object for the xyz file. atoms : list List of atom names. coordinates : list List of atomic coordinates. cell : list Unit cell parameters -> [a, b, c, alpha, beta, gamma]. header : str File header.
Returns:	None Creates a new .cif file.

angstrom.molecule.write.write_molecule(filename, atoms, coordinates, bonds=None, group=None, cell=None, header='angstrom')[source]¶

Write molecule file. Supprted formats -> (xyz | pdb | cif) The file format is extracted from the file extension.

Parameters:	filename : str Molecule file name. atoms : list List of atom names. coordinates : list List of atomic coordinates. bonds : list Atomic bonding (used in pdb format). group : list Atom grouping (used in pdb format). cell : list Unit cell parameters -> [a, b, c, alpha, beta, gamma] (used in cif format). header : str Molecule file header.
Returns:	None Writes molecule information to given file name.

angstrom.molecule.write.write_pdb(fileobj, atoms, coordinates, bonds=None, group=None, header='angstrom')[source]¶

Write given atomic coordinates to file object in pdb format.

Parameters:	fileobj : file object File object for the pdb file. atoms : list List of atom names. coordinates : list List of atomic coordinates. bonds : list Atom bonding. group : list or None Residue number for each atom. header : str File header.
Returns:	None Creates a new .pdb file.

angstrom.molecule.write.write_xyz(fileobj, atoms, coordinates, header='angstrom')[source]¶

Write given atomic coordinates to file object in xyz format.

Parameters:	fileobj : file object File object for the xyz file. atoms : list List of atom names. coordinates : list List of atomic coordinates. header : str File header.
Returns:	None Creates a new .xyz file.

Read¶

— Ångström — Methods for reading chemical file formats.

angstrom.molecule.read.read_xyz(filename)[source]¶

Read xyz file format.

Parameters:	filename : str xyz file name.
Returns:	dict atom names and coordinates: -> {‘atoms’: [‘C’, …], ‘coordinates’: [[x1, y1, z1], …]}.

Trajectory¶

class angstrom.trajectory.Trajectory(atoms=None, coordinates=None, read=None)[source]¶

Reading and analyzing trajectories in xyz format.

Methods

`get_center`([mass])	Get coordinates of molecule center at each frame.
`read`(filename)	Read xyz formatted trajectory file.
`write`(filename)	Write xyz formatted trajectory file.

get_center(mass=True)[source]¶

Get coordinates of molecule center at each frame.

Parameters:	mass : bool Calculate center of mass (True) or geometric center (False).
Returns:	ndarray Molecule center coordinates for each frame.

read(filename)[source]¶

Read xyz formatted trajectory file.

Parameters:	filename : str Trajectory file name.
Returns:	None Assigns ‘coordinates’, ‘atoms’, and ‘headers’ attributes.

write(filename)[source]¶

Write xyz formatted trajectory file.

Parameters:	filename : str Trajectory file name (formats: xyz).
Returns:	None Writes molecule information to given file name.

Write¶

— Ångström — Functions for writing Trajectory files.

angstrom.trajectory.write.write_xyz_traj(fileobj, atoms, coordinates, headers=None)[source]¶

Write given trajectory to file object in xyz format.

Parameters:	fileobj : file object File object for the xyz file. atoms : list List of atom names. coordinates : list List of atomic coordinates. headers : list List of strings to write in the second line as header (optional).
Returns:	None Creates a new .xyz file.

Read¶

— Ångström — Read trajectory from molecular file formats.

angstrom.trajectory.read.read_xyz_traj(filename)[source]¶

Read xyz trajectory and return coordinates as a list. Assumes number of atoms is constant.

Parameters:	filename : str Trajectory file in xyz format.
Returns:	dict Trajectory dictionary with ‘atoms’, ‘coordinates’, ‘timestep’ and ‘xyz’ keys.

Geometry¶

— Ångström — Geometric operations for Ångström Python package.

angstrom.geometry.geometry.align_vectors(v1, v2, norm=True)[source]¶

Calculates the rotation axis and angle to align two vectors (v1 to v2).

Parameters:	v1: ndarray Vector 1. v2: ndarray Vector 2, norm: bool Normalize vectors (default: True),
Returns:	dict Rotation axis and angle for aligning vectors,
Warns:	RuntimeWarning If v1 and v2 are already aligned (parallel). In this case the angle will be returned 0.

angstrom.geometry.geometry.get_molecule_center(atoms, coordinates, mass=True)[source]¶

Calculate center of mass or geometric center for given coordinates and atom names of a molecule.

Parameters:	atoms: ndarray List of element names. coordinates: ndarray List of coordinates (2D list). mass: bool Use atomic masses (True) or calculate geometric center (False).
Returns:	ndarray Center coordinate.

Plane¶

class angstrom.geometry.Plane(*args, size=1)[source]¶

Plane object. Initialized by either giving 3 points or a string (ex: ‘xy’) for main planes.

Methods

`get_center`()	Get center point of the plane.
`grid`(size[, space])	Calculate grid points for the plane for given grid size and spacing.
`reflect`(point)	Get mirror image of a point through the plane of reflection.

get_center()[source]¶

Get center point of the plane.

Returns:	ndarray Center point

grid(size, space=1)[source]¶

Calculate grid points for the plane for given grid size and spacing.

Three points P1(x1, y1, z1), P2(x2, y2, z2), P3(x3, y3, z3):

P2 o…..o…..o P3: o…..o…..o
Pn o…..o…..o: o…..o…..o
P1 o…..o…..o: Pm

Parameters:	size: float Grid size. space: float Grid point spacing.
Returns:	ndarray Grid points.

reflect(point)[source]¶

Get mirror image of a point through the plane of reflection.

Parameters:	point: list 3D point to be reflected.
Returns:	ndarray Mirror image of the point.

Quaternion¶

class angstrom.geometry.Quaternion(param_list)[source]¶

Quaternion class for quaternion operations and 3D rotations.

Methods

`inv`()	Returns the inverse of the quaternion as a new quaternion.
`np`()	Returns numpy array if x, y, z values.
`rotation`(rotation_point, axis_point1, …)	Rotation of a point around an axis defined by two points in 3D space.
`xyz`()	Returns x, y, z values of the quaternion in list format.

inv()[source]¶

Returns the inverse of the quaternion as a new quaternion.

Returns:	Quaternion The inverse of the Quaternion object.

np()[source]¶

Returns numpy array if x, y, z values.

Returns:	ndarray A numpy array of x, y, and z values respectively.

rotation(rotation_point, axis_point1, axis_point2, rotation_angle)[source]¶

Rotation of a point around an axis defined by two points in 3D space. The direction of rotation is counter-clockwise given that axis is defined as p2 - p1. Rotation angle needs to be given in radians.

Parameters:	rotation_point: list The point to rotate. axis_point1: list Point 1 to define the axis of rotation. axis_point2: list Point 2 to define the axis of rotation. rotation_angle: float Rotation angle in radians.
Returns:	Quaternion Quaternion with rotated point.

Examples

>>> import numpy as np
>>> Q = Quaternion([0, 1, 1, 1])
>>> Q = Q.rotation(Q.xyz(), [-2, 4, 6.1], [0.3, 1.2, -0.76], np.pi/6)
[2.1192250600275795, 2.2773560513200133, 5.890236840657188]

xyz()[source]¶

Returns x, y, z values of the quaternion in list format.

Returns:	list A list of x, y, and z values respectively.

Visualize¶

Render¶

— Ångström — Render molecular images and animations.

angstrom.visualize.render.render(molecule, img_file, renderer='blender', settings=None, verbose=False)[source]¶

Render Molecule object.

Parameters:	molecule : Molecule Ångström Molecule object. img_file : str File name for the image file to be saved (use .svg for OpenBabel and .png for Blender). renderer : str Rendering software ([blender] \| openbabel). settings : dict or None Rendering settings.
Returns:	None Saves image file.

angstrom.visualize.render.render_blender(mol_file, img_file, settings, verbose=False)[source]¶

Render molecular images using Blender.

Parameters:	mol_file : str Molecule file in .pdb format. img_file : str Image file (recommended file format: png). settings : dict Blender rendering settings. verbose : bool Blender rendering script verbosity.
Returns:	None Saves image file.

angstrom.visualize.render.render_openbabel(mol_file, img_file, settings=['-xS', '-xd', 'xb', 'none'])[source]¶

Render molecular images using OpenBabel.

Parameters:	mol_file : str Molecule file. img_file : str Image file (recommended file format: svg). settings : list List of command line arguments.
Returns:	None Saves image file.

angstrom.visualize.render.render_vmd(mol_file, img_file, settings, verbose=False)[source]¶

Render molecular images using VMD.

Parameters:	mol_file : str Molecule file. img_file : str Image file. settings : str VMD visualization state file.
Returns:	None Saves image file.

Show¶

— Ångström — Show molecular images and animations. Works well with Jupyter notebook to visualize molecules in browser.

angstrom.visualize.show.show(*molecules, arrange=True, nx=5, distance=(-10, -10), camera='perspective', caps=True, save=None)[source]¶

Show molecule objects using nglview.

Parameters:

molecules : Molecule: Any number Molecule objects.
arrange : bool: Arrange structure positions (default: True).
nx : int: Number of structures in x axis (horizontal).
distance : tuple: Separation distance in x and y axes.
camera : str: Camera style -> ‘perspective’ / ‘orthographic’.
caps : bool: Make atom names all capital letters (required for nglview to assign correct color).
save : str or None: Save visualized structure in pdb format as given filename.

Returns:

view: nglview “view” object.

Tools¶

— Ångström — Visualization tools for arranging molecule positions and more.

angstrom.visualize.tools.arrange_molecules(molecules, arrange=True, nx=5, distance=(-10, -10), caps=True)[source]¶

Arrange molecules in a 2D grid for better visual representation.

Parameters:	molecules : tuple Molecule objects. arrange : bool Arrange structure positions (default: True). nx : int Number of structures in x axis (horizontal). distance : tuple Separation distance in x and y axes. caps : bool Make atom names all capital letters (required for nglview to assign correct color).
Returns:	tuple Atom coordinates, atom names, and group (residue) numbers.

angstrom.visualize.tools.arrange_positions(n_structures, nx=5, distance=(10, 10))[source]¶

Calculate translation vectors to arrange positions of structures.

Parameters:	n_structures : int Total number of structures. nx : int Number of structures in x axis (horizontal). distance : tuple Separation distance in x and y axes.
Returns:	ndarray Translation vectors to arrange structure positions.

Render Settings¶

— Ångström — Render settings for molecular visualization.

angstrom.visualize.render_settings.get_blender_settings(executable='blender', render=True, save='', model='default', camera_zoom=20, camera_distance=10, camera_view='xy', camera_type='ORTHO', resolution=(1920, 1080), brightness=1.0, lamp=2.0, colors={'Carbon': (0.05, 0.05, 0.05), 'Hydrogen': (1.0, 1.0, 1.0), 'Nitrogen': (0.18, 0.34, 0.95), 'Oxygen': (0.7, 0.0, 0.0)}, verbose=False, script='/home/docs/checkouts/readthedocs.org/user_builds/angstrom/envs/numpydoc/lib/python3.5/site-packages/angstrom/visualize/blender_image.py', pickle='temp-settings.pkl')[source]¶

Get Blender image rendering settings.

Parameters:

executable : str: Path to blender executable (depends on OS).
render : bool: Render image switch.
save : str: Saves .blend file to given filename.
model : str: Molecule model (default | ball-and-stick | space_filling).
camera_zoom : float: Camera zoom / focal length (default: 20).
camera_distance : float: Distance between the camera and the molecule (default: 10).
camera_view : str: Camera view plane (xy | xz | yx | yz | zx | zy).
camera_type : str: Camera type (ORTHO | PERSP).
resolution : tuple: Image resolution (default: 1920 x 1080).
brightness : float: Image brighness (environmental lightning).
lamp : float: Lamp strength (default: 2).
colors : dict: Atom colors in RGB | ex: {‘Carbon’: (0.1, 0.1, 0.1), ‘Oxygen’: (0.7, 0.0, 0.0)}.
verbose : bool: Blender subprocess verbosity.
script : str: Python script to render the image.
pickle : str: Pickle file for communicating settings with Blender.

Returns:

dict: Blender render settings.

angstrom.visualize.render_settings.openbabel_settings = ['-xS', '-xd', 'xb', 'none']¶: ———————————– BLENDER SETTINGS ———————————————–