magnon.utils
============

.. py:module:: magnon.utils


Functions
---------

.. autoapisummary::

   magnon.utils.is_array_like
   magnon.utils.all_same_shape
   magnon.utils.all_same_length
   magnon.utils.ensure_vector_magnetic_moments


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

.. py:function:: is_array_like(obj, ndim)

   Check if the input object is an array-like structure with a specific number of dimensions.

   :param obj: Object to be checked.
   :type obj: object
   :param ndim: Number of dimensions expected.
   :type ndim: int

   :returns: True if the object is array-like with the specified number of dimensions, False otherwise.
   :rtype: bool

   :raises Exception: If the object cannot be converted to a NumPy array.


.. py:function:: all_same_shape(*arrays)

   Check whether all input arrays have the same shape.

   :param arrays: Variable number of arrays to compare.
   :type arrays: array-like

   :returns: True if all arrays have the same shape, False otherwise.
   :rtype: bool


.. py:function:: all_same_length(*arrays)

   Check whether all input arrays have the same length.

   :param arrays: Variable number of arrays to compare.
   :type arrays: array-like

   :returns: True if all arrays have the same length, False otherwise.
   :rtype: bool


.. py:function:: ensure_vector_magnetic_moments(atoms)

   Ensure that the ASE Atoms object has vector (3D) magnetic moments for each atom.

   :param atoms: ASE atoms object to be validated.
   :type atoms: ase.Atoms

   :returns: **atoms** -- ASE Atoms object with vector magnetic moments.
   :rtype: ase.Atoms

   .. rubric:: Notes

   ASE allows `initial_magnetic_moments` to be either scalar or vector. This function
   guarantees vector format, which is useful for handling non-collinear magnetism.