% Generated by roxygen2: do not edit by hand
% Please edit documentation in R/MCIS_helpers.R
\name{MC_IS_single}
\alias{MC_IS_single}
\title{Internal Monte Carlo Importance Sampling Routine (Single Limit State Function)}
\usage{
MC_IS_single(
  lsf,
  lDistr,
  cov_user,
  n_batch,
  n_max,
  use_threads,
  backend = "future",
  dataRecord,
  densityType = "norm",
  dps = NULL,
  debug.level,
  streams,
  libPaths_local,
  seed = NULL,
  adaptive_alpha = FALSE,
  alpha_update_rate = 0.1,
  adaptive_batch = FALSE,
  batch_control = list(),
  min_adapt_samples = 10000,
  alpha_min = 0.02,
  stability_mode
)
}
\arguments{
\item{lsf}{Objective (limit state) function in form \code{function(x) \{ ... \}}.}

\item{lDistr}{List of input variable distributions created from TesiproV base variable objects.}

\item{cov_user}{Target coefficient of variation for convergence criterion.}

\item{n_batch}{Number of samples per batch (recommended > 1000).}

\item{n_max}{Maximum total number of samples before forced stop.}

\item{use_threads}{Number of threads/workers to use for parallel computation.}

\item{backend}{Character; either `"parallel"` or `"future"` backend for parallelization on multiple cores.}

\item{dataRecord}{Logical; if `TRUE`, all intermediate results are recorded and returned as data frame.}

\item{densityType}{Character; type of sampling density ("origin" keeps original input distributions).}

\item{dps}{Optional vector of design points supplied by user instead of FORM result.}

\item{debug.level}{Integer verbosity level: 0 = silent, 1 = info, 2 = detailed output during calculation.}

\item{streams}{RNG stream object created by [`init_rng_master()`].}

\item{libPaths_local}{Local library paths passed to cluster workers for package availability.}

\item{seed}{Optional integer seed for reproducibility across parallel runs. If `NULL`, a random seed is used.}

\item{adaptive_alpha}{Logical; if \code{TRUE}, adaptive mixture weights are used
(system case only).}

\item{alpha_update_rate}{Damping factor \eqn{\lambda \in [0,1]} controlling
adaptation speed of mixture weights.}

\item{adaptive_batch}{Logical; if TRUE, the batch size is adapted dynamically
based on the current effective sample size (ESS) and target RSE.}

\item{batch_control}{List controlling adaptive batch behaviour:
\describe{
  \item{n_min}{Minimum batch size}
  \item{n_max}{Maximum batch size}
  \item{K_future}{Desired number of remaining iterations}
}}

\item{min_adapt_samples}{Integer. Minimum total number of MC samples required before adaptive mixtures are updated.
The adaption mechanism is activated only after this threshold has been exceeded to ensure statistically stable estimates.}

\item{alpha_min}{Numeric scalar in \eqn{(0,1)}.
Lower bound for mixture weights \eqn{\alpha_i} during adaptive
updating. This prevents individual components of the importance
sampling density from collapsing to zero and ensures numerical
stability in multimodal system analyses.}

\item{stability_mode}{Character string specifying the numerical
  stabilization strategy used for importance sampling weight
  accumulation.

  \describe{
    \item{"robust"}{
      Default. Uses full log-domain accumulation of weights
      across Monte Carlo iterations. This improves numerical
      stability for high-dimensional systems and very small
      failure probabilities.
    }
    \item{"fast"}{
      Uses shifted exponentiation with batch-level scaling.
      Computationally equivalent under normal engineering
      conditions but may be slightly less stable in extreme
      rare-event scenarios.
    }
  }

  Both modes are mathematically equivalent for typical
  reliability problems. The \code{"robust"} mode is recommended
  for research applications and extreme reliability levels.}
}
\description{
Performs the core Monte Carlo simulation with importance sampling for a single limit state function.
This internal routine is called by the public interface [`MC_IS()`] when the input argument `lsf`
is a single function rather than a list of system functions.

The algorithm uses the FORM design point as center of the sampling density in standard normal space.
Each random variable is transformed between physical and normal spaces using its distribution object
(`PROB_BASEVAR$getlDistr()`), which provides parameterized CDF and inverse-CDF functions:

\deqn{u = \Phi^{-1}(F_X(x))}
\deqn{x = F_X^{-1}(\Phi(u))}

Parallel execution is supported via either base R's **parallel** package or the **future** backend.
}
\keyword{internal}
