Skip to contents

Control Solver Settings for Pseudo-Weight Estimation

Source: R/pw_solver_control.R
pw_solver_control.Rd

pw_solver_control() creates a solver control object used by est_pw to manage numerical 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

solver

Character string specifying the numerical solver used for solving the estimating equations. Currently, only "nleqslv" is supported. Default is "nleqslv".

maxit

Positive finite numeric value passed to 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 150 when a global strategy is specified (i.e., global != "none"), and 20 when no global strategy is used (global = "none"), matching nleqslv's own defaults. Since the default global strategy is "dbldog", the effective default is 150 unless global = "none" is explicitly specified.

trace

Logical. If TRUE, tracing or solver progress information may be requested from the underlying numerical routine when supported. Default is FALSE.

method

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

global

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

xscalm

Character string specifying the scaling method passed to nleqslv::nleqslv(). Supported values are "fixed" and "auto". Default is "fixed".

ftol

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

xtol

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

nleqslv_control

A list of additional control options passed to nleqslv::nleqslv(). This can include less commonly used control options, such as btol, cndtol, sigma, and scalex. See nleqslv for details.

Value

A flat list containing all solver control settings for pseudo-weight estimation:

solver

The selected numerical solver.

method

The nleqslv numerical method.

global

The nleqslv global strategy.

xscalm

The nleqslv scaling method.

ftol

The function-value convergence tolerance.

xtol

The parameter-step convergence tolerance.

maxit

The maximum number of solver iterations, stored as an integer. 150 if a global strategy is used; 20 if global = "none". Since the default global strategy is "dbldog", the effective default is 150 unless global = "none" is explicitly specified.

trace

Logical value indicating whether tracing information is requested.

nleqslv_control

A list of additional options passed to nleqslv::nleqslv().

Details

The control object stores solver settings used by pseudo-weight estimation step. It is passed to est_pw through the control argument.

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

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

Additional, less commonly used nleqslv control options can be supplied through nleqslv_control. To avoid ambiguity, do not supply ftol, xtol, maxit, or trace inside nleqslv_control; use the main arguments instead.

See also

est_pw

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
  )
)