local_moment

py4vasp.calculation.local_moment

(*args, **kwargs)

The local moments describe the charge and magnetization near an atom.

The projection on local moments is particularly relevant in the context of magnetic materials. It analyzes the electronic states in the vicinity of an atom by projecting the electronic orbitals onto the localized projectors of the PAWs. The local moments help understanding the magnetic ordering, the spin polarization, and the influence of neighboring atoms on the magnetic behavior.

This class allows to access the computed moments from a VASP calculation. Remember that VASP calculates the projections only if you need to set LORBIT in the INCAR file. If the system is computed without spin polarization, the resulting moments correspond only to the local charges resolved by angular momentum. For collinear calculation, additionally the magnetic moment are computed. In noncollinear calculations, the magnetization becomes a vector. When comparing the results extracted from VASP to experimental observation, please be aware that the finite size of the radius in the projection may influence the observed moments. Hence, there is no one-to-one correspondence to the experimental moments.

Examples

Let us create some example data so that we can illustrate how to use this class. Of course you can also use your own VASP calculation data if you have it available.

>>> from py4vasp import demo
>>> calculation = demo.calculation(path, "collinear")

If you access the local moments, the result will depend on the steps that you selected with the [] operator. Without any selection the results from the final step will be used.

>>> calculation.local_moment.number_steps()
1

To select the results for all steps, you don’t specify the array boundaries.

>>> calculation.local_moment[:].number_steps()
4

You can also select specific steps or a subset of steps as follows

>>> calculation.local_moment[3].number_steps()
1
>>> calculation.local_moment[1:4].number_steps()
3

charge

() → np.ndarray

Read the site-projected charges of the selected steps.

Returns

np.ndarray
Contains the charges for the selected steps projected on atoms. Equivalent to summing the projected charges over the orbitals.

Examples

First we create some example data so that we can illustrate how to use this method. Of course you can also use your own VASP calculation data if you have it available.

>>> from py4vasp import demo
>>> calculation = demo.calculation(path, "collinear")

If you use the charge method, the result will depend on the steps that you selected with the [] operator. Without any selection the results from the final step will be used.

>>> calculation.local_moment.charge()
array([...])

To select the results for all steps, you don’t specify the array boundaries. Notice that in this case the charge contains an additional dimension for the different steps.

>>> calculation.local_moment[:].charge()
array([[...]])

The charge is equivalent to summing the projected charges over the orbitals

>>> np.allclose(calculation.local_moment.charge(),
...     calculation.local_moment.projected_charge().sum(axis=-1))
True

length_moments

= 1.5
Length in Å how a magnetic moment is displayed relative to the largest moment.

magnetic

(selection: str = ’total’) → np.ndarray

Read the site-projected magnetic moments of the selected steps.

Be careful when comparing the magnetic moments to experimental data. The finite size of the projection sphere may influence the observed moments. Hence, there is no one-to-one correspondence to the experimental moments.

Parameters

selection: str = ’total'
If VASP was run with LORBMOM = T, the orbital moments are computed and the routine will default to the total moments. You can specify “spin” or “orbital” to select the individual contributions instead.

Returns

np.ndarray
Contains the magnetic moments for the selected steps projected on atoms. Equivalent to summing the projected magnetic moments over the orbitals.

Notes

The index order is different compared to the raw data when noncollinear calculations are used. This routine returns the magnetic moments as (steps, orbitals, atoms, directions).

Examples

First we create some example data so that we can illustrate how to use this method. Of course you can also use your own VASP calculation data if you have it available.

>>> from py4vasp import demo
>>> collinear_calculation = demo.calculation(path, "collinear")
>>> noncollinear_calculation = demo.calculation(path, "noncollinear")

If you use the magnetic method, the result will depend on the steps that you selected with the [] operator. Without any selection the results from the final step will be used.

>>> collinear_calculation.local_moment.magnetic()
array([...])

To select the results for all steps, you don’t specify the array boundaries.

>>> collinear_calculation.local_moment[:].magnetic()
array([[...]])

You can also select specific steps or a subset of steps as follows

>>> collinear_calculation.local_moment[2].magnetic()
array([...])
>>> collinear_calculation.local_moment[0:3].magnetic()
array([[...]])

To select the results for all steps, you don’t specify the array boundaries.

>>> collinear_calculation.local_moment[:].magnetic()
array([[...]])

For noncollinear calculations, the magnetic moments are aligned according to the spin axis (SAXIS). Since the moments are now vectors, the result has an additional dimension for the different directions.

>>> noncollinear_calculation.local_moment.magnetic()
array([[...]])

You can also select spin or orbital moments separately.

>>> noncollinear_calculation.local_moment.magnetic(selection="spin")
array([[...]])

The magnetic moment is equivalent to summing the projected magnetic moments over the orbitals

>>> np.allclose(collinear_calculation.local_moment.magnetic(),
...     collinear_calculation.local_moment.projected_magnetic().sum(axis=-1))
True

number_steps

()
Return the number of local moments in the trajectory.

path

Returns the path from which the output is obtained.

plot

(*args, **kwargs) → View

Wrapper around to_view() method.

This method will visualize the quantity in the structure. Please refer to the to_view() method for a documentation of the allowed arguments.

Returns

View
A visualization of the quantity within the crystal structure.

print

()
Print a string representation of this instance.

projected_charge

() → np.ndarray

Read the orbital- and site-projected charges of the selected steps.

Returns

np.ndarray
Contains the charges for the selected steps projected on atoms and orbitals.

Examples

First we create some example data so that we can illustrate how to use this method. Of course you can also use your own VASP calculation data if you have it available.

>>> from py4vasp import demo
>>> calculation = demo.calculation(path, "collinear")

If you use the projected_charge method, the result will depend on the steps that you selected with the [] operator. Without any selection the results from the final step will be used.

>>> calculation.local_moment.projected_charge()
array([[...]])

To select the results for all steps, you don’t specify the array boundaries. Notice that in this case the charge contains an additional dimension for the different steps.

>>> calculation.local_moment[:].projected_charge()
array([[[...]]])

projected_magnetic

(selection: str = ’total’) → np.ndarray

Read the orbital- and site-projected magnetic moments of the selected steps.

Parameters

selection: str = ’total'
If VASP was run with LORBMOM = T, the orbital moments are computed and the routine will default to the total moments. You can specify “spin” or “orbital” to select the individual contributions instead.

Returns

np.ndarray
Contains the magnetic moments for the selected steps projected on atoms and orbitals.

Notes

The index order is different compared to the raw data when noncollinear calculations are used. This routine returns the magnetic moments as (steps, orbitals, atoms, directions).

Examples

First we create some example data so that we can illustrate how to use this method. Of course you can also use your own VASP calculation data if you have it available.

>>> from py4vasp import demo
>>> collinear_calculation = demo.calculation(path, "collinear")
>>> noncollinear_calculation = demo.calculation(path, "noncollinear")

If you use the projected_magnetic method, the result will depend on the steps that you selected with the [] operator. Without any selection the results from the final step will be used.

>>> collinear_calculation.local_moment.projected_magnetic()
array([[...]])

To select the results for all steps, you don’t specify the array boundaries.

>>> collinear_calculation.local_moment[:].projected_magnetic()
array([[[...]]])

You can also select specific steps or a subset of steps as follows

>>> collinear_calculation.local_moment[2].projected_magnetic()
array([[...]])
>>> collinear_calculation.local_moment[0:3].projected_magnetic()
array([[[...]]])

To select the results for all steps, you don’t specify the array boundaries.

>>> collinear_calculation.local_moment[:].projected_magnetic()
array([[[...]]])

For noncollinear calculations, the magnetic moments are aligned according to the spin axis (SAXIS). Since the moments are now vectors, the result has an additional dimension for the different directions.

>>> noncollinear_calculation.local_moment.projected_magnetic()
array([[[...]]])

You can also select spin or orbital moments separately.

>>> noncollinear_calculation.local_moment.projected_magnetic(selection="spin")
array([[[...]]])

read

(*args, **kwargs)
Convenient wrapper around to_dict. Check that function for examples and optional arguments.

selections

() → dict

Returns possible alternatives for this particular quantity VASP can produce.

The returned dictionary contains a single item with the name of the quantity mapping to all possible selections. Each of these selection may be passed to other functions of this quantity to select which output of VASP is used. Some quantities provide additional elements which can be passed as selection for other routines.

Returns

dict
The key indicates this quantity and the values possible choices for arguments to other functions of this quantity.

to_dict

() → dict

Read the charges and magnetization data into a dictionary.

Be careful when comparing the magnetic moments to experimental data. The finite size of the projection sphere may influence the observed moments. Hence, there is no one-to-one correspondence to the experimental moments.

Returns

dict
Contains the charges and magnetic moments generated by VASP projected on atoms and orbitals.

Notes

The index order is different compared to the raw data when noncollinear calculations are used. This routine returns the magnetic moments as (steps, orbitals, atoms, directions).

Examples

First we create some example data so that we can illustrate how to use this method. Of course you can also use your own VASP calculation data if you have it available.

>>> from py4vasp import demo
>>> collinear_calculation = demo.calculation(path, "collinear")
>>> noncollinear_calculation = demo.calculation(path, "noncollinear")

If you use the to_dict method, the result will depend on the steps that you selected with the [] operator. Without any selection the results from the final step will be used.

>>> collinear_calculation.local_moment.to_dict()
{'orbital_projection': ['s', 'p', 'd'], 'charge': array([[...]]),
    'total': array([[...]])}

To select the results for all steps, you don’t specify the array boundaries. Notice that in this case the charge and the total moment contain an additional dimension for the different steps.

>>> collinear_calculation.local_moment[:].to_dict()
{'orbital_projection': ['s', 'p', 'd'], 'charge': array([[[...]]]),
    'total': array([[[...]]])}

You can also select specific steps or a subset of steps as follows

>>> collinear_calculation.local_moment[2].to_dict()
{'orbital_projection': ['s', 'p', 'd'], 'charge': array([[...]]),
    'total': array([[...]])}
>>> collinear_calculation.local_moment[0:3].to_dict()
{'orbital_projection': ['s', 'p', 'd'], 'charge': array([[[...]]]),
    'total': array([[[...]]])}

For noncollinear calculations, the magnetic moments are vectors. In addition, if the calculation was run with LORBMOM = T, orbital and spin moments are reported separately.

>>> noncollinear_calculation.local_moment.to_dict()
{'orbital_projection': ['s', 'p', 'd'], 'charge': array([[...]]),
    'total': array([[[...]]]), 'spin': array([[[...]]]), 'orbital': array([[[...]]])}

to_ngl

(*args, **kwargs) → NGLWidget

Convert the view to an NGL widget.

This method wraps the to_view() method and converts the resulting View to an NGL widget. The to_view() method documents all the possible arguments of this function.

Returns

NGLWidget
A widget to display the structure and other quantities in the unit cell.

to_vasp_viewer

(*args, **kwargs) → VASPViewerWidget

Convert the view to a VASP Viewer widget.

This method wraps the to_view() method and converts the resulting View to a VASP Viewer widget. The to_view() method documents all the possible arguments of this function.

Returns

VASPViewerWidget
A widget to display the structure and other quantities in the unit cell.

to_view

(

  • selection: str = ’total',
  • supercell = None

) → View

Visualize the magnetic moments as arrows inside the structure.

Be aware that the magnetic moments are rescaled for better visibility. The length of the largest moment is set to length_moments. If your moments are vanishingly small, this may lead to unexpectedly large arrows. Please double check the actual values with magnetic().

Parameters

selection: str = ’total'
If VASP was run with LORBMOM = T, the orbital moments are computed and the routine will default to the total moments. You can specify “spin” or “orbital” to select the individual contributions instead.

Returns

View
Contains the atoms and the unit cell as well as an arrow indicating the strength of the magnetic moment. If noncollinear magnetism is used the moment points in the actual direction; for collinear magnetism the moments are aligned along the z axis by convention.

Examples

First we create some example data so that we can illustrate how to use this method. Of course you can also use your own VASP calculation data if you have it available.

>>> from py4vasp import demo
>>> collinear_calculation = demo.calculation(path, "collinear")
>>> noncollinear_calculation = demo.calculation(path, "noncollinear")

If you use the to_view method, the result will depend on the steps that you selected with the [] operator. Without any selection the results from the final step will be used.

>>> collinear_calculation.local_moment.to_view()
View(..., ion_arrows=[IonArrow(quantity=array([[[...]]]), label='total moments', ...)], ...)

For collinear calculations, the magnetic moments are scalars aligned along the z axis. You can see this from the arrows pointing either up or down or x and y components being zero.

To select the results for all steps, you don’t specify the array boundaries.

>>> collinear_calculation.local_moment[:].to_view()
View(..., ion_arrows=[IonArrow(quantity=array([[[...]]]), label='total moments', ...)], ...)

You can also select specific steps or a subset of steps as follows

>>> collinear_calculation.local_moment[2].to_view()
View(..., ion_arrows=[IonArrow(quantity=array([[[...]]]), label='total moments', ...)], ...)
>>> collinear_calculation.local_moment[0:3].to_view()
View(..., ion_arrows=[IonArrow(quantity=array([[[...]]]), label='total moments', ...)], ...)

For noncollinear calculations, the magnetic moments are aligned according to the spin axis (SAXIS). The view has the same interface, but the arrows now point in the actual direction of the magnetic moments.

>>> noncollinear_calculation.local_moment.to_view()
View(..., ion_arrows=[IonArrow(quantity=array([[[...]]]), label='total moments', ...)], ...)

You can also select spin or orbital moments separately.

>>> noncollinear_calculation.local_moment.to_view(selection="spin, orbital")
View(..., ion_arrows=[IonArrow(quantity=array([[[...]]]), label='spin moments', ...),
    IonArrow(quantity=array([[[...]]]), label='orbital moments', ...)], ...)