User Interface

Atom

The Atom class is a useful way of keeping track of properties of an atom, such as its atomic number, charge and position

class render_molecules.atom.Atom(atomic_number: int, element: str, charge: float, x: float, y: float, z: float, is_angstrom: bool)

Bases: object

Parameters:

• atomicNumber (int) – atomic number. For example, for iron atom, 26

• element (str) – element. For example, for iron atom, Fe

• charge (float) – charge of atom

• x (float) – x-coordinate

• y (float) – y-coordinate

• z (float) – z-coordinate

• isAngstrom (bool) – whether coordinates are in Angstrom. If False, assume in Bohr

classmethod from_cube_string(string: str)

Create Atom instance from a line in a CUBE file

Parameters:

string (str) – line in CUBE file

classmethod from_xyz_string(string: str)

Create Atom instance from a line in an XYZ file

Parameters:

string (str) – line from an XYZ file. Formatted as A x y z …, where A is either atomic number or element string

classmethod from_sdf_string(string: str)

Create Atom instance from a line in an SDF file

Parameters:

string (str) – line from an SDF file. Formatted as x y z A, where A is an element string.

get_atomic_number() → int

Get the atomic number of the atom

Returns:

atomic number

Return type:

int

get_charge() → float

Get the charge of the Atom (undefined if created from XYZ file)

Returns:

charge of Atom

Return type:

float

get_x() → float

Get the x-coordinate of the atom

Returns:

x-coordinate of Atom

Return type:

float

get_y() → float

Get the y-coordinate of the atom

Returns:

y-coordinate of Atom

Return type:

float

get_z() → float

Get the z-coordinate of the atom

Returns:

z-coordinate of Atom

Return type:

float

get_position() → ndarray[float]

Get position of the atom

Returns:

array with x, y and z coordinates of Atom

Return type:

ndarray

position_bohr_to_angstrom() → None

Convert the position vector from Bohr to Angstrom

set_position(new_position) → None

Set the position of the atom to a new position

Parameters:

newPosition (ndarray) – x, y and z coordinates of new position

get_element() → str

Get the element of the atom

Returns:

element of Atom

Return type:

str

get_mass() → float

Get the mass of the atom

Returns:

mass of Atom

Return type:

float

get_vdw_radius() → float

Get the Van der Waals radius of the atom

Returns:

Van der Waals radius of the Atom

Return type:

float

Bond

class render_molecules.bond.Bond(atom1_index: int, atom2_index: int, bond_type: str, bond_length: float, interatomic_vector: ndarray, midpoint_position: ndarray, atom1_and_2_pos: ndarray, name: str)

Bases: object

get_atom1_index() → int

Get the index of the first atom that is connected to this bond

get_atom2_index() → int

Get the index of the second atom that is connected to this bond

get_bond_type() → str

Get the bond type (the two connecting elements in alphabetical order)

get_length() → float

Get the bond length

get_interatomic_vector() → ndarray[float]

Get the vector connecting the two atoms

get_midpoint() → ndarray[float]

Get the midpoint position of the two atoms

set_midpoint(midpoint_position: ndarray) → None

Set the midpoint position of the two atoms

get_direction() → ndarray[float]

Get the unit vector in the direction of the bond

get_atom1_position() → ndarray[float]

Get position of atom 1

get_atom2_position() → ndarray[float]

Get position of atom 2

get_name() → str

set_name(name) → None

get_axis_angle_with_z() → tuple[float, float, float, float]

Get the axis angle such that a created cylinder in the direction of the bond

get_vdw_weighted_cylinder_midpoints(element1: str, element2: str) → ndarray

Get the Van der Waals-radii weighted location where both cylinders need to be placed

get_vdw_weighted_midpoint(element1: str, element2: str) → ndarray

Get the Van der Waals-radii weighted bond-midpoints

Structure

class render_molecules.structure.Structure(atoms: list[Atom], bonds: list[Bond] | None = None)

Bases: Geometry

get_atoms() → list[Atom]

Get a list of all atoms in the structure

get_atom_positions() → list[ndarray]

Get a list of all atom positions

create_atoms(resolution: str = 'medium', create_mesh: bool = True, force_material_creation: bool = False, atom_colors: dict | None = None) → None

Create the atoms in the scene

Parameters:

• resolution (str) – resolution of created spheres. One of [‘verylow’, ‘low’, ‘medium’, ‘high’, ‘veryhigh’]

• create_mesh (bool) – create mesh of vertices. saves memory, but atom positions cannot be animated

• force_material_creation (bool) – force creation of new materials with element names, even though materials with that name already exist. This is useful for if you want to change the atom colors

• atom_colors (dict) – dictionary of atom colors, with keys elements and values hex-codes. If None, use the element_data.manifest['atom_colors']. Can also be partially filled, e.g. only contain {'H': 'FFFFFF'} for H2O, and then the color of O atoms will be filled by the values in element_data.manifest['atom_colors'].

find_bonds_from_distances() → list[Bond]

Create bonds based on the geometry

generate_bond_order_bond(bond: Bond, bond_order: int, camera_position: ndarray[float], displacement_scaler=0.2) → list[Bond]

Way to generate multiple bonds, for example in CO2 molecule double bonds, or CO triple bonds.

get_bonds() → list[Bond]

Get all bonds in the system

get_center_of_mass() → ndarray[float]

Get the center of mass position vector

set_center_of_mass(new_center_of_mass: ndarray | list) → None

Set the Center Of Mass (COM) of the whole system to a new position

Parameters:

new_center_of_mass (ndarray) – new COM position

set_average_position(new_average_position: ndarray | list)

Sets the average position of all atoms to a new position

translate(translation_vector: ndarray) → None

Translate every atom in the Structure along a vector

Parameters:

translationVector (ndarray) – vector to translate every atom

get_total_charge() → int

Get the total charge in the system

Returns:

total charge of the system

Return type:

total_charge (int)

get_nr_electrons() → int

Get the total amount of electrons in the system

Returns:

total number of electrons in the system

Return type:

total_electrons (int)

is_radical() → bool

Returns whether the studied structure is a radical (has an uneven amount of electrons)

Returns:

whether the system is a radical or not

Return type:

bool

rotate_around_axis(axis: ndarray, angle: float) → None

Rotate the structure around a certain axis

Parameters:

• axis (ndarray) – 3D vector around which to rotate the structure

• angle (float) – angle with which to rotate the structure. Given in angles, counterclockwise

get_inertia_tensor() → ndarray

Get the moment of inertia tensor

Returns:

inertia tensor in kg m^2

Return type:

inertiaTensor (ndarray)

get_principal_moments_of_inertia() → tuple[ndarray, ndarray]

Get the principal moments of inertia and the principal axes

Returns:

array of length 3 with the three principal moments of inertia in kg m^2 principalAxes (ndarray): matrix of shape 3x3 with three principal moment axes

Return type:

principalMoments (ndarray)

create_hydrogen_bonds() → None

Adds hydrogen bonds to each molecule

create_bonds(bonds: list[Bond], split_bond_to_atom_materials: bool = True, resolution: str = 'medium', atom_colors: dict | None = None, force_material_creation: bool = False) → None

Create the bonds in the Blender scene

Parameters:

• bonds (list[Bond]) – list of bonds to be drawn

• split_bond_to_atom_materials (bool) – whether to split up the bonds to the two atom materials connecting them

• resolution (str) – render resolution. One of [‘verylow’, ‘low’, ‘medium’, ‘high’, ‘veryhigh’]

• atom_colors (dict) – dictionary of atom colors, with keys elements and values hex-codes. If None, use the element_data.manifest['atom_colors']. Can also be partially filled, e.g. only contain {'H': 'FFFFFF'} for H2O, and then the color of O atoms will be filled by the values in element_data.manifest['atom_colors'].

• force_material_creation (bool) – force creation of new materials with element names, even though materials with that name already exist. This is useful for if you want to change the atom colors

create_structure(resolution: str = 'medium', create_mesh: bool = True, atom_colors: dict | None = None, split_bond_to_atom_materials: bool = True, force_material_creation: bool = False) → None

Create the atoms and bond in the scene

Parameters:

• resolution (str) – resolution of created spheres. One of [‘verylow’, ‘low’, ‘medium’, ‘high’, ‘veryhigh’]

• create_mesh (bool) – create mesh of vertices. saves memory, but atom positions cannot be animated

• force_material_creation (bool) – force creation of new materials with element names, even though materials with that name already exist. This is useful for if you want to change the atom colors

• atom_colors (dict) – dictionary of atom colors, with keys elements and values hex-codes. If None, use the element_data.manifest['atom_colors']. Can also be partially filled, e.g. only contain {'H': 'FFFFFF'} for H2O, and then the color of O atoms will be filled by the values in element_data.manifest['atom_colors'].

• split_bond_to_atom_materials (bool) – whether to split up the bonds to the two atom materials connecting them

• force_material_creation – force creation of new materials with element names, even though materials with that name already exist. This is useful for if you want to change the atom colors

join_bonds()

Join bonds. DOES NOT WORK YET

displace_atoms(displacements: ndarray) → None

Displace all atoms along different displacement vectors

Parameters:

displacements (ndarray) – matrix of shape natoms * 3, vectors to displace atoms

classmethod from_xyz(filepath: str)

Create a Structure from an XYZ file

Parameters:

filepath (str) – XYZ file to read

classmethod from_sdf(filepath: str)

Creates a Structure from an SDF file

Parameters:

filepath (str) – SDF file to read

classmethod from_xsf(filepath: str)

Creates a Structure from an XSF file. To be tested

Parameters:

filepath (str) – XSF file to read

class render_molecules.structure.CUBEfile(filepath: str)

Bases: Structure

read_volumetric_data() → None

Read the volumetric data in the CUBE file

get_volumetric_origin_vector() → ndarray[float]

Get the origin vector of the volumetric data

Returns:

np.ndarray of length 3 corresponding to x, y and z coordinates of volumetric origin

Return type:

ndarray

get_volumetric_axis_vectors() → ndarray[float]

Get the axis vectors of the volumetric data

Returns:

np.ndarray of length 3 corresponding to i, j and k axis vectors of volumetric data

Return type:

ndarray

get_volumetric_data() → ndarray[float]

Get the volumetric data

Returns:

matrix of shape NX*NY*NZ containing volumetric data

Return type:

ndarray

write_ply(filepath: str, isovalue: float) → None

Write the volumetric data to a filepath

Parameters:

• filepath (str)

• isovalue (float)

calculate_isosurface(isovalue: float, step_size: int = 1) → tuple[ndarray, ndarray, int]

Calculate the isosurface from the volumetric data and an isovalue

Parameters:

• isovalue (float) – value where to calculate the isosurface

• step_size (int) – step size in the grid. Larger values result in coarser, but quicker, results. Default = 1

Returns:

Vx3 array of floats corresponding to vertex positions faces (ndarray): Fx3 array of integers corresponding to vertex indices normals (ndarray): Vx3 array of floats corresponding to normal direction at each vertex values (ndarray): Vx1 array of maximum value in data close to each vertex

Return type:

vertices (ndarray)

class render_molecules.structure.JSONfile(filepath)

Bases: Structure

WORK IN PROGRESS

Trajectory

class render_molecules.trajectory.Trajectory(frames: list[Structure])

Bases: Geometry

get_frames() → list[Structure]

Get all frames in the trajectory

get_nframes() → int

Get the number of frames in the trajectory

set_center_of_mass(new_center_of_mass: ndarray, frame_index: int = 0) → None

Set the Center Of Mass (COM) of the structure at index ‘frameIndex’ to a new position

Parameters:

• newCOMposition (np.ndarray) – new COM position [x, y, z], in Angstrom

• frameIndex (int) – frame index to position according to COM

create_animation(create_bonds: bool = True, resolution: str = 'medium', split_bond_to_atom_materials: bool = True) → None

Create the animation of the trajectory in the Blender scene

get_frame(frame_index: int) → Structure

Get the Structure at a certain frame index

rotate_around_axis(axis: ndarray, angle: float) → None

Rotate all frames in the trajectory around an axis counterclockwise with a certain angle in degrees

classmethod from_xyz(filepath: str)

Generate a trajectory from an XYZ file containing multiple frames

classmethod from_xsf(filepath: str)

classmethod from_orca(filepath: str, use_vibrations: bool = True, use_geometry_optimization: bool = False, vibration_nr: str | int = 'imag', n_frames_per_oscillation: int = 20, amplitude: float = 0.5)

Get a Trajectory from an ORCA output file.

Parameters:

• filepath (str) – filepath of ORCA output file

• use_vibrations (bool) – whether to use the vibrations

• use_geometry_optimization (bool)

• vibration_nr (str | int) – vibration number index, or string (then has to be one of ['i', 'im', 'imag', 'imaginary']). Vibration number index is 0-indexed (i.e. 0 is the first vibrational mode, 1 is the second, etc.)

• n_frames_per_oscillation (int) – number of keyframes per full vibrational oscillation (phase= \(2\pi\))

• amplitude (float) – amplitude of vibrations. 0.5 seems to be a good default value.

Notes

• Tries to find imaginary mode from the output. If multiple imaginary modes are found, will raise an error. Please investigate the output file manually to see which one you want to visualize, and give the integer index to this function instead.

• Calculates the vibrational trajectory from the normal modes. ORCA outputs the translational and rotational modes as vibrations too, meaning that often the first 6 vibrations (so up to and including vibration_nr=5) have no displacements, and the resulting Trajectory will show no movement.

translate(translation_vector: ndarray | list) → None

Geometry

class render_molecules.geometry.Geometry

Bases: object

get_affine_matrix() → ndarray

set_affine_matrix(new_affine_matrix: ndarray) → None

add_transformation(affine_transform_matrix: ndarray) → None

translate(translation_vector) → None

rotate_around_axis(axis, angle) → None

rotate_around_x(angle: float) → None

Rotate the geometry around the x-axis counterclockwise with a certain angle in degrees

rotate_around_y(angle: float) → None

Rotate the geometry around the y-axis counterclockwise with a certain angle in degrees

rotate_around_z(angle: float) → None

Rotate the geometry around the z-axis counterclockwise with a certain angle in degrees

render_molecules.geometry.rotation_matrix(axis: list | ndarray, theta: float) → ndarray

Return the rotation matrix associated with counterclockwise rotation about the given axis by theta degrees.

render_molecules.geometry.angle_between(vector1: ndarray | list, vector2: ndarray | list) → float

Get the angle between two vectors.

Parameters:

• vector1 (ndarray) – list or np array of length 3

• vector2 (ndarray) – list or np array of length 3

Returns:

angle between two vectors in degrees

Return type:

float

render_molecules.geometry.check_3d_vector(vector: list | ndarray) → ndarray

render_molecules.geometry.check_4x4_matrix(matrix: ndarray) → ndarray

Blender utilities

render_molecules.blender_utils.create_uv_sphere(element: str, position: ndarray, resolution: str = 'medium') → object

render_molecules.blender_utils.get_all_materials() → object

render_molecules.blender_utils.delete_all_materials() → None

render_molecules.blender_utils.create_mesh_of_atoms(positions: ndarray, reference_sphere: object, element: str) → None

render_molecules.blender_utils.material_exists(mat)

Function to determine whether a material already exists. WIP

render_molecules.blender_utils.create_material(name: str, color: str, alpha: float = 1.0, force: bool = False) → object

Build a new material

Parameters:

• name (str) – name of material

• color (str) – color of material

• alpha (float) – transparency of material

• force (bool) – whether to force creation of the new material, regardless of if another material with that name already exists. If True, will remove other materials with that same name.

Returns:

created material

Return type:

mat (object)

Notes

• If a material with name name already exists and force=False is used, returns that material instead.

render_molecules.blender_utils.delete_all_objects()

Deletes all objects in the current scene

render_molecules.blender_utils.create_isosurface(verts: ndarray, faces: ndarray, isovalue: float, prefix: str = 'isosurface', color: str = 'sign', alpha: float = 0.5) → None

Creates isosurface from vertices and faces output from a marching cubes calculation.

Parameters:

• verts (np.ndarray) – Vx3 array of floats corresponding to vertex positions

• faces (np.ndarray) – Fx3 array of integers corresponding to vertex indices

• isovalue (float) – isovalue used to calculate the isosurface

• prefix (str) – prefix to put in front of the isovalue to get its name

• color (str) – color of isosurface. Can also be "sign", and then it is colored using the sign of isovalue, and the constants.manifest['isosurface_color_negative'] or constants.manifest['isosurface_color_positive'].

• alpha (float) – transparency of created isosurface.

Notes

• render_molecules.structure.CUBEfile.calculate_isosurface() can be used to calculate the vertices and faces.

• This function creates a material called Isosurface. Once created, any time create_isosurface is called again, it will call create_material again with the same name. That will return the original material again, so the new isosurface will have the same color and transparency. This is something I will have to fix somehow. Maybe by adding a material_name argument to this function, which can be changed by the user so that if they wish to have a different material on a second isosurface they simply specify a different material name for the two isosurfaces?

render_molecules.blender_utils.load_ply(filepath, color: str = 'sign', alpha=0.5)

render_molecules.blender_utils.assign_isosurface_material_based_on_sign(isosurface_obj: object, isovalue: float, alpha=0.5) → None

render_molecules.blender_utils.try_autosmooth()

render_molecules.blender_utils.set_background_transparency(transparency: bool) → None

render_molecules.blender_utils.set_background_color(rgba: tuple[float]) → None

render_molecules.blender_utils.adjust_settings(is_one_render: bool = True, transparent_background: bool = True) → None

render_molecules.blender_utils.outline_in_render(render_outline: bool = True, thickness: float = 5) → None

render_molecules.blender_utils.select_object_by_name(name: str, select=True) → None

Select an object in the Blender scene from its name

Parameters:

• name (str) – name of object to select

• select (bool) – whether to select it or not (aka deselect)

render_molecules.blender_utils.get_object_by_name(name: str) → object

Get an object in the Blender scene from its name

Parameters:

name (str) – name of object to obtain

Returns:

object in Blender scene with the name name

Return type:

object

render_molecules.blender_utils.create_cylinder(location: ndarray, angle: float, thickness: float, length: float, resolution: str = 'medium', name: str = 'Cylinder') → object

Create a cylinder in the Blender scene.

Parameters:

• location (np.ndarray) – midpoint position of cylinder

• angle (float) – angle with z-axis in radians

• thickness (float) – radius of created cylinder

• length (float) – length of created cylinder

• resolution (str) – desired object resolution. One of ['verylow', 'low', 'medium', 'high', 'veryhigh'].

• name (str) – name of created cylinder

Returns:

Blender object

Return type:

obj (object)

render_molecules.blender_utils.join_two_cylinders(cylinder1, cylinder2, center_position, select_within)

render_molecules.blender_utils.join_cylinders(cylinders: list[object], atom_position: ndarray, vdw_radius: float)

render_molecules.blender_utils.put_cap_on_cylinder(cylinder)

render_molecules.blender_utils.scale_vertices(*args, resolution='medium') → int | tuple[int]

Scale number of vertices according to resolution

Parameters:

• *args – number of vertices. Can also be multiple arguments.

• resolution (str) – desired object resolution. One of ['verylow', 'low', 'medium', 'high', 'veryhigh'].

Returns:

scaled number of vertices. The same number of return values as the number of *args.

Return type:

int | tuple

render_molecules.blender_utils.deselect_all_selected() → None

Deselect all selected objects

render_molecules.blender_utils.orbit_camera(radius: int | None = None, height: int | None = None, set_active: bool = True, nframes: int = 20)

render_molecules.blender_utils.set_frame_step(frame_step: int) → None

render_molecules.blender_utils.set_frame_end(frame_end: int) → None

Other utilities

render_molecules.other_utils.hex2rgbtuple(hexcode: str) → tuple[float, float, float]

Convert 6-digit color hexcode to a tuple of floats

render_molecules.other_utils.color_srgb_to_scene_linear(c: float) → float

Convert RGB to sRGB

render_molecules.other_utils.find_first_string_in_list_of_strings(string_to_find: str | list[str], list_of_strings: list[str], start: int = 0, end: int | None = None) → int | None

Finds the first instance of a string in a list of strings.

render_molecules.other_utils.find_all_string_in_list_of_strings(string_to_find: str | list[str], list_of_strings: list[str], start: int = 0, end: int | None = None) → list[int]

Finds all instances of a string stringToFind in a list of strings.

render_molecules.other_utils.get_render_molecules_dir() → str

Get the directory that contains all render_molecules python files.

Returns:

render_molecules directory

Return type:

str

Notes

• Follows symlinks

Elemental data

render_molecules.element_data.get_element_from_atomic_number(atomic_number: int) → str

render_molecules.element_data.get_atomic_number_from_element(element: str) → int

Constants

render_molecules.constants.BOHR_TO_ANGSTROM = 0.5291177249

Angstrom per Bohr

render_molecules.constants.ANGSTROM_TO_BOHR = 1.8899385768809651

Bohr per Angstrom

render_molecules.constants.BOHR_TO_METERS = 5.2917721067121e-11

Meter per Bohr

render_molecules.constants.METERS_TO_BOHR = 18897261254.535072

Bohr per Meter

render_molecules.constants.ANGSTROM_TO_METERS = 1e-10

Meter per Angstrom

render_molecules.constants.METERS_TO_ANGSTROM = 10000000000.0

Angstrom per Meter

render_molecules.constants.AMU_TO_KG = 1.66053907e-27

kg per amu

render_molecules.constants.KG_TO_AMU = 6.0221407497506215e+26

amu per kg

render_molecules.constants.KGM2_TO_AMU_ANGSTROM2 = 6.022140749750622e+46

amu angstrom2 per kg m2

render_molecules.constants.HYDROGEN_BOND_LENGTH = 3.5

Maximum hydrogen bond length

render_molecules.constants.HYDROGEN_BOND_ANGLE = 35.0

Maximum hydrogen bond angle

render_molecules.constants.SPHERE_SCALE = 0.3

Fraction of Van der Waals radius for created spheres

render_molecules.constants.CYLINDER_LENGTH_FRACTION_SPLIT = 0.25

Cylinder length fraction for a bond split between two materials

render_molecules.constants.CYLINDER_LENGTH_FRACTION = 0.5

Cylinder length fraction for a bond