projector¶

The projectors used for atom and orbital resolved quantities.

This is a utility class that facilitates projecting quantities such as the electronic band structure and the DOS on atoms and orbitals. As a user, you can investigate the available projections with the to_dict() or selections() methods. The former is useful for scripts, when you need to know which array index corresponds to which orbital or atom. The latter describes the available selections that you can use in the methods that project on orbitals or atoms.

class Index(atom: str | Selection, orbital: str | Selection, spin: str | Selection)¶

Helper class specifying which atom, orbital, and spin are selected.

atom: str | Selection¶

Label of the atom or a Selection object to read the corresponding data.

count(value, /)¶

Return number of occurrences of value.

index(value, start=0, stop=9223372036854775807, /)¶

Return first index of value.

Raises ValueError if the value is not present.

orbital: str | Selection¶

Label of the orbital or a Selection object to read the corresponding data.

spin: str | Selection¶

Label of the spin component or a Selection object to read the corresponding data.

parse_selection(selection='__all__')¶

Generate all possible indices where the projected information is stored.

Deprecated since version 0.8.0: This routine was mostly for internal use but is not needed anymore.

Given a string specifying which atoms, orbitals, and spin should be selected an iterable object is created that contains the indices compatible with the select.

Parameters:

selection (str) –

A string specifying the projection of the orbitals. There are four distinct possibilities:

• To specify the atom, you can either use its element name (Si, Al, …) or its index as given in the input file (1, 2, …). For the latter option it is also possible to specify ranges (e.g. 1:4).

• To select a particular orbital you can give a string (s, px, dxz, …) or select multiple orbitals by their angular momentum (s, p, d, f).

• For the spin, you have the options up, down, or total.

• If you used a different k-point mesh choose “kpoints_opt” or “kpoints_wan” to select them instead of the default mesh specified in the KPOINTS file.

You separate multiple selections by commas or whitespace and can nest them using parenthesis, e.g. Sr(s, p) or s(up), p(down). The order of the selections does not matter, but it is case sensitive to distinguish p (angular momentum l = 1) from P (phosphorus).

It is possible to add or subtract different components, e.g., a selection of “Ti(d) - O(p)” would project onto the d orbitals of Ti and the p orbitals of O and then compute the difference of these two selections.

If you are unsure about the specific projections that are available, you can use

>>> calc.projector.selections()

to get a list of all available ones.

Yields:

Iterable[Index] – Indices of the atom, the orbital and the spin compatible with a specific selection.

print()¶

Print a string representation of this instance.

project(selection, projections)¶

Select a certain subset of the given projections and return them with a suitable label.

Parameters:

• selection (str) –

  selection : str A string specifying the projection of the orbitals. There are four distinct possibilities:

  • To specify the atom, you can either use its element name (Si, Al, …) or its index as given in the input file (1, 2, …). For the latter option it is also possible to specify ranges (e.g. 1:4).

  • To select a particular orbital you can give a string (s, px, dxz, …) or select multiple orbitals by their angular momentum (s, p, d, f).

  • For the spin, you have the options up, down, or total.

  • If you used a different k-point mesh choose “kpoints_opt” or “kpoints_wan” to select them instead of the default mesh specified in the KPOINTS file.

  You separate multiple selections by commas or whitespace and can nest them using parenthesis, e.g. Sr(s, p) or s(up), p(down). The order of the selections does not matter, but it is case sensitive to distinguish p (angular momentum l = 1) from P (phosphorus).

  It is possible to add or subtract different components, e.g., a selection of “Ti(d) - O(p)” would project onto the d orbitals of Ti and the p orbitals of O and then compute the difference of these two selections.

  If you are unsure about the specific projections that are available, you can use

  >>> calc.projector.selections()
  

  to get a list of all available ones.

• projections (np.ndarray) – A data array where the first three indices correspond to spin, atom, and orbital, respectively. The selection will be parsed and mapped onto the corresponding dimension.

Returns:

Each selection receives a label describing its spin, atom, and orbital, where default choices are skipped. The value associated to the label contains the corresponding subsection of the projections array summed over all remaining spin components, atoms, and orbitals.

Return type:

dict

read(*args, **kwargs)¶

Convenient wrapper around to_dict. Check that function for examples and optional arguments.

select(atom='__all__', orbital='__all__', spin='__all__')¶

Map selection strings onto corresponding Selection objects.

Deprecated since version 0.8.0: This routine was mostly for internal use but is not needed anymore.

With the selection strings, you specify which atom, orbital, and spin component you are interested in.

Parameters:

• atom (str) – Element name or index of the atom in the input file of Vasp. If a range is specified (e.g. 1:3) a pointer to multiple indices will be created.

• orbital (str) – Character identifying the angular momentum of the orbital. You may select a specific one (e.g. px) or all of the same character (e.g. d).

• spin (str) – Select “up” or “down” for a specific spin component or “total” for the sum of both.

Returns:

Indices to access the selected projection from an array and an associated label.

Return type:

Index

selections()¶

Return a dictionary describing what options are available to specify the atom, orbital, and spin.

to_dict(selection=None, projections=None)¶

Return a map from labels to indices in the arrays produced by VASP.

Deprecated since version 0.8.0: Passing arguments to the read routine is deprecated. Please use the project method instead.

Parameters:

• selection (str or None) – Passed to the project method.

• projections (np.ndarray or None) – Passed to the project method.

Returns:

A dictionary containing three dictionaries for spin, atom, and orbitals. Each of those describes which indices VASP uses to store certain elements for projected quantities.

Return type:

dict