:mod:`heat.sanitation`
===========================
.. py:module:: heat.core.sanitation

.. autoapi-nested-parse::

   Collection of validation/sanitation routines.



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


.. function:: sanitize_distribution(*args: heat.core.dndarray.DNDarray, target: heat.core.dndarray.DNDarray, diff_map: torch.Tensor = None) -> Union[heat.core.dndarray.DNDarray, Tuple(DNDarray)]

   Distribute every `arg` according to `target.lshape_map` or, if provided, `diff_map`.
   After this sanitation, the lshapes are compatible along the split dimension.
   `Args` can contain non-distributed DNDarrays, they will be split afterwards, if `target` is split.

   :param args: Dndarrays to be distributed
   :type args: DNDarray
   :param target: Dndarray used to sanitize the metadata and to, if diff_map is not given, determine the resulting distribution.
   :type target: DNDarray
   :param diff_map: Different lshape_map. Overwrites the distribution of the target array.
                    Used in cases when the target array does not correspond to the actually wanted distribution,
                    e.g. because it only contains a single element along the split axis and gets broadcast.
   :type diff_map: torch.Tensor (optional)

   :raises TypeError: When an argument is not a ``DNDarray`` or ``None``.
   :raises ValueError: When the split-axes or sizes along the split-axis do not match.

   .. seealso::

      :func:`~heat.core.dndarray.create_lshape_map`
          Function to create the lshape_map.


.. function:: sanitize_in(x: Any)

   Verify that input object is ``DNDarray``.

   :param x: Input object
   :type x: Any

   :raises TypeError: When ``x`` is not a ``DNDarray``.


.. function:: sanitize_infinity(x: Union[heat.core.dndarray.DNDarray, torch.Tensor]) -> Union[int, float]

   Returns largest possible value for the ``dtype`` of the input array.

   :param x: Input object.
   :type x: Union[DNDarray, torch.Tensor]


.. function:: sanitize_in_tensor(x: Any)

   Verify that input object is ``torch.Tensor``.

   :param x: Input object.
   :type x: Any

   :raises TypeError: When ``x`` is not a ``torch.Tensor``.


.. function:: sanitize_lshape(array: heat.core.dndarray.DNDarray, tensor: torch.Tensor)

   Verify shape consistency when manipulating process-local arrays.

   :param array: the original, potentially distributed ``DNDarray``
   :type array: DNDarray
   :param tensor: process-local data meant to replace ``array.larray``
   :type tensor: torch.Tensor

   :raises ValueError: if shape of local ``torch.Tensor`` is inconsistent with global ``DNDarray``.


.. function:: sanitize_out(out: heat.core.dndarray.DNDarray, output_shape: Tuple, output_split: int, output_device: str, output_comm: heat.core.communication.Communication = None)

   Validate output buffer ``out``.

   :param out: the `out` buffer where the result of some operation will be stored
   :type out: DNDarray
   :param output_shape: the calculated shape returned by the operation
   :type output_shape: Tuple
   :param output_split: the calculated split axis returned by the operation
   :type output_split: Int
   :param output_device: "cpu" or "gpu" as per location of data
   :type output_device: Str
   :param output_comm: Communication object of the result of the operation
   :type output_comm: Communication

   :raises TypeError: if ``out`` is not a ``DNDarray``.
   :raises ValueError: if shape, split direction, or device of the output buffer ``out`` do not match the operation result.


.. function:: sanitize_sequence(seq: Union[Sequence[int, Ellipsis], Sequence[float, Ellipsis], heat.core.dndarray.DNDarray, torch.Tensor]) -> List

   Check if sequence is valid, return list.

   :param seq: Input sequence.
   :type seq: Union[Sequence[int, ...], Sequence[float, ...], DNDarray, torch.Tensor]

   :raises TypeError: if ``seq`` is neither a list nor a tuple


.. function:: scalar_to_1d(x: heat.core.dndarray.DNDarray) -> heat.core.dndarray.DNDarray

   Turn a scalar ``DNDarray`` into a 1-D ``DNDarray`` with 1 element.

   :param x: with `x.ndim = 0`
   :type x: DNDarray