magnon.magnons
==============

.. py:module:: magnon.magnons


Classes
-------

.. autoapisummary::

   magnon.magnons.MagnonSpectrum


Functions
---------

.. autoapisummary::

   magnon.magnons._single_q_energy_worker


Module Contents
---------------

.. py:class:: MagnonSpectrum(atoms, interactions, calc=None, supercell = (1, 1, 1), name = None, num_threads = 1, **kwargs)

   A class to build and diagonalize the Linear Spin Wave Hamiltonian from exchange interactions.

   :param atoms: The Atoms object of the system to which the magnon spectrum pertains.
   :type atoms: ase.Atoms object
   :param interactions: The InteractionList object of the exchange interactions to use for the spectrum calculation.
   :type interactions: magnon.interactions.InteractionList object
   :param num_threads: The number of threads to use for parallel calculations.
   :type num_threads: int

   :param mag_order_vect: Wavevector for Q-commensurate spin vector ordering.
   :type mag_order_vect: numpy.ndarray, dtype: float
   :param mag_order_axis: The rotation axis around which the Q-commensurate spin vector ordering rotations are to occur
   :type mag_order_axis: numpy.ndarray, dtype: float
   :param ham_prefactor: Choice of Hamiltonian prefactor convention.
   :type ham_prefactor: float
   :param spins_are_unit: Whether to use the unit spin model, or dimensionful spins.
   :type spins_are_unit: bool
   :param supercell: Size of the calculation cell with respect to the primitive cell
   :type supercell: array-like
   :param name: The name of the calculation
   :type name: str

   .. attribute:: u

      The u vectors for each site. See :func:`magnon.magnons.MagnonSpectrum._generate_uv_vectors`.

      :type: numpy.ndarray, dtype: float

   .. attribute:: v

      The v vectors for each site. See :func:`magnon.magnons.MagnonSpectrum._generate_uv_vectors`.

      :type: numpy.ndarray, dtype: float

   .. attribute:: S

      Spin quantum numbers.

      :type: numpy.ndarray, dtype: float

   .. attribute:: usm_factors

      Unit spin model conversion factors.

      :type: numpy.ndarray, dtype: float

   .. seealso:: :obj:`This`


   .. py:attribute:: _num_threads
      :value: 1



   .. py:attribute:: interactions


   .. py:attribute:: atoms


   .. py:attribute:: cell_vectors
      :value: None



   .. py:attribute:: interaction_matrix
      :value: None



   .. py:attribute:: calc
      :value: None



   .. py:attribute:: name
      :value: None



   .. py:attribute:: supercell
      :value: (1, 1, 1)



   .. py:attribute:: spin


   .. py:method:: _build_interaction_matrix()


   .. py:method:: _generate_uv_vectors(spin_vectors)
      :staticmethod:


      Compute u and v vectors from spin orientation vectors for LSWT calculation



   .. py:method:: calculate_eigen_energy(k)

      Compute the eigenvalues of the Hamiltonian at wavevector k. The Hamiltonian in the rotated frame approach [1]_ is built and
      diagonalized using the treatment for generalized quadratic bosonic Hamiltonians [2]_.

      :param k: Wavevector in reciprocal space.
      :type k: ndarray, shape (3,)

      :returns: **hamiltonian_eigs** -- Eigenvalues of the Bogoliubov-transformed Hamiltonian.
      :rtype: ndarray

      .. rubric:: References

      .. [1] S. Toth and B. Lake, J. Phys. Condens. Matter, 27, 166002 (2015)
      .. [2] J.H.P Colpa, Physica, 93A, 327-353 (1978)



   .. py:method:: get_band_structure(path)

      Gets the magnon bandstructure along a path given by an ASE BandPath object. This is a wrapper for `band_structure()`
      which enables handling of k-space paths and bandstructures using ASE objects.

      :param path: The path along which to compute the bandstructure.
      :type path: ASE.dft.kpoints.BandPath object

      :returns: An ASE BandStructure object containing the magnon bandstructure.
      :rtype: ase.spectrum.band_structure.BandStructure



   .. py:method:: band_structure(path_kc)

      Computes the bands energies for a set of reciprocal space points.

      :param path_kc: The reciprocal space path along which to compute the bandstructure, given in Cartesian coordinates.
      :type path_kc: array-like

      :returns: The band energies along the specified path.
      :rtype: numpy.ndarray



   .. py:method:: get_dos(kpts = (10, 10, 10))

      Computes the magnon density of states.

      :param kpts: The dimensions of the Monkhorst-Pack grid to sample.
      :type kpts: array-like, dtype=int

      :rtype: ase.spectrum.dosdata.RawDOSData object



.. py:function:: _single_q_energy_worker(args)

   Compute and return sorted real magnon energies at a k-point.

   This is a multiprocessing-friendly worker function for use with MagnonSpectrum.
   It must be defined at module level to be pickleable.


   :param args:
                Tuple of (instance, q_c) where:
                    instance : MagnonSpectrum
                        Instance of the MagnonSpectrum class.
                    q_c : array_like
                        k-point in scaled Cartesian coordinates.
   :type args: tuple

   :returns: **energies** -- Sorted real eigenvalues of the magnon Hamiltonian at the given k-point.
   :rtype: ndarray

   .. rubric:: Notes

   The k-point is converted to cartesian space (multiplied by 2*pi).
   Only the real parts of the eigenvalues are returned.