Ångström

Molecule

Molecule

class angstrom.molecule.Molecule(atoms=None, coordinates=None, read=None)

Molecule class.

Methods

align(self, mol_vector, align_vector[, …])	Align molecule to given vector using molecule vector.
center(self[, coor, mass])	Move linker to given coordinates using it’s center
delete(self, atom_ids)	Delete a list of atoms with given indices.
get_angles(self)	Iterate over bonds to get angles.
get_bonds(self)	Estimate molecular bonding.
get_center(self[, mass])	Get coordinates for molecule center.
get_chemical_formula(self)	Get chemical formula of the molecule.
get_dihedrals(self)	Iterate over bonds to get dihedrals.
get_impropers(self)	Iterate over angles to get impropers.
get_molecular_weight(self)	Calculate molecular weight.
get_topology(self)	Estimate molecular topology (bonds, angles, dihedrals, and impropers).
read(self, filename)	Read molecule file.
reflect(self, plane[, translate])	Get mirror image of a molecule by reflecting each atom through a plane of reflection.
replicate(self, replication[, center])	Build a supercell by replicating the cell.
rotate(self, axis, angle[, center, mass])	Rotate molecule around an axis defined by two point by a given angle in degrees.
set_cell(self, cellpar)	Set cell for molecule.
translate(self, vector)	Translate molecule by given vector.
write(self, filename[, bonds, cell, header, …])	Write molecule file.

align(self, mol_vector, align_vector, center=False, mass=True)

Align molecule to given vector using molecule vector.

Parameters

mol_vectorndarray

Molecule vector to be aligned.

align_vectorndarray

Target vector to align the molecule.

centerbool

Keep the molecule at the same position after alignment (default: False).

massbool

Use atomic mass for calculating the center (default: True).

Returns

None

Modifies ‘coordinates’ attribute of the Molecule object.

center(self, coor=[0, 0, 0], mass=True)

Move linker to given coordinates using it’s center

Parameters

coorndarray

Destination coordinate of the molecule.

massbool

Use atomic mass for calculating the center (default: True).

Returns

None

Modifies ‘coordinates’ attribute of the Molecule object by calling the ‘translate’ method.

delete(self, atom_ids)

Delete a list of atoms with given indices.

Parameters

atom_idslist

List of atom indices to delete.

get_angles(self)

Iterate over bonds to get angles.

get_bonds(self)

Estimate molecular bonding.

get_center(self, mass=True)

Get coordinates for molecule center.

Parameters

massbool

Calculate center of mass (True) or geometric center (False).

Returns

ndarray

Molecule center coordinates.

get_chemical_formula(self)

Get chemical formula of the molecule.

Parameters

None

Returns

dict

Chemical formula with elements as keys and counts as values.

get_dihedrals(self)

Iterate over bonds to get dihedrals.

get_impropers(self)

Iterate over angles to get impropers.

get_molecular_weight(self)

Calculate molecular weight.

Parameters

None

Returns

float

Molecular weight of the Molecule object.

get_topology(self)

Estimate molecular topology (bonds, angles, dihedrals, and impropers).

read(self, filename)

Read molecule file.

Parameters

filenamestr

Molecule file name (formats: xyz).

Returns

None

Assigns ‘coordinates’, ‘atoms’, and ‘header’, and ‘name’ attributes.

reflect(self, plane, translate=None)

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

Parameters

planePlane

Mirror plane defined by either 3 points or a string (ex: ‘xy’) for main planes.

translatefloat 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(self, replication, center=True)

Build a supercell by replicating the cell.

Parameters

replicationlist

Replication in cell vectors -> [a, b, c].

Returns

Molecule

The replicated Molecule object.

rotate(self, axis, angle, center=False, mass=True)

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: tuple

Tuple of 3D points defining the axis of rotation.

anglefloat

Degree of rotation (radians).

centerbool

Keep the molecule at the same position after rotation (default: False).

massbool

Use atomic mass for calculating the center (default: True).

Returns

None

Modifies ‘coordinates’ attribute of the Molecule object.

set_cell(self, cellpar)

Set cell for molecule.

Parameters

cellparlist

Cell parameters -> [a, b, c, alpha, beta, gamma].

Returns

None

Assigns ‘cell’ attribute as a Cell object.

translate(self, vector)

Translate molecule by given vector.

Parameters

vectorndarray

Translation vector.

Returns

None

Modifies ‘coordinates’ attribute of the Molecule object.

write(self, filename, bonds=False, cell=None, header='angstrom', group=None)

Write molecule file.

Parameters

filenamestr

Molecule file name, file format extracted from file extension (formats: xyz | pdb | cif).

bondsbool

Write atomic bonding (used in pdb format).

celllist

Write unit cell parameters (used in cif format).

headerstr

Molecule file header.

grouplist

Atom grouping (used in pdb format).

Returns

None

Writes molecule information to given file name.

Cell

class angstrom.molecule.Cell(cellpar)

Cell class for unit cell and periodic boundary operations.

Methods

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

calculate_edges(self)

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(self)

Calculates cell vectors.

Parameters

None

Returns

None

Assigns ‘vectors’ attribute to the Cell object.

calculate_vertices(self)

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(self)

Calculates cell volume and fractional volume.

Parameters

None

Returns

None

Assigns ‘volume’ and ‘frac_volume’ attributes to the Cell object.

car2frac(self, car_coor)

Convert cartesian coordinates to fractional coordinates.

Parameters

atomsndarray

List of atom types.

Returns

list

Fractional coordinates.

Notes

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

frac2car(self, frac_coor)

Convert fractional coordinates to cartesian coordinates.

Parameters

atomsndarray

List of atom types.

Returns

list

Cartesian coordinates.

Notes

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

supercell(self, atoms, coordinates, replication, center=True)

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

Parameters

atomsndarray

List of atom types.

coordinatesndarray

List of atomic coordinates.

replicationlist

Replication in cell vectors -> [a, b, c].

centerbool

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(self)

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)

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

atomslist

List of atom names.

coordinateslist

List of atomic coordinates.

RADIUS_BUFFERfloat

Atomic radius buffer (Å).

MIN_BOND_DISTANCEfloat

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')

Write given atomic coordinates to file in cif format.

Parameters

fileobjfile object

File object for the xyz file.

atomslist

List of atom names.

coordinateslist

List of atomic coordinates.

celllist

Unit cell parameters -> [a, b, c, alpha, beta, gamma].

headerstr

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')

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

Parameters

filenamestr

Molecule file name.

atomslist

List of atom names.

coordinateslist

List of atomic coordinates.

bondslist

Atomic bonding (used in pdb format).

grouplist

Atom grouping (used in pdb format).

celllist

Unit cell parameters -> [a, b, c, alpha, beta, gamma] (used in cif format).

headerstr

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')

Write given atomic coordinates to file object in pdb format.

Parameters

fileobjfile object

File object for the pdb file.

atomslist

List of atom names.

coordinateslist

List of atomic coordinates.

bondslist

Atom bonding.

grouplist or None

Residue number for each atom.

headerstr

File header.

Returns

None

Creates a new .pdb file.

angstrom.molecule.write.write_xyz(fileobj, atoms, coordinates, header='angstrom')

Write given atomic coordinates to file object in xyz format.

Parameters

fileobjfile object

File object for the xyz file.

atomslist

List of atom names.

coordinateslist

List of atomic coordinates.

headerstr

File header.

Returns

None

Creates a new .xyz file.

Read

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

angstrom.molecule.read.read_xyz(filename)

Read xyz file format.

Parameters

filenamestr

xyz file name.

Returns

dict

atom names and coordinates: -> {‘atoms’: [‘C’, …], ‘coordinates’: [[x1, y1, z1], …]}.

Trajectory

Trajectory

class angstrom.trajectory.Trajectory(atoms=None, coordinates=None, read=None, molecule=None)

Reading and analyzing trajectories in xyz format.

Methods

append(self, mol)	Append molecule to trajectory.
get_center(self[, mass])	Get coordinates of molecule center at each frame.
read(self, filename)	Read xyz formatted trajectory file.
write(self, filename)	Write xyz formatted trajectory file.

append(self, mol)

Append molecule to trajectory. The number of atoms in the molecule must match that of the trajectory.

Parameters

molMolecule

Molecule object to be added

Returns

None

Added to Trajectory object.

get_center(self, mass=True)

Get coordinates of molecule center at each frame.

Parameters

massbool

Calculate center of mass (True) or geometric center (False).

Returns

ndarray

Molecule center coordinates for each frame.

read(self, filename)

Read xyz formatted trajectory file.

Parameters

filenamestr

Trajectory file name.

Returns

None

Assigns ‘coordinates’, ‘atoms’, and ‘headers’ attributes.

write(self, filename)

Write xyz formatted trajectory file.

Parameters

filenamestr

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)

Write given trajectory to file object in xyz format.

Parameters

fileobjfile object

File object for the xyz file.

atomslist

List of atom names.

coordinateslist

List of atomic coordinates.

headerslist

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)

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

Parameters

filenamestr

Trajectory file in xyz format.

Returns

dict

Trajectory dictionary with ‘atoms’, ‘coordinates’, ‘timestep’ and ‘xyz’ keys.

Geometry

Geometry

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

angstrom.geometry.geometry.align_vectors(v1, v2, norm=True)

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)

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)

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

Methods

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

get_center(self)

Get center point of the plane.

Returns

ndarray

Center point

grid(self, size, space=1)

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(self, point)

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)

Quaternion class for quaternion operations and 3D rotations.

Methods

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

inv(self)

Returns the inverse of the quaternion as a new quaternion.

Returns

Quaternion

The inverse of the Quaternion object.

np(self)

Returns numpy array if x, y, z values.

Returns

ndarray

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

rotation(self, rotation_point, rotation_axis, rotation_angle)

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.

rotation_axis: tuple or str

Tuple of 3D points defining the axis of rotation. If ‘x’, ‘y’, or ‘z’ is given primary axes are used.

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(self)

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(render_obj, output='angstrom', renderer='blender', verbose=False)

Render Molecule object.

Parameters

render_objMolecule or Trajectory

Ångström Molecule (for image) or Trajectory (for video) object.

outputstr

File name for the render without extension.

rendererstr or object

The renderer can be either a string (‘blender’ | ‘openbabel’) or a renderer object. Using a string would select default configuration for each renderer. To configure renderer settings the renderer object should be initialized separately and used here as an argument.

verbosebool

Verbosity.

Returns

None

Saves image / video file.

Notes

Image renderers:

Blender: ‘png’ image format is recommended. OpenBabel: ‘svg’ image format is recommended.

Video renderers:

Blender: Background color is white by default. See Blender configuration for more options.

angstrom.visualize.render.render_image(molecule, img_file, renderer, verbose=False)

Renders image of a Molecule object.

Parameters

moleculeMolecule

Ångström Molecule object.

img_filestr

File name for the image file to be saved (use .svg for OpenBabel and .png for Blender).

rendererobject

Renderer object (blender | openbabel).

verbosebool

Verbosity.

Returns

None

Saves image file.

Notes

Blender: ‘png’ image format is recommended. OpenBabel: ‘svg’ image format is recommended.

angstrom.visualize.render.render_video(trajectory, vid_file, renderer, verbose=False)

Renders video of a Trajectory object.

Parameters

trajectoryTrajectory

Ångström Trajectory object.

vid_filestr

File name for the video file to be saved (no extension required).

rendererobject

Renderer object (blender).

verbosebool

Verbosity.

Returns

None

Saves video file.

Notes

Blender: Background color is white by default. See Blender configuration for more options.

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)

Show molecule objects using nglview.

Parameters

moleculesMolecule

Any number Molecule objects.

arrangebool

Arrange structure positions (default: True).

nxint

Number of structures in x axis (horizontal).

distancetuple

Separation distance in x and y axes.

camerastr

Camera style -> ‘perspective’ / ‘orthographic’.

capsbool

Make atom names all capital letters (required for nglview to assign correct color).

savestr 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)

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

Parameters

moleculestuple

Molecule objects.

arrangebool

Arrange structure positions (default: True).

nxint

Number of structures in x axis (horizontal).

distancetuple

Separation distance in x and y axes.

Returns

tuple

Atom coordinates, atom names, and group (residue) numbers.

angstrom.visualize.tools.arrange_positions(n_structures, nx=5, distance=10, 10)

Calculate translation vectors to arrange positions of structures.

Parameters

n_structuresint

Total number of structures.

nxint

Number of structures in x axis (horizontal).

distancetuple

Separation distance in x and y axes.

Returns

ndarray

Translation vectors to arrange structure positions.

Render Settings