
    +h:              	           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Jr  \(       a  SSKJr   " S S	\5      rSS
\R"                  S\R"                  S\S\R"                  4S jjrg)    N)TYPE_CHECKINGDictListOptionalTupleUnion   )register_to_config   )BaseGuidancerescale_noise_cfg)
BlockStatec                   J  ^  \ rS rSrSrSS/r\      SS\S\S\S\	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rU =r$ )ClassifierFreeZeroStarGuidance   a  
Classifier-free Zero* (CFG-Zero*): https://huggingface.co/papers/2503.18886

This is an implementation of the Classifier-Free Zero* guidance technique, which is a variant of classifier-free
guidance. It proposes zero initialization of the noise predictions for the first few steps of the diffusion
process, and also introduces an optimal rescaling factor for the noise predictions, which can help in improving the
quality of generated images.

The authors of the paper suggest setting zero initialization in the first 4% of the inference steps.

Args:
    guidance_scale (`float`, defaults to `7.5`):
        The scale parameter for classifier-free guidance. 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.
    zero_init_steps (`int`, defaults to `1`):
        The number of inference steps for which the noise predictions are zeroed out (see Section 4.2).
    guidance_rescale (`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).
    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`, defaults to `0.01`):
        The fraction of the total number of denoising steps after which guidance starts.
    stop (`float`, defaults to `0.2`):
        The fraction of the total number of denoising steps after which guidance stops.
	pred_condpred_uncondguidance_scalezero_init_stepsguidance_rescaleuse_original_formulationstartstopc                 T   > [         TU ]  XV5        Xl        X l        X0l        X@l        g N)super__init__r   r   r   r   )selfr   r   r   r   r   r   	__class__s          n/home/james-whalen/.local/lib/python3.13/site-packages/diffusers/guiders/classifier_free_zero_star_guidance.pyr   'ClassifierFreeZeroStarGuidance.__init__>   s*     	%,. 0(@%    datar   input_fieldsreturnc                     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_conditionsrange_prepare_batch_input_predictionsappend)r   r#   r$   tuple_indicesdata_batchesi
data_batchs          r    prepare_inputs-ClassifierFreeZeroStarGuidance.prepare_inputsO   s     --L#22a7aVt**+A,,\AQSWSjSjklSmnJ
+ , r"   c                    S nU R                   U R                  :  a  [        R                  " U5      nOU R	                  5       (       d  UnOUR                  S5      nUR                  S5      n[        XE5      nUR                  " S/S[        UR                  5      S-
  -  Q76 nX&-  nX-
  nU R                  (       a  UOUnX0R                  U-  -   nU R                  S:  a  [        X1U R                  5      nU0 4$ )Nr   )r           )_stepr   torch
zeros_like_is_cfg_enabledflattencfg_zero_star_scaleviewlenshaper   r   r   r   )r   r   r   predpred_cond_flatpred_uncond_flatalphashifts           r    forward&ClassifierFreeZeroStarGuidance.forward\   s    ::,,,##I.D%%''D&..q1N*2215'IEJJrFDC	,@1,D$EFE%-K+E $ = =9;D--55D  3&$Td6K6KLDRxr"   c                      U R                   S:H  $ Nr   )_count_prepared)r   s    r    is_conditional-ClassifierFreeZeroStarGuidance.is_conditionalr   s    ##q((r"   c                 >    SnU R                  5       (       a  US-  nU$ rG   )r9   )r   r(   s     r    r(   -ClassifierFreeZeroStarGuidance.num_conditionsv   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"  [        R                  " U R                  S5      nO![        R                  " U R                  S5      nU=(       a    U(       + $ )NFTr5         ?)
_enabled_num_inference_stepsint_start_stopr6   r   mathiscloser   )r   is_within_rangeskip_start_stepskip_stop_stepis_closes        r    r9   .ClassifierFreeZeroStarGuidance._is_cfg_enabled}   s    }}$$0!$++0I0I"IJO d.G.G!GHN-LLnLO((||D$7$7=H||D$7$7=H/x</r"   )r   r   r   r   )g      @r   r5   Fr5   rN   r   )__name__
__module____qualname____firstlineno____doc__r+   r
   floatrQ   boolr   r   r   strr   r   r   r1   r7   TensorrD   propertyrI   r(   r9   __static_attributes____classcell__)r   s   @r    r   r      s?   > &}5 !$ "%).AA A  	A
 #'A A A A" dh 08c5eTWY\T\oI]C^>^9_0`	l	 HU\\<R ^c^j^j , ) ) )   0 0 0r"   r   conduncondepsr%   c                     U R                   nU R                  5       n UR                  5       n[        R                  " X-  SSS9n[        R                  " US-  SSS9U-   nXE-  nUR	                  US9$ )Nr   T)dimkeepdimr	   )dtype)rm   r`   r7   sumto)rg   rh   ri   
cond_dtypedot_productsquared_normscales          r    r;   r;      si    J::<D\\^F))DMq$?K99VQYAt<sBL&E88*8%%r"   )g:0yE>)rT   typingr   r   r   r   r   r   r7   configuration_utilsr
   guider_utilsr   r   "modular_pipelines.modular_pipeliner   r   rc   r`   r;    r"   r    <module>ry      s`     D D  4 9 ?q0\ q0h&ell &ELL &u &X]XdXd &r"   