magnon.input
============

.. py:module:: magnon.input


Functions
---------

.. autoapisummary::

   magnon.input.read_site_spin_data
   magnon.input.create_interacting_system


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

.. py:function:: read_site_spin_data(spin_data_filename)

   Read information on the magnitudes and directions of the magnetic moments from a file.

   :param spin_data_filename: The location and name of the file containing the magnitudes and directions of the spin magnetic moments.
   :type spin_data_filename: str

   :raises ValueError: If there are one or more lines which do not match the required format.

   :returns: * **spin_data** (*numpy.ndarray*) -- Magnitudes of the spin magnetic moments.
             * **direction_data** (*numpy.ndarray*) -- Directions of the spin magnetic moments.

   .. rubric:: Notes

   The ordering of the lines should correspond to the order of the coordinates in the structure input file.
   Each line consists of the magnitude of the spin magnetic moment followed by the three vector components of its direction.
   These should be separated by spaces.


.. py:function:: create_interacting_system(cell_file, magmom_file, interaction_file, magmom_scaling=1)

   Read structural, magnetic and exchange coupling data to create an ASE Atoms object and a Magnon.InteractionList object.

   :param cell_file: The location and name of the file containing the cell vectors and coordinates.
   :type cell_file: str
   :param magmom_file: The location and name of the file containing the magnitudes and directions of the magnetic moments.
   :type magmom_file: str
   :param interaction_file: The location and name of the file containing the exchange coupling data.
   :type interaction_file: str
   :param magmom_scaling: A number by which to multiply all magnetic moment magnitudes.
   :type magmom_scaling: float

   :returns: * **atoms** (*ase.Atoms object*) -- The ASE Atoms object describing the structure and magnetic moments.
             * **interactions** (*magnon.InteractionList object*) -- The InteractionList object describing the exchange coupling.

   .. rubric:: Notes

   The magmom_scaling allows straightforward conversion of the magnitudes if they are provided as e.g. spin quantum numbers
   in the data file (in this case, we would scale by 2 to get the magnetic moment from S).