# TCDScheduler

[Trajectory Consistency Distillation](https://huggingface.co/papers/2402.19159), de Jianbin Zheng, Minghui Hu, Zhongyi Fan, Chaoyue Wang, Changxing Ding, Dacheng Tao y Tat-Jen Cham, introdujo un Strategic Stochastic Sampling (Algoritmo 4) capaz de generar buenas muestras en un pequeño número de pasos. Al distinguirlo como una iteración avanzada del multistep scheduler (Algoritmo 1) en los [Consistency Models](https://huggingface.co/papers/2303.01469), el Strategic Stochastic Sampling está específicamente diseñado para la función de consistencia de trayectoria.

El resumen del artículo es:

*Latent Consistency Model (LCM) extiende el Consistency Model al espacio latente y aprovecha la técnica de destilación de consistencia guiada para lograr un rendimiento impresionante en la aceleración de la síntesis de texto a imagen. Sin embargo, observamos que LCM tiene dificultades para generar imágenes con claridad y detalle intrincado a la vez. Para abordar esta limitación, inicialmente profundizamos y elucidamos las causas subyacentes. Nuestra investigación identifica que el problema principal proviene de errores en tres áreas distintas. En consecuencia, introducimos Trajectory Consistency Distillation (TCD), que abarca la función de consistencia de trayectoria y la muestreo estocástico estratégico. La función de consistencia de trayectoria reduce los errores de destilación ampliando el alcance de la condición de frontera de autoconsistencia y dotando a TCD de la capacidad de trazar con precisión toda la trayectoria del ODE de flujo de probabilidad. Además, el muestreo estocástico estratégico está diseñado específicamente para evitar los errores acumulados inherentes al muestreo de consistencia de múltiples pasos, y está meticulosamente adaptado para complementar el modelo TCD. Los experimentos demuestran que TCD no solo mejora significativamente la calidad de la imagen con bajos NFE, sino que también produce resultados más detallados en comparación con el modelo maestro con altos NFE.*

El código original se puede encontrar en [jabir-zheng/TCD](https://github.com/jabir-zheng/TCD).

## TCDScheduler[[diffusers.TCDScheduler]]

#### diffusers.TCDScheduler[[diffusers.TCDScheduler]]

```python
diffusers.TCDScheduler(num_train_timesteps: int = 1000, beta_start: float = 0.00085, beta_end: float = 0.012, beta_schedule: str = 'scaled_linear', trained_betas: numpy.ndarray | list[float] | None = None, original_inference_steps: int = 50, clip_sample: bool = False, clip_sample_range: float = 1.0, set_alpha_to_one: bool = True, steps_offset: int = 0, prediction_type: str = 'epsilon', thresholding: bool = False, dynamic_thresholding_ratio: float = 0.995, sample_max_value: float = 1.0, timestep_spacing: str = 'leading', timestep_scaling: float = 10.0, rescale_betas_zero_snr: bool = False)
```

[Fuente](https://github.com/huggingface/diffusers/blob/v0.43.0/src/diffusers/schedulers/scheduling_tcd.py#L141)

**Parámetros:**

num_train_timesteps (`int`, por defecto `1000`) : El número de pasos de difusión para entrenar el modelo.

beta_start (`float`, por defecto `0.00085`) : El valor inicial de `beta` para la inferencia.

beta_end (`float`, por defecto `0.012`) : El valor final de `beta`.

beta_schedule (`str`, por defecto `"scaled_linear"`) : La programación de beta, un mapeo desde un rango de beta hasta una secuencia de betas para dar pasos al modelo. Elija entre `linear`, `scaled_linear` o `squaredcos_cap_v2`.

trained_betas (`np.ndarray` o `list[float]`, *opcional*) : Pasa un array de betas directamente al constructor para omitir `beta_start` y `beta_end`.

original_inference_steps (`int`, por defecto `50`) : El número predeterminado de pasos de inferencia utilizados para generar un calendario de pasos de tiempo espaciados linealmente, del cual finalmente tomaremos `num_inference_steps` pasos de tiempo equiespaciados para formar el calendario de pasos de tiempo final.

clip_sample (`bool`, por defecto `False`) : Recorta la muestra predicha para la estabilidad numérica.

clip_sample_range (`float`, por defecto `1.0`) : La magnitud máxima para el recorte de muestras. Solo es válido cuando `clip_sample=True`.

set_alpha_to_one (`bool`, por defecto `True`) : Cada paso de difusión utiliza el valor del producto de alfas en ese paso y en el anterior. En el paso final no hay un alfa anterior. Cuando esta opción es `True`, el producto de alfas anterior se fija en `1`; de lo contrario, se utiliza el valor de alfa en el paso 0.

steps_offset (`int`, por defecto `0`) : Un desplazamiento que se suma a los pasos de inferencia, tal como lo requieren algunas familias de modelos.

prediction_type (`str`, defaults to `"epsilon"`) : Prediction type of the scheduler function; can be `epsilon` (predicts the noise of the diffusion process), `sample` (directly predicts the noisy sample`) or `v_prediction` (see section 2.4 of [Imagen Video](https://huggingface.co/papers/2210.02303) paper).

thresholding (`bool`, por defecto `False`) : Si se debe utilizar el método de "umbral dinámico". No es adecuado para modelos de difusión en el espacio latente, como Stable Diffusion.

dynamic_thresholding_ratio (`float`, por defecto `0.995`) : La proporción para el método de umbral dinámico. Solo es válido cuando `thresholding=True`.

sample_max_value (`float`, por defecto `1.0`) : El valor de umbral para el umbral dinámico. Solo es válido cuando `thresholding=True`.

timestep_spacing (`str`, por defecto `"leading"`) : La forma en que se deben escalar los pasos de tiempo. Consulte la Tabla 2 de [Common Diffusion Noise Schedules and Sample Steps are Flawed](https://huggingface.co/papers/2305.08891) para obtener más información.

timestep_scaling (`float`, por defecto `10.0`) : El factor por el que se multiplicarán los timesteps al calcular las condiciones de frontera del modelo de consistencia `c_skip` y `c_out`. Aumentar este valor reducirá el error de aproximación (aunque el error de aproximación con el valor por defecto de `10.0` ya es bastante pequeño).

rescale_betas_zero_snr (`bool`, por defecto `False`) : Si se deben reescalar los betas para tener un SNR terminal cero. Esto permite al modelo generar muestras muy brillantes y oscuras en lugar de limitarlo a muestras con un brillo medio. Relacionado de forma laxa con [`--offset_noise`](https://github.com/huggingface/diffusers/blob/74fd735eb073eb1d774b1ab4154a0876eb82f055/examples/dreambooth/train_dreambooth.py#L506).

`TCDScheduler` incorpora el `Strategic Stochastic Sampling` introducido por el artículo `Trajectory Consistency Distillation`, extendiendo el Multistep Consistency Sampling original para permitir la exploración de trayectorias sin restricciones.

Este código se basa en el repositorio oficial de TCD(https://github.com/jabir-zheng/TCD).

Este modelo hereda de [SchedulerMixin](/docs/diffusers/v0.43.0/es/api/schedulers/overview#diffusers.SchedulerMixin) y [ConfigMixin](/docs/diffusers/v0.43.0/es/api/configuration#diffusers.ConfigMixin). [~ConfigMixin](/docs/diffusers/v0.43.0/es/api/configuration#diffusers.ConfigMixin) se encarga de almacenar todos los atributos de configuración que se pasan en la función `__init__` del scheduler, como `num_train_timesteps`. Se pueden acceder mediante `scheduler.config.num_train_timesteps`. [SchedulerMixin](/docs/diffusers/v0.43.0/es/api/schedulers/overview#diffusers.SchedulerMixin) proporciona funcionalidad general de carga y guardado a través de las funciones [SchedulerMixin.save_pretrained()](/docs/diffusers/v0.43.0/es/api/schedulers/overview#diffusers.SchedulerMixin.save_pretrained) y [from_pretrained()](/docs/diffusers/v0.43.0/es/api/schedulers/overview#diffusers.SchedulerMixin.from_pretrained).

#### add_noise[[diffusers.TCDScheduler.add_noise]]

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

[Fuente](https://github.com/huggingface/diffusers/blob/v0.43.0/src/diffusers/schedulers/scheduling_tcd.py#L702)

**Parámetros:**

original_samples (`torch.Tensor`) : Las muestras originales a las que se les añadirá ruido.

noise (`torch.Tensor`) : El ruido que se añadirá a las muestras.

timesteps (`torch.IntTensor`) : Los pasos de tiempo que indican el nivel de ruido para cada muestra.

**Devuelve:** `torch.Tensor`

Las muestras ruidosas.

Añada ruido a las muestras originales según la magnitud del ruido en cada paso temporal (este es el proceso de difusión hacia adelante).

#### get_velocity[[diffusers.TCDScheduler.get_velocity]]

```python
get_velocity(sample: Tensor, noise: Tensor, timesteps: IntTensor)
```

[Fuente](https://github.com/huggingface/diffusers/blob/v0.43.0/src/diffusers/schedulers/scheduling_tcd.py#L745)

**Parámetros:**

sample (`torch.Tensor`) : La muestra de entrada.

noise (`torch.Tensor`) : El tensor de ruido.

timesteps (`torch.IntTensor`) : Los pasos de tiempo para el cálculo de la velocidad.

**Devuelve:** `torch.Tensor`

La velocidad calculada.

Calcule la predicción de velocidad a partir de la muestra y el ruido según la fórmula de velocidad.

#### index_for_timestep[[diffusers.TCDScheduler.index_for_timestep]]

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

[Fuente](https://github.com/huggingface/diffusers/blob/v0.43.0/src/diffusers/schedulers/scheduling_tcd.py#L263)

**Parámetros:**

timestep (`float` o `torch.Tensor`) : El valor de timestep a buscar en la programación.

schedule_timesteps (`torch.Tensor`, *opcional*) : El calendario de pasos de tiempo en el que buscar. Si es `None`, usa `self.timesteps`.

**Devuelve:** `int`

El índice del paso de tiempo en la programación. Para el primer paso, devuelve el segundo índice si existen múltiples coincidencias para evitar omitir una sigma al comenzar a mitad de la programación (p. ej., para imagen a imagen).

Encuentra el índice de un paso de tiempo dado en la programación de pasos de tiempo.

#### previous_timestep[[diffusers.TCDScheduler.previous_timestep]]

```python
previous_timestep(timestep: int)
```

[Fuente](https://github.com/huggingface/diffusers/blob/v0.43.0/src/diffusers/schedulers/scheduling_tcd.py#L790)

**Parámetros:**

timestep (`int`) : El paso de tiempo actual.

**Devuelve:** `int` o `torch.Tensor`

El paso de tiempo anterior.

Calcule el paso de tiempo anterior en la cadena de difusión.

#### scale_model_input[[diffusers.TCDScheduler.scale_model_input]]

```python
scale_model_input(sample: Tensor, timestep: typing.Union[int, torch.Tensor, NoneType] = None)
```

[Fuente](https://github.com/huggingface/diffusers/blob/v0.43.0/src/diffusers/schedulers/scheduling_tcd.py#L342)

**Parámetros:**

sample (`torch.Tensor`) : La muestra de entrada.

timestep (`int` o `torch.Tensor`, *opcional*) : El paso temporal actual en la cadena de difusión.

**Devuelve:** `torch.Tensor`

Una muestra de entrada escalada.

Garantiza la interoperabilidad con los programadores que necesitan escalar la entrada del modelo de desruido en función del paso temporal actual.

#### set_begin_index[[diffusers.TCDScheduler.set_begin_index]]

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

[Fuente](https://github.com/huggingface/diffusers/blob/v0.43.0/src/diffusers/schedulers/scheduling_tcd.py#L332)

**Parámetros:**

begin_index (`int`, por defecto `0`) : El índice inicial del programador.

Establece el índice inicial para el programador. Esta función debe ejecutarse desde la tubería antes de la inferencia.

#### set_timesteps[[diffusers.TCDScheduler.set_timesteps]]

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

[Fuente](https://github.com/huggingface/diffusers/blob/v0.43.0/src/diffusers/schedulers/scheduling_tcd.py#L432)

**Parámetros:**

num_inference_steps (`int`, *opcional*) : El número de pasos de difusión utilizados al generar muestras con un modelo preentrenado. Si se usa, `timesteps` debe ser `None`.

device (`str` o `torch.device`, *opcional*) : El dispositivo al que deben moverse los pasos de tiempo. Si es `None`, los pasos de tiempo no se mueven.

original_inference_steps (`int`, *opcional*) : El número original de pasos de inferencia, que se utilizará para generar un calendario de pasos de tiempo linealmente espaciado (que es diferente de la implementación estándar de `diffusers`). A continuación, tomaremos `num_inference_steps` pasos de tiempo de este calendario, espaciados uniformemente en términos de índices, y usaremos eso como nuestro calendario final de pasos de tiempo. Si no se establece, esto se ajustará por defecto al atributo `original_inference_steps`.

timesteps (`list[int]`, *opcional*) : Pasos de tiempo personalizados para admitir un espaciado arbitrario entre los pasos de tiempo. Si es `None`, se utiliza la estrategia de espaciado de pasos de tiempo predeterminada, que consiste en un espaciado igual entre los pasos de tiempo en la programación de pasos de tiempo de entrenamiento/destilación. Si se pasa `timesteps`, `num_inference_steps` debe ser `None`.

strength (`float`, por defecto `1.0`) : Se utiliza para determinar el número de pasos de tiempo (timesteps) empleados para la inferencia al usar img2img, inpaint, etc.

Establece los pasos discretos utilizados para la cadena de difusión (para ejecutarse antes de la inferencia).

#### paso[[diffusers.TCDScheduler.step]]

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

[Fuente](https://github.com/huggingface/diffusers/blob/v0.43.0/src/diffusers/schedulers/scheduling_tcd.py#L594)

**Parámetros:**

model_output (`torch.Tensor`) : La salida directa del modelo de difusión aprendido.

timestep (`int` o `torch.Tensor`) : El paso de tiempo discreto actual en la cadena de difusión.

sample (`torch.Tensor`) : Una instancia actual de una muestra creada por el proceso de difusión.

eta (`float`, por defecto `0.3`) : Un parámetro estocástico (denominado `gamma` en el artículo) utilizado para controlar la estocasticidad en cada paso. Cuando eta = 0, representa una muestreo determinista, mientras que eta = 1 indica un muestreo completamente estocástico.

generator (`torch.Generator`, *opcional*) : Un generador de números aleatorios.

return_dict (`bool`, por defecto `True`) : Si se devuelve un [TCDSchedulerOutput](/docs/diffusers/v0.43.0/es/api/schedulers/tcd#diffusers.schedulers.scheduling_tcd.TCDSchedulerOutput) o un `tuple`.

**Devuelve:** [TCDSchedulerOutput](/docs/diffusers/v0.43.0/es/api/schedulers/tcd#diffusers.schedulers.scheduling_tcd.TCDSchedulerOutput) o `tuple[torch.Tensor, torch.Tensor]`

If return_dict is `True`, [TCDSchedulerOutput](/docs/diffusers/v0.43.0/es/api/schedulers/tcd#diffusers.schedulers.scheduling_tcd.TCDSchedulerOutput) is returned, otherwise a tuple is returned containing the previous sample and the predicted noised sample.

Predice la muestra del paso de tiempo anterior invirtiendo el SDE. Esta función propaga el proceso de difusión desde las salidas del modelo aprendido (con mayor frecuencia, el ruido predicho).

## TCDSchedulerOutput[[diffusers.schedulers.scheduling_tcd.TCDSchedulerOutput]]

#### diffusers.schedulers.scheduling_tcd.TCDSchedulerOutput[[diffusers.schedulers.scheduling_tcd.TCDSchedulerOutput]]

```python
diffusers.schedulers.scheduling_tcd.TCDSchedulerOutput(prev_sample: Tensor, pred_noised_sample: typing.Optional[torch.Tensor] = None)
```

[Fuente](https://github.com/huggingface/diffusers/blob/v0.43.0/src/diffusers/schedulers/scheduling_tcd.py#L35)

**Parámetros:**

prev_sample (`torch.Tensor` de forma `(batch_size, num_channels, height, width)` para imágenes) : Muestra `(x_{t-1})` calculada del paso de tiempo anterior. `prev_sample` debe usarse como entrada del modelo en la siguiente iteración del bucle de desruido.

pred_noised_sample (`torch.Tensor` de forma `(batch_size, num_channels, height, width)` para imágenes, *opcional*) : La muestra con ruido predicha `(x_{s})` basada en la salida del modelo del paso de tiempo actual.

Clase de salida para la salida de la función `step` del programador.