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:
- 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:
- 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.
- 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:
- 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:
- Raises:
ValueError – If value is unrecognized.
- atomman.tools.compositionstr(symbols: list, counts: list) str
Generates a reduced composition string based on symbols and counts.
- 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:
- Returns:
False for first occurrence of checked values, True for subsequent duplicates.
- Return type:
- 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:
- 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.
- 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:
- 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:
- 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:
- 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:
- 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:
- 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:
- 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:
- atomman.tools.screen_input(prompt: str = '') str
Replacement input function that is compatible with the mingw terminal.
- 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
Returns the angle between two vectors.
- 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.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.