lenskit.training.TrainingOptions
================================

.. py:class:: lenskit.training.TrainingOptions
   

   Options and context settings that govern model training.


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


      Whether the model should retrain if it is already trained.  If ``False``,
      the component is allowed to skip training if it is already trained.

      In the common case of training pipelines, this flag is examined by
      :meth:`lenskit.pipeline.Pipeline.train`: if it is ``False``, that method
      skips training any components that are already trained.  Custom training
      code that wishes to avoid retraining models should check
      :meth:`Trainable.is_trained` instead of assuming that individual components
      will respect this flag.

      .. note::

          This division of responsibility is to reduce the need for repetitive
          code: since implementing components seems to be a more common activity
          than logic that directly trains components (as opposed to pipelines) in
          ordinary LensKit use, making training code responsible for skipping
          retrain instead of requiring that of every component implementation
          allows individual implementations to be slightly simpler, without
          requiring separate options classes for pipeline and component training.

      .. versionchanged:: 2026.1

          Added the :meth:`is_trained` method that implementers must now also
          provide.


   .. py:attribute:: device
      :type:  str | None
      :value: None


      The device on which to train (e.g. ``'cuda'``).  May be ignored if the model
      does not support the specified device.


   .. py:attribute:: rng
      :type:  lenskit.random.RNGInput
      :value: None


      Random number generator to use for any randomness in the training process.
      This option contains any `SPEC 7`_-compatible random number generator
      specification; the :func:`~lenskit.random.random_generator` will convert
      that into a NumPy :class:`~numpy.random.Generator`.


   .. py:attribute:: environment
      :type:  dict[str, str]

      Additional training environment variables to control training behavior.
      Variables and their meanings are defined by individual components.
      Variables in this option override system environment variables when fetched
      with :meth:`envvar`.


   .. py:attribute:: torch_profiler
      :type:  torch.profiler.profile | None
      :value: None


      Torch profiler for profiling training options.


   .. py:method:: step_profiler()

      Signal to active profiler(s) that a new step has completed.



   .. py:method:: random_generator(*, type: Literal['numpy'] = 'numpy') -> numpy.random.Generator
                  random_generator(*, type: Literal['torch']) -> torch.Generator

      Obtain a random generator from the configured RNG or seed.

      .. note::

          Each call to this method will return a fresh generator from the same
          seed.  Components should call it once at the beginning of their
          training procesess.



   .. py:method:: configured_device(*, gpu_default = False)

      Get the configured device, consulting environment variables and defaults
      if necessary.  It looks for a device in the following order:

      1. The :attr:`device`, if specified on this object.
      2. The :envvar:`LK_DEVICE` environment variable.
      3. If CUDA is enabled and ``gpu_default`` is ``True``, return `"cuda"`
      4. The CPU.

      :param gpu_default: Whether a CUDA GPU should be preferred if it is available and no
                          device has been specified.



   .. py:method:: env_var(name: str, default: str) -> str
                  env_var(name: str, default: str | None = None) -> str | None

      Fetch a training environment variable.  Variables are first looked up in
      :attr:`environment`, then in :attr:`os.environ`.

      .. seealso::
          :attr:`environment`, :ref:`training-config`

      :param name: The full name of the environment variable.
      :param default: Default value to return if the environment varible is not specified.

      :returns: The environment variable's value, or ``default``.



   .. py:method:: env_flag(name, *, default = False)

      Query a boolean flag from the environment.