foscat.SphereDownGeo
====================

.. py:module:: foscat.SphereDownGeo


Classes
-------

.. autoapisummary::

   foscat.SphereDownGeo.SphereDownGeo


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

.. py:class:: SphereDownGeo(nside_in: int, mode: str = 'smooth', radius_deg: float | None = None, sigma_deg: float | None = None, weight_norm: str = 'l1', cell_ids_out: numpy.ndarray | list[int] | None = None, in_cell_ids: numpy.ndarray | list[int] | torch.Tensor | None = None, use_csr=True, device=None, dtype: torch.dtype = torch.float32)

   Bases: :py:obj:`torch.nn.Module`


   Geometric HEALPix downsampling operator (NESTED indexing).

   This module reduces resolution by a factor 2:
       nside_out = nside_in // 2

   Input conventions
   -----------------
   - If in_cell_ids is None:
       x is expected to be full-sphere: [B, C, N_in]
       output is [B, C, K_out] with K_out = len(cell_ids_out) (or N_out if None).
   - If in_cell_ids is provided (fine pixels at nside_in, NESTED):
       x can be either:
         * compact: [B, C, K_in] where K_in = len(in_cell_ids), aligned with in_cell_ids order
         * full-sphere: [B, C, N_in] (also supported)
       output is [B, C, K_out] where cell_ids_out is derived as unique(in_cell_ids // 4),
       unless you explicitly pass cell_ids_out (then it will be intersected with the derived set).

   Modes
   -----
   - mode="smooth": linear downsampling y = M @ x  (M sparse)
   - mode="maxpool": non-linear max over available children (fast)


   .. py:attribute:: device
      :value: None



   .. py:attribute:: dtype
      :value: Ellipsis



   .. py:attribute:: nside_in


   .. py:attribute:: nside_out


   .. py:attribute:: N_in


   .. py:attribute:: N_out


   .. py:attribute:: mode
      :value: ''



   .. py:attribute:: weight_norm
      :value: ''



   .. py:attribute:: in_cell_ids
      :value: None



   .. py:attribute:: has_in_subset


   .. py:attribute:: K_out


   .. py:attribute:: K_in


   .. py:method:: forward(x: torch.Tensor)

      :Parameters: **x** (:py:class:`torch.Tensor`) --

                   If has_in_subset:
                       - [B,C,K_in] (compact, aligned with in_cell_ids) OR [B,C,N_in] (full sphere)
                   Else:
                       - [B,C,N_in] (full sphere)

      :returns: * **y** (:py:class:`torch.Tensor`) -- [B,C,K_out]
                * **cell_ids_out** (:py:class:`torch.Tensor`) -- [K_out] coarse pixel ids (nside_out), aligned with y last dimension.