# freezing

Python API: `luxonis_train.lightning.freezing`

节点冻结计划，源自配置。

配置单独定义了计划。具有 `freezing.active` 的节点在其解冻 epoch 之前保持冻结状态，并从该 epoch
开始训练。[resolve_unfreeze_epoch](/software-v3/ai-inference/model-source/training/luxonis-train/luxonis-train-api-reference/lightning/freezing.md)
计算解冻 epoch。

[FreezeSchedule.apply](/software-v3/ai-inference/model-source/training/luxonis-train/luxonis-train-api-reference/lightning/freezing.md)
从 epoch 编号派生节点的状态，因此对同一 epoch
的重复调用会给出相同的状态。[TrainingManager](/software-v3/ai-inference/model-source/training/luxonis-train/luxonis-train-api-reference/callbacks/training_manager.md)
在 fit 开始时和每个训练 epoch 开始时调用它。因此，恢复的运行会获得正确的状态，并且检查点不需要回调的任何状态：

 * 冻结的参数保留在其参数组中，因为训练计划将每个参数放入一个固定的组中。因此，优化器状态作为普通的 `state_dict` 加载。
 * 每个 epoch 开始时，再次根据计划设置 `requires_grad` 和批归一化状态。
 * 优化器和调度器状态字典保存学习率。Lightning 保存并恢复它们。

[FreezeSchedule.apply](/software-v3/ai-inference/model-source/training/luxonis-train/luxonis-train-api-reference/lightning/freezing.md)
仅在解冻 epoch 本身设置 `lr_after_unfreeze`。在该 epoch 之后 恢复的运行不会再次设置它。检查点已经保存了调度器达到的学习率。第二次更新速率会破坏计算每个速率的调度器，例如 `StepLR`。

## 类

### FreezeSchedule

所有具有 `freezing.active` 的节点的冻结计划。

[Nodes](/software-v3/ai-inference/model-source/training/luxonis-train/luxonis-train-api-reference/lightning/utils.md)
在构建节点后构建计划，并将其存储在 `freeze_schedule`
中。[TrainingManager](/software-v3/ai-inference/model-source/training/luxonis-train/luxonis-train-api-reference/callbacks/training_manager.md)
应用它。

#### 方法

##### init

```python
def __init__(plans: list[NodeFreezePlan]):
```

初始化计划。

参数

 * `plans` (`list[NodeFreezePlan]`): 每个具有冻结计划的节点一个计划。计划保留列表本身，而不是副本。

##### apply

```python
def apply(epoch: int, runtime: TrainingPlanRuntime | None = None):
```

为 epoch 设置每个计划节点的状态。

对于在 `epoch` 中冻结的节点，该方法将每个参数的 `requires_grad` 和每个批归一化层的 `track_running_stats` 设置为
`False`。对于任何其他节点，它恢复计划的原始值。当参数从可训练变为冻结时，该方法会为节点记录一条信息消息，当参数恢复时，会记录另一条信息消息。对同一 epoch 的重复调用会给出相同的状态。

使用 `runtime`，该方法还将 `lr_after_unfreeze` 设置为节点每个组的基本学习率，但仅当 `epoch` 是节点的解冻 epoch 时。模块文档字符串说明了为什么后续 epoch 不设置速率。这些组来自
[attach_group_handles](/software-v3/ai-inference/model-source/training/luxonis-train/luxonis-train-api-reference/lightning/freezing.md)。

> **示例**
> 该示例关闭了日志记录器，因此不显示信息消息：

```pycon
>>> from loguru import logger
>>> from torch import nn
>>> logger.disable("luxonis_train")
>>> module = nn.Sequential(nn.Linear(2, 2), nn.BatchNorm1d(2))
>>> plan = NodeFreezePlan.from_module(
...     "head", module, unfreeze_epoch=2, lr_after_unfreeze=None
... )
>>> schedule = FreezeSchedule([plan])
>>> schedule.apply(epoch=0)
>>> module[0].weight.requires_grad, module[1].track_running_stats
(False, False)
>>> schedule.apply(epoch=2)
>>> module[0].weight.requires_grad, module[1].track_running_stats
(True, True)
>>> logger.enable("luxonis_train")
```

参数

 * `epoch` (`int`): epoch 编号，从 `0` 开始。
 * `runtime` (`TrainingPlanRuntime | None`): 运行的优化器和调度器。`None` 不改变学习率。

##### attach_group_handles

```python
def attach_group_handles(runtime: TrainingPlanRuntime):
```

在每个计划中存储其节点的参数组。

[LuxonisLightningModule.configure_optimizers](/software-v3/ai-inference/model-source/training/luxonis-train/luxonis-train-api-reference/lightning/luxonis_lightning.md)
在构建优化器后调用该方法。对于每个计划，该方法获取包含节点参数的组的句柄。它检查这些组中的每个组是否仅包含该节点的参数。因此，`lr_after_unfreeze` 不会改变另一个节点的学习率。

参数

 * `runtime` (`TrainingPlanRuntime`): 运行的优化器和调度器。

引发

 * `RuntimeError`: 当计划节点的组也包含另一个节点的参数时。

##### from_nodes

```python
def from_nodes(nodes: Nodes) -> Self:
```

从模型的节点构建计划。

该方法为每个 `unfreeze_after` 不为 `None` 的节点创建
[NodeFreezePlan.from_module](/software-v3/ai-inference/model-source/training/luxonis-train/luxonis-train-api-reference/lightning/freezing.md)
的计划。在任何冻结之前构建计划，以便计划记录原始状态。

参数

 * `nodes` (`Nodes`): 模型的节点。该方法读取每个
   [NodeWrapper](/software-v3/ai-inference/model-source/training/luxonis-train/luxonis-train-api-reference/lightning/utils.md)
   的 `name`、`module`、`unfreeze_after` 和 `lr_after_unfreeze`。

返回

 * `Self`: 计划，按 `nodes` 的顺序排列。

##### is_frozen

```python
def is_frozen(node_name: str, epoch: int) -> bool:
```

返回节点在 epoch 中是否冻结。

参数

 * `node_name` (`str`): 图中节点的名称。
 * `epoch` (`int`): epoch 编号，从 `0` 开始。

返回

 * `bool`: 当节点有计划且 `epoch` 在其解冻 epoch 之前时为 `True`。对于没有计划的节点为 `False`。

#### 属性

##### plans

计划的计划，每个计划节点一个。

该属性返回存储的列表，而不是副本。

### NodeFreezePlan

一个节点的冻结计划，及其原始状态。

#### 方法

##### from_module

```python
def from_module(node_name: str, module: nn.Module, unfreeze_epoch: int, lr_after_unfreeze: float | None) -> Self:
```

创建一个记录模块原始状态的计划。

计划存储每个参数的 `requires_grad` 值和每个批归一化层的 `track_running_stats` 值。解冻会恢复这些值。它不会使每个参数都可训练。因此，节点本身冻结的参数，或使用 `track_running_stats=False`
构建的层，会保留其设置。在任何冻结之前调用此方法。

> **示例**
> ```pycon
>>> from torch import nn
>>> module = nn.Linear(2, 2)
>>> _ = module.bias.requires_grad_(False)
>>> plan = NodeFreezePlan.from_module(
...     "head", module, unfreeze_epoch=3, lr_after_unfreeze=None
... )
>>> plan.original_requires_grad
[True, False]
>>> plan.is_frozen(2), plan.unfreezes_at(3)
(True, True)
```

参数

 * `node_name` (`str`): 图中节点的名称。
 * `module` (`nn.Module`): 节点。
 * `unfreeze_epoch` (`int`): 节点训练的第一个 epoch。
 * `lr_after_unfreeze` (`float | None`): 从解冻 epoch 开始的节点的基本学习率。`None` 保留调度器达到的速率。

返回

 * `Self`: 计划，不带组句柄。

##### is_frozen

```python
def is_frozen(epoch: int) -> bool:
```

返回节点在 epoch 中是否冻结。

参数

 * `epoch` (`int`): epoch 编号，从 `0` 开始。

返回

 * `bool`: 当 `epoch` 在 `unfreeze_epoch` 之前时为 `True`。

##### unfreezes_at

```python
def unfreezes_at(epoch: int) -> bool:
```

返回节点是否在 epoch 中解冻。

参数

 * `epoch` (`int`): epoch 编号，从 `0` 开始。

返回

 * `bool`: 当 `epoch` 是 `unfreeze_epoch` 时为 `True`。

#### 属性

##### batch_norms

节点的批归一化层。

##### group_handles

包含节点参数的参数组。[FreezeSchedule.attach_group_handles](/software-v3/ai-inference/model-source/training/luxonis-train/luxonis-train-api-reference/lightning/freezing.md) 设置它们。在该调用之前，元组为空。

##### lr_after_unfreeze

从解冻 epoch 开始的节点参数组的基本学习率。`None` 保留调度器达到的速率。

##### node_name

图中节点的名称。

##### original_requires_grad

在任何冻结之前每个参数的 `requires_grad` 值，按 `parameters` 的顺序。

##### original_track_running_stats

在任何冻结之前每个层的 `track_running_stats` 值，按 `batch_norms` 的顺序。

##### parameters

节点的参数。

##### unfreeze_epoch

节点训练的第一个 epoch。

## 函数

### resolve_unfreeze_epoch

```python
def resolve_unfreeze_epoch(freezing: FreezingConfig, total_epochs: int) -> int | None:
```

将 `freezing.unfreeze_after` 解析为 epoch 编号。

整数是 epoch 编号本身。浮点数是 `total_epochs` 的一部分，截断为整数。`None` 给出 `total_epochs`，因此节点在整个运行期间保持冻结。

> **示例**
> ```pycon
>>> from luxonis_train.config.config import FreezingConfig
>>> resolve_unfreeze_epoch(
...     FreezingConfig(active=True, unfreeze_after=0.25), 10
... )
2
>>> resolve_unfreeze_epoch(FreezingConfig(active=True), 10)
10
>>> print(resolve_unfreeze_epoch(FreezingConfig(), 10))
None
```

参数

 * `freezing` (`FreezingConfig`): 节点配置的 `freezing` 部分。
 * `total_epochs` (`int`): 运行的 epoch 数量，来自 `trainer.epochs`。

返回

 * `int | None`: 节点训练的第一个 epoch。当 `freezing.active` 为 `False` 时为 `None`。
