Skip to content

Optimizer Controls

Bivariate Models

All bivariate fits go through the strategy registry:

from pyscarcopula import JoeCopula
from pyscarcopula.api import fit

copula = JoeCopula(rotate=180)

# Default GAS fit.
result = fit(copula, u, method='gas')

# Tighten or relax optimizer controls for this run.
result = fit(
    copula,
    u,
    method='gas',
    gamma_bound=30.0,
    beta_bound=0.995,
    gtol=1e-4,
    ftol=1e-12,
    maxfun=3000,
)

The object method is equivalent:

result = copula.fit(u, method='scar-tm-ou', K=500, gtol=5e-3)

MLE

MLE labels a static model. For scalar bivariate families it estimates one constant copula parameter; the table in this subsection applies to that optimizer. Static multivariate Gaussian and Student correlation controls are described under Multivariate Native Paths.

Parameter Where Default Effect
alpha0 fit kwarg auto Initial point in the copula's natural parameter space.
gtol fit kwarg / mle_optimizer.gtol 1e-3 L-BFGS-B projected-gradient tolerance.
maxls fit kwarg / mle_optimizer.maxls 20 Maximum L-BFGS-B line-search steps per iteration.
from pyscarcopula import LBFGSBConfig, NumericalConfig

cfg = NumericalConfig(mle_optimizer=LBFGSBConfig(gtol=1e-6))
result = fit(copula, u, method='mle', config=cfg)

MLE evaluates the likelihood directly in the natural copula parameter. For example, alpha0=[2.0] means a Gumbel parameter of 2.0, while a stochastic Student initial value of 5.0 means five degrees of freedom. Parameter transforms are used by dynamic latent-state methods, not by the MLE objective.

When alpha0 is omitted for a bivariate copula, the implementation calls copula.transform([1.5]) only to obtain a family-valid natural starting value. The returned value is passed directly to the MLE optimizer; it is not treated as a latent coordinate.

GAS

GAS estimates an observation-driven recursion \(g_t = \omega + \beta g_{t-1} + \gamma\,score_{t-1}\).

Parameter Where Default Effect
gamma0 fit kwarg Two MLE-based starts Explicit initial \([\omega, \gamma, \beta]\) selects a single start.
gtol fit kwarg / gas_optimizer.gtol 1e-3 L-BFGS-B projected-gradient tolerance.
ftol fit kwarg / gas_optimizer.ftol 1e-9 Relative objective decrease tolerance.
maxfun fit kwarg / gas_optimizer.maxfun 4000 Maximum scalar objective evaluations, including numerical-gradient probes.
maxiter fit kwarg / gas_optimizer.maxiter 1000 Maximum optimizer iterations.
maxls fit kwarg / gas_optimizer.maxls 100 Maximum L-BFGS-B line-search steps per iteration.
eps fit kwarg / gas_optimizer.eps 1e-8 Absolute native two-point step for the outer optimizer gradient when finite_diff_rel_step is unset.
finite_diff_rel_step fit kwarg / gas_optimizer.finite_diff_rel_step None Relative two-point step in optimizer coordinates; takes precedence over eps.
score_eps fit kwarg / gas_score_eps 1e-4 Finite-difference step for Fisher curvature.
gamma_bound fit kwarg / gas_gamma_bound 20.0 Bounds score sensitivity to \([-\texttt{gamma\_bound}, \texttt{gamma\_bound}]\).
beta_bound fit kwarg / gas_beta_bound 0.999 Bounds persistence to \([-\texttt{beta\_bound}, \texttt{beta\_bound}]\); must be in \((0, 1)\).
scaling strategy kwarg 'unit' Recommended score scaling mode. 'fisher' is numerically sensitive.
result = fit(
    JoeCopula(rotate=180),
    u,
    method='gas',
    scaling='unit',
    ftol=1e-12,
    maxfun=3000,
)

Automatic fitting tries the standard MLE-based score-driven start and a nested static start with gamma=0. The latter shares the standard start's intercept and persistence and exactly reproduces the static MLE path. An explicit gamma0 retains single-start semantics, including joint shrinkage fits. When ftol is omitted, the best candidate is refined with ftol=1e-12. Each start and refinement has its own maxfun and maxiter budget; nfev sums the runs and the final stationarity checks. The best finite terminal candidate is retained even if a worse candidate reported convergence. A trial point that improves log likelihood by more than 0.001 is retained with success=False if convergence there was not established.

For bivariate, EquicorrGaussian and fixed-correlation StochasticStudent fits, a separate native three-point check validates the gradient of the mean negative log likelihood in stationary-mean coordinates (omega/(1-beta), gamma, beta). Both the projected gradient and its discrepancy between two difference steps must be at most gtol. Default validation uses cbrt(machine epsilon) and half that step to balance truncation and roundoff. The stencil is formed directly in stationary-mean coordinates; differentiating in physical intercept coordinates first amplifies perturbations near beta=1. When step uncertainty straddles the acceptance threshold, validation can refine to quarter and eighth steps. Acceptance always requires two neighboring estimates below tolerance and agreement within tolerance; a resolved large gradient stops refinement and requests recovery. All evaluated steps and norms are saved. Explicit per-call difference steps are preserved. This validation scale is separate from the original optimizer's summed-objective tolerance and is recorded in diagnostics['stationarity_validation'] together with the coordinate system, steps, raw gradient, and discrepancy.

Automatic multivariate fits without per-call optimizer overrides complete the same two starts at a second native difference step even when the first point passes stationarity. A stationary point does not establish multistart coverage. Bivariate fits use these additional starts when validation fails. If needed, they polish the best point in stationary-mean coordinates. A final bounded Powell stage can recover when noisy gradients prevent line-search progress. Its iterations evaluate only the scalar objective, reserving one final gradient evaluation within the scalar-objective budget. A verified stationary candidate can be preferred over a nonstationary candidate only within the existing 0.001 material log-likelihood tolerance; stationary_selection_loglik_loss records the exact loss. Explicit per-call starts, difference steps, function/iteration budgets, line-search limits, and ftol suppress these additional recovery stages. These bounded recovery stages have their own optimizer budgets, including budgets supplied through NumericalConfig, and are recorded in optimizer_stages. A fit whose final point fails validation has success=False. Saturated Equicorr transforms remain valid for scalar likelihood evaluation, but the optimizer gradient provider rejects their unresolvable sensitivity so line search can recover instead of accepting a large finite plateau with zero gradient. Bivariate vine-edge fits use the same independent check. If recovery does not establish stationarity, the existing vine dynamic_failure_policy determines whether to fall back to MLE, keep the unsuccessful result, or raise.

Multivariate GAS bootstrap refits distinguish a library-inherited start from an explicit bootstrap_fit_kwargs['gamma0']. An inherited result adds a warm start alongside starts computed from the bootstrap sample's static MLE; it does not disable automatic recovery. Each recovery stage uses the supplied maxfun, maxiter, and maxls; the total work can span several stage budgets. Explicit gamma0, difference steps, and ftol retain their existing control over recovery. An explicit gamma0 is also preserved on the bootstrap retry. Both attempts use the same simulated sample. Unresolved stationarity still raises a bootstrap failure rather than accepting the fit or drawing a replacement sample.

success additionally requires the optimizer's objective to agree with the reported likelihood within 1e-6, and the likelihood to be no more than 0.001 below either the initial nested static likelihood (automatic starts) or the constant path at the final intercept and persistence. Joint Student shrinkage fitting preserves the quantile interpolation cache so optimization and reporting evaluate the same function.

GASResult.diagnostics includes optimizer_stages (starts, final parameters, objectives, raw convergence messages and evaluation counts), optimizer_success, optimizer_message, projected_gradient_inf_norm, static_baseline_log_likelihood, objective_discrepancy, and likelihood_validation_passed, and stationarity_validation. The original projected_gradient_inf_norm is informational; a small relative function decrease can still occur with a large gradient. The fits above use the separately scaled, independently checked stationarity diagnostic for acceptance. Neither these checks nor multistart establish global optimality or guarantee agreement with another version to 0.001. Inspect alternative starts and finite-difference steps for sensitive fits. The smaller default eps limits perturbations amplified by the recursion; explicit eps and finite_diff_rel_step retain their documented precedence and behavior.

GAS uses the compiled numerical engine for likelihood, score recursion, filtering, prediction, and Rosenblatt operations. Unsupported copulas fail immediately.

The model score driving the GAS recursion is not an analytical gradient of the complete likelihood with respect to omega, gamma, and beta. The compiled evaluator obtains that optimizer gradient by two-point finite differences and returns it together with the objective to SciPy L-BFGS-B. It follows SciPy's forward-step convention, adjusts steps at parameter bounds, and divides by the actual representable displacement. An explicit relative step follows the sign and magnitude of the optimizer coordinate. GASResult.diagnostics records these as model_score='native', optimizer_gradient='native', and gradient_kind='native_finite_difference'. maxfun and nfev use scalar objective budget units, preserving the previous counts for completed finite-difference calls. Each native objective/gradient call is charged four units, or five for joint GAS/shrinkage fitting. Three-point validation and recovery use seven units for three parameters, including one base evaluation and two perturbations per parameter. An early numerical failure may execute fewer likelihood evaluations but still incurs that full charge; nfev therefore does not count physical likelihood calls. As with SciPy numerical gradients, an iteration or line search can exceed maxfun.

Fisher scaling uses the analytical copula score \(\partial\log c/\partial r\,\partial r/\partial g\) as its numerator and computes only the local curvature by a second finite difference inside the GAS recursion. The native evaluator still differentiates the outer objective numerically. Together with the Fisher floor and score clipping, this can produce a piecewise, step-sensitive objective. Prefer scaling='unit' unless Fisher behavior is specifically under study.

Post-fit API operations inherit GASResult.scaling unless an explicit scaling= override is supplied. The override applies to likelihood, filtering, sampling, and prediction without changing the fitted result. Likewise, GASStrategy() inherits the result's scaling for post-fit calls; its fit default remains unit. Overriding scaling when predicting requires the observation history, since the cached final parameter belongs to the original scaling.

GAS sample and predict require a positive integer draw count. Both accept memory_budget_bytes= as a pre-allocation guard. Fused bivariate sample accounts for its caller-owned RNG draws, native result staging, and final NumPy output: 6 * n * sizeof(float64) bytes. Other sample paths account for their output. predict accounts for its output plus the predictive parameter path. Unconditional bivariate sampling performs its causal score recursion in one fused native call; conditional and multivariate sampling retain the stepwise model-specific path. The causal GAS sample recursion is not split into batches.

NumericalConfig

Use NumericalConfig when a setting should apply to many fits:

NumericalConfig() always uses n_threads=1, independently of process environment variables. Native parallelism is enabled only by explicitly passing n_threads to a method or by constructing NumericalConfig(n_threads=N).

from pyscarcopula import LBFGSBConfig, NumericalConfig

cfg = NumericalConfig(
    gas_optimizer=LBFGSBConfig(
        gtol=1e-4,
        ftol=1e-12,
        maxfun=3000,
        maxiter=3000,
        maxls=50,
    ),
    scar_optimizer=LBFGSBConfig(
        gtol=1e-4,
        maxls=50,
    ),
    default_K=500,
)

result = fit(copula, u, method='gas', config=cfg)

Per-call keyword arguments override the config values for that fit.

For conditional bivariate api.sample and api.predict, bisection_tol and bisection_maxiter configure the iterative inverse-h solvers used by Gumbel and Joe (including rotations). The default tolerance is 1e-10, and the iteration limit is 60. Gumbel tests a relative transformed-equation residual; Joe tests a log(-log(h)) residual or a certified root bracket at float64 resolution. Tolerance is an upper bound: the kernels can apply a tighter criterion to preserve tail accuracy. Exhausting the iteration budget raises an error instead of returning an unchecked approximation. These settings do not affect analytical inverse-h families or unconditional sampling. Direct low-level inverse-h calls use 80 iterations and 8e-15 for Gumbel, and 50 iterations and 1e-10 for Joe.

GAS fit uses config.fail_value when a numerical objective evaluation raises FloatingPointError, including joint shrinkage fits. Argument and programming errors such as TypeError and ValueError propagate to the caller.

Multivariate Student models use separate GAS optimizer defaults, so changing them does not affect bivariate GAS fits or vine edges:

cfg = NumericalConfig(
    stochastic_student_gas_optimizer=LBFGSBConfig(ftol=1e-9),
)