Structures

The Structure object is a collection of atoms in a periodic box. The mandatory inputs are the cell vectors of the box and the chemical species and Cartesian coordinates of the atoms. The atoms are automatically folded back into the primary cell, so the input coordinates don’t need to lie inside the box.

class flare.struc.Structure(cell: ndarray, species: Union[List[str], List[int]], positions: ndarray, mass_dict: dict = None, prev_positions: ndarray = None, species_labels: List[str] = None, forces=None, stds=None, energy: float = None)

Contains information about a periodic structure of atoms, including the periodic cell boundaries, atomic species, and coordinates.

Note that input positions are assumed to be Cartesian.

Parameters:

• cell (np.ndarray) – 3x3 array whose rows are the Bravais lattice vectors of the cell.
• species (List) – List of atomic species, which are represented either as integers or chemical symbols.
• positions (np.ndarray) – Nx3 array of atomic coordinates.
• mass_dict (dict) – Dictionary of atomic masses used in MD simulations.
• prev_positions (np.ndarray) – Nx3 array of previous atomic coordinates used in MD simulations.
• species_labels (List[str]) – List of chemical symbols. Used in the output file of on-the-fly runs.
• stds (np.ndarray) – Uncertainty associated with forces

as_dict() → dict

Returns structure as a dictionary; useful for serialization purposes.

Returns:Dictionary version of current structure Return type:dict

as_str() → str

Returns string dictionary serialization cast as string.

Returns:output of as_dict method cast as string Return type:str

static from_ase_atoms(atoms: ase.Atoms, cell=None) → flare.struc.Structure

From an ASE Atoms object, return a FLARE structure

Parameters:atoms (ASE Atoms object) – ASE Atoms object Returns:A FLARE structure from an ASE atoms object

static from_dict(dictionary: dict) → flare.struc.Structure

Assembles a Structure object from a dictionary parameterizing one.

Parameters:dictionary – dict describing structure parameters. Returns:FLARE structure assembled from dictionary

static from_file(file_name: str, format: str = '', as_trajectory: bool = False) → Union[flare.struc.Structure, List[flare.struc.Structure]]

Load a FLARE structure from a file or a series of FLARE structures :param file_name: :param format: :return:

static from_pmg_structure(structure: pymatgen Structure) → flare Structure

Returns Pymatgen structure as FLARE structure.

Parameters:structure (Pymatgen Structure) – Pymatgen Structure Returns:FLARE Structure

static get_cell_dot(cell_array)

Compute 3x3 array of dot products of cell vectors used to fold atoms back to the unit cell.

Returns:3x3 array of cell vector dot products. Return type:np.ndarray

indices_of_specie(specie: Union[int, str]) → List[int]

Return the indices of a given species within atoms of the structure.

Parameters:specie – Element to target, can be string or integer Returns:The indices in the structure at which this element occurs Return type:List[str]

is_valid(tolerance: float = 0.5) → bool

Plugin to pymatgen’s is_valid method to gauge if a structure has atoms packed too closely together, which is likely to cause unphysically large forces / energies or present convergence issues in DFT. :return:

static raw_to_relative(positions: ndarray, cell_transpose: ndarray, cell_dot_inverse: ndarray) → ndarray

Convert Cartesian coordinates to relative (fractional) coordinates, expressed in terms of the cell vectors set in self.cell.

Parameters:

• positions (np.ndarray) – Cartesian coordinates.
• cell_transpose (np.ndarray) – Transpose of the cell array.
• cell_dot_inverse (np.ndarray) – Inverse of the array of dot products of cell vectors.

Returns:

Relative positions.

Return type:

np.ndarray

static relative_to_raw(relative_positions: ndarray, cell_transpose_inverse: ndarray, cell_dot: ndarray) → ndarray

Convert fractional coordinates to raw (Cartesian) coordinates.

Parameters:

• relative_positions (np.ndarray) – fractional coordinates.
• cell_transpose_inverse (np.ndarray) – Transpose of the cell array.
• cell_dot (np.ndarray) – Dot products of cell vectors

Returns:

Cartesian positions.

Return type:

np.ndarray

to_pmg_structure()

Returns FLARE structure as a pymatgen structure.

Returns:Pymatgen structure corresponding to current FLARE structure

to_xyz(extended_xyz: bool = True, print_stds: bool = False, print_forces: bool = False, print_max_stds: bool = False, print_energies: bool = False, predict_energy=None, dft_forces=None, dft_energy=None, target_atoms=None, timestep=-1, write_file: str = '', append: bool = False) → str

Convenience function which turns a structure into an extended .xyz file; useful for further input into visualization programs like VESTA or Ovito. Can be saved to an output file via write_file.

Parameters:

• print_stds – Print the stds associated with the structure.
• print_forces –
• extended_xyz –
• print_max_stds –
• write_file –

Returns:

wrap_positions() → ndarray

Convenience function which folds atoms outside of the unit cell back into the unit cell. in_place flag controls if the wrapped positions are set in the class.

Returns:Cartesian coordinates of positions all in unit cell Return type:np.ndarray

flare.struc.get_unique_species(species: List[Any]) -> (typing.List, typing.List[int])

Returns a list of the unique species passed in, and a list of integers indexing them.

Parameters:species – Species to index uniquely Returns:List of the unique species, and integer indexes