`aim2dat.strct`¶

Modules to analyze the chemical environment and the coordination of atoms.

Subpackages¶

Submodules¶

aim2dat.strct.strct_io

Package Contents¶

Classes¶

`Structure`	Represents a structure and contains methods to calculate properties of a structure
`StructureCollection`	The StructureCollection class is a container for one or multiple atomic structures. It
`StructureImporter`	Imports structures from online databases.
`SurfaceGeneration`	Generates a surfaces and surface slabs based on a bulk crystal structure.

class aim2dat.strct.Structure(elements: list[str], positions: list[list[float]], pbc: list[bool], is_cartesian: bool = True, wrap: bool = False, cell: list[list[float]] = None, kinds: list[str] = None, label: str = None, site_attributes: dict = None, store_calculated_properties: bool = True, attributes: dict = None, extras: dict = None, function_args: dict = None)[source]¶

Bases: aim2dat.strct.mixin.AnalysisMixin, aim2dat.strct.mixin.ManipulationMixin

Represents a structure and contains methods to calculate properties of a structure (molecule or crystal) or to manipulate a structure.

Overview

Properties¶
`analysis_methods`	class Return calculation methods.
`attributes`	Return attributes.
`cell`	Return the cell of the structure.
`cell_angles`	Cell angles.
`cell_lengths`	cell lengths.
`cell_volume`	cell volume.
`chem_formula`	Return chemical formula.
`elements`	Return the elements of the structure.
`export_methods`	class Return export methods.
`extras`	Return extras.
`function_args`	Return function arguments for stored extras.
`import_methods`	class Return import methods.
`kinds`	Kinds of the structure.
`label`	Return label of the structure (especially relevant in StructureCollection).
`manipulation_methods`	class Return manipulation methods.
`pbc`	Return the pbc of the structure.
`positions`	Return the cartesian positions of the structure.
`scaled_positions`	Return the scaled positions of the structure.
`site_attributes`	dict:
`store_calculated_properties`	Store calculated properties to reuse them later.

Methods¶
`calculate_angle`(site_index1, site_index2, site_index3, backfold_positions)	Calculate angle between three atoms.
`calculate_coordination`(r_max, method, min_dist_delta, n_nearest_neighbours, radius_type, atomic_radius_delta, econ_tolerance, econ_conv_threshold, voronoi_weight_type, voronoi_weight_threshold, okeeffe_weight_threshold)	Calculate coordination environment of each atomic site.
`calculate_dihedral_angle`(site_index1, site_index2, site_index3, site_index4, backfold_positions)	Calculate dihedral angle between four atoms.
`calculate_distance`(site_index1, site_index2, backfold_positions, use_supercell, r_max, return_pos)	Calculate distance between two atoms.
`calculate_ffingerprint`(r_max, delta_bin, sigma, use_legacy_smearing, distinguish_kinds)	Calculate f-fingerprint function for each element-pair and atomic site.
`calculate_voronoi_tessellation`(r_max)	Calculate voronoi polyhedron for each atomic site.
`copy`()	Return copy of Structure object.
`delete_atoms`(elements, site_indices, change_label)	Delete atoms by element, list of elements, site index or list of site indices.
`determine_point_group`(threshold_distance, threshold_angle, threshold_inertia)	Determine the point group of a molecule.
`determine_space_group`(symprec, angle_tolerance, hall_number, return_sym_operations, return_primitive_structure, return_standardized_structure, no_idealize)	Determine the space group of the structure using spglib as backend.
`from_aiida_structuredata`(structure_node, use_uuid, label)	class Append structure from AiiDA structure node.
`from_ase_atoms`(ase_atoms, attributes, label)	class Get structure from ase atoms object.
`from_file`(file_path, attributes, label, backend, file_format, backend_kwargs)	class Get structure from file using the ase read-function.
`from_pymatgen_structure`(pymatgen_structure, attributes, label)	class Get structure from pymatgen structure or molecule object.
`get`(key, value)	Get attribute by key and return default if not present.
`get_positions`(cartesian, wrap)	Return positions of atoms.
`iter_sites`(get_kind, get_cart_pos, get_scaled_pos, wrap, site_attributes)	Iterate through the sites of the structure.
`keys`()	Return property names to create the structure.
`perform_analysis`(method, kwargs)	Perform structure analaysis using an external method.
`perform_manipulation`(method, kwargs)	Perform structure manipulation using an external method.
`scale_unit_cell`(scaling_factor, change_label)	Scale unit cell of the structure.
`set_attribute`(key, value)	Set attribute.
`set_positions`(positions, is_cartesian, wrap)	Set postions of atoms.
`set_site_attribute`(key, values)	Set site attribute.
`substitute_elements`(elements, radius_type, remove_kind, change_label)	Substitute all atoms of one or several elements.
`to_aiida_structuredata`(label)	Create AiiDA structuredata.
`to_ase_atoms`()	Create ase Atoms object.
`to_dict`(cartesian, wrap, include_calculated_properties)	Export structure to python dictionary.
`to_file`(file_path)	Export structure to file using the ase interface or certain file formats for Zeo++.
`to_pymatgen_structure`()	Create pymatgen Structure (if cell is not None) or Molecule (if cell is None) object.

class property analysis_methods : list¶

Return calculation methods.

Type:¶: list

property attributes : dict¶: Return attributes.

property cell : tuple | None¶: Return the cell of the structure.

property cell_angles : tuple | None¶

Cell angles.

Type:¶: tuple

property cell_lengths : tuple | None¶

cell lengths.

Type:¶: tuple

property cell_volume : float | None¶

cell volume.

Type:¶: tuple

property chem_formula : dict¶: Return chemical formula.

property elements : tuple¶: Return the elements of the structure.

class property export_methods : list¶

Return export methods.

Type:¶: list

property extras : dict¶: Return extras.

property function_args : dict¶: Return function arguments for stored extras.

class property import_methods : list¶

Return import methods.

Type:¶: list

property kinds : tuple | None¶

Kinds of the structure.

Type:¶: tuple

property label : str | None¶: Return label of the structure (especially relevant in StructureCollection).

class property manipulation_methods : list¶

Return manipulation methods.

Type:¶: list

property pbc : tuple¶: Return the pbc of the structure.

property positions : tuple¶

Return the cartesian positions of the structure.

Type:¶: tuple

property scaled_positions : tuple | None¶

Return the scaled positions of the structure.

Type:¶: tuple or None

property site_attributes : dict | None¶: dict: Dictionary containing the label of a site attribute as key and a tuple/list of values having the same length as the Structure object itself (number of sites) containing site specific properties or attributes (e.g. charges, magnetic moments, forces, …).

property store_calculated_properties : bool¶: Store calculated properties to reuse them later.

calculate_angle(site_index1: int = 0, site_index2: int = 1, site_index3: int = 2, backfold_positions: bool = True) → float¶

Calculate angle between three atoms.

Parameters:¶

site_index1 (int) – Index of the site.
site_index2 (int) – Index of the site.
site_index3 (int) – Index of the site.
backfold_positions (bool) – Whether to backfold the atomic sites and return the smallest distance.

Returns:¶

float – Angle calculated via the vectors from atom 2 to atom 1 and atom 3.

calculate_coordination(r_max: float = 10.0, method: str = 'minimum_distance', min_dist_delta: float = 0.1, n_nearest_neighbours: int = 5, radius_type: str = 'chen_manz', atomic_radius_delta: float = 0.0, econ_tolerance: float = 0.5, econ_conv_threshold: float = 0.001, voronoi_weight_type: float = 'rel_solid_angle', voronoi_weight_threshold: float = 0.5, okeeffe_weight_threshold: float = 0.5) → dict¶

Calculate coordination environment of each atomic site.

Parameters:¶

r_max (float (optional)) – Cut-off value for the maximum distance between two atoms in angstrom.
method (str (optional)) – Method used to calculate the coordination environment. The default value is 'minimum_distance'.
min_dist_delta (float (optional)) – Tolerance parameter that defines the relative distance from the nearest neighbour atom for the 'minimum_distance' method.
n_nearest_neighbours (int (optional)) – Number of neighbours that are considered coordinated for the 'n_neighbours' method.
radius_type (str (optional)) – Type of the atomic radius used for the 'atomic_radius' method ('covalent' is used as fallback in the radius for an element is not defined).
atomic_radius_delta (float (optional)) – Tolerance relative to the sum of the atomic radii for the 'atomic_radius' method. If set to 0.0 the maximum threshold is defined by the sum of the atomic radii, positive (negative) values increase (decrease) the threshold.
econ_tolerance (float (optional)) – Tolerance parameter for the econ method.
econ_conv_threshold (float (optional)) – Convergence threshold for the econ method.
voronoi_weight_type (str (optional)) – Weight type of the Voronoi facets. Supported options are 'covalent_atomic_radius', 'area' and 'solid_angle'. The prefix 'rel_' specifies that the relative weights with respect to the maximum value of the polyhedron are calculated.
voronoi_weight_threshold (float (optional)) – Weight threshold to consider a neighbouring atom coordinated.
okeeffe_weight_threshold (float (optional)) – Threshold parameter to distinguish indirect and direct neighbour atoms for the 'okeeffe'.

This parameter is depreciated and will be removed in a future version. The original results can be obtained by using the voronoi_weight_threshold parameter and setting voronoi_weight_type to 'rel_solid_angle'.

Returns:¶

dict – Dictionary containing the coordination information of the structure.

calculate_dihedral_angle(site_index1: int = 0, site_index2: int = 1, site_index3: int = 2, site_index4: int = 3, backfold_positions: bool = True) → float¶

Calculate dihedral angle between four atoms.

Parameters:¶

site_index1 (int) – Index of the site.
site_index2 (int) – Index of the site.
site_index3 (int) – Index of the site.
site_index4 (int) – Index of the site.
backfold_positions (bool) – Whether to backfold the atomic sites and return the smallest distance.

Returns:¶

float – Dihedral angle.

calculate_distance(site_index1: int | list[int] = 0, site_index2: int | list[int] = 1, backfold_positions: bool = True, use_supercell: bool = False, r_max: float = 7.5, return_pos: bool = False) → float | list¶

Calculate distance between two atoms.

Parameters:¶

site_index1 (int) – Index of the site.
site_index2 (int) – Index of the site.
backfold_positions (bool) – Whether to backfold the atomic sites and return the smallest distance.
use_supercell (bool) – User supercell to calculate all distances between the two atomic sites up to the radius r_max.
r_max (float) – Cut-off value for the maximum distance between two atoms in angstrom.
return_pos (bool) – Whether to return the positions. Useful if use_supercell is set to True or when trying to determine the closest periodic image.

Returns:¶

float or None – Distance between the two atoms or a list of distances (if use_super_cell is set to True). If multiple indices are provided, a dictionary with the index pairs as keys is returned. If return_pos is set to True, the positions are returned as well. In case use_super_cell is set to True and the distance between the two sites exceeds r_max, None is returned.

calculate_ffingerprint(r_max: float = 20.0, delta_bin: float = 0.005, sigma: float = 0.05, use_legacy_smearing: bool = False, distinguish_kinds: bool = False) → tuple[dict, dict]¶

Calculate f-fingerprint function for each element-pair and atomic site.

The calculation is based on equation (3) in doi:10.1063/1.3079326.

Parameters:¶

r_max (float (optional)) – Cut-off value for the maximum distance between two atoms in angstrom.
delta_bin (float (optional)) – Bin size to descritize the function in angstrom.
sigma (float (optional)) – Smearing parameter for the Gaussian function.
use_legacy_smearing (bool) – Use the depreciated smearing method.
distinguish_kinds (bool (optional)) – Whether different kinds should be distinguished e.g. Ni0 and Ni1 would be considered as different elements if True.

Returns:¶

element_fingerprints (dict) – Dictionary containing all fingerprint functions of the structure summed over all atoms of the same element.
atomic_fingerprints (dict) – Dictionary containing all individual fingerprint functions for each atomic site.

calculate_voronoi_tessellation(r_max: float = 10.0) → list[list[dict]]¶

Calculate voronoi polyhedron for each atomic site.

Parameters:¶: r_max (float (optional)) – Cut-off value for the maximum distance between two atoms in angstrom.
Returns:¶: list – List of voronoi details for each atomic site.

copy() → Structure[source]¶: Return copy of Structure object.

delete_atoms(elements: str | list[str] = [], site_indices: int | list[int] = [], change_label: bool = False) → aim2dat.strct.Structure | aim2dat.strct.StructureCollection¶

Delete atoms by element, list of elements, site index or list of site indices.

Parameters:¶

elements (str, list or tuple) – Element or tuple or list of the elements to be deleted.
site_indices (list or tuple) – Site index or tuple or list of site indices to be deleted.

Returns:¶

aim2dat.strct.Structure – Structure with deleted atoms.

determine_point_group(threshold_distance: float = 0.1, threshold_angle: float = 1.0, threshold_inertia: float = 0.1) → dict¶

Determine the point group of a molecule.

Parameters:¶

threshold_distance (float (optional)) – Tolerance parameter for distances.
threshold_angle (float (optional)) – Tolerance parameter for angles.
threshold_inertia (float (optional)) – Tolerance parameter for inertia.

Returns:¶

dict – Dictionary containing the point group and symmetry elements of the structure.

determine_space_group(symprec: float = 0.005, angle_tolerance: float = -1.0, hall_number: int = 0, return_sym_operations: bool = False, return_primitive_structure: bool = False, return_standardized_structure: bool = False, no_idealize: bool = False) → dict¶

Determine the space group of the structure using spglib as backend.

Parameters:¶

symprec (float (optional)) – Tolerance parameter for spglib
angle_tolerance (float (optional)) – Tolerance parameter for spglib.
hall_number (int (optional)) – The argument to constrain the space-group-type search only for the Hall symbol corresponding to it.
return_sym_operations (bool (optional)) – Additionally, return all symmetry elements.
return_primitive_structure (bool (optional)) – Whether to return the primitive standardized structure.
return_standardized_structure (bool (optional)) – Whether to the non-primitive standardized structure.
no_idealize (bool (optional)) – Whether to idealize unit cell vectors and angles.

Returns:¶

dict – Dictionary containing the internal space group number and labels.

classmethod from_aiida_structuredata(structure_node: int | str | aiida.orm.StructureData, use_uuid: bool = False, label: str = None) → Structure[source]¶

Append structure from AiiDA structure node.

Parameters:¶

label (str) – Label used internally to store the structure in the object.
structure_node (int, str or aiida.orm.nodes.data.structure.StructureData) – Primary key, UUID or AiiDA structure node.
use_uuid (bool (optional)) – Whether to use the uuid (str) to represent AiiDA nodes instead of the primary key (int).

Returns:¶

aim2dat.strct.Structure – Structure.

classmethod from_ase_atoms(ase_atoms: ase.Atoms, attributes: dict = None, label: str = None) → Structure[source]¶

Get structure from ase atoms object.

Parameters:¶

ase_atoms (ase.Atoms) – ase Atoms object.
attributes (dict) – Attributes stored within the structure object.
label (str) – Label used internally to store the structure in the object.

Returns:¶

aim2dat.strct.Structure – Structure.

classmethod from_file(file_path: str, attributes: dict = None, label: str = None, backend: str = 'ase', file_format: str = None, backend_kwargs: dict = None) → Structure[source]¶

Get structure from file using the ase read-function.

Parameters:¶

file_path (str) – File path.
attributes (dict) – Attributes stored within the structure object(s).
label (str) – Label used internally to store the structure in the object.
backend (str (optional)) – Backend to be used to parse the structure file. Supported options are 'ase' and 'internal'.
file_format (str or None (optional)) – File format of the backend. For 'ase', please refer to the documentation of the package for a complete list. For 'internal', the format translates from io.{module}.read_structure to '{module}' or from {module}.read_{specification}_structure to 'module-specification'. If set to None the corresponding function is searched based on the file name and suffix.
backend_kwargs (dict (optional)) – Arguments passed to the backend function.

Returns:¶

aim2dat.strct.Structure – Structure.

classmethod from_pymatgen_structure(pymatgen_structure: pymatgen.core.Molecule | pymatgen.core.Structure, attributes: dict = None, label: str = None) → Structure[source]¶

Get structure from pymatgen structure or molecule object.

Parameters:¶

pymatgen_structure (pymatgen.core.Structure or pymatgen.core.Molecule) – pymatgen structure or molecule object.
attributes (dict) – Additional information about the structure.
label (str) – Label used internally to store the structure in the object.

Returns:¶

aim2dat.strct.Structure – Structure.

get(key, value=None)[source]¶: Get attribute by key and return default if not present.

get_positions(cartesian: bool = True, wrap: bool = False)[source]¶

Return positions of atoms.

Parameters:¶

cartesian (bool (optional)) – Get cartesian positions. If set to False scaled positions are returned.
wrap (bool (optional)) – Wrap atomic positions into the unit cell.

iter_sites(get_kind: bool = False, get_cart_pos: bool = False, get_scaled_pos: bool = False, wrap: bool = False, site_attributes: str | list = [])[source]¶

Iterate through the sites of the structure.

Parameters:¶

get_kind (bool (optional)) – Include kind in tuple.
get_cart_pos (bool (optional)) – Include cartesian position in tuple.
get_scaled_pos (bool (optional)) – Include scaled position in tuple.
wrap (bool (optional)) – Wrap atomic positions back into the unit cell.
site_attributes (list (optional)) – Include site attributes defined by their label.

Yields:¶

str or tuple – Either element symbol or tuple containing the element symbol, kind string, cartesian position, scaled position or specified site attributes.

keys() → list[source]¶: Return property names to create the structure.

perform_analysis(method: collections.abc.Callable, kwargs: dict = {})[source]¶

Perform structure analaysis using an external method.

Parameters:¶

method (function) – Analysis function.
kwargs (dict) – Arguments to be passed to the function.

Returns:¶

output – Output of the analysis.

perform_manipulation(method: collections.abc.Callable, kwargs: dict = {})¶

Perform structure manipulation using an external method.

Parameters:¶

method (function) – Function which manipulates the structure(s).
kwargs (dict) – Arguments to be passed to the function.

Returns:¶

aim2dat.strct.Structure or
aim2dat.strct.StructureCollection – Manipulated structure(s).

scale_unit_cell(scaling_factor: float = 1.0, change_label: bool = False) → aim2dat.strct.Structure | aim2dat.strct.StructureCollection¶

Scale unit cell of the structure.

Parameters:¶: scaling_factor (float) – Scaling factor.
Returns:¶: aim2dat.strct.Structure – Structure with scaled unit cell.

set_attribute(key: str, value)[source]¶

Set attribute.

Parameters:¶

key (str) – Key of the attribute.
value – Value of the attribute.

set_positions(positions: list | tuple, is_cartesian: bool = True, wrap: bool = False)[source]¶

Set postions of atoms.

Parameters:¶

positions (list or tuple) – Nested list or tuple of the coordinates (n atoms x 3).
is_cartesian (bool (optional)) – Whether the coordinates are cartesian or scaled.
wrap (bool (optional)) – Wrap atomic positions into the unit cell.

set_site_attribute(key: str, values: list | tuple)[source]¶

Set site attribute.

Parameters:¶

key (str) – Key of the site attribute.
values – Values of the attribute, need to have the same length as the Structure object itself (number of sites).

substitute_elements(elements: list[tuple[str]] | list[tuple[int]] = [], radius_type: str | None = 'covalent', remove_kind: bool = False, change_label: bool = False) → aim2dat.strct.Structure | aim2dat.strct.StructureCollection¶

Substitute all atoms of one or several elements.

Parameters:¶

elements (list or tuple) – Tuple or list of tuples of the elements that are substituted.
remove_kind (bool (optional)) – Sets the entries of the substituted sites in kinds to None.
radius_type (str or None (optional)) – Radius type used to calculate the scaling factor for the unit cell. If set to None no scaling is applied. The default value is covalent.

Returns:¶

aim2dat.strct.Structure – Structure with substituted elements.

to_aiida_structuredata(label=None)[source]¶

Create AiiDA structuredata.

Returns:¶: aiida.orm.StructureData – AiiDA structure node.

to_ase_atoms() → ase.Atoms[source]¶

Create ase Atoms object.

Returns:¶: ase.Atoms – ase Atoms object of the structure.

to_dict(cartesian: bool = True, wrap: bool = False, include_calculated_properties: bool = False) → dict[source]¶

Export structure to python dictionary.

Parameters:¶

cartesian (bool (optional)) – Whether cartesian or scaled coordinates are returned.
wrap (bool (optional)) – Whether the coordinates are wrapped back into the unit cell.
include_calculated_properties (bool (optional)) – Include extras and function_args in the dictionary as well.

Returns:¶

dict – Dictionary representing the structure. The Structure object can be retrieved via Structure(**dict).

to_file(file_path: str) → None[source]¶: Export structure to file using the ase interface or certain file formats for Zeo++.

to_pymatgen_structure() → pymatgen.core.Molecule | pymatgen.core.Structure[source]¶

Create pymatgen Structure (if cell is not None) or Molecule (if cell is None) object.

Returns:¶: pymatgen.core.Structure or pymatgen.core.Molecule – pymatgen structure or molecule object.

class aim2dat.strct.StructureCollection(structures: list[aim2dat.strct.strct.Structure | dict] | None = None)[source]¶

The StructureCollection class is a container for one or multiple atomic structures. It implements several import_* and append_* functions to add new data to the object.

Parameters:¶: structures (list) – List of Structure or dict objects.

Overview

Properties¶
`labels`	Labels assigened to the structures.

Methods¶
`append`(label, elements, positions, pbc, cell, is_cartesian, wrap, kinds, attributes, extras)	Append structure.
`append_from_aiida_structuredata`(aiida_node, use_uuid, label)	Append structure from aiida structuredata.
`append_from_ase_atoms`(label, ase_atoms, attributes)	Append structure from ase atoms object.
`append_from_file`(label, file_path, attributes, backend, backend_kwargs)	Append structure from file using the ase read-function.
`append_from_pymatgen_structure`(label, pymatgen_structure, attributes)	Append structure from pymatgen structure or molecule object.
`append_structure`(structure, label)	Append `Structure` object to collection. The label of the structure needs to be
`copy`()	Return copy of `StructureCollection` object.
`create_pandas_df`(exclude_columns)	Create a pandas data frame of the object.
`duplicate_structure`(key, new_label)	Duplicate structure.
`get_all_attribute_keys`()	Get all attribute keys.
`get_all_elements`()	Get the element symbols of all structures.
`get_all_kinds`()	Get the kind strings of all structures.
`get_all_structures`()	Return a list of all structures.
`get_structure`(key, return_index_label)	Get structure by key.
`import_from_aiida_db`(group_label, use_uuid, raise_error)	Import from the AiiDA database.
`import_from_hdf5_file`(file_path, raise_error)	Import from hdf5-file. Calculated extras are not yet supported.
`import_from_pandas_df`(data_frame, structure_column, exclude_columns, use_uuid, raise_error)	Import from pandas data frame.
`index`(label)	Return index of label. If the label is not present, `None` is returned.
`items`()	Return a list of label, value tuples.
`pop`(key)	Pop structure.
`store_in_aiida_db`(group_label, group_description)	Store structures into the AiiDA-database.
`store_in_hdf5_file`(file_path)	Store structures in hdf5-file. Calculated extras are not yet supported.

property labels : list[str]¶: Labels assigened to the structures.

append(label: str, elements: list, positions: list, pbc: list, cell: list = None, is_cartesian: bool = True, wrap: bool = False, kinds: list = None, attributes: dict = None, extras: dict = None)[source]¶

Append structure.

Parameters:¶

label (str) – String used to identify the structure.
elements (list) – List of element symbols or their atomic numbers.
positions (list) – List of the atomic positions, either cartesian or scaled coordinates.
pbc (list or bool) – Periodic boundary conditions.
cell (list or np.array) – Nested 3x3 list of the cell vectors.
is_cartesian (bool (optional)) – Whether the coordinates are cartesian or scaled.
wrap (bool (optional)) – Wrap atomic positions back into the unit cell.
kinds (list) – List of kind names (this allows custom kinds like Ni0, Ni1, …). If None, the elements will be used as the kind names.
attributes (dict) – Additional information about the structure.
extras (dict) – Extras of the structure.

append_from_aiida_structuredata(aiida_node: int | str | aiida.orm.StructureData, use_uuid: bool = False, label: str = None)[source]¶

Append structure from aiida structuredata.

Parameters:¶

aiida_node (int, str or aiida.orm.StructureData) – Primary key, UUID or AiiDA structure node.
use_uuid (bool (optional)) – Whether to use the uuid (str) to represent AiiDA nodes instead of the primary key (int).
label (str) – String used to identify the structure. Overwrites label property of the structure.

append_from_ase_atoms(label: str, ase_atoms: ase.Atoms, attributes: dict = None)[source]¶

Append structure from ase atoms object.

Parameters:¶

label (str) – String used to identify the structure.
ase_atoms (ase.Atoms) – ase Atoms object.
attributes (dict) – Additional information about the structure.

append_from_file(label: str, file_path: str, attributes: dict = None, backend: str = 'ase', backend_kwargs: dict = None)[source]¶

Append structure from file using the ase read-function.

Parameters:¶

label (str) – String used to identify the structure.
file_path (str) – File path.
attributes (dict) – Additional information about the structure.

append_from_pymatgen_structure(label: str, pymatgen_structure: pymatgen.core.Molecule | pymatgen.core.Structure, attributes: dict = None)[source]¶

Append structure from pymatgen structure or molecule object.

Parameters:¶

label (str) – String used to identify the structure.
pymatgen_structure (pymatgen.core.Structure or pymatgen.core.Molecule) – pymatgen structure or molecule object.
attributes (dict) – Additional information about the structure.

append_structure(structure: aim2dat.strct.strct.Structure, label: str = None)[source]¶

Append Structure object to collection. The label of the structure needs to be either given via the structures’s property or as keyword argument.

Parameters:¶

structure (Structure) – Structure object.
label (str (optional)) – String used to identify the structure. Overwrites label property of the structure.

copy() → StructureCollection[source]¶: Return copy of StructureCollection object.

create_pandas_df(exclude_columns: list = []) → pandas.DataFrame[source]¶

Create a pandas data frame of the object.

Parameters:¶: exclude_columns (list (optional)) – Columns that are not shown in the pandas data frame.
Returns:¶: pandas.DataFrame – Pandas data frame.

duplicate_structure(key: str | int, new_label: str)[source]¶

Duplicate structure.

Parameters:¶

key (str or int) – Key of the structure.
new_label (str) – Label of the copied structure.

get_all_attribute_keys() → list[source]¶

Get all attribute keys.

Returns:¶: list – All attribute keys.

get_all_elements() → list[str][source]¶

Get the element symbols of all structures.

Returns:¶: list – List of all element symbols .

get_all_kinds() → list[source]¶

Get the kind strings of all structures.

Returns:¶: list – List of all kinds.

get_all_structures() → list[aim2dat.strct.strct.Structure][source]¶

Return a list of all structures.

Returns:¶: list – List of all structures stored in the object.

get_structure(key: str | int, return_index_label: bool = False) → aim2dat.strct.strct.Structure[source]¶

Get structure by key.

Parameters:¶: key (str or int) – Key of the structure.
Returns:¶: Structure – structure.

import_from_aiida_db(group_label: str = None, use_uuid: bool = False, raise_error: bool = True)[source]¶

Import from the AiiDA database.

Parameters:¶

group_label (str or list (optional)) – Constrains query to structures that are member of the group(s).
use_uuid (bool (optional)) – Whether to use the uuid (str) to represent AiiDA nodes instead of the primary key (int).
raise_error (bool (optional)) – Whether to raise an error if one of the constraints is not met.

import_from_hdf5_file(file_path: str, raise_error: bool = True)[source]¶

Import from hdf5-file. Calculated extras are not yet supported.

Parameters:¶

file_path (str) – File path.
raise_error (bool (optional)) – Whether to raise an error if one of the constraints is not met.

import_from_pandas_df(data_frame: pandas.DataFrame, structure_column: str = 'optimized_structure', exclude_columns: list = [], use_uuid: bool = False, raise_error: bool = True)[source]¶

Import from pandas data frame.

Parameters:¶

data_frame (pd.DataFrame) – Pandas data frame containing at least one column with the AiiDA structure nodes.
structure_column (str (optional)) – Column containing AiiDA structure nodes used to determine structural and compositional properties. The default value is 'optimized_structure'.
exclude_columns (list (optional)) – Columns of the data frame that are excluded. The default value is [].
use_uuid (bool (optional)) – Whether to use the uuid (str) to represent AiiDA nodes instead of the primary key (int).
raise_error (bool (optional)) – Whether to raise an error if one of the constraints is not met.

index(label: str)[source]¶

Return index of label. If the label is not present, None is returned.

Parameters:¶: str – Label of the structure.

items() → list[tuple[str, aim2dat.strct.strct.Structure]][source]¶: Return a list of label, value tuples.

pop(key: str | int) → aim2dat.strct.strct.Structure[source]¶

Pop structure.

Parameters:¶: str – Key of the structure.

store_in_aiida_db(group_label: str = None, group_description: str = None)[source]¶

Store structures into the AiiDA-database.

Parameters:¶

group_label (str (optional)) – Label of the AiiDA group.
group_description (str (optional)) – Description of the AiiDA group.

Returns:¶

list – List containing dictionary of all structure nodes.

store_in_hdf5_file(file_path: str)[source]¶

Store structures in hdf5-file. Calculated extras are not yet supported.

Parameters:¶: file_path (str) – File path.

class aim2dat.strct.StructureImporter(structures: aim2dat.strct.StructureCollection = None, neglect_elemental_structures: bool = False)[source]¶

Bases: aim2dat.strct.mixin.ConstraintsMixin

Imports structures from online databases.

Overview

Properties¶
`attribute_constraints`	Attribute constraints.
`chem_formula_constraints`	Constraints on the chemical formula.
`concentration_constraints`	Elemental concentration constraints.
`neglect_elemental_structures`	Whether to neglect elemental phases.
`structures`	Return the internal `StructureCollection` object.

Methods¶
`add_chem_formula_constraint`(chem_formula, reduced_formula)	Add a chemical formula as a constraint.
`append_from_mp_by_id`(entry_id, api_key, property_data, structure_type)	Append structure via the database-id.
`generate_random_crystals`(formulas, excl_space_groups, tol_tuples, molecular, dimensions, bin_size, max_atoms, max_structures, max_structures_per_cs, max_structures_per_sg, volume_factor)	Generate random crystals using the PyXtaL library.
`import_from_mp`(formulas, api_key, compatible_only, conv_unit_cell, property_data, structure_type, use_openapi)	Import structures from the crystal database Materials Project using the pymatgen interface.
`import_from_optimade`(formulas, database_id, api_version, optimade_url, timeout)	Import crystal structures using the optimade-API.
`import_from_oqmd`(formulas, query_limit)	Import from the open quantum materials database.
`remove_constraints`()	Remove all constraints.
`return_optimade_database_ids`(api_version, optimade_url, timeout)	Return a list of all ids of online databases that provide a base-url.
`set_attribute_constraint`(attribute, min_value, max_value)	Set a constraint on attributes.
`set_concentration_constraint`(element, min_conc, max_conc)	Set a constraint on the concentration of an element in the structure.

property attribute_constraints¶: Attribute constraints.

property chem_formula_constraints¶: Constraints on the chemical formula.

property concentration_constraints¶: Elemental concentration constraints.

property neglect_elemental_structures¶: Whether to neglect elemental phases.

property structures : aim2dat.strct.StructureCollection¶: Return the internal StructureCollection object.

add_chem_formula_constraint(chem_formula, reduced_formula=True)¶

Add a chemical formula as a constraint.

The formula can be given as a string, dictionary or list of strings or dictionaries.

Parameters:¶

chem_formula (list, dict or str) – Chemical formula given as list, dict or str.
reduced_formula (bool (optional)) – If set to True the reduced formulas are compared. The default value is True.

append_from_mp_by_id(entry_id: str, api_key: str, property_data: list = None, structure_type: str = 'initial') → aim2dat.strct.Structure[source]¶

Append structure via the database-id.

Parameters:¶

entry_id (str) – Database id of the entry.
api_key (str) – API key for the database, can be obtained here: https://www.materialsproject.org/dashboard
property_data (list (optional)) – Extra data that is queried for each entry. The properties need to be passed as a list of strings (e.g. ['el_band_structure', 'el_dos'] to obtain the electronic band structure and the electronic density of states).
structure_type (str (optional)) – Materials project includes the initial and final (relaxed) stucture in the database. The intial or final structure can be queried by setting this attribute to initial or final, respectively.

generate_random_crystals(formulas: str | list[str], excl_space_groups: list = [], tol_tuples: list = None, molecular: bool = False, dimensions: int = 3, bin_size: float = 0.1, max_atoms: int = 30, max_structures: int = 10, max_structures_per_cs: int = 10, max_structures_per_sg: int = 5, volume_factor: float = 1.0) → aim2dat.strct.StructureCollection[source]¶

Generate random crystals using the PyXtaL library.

Parameters:¶

formulas (str or list of str) – List of chemical formulas or systems that are queried from the database. E.g. 'Fe2O3' - defined chemical composition, 'Cs' - all entries of elemental phases Cs, 'Cs-Te' - all entries that exclusively contain the elements Cs and/or Te.
excl_space_groups (list (optional)) – Exclude one or more space groups.
tol_tuples (None or list) – Tolerance tuples used to create the tolerance matrix. The default value is None.
molecular (bool (optional)) – Whether to generate molecular crystals. The default value is False.
dimensions (int) – Dimension of the crystal, possible values range from zero to three. The default value is 3.
bin_size (float (optional)) – Size of bins that contain a certain number of structures. The default value is 0.1.
max_atoms (int (optional)) – Maximum number of atoms per structure. The default value is 30.
max_structures (int (optional)) – Maximum number of structures that are generated. The default value is 10.
max_structures_per_cs (int (optional)) – Maximum number of structures that are generated per crystal system. The default value is 10.
max_structures_per_sg (int (optional)) – Maximum number of structures that are generated per space group. The default value is 5.
volume_factor (float (optional)) – Volume factor used to generate the crystal. The default value is 1.0.

import_from_mp(formulas: str | list[str], api_key: str, compatible_only: bool = True, conv_unit_cell: bool = False, property_data: list = [], structure_type: str = 'initial', use_openapi: bool = False) → aim2dat.strct.StructureCollection[source]¶

Import structures from the crystal database Materials Project using the pymatgen interface.

Parameters:¶

formulas (str or list of str) – List of chemical formulas or systems that are queried from the database. E.g. 'Fe2O3' - defined chemical composition, 'Cs' - all entries of elemental phases Cs, 'Cs-Te' - all entries that exclusively contain the elements Cs and/or Te.
api_key (str) – API key for the database, can be obtained here: https://www.materialsproject.org/dashboard
compatible_only (bool (optional)) – Whether to only query compatible data. The default value is True.
conv_unit_cell (bool (optional)) – Query the conventional unit cell instead of the primitive unit cell. The default value is False.
property_data (list (optional)) – Extra data that is queried for each entry. The properties need to be passed as a list of strings (e.g. ['el_bandstructure', 'el_dos'] to obtain the electronic band structure and the electronic density of states). The default value is [].
structure_type (str (optional)) – Materials project includes the initial and final (relaxed) structure in the database. The initial or final structure can be queried by setting this attribute to initial or final, respectively. The default setting is initial.
use_openapi (bool (optional)) – Whether to use the openapi interface of Materials Project. If set to False the legacy interface is used. The default value is False.

import_from_optimade(formulas: str | list[str], database_id: str, api_version: int = 1, optimade_url: str = 'https://providers.optimade.org/providers.json', timeout: float = 60.0) → aim2dat.strct.StructureCollection[source]¶

Import crystal structures using the optimade-API.

The provider information is queried using the page: https://providers.optimade.org/providers.json.

Parameters:¶

formulas (str or list of str) – List of chemical formulas or systems that are queried from the database. E.g. 'Fe2O3' - defined chemical composition, 'Cs' - all entries of elemental phases Cs, 'Cs-Te' - all entries that exclusively contain the elements Cs and/or Te.
database_id (str) – Database used to query the data.
api_version (int (optional)) – Version of the optimade API. The default value is 1.
optimade_url (str (optional)) – Page used to obtain the provider information. The default value is 'https://providers.optimade.org/providers.json'.
timeout (float (optional)) – Specifies the time to wait for response from the server. The default value is 60.0.

import_from_oqmd(formulas: str | list[str], query_limit=1000) → aim2dat.strct.StructureCollection[source]¶

Import from the open quantum materials database.

Parameters:¶

formulas (str or list of str) – List of chemical formulas or systems that are queried from the database. E.g. 'Fe2O3' - defined chemical composition, 'Cs' - all entries of elemental phases Cs, 'Cs-Te' - all entries that exclusively contain the elements Cs and/or Te.
query_limit (int (optional)) – Maximum number of crystals that are queried.

remove_constraints()¶: Remove all constraints.

return_optimade_database_ids(api_version: int = 1, optimade_url: str = 'https://providers.optimade.org/providers.json', timeout: float = 60.0) → list[source]¶

Return a list of all ids of online databases that provide a base-url.

Parameters:¶

api_version (int (optional)) – Version of the optimade API. The default value is 1.
optimade_url (str (optional)) – Page used to obtain the provider information. The default value is 'https://providers.optimade.org/providers.json'.
timeout (float (optional)) – Specifies the time to wait for response from the server. The default value is 60.0.

Returns:¶

list – List of provider-ids.

set_attribute_constraint(attribute, min_value=None, max_value=None)¶

Set a constraint on attributes.

Parameters:¶

attribute (str) – Attribute to be constraint.
min_value (float) – Minimum value of the attribute. In case of no limit the variable can be set to 0.0.
max_value (float) – Maximum value of the attribute. In case of no limit the variable can be set to 1.0.

set_concentration_constraint(element, min_conc=0.0, max_conc=1.0)¶

Set a constraint on the concentration of an element in the structure.

The minimum and maximum values have to be set between 0.0 and 1.0.

Parameters:¶

element (str) – Element to be constraint.
min_conc (float) – Minimum concentration. In case of no limit the variable can be set to 0.0.
max_conc (float) – Maximum concentration. In case of no limit the variable can be set to 1.0.

class aim2dat.strct.SurfaceGeneration(structure: aim2dat.strct.strct.Structure)[source]¶

Generates a surfaces and surface slabs based on a bulk crystal structure.

Overview

Methods¶
`create_surface`(miller_indices, termination, tolerance, symprec, angle_tolerance, hall_number)	Create surface from a bulk crystal structure.
`generate_surface_slabs`(miller_indices, nr_layers, periodic, vacuum, vacuum_factor, symmetrize, tolerance, symprec, angle_tolerance, hall_number)	Generate surface slabs with all terminations for a certain direction given by its
`store_surfaces_in_aiida_db`(miller_indices, tolerance, symprec, angle_tolerance, hall_number, group_label, group_description)	Store surfaces into the AiiDA-database.
`to_aiida_surfacedata`(miller_indices, termination, tolerance, symprec, angle_tolerance, hall_number)	Create surface from a bulk crystal structure.

create_surface(miller_indices: tuple[int] | list[int] = (1, 0, 0), termination: int = 1, tolerance: float = 0.005, symprec: float = 0.005, angle_tolerance: float = -1.0, hall_number: int = 0) → dict[source]¶

Create surface from a bulk crystal structure.

Parameters:¶

miller_indices (list or tuple (optional)) – Miller indices of the surface. The default value is (1, 0, 0).
termination (int (optional)) – Determine termination of the surface.
tolerance (float (optional)) – Numerical tolerance. The default value is 0.005.
symprec (float (optional)) – Tolerance parameter for spglib. The default value is 0.005.
angle_tolerance (float (optional)) – Tolerance parameter for spglib. The default value is -1.0.
hall_number (int (optional)) – The argument to constrain the space-group-type search only for the Hall symbol corresponding to it. The default number is 0.

Returns:¶

dict – Dictionary containing the surface data.

generate_surface_slabs(miller_indices: tuple[int] | list[int] = (1, 0, 0), nr_layers: int = 5, periodic: bool = False, vacuum: float = 10.0, vacuum_factor: float = 0.0, symmetrize: bool = True, tolerance: float = 0.01, symprec: float = 0.005, angle_tolerance: float = -1.0, hall_number: int = 0) → aim2dat.strct.structure_collection.StructureCollection | None[source]¶

Generate surface slabs with all terminations for a certain direction given by its miller indices.

Parameters:¶

miller_indices (list or tuple (optional)) – Miller indices of the surface. The default value is (1, 0, 0).
nr_layers (int (optional)) – Number of repititions of the underlying periodic surface cell. The default value is 5.
periodic (bool (optional)) – Whether to apply periodic boundary conditions in the direction normal to the surface plane. The default value is False.
vacuum (float (optional)) – Vacuum space added at the top and bottom of the slab. The default value is 10.0.
vacuum_factor (float (optional)) – Alternatively to the vacuum-parameter the amount of vacuum can be set as a multiple of the slab size. The method is only applied if the parameter is larger than zero. The default value is 0.0.
symmetrize (bool (optional)) – Create slabs that have the same termination on both sides. The default value is True.
tolerance (float (optional)) – Numerical tolerance. The default value is 0.005.
symprec (float (optional)) – Tolerance parameter for spglib. The default value is 0.005.
angle_tolerance (float (optional)) – Tolerance parameter for spglib. The default value is -1.0.
hall_number (int (optional)) – The argument to constrain the space-group-type search only for the Hall symbol corresponding to it. The default number is 0.

Returns:¶

StructureCollection – Collection of the generated surface slabs.

store_surfaces_in_aiida_db(miller_indices: tuple[int] = (1, 0, 0), tolerance: float = 0.005, symprec: float = 0.005, angle_tolerance: float = -1.0, hall_number: int = 0, group_label: str = None, group_description: str = None)[source]¶

Store surfaces into the AiiDA-database.

Parameters:¶

miller_indices (list or tuple (optional)) – Miller indices of the surface. The default value is (1, 0, 0).
tolerance (float (optional)) – Numerical tolerance. The default value is 0.005.
symprec (float (optional)) – Tolerance parameter for spglib. The default value is 0.005.
angle_tolerance (float (optional)) – Tolerance parameter for spglib. The default value is -1.0.
hall_number (int (optional)) – The argument to constrain the space-group-type search only for the Hall symbol corresponding to it. The default number is 0.
group_label (str (optional)) – Label of the AiiDA group.
group_description (str (optional)) – Description of the AiiDA group.

Returns:¶

list – List containing dictionary of all surface nodes.

to_aiida_surfacedata(miller_indices: tuple[int] | list[int] = (1, 0, 0), termination: int = 1, tolerance: float = 0.005, symprec: float = 0.005, angle_tolerance: float = -1.0, hall_number: int = 0)[source]¶

Create surface from a bulk crystal structure.

Parameters:¶

miller_indices (list or tuple (optional)) – Miller indices of the surface. The default value is (1, 0, 0).
termination (int (optional)) – Determine termination of the surface.
tolerance (float (optional)) – Numerical tolerance. The default value is 0.005.
symprec (float (optional)) – Tolerance parameter for spglib. The default value is 0.005.
angle_tolerance (float (optional)) – Tolerance parameter for spglib. The default value is -1.0.
hall_number (int (optional)) – The argument to constrain the space-group-type search only for the Hall symbol corresponding to it. The default number is 0.

Returns:¶

SurfaceData – AiiDA surface data node.

aim2dat.strct¶

Subpackages¶

Submodules¶

Package Contents¶

Classes¶

`aim2dat.strct`¶