% Generated by roxygen2: do not edit by hand
% Please edit documentation in R/get_B.R
\name{.woodbury_decompose_V}
\alias{.woodbury_decompose_V}
\title{Woodbury Decomposition of Correlation Structure}
\usage{
.woodbury_decompose_V(
  VhalfInv_perm,
  X,
  K,
  p_expansions,
  Lambda,
  Lambda_block,
  unique_penalty_per_partition,
  L_partition_list,
  order_list,
  parallel_eigen,
  cl,
  chunk_size,
  num_chunks,
  rem_chunks,
  rank_threshold_fraction = 1/3,
  family
)
}
\arguments{
\item{VhalfInv_perm}{\eqn{\mathbf{V}^{-1/2}} permuted to partition
ordering.}

\item{X}{List of partition-specific design matrices.}

\item{K, p_expansions}{Integer dimensions.}

\item{Lambda, Lambda_block}{Shared and full block-diagonal penalty
matrices.}

\item{unique_penalty_per_partition}{Logical.}

\item{L_partition_list}{Partition-specific penalty matrices.}

\item{order_list}{Partition-to-data index mapping.}

\item{parallel_eigen}{Logical; parallel eigendecomposition.}

\item{cl, chunk_size, num_chunks, rem_chunks}{Parallel parameters.}

\item{rank_threshold_fraction}{Numeric; Woodbury is used only when
\eqn{r < P \times} this fraction (default 1/3).}

\item{family}{GLM family object.}
}
\value{
A list with components:
\describe{
  \item{use_woodbury}{Logical; FALSE triggers dense Path 1 fallback.}
  \item{Ghalf_corrected}{List of corrected \eqn{\mathbf{G}_{\mathrm{on},k}^{1/2}}.}
  \item{GhalfInv_corrected}{List of corrected \eqn{\mathbf{G}_{\mathrm{on},k}^{-1/2}}.}
  \item{G_corrected}{List of corrected \eqn{\mathbf{G}_{\mathrm{on},k}}.}
  \item{E}{Off-diagonal low-rank factor (\eqn{P \times r}) from the
    supplement factorization
    \eqn{\mathbf{G}_{\mathrm{off}}^{-1} = \mathbf{E}\mathbf{J}\mathbf{E}^{\top}}.}
  \item{J_signs}{Length-\eqn{r} vector giving the diagonal of
    \eqn{\mathbf{J}}.}
  \item{r}{Integer effective rank.}
  \item{inner_inv}{Precomputed \eqn{r \times r} Woodbury inner inverse. In
    supplement notation this is
    \eqn{(\mathbf{J}^{-1} + \mathbf{E}^{\top}\mathbf{G}_{\mathrm{on}}
    \mathbf{E})^{-1}}.}
  \item{GL}{List of \eqn{K+1} matrices storing
    \eqn{\mathbf{G}_{\mathrm{on},k}\mathbf{E}[rows_k,]} in supplement notation,
    each \eqn{p \times r}.}
  \item{L,S_signs,M}{Legacy internal aliases for
    \code{E}, \code{J_signs}, and \code{inner_inv}, retained for
    compatibility within the package code.}
}
}
\description{
Builds the Woodbury factors for the correlated solver. The function
decomposes
\eqn{\mathbf{G}^{-1} = \mathbf{G}_{\mathrm{on}}^{-1} +
\mathbf{G}_{\mathrm{off}}^{-1}}
by absorbing the block-diagonal part of
\eqn{\mathbf{X}^{\top}\mathbf{V}^{-1}\mathbf{X} + \boldsymbol{\Lambda}}
into \eqn{\mathbf{G}_{\mathrm{on}}^{-1}}, then factoring the
cross-partition part as
\eqn{\mathbf{G}_{\mathrm{off}}^{-1} = \mathbf{E}\mathbf{J}\mathbf{E}^{\top}}.
}
\details{
The output is exactly the information needed by
\code{.woodbury_halfsqrt_components()} and
\code{.lagrangian_project_woodbury()}:
corrected block-diagonal \eqn{\mathbf{G}_{\mathrm{on}}},
the low-rank factor \eqn{\mathbf{E}}, the sign matrix diagonal
\eqn{\mathbf{J}}, and the small inverse
\eqn{(\mathbf{J}^{-1} +
\mathbf{E}^{\top}\mathbf{G}_{\mathrm{on}}\mathbf{E})^{-1}}.

When the cross-partition rank is zero or too large to be worthwhile,
the helper returns \code{use_woodbury = FALSE} so the caller can use
the dense correlated path instead.
}
\keyword{internal}
