tools

Functions and attributes

atomman.tools.aslist(term: Any) list

Create list representation of term. Treats a str 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

atomman.tools.atomic_mass(atomic_info: int | str, mass_number: int | None = None, prompt: bool = False) float

Returns either the median standard atomic weight for an element or the relative atomic mass for an isotope.

Parameters:
  • atomic_info (str or int) – The atomic symbol or number identifying the element/isotopes.

  • mass_number (int, optional) – An isotope mass number.

  • prompt (bool, optional) – If True, then a screen prompt will appear for radioactive elements with no standard mass to ask for the isotope to use. If False (default), then the most stable isotope will be automatically used.

Returns:

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

Return type:

float

Raises:

ValueError – For invalid input values or combinations of values.

atomman.tools.atomic_number(atomic_symbol: str) int

Return the corresponding atomic number for a given atomic symbol.

Parameters:

atomic_symbol (str) – An atomic symbol.

Returns:

The corresponding atomic number.

Return type:

int

atomman.tools.atomic_symbol(atomic_number: int) str

Return the corresponding atomic symbol for a given atomic number.

Parameters:

atomic_number (int) – An atomic number.

Returns:

The corresponding atomic symbol.

Return type:

str

Raises:

IndexError – If no matches for the atomic number are found.

atomman.tools.axes_check(axes: _SupportsArray[dtype[Any]] | _NestedSequence[_SupportsArray[dtype[Any]]] | bool | int | float | complex | str | bytes | _NestedSequence[bool | int | float | complex | str | bytes], tol: float = 1e-08) ndarray

Checks that given axes are orthogonal and right-handed.

Parameters:
  • axes (array-like object) – 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:

numpy.ndarray

Raises:

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

atomman.tools.boolean(value: str | bool) bool

Allows conversion of strings to Booleans.

Parameters:

value (str or bool) – If str, then ‘true’ and ‘t’ become True and ‘false’ and ‘f’ become false. If bool, simply return the value.

Returns:

Equivalent bool of value.

Return type:

bool

Raises:

ValueError – If value is unrecognized.

atomman.tools.compositionstr(symbols: list, counts: list) str

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(dataframe='__no__default__', dcols='__no__default__', fcols='__no__default__')

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: str | IOBase, variable: dict, s_delimiter: str, e_delimiter: str) str

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: Any) Generator[Any, None, None]

Iterate over items in term as if term was a list. Treats a str 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: float = 1e-05, atol: float = 1e-08) str | None

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: Tuple[int]) Generator[Tuple[Tuple[int], str], None, None]

Iterates through all unique indices 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: float = 1e-05, atol: float = 1e-08) bool

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: float = 1e-05, atol: float = 1e-08) bool

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: float = 1e-05, atol: float = 1e-08) bool

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: float = 1e-05, atol: float = 1e-08) bool

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: float = 1e-05, atol: float = 1e-08) bool

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: float = 1e-05, atol: float = 1e-08) bool

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: float = 1e-05, atol: float = 1e-08) bool

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

atomman.tools.screen_input(prompt: str = '') str

Replacement input function that is compatible with the mingw terminal.

Parameters:

prompt (str, optional) – The screen prompt to use for asking for the input.

Returns:

The user input.

Return type:

str

atomman.tools.uber_open_rmode(data: str | bytes | Path | IOBase) IOBase

Provides a uniform means of reading data from files, file-like objects, and string/bytes content.

Parameters:

data (file-like object, file path, or str/bytes file content) – The data that will be opened for reading.

Returns:

An open file-like object that is in a bytes read mode. If a file-like object is given, it is passed through after checking that it is for bytes content. If a file path is given, the file is opened in ‘rb’ mode. If bytes or string content is given, the content is returned in a BytesIO object.

Return type:

file-like object

Raises:
  • ValueError – If a file-like object in text mode is given.

  • TypeError – If data is not a file-like object, bytes, str or Path.

  • FileNotFoundError – If data is a pathlib.Path object and is not an existing file.

atomman.tools.vect_angle(vect1: _SupportsArray[dtype[Any]] | _NestedSequence[_SupportsArray[dtype[Any]]] | bool | int | float | complex | str | bytes | _NestedSequence[bool | int | float | complex | str | bytes], vect2: _SupportsArray[dtype[Any]] | _NestedSequence[_SupportsArray[dtype[Any]]] | bool | int | float | complex | str | bytes | _NestedSequence[bool | int | float | complex | str | bytes], unit: str = 'degree') float | ndarray

Returns the angle(s) between two sets of vectors.

Parameters:
  • vect1 (array-like object) – First vector or set of vectors.

  • vect2 (array-like object) – Second vector or set of vectors.

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

Returns:

The angle(s) between vect1 and vect2.

Return type:

float or numpy.NDArray

atomman.tools.miller.all_indices(maxindex: int = 10, reduce: bool = False) ndarray

Generates an array containing all Miller indices where each individual index value is an integer independently ranging from -maxindex to maxindex.

Parameters:
  • maxindex (int, optional) – The maximum absolute index to use: u,v,w (or h,k,l) can all independently vary from -maxindex to maxindex. Default value is 10.

  • reduce (bool, optional) – Setting this to True will return only the indices sets that are unique after reducing to their smallest integer values. Default value of False will return all indices even those that are multiples of others.

Returns:

indices – All integer Miller [uvw] or (hkl) indices within the maxindex range.

Return type:

numpy.NDArray

atomman.tools.miller.fromstring(value)

Reads Miller and Miller-Bravais vector/plane strings and returns a corresponding numpy array. Values should be space-delimited and surrounded by angle brackets. The values in the brackets should be integers. Fractional arrays can be defined by placing a fraction before the array.

Examples: [1 0 0] 1/2 [1 1 0] [0 0 0 1] 1/3 [1 1 -2 0]

Parameters:

value (str) – The Miller(-Bravais) vector/plane string to interpret.

Returns:

The vector/plane as an array of floats.

Return type:

numpy.NDArray

atomman.tools.miller.plane3to4(indices: _SupportsArray[dtype[Any]] | _NestedSequence[_SupportsArray[dtype[Any]]] | bool | int | float | complex | str | bytes | _NestedSequence[bool | int | float | complex | str | bytes]) ndarray

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

Parameters:

indices (array-like object) – (…, 3) array of Miller crystallographic indices.

Returns:

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

Return type:

numpy.ndarray

Raises:

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

atomman.tools.miller.plane4to3(indices: _SupportsArray[dtype[Any]] | _NestedSequence[_SupportsArray[dtype[Any]]] | bool | int | float | complex | str | bytes | _NestedSequence[bool | int | float | complex | str | bytes]) ndarray

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

Parameters:

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

Returns:

(…, 3) array of Miller crystallographic indices.

Return type:

numpy.ndarray

Raises:

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

atomman.tools.miller.plane_crystal_to_cartesian(indices: _SupportsArray[dtype[Any]] | _NestedSequence[_SupportsArray[dtype[Any]]] | bool | int | float | complex | str | bytes | _NestedSequence[bool | int | float | complex | str | bytes], box) ndarray

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 (array-like object) – (…, 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:

numpy.ndarray

Raises:

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

atomman.tools.miller.reduce_indices(indices: _SupportsArray[dtype[Any]] | _NestedSequence[_SupportsArray[dtype[Any]]] | bool | int | float | complex | str | bytes | _NestedSequence[bool | int | float | complex | str | bytes]) array

Given an array of one or more Miller(-Bravais) indices reduce them to the smallest integer representation.

Parameters:

indices (Array-like object) – An array of ints with shapes (…,3) or (…,4) that represent one or more Miller(-Bravais) crystal vectors.

Returns:

The reduced indices

Return type:

numpy.ndarray

atomman.tools.miller.vector3to4(indices: _SupportsArray[dtype[Any]] | _NestedSequence[_SupportsArray[dtype[Any]]] | bool | int | float | complex | str | bytes | _NestedSequence[bool | int | float | complex | str | bytes]) ndarray

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

Parameters:

indices (array-like object) – (…, 3) array of Miller crystallographic indices.

Returns:

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

Return type:

numpy.ndarray

Raises:

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

atomman.tools.miller.vector4to3(indices: _SupportsArray[dtype[Any]] | _NestedSequence[_SupportsArray[dtype[Any]]] | bool | int | float | complex | str | bytes | _NestedSequence[bool | int | float | complex | str | bytes]) ndarray

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

Parameters:

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

Returns:

(…, 3) array of Miller crystallographic indices.

Return type:

numpy.ndarray

Raises:

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

atomman.tools.miller.vector_conventional_to_primitive(indices: _SupportsArray[dtype[Any]] | _NestedSequence[_SupportsArray[dtype[Any]]] | bool | int | float | complex | str | bytes | _NestedSequence[bool | int | float | complex | str | bytes], setting: str = 'p') ndarray

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

Parameters:
  • indices (array-like object) – (…, 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, ‘f’ for face-centered, and ‘t1’ or ‘t2’ for trigonal systems.

Returns:

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

Return type:

numpy.ndarray

Raises:

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

atomman.tools.miller.vector_crystal_to_cartesian(indices: _SupportsArray[dtype[Any]] | _NestedSequence[_SupportsArray[dtype[Any]]] | bool | int | float | complex | str | bytes | _NestedSequence[bool | int | float | complex | str | bytes], box) ndarray

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

Parameters:
  • indices (array-like object) – (…, 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:

numpy.ndarray

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: _SupportsArray[dtype[Any]] | _NestedSequence[_SupportsArray[dtype[Any]]] | bool | int | float | complex | str | bytes | _NestedSequence[bool | int | float | complex | str | bytes], setting: str = 'p') ndarray

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

Parameters:
  • indices (array-like object) – (…, 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, ‘f’ for face-centered, and ‘t’ for trigonal systems.

Returns:

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

Return type:

numpy.ndarray

Raises:

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