artlib.optimized.backends.torch.GaussianARTMAP
==============================================

.. py:module:: artlib.optimized.backends.torch.GaussianARTMAP

.. autoapi-nested-parse::

   Gaussian ARTMAP :cite:`williamson1996gaussian` (Torch backend).



Classes
-------

.. autoapisummary::

   artlib.optimized.backends.torch.GaussianARTMAP._TorchGaussianARTMAPConfig
   artlib.optimized.backends.torch.GaussianARTMAP._TorchGaussianARTMAP
   artlib.optimized.backends.torch.GaussianARTMAP.GaussianARTMAP


Functions
---------

.. autoapisummary::

   artlib.optimized.backends.torch.GaussianARTMAP._to_device


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

.. py:function:: _to_device(x: Union[torch.Tensor, numpy.ndarray], device, dtype=torch.float32) -> torch.Tensor

.. py:class:: _TorchGaussianARTMAPConfig

   .. py:attribute:: input_dim
      :type:  int


   .. py:attribute:: rho
      :type:  float


   .. py:attribute:: alpha
      :type:  float
      :value: 1e-10



   .. py:attribute:: sigma_init
      :type:  Union[numpy.ndarray, torch.Tensor, float]
      :value: 0.1



   .. py:attribute:: epsilon
      :type:  float
      :value: 1e-07



   .. py:attribute:: match_tracking
      :type:  bool
      :value: True



   .. py:attribute:: device
      :type:  str
      :value: 'cuda'



   .. py:attribute:: dtype
      :type:  torch.dtype
      :value: Ellipsis



   .. py:attribute:: clamp_inputs
      :type:  bool
      :value: False



   .. py:attribute:: fallback_to_choice_on_fail
      :type:  bool
      :value: True



.. py:class:: _TorchGaussianARTMAP(cfg: _TorchGaussianARTMAPConfig)

   Torch-accelerated Gaussian ARTMAP with export hooks for artlib synchronization.

   Category weight layout (numpy-compatible on export):     [ mean(D), sigma(D),
   inv_sigma(D), sqrt_det_sigma(1), n(1) ]  -> length 3D + 2



   .. py:attribute:: cfg


   .. py:attribute:: device


   .. py:attribute:: dtype


   .. py:attribute:: input_dim


   .. py:attribute:: mean
      :type:  Optional[torch.Tensor]
      :value: None



   .. py:attribute:: sigma
      :type:  Optional[torch.Tensor]
      :value: None



   .. py:attribute:: inv_var
      :type:  Optional[torch.Tensor]
      :value: None



   .. py:attribute:: sqrt_det
      :type:  Optional[torch.Tensor]
      :value: None



   .. py:attribute:: counts
      :type:  Optional[torch.Tensor]
      :value: None



   .. py:attribute:: map_y
      :type:  Optional[torch.Tensor]
      :value: None



   .. py:attribute:: _sigma_init


   .. py:property:: n_cat
      :type: int



   .. py:method:: _ensure_capacity()


   .. py:method:: _validate_prepared(X: torch.Tensor)


   .. py:method:: _free_mem_bytes() -> int


   .. py:method:: prepare_data(X: Union[torch.Tensor, numpy.ndarray]) -> torch.Tensor


   .. py:method:: _gaussian_terms_for(I: torch.Tensor) -> Tuple[torch.Tensor, torch.Tensor]

      Compute exp(-0.5 * (x-μ)^T Σ^{-1} (x-μ)) and priors p(cj) for all categories.

      :returns: [K]  (likelihood numerator without constants and det term)
                p_cj:     [K]  (counts / sum_counts; zero-safe)
      :rtype: exp_term



   .. py:method:: _choice_and_match(I: torch.Tensor) -> Tuple[torch.Tensor, torch.Tensor]

      Returns (T, m) over all categories for single input I.

      T = p(x|cj) * p(cj) with p(x|cj) ∝ exp_term / (alpha + sqrt_det). m = exp_term
      (match criterion).




   .. py:method:: _commit_new_category(I: torch.Tensor, y: int)

      Initialize new Gaussian with mean=I, sigma=sigma_init, n=1.



   .. py:method:: _learn_in_category(j: int, I: torch.Tensor)

      Update mean, sigma, inv_var, sqrt_det, counts; replicate numpy reference.



   .. py:method:: partial_fit_and_export(X_prepared: Union[torch.Tensor, numpy.ndarray], y: Union[torch.Tensor, numpy.ndarray], epsilon: float = 1e-10, match_tracking: Literal['MT+', 'MT-', 'MT0', 'MT1', 'MT~'] = 'MT+') -> Tuple[numpy.ndarray, list[numpy.ndarray], numpy.ndarray]

      Incremental training on already-prepared inputs (raw, not complement-coded).

      :returns: chosen category indices per-sample
                weights_arrays (list[np.ndarray]): per-category weights (float64)
                cluster_labels_out (np.ndarray): map from categories to class labels
      :rtype: labels_a_out (np.ndarray)



   .. py:method:: predict_ab_prepared(X_prepared: Union[torch.Tensor, numpy.ndarray]) -> Tuple[numpy.ndarray, numpy.ndarray]

      Return (a_idx, b_labels) for prepared inputs.



.. py:class:: GaussianARTMAP(rho: float, sigma_init: Union[numpy.ndarray, float], alpha: float = 1e-10, input_dim: Optional[int] = None, device: str = 'cuda', dtype: torch.dtype = torch.float64)

   Bases: :py:obj:`artlib.optimized.backends.torch._TorchSimpleARTMAP._TorchSimpleARTMAP`


   GaussianARTMAP for Classification. optimized with torch.

   This module implements GaussianARTMAP

   GaussianARTMAP is a non-modular classification model which has been highly
   optimized for run-time performance. Fit and predict functions are implemented in
   torch for efficient execution. This class acts as a wrapper for the underlying torch
   functions and to provide compatibility with the artlib style and usage.
   Functionally, GaussianARTMAP behaves as a special case of
   :class:`~artlib.supervised.SimpleARTMAP.SimpleARTMAP` instantiated with
   :class:`~artlib.elementary.GaussianART.GaussianART`.



   .. py:attribute:: _device
      :value: 'cuda'



   .. py:attribute:: _dtype
      :value: Ellipsis



   .. py:attribute:: _backend
      :type:  Optional[_TorchGaussianARTMAP]
      :value: None



   .. py:attribute:: _declared_input_dim
      :value: None



   .. py:method:: _ensure_backend(X: numpy.ndarray)