Package 'withinr'

Title: High-Performance Fixed Effects Solver
Description: Fast modified LSMR solvers with Schwarz and diagonal preconditioners for absorbing high-dimensional fixed effects in panel data regressions. The computational core is written in Rust via version 0.2.0 of the 'within' crate and accessed through 'extendr'.
Authors: Alexander Fischer [aut, cre], Kristof Schroeder [aut]
Maintainer: Alexander Fischer <[email protected]>
License: MIT + file LICENSE
Version: 0.1.0
Built: 2026-10-06 13:48:32 UTC
Source: https://github.com/py-econometrics/within

Help Index

Additive Schwarz preconditioner configuration

Description

Additive Schwarz preconditioner configuration

Usage

AdditiveSchwarz(local_solver = NULL, reduction = ReductionStrategy$Auto)

Arguments

local_solver

NULL for the library default, or a LocalSolverConfig() object.
reduction

One of ReductionStrategy$Auto, ReductionStrategy$AtomicScatter, or ReductionStrategy$ParallelReduction.

Value

A preconditioner configuration object.

Approximate Cholesky configuration

Description

Approximate Cholesky configuration

Usage

ApproxCholConfig(seed = 0, split_merge = NULL)

Arguments

seed

Non-negative integer random seed.
split_merge

Optional positive integer split/merge parameter, or NULL.

Value

A local-solver configuration object.

Approximate Schur complement configuration

Description

Approximate Schur complement configuration

Usage

ApproxSchurConfig(seed = 0, split = 1L)

Arguments

seed

Non-negative integer random seed.
split

Positive integer edge split factor.

Value

A local-solver configuration object.

Local solver configuration for additive Schwarz subdomains

Description

Local solver configuration for additive Schwarz subdomains

Usage

LocalSolverConfig(
  approx_chol = NULL,
  approx_schur = .default_approx_schur(),
  dense_threshold = NULL
)

Arguments

approx_chol

NULL for the library default, or an ApproxCholConfig() object.
approx_schur

Omitted for the library default approximate Schur, NULL for exact Schur, or an ApproxSchurConfig() object.
dense_threshold

Optional non-negative integer dense Schur threshold.

Value

A local-solver configuration object accepted by AdditiveSchwarz().

Modified LSMR solver options

Description

Uses Modified Golub-Kahan bidiagonalization to solve the least-squares problem directly. The preconditioner approximates ⁠A^T A⁠ and is applied as one M^{-1} solve per iteration.

Usage

LsmrOptions(tol = 1e-08, maxiter = 1000L, local_size = NULL)

lsmr_options(tol = 1e-08, maxiter = 1000L, local_size = NULL)

Arguments

tol

Positive finite convergence tolerance. Default 1e-8.
maxiter

Maximum number of LSMR iterations. Default 1000L.
local_size

Optional window size for modified Gram-Schmidt reorthogonalization, or NULL to use the short recurrence.

Value

A solver options object accepted by solve(), solve_batch(), and persistent solver methods.

Built preconditioner handle

Description

Deserializes a preconditioner from raw bytes produced by solver$preconditioner()$serialize(). Handles returned by solver$preconditioner() also expose ⁠$variant⁠ and ⁠$build_time_seconds⁠ metadata. Deserialized handles keep ⁠$variant⁠ but report ⁠$build_time_seconds = NA_real_⁠.

Usage

Preconditioner(data)

Arguments

data

Raw vector containing serialized preconditioner bytes.

Value

A within_preconditioner object with ⁠$apply()⁠ and ⁠$serialize()⁠ methods, ⁠$nrows⁠, ⁠$ncols⁠, ⁠$variant⁠, and ⁠$build_time_seconds⁠ fields.

Preconditioner shortcut values

Description

Use PreconditionerConfig$Additive, PreconditionerConfig$Off, or PreconditionerConfig$Diagonal as the preconditioner argument. Additive builds the default additive Schwarz preconditioner, Off disables preconditioning, and Diagonal uses diagonal/Jacobi scaling.

Usage

PreconditionerConfig

Format

An object of class within_preconditioner_config of length 3.

Reduction strategy shortcut values

Description

Use these values inside AdditiveSchwarz().

Usage

ReductionStrategy

Format

An object of class within_reduction_strategy of length 3.

Solve fixed-effects normal equations

Description

Computes fixed-effect coefficients by solving the normal equations DTWDx=DTWyD^T W D x = D^T W y where DD is the dummy-variable design matrix implied by categories and WW is the diagonal weight matrix.

Usage

solve(categories, y, options = NULL, weights = NULL, preconditioner = NULL)

Arguments

categories

Integer matrix of shape ⁠(n_obs, n_factors)⁠. Each column contains 1-based factor level assignments. Values must be positive integers with no NAs.
y

Numeric vector of length n_obs.
options

NULL for default LsmrOptions() or an options object.
weights

Numeric vector of length n_obs or NULL.
preconditioner

Controls preconditioning. Five input forms are accepted: NULL builds the default additive Schwarz preconditioner, PreconditionerConfig$Off disables preconditioning, PreconditionerConfig$Diagonal uses diagonal/Jacobi scaling, AdditiveSchwarz() overrides local-solver and reduction settings, and a built Preconditioner() object reuses an existing factorization.

Value

A named list with fields x, demeaned, converged, iterations, residual, time_total, time_setup, and time_solve.

Solve fixed-effects normal equations for multiple response vectors

Description

Builds the operator and preconditioner once, then solves for each column of Y in parallel.

Usage

solve_batch(
  categories,
  Y,
  options = NULL,
  weights = NULL,
  preconditioner = NULL
)

Arguments

categories

Integer matrix of shape ⁠(n_obs, n_factors)⁠. Each column contains 1-based factor level assignments. Values must be positive integers with no NAs.
Y

Numeric matrix of shape ⁠(n_obs, k)⁠.
options

NULL for default LsmrOptions() or an options object.
weights

Numeric vector of length n_obs or NULL.
preconditioner

Controls preconditioning. Five input forms are accepted: NULL builds the default additive Schwarz preconditioner, PreconditionerConfig$Off disables preconditioning, PreconditionerConfig$Diagonal uses diagonal/Jacobi scaling, AdditiveSchwarz() overrides local-solver and reduction settings, and a built Preconditioner() object reuses an existing factorization.

Value

A named list with matrix fields x and demeaned, plus converged, iterations, residual, time_solve, and time_total.

Persistent fixed-effects solver

Description

Builds the preconditioner once and reuses it for repeated solves with the same design matrix.

Usage

Solver(categories, weights = NULL, preconditioner = NULL)

Arguments

categories

Integer matrix of shape ⁠(n_obs, n_factors)⁠. Each column contains 1-based factor level assignments. Values must be positive integers with no NAs.
weights

Numeric vector of length n_obs or NULL.
preconditioner

Controls preconditioning. Five input forms are accepted: NULL builds the default additive Schwarz preconditioner, PreconditionerConfig$Off disables preconditioning, PreconditionerConfig$Diagonal uses diagonal/Jacobi scaling, AdditiveSchwarz() overrides local-solver and reduction settings, and a built Preconditioner() object reuses an existing factorization.

Value

A within_solver object with ⁠$solve()⁠, ⁠$solve_batch()⁠, and ⁠$preconditioner()⁠ methods, plus ⁠$n_dofs⁠ and ⁠$n_obs⁠ fields.