tools

Functions and attributes

atomman.tools.aslist(term)

Create list representation of term. Treats a str, unicode term as a single item.

Parameters

term (any) – Term to convert into a list, if needed.

Returns

All items in term as a list

Return type

list of any

atomman.tools.atomic_mass(term)

Get the atomic mass of an element or isotope. Isotopes are specified using symbols followed by -#, where # is the mass number (eg. ‘He-3’). Deuterium and tritium can alternatively be specified using D and T respectively. Values obtained from NIST reference database: http://www.nist.gov/pml/data/comp.cfm

Parameters

term (str or int) – The atomic number or atomic/isotope symbol to retrieve the mass for.

Returns

The average standard atomic weight of an element or the relative atomic mass of an isotope.

Return type

float

atomman.tools.atomic_number(symbol)

Return the corresponding atomic number for a given atomic symbol.

Parameters

symbol (str) – An atomic symbol.

Returns

The corresponding atomic number.

Return type

int

atomman.tools.atomic_symbol(number)

Return the corresponding atomic symbol for a given atomic number.

Parameters

number (int) – An atomic number.

Returns

The corresponding atomic symbol.

Return type

int

atomman.tools.axes_check(axes, tol=1e-08)

Checks that given axes are orthogonal and right-handed.

Parameters
  • axes (list of list or np.ndarray) – A 3x3 array of axes vectors.

  • tol (float, optional) – Tolerance to use in checking if axes are orthogonal and right-handed. Default value is 1e-8.

Returns

A 3x3 array of the corresponding unit vectors of axes.

Return type

np.ndarray

Raises

ValueError – If axes are not orthogonal or right-handed.

atomman.tools.compositionstr(symbols, counts)

Generates a reduced composition string based on symbols and counts.

Parameters
  • symbols (list) – The model symbol for a site.

  • count (list) – How many sites are occupied by each symbol.

Returns

The reduced composition string.

Return type

str

atomman.tools.duplicates_allclose

Determine duplicates in dataframe based on tolerances. The implementation first uses pandas.DataFrame.duplicated on the dcols argument with keep=False to keep all duplicates. The duplicate sub-dataframe is then sorted on both dcols and fcols. A diff between each row is then done on the sorted duplicates dataframe. The float values are then checked for their tolerances.

Note: False duplicates may be identified if tolerance ranges overlap. Consider dataframe with rows 1,2,3. If row 2 matches row 1 within the tolerances, and row 3 matches row 2 within the tolerances, both rows 2 and 3 will be labeled as tolerances even if row 3 does not match row 1 within the tolerances.

Parameters
  • dataframe (pandas.DataFrame) – The dataframe to search for duplicates

  • dcols (list) – The column names that are tested for exact duplicates.

  • fcols (dict) – The column names (keys) that are tested using absolute tolerances (values).

Returns

False for first occurrence of checked values, True for subsequent duplicates.

Return type

list of bool of length nrows

atomman.tools.filltemplate(template, variable, s_delimiter, e_delimiter)

Takes a template and fills in values for delimited template variables.

Parameters
  • template (string or file-like object) – The template file or file content to fill in.

  • variable (dict) – Dictionary with keys defining the delimited template variable terms, and values the values to replace the variable terms with.

  • s_delimiter (str) – The leading delimiter for identifying the template variable terms.

  • e_delimiter (str) – The trailing delimiter for identifying the template variable terms.

Returns

The template with all delimited variable terms replaced with their corresponding defined values from variable.

Return type

str

Raises
  • KeyError – If delimited term found in template that has no value in variable.

  • ValueError – If parsing of s_delimiter, e_delimiter pairs fails.

atomman.tools.iaslist(term)

Iterate over items in term as if term was a list. Treats a str, unicode term as a single item.

Parameters

term (any) – Term to iterate over.

Yields

any – Items in the list representation of term.

atomman.tools.identifyfamily(box, rtol=1e-05, atol=1e-08)

Tests if a box is consistent with a standard representation of a crystal system cell.

Parameters
  • box (atomman.Box) – The box object to test.

  • rtol (float, optional) – Relative tolerance for testing box parameters. Default value is 1e-5.

  • atol (float, optional) – Absolute tolerance for testing box parameters. Default value is 1e-8.

Returns

‘cubic’, ‘hexagonal’, ‘tetragonal’, ‘rhombohedral’, ‘orthorhombic’, ‘monoclinic’ or ‘triclinic’ if it matches any. None if no matches.

Return type

str or None

Raises

ValueError – If box is not consistent with a standard cell.

atomman.tools.indexstr(shape)

Iterates through all unique indicies of an array with a given shape.

Parameters

shape (tuple of int) – The array shape to iterate through.

Yields
  • index (tuple of int) – A unique index set of the array.

  • istr (str) – A string representation of index with numbers in [].

atomman.tools.iscubic(box, rtol=1e-05, atol=1e-08)

Tests if a box is consistent with a standard cubic cell: a = b = c alpha = beta = gamma = 90

Parameters
  • box (atomman.Box) – The box object to test.

  • rtol (float, optional) – Relative tolerance for testing box parameters. Default value is 1e-5.

  • atol (float, optional) – Absolute tolerance for testing box parameters. Default value is 1e-8.

Returns

True if box is a standard cubic cell, False otherwise.

Return type

bool

atomman.tools.ishexagonal(box, rtol=1e-05, atol=1e-08)

Tests if a box is consistent with a standard hexagonal cell: a = b != c alpha = beta = 90 gamma = 120

Parameters
  • box (atomman.Box) – The box object to test.

  • rtol (float, optional) – Relative tolerance for testing box parameters. Default value is 1e-5.

  • atol (float, optional) – Absolute tolerance for testing box parameters. Default value is 1e-8.

Returns

True if box is a standard hexagonal cell, False otherwise.

Return type

bool

atomman.tools.ismonoclinic(box, rtol=1e-05, atol=1e-08)

Tests if a box is consistent with a standard monoclinic cell: a != b != c alpha = gamma = 90 beta != 90

Parameters
  • box (atomman.Box) – The box object to test.

  • rtol (float, optional) – Relative tolerance for testing box parameters. Default value is 1e-5.

  • atol (float, optional) – Absolute tolerance for testing box parameters. Default value is 1e-8.

Returns

True if box is a standard monoclinic cell, False otherwise.

Return type

bool

atomman.tools.isorthorhombic(box, rtol=1e-05, atol=1e-08)

Tests if a box is consistent with a standard orthorhombic cell: a != b != c alpha = beta = gamma = 90

Parameters
  • box (atomman.Box) – The box object to test.

  • rtol (float, optional) – Relative tolerance for testing box parameters. Default value is 1e-5.

  • atol (float, optional) – Absolute tolerance for testing box parameters. Default value is 1e-8.

Returns

True if box is a standard orthorhombic cell, False otherwise.

Return type

bool

atomman.tools.isrhombohedral(box, rtol=1e-05, atol=1e-08)

Tests if a box is consistent with a standard rhombohedral cell: a = b = c alpha = beta = gamma != 90

Parameters
  • box (atomman.Box) – The box object to test.

  • rtol (float, optional) – Relative tolerance for testing box parameters. Default value is 1e-5.

  • atol (float, optional) – Absolute tolerance for testing box parameters. Default value is 1e-8.

Returns

True if box is a standard rhombohedral cell, False otherwise.

Return type

bool

atomman.tools.istetragonal(box, rtol=1e-05, atol=1e-08)

Tests if a box is consistent with a standard tetragonal cell: a = b != c alpha = beta = gamma = 90

Parameters
  • box (atomman.Box) – The box object to test.

  • rtol (float, optional) – Relative tolerance for testing box parameters. Default value is 1e-5.

  • atol (float, optional) – Absolute tolerance for testing box parameters. Default value is 1e-8.

Returns

True if box is a standard tetragonal cell, False otherwise.

Return type

bool

atomman.tools.istriclinic(box, rtol=1e-05, atol=1e-08)

Tests if a box is consistent with a standard triclinic cell: a != b != c alpha != 90 beta != 90 gamma != 90

Parameters
  • box (atomman.Box) – The box object to test.

  • rtol (float, optional) – Relative tolerance for testing box parameters. Default value is 1e-5.

  • atol (float, optional) – Absolute tolerance for testing box parameters. Default value is 1e-8.

Returns

True if box is a standard triclinic cell, False otherwise.

Return type

bool

class atomman.tools.uber_open_rmode(data)

Bases: object

Context manager for reading data from file-like objects, file names, and data strings in the same manner.

atomman.tools.vect_angle(vect1, vect2, unit='degree')

Returns the angle between two vectors.

Parameters
  • vect1 (list or numpy.ndarray) – First vector.

  • vect2 (list or numpy.ndarray) – Second vector.

  • unit (str) – Specifies unit of returned angle: ‘degree’ or ‘radian’. Default value is ‘degree’.

Returns

The angle between vect1 and vect2.

Return type

float

atomman.tools.miller.plane3to4(indices)

Converts 3-term Miller (hkl) plane indices to 4-term hexagonal (hkil) Miller-Bravias indices.

Parameters

indices (np.ndarray) – (…, 3) array of Miller crystallographic indices.

Returns

(…, 4) array of Miller-Bravais crystallographic indices.

Return type

np.ndarray

Raises

ValueError – If indices dimensions are not (…, 3).

atomman.tools.miller.plane4to3(indices)

Converts 4-term hexagonal Miller-Bravias (hkil) plane indices to 3-term Miller (hkl) indices.

Parameters

indices (np.ndarray of int) – (…, 4) array of Miller-Bravais crystallographic indices.

Returns

(…, 3) array of Miller crystallographic indices.

Return type

np.ndarray of int

Raises

ValueError – If indices dimensions are not (…, 4), or if h+k+i != 0.

atomman.tools.miller.vector3to4(indices)

Converts 3-term Miller [uvw] vector indices to 4-term hexagonal [uvtw] Miller-Bravias indices.

Parameters

indices (np.ndarray) – (…, 3) array of Miller crystallographic indices.

Returns

(…, 4) array of Miller-Bravais crystallographic indices.

Return type

np.ndarray

Raises

ValueError – If indices dimensions are not (…, 3).

atomman.tools.miller.vector4to3(indices)

Converts 4-term hexagonal Miller-Bravias [uvtw] vector indices to 3-term Miller [uvw] indices.

Parameters

indices (np.ndarray of int) – (…, 4) array of Miller-Bravais crystallographic indices.

Returns

(…, 3) array of Miller crystallographic indices.

Return type

np.ndarray of int

Raises

ValueError – If indices dimensions are not (…, 4), or if u+v+t != 0.

atomman.tools.miller.plane_crystal_to_cartesian(indices, box)

Converts crystal planar indices to Cartesian plane normal vectors relative to a given lattice box. Note: the algorithm used requires that the planar indices be integers.

Parameters
  • indices (np.ndarray) – (3,) array of [hkl] Miller crystallographic indices or (4,) array of [hkil] Miller-Bravais crystallographic indices.

  • box (atomman.Box) – Box that defines the lattice cell vectors to use.

Returns

(…, 3) array of Cartesian vectors corresponding to plane normals.

Return type

np.ndarray of float

Raises

ValueError – If indices dimensions are not (…, 3) or (…, 4), or if hexagonal indices given with non-hexagonal box.

atomman.tools.miller.vector_crystal_to_cartesian(indices, box)

Converts crystal indices to Cartesian vectors relative to a given lattice box.

Parameters
  • indices (np.ndarray) – (…, 3) array of [uvw] Miller crystallographic indices or (…, 4) array of [uvtw] Miller-Bravais crystallographic indices.

  • box (atomman.Box) – Box that defines the lattice cell vectors to use.

Returns

(…, 3) array of Cartesian vectors.

Return type

np.ndarray of float

Raises

ValueError – If indices dimensions are not (…, 3) or (…, 4), or if hexagonal indices given with non-hexagonal box.

atomman.tools.miller.vector_primitive_to_conventional(indices, setting='p')

Converts crystal indices relative to a primitive cell to indices relative to a conventional cell in a specified setting.

Parameters
  • indices (np.ndarray) – (…, 3) array of [uvw] Miller crystallographic indices relative to the primitive cell

  • setting (str) – Specifies the conventional cell setting: ‘p’ for primitive, ‘a’, ‘b’, ‘c’ for side-centered, ‘i’ for body-centered, and ‘f’ for face-centered.

Returns

(…, 3) array of [uvw] Miller crystallographic indices relative to the conventional cell

Return type

np.ndarray of float

Raises

ValuenError – If indices dimensions are not (…, 3) or if an unknown setting value is given.

atomman.tools.miller.vector_conventional_to_primitive(indices, setting='p')

Converts crystal indices relative to a conventional cell in a specified setting to indices relative to a primitive cell.

Parameters
  • indices (np.ndarray) – (…, 3) array of [uvw] Miller crystallographic indices relative to the conventional cell

  • setting (str) – Specifies the conventional cell setting: ‘p’ for primitive, ‘a’, ‘b’, ‘c’ for side-centered, ‘i’ for body-centered, and ‘f’ for face-centered.

Returns

(…, 3) array of [uvw] Miller crystallographic indices relative to the primitive cell

Return type

np.ndarray of float

Raises

ValuenError – If indices dimensions are not (…, 3) or if an unknown setting value is given.