Add function to get the algorithm option defaults

[avehtari]

Currently methods to run Stan algorithms
https://mc-stan.org/cmdstanr/reference/model-method-sample.html
state

Any argument left as NULL will default to the default value used by the installed version of CmdStan. See the CmdStan User’s Guide for more details.

It would be nice to have methods that would call CmdStan help and show the defaults of the actual CmdStan used. For example, we could have a method $sample_defaults(), which would execute the model binary with argument sample help-all. The minimal implementation would print the help text as is (excluding the generic part in the end). A bit nicer version would parse the arguments and defaults to be a nested list so that the defaults could easily be accessed programmatically.

[avehtari]

Here's a draft of function getting the default values from CmdStan. I don't know how this should be added to cmdstanr

#' Get CmdStan default argument values
#'
#' Runs a CmdStan model binary with help-all to extract valid arguments
#' and their default values for a given inference method, returning them
#' with cmdstanr argument names.
#'
#' @param model_binary Path to the CmdStan model binary
#' @param method Inference method: "sample", "optimize", "variational",
#'   "pathfinder", or "laplace"
#' @return A named list with cmdstanr-style argument names and default values.
#'
#' @examples
#' args <- parse_cmdstan_args("./normal", "sample")
#' args$adapt_delta
#' args$iter_warmup
#'
#' @export
parse_cmdstan_args <- function(model_binary, method) {
  output <- system2(model_binary, args = c(method, "help-all"),
                    stdout = TRUE, stderr = TRUE)

  paths <- get_cmdstan_paths(method)
  target_args <- vapply(paths, function(p) {
    parts <- strsplit(p, "\\.")[[1]]
    parts[length(parts)]
  }, FUN.VALUE = character(1), USE.NAMES = TRUE)

  result <- list()
  n <- length(output)

  for (i in seq_len(n)) {
    line <- output[i]
    content <- trimws(line)

    # Match argument lines like "num_samples=<int>" or "t0=<double>"
    arg_match <- regmatches(content, regexec("^([a-z_][a-z0-9_]*)=", content))[[1]]

    if (length(arg_match) >= 2) {
      arg_name <- arg_match[2]

      # Check if this is one of our target arguments
      matches <- which(target_args == arg_name)

      if (length(matches) > 0) {
        # Look ahead for "Defaults to" line
        default_value <- NULL
        for (j in (i + 1):min(i + 5, n)) {
          next_content <- trimws(output[j])
          if (grepl("^Defaults to", next_content)) {
            default_value <- parse_default_value(next_content)
            break
          }
          # Stop if we hit another argument
          if (grepl("^[a-z_][a-z0-9_]*=", next_content)) break
        }

        # Add to result for each matching cmdstanr argument name
        for (m in matches) {
          cmdstanr_name <- names(target_args)[m]
          result[[cmdstanr_name]] <- default_value
        }
      }
    }
  }

  result
}

#' Parse default value from "Defaults to ..." line
#' @noRd
parse_default_value <- function(line) {
  val_str <- sub("^Defaults to\\s*", "", line)
  if (val_str %in% c("true", "false")) return(val_str == "true")
  if (grepl("^-?[0-9]+$", val_str)) return(as.integer(val_str))
  if (grepl("^-?[0-9]*\\.?[0-9]+([eE][+-]?[0-9]+)?$", val_str)) return(as.numeric(val_str))
  val_str
}

#' Get mapping from cmdstanr argument names to CmdStan paths
#' @noRd
get_cmdstan_paths <- function(method) {
  switch(method,
    sample = c(
      iter_sampling = "sample.num_samples",
      iter_warmup = "sample.num_warmup",
      save_warmup = "sample.save_warmup",
      thin = "sample.thin",
      adapt_engaged = "sample.adapt.engaged",
      adapt_delta = "sample.adapt.delta",
      init_buffer = "sample.adapt.init_buffer",
      term_buffer = "sample.adapt.term_buffer",
      window = "sample.adapt.window",
      save_metric = "sample.adapt.save_metric",
      max_treedepth = "sample.algorithm.hmc.engine.nuts.max_depth",
      metric = "sample.algorithm.hmc.metric",
      metric_file = "sample.algorithm.hmc.metric_file",
      step_size = "sample.algorithm.hmc.stepsize",
      num_chains = "sample.num_chains"
    ),
    optimize = c(
      algorithm = "optimize.algorithm",
      jacobian = "optimize.jacobian",
      iter = "optimize.iter",
      save_iterations = "optimize.save_iterations",
      init_alpha = "optimize.algorithm.lbfgs.init_alpha",
      tol_obj = "optimize.algorithm.lbfgs.tol_obj",
      tol_rel_obj = "optimize.algorithm.lbfgs.tol_rel_obj",
      tol_grad = "optimize.algorithm.lbfgs.tol_grad",
      tol_rel_grad = "optimize.algorithm.lbfgs.tol_rel_grad",
      tol_param = "optimize.algorithm.lbfgs.tol_param",
      history_size = "optimize.algorithm.lbfgs.history_size"
    ),
    variational = c(
      algorithm = "variational.algorithm",
      iter = "variational.iter",
      grad_samples = "variational.grad_samples",
      elbo_samples = "variational.elbo_samples",
      eta = "variational.eta",
      adapt_engaged = "variational.adapt.engaged",
      adapt_iter = "variational.adapt.iter",
      tol_rel_obj = "variational.tol_rel_obj",
      eval_elbo = "variational.eval_elbo",
      output_samples = "variational.output_samples"
    ),
    pathfinder = c(
      init_alpha = "pathfinder.init_alpha",
      tol_obj = "pathfinder.tol_obj",
      tol_rel_obj = "pathfinder.tol_rel_obj",
      tol_grad = "pathfinder.tol_grad",
      tol_rel_grad = "pathfinder.tol_rel_grad",
      tol_param = "pathfinder.tol_param",
      history_size = "pathfinder.history_size",
      draws = "pathfinder.num_psis_draws",
      num_paths = "pathfinder.num_paths",
      save_single_paths = "pathfinder.save_single_paths",
      psis_resample = "pathfinder.psis_resample",
      calculate_lp = "pathfinder.calculate_lp",
      max_lbfgs_iters = "pathfinder.max_lbfgs_iters",
      single_path_draws = "pathfinder.num_draws",
      num_elbo_draws = "pathfinder.num_elbo_draws"
    ),
    laplace = c(
      jacobian = "laplace.jacobian",
      draws = "laplace.draws"
    ),
    character(0)
  )
}