:py:mod:`mipcandy.training`
===========================

.. py:module:: mipcandy.training

.. autodoc2-docstring:: mipcandy.training
   :allowtitles:

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

Classes
~~~~~~~

.. list-table::
   :class: autosummary longtable
   :align: left

   * - :py:obj:`TrainerToolbox <mipcandy.training.TrainerToolbox>`
     - .. autodoc2-docstring:: mipcandy.training.TrainerToolbox
          :summary:
   * - :py:obj:`TrainerTracker <mipcandy.training.TrainerTracker>`
     - .. autodoc2-docstring:: mipcandy.training.TrainerTracker
          :summary:
   * - :py:obj:`Trainer <mipcandy.training.Trainer>`
     - .. autodoc2-docstring:: mipcandy.training.Trainer
          :summary:

Functions
~~~~~~~~~

.. list-table::
   :class: autosummary longtable
   :align: left

   * - :py:obj:`try_append <mipcandy.training.try_append>`
     - .. autodoc2-docstring:: mipcandy.training.try_append
          :summary:
   * - :py:obj:`try_append_all <mipcandy.training.try_append_all>`
     - .. autodoc2-docstring:: mipcandy.training.try_append_all
          :summary:

API
~~~

.. py:function:: try_append(new: float, to: dict[str, list[float]], key: str) -> None
   :canonical: mipcandy.training.try_append

   .. autodoc2-docstring:: mipcandy.training.try_append

.. py:function:: try_append_all(new: dict[str, float], to: dict[str, list[float]]) -> None
   :canonical: mipcandy.training.try_append_all

   .. autodoc2-docstring:: mipcandy.training.try_append_all

.. py:class:: TrainerToolbox
   :canonical: mipcandy.training.TrainerToolbox

   Bases: :py:obj:`object`

   .. autodoc2-docstring:: mipcandy.training.TrainerToolbox

   .. py:attribute:: model
      :canonical: mipcandy.training.TrainerToolbox.model
      :type: torch.nn.Module
      :value: None

      .. autodoc2-docstring:: mipcandy.training.TrainerToolbox.model

   .. py:attribute:: optimizer
      :canonical: mipcandy.training.TrainerToolbox.optimizer
      :type: torch.optim.Optimizer
      :value: None

      .. autodoc2-docstring:: mipcandy.training.TrainerToolbox.optimizer

   .. py:attribute:: scheduler
      :canonical: mipcandy.training.TrainerToolbox.scheduler
      :type: torch.optim.lr_scheduler.LRScheduler
      :value: None

      .. autodoc2-docstring:: mipcandy.training.TrainerToolbox.scheduler

   .. py:attribute:: criterion
      :canonical: mipcandy.training.TrainerToolbox.criterion
      :type: torch.nn.Module
      :value: None

      .. autodoc2-docstring:: mipcandy.training.TrainerToolbox.criterion

   .. py:attribute:: ema
      :canonical: mipcandy.training.TrainerToolbox.ema
      :type: torch.nn.Module | None
      :value: None

      .. autodoc2-docstring:: mipcandy.training.TrainerToolbox.ema

.. py:class:: TrainerTracker
   :canonical: mipcandy.training.TrainerTracker

   Bases: :py:obj:`object`

   .. autodoc2-docstring:: mipcandy.training.TrainerTracker

   .. py:attribute:: epoch
      :canonical: mipcandy.training.TrainerTracker.epoch
      :type: int
      :value: 0

      .. autodoc2-docstring:: mipcandy.training.TrainerTracker.epoch

   .. py:attribute:: best_score
      :canonical: mipcandy.training.TrainerTracker.best_score
      :type: float
      :value: 'float(...)'

      .. autodoc2-docstring:: mipcandy.training.TrainerTracker.best_score

   .. py:attribute:: worst_case
      :canonical: mipcandy.training.TrainerTracker.worst_case
      :type: int | None
      :value: None

      .. autodoc2-docstring:: mipcandy.training.TrainerTracker.worst_case

.. py:class:: Trainer(trainer_folder: str | os.PathLike[str], dataloader: torch.utils.data.DataLoader[tuple[torch.Tensor, torch.Tensor]], validation_dataloader: torch.utils.data.DataLoader[tuple[torch.Tensor, torch.Tensor]], *, recoverable: bool = True, profiler: bool = False, device: torch.device | str = 'cpu', console: rich.console.Console = Console())
   :canonical: mipcandy.training.Trainer

   Bases: :py:obj:`mipcandy.layer.WithPaddingModule`, :py:obj:`mipcandy.layer.WithNetwork`

   .. autodoc2-docstring:: mipcandy.training.Trainer

   .. rubric:: Initialization

   .. autodoc2-docstring:: mipcandy.training.Trainer.__init__

   .. py:method:: save_everything_for_recovery(toolbox: mipcandy.training.TrainerToolbox, tracker: mipcandy.training.TrainerTracker, **training_arguments) -> None
      :canonical: mipcandy.training.Trainer.save_everything_for_recovery

      .. autodoc2-docstring:: mipcandy.training.Trainer.save_everything_for_recovery

   .. py:method:: load_state_orb() -> dict[str, dict[str, mipcandy.types.Setting]]
      :canonical: mipcandy.training.Trainer.load_state_orb

      .. autodoc2-docstring:: mipcandy.training.Trainer.load_state_orb

   .. py:method:: load_tracker() -> mipcandy.training.TrainerTracker
      :canonical: mipcandy.training.Trainer.load_tracker

      .. autodoc2-docstring:: mipcandy.training.Trainer.load_tracker

   .. py:method:: load_training_arguments() -> dict[str, mipcandy.types.Setting]
      :canonical: mipcandy.training.Trainer.load_training_arguments

      .. autodoc2-docstring:: mipcandy.training.Trainer.load_training_arguments

   .. py:method:: load_metrics() -> dict[str, list[float]]
      :canonical: mipcandy.training.Trainer.load_metrics

      .. autodoc2-docstring:: mipcandy.training.Trainer.load_metrics

   .. py:method:: load_toolbox(num_epochs: int, example_shape: mipcandy.types.AmbiguousShape, compile_model: bool, ema: bool) -> mipcandy.training.TrainerToolbox
      :canonical: mipcandy.training.Trainer.load_toolbox

      .. autodoc2-docstring:: mipcandy.training.Trainer.load_toolbox

   .. py:method:: recover_from(experiment_id: str) -> typing.Self
      :canonical: mipcandy.training.Trainer.recover_from

      .. autodoc2-docstring:: mipcandy.training.Trainer.recover_from

   .. py:method:: continue_training(num_epochs: int) -> None
      :canonical: mipcandy.training.Trainer.continue_training

      .. autodoc2-docstring:: mipcandy.training.Trainer.continue_training

   .. py:method:: trainer_folder() -> str
      :canonical: mipcandy.training.Trainer.trainer_folder

      .. autodoc2-docstring:: mipcandy.training.Trainer.trainer_folder

   .. py:method:: trainer_variant() -> str
      :canonical: mipcandy.training.Trainer.trainer_variant

      .. autodoc2-docstring:: mipcandy.training.Trainer.trainer_variant

   .. py:method:: experiment_id() -> str
      :canonical: mipcandy.training.Trainer.experiment_id

      .. autodoc2-docstring:: mipcandy.training.Trainer.experiment_id

   .. py:method:: dataloader() -> torch.utils.data.DataLoader[tuple[torch.Tensor, torch.Tensor]]
      :canonical: mipcandy.training.Trainer.dataloader

      .. autodoc2-docstring:: mipcandy.training.Trainer.dataloader

   .. py:method:: validation_dataloader() -> torch.utils.data.DataLoader[tuple[torch.Tensor, torch.Tensor]]
      :canonical: mipcandy.training.Trainer.validation_dataloader

      .. autodoc2-docstring:: mipcandy.training.Trainer.validation_dataloader

   .. py:method:: console() -> rich.console.Console
      :canonical: mipcandy.training.Trainer.console

      .. autodoc2-docstring:: mipcandy.training.Trainer.console

   .. py:method:: metrics() -> dict[str, list[float]]
      :canonical: mipcandy.training.Trainer.metrics

      .. autodoc2-docstring:: mipcandy.training.Trainer.metrics

   .. py:method:: frontend() -> mipcandy.frontend.Frontend
      :canonical: mipcandy.training.Trainer.frontend

      .. autodoc2-docstring:: mipcandy.training.Trainer.frontend

   .. py:method:: tracker() -> mipcandy.training.TrainerTracker
      :canonical: mipcandy.training.Trainer.tracker

      .. autodoc2-docstring:: mipcandy.training.Trainer.tracker

   .. py:method:: initialized() -> bool
      :canonical: mipcandy.training.Trainer.initialized

      .. autodoc2-docstring:: mipcandy.training.Trainer.initialized

   .. py:method:: recovery() -> bool
      :canonical: mipcandy.training.Trainer.recovery

      .. autodoc2-docstring:: mipcandy.training.Trainer.recovery

   .. py:method:: experiment_folder() -> str
      :canonical: mipcandy.training.Trainer.experiment_folder

      .. autodoc2-docstring:: mipcandy.training.Trainer.experiment_folder

   .. py:method:: get_example_input() -> torch.Tensor
      :canonical: mipcandy.training.Trainer.get_example_input

      .. autodoc2-docstring:: mipcandy.training.Trainer.get_example_input

   .. py:method:: predict_maximum_validation_score(num_epochs: int, *, degree: int = 5) -> tuple[int, float]
      :canonical: mipcandy.training.Trainer.predict_maximum_validation_score

      .. autodoc2-docstring:: mipcandy.training.Trainer.predict_maximum_validation_score

   .. py:method:: etc(epoch: int, num_epochs: int, *, target_epoch: int | None = None, val_score_prediction_degree: int = 5) -> float
      :canonical: mipcandy.training.Trainer.etc

      .. autodoc2-docstring:: mipcandy.training.Trainer.etc

   .. py:method:: set_frontend(frontend: type[mipcandy.frontend.Frontend], *, path_to_secrets: str | os.PathLike[str] | None = None) -> None
      :canonical: mipcandy.training.Trainer.set_frontend

      .. autodoc2-docstring:: mipcandy.training.Trainer.set_frontend

   .. py:method:: set_seed(seed: int) -> None
      :canonical: mipcandy.training.Trainer.set_seed

      .. autodoc2-docstring:: mipcandy.training.Trainer.set_seed

   .. py:method:: _allocate_experiment_folder() -> str
      :canonical: mipcandy.training.Trainer._allocate_experiment_folder

      .. autodoc2-docstring:: mipcandy.training.Trainer._allocate_experiment_folder

   .. py:method:: allocate_experiment_folder() -> str
      :canonical: mipcandy.training.Trainer.allocate_experiment_folder

      .. autodoc2-docstring:: mipcandy.training.Trainer.allocate_experiment_folder

   .. py:method:: init_experiment() -> None
      :canonical: mipcandy.training.Trainer.init_experiment

      .. autodoc2-docstring:: mipcandy.training.Trainer.init_experiment

   .. py:method:: log(msg: str, *, on_screen: bool = True) -> None
      :canonical: mipcandy.training.Trainer.log

      .. autodoc2-docstring:: mipcandy.training.Trainer.log

   .. py:method:: record(metric: str, value: float) -> None
      :canonical: mipcandy.training.Trainer.record

      .. autodoc2-docstring:: mipcandy.training.Trainer.record

   .. py:method:: record_all(metrics: dict[str, list[float]]) -> None
      :canonical: mipcandy.training.Trainer.record_all

      .. autodoc2-docstring:: mipcandy.training.Trainer.record_all

   .. py:method:: record_profiler() -> None
      :canonical: mipcandy.training.Trainer.record_profiler

      .. autodoc2-docstring:: mipcandy.training.Trainer.record_profiler

   .. py:method:: record_profiler_linebreak(message: str) -> None
      :canonical: mipcandy.training.Trainer.record_profiler_linebreak

      .. autodoc2-docstring:: mipcandy.training.Trainer.record_profiler_linebreak

   .. py:method:: record_profiler_allocated_tensors() -> None
      :canonical: mipcandy.training.Trainer.record_profiler_allocated_tensors

      .. autodoc2-docstring:: mipcandy.training.Trainer.record_profiler_allocated_tensors

   .. py:method:: save_metrics() -> None
      :canonical: mipcandy.training.Trainer.save_metrics

      .. autodoc2-docstring:: mipcandy.training.Trainer.save_metrics

   .. py:method:: save_metric_curve(name: str, values: typing.Sequence[float]) -> None
      :canonical: mipcandy.training.Trainer.save_metric_curve

      .. autodoc2-docstring:: mipcandy.training.Trainer.save_metric_curve

   .. py:method:: save_metric_curve_combo(metrics: dict[str, typing.Sequence[float]], *, title: str = 'All Metrics') -> None
      :canonical: mipcandy.training.Trainer.save_metric_curve_combo

      .. autodoc2-docstring:: mipcandy.training.Trainer.save_metric_curve_combo

   .. py:method:: save_metric_curves(*, names: typing.Sequence[str] | None = None) -> None
      :canonical: mipcandy.training.Trainer.save_metric_curves

      .. autodoc2-docstring:: mipcandy.training.Trainer.save_metric_curves

   .. py:method:: save_progress(*, names: typing.Sequence[str] = ('combined loss', 'val score')) -> None
      :canonical: mipcandy.training.Trainer.save_progress

      .. autodoc2-docstring:: mipcandy.training.Trainer.save_progress

   .. py:method:: save_preview(image: torch.Tensor, label: torch.Tensor, output: torch.Tensor, *, quality: float = 0.75) -> None
      :canonical: mipcandy.training.Trainer.save_preview

      .. autodoc2-docstring:: mipcandy.training.Trainer.save_preview

   .. py:method:: show_metrics(epoch: int, metrics: dict[str, list[float]], prefix: str, *, epochwise: bool = True, lookup_prefix: str = '', global_previous_index: int = -2) -> None
      :canonical: mipcandy.training.Trainer.show_metrics

      .. autodoc2-docstring:: mipcandy.training.Trainer.show_metrics

   .. py:method:: show_metrics_per_case(epoch: int, metrics: dict[str, list[float]]) -> None
      :canonical: mipcandy.training.Trainer.show_metrics_per_case

      .. autodoc2-docstring:: mipcandy.training.Trainer.show_metrics_per_case

   .. py:method:: build_optimizer(params: mipcandy.types.Params) -> torch.optim.Optimizer
      :canonical: mipcandy.training.Trainer.build_optimizer
      :abstractmethod:

      .. autodoc2-docstring:: mipcandy.training.Trainer.build_optimizer

   .. py:method:: build_scheduler(optimizer: torch.optim.Optimizer, num_epochs: int) -> torch.optim.lr_scheduler.LRScheduler
      :canonical: mipcandy.training.Trainer.build_scheduler
      :abstractmethod:

      .. autodoc2-docstring:: mipcandy.training.Trainer.build_scheduler

   .. py:method:: build_criterion() -> torch.nn.Module
      :canonical: mipcandy.training.Trainer.build_criterion
      :abstractmethod:

      .. autodoc2-docstring:: mipcandy.training.Trainer.build_criterion

   .. py:method:: build_ema(model: torch.nn.Module) -> torch.nn.Module
      :canonical: mipcandy.training.Trainer.build_ema
      :abstractmethod:

      .. autodoc2-docstring:: mipcandy.training.Trainer.build_ema

   .. py:method:: _build_toolbox(num_epochs: int, example_shape: mipcandy.types.AmbiguousShape, compile_model: bool, ema: bool, *, model: torch.nn.Module | None = None) -> mipcandy.training.TrainerToolbox
      :canonical: mipcandy.training.Trainer._build_toolbox

      .. autodoc2-docstring:: mipcandy.training.Trainer._build_toolbox

   .. py:method:: build_toolbox(num_epochs: int, example_shape: mipcandy.types.AmbiguousShape, compile_model: bool, ema: bool) -> mipcandy.training.TrainerToolbox
      :canonical: mipcandy.training.Trainer.build_toolbox

      .. autodoc2-docstring:: mipcandy.training.Trainer.build_toolbox

   .. py:method:: empty_cache() -> None
      :canonical: mipcandy.training.Trainer.empty_cache

      .. autodoc2-docstring:: mipcandy.training.Trainer.empty_cache

   .. py:method:: sanity_check(template_model: torch.nn.Module, example_shape: mipcandy.types.AmbiguousShape) -> mipcandy.sanity_check.SanityCheckResult
      :canonical: mipcandy.training.Trainer.sanity_check

      .. autodoc2-docstring:: mipcandy.training.Trainer.sanity_check

   .. py:method:: backward(images: torch.Tensor, labels: torch.Tensor, toolbox: mipcandy.training.TrainerToolbox) -> tuple[float, dict[str, float]]
      :canonical: mipcandy.training.Trainer.backward
      :abstractmethod:

      .. autodoc2-docstring:: mipcandy.training.Trainer.backward

   .. py:method:: train_batch(images: torch.Tensor, labels: torch.Tensor, toolbox: mipcandy.training.TrainerToolbox) -> tuple[float, dict[str, float]]
      :canonical: mipcandy.training.Trainer.train_batch

      .. autodoc2-docstring:: mipcandy.training.Trainer.train_batch

   .. py:method:: train_epoch(toolbox: mipcandy.training.TrainerToolbox) -> dict[str, list[float]]
      :canonical: mipcandy.training.Trainer.train_epoch

      .. autodoc2-docstring:: mipcandy.training.Trainer.train_epoch

   .. py:method:: train(num_epochs: int, *, note: str = '', num_checkpoints: int = 5, compile_model: bool = True, ema: bool = True, seed: int | None = None, early_stop_tolerance: int = 5, val_score_prediction: bool = True, val_score_prediction_degree: int = 5, save_preview: bool = True, preview_quality: float = 0.75) -> None
      :canonical: mipcandy.training.Trainer.train

      .. autodoc2-docstring:: mipcandy.training.Trainer.train

   .. py:method:: filter_train_params(**kwargs) -> dict[str, mipcandy.types.Setting]
      :canonical: mipcandy.training.Trainer.filter_train_params
      :staticmethod:

      .. autodoc2-docstring:: mipcandy.training.Trainer.filter_train_params

   .. py:method:: train_with_settings(num_epochs: int, **kwargs) -> None
      :canonical: mipcandy.training.Trainer.train_with_settings

      .. autodoc2-docstring:: mipcandy.training.Trainer.train_with_settings

   .. py:method:: validate_case(idx: int, image: torch.Tensor, label: torch.Tensor, toolbox: mipcandy.training.TrainerToolbox) -> tuple[float, dict[str, float], torch.Tensor]
      :canonical: mipcandy.training.Trainer.validate_case
      :abstractmethod:

      .. autodoc2-docstring:: mipcandy.training.Trainer.validate_case

   .. py:method:: validate(toolbox: mipcandy.training.TrainerToolbox) -> tuple[float, dict[str, list[float]]]
      :canonical: mipcandy.training.Trainer.validate

      .. autodoc2-docstring:: mipcandy.training.Trainer.validate

   .. py:method:: __call__(*args, **kwargs) -> None
      :canonical: mipcandy.training.Trainer.__call__

      .. autodoc2-docstring:: mipcandy.training.Trainer.__call__

   .. py:method:: __str__() -> str
      :canonical: mipcandy.training.Trainer.__str__