% Generated by roxygen2: do not edit by hand
% Please edit documentation in R/tune_Lambda.R
\name{.compute_gcvu_gradient}
\alias{.compute_gcvu_gradient}
\title{Compute Closed-Form Gradient of GCV_u Criterion}
\usage{
.compute_gcvu_gradient(par, log_penalty_vec, outlist = NULL, env, ...)
}
\arguments{
\item{par}{Numeric vector; log-scale penalty parameters.}

\item{log_penalty_vec}{Numeric vector; log-scale predictor/partition
penalties.}

\item{outlist}{List or NULL; pre-computed GCV_u components from
\code{.compute_gcvu}. If NULL, they are computed internally.}

\item{env}{List; pre-computed objects and tuning configuration (same
structure as in \code{.compute_gcvu}).}

\item{...}{Additional arguments passed to fitting functions.}
}
\value{
List containing:
\describe{
  \item{GCV_u}{Numeric; GCV_u criterion value including meta-penalty.}
  \item{gradient}{Numeric vector; gradient on the log penalty scale.}
  \item{outlist}{List; GCV_u components (for reuse to avoid recomputation).}
}
}
\description{
Computes the gradient of the modified GCV_u criterion with respect to the
log-scale penalty parameters using analytical derivatives of the hat matrix
trace and residual sum of squares.
}
\details{
The gradient is computed via:
\deqn{\frac{\partial \mathrm{GCV}_u}{\partial \theta}
  = \frac{1}{D^{2}} \left(
    \frac{\partial N}{\partial \theta} D
    - N \frac{\partial D}{\partial \theta}
  \right)}
where \eqn{N = \sum r_{i}^{2}} (numerator),
\eqn{D = n(1 - \gamma\bar{W})^{2}} (denominator), \eqn{\theta} is the
log-scale penalty parameter, and the chain rule
\eqn{d\lambda / d\theta = \lambda} (exp parameterization) is applied.

The shared wiggle and flat directions are differentiated directly from the
fitted criterion. For predictor- and partition-specific penalties, a
lower-cost ratio heuristic is used on the log-penalty scale:
\deqn{\frac{\partial \mathrm{GCV}_u}{\partial \theta_{j}}
  \approx \frac{\mathrm{tr}(\mathbf{L}_{j})}{\mathrm{tr}(\boldsymbol{\Lambda})}
  \cdot \frac{\partial \mathrm{GCV}_u}{\partial \theta_{w}},}
where \eqn{\mathbf{L}_{j}} denotes the current contribution of that extra
penalty to \eqn{\boldsymbol{\Lambda}}.
}
\keyword{internal}
