API Reference

Core functions

molecular_builder.core.carve_geometry(atoms, geometry, side='in', return_carved=False)

Delete atoms according to geometry.

Arguments:

atoms – The ase Atoms object containing the molecular system geometry – A molecular_builder.geometry.Geometry object defining the region to be carved side – Whether to carve out the inside or the outside of geometry

Returns:

Number of deleted atoms Optionally an atoms object containing the atoms that were carved away

molecular_builder.core.create_bulk_crystal(name, size, round='up')

Create a bulk crystal from a spacegroup description.

Parameters

  • name (str) – name of the crystal. A list can be found by @TODO

  • size (array_like with 3 elements) – size of the bulk crystal. In the case of a triclinic cell, the dimensions are the ones along the diagonal of the cell matrix, and the crystal tilt decides the rest.

Returns

ase.Atoms object containing the crystal

Return type

ase.Atoms

molecular_builder.core.fetch_prepared_system(name, type_mapping=None)

Retrieves molecular system from a particular zenodo repository. Caches data locally with requests-cache, which creates a sqlite database locally.

Parameters

  • name (string) – name of system to be retrieved

  • type_mapping (List of pair-like of integers.) – List of pairs of numbers mapping the atom type in the file from the online repository to an atom number. For example silica from an online repository of lammps data files will have Si and O as type 1 and 2, whereas the correct atomic numbers are 14 and 8

Returns :returns: ase.Atoms object with the system

molecular_builder.core.fetch_system_from_url(url, type_mapping=None)

Retrieves molecular system from an online location. Caches data locally with requests-cache, which creates a sqlite database locally.

Parameters

  • name (string) – name of system to be retrieved

  • type_mapping (List of pair-like of integers.) – List of pairs of numbers mapping the atom type in the file from the online repository to an atom number. For example silica from an online repository of lammps data files will have Si and O as type 1 and 2, whereas the correct atomic numbers are 14 and 8

Returns :returns: ase.Atoms object with the system

molecular_builder.core.pack_water(atoms=None, nummol=None, volume=None, density=0.997, geometry=None, side='in', pbc=0.0, tolerance=2.0)

Pack water molecules into voids at a given volume defined by a geometry. The packing is performed by packmol.

Parameters

  • atoms (Atoms object) – ase Atoms object that specifies particles that water is to be packed around. The packed water molecules will be added to this atoms object.

  • nummol (int) – Number of water molecules

  • volume (float) – Void volume in \(Å^3\) to be filled with water. Can only be used if nummol=None, since pack_water will compute the number of atoms based on the volume and density of water.

  • density (float) – Water density. Used to compute the number of water molecules to be packed if volume is provided.

  • geometry (Geometry object) – Geometry object specifying where to pack water

  • side (str) – Pack water inside/outside of geometry

  • pbc (float or array_like) – Inner margin to add to the simulation box to avoid overlapping atoms over periodic boundary conditions. This is necessary because packmol doesn’t support periodic boundary conditions.

  • tolerance (float) – Minimum separation distance between molecules.

Returns

Coordinates of the packed water

molecular_builder.core.read_data(filename, type_mapping=None, style='atomic')

Read a lammps data file into an ase atoms object.

Parameters

  • filename (string) – path to the lammps data file

  • type_mapping (List of pair-like of integers.) – List of pairs of numbers mapping the atom type in the file from the online repository to an atom number. For example silica from an online repository of lammps data files will have Si and O as type 1 and 2, whereas the correct atomic numbers are 14 and 8

Returns

ase.Atoms object with the system

molecular_builder.core.write(atoms, filename, bond_specs=None, atom_style='molecular', size=(640, 480), camera_dir=(2, 1, - 1), viewport_type='perspective', atom_radii=None)

Write atoms to lammps data file

Parameters

  • atoms (ase.Atoms) – The atoms object to write to file

  • filename (str) – filename to write to. Can either have suffix .data or .png, in which case a Lammps data file or a png picture will be produced, respectively.

  • bonds_spec (List of tuples) – List of (element1, element2, cutoff)

Geometry

The following geometries are available:

class molecular_builder.geometry.BerkovichGeometry(tip, axis=[0, 0, - 1], angle=1.1391764027766988)
packmol_structure(number, side)

Make structure to be used in PACKMOL input script

class molecular_builder.geometry.BlockGeometry(center, length, orientation=[], **kwargs)

This is a more flexible box geometry, where the angle

Parameters

  • center (array_like) – the center point of the block

  • length (array_like) – the spatial extent of the block in each direction.

  • orientation (nested list / ndarray_like) – orientation of block

NB: Does not support pack_water and packmol NB: This geometry will be deprecated

packmol_structure(number, side)

Make structure to be used in PACKMOL input script

class molecular_builder.geometry.BoxGeometry(center=None, length=None, lo_corner=None, hi_corner=None, **kwargs)

Box geometry.

Parameters

  • center (array_like) – geometric center of box

  • length (array_like) – length of box in all directions

  • lo_corner (array_like) – lower corner

  • hi_corner (array_like) – higher corner

class molecular_builder.geometry.CubeGeometry(center, length, **kwargs)

Cubic geometry.

Parameters

  • center (array_like) – center of cube

  • length (float) – length of each side

class molecular_builder.geometry.CylinderGeometry(center, radius, length, orientation=None, **kwargs)

Cylinder object.

Parameters

  • center (array_like) – the center point of the cylinder

  • radius (float) – cylinder radius

  • length (float) – cylinder length

  • orientation (array_like) – orientation of cylinder, given as a vector pointing along the cylinder. Pointing in x-direction by default.

class molecular_builder.geometry.DodecahedronGeometry(d, center=[0, 0, 0])

A convex rectangular dodecahedron geometry to be used for silicon carbide (SiC).

Parameters

  • d (float) – (shortest) length from dodecahedron center to sides

  • center (array_like) – center of dodecahedron

class molecular_builder.geometry.EllipsoidGeometry(center, length_axes, d, **kwargs)

Ellipsoid geometry, satisfies the equation

(x - x0)^2 (y - y0)^2 (z - z0)^2 ———- + ———- + ———- = d

a^2 b^2 c^2

Parameters

  • center (array_like) – center of ellipsoid (x0, y0, z0)

  • length_axes (array_like) – length of each axis (a, b, c)

  • d (float) – scaling

class molecular_builder.geometry.EllipticalCylinderGeometry(center, a, b, length, orientation=None, **kwargs)

Elliptical Cylinder

Parameters

  • center (array_like) – center of elliptical cylinder

  • a (float) – axes along x-axis

  • b (float) – axes along y-axis

  • length (float) – length of cylinder

  • orientation (ndarray) – which way the cylinder should point

NB: This geometry is not supported by packmol or pack_water

packmol_structure(number, side)

Make structure to be used in PACKMOL input script

class molecular_builder.geometry.Geometry(periodic_boundary_condition=(False, False, False), minimum_image_convention=True)

Base class for geometries.

Parameters

  • periodic_boundary_condition (array_like) – self-explanatory

  • minimum_image_convention (bool) – use the minimum image convention for bookkeeping how the particles interact

static cell2planes(cell, pbc)

Get the parameterization of the sizes of a ase.Atom cell

Parameters

  • cell (obj) – ase.Atom cell

  • pbc (float) – shift of boundaries to be used with periodic boundary condition

Returns

parameterization of cell plane sides

Return type

list of ndarray

3 planes intersect the origin by ase design.

static distance_point_line(vec, point_line, point_ext)

Returns the (shortest) distance between a line parallel to a normal vector ‘vec’ through point ‘point_line’ and an external point ‘point_ext’.

Parameters

  • vec (ndarray) – unit vector parallel to line

  • point_line (ndarray) – point on line

  • point_ext (ndarray) – external points

Returns

distance between line and external point(s)

Return type

ndarray

static distance_point_plane(vec, point_plane, point_ext)

Returns the (shortest) distance between a plane with normal vector ‘vec’ through point ‘point_plane’ and a point ‘point_ext’.

Parameters

  • vec (ndarray) – normal vector of plane

  • point_plane (ndarray) – point on line

  • point_ext (ndarray) – external point(s)

Returns

distance between plane and external point(s)

Return type

ndarray

static extract_box_properties(center, length, lo_corner, hi_corner)

Given two of the properties ‘center’, ‘length’, ‘lo_corner’, ‘hi_corner’, return all the properties. The properties that are not given are expected to be ‘None’.

packmol_structure(number, side)

Make structure to be used in PACKMOL input script

Parameters

  • number (int) – number of water molecules

  • side (str) – pack water inside/outside of geometry

Returns

string with information about the structure

Return type

str

static vec_and_point_to_plane(vec, point)

Returns the (unique) plane, given a normal vector ‘vec’ and a point ‘point’ in the plane. ax + by + cz - d = 0

Parameters

  • vec (ndarray) – normal vector of plane

  • point (ndarray) – point in plane

Returns

parameterization of plane

Return type

ndarray

class molecular_builder.geometry.NotchGeometry(entry, vector_in, vector_up)

Carve out a notch geometry in a structure

Parameters

  • entry (array_like) – The starting poing of the crack

  • vector_in (array_like) – The length of the crack

  • vector_up (array_like) – The thickness of the crack above and below the starting point

class molecular_builder.geometry.OctahedronGeometry(d, center=[0, 0, 0])

A rectangular octahedron geometry to be used for silicon carbide (SiC) All sides are assumed to have a normal vector pointing where are components have the same magnitude (ex. (1, 1, 1))

Parameters

  • d (float) – (shortest) length from octahedron center to sides

  • center (array_like) – center of octahedron

class molecular_builder.geometry.PlaneBoundTriclinicGeometry(cell, pbc=0.0)

Triclinic crystal geometry based on ase.Atom cell

Parameters

  • cell (obj) – ase.Atom cell

  • pbc (float) – shift of boundaries to be used with periodic boundary condition

packmol_structure(number, side)

Make structure to be used in PACKMOL input script

class molecular_builder.geometry.PlaneGeometry(point, normal, **kwargs)

Remove all particles on one side of one or more planes. Can be used to form any 3d polygon, among other geometries

Parameters

  • point (array_like) – point on plane

  • normal (array_like) – vector normal to plane

packmol_structure(number, side)

Make structure to be used in PACKMOL input script

class molecular_builder.geometry.ProceduralSurfaceGeometry(point, normal, thickness, scale=1, method='perlin', f=<function ProceduralSurfaceGeometry.<lambda>>, threshold=None, repeat=False, angle=90, seed=45617, **kwargs)

Creates procedural noise on a surface defined by a point, a normal vector and a thickness.

Parameters

  • point (array_like) – an equilibrium point of noisy surface

  • normal (array_like) – normal vector of noisy surface, surface is carved out in the poiting direction

  • thickness (float) – thickness of noise area

  • scale (int) – scale of noise structures

  • method (str) – noise method, either ‘simplex’ or ‘perlin’

  • f (func) – arbitrary R^2 => R function to be added to the noise

  • threshold (float) – define a threshold to define two-level surface by noise

  • repeat (array_like or bool or float) – define at what lengths the noise should repeat, default is surface length (if repeat=True)

  • angle (float) – angle of triclinic surface given in degrees

  • seed (int) – seed used in procedural noise

packmol_structure(number, side)

Make structure to be used in PACKMOL input script

class molecular_builder.geometry.ProceduralSurfaceGridGeometry(normal, scale=10, threshold=0, seed=1, grid=(50, 100), period=4096, **kwargs)

Creates tileable procedural noise on a surface defined by a grid and a normal vector. Noise is applied throughout the direction of the normal.

Parameters

  • normal (array_like) – normal vector of noisy surface, surface is carved out in the poiting direction

  • scale (float) – scale of noise structures

  • grid (array_like) – Number of grid cells in each direction perpendicular to the normal vector.

  • threshold (float) – Threshold for Simplex values to create a two-level surface.

  • seed (int) – Seed for procedural noise.

  • period (int) – Period for randomization of Simplex permutation matrix.

Returns

ndarray of bools stating which atoms to remove.

Return type

ndarray

packmol_structure(number, side)

Make structure to be used in PACKMOL input script

class molecular_builder.geometry.SphereGeometry(center, radius, **kwargs)

Spherical geometry.

Parameters

  • center (array_like) – Center of sphere

  • radius – radius of sphere

Indices and tables