
    biA                     h   d dl Z d dlmZmZmZmZmZmZ d dlZddl	m
Z
 ddlmZ ddlmZmZ erddlmZ  e       Zerd d	lmZ d d
lmZ ndZdZddej2                  dej2                  dedeej2                  ej2                  f   fdZdeej2                     dej2                  fdZ G d de      Zy)    N)TYPE_CHECKINGDictListOptionalTupleUnion   )register_to_config)is_kornia_available   )BaseGuidancerescale_noise_cfg)
BlockState)pyrup)build_laplacian_pyramidv0v1upcast_to_doublereturnc                    t        t        dt        | j                                    }|r,| j                  }| j                         |j                         }} t        j                  j                  j                  ||      }| |z  j                  |d      |z  }| |z
  }|r"|j                        }|j                  |      }||fS )z
    Project vector v0 onto vector v1, returning the parallel and orthogonal components of v0. Implementation from paper
    (Algorithm 2).
    r   )dimT)r   keepdim)listrangelenshapedtypedoubletorchnn
functional	normalizesumto)r   r   r   all_dims_but_firstr   v0_parallelv0_orthogonals          i/home/cdr/jupyterlab/.venv/lib/python3.12/site-packages/diffusers/guiders/frequency_decoupled_guidance.pyprojectr)   (   s     eAs288}56biikB				&	&r/A	&	BB7--$6-EJK$M!nnU+%((/%%    pyramidc                 n    | d   }t        t        |       dz
  dd      D ]  }t        |      | |   z   } |S )z
    Recovers the data space latents from the Laplacian pyramid frequency space. Implementation from the paper
    (Algorihtm 2).
    r	   )r   r   upsample_and_blur_func)r+   imgis      r(   build_image_from_pyramidr1   =   sF     "+C3w<!#R, 7$S)GAJ67Jr*   c                       e Zd ZdZddgZeddgddddd	d
dfdeee   e	e   f   deeee   e	e   f   de
eeee   e	e   f      dedeeee   e	e   f   deeee   e	e   f   dedef fd       Z	 dd
dde
eeeee	eef   f   f      ded   fdZddej"                  de
ej"                     dej"                  fdZedefd       Zedefd       ZdefdZdedefdZ xZS ) FrequencyDecoupledGuidancea*  
    Frequency-Decoupled Guidance (FDG): https://huggingface.co/papers/2506.19713

    FDG is a technique similar to (and based on) classifier-free guidance (CFG) which is used to improve generation
    quality and condition-following in diffusion models. Like CFG, during training we jointly train the model on both
    conditional and unconditional data, and use a combination of the two during inference. (If you want more details on
    how CFG works, you can check out the CFG guider.)

    FDG differs from CFG in that the normal CFG prediction is instead decoupled into low- and high-frequency components
    using a frequency transform (such as a Laplacian pyramid). The CFG update is then performed in frequency space
    separately for the low- and high-frequency components with different guidance scales. Finally, the inverse
    frequency transform is used to map the CFG frequency predictions back to data space (e.g. pixel space for images)
    to form the final FDG prediction.

    For images, the FDG authors found that using low guidance scales for the low-frequency components retains sample
    diversity and realistic color composition, while using high guidance scales for high-frequency components enhances
    sample quality (such as better visual details). Therefore, they recommend using low guidance scales (low w_low) for
    the low-frequency components and high guidance scales (high w_high) for the high-frequency components. As an
    example, they suggest w_low = 5.0 and w_high = 10.0 for Stable Diffusion XL (see Table 8 in the paper).

    As with CFG, Diffusers implements the scaling and shifting on the unconditional prediction based on the [Imagen
    paper](https://huggingface.co/papers/2205.11487), which is equivalent to what the original CFG paper proposed in
    theory. [x_pred = x_uncond + scale * (x_cond - x_uncond)]

    The `use_original_formulation` argument can be set to `True` to use the original CFG formulation mentioned in the
    paper. By default, we use the diffusers-native implementation that has been in the codebase for a long time.

    Args:
        guidance_scales (`List[float]`, defaults to `[10.0, 5.0]`):
            The scale parameter for frequency-decoupled guidance for each frequency component, listed from highest
            frequency level to lowest. Higher values result in stronger conditioning on the text prompt, while lower
            values allow for more freedom in generation. Higher values may lead to saturation and deterioration of
            image quality. The FDG authors recommend using higher guidance scales for higher frequency components and
            lower guidance scales for lower frequency components (so `guidance_scales` should typically be sorted in
            descending order).
        guidance_rescale (`float` or `List[float]`, defaults to `0.0`):
            The rescale factor applied to the noise predictions. This is used to improve image quality and fix
            overexposure. Based on Section 3.4 from [Common Diffusion Noise Schedules and Sample Steps are
            Flawed](https://huggingface.co/papers/2305.08891). If a list is supplied, it should be the same length as
            `guidance_scales`.
        parallel_weights (`float` or `List[float]`, *optional*):
            Optional weights for the parallel component of each frequency component of the projected CFG shift. If not
            set, the weights will default to `1.0` for all components, which corresponds to using the normal CFG shift
            (that is, equal weights for the parallel and orthogonal components). If set, a value in `[0, 1]` is
            recommended. If a list is supplied, it should be the same length as `guidance_scales`.
        use_original_formulation (`bool`, defaults to `False`):
            Whether to use the original formulation of classifier-free guidance as proposed in the paper. By default,
            we use the diffusers-native implementation that has been in the codebase for a long time. See
            [~guiders.classifier_free_guidance.ClassifierFreeGuidance] for more details.
        start (`float` or `List[float]`, defaults to `0.0`):
            The fraction of the total number of denoising steps after which guidance starts. If a list is supplied, it
            should be the same length as `guidance_scales`.
        stop (`float` or `List[float]`, defaults to `1.0`):
            The fraction of the total number of denoising steps after which guidance stops. If a list is supplied, it
            should be the same length as `guidance_scales`.
        guidance_rescale_space (`str`, defaults to `"data"`):
            Whether to performance guidance rescaling in `"data"` space (after the full FDG update in data space) or in
            `"freq"` space (right after the CFG update, for each freq level). Note that frequency space rescaling is
            speculative and may not produce expected results. If `"data"` is set, the first `guidance_rescale` value
            will be used; otherwise, per-frequency-level guidance rescale values will be used if available.
        upcast_to_double (`bool`, defaults to `True`):
            Whether to upcast certain operations, such as the projection operation when using `parallel_weights`, to
            float64 when performing guidance. This may result in better performance at the cost of increased runtime.
    	pred_condpred_uncondg      $@g      @        NF      ?dataTguidance_scalesguidance_rescaleparallel_weightsuse_original_formulationstartstopguidance_rescale_spacer   c	                    t         st        d      t        |t              r|n
t	        |      }	t        |t              r|n
t        |      }
t        |   |	|
       || _        t        |      | _
        t        |t              r|g| j                  z  | _        nNt        |      | j                  k(  r|| _        n.t        dt        |       dt        | j                         d      |dvrt        d| d      || _        |dg| j                  z  | _        ntt        |t              r|g| j                  z  | _        nNt        |      | j                  k(  r|| _        n.t        d	t        |       dt        | j                         d      || _        || _        t        |t              r|g| j                  z  | _        nNt        |      | j                  k(  r|| _        n.t        d
t        |       dt        | j                         d      t        |t              r|g| j                  z  | _        y t        |      | j                  k(  r|| _        y t        dt        |       dt        | j                         d      )NzThe `FrequencyDecoupledGuidance` guider cannot be instantiated because the `kornia` library on which it depends is not available in the current environment. You can install `kornia` with `pip install kornia`.z`guidance_rescale` has length z7 but should have the same length as `guidance_scales` ())r8   freqzGuidance rescale space is z% but must be one of `data` or `freq`.r7   z`parallel_weights` has length z`start` has length z`stop` has length )_CAN_USE_KORNIAImportError
isinstancefloatminmaxsuper__init__r9   r   levelsr:   
ValueErrorr?   r;   r<   r   guidance_startguidance_stop)selfr9   r:   r;   r<   r=   r>   r?   r   	min_startmax_stop	__class__s              r(   rJ   z#FrequencyDecoupledGuidance.__init__   s      (u5E3u:	%dE24D	H-./*&.%5$6$DD!!"dkk1$4D!05E1F0G H&&)$*>*>&?%@C  ")99,-C,DDij  '=##%(EDKK$7D!(%0%5$6$DD!!"dkk1$4D!05E1F0G H&&)$*>*>&?%@C 
 )A% 0eU##('DKK"7DZ4;;&"'D%c%j\ 2,,-.a1  dE""&$++!5DY$++%!%D$SYK 0,,-.a1 r*   r   input_fieldsr   c                     || j                   }| j                  dk(  rdgnddg}g }t        | j                        D ]7  }| j                  ||||   | j                  |         }|j                  |       9 |S )Nr   r   )_input_fieldsnum_conditionsr   _prepare_batch_input_predictionsappend)rO   r8   rS   tuple_indicesdata_batchesr0   
data_batchs          r(   prepare_inputsz)FrequencyDecoupledGuidance.prepare_inputs   s     --L#22a7aVt**+ 	,A,,\4qAQSWSjSjklSmnJ
+	, r*   c                    d }| j                         s|}|i fS t        || j                        }t        || j                        }g }t        | j                  | j
                  | j                        }t        |      D ]  \  }\  }	}
}| j                  |      r||   }||   }||z
  }t        j                  |
d      s"t        ||| j                        \  }}|
|z  |z   }| j                  r|n|}||	|z  z   }| j                  dk(  r|dkD  rt        |||      }|j!                  |       |j!                          t#        |      }| j                  dk(  r,| j                  d   dkD  rt        ||| j                  d         }|i fS )Nr7   rB   r6   r8   r   )_is_fdg_enabledbuild_laplacian_pyramid_funcrK   zipr9   r;   r:   	enumerate_is_fdg_enabled_for_levelmathiscloser)   r   r<   r?   r   rY   r1   )rO   r4   r5   predpred_cond_pyramidpred_uncond_pyramidpred_guided_pyramid
parameterslevelguidance_scaleparallel_weightr:   pred_cond_freqpred_uncond_freqshiftshift_parallelshift_orthogonals                    r(   forwardz"FrequencyDecoupledGuidance.forward   s   ##%DV RxQ !=Y T">{DKK"X #%T1143H3H$J_J_`JNWXbNc ?JJ9I11%8%6u%=N':5'A$*-==E  <<=;B5.Z^ZoZo;p8(8 /. @CS S .2-J-J>P`D.5"88D22f<AQTWAW0~GWX (..t4 (..~>1?6 ,,?@D **f49N9Nq9QTW9W(y$:O:OPQ:RSRxr*   c                      | j                   dk(  S Nr   )_count_prepared)rO   s    r(   is_conditionalz)FrequencyDecoupledGuidance.is_conditional  s    ##q((r*   c                 4    d}| j                         r|dz  }|S ru   )r_   )rO   rV   s     r(   rV   z)FrequencyDecoupledGuidance.num_conditions  s#    !aNr*   c                    | j                   syd}| j                  ^t        | j                  | j                  z        }t        | j                  | j                  z        }|| j
                  cxk  xr |k  nc }d}| j                  rt        d | j                  D              }nt        d | j                  D              }|xr | S )NFTc              3   H   K   | ]  }t        j                  |d         yw)r6   Nrd   re   .0rl   s     r(   	<genexpr>z=FrequencyDecoupledGuidance._is_fdg_enabled.<locals>.<genexpr>1       h4<<<h    "c              3   H   K   | ]  }t        j                  |d         yw)r7   Nr{   r|   s     r(   r~   z=FrequencyDecoupledGuidance._is_fdg_enabled.<locals>.<genexpr>3  r   r   )	_enabled_num_inference_stepsint_start_stop_stepr<   allr9   )rO   is_within_rangeskip_start_stepskip_stop_stepis_closes        r(   r_   z*FrequencyDecoupledGuidance._is_fdg_enabled%  s    }}$$0!$++0I0I"IJO d.G.G!GHN-LnLO((hSWSgSghhHhSWSgSghhH/x</r*   rk   c                    | j                   syd}| j                  dt        | j                  |   | j                  z        }t        | j                  |   | j                  z        }|| j
                  cxk  xr |k  nc }d}| j                  r$t        j                  | j                  |   d      }n#t        j                  | j                  |   d      }|xr | S )NFTr6   r7   )
r   r   r   rM   rN   r   r<   rd   re   r9   )rO   rk   r   r   r   r   s         r(   rc   z4FrequencyDecoupledGuidance._is_fdg_enabled_for_level7  s    }}$$0!$"5"5e"<t?X?X"XYO !3!3E!:T=V=V!VWN-LnLO((||D$8$8$?EH||D$8$8$?EH/x</r*   )N)__name__
__module____qualname____doc__rX   r
   r   r   rF   r   r   boolstrrJ   r   r]   r   Tensorrs   propertyrw   r   rV   r_   rc   __classcell__)rR   s   @r(   r3   r3   I   s   ?B &}5 >B3KDGNR).9<8;&,!%LtE{E%L89L  tE{E%L @AL #5UU5\)I#JK	L
 #'L UDKu56L E4;e45L !$L L L^ dh 08c5eTWY\T\oI]C^>^9_0`	l	/ /HU\\<R /^c^j^j /b ) ) )   0 0$0s 0t 0r*   r3   )T)rd   typingr   r   r   r   r   r   r   configuration_utilsr
   utilsr   guider_utilsr   r   "modular_pipelines.modular_pipeliner   rC   kornia.geometryr   r.   kornia.geometry.transformr   r`   r   r   r)   r1   r3    r*   r(   <module>r      s     D D  4 ' 9 ? &' ?a!#' & &%,, &$ &RWX]XdXdfkfrfrXrRs &*	d5<<&8 	U\\ 	~0 ~0r*   