magnon.build
============

.. py:module:: magnon.build


Functions
---------

.. autoapisummary::

   magnon.build.cell_transformation
   magnon.build.build_primitive_cell
   magnon.build.convert_kpts


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

.. py:function:: cell_transformation(original_cell, new_cell)

   Computes the matrix transformation mapping from scaled coordinates in the original cell
   to scaled coordinates in the new cell.


   :param original_cell: The lattice vectors of the original cell with shape (3, 3).
   :type original_cell: numpy.ndarray, dtype float
   :param new_cell: The lattice vectors of the new cell with shape (3, 3).
   :type new_cell: numpy.ndarray, dtype float

   :returns: **transformation_matrix** -- The matrix transforming a point from the old to the new basis with shape (3, 3).
   :rtype: numpy.ndarray, dtype float

   .. seealso::

      :obj:`magnon.build.build_primitive_cell`
          Uses to map from conventional to primitive cell.

   .. rubric:: Notes

   .. math:: NTx = Ox

   for transformation_matrix :math:`T`, scaled coordinates :math:`x`, and old and new cell bases :math:`O,N` respectively.


.. py:function:: build_primitive_cell(ase_atoms, interactions, distance_tol = default_distance_tol, no_idealize = False)

   From the provided Atoms object, attempts to find a primitive cell and rewrites the interactions for this primitive cell.

   :param ase_atoms: The atoms object from which to build the primitive cell.
   :type ase_atoms: ase.Atoms
   :param interactions: The InteractionList object for the original cell exchange couplings.
   :type interactions: magnon.InteractionsList
   :param distance_tol: The precision to use in determining equivalent positions.
   :type distance_tol: float, optional
   :param no_idealize: Whether Spglib should idealize the primitive cell.
   :type no_idealize: bool

   :raises RuntimeError: If the generated primitive cell includes atom properties not compatible with those of the retained atoms from the
       original cell.

   :returns: * **ase_prim_atoms** (*ase.Atoms object*) -- The ASE Atoms object for the primitive cell
             * **interactions** (*magnon.InteractionsList*) -- The InteractionList object for the primitive cell.
             * **transformation_matrix** (*numpy.ndarray, dtype float*) -- The matrix transformation mapping from scaled coordinates with respect to the original cell, with shape (3, 3).

   .. rubric:: Notes

   This 'idealizes' the lattice, meaning the primitive cell may be rotated in cartesian space. We do this because
   otherwise we can end up with strange primitive lattice vectors (e.g. negative or left-handed), which then causes
   great difficulty in plotting correct k-space paths. We next calculate the transformation matrix between the two
   cells in the next step which we will need for manipulating the interaction vectors.

   The spglib `standardize_cell` function does not use magnetic information. We cannot use
   spglib.get_magnetic_symmetry_dataset because this has no way to idealize the cell. This is an issue, for example,
   with antiferromagnets where often the magnetic cell must be larger than non-magnetic cell. We work around the
   problem here by assigning all atoms with the same atomic number and same magnetic moment a unique number. Spglib
   only sees numbers as type labels, not as atomic numbers, so this is fine. To avoid collisions with atomic
   numbers we add 1000x the magnetic moment index. This also means we can trivially remove the artificial type
   and restore the atomic numbers for the primitive cell data returned by spglib.


.. py:function:: convert_kpts(kpts, original_cell, new_cell)

   Convert k-point(s) from scaled coordinates of one cell to another.

   :param kpts: The k-point(s) in scaled coordinates of the original_cell as an array of shape (3,) or (:math:`N_k`, 3)
   :type kpts: numpy.ndarray, dtype float
   :param original_cell: The lattice vectors of the original cell with shape (3,3)
   :type original_cell: numpy.ndarray, dtype float
   :param new_cell: The lattice vectors of the new cell with shape (3,3)
   :type new_cell: numpy.ndarray, dtype float

   :returns: **k_scaled_new_cell** -- The k-point(s) in scaled coordinates of new_cell with shape (3,) or (:math:`N_k`, 3)
   :rtype: numpy.ndarray, dtype float

   .. seealso::

      :obj:`magnon.build.cell_transformation`
          Returns the transformation matrix for scaled coordinates between two cells