httk.atomistic package

The httk.atomistic package

Classes and utilities for dealing with high-throughput calculations of atomistic systems.

class httk.atomistic.Assignments(siteassignments, extensions=[])[source]

Bases: HttkObject

Represents a possible vector of assignments

property atomic_numbers
classmethod create(assignments=None)[source]

Create a new assignment object,

assignments: a list-style object with one entry per ‘atom type’. Any sensible type accepted, most notably,

integers (for atom number)

property extended
property ratios
property ratioslist
property symbollists
property symbols
to_basis()[source]
classmethod use(old)[source]
class httk.atomistic.Cell(basis, lattice_system, orientation=1)[source]

Bases: HttkObject

Represents a cell (e.g., a unitcell, but also possibly just the basis vectors of a non-periodic system)

(The ability to represent the cell for a non-periodic system is also the reason this class is not called Lattice.)

clean()[source]
coordgroups_cartesian_to_reduced(coordgroups)[source]
coordgroups_reduced_to_cartesian(coordgroups)[source]
coords_cartesian_to_reduced(coords)[source]
coords_reduced_to_cartesian(coords)[source]
classmethod create(cell=None, basis=None, metric=None, niggli_matrix=None, a=None, b=None, c=None, alpha=None, beta=None, gamma=None, lengths=None, angles=None, cosangles=None, scale=None, scaling=None, volume=None, periodicity=None, nonperiodic_vecs=None, orientation=1, hall=None, lattice_system=None, eps=0)[source]

Create a new cell object,

cell: any one of the following:

  • a 3x3 array with (in rows) the three basis vectors of the cell (a non-periodic system should conventionally use an identity matrix)

  • a dict with a single key ‘niggli_matrix’ with a 3x2 array with the Niggli Matrix representation of the cell

  • a dict with 6 keys, ‘a’, ‘b’, ‘c’, ‘alpha’, ‘beta’, ‘gamma’ giving the cell parameters as floats

scaling: free form input parsed for a scale.

positive value = multiply basis vectors by this value negative value = rescale basis vectors so that cell volume becomes abs(value).

scale: set to non-None to multiply all cell vectors with this factor

volume: set to non-None if the basis vectors only give directions, and the volume of the cell should be this value (overrides scale)

periodicity: free form input parsed for periodicity

sequence: True/False for each basis vector being periodic integer: number of non-periodic basis vectors

hall: giving the hall symbol makes it possible to determine the lattice system without numerical inaccuracy

lattice_system: any one of: ‘cubic’, ‘hexagonal’, ‘tetragonal’, ‘orthorhombic’, ‘trigonal’, ‘triclinic’, ‘monoclinic’, ‘unknown’

get_axes_standard_order_transform()[source]
get_normalized()[source]
get_normalized_longestvec()[source]
is_point_inside(cartesian_coord)[source]
property normalization_longestvec_scale

Get the factor with which a normalized version of this cell needs to be multiplied to reproduce this cell.

I.e. self = (normalization_scale)*self.get_normalized()

property normalization_scale
scaling()[source]
classmethod use(other)[source]
property volume
class httk.atomistic.Compound(element_wyckoff_sequence, formula, spacegroup_number, extended, extensions, wyckoff_sequence, anonymous_wyckoff_sequence, anonymous_formula, formula_symbols, formula_counts, pbc)[source]

Bases: HttkObject

add_name(name)[source]
add_names(names)[source]
add_ref(ref)[source]
add_refs(refs)[source]
add_tag(tag, val)[source]
add_tags(tags)[source]
property anonymous_formula
property anonymous_wyckoff_sequence
classmethod create(base_on_structure=None, lift_tags=True, lift_refs=True)[source]

struct: Structure object which forms the basis of this object

property formula_counts
property formula_symbols
get_names()[source]
get_refs()[source]
get_tag(tag)[source]
get_tags()[source]
property number_of_elements
property wyckoff_sequence
class httk.atomistic.CompoundRef(compound, reference)[source]

Bases: HttkObject

class httk.atomistic.CompoundStructure(compound, structure)[source]

Bases: HttkObject

classmethod create(compound, structure)[source]
class httk.atomistic.CompoundTag(compound, tag, value)[source]

Bases: HttkObject

class httk.atomistic.PlaneWaveFunctions(file_ref=None, recpos_func=None, nkpts=None, nbands=None, nspins=None, nplws=None, encut=None, cell=None, kpts=None, kgrid_size=None, double_precision=None, eigs=None, occups=None, pwcoeffs=None, is_gamma=None, gamma_half=None, kgrid=None)[source]

Bases: HttkObject

PlaneWaveFunction is a proxy for a collection of wavefunctions contained in output files of plane-wave basis DFT codes.

This object stores the energy, occupation and plane-wave coefficients from a calculation, contained in a wavefunction file (e.g. a VASP WAVECAR). The access to the plane-wave coefficients is done in a lazy fashion, only caching the requested orbitals at specified K-points

In addition, it caches the k-vectors/g-vectors associated with the basis set and parameters necessary to generate these (e.g. VASP energy cutoff)

NOTE: Currently does not support non-collinear (SOC) output formats

NOTE: As fourier transforms and similar rely on the numpy/scipy/jax library, read-in FracVectors are in working functions converted to numpy arrays during processing

copy(spins=None, ikpts=None, bands=None, file_ref=None, format=None, gamma_half='x')[source]
classmethod create(file_wrapper=None, rec_pos_func=None, nplws=None, encut=None, cell=None, kpts=None, double_precision=None, eigs=None, occups=None, pwcoeffs=None, is_gamma=None, gamma_half='x')[source]

Factory function for the proxy object for wavefunctions file.

Input: file_wrapper: File wrapper for the wavefunction file. If None, the wavefunction coefficients must be provided directly rec_pos_func: Function taking spin, kpoint and band indices, returning the record position in the binary file. If None, the coefficients must be provided directly nplws: Number of plane-waves for each k-point. encut: Energy cutoff for the plane-wave basis set cell: Cell object containing the basis vectors of the supercell kpts: List of k-points for the wavefunction coefficients double_precision: If the wavefunction coefficients are stored in double precision (True) or single precision (False) eigs: Eigenvalues of the wavefunctions occups: Occupation numbers of the wavefunctions pwcoeffs: Coefficients of the wavefunctions. Either a nested list of coefficients, or a dictionary with keys (spin, kpt, band) and values as list-like objects of coefficients is_gamma: If the wavefunction is gamma-compressed (True) or not (False). If None, the function tries to determine the format from the k-point list and the number of plane-waves gamma_half: If the wavefunction is gamma-compressed, which axis of k-space was used for the compression. Either “x” or “z”, but defaults to “x”. Only relevant if is_gamma is True.

Either file_wrapper and rec_pos_func must be provided, or pwcoeffs must be provided directly. If both are provided, the pwcoeffs are ignored.

eigenval(s, k, b)[source]
property encut

Returns the energy cutoff for the plane-wave basis set.

property gamma_half

Returns the axis of k-space used for gamma-compression, if the wavefunction is gamma-compressed.

get_gvecs(kpt_ind=None, kpt=None, gamma=None, gamma_half=None, kgrid=None, cache=True)[source]

Getter function for the g-vectors of the wavefunction. Can either be used to generate a new set of g-vectors, or to retrieve a cached set of g-vectors for the current object.

Input: kpt_ind: K-point index of the wavefunction (1-indexed) kpt: K-point vector of the wavefunction (3D numpy array), if kpt_ind is not provided gamma: Whether to generate gamma-compressed g-vectors (True) or not (False). If None, use the gamma-format of the wavefunction object. gamma_half: Which axis of k-space to use for the gamma-compression. Either “x” or “z”. Only relevant if gamma is True. kgrid: The k-grid to use for the generation of the g-vectors. If None, generate a new k-grid for current object.

get_plws(spin, kpt, band, cache=True)[source]

Getter function for the plane-wave coefficients of the wavefunction. The function will check if the coefficients are already cached, and if not, read them from the file.

Input: spin: Spin index of the wavefunction (1-indexed) kpt: K-point index of the wavefunction (1-indexed) band: Band index of the wavefunction (1-indexed) cache: If True, the coefficients are cached in the object. If False, the coefficients are not cached and read from the file every time.

Output: coeffs: 3D numpy array of complex numbers, containing the plane-wave coefficients of the wavefunction

get_wavr(spin, kpt, band, norm=True)[source]

Getter function for the real-space form of the wavefunction at given indices.

Input: spin: Spin index of the wavefunction (1-indexed) kpt: K-point index of the wavefunction (1-indexed) band: Band index of the wavefunction (1-indexed) norm: If True, the wavefunction is normalized to unit length. Otherwise, the wavefunction is transformed as found in the WAVECAR.

Output: real_space_wave: 3D numpy array of complex numbers, containing the real-space form of the wavefunction

property is_gamma

Returns whether the wavefunction is gamma-compressed or not.

property kpoints

Returns the k-points of the wavefunction object as fracvector array.

property nbands

Returns the number of bands in the wavefunction object.

property nkpts

Returns the number of k-points in the wavefunction object.

property nplanewaves

Returns the number of plane-waves for each k-point in the wavefunction object.

property nspins

Returns the number of spin-channels in the wavefunction object.

occupation(s, k, b)[source]
read_plws(spin, kpt, band)[source]

Reads the plane-wave coefficients from the stored file wrapper. The function will check if the file reference is valid and if the record position function is valid.

rearrange(index_map)[source]

Exchanges specified orbitals, exchanging band index or spin index according to given map. Note that orbitals cannot be exchanged between k-points, as the number of coefficients and g-vectors are k-dependent.

Input index_map: Dictionary with indices of orbitals to rearrange as keys, and target indices as values, on the form (spin_i, k_i, band_i). k_i of key and value has to be the same. The map has to be one-to-one for the given indices in both directions.

class httk.atomistic.RepresentativeSites(reduced_coordgroups=None, cartesian_coordgroups=None, reduced_coords=None, cartesian_coords=None, counts=None, hall_symbol=None, pbc=None, wyckoff_symbols=None, multiplicities=None)[source]

Bases: Sites

Represents any collection of sites in a unitcell

property anonymous_wyckoff_sequence
clean()[source]
classmethod create(sites=None, reduced_coordgroups=None, reduced_coords=None, counts=None, spacegroup=None, hall_symbol=None, spacegroupnumber=None, setting=None, periodicity=None, wyckoff_symbols=None, multiplicities=None, occupancies=None, pbc=None)[source]

Create a new sites object

property crystal_system
get_uc_sites()[source]
property lattice_symbol
property lattice_system
tidy()[source]
property total_number_of_atoms
property wyckoff_sequence
class httk.atomistic.RepresentativeStructure(assignments, rc_sites=None, rc_cell=None)[source]

Bases: HttkObject

A RepresentativeStructure represents N sites of, e.g., atoms or ions, in any periodic or non-periodic arrangement. It keeps track of a set of representative atoms in a unit cell (the conventional cell) and the symmetry group / operations that are to be applied to them to get all atoms.

This is meant to be a light-weight Structure object. For a heavy-weight with more functionality, use Structure.

The RepresentativeStructure object is meant to be immutable and assumes that no internal variables are changed after its creation. All methods that ‘changes’ the object creates and returns a new, updated, structure object.

clean()[source]
classmethod create(structure=None, rc_cell=None, rc_basis=None, rc_lengths=None, rc_angles=None, rc_niggli_matrix=None, rc_metric=None, rc_a=None, rc_b=None, rc_c=None, rc_alpha=None, rc_beta=None, rc_gamma=None, rc_sites=None, rc_reduced_coordgroups=None, rc_cartesian_coordgroups=None, rc_reduced_coords=None, rc_cartesian_coords=None, rc_reduced_occupationscoords=None, rc_cartesian_occupationscoords=None, rc_occupancies=None, rc_counts=None, wyckoff_symbols=None, multiplicities=None, spacegroup=None, hall_symbol=None, spacegroupnumber=None, setting=None, rc_scale=None, rc_scaling=None, rc_volume=None, vol_per_atom=None, assignments=None, periodicity=None, nonperiodic_vecs=None, refs=None, tags=None)[source]

A Structure represents N sites of, e.g., atoms or ions, in any periodic or non-periodic arrangement.

This is a swiss-army-type constructor that allows a selection between a large number of optional arguments.

To create a new structure, three primary components are:
  • cell: defines the basis vectors in which reduced coordinates are expressed, and the

    unit of repetition (if the structure has any periodicity - see the ‘periodicity’ parameter)

  • assignments: a list of ‘things’ (atoms, ions, etc.) that goes on the sites in the structure

  • sites: a sensible representation of location / coordinates of the sites.

Note: rc_-prefixes are consistently enforced for any quantity that would be different in a UnitcellStructure. This is to allow for painless change between the various structure-type objects without worrying about accidently using the wrong type of sites object.

Input parameters:

  • ONE OF: ‘cell’; ‘basis’, ‘length_and_angles’; ‘niggli_matrix’; ‘metric’; all of: a,b,c, alpha, beta, gamma. (cell requires a Cell object or a very specific format, so unless you know what you are doing, use one of the others.)

  • ONE OF: ‘assignments’, ‘atomic_numbers’, ‘occupancies’ (assignments requires an Assignments object or a sequence.), occupations repeats similar site assignments as needed

  • ONE OF: ‘rc_sites’, ‘rc_coords’ (IF rc_occupations OR rc_counts are also given), ‘uc_coords’ (IF uc_occupations OR uc_counts are also given) ‘rc_B_C’, where B=reduced or cartesian, C=coordgroups, coords, or occupationscoords

    Notes:

    • occupationscoords may differ from coords by order, since giving occupations as, e.g., [‘H’,’O’,’H’] does not necessarily have the same order of the coordinates as the format of counts+coords as (2,1), [‘H’,’O’].

    • rc_sites and uc_sites requires a Sites object or a very specific format, so unless you know what you are doing, use one of the others.)

  • ONE OF: scale or volume:

    scale = multiply the basis vectors with this scaling factor, volume = the representative (conventional) cell volume (overrides ‘scale’ if both are given) volume_per_atom = cell volume / number of atoms

  • ONE OF periodicity or nonperiodic_vecs

See help(Structure) for more information on the data format of all these data representations.

formula_builder
property pbc
property rc_a
property rc_alpha
property rc_b
property rc_basis
property rc_beta
property rc_c
property rc_cartesian_coordgroups
property rc_cartesian_coords
property rc_cartesian_occupationscoords
property rc_cell_orientation
property rc_gamma
property rc_lengths_and_angles
property rc_volume
property uc_volume_per_atom
classmethod use(other)[source]
class httk.atomistic.Structure(assignments, rc_sites=None, rc_cell=None, other_reps=None)[source]

Bases: HttkObject

A Structure represents N sites of, e.g., atoms or ions, in any periodic or non-periodic arrangement. The structure object is meant to be immutable and assumes that no internal variables are changed after its creation. All methods that ‘changes’ the object creates and returns a new, updated, structure object.

This is the general heavy weight structure object. For lightweight structure objects, use UnitcellStructure or RepresentativeStructure.

Naming conventions in httk.atomistic:

Structure cell type abbreviations:
rc = Representative cell: only representative atoms are given inside the conventional cell.

they need to be replicated by the symmetry elements.

uc = Unit cell: any (imprecisely defined) unit cell (usually the unit cell used to define the structure

if it was not done via a representative cell.) with all atoms inside.

pc = Primitive unit cell: a smallest possible unit cell (the standard one) with all atoms inside.

cc = Conventional unit cell: the high symmetry unit cell (rc) with all atoms inside.

For cells:
cell = an abstract name for any reasonable representation of a ‘cell’ that defines

the basis vectors used for representing the structure. When a ‘cell’ is returned, it is an object of type Cell

basis = a 3x3 sequence-type with (in rows) the three basis vectors (for a periodic system, defining the unit cell, and defines the unit of repetition for the periodic dimensions)

lengths_and_angles = (a,b,c,alpha,beta,gamma): the basis vector lengths and angles

niggli_matrix = ((v1*v1, v2*v2, v3*v3),(2*v2*v3, 2*v1*v3, 2*v2*v3)) where v1, v2, v3 are the vectors forming the basis

metric = ((v1*v1,v1*v2,v1*v3),(v2*v1,v2*v2,v2*v3),(v3*v1,v3*v2,v3*v3))

For sites:
These following prefixes are used to describe types of site specifications:

representative cell/rc = only representative atoms are given, which are then to be repeated by structure symmetry group to give all sites

unit cell/uc = all atoms in unitcell

reduced = coordinates given in cell vectors

cartesian = coordinates given as direct cartesian coordinates

sites = used as an abstract name for any sensible representation of a list of coordinates and a cell,

when a ‘sites’ is returned, it is an object of type Sites

counts = number of atoms of each type (one per entry in assignments)

coordgroups = coordinates represented as a 3-level-list of coordinates, e.g. [[[0,0,0],[0.5,0.5,0.5]],[[0.25,0.25,0.25]]] where level-1 list = groups: one group for each equivalent atom

counts and coords = one list with the number of atoms of each type (one per entry in assignments) and a 2-level list of coordinates.

For assignments of atoms, etc. to sites:

assignments = abstract name for any representation of assignment of atoms. When returned, will be object of type Assignment.

atomic_numbers = a sequence of integers for the atomic number of each species

occupations = a sequence where the assignments are repeated for each coordinate as needed (prefixed with uc or rc depending on which coordinates)

For cell scaling:

scaling = abstract name for any representation of cell scaling

scale = multiply all basis vectors with this number

volume = rescaling the cell such that it takes this volume

For periodicity:

periodicity = abstract name of a representation of periodicity

pbc = ‘periodic boundary conditions’ = sequence of True and False for which basis vectors are periodic / non-periodic

nonperiodic_vecs = integer, number of basis vectors, counted from the first, which are non-periodic

For spacegroup:

spacegroup = abstract name for any spacegroup representation. When returned, is of type Spacegroup.

hall_symbol = specifically the hall_symbol string representation of the spacegroup

add_ref(ref)[source]
add_refs(refs)[source]
add_tag(tag, val)[source]
add_tags(tags)[source]
property anonymous_formula
property anonymous_wyckoff_sequence
property cc
property cc_formula_parts
clean()[source]
classmethod create(structure=None, assignments=None, rc_cell=None, rc_basis=None, rc_lengths=None, rc_angles=None, rc_cosangles=None, rc_niggli_matrix=None, rc_metric=None, rc_a=None, rc_b=None, rc_c=None, rc_alpha=None, rc_beta=None, rc_gamma=None, rc_sites=None, rc_reduced_coordgroups=None, rc_cartesian_coordgroups=None, rc_reduced_coords=None, rc_cartesian_coords=None, rc_reduced_occupationscoords=None, rc_cartesian_occupationscoords=None, rc_occupancies=None, rc_counts=None, wyckoff_symbols=None, multiplicities=None, spacegroup=None, hall_symbol=None, spacegroupnumber=None, setting=None, rc_scale=None, rc_scaling=None, rc_volume=None, uc_cell=None, uc_basis=None, uc_lengths=None, uc_angles=None, uc_cosangles=None, uc_niggli_matrix=None, uc_metric=None, uc_a=None, uc_b=None, uc_c=None, uc_alpha=None, uc_beta=None, uc_gamma=None, uc_sites=None, uc_reduced_coordgroups=None, uc_cartesian_coordgroups=None, uc_reduced_coords=None, uc_cartesian_coords=None, uc_reduced_occupationscoords=None, uc_cartesian_occupationscoords=None, uc_occupancies=None, uc_counts=None, uc_scale=None, uc_scaling=None, uc_volume=None, uc_is_primitive_cell=False, uc_is_conventional_cell=False, volume_per_atom=None, periodicity=None, nonperiodic_vecs=None, refs=None, tags=None)[source]

A Structure represents N sites of, e.g., atoms or ions, in any periodic or non-periodic arrangement.

This is a swiss-army-type constructor that allows a selection between a large number of optional arguments.

Note: if redundant and non-compatible information is given, the behavior is undefined. E.g., don’t try to call this with a structure + a volume in hopes to get a copy with rescaled volume.

To create a new structure, three primary components are:
  • cell: defines the basis vectors in which reduced coordinates are expressed, and the

    unit of repetition (if the structure has any periodicity - see the ‘periodicity’ parameter)

  • assignments: a list of ‘things’ (atoms, ions, etc.) that goes on the sites in the structure

  • sites: a sensible representation of location / coordinates of the sites.

Note: rc_-prefixes are consistently enforced for any quantity that would be different in a UnitcellStructure. This is to allow for painless change between the various structure-type objects without worrying about accidently using the wrong type of sites object.

Input parameters:

  • ONE OF: ‘cell’; ‘basis’, ‘length_and_angles’; ‘niggli_matrix’; ‘metric’; all of: a,b,c, alpha, beta, gamma. (cell requires a Cell object or a very specific format, so unless you know what you are doing, use one of the others.)

  • ONE OF: ‘assignments’, ‘atomic_numbers’, ‘occupancies’ (assignments requires an Assignments object or a sequence.), occupations repeats similar site assignments as needed

  • ONE OF: ‘rc_sites’, ‘rc_coords’ (IF rc_occupations OR rc_counts are also given), ‘uc_coords’ (IF uc_occupations OR uc_counts are also given) ‘rc_B_C’, where B=reduced or cartesian, C=coordgroups, coords, or occupationscoords

    Notes:

    • occupationscoords may differ from coords by order, since giving occupations as, e.g., [‘H’,’O’,’H’] does not necessarily have the same order of the coordinates as the format of counts+coords as (2,1), [‘H’,’O’].

    • rc_sites and uc_sites requires a Sites object or a very specific format, so unless you know what you are doing, use one of the others.)

  • ONE OF: scale or volume:

    scale = multiply the basis vectors with this scaling factor, volume = the representative (conventional) cell volume (overrides ‘scale’ if both are given) volume_per_atom = cell volume / number of atoms

  • ONE OF periodicity or nonperiodic_vecs

See help(Structure) for more information on the data format of all these data representations.

property element_wyckoff_sequence
property extended
property extensions
find_symmetry()[source]
property formula
property formula_counts
property formula_spaceseparated
property formula_symbols
get_refs()[source]
get_tag(tag)[source]
get_tags()[source]
property hall_symbol
property has_rc_repr

Returns True if the structure already contains the representative coordinates + spacegroup, and thus can be queried for this data without launching an expensive symmetry finder operation.

property has_uc_repr

Returns True if the structure contains any unit cell-type coordinate representation, and thus can be queried for this data without launching a somewhat expensive cell filling operation.

io
property number_of_elements
property pbc
property pc
property pc_a
property pc_alpha
property pc_b
property pc_beta
property pc_c
property pc_counts
property pc_formula_parts
property pc_gamma
property pc_nbr_atoms
property pc_volume
property rc
property rc_a
property rc_alpha
property rc_b
property rc_basis
property rc_beta
property rc_c
property rc_cartesian_coordgroups
property rc_cartesian_coords
property rc_cartesian_occupationscoords
property rc_cell_orientation
property rc_counts
property rc_gamma
property rc_lengths_and_angles
property rc_nbr_atoms
property rc_occupancies
property rc_occupationssymbols
property rc_reduced_coordgroups
property rc_reduced_coords
property rc_volume
property spacegroup
property spacegroup_number
property spacegroup_number_and_setting
supercell
property symbols
tidy()[source]
transform(matrix, max_search_cells=20, max_atoms=5000, force_hall_symbol=None)[source]
property uc
property uc_a
property uc_alpha
property uc_b
property uc_basis
property uc_beta
property uc_c
property uc_cartesian_coordgroups
property uc_cartesian_coords
property uc_cartesian_occupationscoords
property uc_cell
property uc_cell_orientation
property uc_counts
property uc_formula
property uc_formula_counts
property uc_formula_parts
property uc_formula_symbols
property uc_gamma
property uc_lengths_and_angles
property uc_nbr_atoms
property uc_occupancies
property uc_occupationssymbols
property uc_reduced_coordgroups
property uc_reduced_coords
property uc_reduced_occupationscoords
property uc_sites
property uc_volume
classmethod use(other)[source]
property volume_per_atom
property wyckoff_sequence
class httk.atomistic.StructurePhaseDiagram(structures, energies, hull_indices, competing_indices, hull_competing_indices, hull_distances, coord_system, phase_lines)[source]

Bases: HttkObject

Represents a phase diagram of structures

classmethod create(structures, energies)[source]
get_phasediagram()[source]
class httk.atomistic.StructureRef(structure, reference)[source]

Bases: HttkObject

class httk.atomistic.StructureTag(structure, tag, value)[source]

Bases: HttkObject

class httk.atomistic.UnitcellSites(reduced_coordgroups=None, reduced_coords=None, counts=None, hall_symbol='P 1', pbc=None)[source]

Bases: Sites

Represents any collection of sites in a unitcell

property total_number_of_atoms
class httk.atomistic.UnitcellStructure(assignments=None, uc_sites=None, uc_cell=None)[source]

Bases: HttkObject

A UnitcellStructure represents N sites of, e.g., atoms or ions, in any periodic or non-periodic arrangement. It keeps track of all the copies of the atoms within a unitcell.

The structure object is meant to be immutable and assumes that no internal variables are changed after its creation. All methods that ‘changes’ the object creates and returns a new, updated, structure object.

Naming conventions in httk.atomistic:

For cells:
cell = an abstract name for any reasonable representation of a ‘cell’ that defines

the basis vectors used for representing the structure. When a ‘cell’ is returned, it is an object of type Cell

basis = a 3x3 sequence-type with (in rows) the three basis vectors (for a periodic system, defining the unit cell, and defines the unit of repetition for the periodic dimensions)

lengths_and_angles = (a,b,c,alpha,beta,gamma): the basis vector lengths and angles

niggli_matrix = ((v1*v1, v2*v2, v3*v3),(2*v2*v3, 2*v1*v3, 2*v2*v3)) where v1, v2, v3 are the vectors forming the basis

metric = ((v1*v1,v1*v2,v1*v3),(v2*v1,v2*v2,v2*v3),(v3*v1,v3*v2,v3*v3))

For sites:
These following prefixes are used to describe types of site specifications:

representative cell/rc = only representative atoms are given, which are then to be repeated by structure symmetry group to give all sites

unit cell/uc = all atoms in unitcell

reduced = coordinates given in cell vectors

cartesian = coordinates given as direct cartesian coordinates

sites = used as an abstract name for any sensible representation of a list of coordinates and a cell,

when a ‘sites’ is returned, it is an object of type Sites

counts = number of atoms of each type (one per entry in assignments)

coordgroups = coordinates represented as a 3-level-list of coordinates, e.g. [[[0,0,0],[0.5,0.5,0.5]],[[0.25,0.25,0.25]]] where level-1 list = groups: one group for each equivalent atom

counts and coords = one list with the number of atoms of each type (one per entry in assignments) and a 2-level list of coordinates.

For assignments of atoms, etc. to sites:

assignments = abstract name for any representation of assignment of atoms. When returned, will be object of type Assignment.

atomic_numbers = a sequence of integers for the atomic number of each species

occupations = a sequence where the assignments are repeated for each coordinate as needed (prefixed with uc or rc depending on which coordinates)

For cell scaling:

scaling = abstract name for any representation of cell scaling

scale = multiply all basis vectors with this number

volume = rescaling the cell such that it takes this volume

For periodicity:

periodicity = abstract name of a representation of periodicity

pbc = ‘periodic boundary conditions’ = sequence of True and False for which basis vectors are periodic / non-periodic

nonperiodic_vecs = integer, number of basis vectors, counted from the first, which are non-periodic

For spacegroup:

spacegroup = abstract name for any spacegroup representation. When returned, is of type Spacegroup.

hall_symbol = specifically the hall_symbol string representation of the spacegroup

classmethod create(structure=None, uc_cell=None, uc_basis=None, uc_lengths=None, uc_angles=None, uc_niggli_matrix=None, uc_metric=None, uc_a=None, uc_b=None, uc_c=None, uc_alpha=None, uc_beta=None, uc_gamma=None, uc_sites=None, uc_reduced_coordgroups=None, uc_cartesian_coordgroups=None, uc_reduced_coords=None, uc_cartesian_coords=None, uc_reduced_occupationscoords=None, uc_cartesian_occupationscoords=None, uc_occupancies=None, uc_counts=None, uc_scale=None, uc_scaling=None, uc_volume=None, volume_per_atom=None, assignments=None, periodicity=None, nonperiodic_vecs=None, other_reps=None, refs=None, tags=None)[source]

A FullStructure represents N sites of, e.g., atoms or ions, in any periodic or non-periodic arrangement, where the positions of all cites are given (as opposed to a set of unique sites + symmetry operations).

This is a swiss-army-type constructor that allows several different ways to create a FullStructure object.

To create a new structure, three primary components are:

  • cell: defines the basis vectors in which reduced coordinates are expressed, and the unit of repetition (if the structure has any periodicity - see the ‘periodicity’ parameter)

  • assignments: a list of ‘things’ (atoms, ions, etc.) that goes on the sites in the structure

  • sites: a sensible representation of location / coordinates of the sites.

Note: uc_-prefixes are consistently enforced for any quantity that would be different in a UniqueSitesStructure. This is to allow for painless change between the various structure-type objects without worrying about accidently using the wrong type of sites object.

Note: see help(Structure) for parameter naming conventions, i.e., what type of object is expected given a parameter name.

Input parameters:

  • ONE OF: ‘uc_cell’; ‘uc_basis’, ‘uc_length_and_angles’; ‘uc_niggli_matrix’; ‘uc_metric’; all of: uc_a,uc_b,uc_c, uc_alpha, uc_beta, uc_gamma. (cell requires a Cell object or a very specific format, so unless you know what you are doing, use one of the others.)

  • ONE OF: ‘uc_assignments’, ‘uc_atomic_numbers’, ‘uc_occupations’ (uc_assignments requires an Assignments object or a sequence.), uc_occupations repeats similar site assignments as needed

  • ONE OF: ‘uc_sites’, ‘uc_coords’ (IF uc_occupations OR uc_counts are also given), or ‘uc_B_C’, where B=reduced or cartesian, C=coordgroups, coords, or occupationscoords

    Notes:

    • occupationscoords may differ from coords by order, since giving occupations as, e.g., [‘H’,’O’,’H’] does not necessarily have the same order of the coordinates as the format of counts+coords as (2,1), [‘H’,’O’].

    • uc_sites requires a Sites object or a python list on a very specific format, (so unless you know what you are doing, use one of the others.)

  • ONE OF: uc_scale, uc_volume, or volume_per_atom:

    scale = multiply the basis vectors with this scaling factor, volume = the unit cell volume (overrides ‘scale’ if both are given) volume_per_atom = cell volume / number of atoms

  • ONE OF periodicity or nonperiodic_vecs

formula_builder
property pbc
supercell
transform(matrix, max_search_cells=20, max_atoms=10000)[source]
property uc_a
property uc_alpha
property uc_b
property uc_basis
property uc_beta
property uc_c
property uc_cartesian_coordgroups
property uc_cartesian_coords
property uc_cartesian_occupationscoords
property uc_cell_orientation
property uc_counts
property uc_gamma
property uc_lengths_and_angles
property uc_reduced_coordgroups
property uc_reduced_coords
property uc_volume
property uc_volume_per_atom
classmethod use(other)[source]

Subpackages

Submodules