# CMStochasticIterativeScheduler

Yang Song、Prafulla Dhariwal、Mark Chen、Ilya Sutskever による [Consistency Models](https://huggingface.co/papers/2303.01469) は、1 ステップまたは少数のステップで良好なサンプルを生成できるマルチステップおよびワンステップのスケジューラ（アルゴリズム 1）を導入しました。

論文の抄録は以下の通りです：

*Diffusionモデルは画像・音声・動画生成の分野を大きく前進させましたが、反復的なサンプリングプロセスに依存しているため、生成が遅いという課題があります。この制約を克服するために、ノイズをデータへ直接マッピングすることで高品質なサンプルを生成する新しいモデルファミリーであるconsistencyモデルを提案します。consistencyモデルは設計上、1ステップでの高速生成をサポートしつつ、計算量とサンプル品質のトレードオフを可能にするマルチステップサンプリングにも対応します。また、これらのタスクに対する明示的なトレーニングを必要とせずに、画像インペインティング、カラー化、スーパーリゾリューションなどのゼロショットデータ編集にも対応します。consistencyモデルは、事前学習済みDiffusionモデルからの蒸留によって学習することも、完全に独立した生成モデルとして学習することも可能です。広範な実験を通じて、1ステップおよび少数ステップのサンプリングにおいて、既存のDiffusionモデル向け蒸留手法を上回ることを示しました。1ステップ生成において、CIFAR-10でFID 3.55、ImageNet 64x64で6.20という新たなSOTAを達成しています。独立して学習された場合、consistencyモデルは、CIFAR-10、ImageNet 64x64、LSUN 256x256といった標準ベンチマークにおいて、既存の1ステップ・非敵対的生成モデルを上回る性能を発揮する、新しい生成モデルファミリーとなります。*

元のコードベースは[openai/consistency_models](https://github.com/openai/consistency_models)で確認できます。

## CMStochasticIterativeScheduler[[diffusers.CMStochasticIterativeScheduler]]

#### diffusers.CMStochasticIterativeScheduler[[diffusers.CMStochasticIterativeScheduler]]

```python
diffusers.CMStochasticIterativeScheduler(num_train_timesteps: int = 40, sigma_min: float = 0.002, sigma_max: float = 80.0, sigma_data: float = 0.5, s_noise: float = 1.0, rho: float = 7.0, clip_denoised: bool = True)
```

[ソース](https://github.com/huggingface/diffusers/blob/main/src/diffusers/schedulers/scheduling_consistency_models.py#L43)

**パラメータ:**

num_train_timesteps (`int`、デフォルトは 40) : モデルを学習するための拡散ステップ数。

sigma_min (`float`、デフォルト値は 0.002) : sigma スケジュールにおける最小ノイズ量。元の実装から引き継いで、デフォルト値は 0.002 です。

sigma_max (`float`、デフォルト値は 80.0) : sigma スケジュールにおける最大ノイズ量。元の実装からデフォルト値は 80.0 です。

sigma_data (`float`、デフォルト値は 0.5) : EDM の [論文](https://huggingface.co/papers/2206.00364) に記載されているデータ分布の標準偏差です。元の実装から引き継いで、デフォルト値は 0.5 です。

s_noise (`float`、デフォルト値は 1.0) : サンプリング中の詳細な情報の損失を補うために追加するノイズの量です。適切な範囲は [1.000, 1.011] です。元の実装ではデフォルト値が 1.0 に設定されています。

rho (`float`、デフォルト値は 7.0) : EDM の [論文](https://huggingface.co/papers/2206.00364) に基づいて Karras sigma スケジュールを計算するためのパラメータです。元の実装から 7.0 がデフォルト値として採用されています。

clip_denoised (`bool`、デフォルトは`True`) : 去噪された出力を`(-1, 1)`にクリップするかどうか。

timesteps (`list` または `np.ndarray` または `torch.Tensor`、*任意*) : 任意で指定できる明示的なタイムステップスケジュールです。タイムステップは昇順であることが期待されます。

Consistencyモデルにおけるマルチステップサンプリングとワンステップサンプリング。

このモデルは [SchedulerMixin](/docs/diffusers/main/ja/api/schedulers/overview#diffusers.SchedulerMixin) と [ConfigMixin](/docs/diffusers/main/ja/api/configuration#diffusers.ConfigMixin) を継承しています。読み込みや保存など、ライブラリがすべてのスケジューラに対して実装している汎用的なメソッドについては、スーパークラスのドキュメントを参照してください。

#### add_noise[[diffusers.CMStochasticIterativeScheduler.add_noise]]

```python
add_noise(original_samples: Tensor, noise: Tensor, timesteps: Tensor)
```

[ソース](https://github.com/huggingface/diffusers/blob/main/src/diffusers/schedulers/scheduling_consistency_models.py#L461)

**パラメータ:**

original_samples (`torch.Tensor`) : ノイズが加えられる元のサンプル。

noise (`torch.Tensor`) : 元のサンプルに追加するノイズのテンソル。

timesteps (`torch.Tensor`) : ノイズを追加するタイムステップ。スケジュールに基づいてノイズレベルを決定します。

**戻り値:** `torch.Tensor`

タイムステップスケジュールに従ってスケーリングされたノイズが加えられたノイズ付きサンプル。

指定されたタイムステップにおけるノイズスケジュールに従って、元のサンプルにノイズを追加します。

#### get_scalings[[diffusers.CMStochasticIterativeScheduler.get_scalings]]

```python
get_scalings(sigma: Tensor)
```

[ソース](https://github.com/huggingface/diffusers/blob/main/src/diffusers/schedulers/scheduling_consistency_models.py#L276)

**パラメータ:**

sigma (`torch.Tensor`) : ノイズスケジュールにおける現在の sigma 値。

**戻り値:** `tuple[torch.Tensor, torch.Tensor]`

`c_skip`（入力サンプルのスケーリング）と`c_out`（モデル出力のスケーリング）を含むタプル。

Consistency modelの出力に対するスケーリング係数を計算します。

#### get_scalings_for_boundary_condition[[diffusers.CMStochasticIterativeScheduler.get_scalings_for_boundary_condition]]

```python
get_scalings_for_boundary_condition(sigma: Tensor)
```

[ソース](https://github.com/huggingface/diffusers/blob/main/src/diffusers/schedulers/scheduling_consistency_models.py#L294)

**パラメータ:**

sigma (`torch.Tensor`) : Karras sigma スケジュールにおける現在の sigma。

**戻り値:** `tuple[torch.Tensor, torch.Tensor]`

`c_skip`（現在のサンプルの重み）が最初の要素、`c_out`（consistency model の出力の重み）が2番目の要素である、2要素のタプルです。

[論文](https://huggingface.co/papers/2303.01469)の付録Cから、境界条件を強制するためにconsistency modelのパラメータ化で使用されるスケーリングを取得します。

> [!TIP] > `c_skip` と `c_out` の数式における `epsilon` は `sigma_min` に設定されています。

#### index_for_timestep[[diffusers.CMStochasticIterativeScheduler.index_for_timestep]]

```python
index_for_timestep(timestep: typing.Union[float, torch.Tensor], schedule_timesteps: typing.Optional[torch.Tensor] = None)
```

[ソース](https://github.com/huggingface/diffusers/blob/main/src/diffusers/schedulers/scheduling_consistency_models.py#L318)

**パラメータ:**

timestep (`float` または `torch.Tensor`) : スケジュール内で検索するタイムステップの値。

schedule_timesteps (`torch.Tensor`, *任意*) : 検索対象のタイムステップスケジュール。`None` の場合は `self.timesteps` を使用します。

**戻り値:** `int`

スケジュールにおけるタイムステップのインデックスです。最初のステップでは、スケジュールの途中から開始する場合（画像から画像への生成など）にシグマをスキップすることを避けるため、複数の一致が存在する場合は2番目のインデックスを返します。

与えられたタイムステップのタイムステップスケジュールにおけるインデックスを特定します。

#### scale_model_input[[diffusers.CMStochasticIterativeScheduler.scale_model_input]]

```python
scale_model_input(sample: Tensor, timestep: typing.Union[float, torch.Tensor])
```

[ソース](https://github.com/huggingface/diffusers/blob/main/src/diffusers/schedulers/scheduling_consistency_models.py#L136)

**パラメータ:**

sample (`torch.Tensor`) : 入力サンプル。

timestep (`float` または `torch.Tensor`) : 拡散チェーンにおける現在のタイムステップ。

**戻り値:** `torch.Tensor`

スケーリングされた入力サンプル。

`(sigma**2 + sigma_data**2) ** 0.5` によって、consistency model の入力をスケーリングします。

#### set_begin_index[[diffusers.CMStochasticIterativeScheduler.set_begin_index]]

```python
set_begin_index(begin_index: int = 0)
```

[ソース](https://github.com/huggingface/diffusers/blob/main/src/diffusers/schedulers/scheduling_consistency_models.py#L126)

**パラメータ:**

begin_index (`int`、デフォルトは`0`) : スケジューラの開始インデックス。

スケジューラの開始インデックスを設定します。この関数は、推論の前にパイプラインから実行する必要があります。

#### set_timesteps[[diffusers.CMStochasticIterativeScheduler.set_timesteps]]

```python
set_timesteps(num_inference_steps: int | None = None, device: typing.Union[str, torch.device] = None, timesteps: list[int] | None = None)
```

[ソース](https://github.com/huggingface/diffusers/blob/main/src/diffusers/schedulers/scheduling_consistency_models.py#L180)

**パラメータ:**

num_inference_steps (`int`, *任意*) : 事前学習済みモデルでサンプルを生成する際に使用される拡散ステップ数。

device (`str` または `torch.device`、*任意*) : timesteps を移動先とするデバイスです。`None` の場合、timesteps は移動されません。

timesteps (`list[int]`、*任意*) : 任意の間隔でタイムステップをサポートするために使用するカスタムタイムステップ。`None` の場合、タイムステップ間の等間隔というデフォルトのタイムステップ間隔戦略が使用されます。`timesteps` が渡された場合、`num_inference_steps` は `None` でなければなりません。

拡散チェーンで使用されるタイムステップを設定します（推論の実行前に実行します）。

#### sigma_to_t[[diffusers.CMStochasticIterativeScheduler.sigma_to_t]]

```python
sigma_to_t(sigmas: float | numpy.ndarray)
```

[ソース](https://github.com/huggingface/diffusers/blob/main/src/diffusers/schedulers/scheduling_consistency_models.py#L161)

**パラメータ:**

sigmas (`float` または `np.ndarray`) : 単一の Karras sigma または Karras sigma の配列。

**戻り値:** `np.ndarray`

スケーリングされた入力タイムステップ配列。

Karrasシグマから、consistency modelへの入力としてスケーリングされたタイムステップを取得します。

#### ステップ[[diffusers.CMStochasticIterativeScheduler.step]]

```python
step(model_output: Tensor, timestep: typing.Union[float, torch.Tensor], sample: Tensor, generator: typing.Optional[torch.Generator] = None, return_dict: bool = True)
```

[ソース](https://github.com/huggingface/diffusers/blob/main/src/diffusers/schedulers/scheduling_consistency_models.py#L364)

**パラメータ:**

model_output (`torch.Tensor`) : 学習済み拡散モデルからの直接の出力です。

timestep (`float` または `torch.Tensor`) : 拡散チェーンにおける現在のタイムステップ。

sample (`torch.Tensor`) : 拡散プロセスによって生成されたサンプルの現在のインスタンス。

generator (`torch.Generator`, *任意*) : 乱数生成器。

return_dict (`bool`、デフォルトは`True`) : [CMStochasticIterativeSchedulerOutput](/docs/diffusers/main/ja/api/schedulers/cm_stochastic_iterative#diffusers.schedulers.scheduling_consistency_models.CMStochasticIterativeSchedulerOutput)を返すか、`tuple`を返すかを指定します。

**戻り値:** [CMStochasticIterativeSchedulerOutput](/docs/diffusers/main/ja/api/schedulers/cm_stochastic_iterative#diffusers.schedulers.scheduling_consistency_models.CMStochasticIterativeSchedulerOutput) または `tuple`

`True` の場合、[CMStochasticIterativeSchedulerOutput](/docs/diffusers/main/ja/api/schedulers/cm_stochastic_iterative#diffusers.schedulers.scheduling_consistency_models.CMStochasticIterativeSchedulerOutput) が返され、それ以外の場合は、最初の要素がサンプルテンソルであるタプルが返されます。

前回のタイムステップからのサンプルを、SDEを逆方向に適用することで予測します。この関数は、学習済みモデルの出力（最もよく使われるのは予測ノイズ）から拡散過程を伝播させます。

## CMStochasticIterativeSchedulerOutput[[diffusers.schedulers.scheduling_consistency_models.CMStochasticIterativeSchedulerOutput]]

#### diffusers.schedulers.scheduling_consistency_models.CMStochasticIterativeSchedulerOutput[[diffusers.schedulers.scheduling_consistency_models.CMStochasticIterativeSchedulerOutput]]

```python
diffusers.schedulers.scheduling_consistency_models.CMStochasticIterativeSchedulerOutput(prev_sample: Tensor)
```

[ソース](https://github.com/huggingface/diffusers/blob/main/src/diffusers/schedulers/scheduling_consistency_models.py#L30)

**パラメータ:**

prev_sample (`torch.Tensor`、画像の場合は `(batch_size, num_channels, height, width)` の形状) : 前のタイムステップの計算済みサンプル `(x_{t-1})`。`prev_sample` は、デノイジングループの次のモデル入力として使用する必要があります。

スケジューラの`step`関数の出力クラス。