
    +hA                        S SK r S SKJrJrJrJrJrJr  S SKrSSK	J
r
  SSKJr  SSKJrJr  \(       a  SSKJr  \" 5       r\(       a  S S	KJr  S S
KJr  OSrSrSS\R2                  S\R2                  S\S\\R2                  \R2                  4   4S jjrS\\R2                     S\R2                  4S jr " S S\5      rg)    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                    [        [        S[        U R                  5      5      5      nU(       a+  U R                  nU R                  5       UR                  5       p[        R                  R                  R                  XS9nX-  R                  USS9U-  nX-
  nU(       a"  UR                  W5      nUR                  U5      nXV4$ )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          h/home/james-whalen/.local/lib/python3.13/site-packages/diffusers/guiders/frequency_decoupled_guidance.pyprojectr)   (   s     eAs288}56biikB				&	&r	&	BB7--$6-EJK$M!nnU+%((/%%    pyramidc                 p    U S   n[        [        U 5      S-
  SS5       H  n[        U5      X   -   nM     U$ )zz
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   =   s?     "+C3w<!#R,$S)GJ6 -Jr*   c                     ^  \ rS rSrSrSS/r\SS/SSS	SS
SS4S\\\	   \
\	   4   S\\	\\	   \
\	   4   S\\\	\\	   \
\	   4      S\S\\	\\	   \
\	   4   S\\	\\	   \
\	   4   S\S\4U 4S jjj5       r S!SSS\\\\\\
\\4   4   4      S\S   4S jjrS!S\R$                  S\\R$                     S\R$                  4S jjr\S\4S j5       r\S\4S j5       rS\4S jrS\S\4S jrS rU =r$ )"FrequencyDecoupledGuidanceI   aF  
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	                 J  > [         (       d  [        S5      e[        U[        5      (       a  UO
[	        U5      n	[        U[        5      (       a  UO
[        U5      n
[        TU ]  X5        Xl        [        U5      U l
        [        U[        5      (       a  U/U R                  -  U l        ON[        U5      U R                  :X  a  X l        O.[        S[        U5       S[        U R                  5       S35      eUS;  a  [        SU S35      eXpl        Uc  S/U R                  -  U l        Oy[        U[        5      (       a  U/U R                  -  U l        ON[        U5      U R                  :X  a  X0l        O.[        S	[        U5       S[        U R                  5       S35      eX@l        Xl        [        U[        5      (       a  U/U R                  -  U l        ON[        U5      U R                  :X  a  XPl        O.[        S
[        U5       S[        U R                  5       S35      e[        U[        5      (       a  U/U R                  -  U l        g [        U5      U R                  :X  a  X`l        g [        S[        U5       S[        U R                  5       S35      e)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` ())r9   freqzGuidance rescale space is z% but must be one of `data` or `freq`.r8   z`parallel_weights` has length z`start` has length z`stop` has length )_CAN_USE_KORNIAImportError
isinstancefloatminmaxsuper__init__r:   r   levelsr;   
ValueErrorr@   r<   r=   r   guidance_startguidance_stop)selfr:   r;   r<   r=   r>   r?   r@   r   	min_startmax_stop	__class__s              r(   rK   #FrequencyDecoupledGuidance.__init__   s      (u55E3u:	%dE224D	-./*&..%5$6$DD!!"dkk1$4!05E1F0G H&&)$*>*>&?%@C  ")99,-C,DDij  '=##%(EDKK$7D!(%00%5$6$DD!!"dkk1$4!05E1F0G H&&)$*>*>&?%@C 
 )A% 0eU###('DKK"7DZ4;;&"'%c%j\ 2,,-.a1  dE"""&$++!5DY$++%!%$SYK 0,,-.a1 r*   r   input_fieldsr   c                     Uc  U R                   nU R                  S:X  a  S/OSS/n/ n[        U R                  5       H6  nU R                  X!X5   U R                  U   5      nUR                  U5        M8     U$ )Nr   r   )_input_fieldsnum_conditionsr   _prepare_batch_input_predictionsappend)rP   r9   rU   tuple_indicesdata_batchesr0   
data_batchs          r(   prepare_inputs)FrequencyDecoupledGuidance.prepare_inputs   s     --L#22a7aVt**+A,,\AQSWSjSjklSmnJ
+ , r*   c                 0   S nU R                  5       (       d  UnU0 4$ [        XR                  5      n[        X R                  5      n/ n[        U R                  U R
                  U R                  5      n[        U5       H  u  nu  pnU R                  U5      (       a  XH   nXX   nX-
  n[        R                  " U
S5      (       d   [        XU R                  5      u  nnX-  U-   nU R                  (       a  UOUnX9U-  -   nU R                  S:X  a  US:  a  [        X<U5      nUR!                  U5        M  UR!                  W5        M     [#        U5      nU R                  S:X  a,  U R                  S   S:  a  [        X1U R                  S   5      nU0 4$ )Nr8   rC   r7   r9   r   )_is_fdg_enabledbuild_laplacian_pyramid_funcrL   zipr:   r<   r;   	enumerate_is_fdg_enabled_for_levelmathiscloser)   r   r=   r@   r   r[   r1   )rP   r5   r6   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(   forward"FrequencyDecoupledGuidance.forward   s   ##%%DV RxQ !=Y T">{KK"X #%T1143H3H$J_J_`JNWXbNcJJ9I11%88%6%=N':'A$*=E  <<==;B5Z^ZoZo;p8(8 / @CS S .2-J-J>P`D5"88D22f<AQTWAW0GWX (..t4 (..~>1 Od6 ,,?@D **f49N9Nq9QTW9W($:O:OPQ:RSRxr*   c                      U R                   S:H  $ Nr   )_count_prepared)rP   s    r(   is_conditional)FrequencyDecoupledGuidance.is_conditional  s    ##q((r*   c                 >    SnU R                  5       (       a  US-  nU$ ry   )rb   )rP   rX   s     r(   rX   )FrequencyDecoupledGuidance.num_conditions  s&    !!aNr*   c                    U R                   (       d  gSnU R                  bb  [        U R                  U R                  -  5      n[        U R                  U R                  -  5      nX R
                  s=:*  =(       a    U:  Os  nSnU R                  (       a  [        S U R                   5       5      nO[        S U R                   5       5      nU=(       a    U(       + $ )NFTc              3   P   #    U  H  n[         R                  " US 5      v   M     g7f)r7   Nrg   rh   .0ro   s     r(   	<genexpr>=FrequencyDecoupledGuidance._is_fdg_enabled.<locals>.<genexpr>1        hSg4<<<<Sg   $&c              3   P   #    U  H  n[         R                  " US 5      v   M     g7f)r8   Nr   r   s     r(   r   r   3  r   r   )	_enabled_num_inference_stepsint_start_stop_stepr=   allr:   )rP   is_within_rangeskip_start_stepskip_stop_stepis_closes        r(   rb   *FrequencyDecoupledGuidance._is_fdg_enabled%  s    }}$$0!$++0I0I"IJO d.G.G!GHN-LLnLO((hSWSgSghhHhSWSgSghhH/x</r*   rn   c                    U R                   (       d  gSnU R                  bh  [        U R                  U   U R                  -  5      n[        U R                  U   U R                  -  5      nX0R
                  s=:*  =(       a    U:  Os  nSnU R                  (       a%  [        R                  " U R                  U   S5      nO$[        R                  " U R                  U   S5      nU=(       a    U(       + $ )NFTr7   r8   )
r   r   r   rN   rO   r   r=   rg   rh   r:   )rP   rn   r   r   r   r   s         r(   rf   4FrequencyDecoupledGuidance._is_fdg_enabled_for_level7  s    }}$$0!$"5"5e"<t?X?X"XYO !3!3E!:T=V=V!VWN-LLnLO((||D$8$8$?EH||D$8$8$?EH/x</r*   )	r;   r@   r:   rN   rO   rL   r<   r   r=   )N)__name__
__module____qualname____firstlineno____doc__rZ   r
   r   r   rG   r   r   boolstrrK   r   r_   r   Tensorrv   propertyr{   r   rX   rb   rf   __static_attributes____classcell__)rS   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 0 0r*   r3   )T)rg   typingr   r   r   r   r   r   r   configuration_utilsr
   utilsr   guider_utilsr   r   "modular_pipelines.modular_pipeliner   rD   kornia.geometryr   r.   kornia.geometry.transformr   rc   r   r   r)   r1   r3    r*   r(   <module>r      s     D D  4 ' 9 ? &' ?a!#' & &%,, &$ &RWX]XdXdfkfrfrXrRs &*	d5<<&8 	U\\ 	~0 ~0r*   