hyrax.data_sets.tensor_cache_mixin
==================================

.. py:module:: hyrax.data_sets.tensor_cache_mixin


Attributes
----------

.. autoapisummary::

   hyrax.data_sets.tensor_cache_mixin.logger


Classes
-------

.. autoapisummary::

   hyrax.data_sets.tensor_cache_mixin.TensorCacheMixin


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

.. py:data:: logger

.. py:class:: TensorCacheMixin

   Bases: :py:obj:`abc.ABC`


   Mixin class providing in-memory tensor caching functionality for datasets.

   This mixin provides:
   - use_cache: Cache tensors in memory after first load
   - preload_cache: Preload all tensors in background thread
   - Efficient tensor cache management with hit/miss tracking
   - Background preloading with parallel processing

   Classes using this mixin must implement:
   - _load_tensor_for_cache(object_id: str) -> torch.Tensor
   - ids() -> Generator[str] (iterator over object IDs)
   - __len__() -> int


   .. py:method:: _init_tensor_cache(config)

      Initialize tensor caching. Call this from __init__ after other setup.



   .. py:method:: _load_tensor_for_cache(object_id: str)
      :abstractmethod:


      Load tensor for the given object_id. Must be implemented by subclasses.

      :param object_id: The object ID to load tensor for
      :type object_id: str

      :returns: The loaded tensor
      :rtype: torch.Tensor



   .. py:method:: ids(log_every: int | None = None) -> collections.abc.Generator[str, None, None]
      :abstractmethod:


      Iterator over all object IDs. Must be implemented by subclasses.

      :param log_every: Log progress every N objects
      :type log_every: Optional[int]

      :Yields: *str* -- Object IDs in the dataset



   .. py:method:: _check_object_id_to_tensor_cache(object_id: str)

      Check if tensor is already cached.



   .. py:method:: _populate_object_id_to_tensor_cache(object_id: str)

      Load tensor and populate cache.



   .. py:method:: _object_id_to_tensor_cached(object_id: str)

      Get tensor for object_id with caching support.

      :param object_id: The object_id requested
      :type object_id: str

      :returns: The tensor for the object
      :rtype: torch.Tensor



   .. py:method:: _determine_numprocs_preload()
      :staticmethod:


      Determine number of processes for preloading.



   .. py:method:: _preload_tensor_cache()

      Preload all tensors in the dataset using multiple threads.



   .. py:method:: _lazy_map_executor(executor: concurrent.futures.Executor, ids: collections.abc.Iterable[str])

      Lazy evaluation version of concurrent.futures.Executor.map().

      This limits memory usage during preloading by keeping only a small
      number of tensors in memory at once.

      :param executor: An executor for running futures
      :type executor: concurrent.futures.Executor
      :param ids: An iterable list of object IDs
      :type ids: Iterable[str]

      :Yields: *Iterator[torch.Tensor]* -- An iterator over torch tensors, lazily loaded



   .. py:method:: _log_duration_tensorboard(name: str, start_time: int)

      Log a duration to tensorboardX if configured.

      :param name: The name of the scalar to log
      :type name: str
      :param start_time: Start time in nanoseconds from time.monotonic_ns()
      :type start_time: int