% Generated by roxygen2: do not edit by hand
% Please edit documentation in R/pw_solver_control.R
\name{pw_solver_control}
\alias{pw_solver_control}
\title{Control Solver Settings for Pseudo-Weight Estimation}
\usage{
pw_solver_control(
  solver = "nleqslv",
  maxit = NULL,
  trace = FALSE,
  method = c("Newton", "Broyden"),
  global = c("dbldog", "cline", "pwldog", "qline", "gline", "hook", "none"),
  xscalm = c("fixed", "auto"),
  ftol = 1e-08,
  xtol = 1e-08,
  nleqslv_control = list()
)
}
\arguments{
\item{solver}{Character string specifying the numerical solver used for
solving the estimating equations. Currently, only \code{"nleqslv"} is
supported. Default is \code{"nleqslv"}.}

\item{maxit}{Positive finite numeric value passed to
\code{nleqslv::nleqslv()} as the maximum number of solver iterations. The
value is converted to an integer before being stored in the returned
control object. Default is \code{150} when a global strategy is specified
(i.e., \code{global != "none"}), and \code{20} when no global strategy is
used (\code{global = "none"}), matching \code{nleqslv}'s own defaults.
Since the default global strategy is \code{"dbldog"}, the effective default
is \code{150} unless \code{global = "none"} is explicitly specified.}

\item{trace}{Logical. If \code{TRUE}, tracing or solver progress information
may be requested from the underlying numerical routine when supported.
Default is \code{FALSE}.}

\item{method}{Character string specifying the numerical method passed to
\code{nleqslv::nleqslv()}. Supported values are \code{"Newton"} and
\code{"Broyden"}. Default is \code{"Newton"}.}

\item{global}{Character string specifying the global strategy passed to
\code{nleqslv::nleqslv()}. Supported values are \code{"dbldog"},
\code{"cline"}, \code{"pwldog"}, \code{"qline"}, \code{"gline"},
\code{"hook"}, and \code{"none"}. Default is \code{"dbldog"}.}

\item{xscalm}{Character string specifying the scaling method passed to
\code{nleqslv::nleqslv()}. Supported values are \code{"fixed"} and
\code{"auto"}. Default is \code{"fixed"}.}

\item{ftol}{Positive finite numeric value passed to
\code{nleqslv::nleqslv()} as the function-value convergence tolerance. This
controls convergence based on the size of the estimating function. Default
is \code{1e-8}.}

\item{xtol}{Positive finite numeric value passed to
\code{nleqslv::nleqslv()} as the parameter-step convergence tolerance. This
controls convergence based on changes in the parameter vector. Default is
\code{1e-8}.}

\item{nleqslv_control}{A list of additional control options
passed to \code{nleqslv::nleqslv()}. This can include less commonly used
control options, such as \code{btol}, \code{cndtol},
\code{sigma}, and \code{scalex}. See
\code{\link[nleqslv]{nleqslv}} for details.}
}
\value{
A flat list containing all solver control settings for pseudo-weight
estimation:

\describe{
  \item{\code{solver}}{The selected numerical solver.}
  \item{\code{method}}{The nleqslv numerical method.}
  \item{\code{global}}{The nleqslv global strategy.}
  \item{\code{xscalm}}{The nleqslv scaling method.}
  \item{\code{ftol}}{The function-value convergence tolerance.}
  \item{\code{xtol}}{The parameter-step convergence tolerance.}
  \item{\code{maxit}}{The maximum number of solver iterations, stored as an integer.
    \code{150} if a global strategy is used; \code{20} if \code{global = "none"}.
    Since the default global strategy is \code{"dbldog"}, the effective default
    is \code{150} unless \code{global = "none"} is explicitly specified.}
  \item{\code{trace}}{Logical value indicating whether tracing information is requested.}
  \item{\code{nleqslv_control}}{A list of additional options passed to
    \code{nleqslv::nleqslv()}.}
}
}
\description{
\code{pw_solver_control()} creates a solver control object used by
\code{\link{est_pw}} to manage numerical settings for pseudo-weight
estimation.
}
\details{
The control object stores solver settings used by pseudo-weight estimation
step. It is passed to \code{\link{est_pw}} through the \code{control}
argument.

Currently, only \code{solver = "nleqslv"} is supported. The arguments
\code{method}, \code{global}, \code{xscalm}, \code{ftol}, \code{xtol}, and
\code{maxit} correspond to options used by \code{nleqslv::nleqslv()}.
They are collected internally and passed to \code{nleqslv::nleqslv()} at the
pseudo-weight estimation step.

The argument \code{ftol} is the function-value convergence tolerance. It
controls convergence based on the size of the estimating function. The
argument \code{xtol} is the parameter-step convergence tolerance. It controls
convergence based on changes in the parameter vector. The argument
\code{maxit} controls the maximum number of solver iterations.

Additional, less commonly used \code{nleqslv} control options can be supplied
through \code{nleqslv_control}. To avoid ambiguity, do not supply
\code{ftol}, \code{xtol}, \code{maxit}, or \code{trace} inside
\code{nleqslv_control}; use the main arguments instead.
}
\examples{
## Default solver control settings
ctrl <- pw_solver_control()

## Custom nleqslv solver settings
ctrl <- pw_solver_control(
  maxit  = 20,
  trace  = FALSE,
  method = "Newton",
  global = "cline",
  xscalm = "auto",
  ftol   = 1e-8,
  xtol   = 1e-10
)

## Additional nleqslv control options
ctrl <- pw_solver_control(
  method = "Newton",
  global = "dbldog",
  nleqslv_control = list(
    btol = 1e-3
  )
)

}
\seealso{
\code{\link{est_pw}}
}
