pwtools.crys.Structure

class pwtools.crys.Structure(set_all_auto=True, units=None, **kwds)[source]

Bases: UnitsHandler

Container class for representing a single crystal structure (unit cell + atoms).

Derived classes may add attributes and getters but the idea is that this class is the minimal API for how to pass an atomic structure around.

Units are supposed to be similar to ASE:

what

unit

SI

length

Angstrom

(1e-10 m)

energy

eV

(1.602176487e-19 J)

forces

eV / Angstrom

stress

GPa

(not eV/Angstrom**3)

temperature

K

velocity

Angstrom / fs

time

fs

(1e-15 s)

mass

amu

(1.6605387820000001e-27 kg)

Unit conversion factors, which are applied to input arguments for conversion to the above units can be given by the units input keyword.

Note that we cannot verify the unit of input args to the constructor, but all functions in this package, which use Structure / Trajectory as container classes, assume these units.

This class is very much like ase.Atoms, but without the “calculators”. You can use get_ase_atoms() to get an Atoms object or get_fake_ase_atoms() for a minimal Atoms-like object.

Examples

>>> symbols=['N', 'Al', 'Al', 'Al', 'N', 'N', 'Al']
>>> coords_frac=rand(len(symbols),3)
>>> cryst_const=np.array([5,5,5,90,90,90.0])
>>> st=Structure(coords_frac=coords_frac,
...              cryst_const=cryst_const,
...              symbols=symbols)
>>> st.symbols
['N', 'Al', 'Al', 'Al', 'N', 'N', 'Al']
>>> st.symbols_unique
['Al', 'N']
>>> st.order
{'Al': 1, 'N': 2}
>>> st.typat
[2, 1, 1, 1, 2, 2, 1]
>>> st.znucl_unique
[13, 7]
>>> st.nspecies
{'Al': 4, 'N': 3}
>>> st.coords
array([[ 1.1016541 ,  4.52833103,  0.57668453],
       [ 0.18088339,  3.41219704,  4.93127985],
       [ 2.98639824,  2.87207221,  2.36208784],
       [ 2.89717342,  4.21088541,  3.13154023],
       [ 2.28147351,  2.39398397,  1.49245281],
       [ 3.16196033,  3.72534409,  3.24555934],
       [ 4.90318748,  2.02974457,  2.49846847]])
>>> st.coords_frac
array([[ 0.22033082,  0.90566621,  0.11533691],
       [ 0.03617668,  0.68243941,  0.98625597],
       [ 0.59727965,  0.57441444,  0.47241757],
       [ 0.57943468,  0.84217708,  0.62630805],
       [ 0.4562947 ,  0.47879679,  0.29849056],
       [ 0.63239207,  0.74506882,  0.64911187],
       [ 0.9806375 ,  0.40594891,  0.49969369]])
>>> st.cryst_const
array([  5.,   5.,   5.,  90.,  90.,  90.])
>>> st.cell
array([[  5.00000000e+00,   0.00000000e+00,   0.00000000e+00],
       [  3.06161700e-16,   5.00000000e+00,   0.00000000e+00],
       [  3.06161700e-16,   3.06161700e-16,   5.00000000e+00]])
>>> st.get_ase_atoms(pbc=True)
Atoms(symbols='NAl3N2Al', positions=..., cell=[[2.64588604295, 0.0, 0.0],
[1.6201379367036871e-16, 2.64588604295, 0.0], [1.6201379367036871e-16,
1.6201379367036871e-16, 2.64588604295]], pbc=[True, True, True])
__init__(set_all_auto=True, units=None, **kwds)[source]
Parameters:
  • coords ((natoms, 3) [Ang]) – Cartesian coords. Optional if coords_frac given.

  • coords_frac ((natoms, 3)) – Fractional coords w.r.t. cell. Optional if coords given.

  • symbols (sequence of strings (natoms,)) – atom symbols

  • cell ((3,3)) – Unit cell vectors as rows. [Ang] Optional if cryst_const given.

  • cryst_const ((6,)) – [a,b,c,alpha,beta,gamma]; a,b,c in [Ang] Optional if cell given.

  • forces ((nstep,natoms,3)) – [eV/Ang]

  • stress ((nstep,3,3)) – stress tensor [GPa]

  • etot (float, optional) – total energy [eV]

  • units (optional, dict,) – see UnitsHandler

  • set_all_auto (optional, bool) – Call set_all() in __init__().

  • Trajectory (Only)

  • ekin ((nstep,)) – [eV]

  • forces – [eV/Ang]

  • pressure ((nstep,)) – [GPa]

  • stress – [GPa]

  • temperature ((nstep,)) – [K]

  • timestep (float) – [fs]

  • velocity ((nstep, natoms, 3)) – [Ang/fs]

  • volume ((nstep,)) – [Ang^3]

Notes

cell, cryst_constProvide either cell or cryst_const, or both

(which is redundant). If only one is given, the other is calculated from it. See {cell2cc,cc2cell}.

coords, coords_fracProvide either coords or coords_frac, or both

(which is redundant). If only one is given, the other is calculated from it. See coord_trans().

Methods

apply_units()

Like _apply_units_raw(), make sure that units are only applied once.

assert_attr(attr)

Raise AssertionError if self.<attr> is not set (is_set_attr() returns False.

assert_attr_lst(attr_lst)

assert_set_attr(attr)

Same as assert_attr(), but run try_set_attr() first.

assert_set_attr_lst(attr_lst)

check_set_attr(attr)

Run try_set_attr() and return the result of is_set_attr(), i.e. True or False.

check_set_attr_lst(attr_lst)

compress([forget, dtype])

Compress Trajectory by deleting unused or redundant attrs (see forget).

copy()

Return a copy of the inctance.

dump(dump_filename[, mkdir])

Write object to binary file using pickle.

get_ase_atoms(**kwds)

Return ASE Atoms object.

get_cell()

get_coords()

get_coords_frac()

get_cryst_const()

get_ekin()

ekin [eV]

get_etot()

Total anergy.

get_fake_ase_atoms()

FakeASEAtoms instance representing this Structure.

get_forces()

Forces.

get_mass()

1D array of atomic masses in amu (atomic mass unit 1.660538782e-27 kg as in periodic table).

get_mass_unique()

get_natoms()

get_nspecies()

Dict with number of atoms per species.

get_nstep()

get_ntypat()

Number of atomic species.

get_order()

Dict which maps symbols_unique to numbers, starting at 1.

get_pressure()

get_return_attr(attr_name)

Call try_set_attr() are return self.<attr_name> if set.

get_spglib()

Return spglib input tuple (cell, coords_frac, znucl).

get_stress()

Stress tensor

get_symbols()

List of atomic symbols.

get_symbols_unique()

List of unique atom symbols.

get_temperature()

[K]

get_time()

get_timestep()

get_traj(nstep)

Return a Trajectory object, where this Structure is copied nstep times.

get_typat()

List of atom type integers in self.order, same length as symbols.

get_velocity()

Calculate velocity from coords and timestep if velocity=None.

get_volume()

get_znucl()

All atomic numbers.

get_znucl_unique()

Unique atomic numbers.

init_attr_lst([attr_lst])

Set each self.<attr> in attr_lst to None.

is_set_attr(attr)

Check if self has the attribute self.<attr> and if it is _not_ None.

is_set_attr_lst(attr_lst)

load(dump_filename)

Load pickled object.

raw_return(attr_name)

Call try_set_attr(_<attr_name>_raw) and return it if set, else None.

raw_slice_get(attr_name, sl, axis)

Shortcut method:

set_all()

Extend arrays, apply units, call all getters.

set_attr_lst(attr_lst)

Set self.attr_lst and init each attr to None.

try_set_attr(attr)

If self.<attr> does not exist or is None, then invoke an appropirately named getter as if this command would be executed.

try_set_attr_lst(attr_lst)

update_units(units)

Update self.units dict from units.

Attributes

is_struct

is_traj

timeaxis