
    6biO&                         S r SSKJs  Jr  SSKJr  SSKJr  SSK	J
r
  \" 5       \
" SS/ S9 " S	 S
\R                  5      5       5       r\R                   R                  S\R                  5      \l         g)zFTRL optimizer implementation.    N)	optimizer)register_keras_serializable)keras_exportz"keras.optimizers.experimental.Ftrlzkeras.optimizers.Ftrl)v1c                   n   ^  \ rS rSrSr                SU 4S jjrU 4S jrS rU 4S jrSr	U =r
$ )	Ftrl   a
  Optimizer that implements the FTRL algorithm.

"Follow The Regularized Leader" (FTRL) is an optimization algorithm
developed at Google for click-through rate prediction in the early 2010s. It
is most suitable for shallow models with large and sparse feature spaces.
The algorithm is described by
[McMahan et al., 2013](https://research.google.com/pubs/archive/41159.pdf).
The TF-Keras version has support for both online L2 regularization
(the L2 regularization described in the paper
above) and shrinkage-type L2 regularization
(which is the addition of an L2 penalty to the loss function).

Initialization:

```python
n = 0
sigma = 0
z = 0
```

Update rule for one variable `w`:

```python
prev_n = n
n = n + g ** 2
sigma = (n ** -lr_power - prev_n ** -lr_power) / lr
z = z + g - sigma * w
if abs(z) < lambda_1:
  w = 0
else:
  w = (sgn(z) * lambda_1 - z) / ((beta + sqrt(n)) / alpha + lambda_2)
```

Notation:

- `lr` is the learning rate
- `g` is the gradient for the variable
- `lambda_1` is the L1 regularization strength
- `lambda_2` is the L2 regularization strength
- `lr_power` is the power to scale n.

Check the documentation for the `l2_shrinkage_regularization_strength`
parameter for more details when shrinkage is enabled, in which case gradient
is replaced with a gradient with shrinkage.

Args:
    learning_rate: A `Tensor`, floating point value, a schedule that is a
        `tf.keras.optimizers.schedules.LearningRateSchedule`, or a callable
         that takes no arguments and returns the actual value to use. The
         learning rate.  Defaults to `0.001`.
    learning_rate_power: A float value, must be less or equal to zero.
        Controls how the learning rate decreases during training. Use zero
        for a fixed learning rate.
    initial_accumulator_value: The starting value for accumulators. Only
        zero or positive values are allowed.
    l1_regularization_strength: A float value, must be greater than or equal
        to zero. Defaults to `0.0`.
    l2_regularization_strength: A float value, must be greater than or equal
        to zero. Defaults to `0.0`.
    l2_shrinkage_regularization_strength: A float value, must be greater
        than or equal to zero. This differs from L2 above in that the L2
        above is a stabilization penalty, whereas this L2 shrinkage is a
        magnitude penalty. When input is sparse shrinkage will only happen
        on the active weights.
    beta: A float value, representing the beta value from the paper.
        Defaults to 0.0.
    {{base_optimizer_keyword_args}}
c                   > [         TU ]  " S	UUU	U
UUUUUS.	UD6  US:  a  [        SU S35      eUS:  a  [        SU S35      eUS:  a  [        SU S35      eUS:  a  [        SU S35      eUS:  a  [        SU S35      eU R                  U5      U l        X l        X0l        X@l        XPl        UU l	        Xpl
        g )
N)	nameweight_decayclipnorm	clipvalueglobal_clipnormuse_emaema_momentumema_overwrite_frequencyjit_compile        z^`initial_accumulator_value` needs to be positive or zero. Received: initial_accumulator_value=.zR`learning_rate_power` needs to be negative or zero. Received: learning_rate_power=z``l1_regularization_strength` needs to be positive or zero. Received: l1_regularization_strength=z``l2_regularization_strength` needs to be positive or zero. Received: l2_regularization_strength=zt`l2_shrinkage_regularization_strength` needs to be positive or zero. Received: l2_shrinkage_regularization_strength= )super__init__
ValueError_build_learning_rate_learning_ratelearning_rate_powerinitial_accumulator_valuel1_regularization_strengthl2_regularization_strength$l2_shrinkage_regularization_strengthbeta)selflearning_rater   r   r   r   r    r!   r   r   r   r   r   r   r   r   r   kwargs	__class__s                     V/home/james-whalen/.local/lib/python3.13/site-packages/tf_keras/src/optimizers/ftrl.pyr   Ftrl.__init__d   sH   ( 	 	
%+%$;#	
 	
 %s*7,-Q0 
 $'':&;1>  &+8-.a1 
 &+8-.a1 
 0#589<  #77F#6 )B&*D'*D'0 	1 	    c                   > [         TU ]  U5        [        U S5      (       a  U R                  (       a  g/ U l        / U l        U H  nU R                  R                  U R                  US[        R                  " [        R                  " UR                  U R                  S9UR                  S9S95        U R
                  R                  U R                  USS95        M     S	U l        g)
zgInitialize optimizer variables.

Args:
  var_list: list of model variables to build Ftrl variables on.
_builtNaccumulator)dimsvalue)dtype)model_variablevariable_nameinitial_valuelinear)r/   r0   T)r   buildhasattrr*   _accumulators_linearsappendadd_variable_from_referencetfcastfillshaper   r.   )r"   var_listvarr%   s      r&   r3   
Ftrl.build   s     	h4""t{{C%%00#&"/"$''!$$2P2P "ii	# 1 	 MM  00#&h 1  $ r(   c                    [         R                  " U R                  UR                  5      nU R	                  U5      nU R
                  U R                  U      nU R                  U R                  U      nU R                  nU R                  nXR                  SU-  -  -   nUSU R                  -  U-  -   n	U[         R                  " US5      -   n
UR                  U	[         R                  " X* 5      [         R                  " XW* 5      -
  U-  U-  -
  5        [         R                  " X* 5      U-  SU-  -   n[         R                  " UU R                  * U R                  5      nUR!                  X-
  U-  5        UR!                  U
5        g)z=Update step given gradient and the associated model variable.g       @   N)r9   r:   r#   r.   _var_keyr5   _index_dictr6   r   r   r!   r    pow
assign_addclip_by_valuer   assign)r"   gradientvariablelrvar_keyaccumr2   lr_powerl2_reggrad_to_use	new_accum	quadraticlinear_clippeds                r&   update_stepFtrl.update_step   so    WWT''8--)""4#3#3G#<=t//89++00))sRx00
 q4DDDxOO 	 BFF8Q//	vvi+bffUI.FF	
 FF9y2R7!f*D	)),,,++

 	0I=>Yr(   c           
         > [         TU ]  5       nUR                  U R                  U R                  5      U R
                  U R                  U R                  U R                  U R                  U R                  S.5        U$ )N)r#   r   r   r   r   r    r!   )r   
get_configupdate_serialize_hyperparameterr   r   r   r   r   r    r!   )r"   configr%   s     r&   rV   Ftrl.get_config   su    #%!%!?!?''" (,'?'?-1-K-K.2.M.M.2.M.M8<8a8a		
	
 r(   )
r5   r*   r   r6   r!   r   r   r   r    r   )gMbP?g      g?r   r   r   r   NNNNFgGz?NTr   )__name__
__module____qualname____firstlineno____doc__r   r3   rS   rV   __static_attributes____classcell__)r%   s   @r&   r   r      sX    
CN  "%#&#&-0 $#GR> B r(   r   z{{base_optimizer_keyword_args}})r_   tensorflow.compat.v2compatv2r9   tf_keras.src.optimizersr   'tf_keras.src.saving.object_registrationr    tensorflow.python.util.tf_exportr   	Optimizerr   replacebase_optimizer_keyword_argsr   r(   r&   <module>rk      s{    % ! ! - O : (*Ab_9 _ _D ||##%y'L'Lr(   