Skip to contents

Optimize Number of Variability Iterations Based on Convergence

Source: R/mc_analysis.R
optim_ndvar.Rd

[Experimental]

Automatically determines the minimum number of variability iterations (ndvar) required for all input nodes in a Monte Carlo model to converge at the 5% threshold. Uses an iterative algorithm starting with 1,001 variates and adjusting up or down based on observed convergence.

Usage

optim_ndvar(
  mctable = set_mctable(),
  exp = NULL,
  mc_names = NULL,
  min_ndvar = 100,
  max_ndvar = 50000,
  start_ndvar = 1001,
  conv_threshold = 0.05,
  print_summary = TRUE,
  progress = FALSE
)

Arguments

mctable

(data frame). Table with mcnode and sample_space columns defining the sampling distribution for each input. Default: set_mctable().

exp

(language or list). Optional model expression(s) to evaluate. Default: NULL, will create an expression multipling all input nodes.

mc_names

(character vector, optional). Specific node names to analyze. If NULL, analyzes all nodes. Default: NULL.

min_ndvar

(integer). Minimum allowed ndvar. Default: 100.

max_ndvar

(integer). Maximum allowed ndvar. Default: 50000.

start_ndvar

(integer). Initial ndvar to test. Default: 1001.

conv_threshold

(numeric). Convergence threshold at 5%. Default: 0.05.

print_summary

(logical). If TRUE, print optimization summary. Default: TRUE.

progress

(logical). If TRUE, print progress for each iteration. Default: FALSE.

Value

A list containing:

  • optimal_ndvar: The minimum ndvar where all nodes converge.

  • converged: Logical indicating if convergence was achieved.

  • iterations: Data frame with each iteration's details (ndvar, converged, reason).

  • convergence_results: Convergence analysis results from mcmodule_converg().

Details

The optimization algorithm:

  • Starts with start_ndvar (default 1,001)

  • If convergence achieved: tries n/2 (lower bound search)

  • If convergence not achieved: tries 2n (upper bound search)

  • Continues until minimum converging ndvar is found

  • Warns if limits (min_ndvar, max_ndvar) are reached

Examples

# Define mctable
mctable <- data.frame(
  mcnode = c("input_a", "input_b"),
  sample_space = c("min = 0, max = 1", "min = 10, max = 20")
)

# Optimize ndvar
result <- optim_ndvar(
  exp = quote({result <- input_a * input_b}),
  mctable = mctable
)
#> Warning: No mc_func column found in the mctable. All nodes will be treated as deterministic (no uncertainty).
#> exp evaluated
#> mcmodule created (expressions: exp)
#> Warning: No mc_func column found in the mctable. All nodes will be treated as deterministic (no uncertainty).
#> exp evaluated
#> mcmodule created (expressions: exp)
#> Warning: No mc_func column found in the mctable. All nodes will be treated as deterministic (no uncertainty).
#> exp evaluated
#> mcmodule created (expressions: exp)
#> Warning: No mc_func column found in the mctable. All nodes will be treated as deterministic (no uncertainty).
#> exp evaluated
#> mcmodule created (expressions: exp)
#> Warning: No mc_func column found in the mctable. All nodes will be treated as deterministic (no uncertainty).
#> exp evaluated
#> mcmodule created (expressions: exp)
#> 
#> === NDvar Optimization Summary ===
#> 
#> Optimization Parameters:
#> - Starting ndvar: 1001
#> - Min ndvar limit: 100
#> - Max ndvar limit: 50000
#> - Convergence threshold: 5%
#> 
#> Optimization Results:
#> - Total iterations: 5
#> - Optimal ndvar found: 250
#> - Status: CONVERGED
#> 
#> Iteration History:
#>   iteration ndvar converged                   reason
#> 1         1  1001      TRUE                  Initial
#> 2         2   500      TRUE    Converged, trying n/2
#> 3         3   250      TRUE    Converged, trying n/2
#> 4         4   125     FALSE Not converged, trying 2n
#> 5         5   250      TRUE    Converged, trying n/2
#> 
#> Successfully optimized ndvar to 250 (all nodes converge at 5% threshold) :)

result$optimal_ndvar
#> [1] 250