ncalab.utils
============

.. py:module:: ncalab.utils


Attributes
----------

.. autoapisummary::

   ncalab.utils.DEFAULT_RANDOM_SEED


Functions
---------

.. autoapisummary::

   ncalab.utils.get_compute_device
   ncalab.utils.pad_input
   ncalab.utils.print_NCALab_banner
   ncalab.utils.print_mascot
   ncalab.utils.fix_random_seed
   ncalab.utils.unwrap
   ncalab.utils.intepret_range_parameter


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

.. py:function:: get_compute_device(device: str = 'cuda:0') -> torch.device

   Obtain a pytorch compute device handle based on input string.
   If user tries to get a CUDA device, but none is available,
   defaults to CPU.

   :param device: Device string, defaults to "cuda:0".
   :type device: str

   :returns: Pytorch compute device.
   :rtype: torch.device


.. py:function:: pad_input(x: torch.Tensor, nca: ncalab.models.BasicNCAModel, noise: bool = True, mean: float = 0.5, std: float = 0.225) -> torch.Tensor

   Pads the BCWH input tensor along its channel dimension to match the expected number of
   channels required by the NCA model. Pads with either Gaussian noise (parameterized by
   mean and std) or zeros, depending on the "noise" parameter.

   :param x: Input image tensor, BCWH.
   :type x: torch.Tensor
   :param nca: NCA model definition.
   :type nca: ncalab.BasicNCAModel
   :param noise: Whether to pad with noise. Otherwise zeros, defaults to True.
   :type noise: bool, optional
   :param mean: Mean (mu) of Gaussian noise distribution, defaults to 0.5.
   :type mean: float, optional
   :param std: Standard deviation (sigma) of Gaussian noise distribution, defaults to 0.225.
   :type std: float, optional

   :returns: Input tensor, BCWH, padded along the channel dimension.
   :rtype: torch.Tensor


.. py:function:: print_NCALab_banner()

   Show NCALab banner on terminal.


.. py:function:: print_mascot(message: str)

   Show help text in a speech bubble.

   :param message: Message to display.
   :type message: str


.. py:data:: DEFAULT_RANDOM_SEED
   :value: 1337


.. py:function:: fix_random_seed(seed: int = DEFAULT_RANDOM_SEED)

   Fixes the random seed for all pseudo-random number generators,
   including Python-native, Numpy and Pytorch.

   :param seed: Random seed, defaults to DEFAULT_RANDOM_SEED.
   :type seed: int, optional


.. py:function:: unwrap(x: Any)

   Panics if x is None, otherwise returns x.

   This is a useful shorthand for cases such as ``x = unwrap(some_object).do_something()``
   in which we are 99% certain that some_object is not None and want to avoid a mypy complaint.

   :param x: Any kind of object.
   :type x: Any
   :raises RuntimeError: If x is None.
   :return: Just passes through the input x if it is not None.


.. py:function:: intepret_range_parameter(x: int | Tuple[int, int]) -> int

   Interpret a range parameter that is passed for NCA timesteps.

   If the parameter is a single int, just return it as is.
   If the parameter is a two-valued tuple, interpret it as a [min,max) and randomly
   sample from that range.

   :param x: _description_
   :type x: int | Tuple[int, int]
   :raises TypeError: If something else than an int or a tuple was passed.
   :return: _description_
   :rtype: int