magnon.interactions =================== .. py:module:: magnon.interactions Classes ------- .. autoapisummary:: magnon.interactions.Interaction magnon.interactions.InteractionList Functions --------- .. autoapisummary:: magnon.interactions.apply_bond_reversal_symmetry magnon.interactions.symmetrize_couplings magnon.interactions.read_interactions Module Contents --------------- .. py:class:: Interaction A class used to represent a single exchange interaction :param i_index: The index of the first site involved in the interaction :type i_index: int :param j_index: The index of the second site involved in the interaction :type j_index: int :param r_ij_scaled: The interaction vector from i to j, in units of the lattice vectors :type r_ij_scaled: numpy.ndarray, dtype=float :param J_ij: The exchange coupling tensor :type J_ij: numpy.ndarray, dtype=float .. py:attribute:: i_index :type: int .. py:attribute:: j_index :type: int .. py:attribute:: r_ij_scaled :type: numpy.ndarray .. py:attribute:: J_ij :type: numpy.ndarray .. py:method:: __iter__() An iterator which enables unpacking of an Interaction object. .. py:class:: InteractionList(interaction_data, atoms, cartesian=False) A class used to represent a set of exchange coupling interactions associated with a given structure. This class also enables the application of symmetry operations to the exchange coupling dataset. :param interaction_data: A list either of Interaction objects or Interaction object initialisation inputs. :type interaction_data: list :param atoms: An ase.Atoms object describing the structure :type atoms: ase.Atoms object :param cartesian: Whether the distance vectors are Cartesian or scaled, defaults to False. :type cartesian: bool .. py:attribute:: atoms .. py:attribute:: interaction_list :value: [] .. py:method:: __iter__() An iterator that yields tuples of interaction data containing i_index, j_index, r_ij, J_ij. .. py:method:: insert_interaction(i_index, j_index, r_ij, J_ij, cartesian=False) Appends an Interaction object to the list of interactions. :param i_index: The index of the first site involved in the new interaction :type i_index: int :param j_index: The index of the second site involved in the new interaction :type j_index: int :param r_ij_scaled: The interaction vector from i to j, in units of the lattice vectors :type r_ij_scaled: numpy.ndarray, dtype=float :param J_ij: The exchange coupling tensor :type J_ij: numpy.ndarray, dtype=float .. py:method:: find_interactions(i_index, j_index, r_ij_scaled) Returns a list of Interaction objects matching the specified indices and vector. :param i_index: The index of the first site involved in the interaction(s) to be returned :type i_index: int :param j_index: The index of the second site involved in the interaction(s) to be returned :type j_index: int :param r_ij_scaled: The interaction vector from i to j, in units of the lattice vectors, of the interaction(s) to be returned :type r_ij_scaled: numpy.ndarray, dtype=float :returns: **matches** -- A list of Interaction objects matching the specified indices and vector. :rtype: list of Interaction objects .. py:method:: deduplicate() Removes any duplicate interactions from the current instance. .. py:method:: get_interactions(i) Returns a list of Interaction objects associated with a specified site index. :param i: The index of the site to get interactions for. :type i: int :rtype: A list of Interaction objects in which the first index is i .. py:method:: symmetrize(atoms) Apply the symmetry of the cell to the couplings :param atoms: The ASE Atoms object of the cell whose symmetry to use. :type atoms: ASE.Atoms object :rtype: InteractionList object containing the symmetrized exchange coupling .. py:method:: update_indices(index_map) Update the site indices based on a provided remapping :param index_map: A list in which the entry at each position is the new site index. :type index_map: list :raises ValueError: If one or more of the updated indices is invalid. :rtype: InteractionList object containing the updated site indices. .. rubric:: Notes This can be used to update the site indices when the nonmagnetic sites are removed - see `magnon.MagnonSpectrum`. The mapping in this case contains -1 for the nonmagnetic sites. If -1 is detected in the new couplings, a ValueError is raised. .. py:function:: apply_bond_reversal_symmetry(interaction_list) Applies the bond reversal symmetry due to bidirectionality of the exchange coupling. Returns the new couplings generated under this symmetry which were not included in the original interaction data. :param interaction_list: The exchange coupling to which the bond reversal symmetry will be applied. :type interaction_list: InteractionList object :raises RuntimeError: If the symmetry results in inconsistent interactions. :returns: **new_interaction_list** -- The new interactions generated under this symmetry which were not included in the original interaction data. :rtype: InteractionList object .. rubric:: Notes Applies the intrinsic symmetry .. math:: J(r_ij) = (J(r_ji))^T Any symmetric couplings which are absent in the input are returned. If any existing couplings violate the intrinsic symmetry then a RuntimeError is raised. This will happen in the following cases: - More than 1 interaction is found that has the same :math:`i,j` -> :math:`j,i` and :math:`r_ij` -> :math:`r_ji` symmetry. This means the input data is incorrect or incompatible with our code (for example assuming that identical interactions will be summed). - An interaction is found with the :math:`i,j` -> :math:`j,i` and :math:`r_ij` -> :math:`r_ji` symmetry but the coupling matrix does not have the correct :math:`J(r_ij) = (J(r_ji))^T` symmetry. .. py:function:: symmetrize_couplings(interaction_list, atoms, distance_tol = default_distance_tol) Generates the full exchange interaction data under the symmetry of a unit cell :param interaction_list: The InteractionList object containing the exchange coupling to be symmetrized :type interaction_list: magnon.InteractionList object :param atoms: The ASE Atoms object of the cell associated with the interactions :type atoms: ASE.Atoms object :param distance_tol: The precision used in determining equivalent coordinates, defaults to 1e-6 :type distance_tol: float, optional :raises RuntimeError: If the image of an atom under a symmetry operation does not correspond to another atom's location :returns: **new_interaction_list** -- The fully-symmetrized exchange coupling interactions :rtype: magnon.InteractionList object .. py:function:: read_interactions(filename, atom_base_index=1) Reads in interaction data from a file. :param filename: The location of the file containing the interaction data. :type filename: str :param atom_base_index: The convention for the index of the first atom, defaults to 1 :type atom_base_index: int, optional :raises ValueError: If the number of entries does not enable the construction of a scalar or 3x3 exchange coupling :returns: **interaction_data** -- A list of data needed to create an Interaction object for each exchange coupling interaction in the file. :rtype: list .. rubric:: Notes Each line describes an interaction. The first two values are the atom indices in the unit cell, the next three give the vector between the atoms and the remainder give the coupling strength, either as a tensor or a scalar.