# turboSim: Conduct benchmark studies of EM accelerator In turboEM: A Suite of Convergence Acceleration Schemes for EM, MM and Other Fixed-Point Algorithms

## Description

The `turboSim` function conducts benchmark studies to compare performance of multiple acceleration schemes over a large number of repetitions. The `turboSim` function outputs objects of class `turbosim`.

## Usage

 ```1 2 3 4``` ```turboSim(parmat, fixptfn, objfn, method = c("em","squarem","pem","decme","qn"), boundary, pconstr = NULL, project = NULL, parallel = FALSE, method.names, keep.pars = FALSE, ..., control.method = replicate(length(method),list()), control.run = list()) ```

## Arguments

 `parmat` A matrix of starting parameter values, where each row corresponds to a single benchmark study repetition. `fixptfn` A vector function, F that denotes the fixed-point mapping. This function is the most essential input in the package. It should accept a parameter vector as input and should return a parameter vector of same length. This function defines the fixed-point iteration: x[k+1] = F(x[k]). In the case of EM algorithm, F defines a single E and M step. `objfn` This is a scalar function, L, that denotes a “merit” function which attains its local minimum at the fixed-point of F. This function should accept a parameter vector as input and should return a scalar value. In the EM algorithm, the merit function L is the negative log-likelihood. In some problems, a natural merit function may not exist. However, this argument is required for all of the algorithms *except* Squarem (which defaults to Squarem-2 if `objfn` not provided) and EM. `method` Specifies which algorithm(s) will be applied. Must be a vector containing one or more of `c("em", "squarem", "pem", "decme", "qn")`. `boundary` Argument required for Dynamic ECME (`decme`) only. Function to define the subspaces over which the line search is conducted. `pconstr` Optional function for defining boundary constraints on parameter values. Function maps a vector of parameter values to TRUE if constraints are satisfied. Note that this argument is only used for the Squarem (`squarem`), Parabolic EM (`pem`), and quasi-Newton (`qn`) algorithms, and it has no effect on the other algorithms. `project` Optional function for defining a projection that maps an out-of-bound parameter value into the constrained parameter space. Requires the `pconstr` argument to be specified in order for the `project` to be applied. `parallel` Logical indicating whether the repetitions of the benchmark study will be run in parallel. Note that the parallel implementation is based on the `foreach` package, which depends on a parallel backend being registered prior to running `turboSim()`. See *Details* of `foreach`. `method.names` Vector of unique names that identify the algorithms being compared. `keep.pars` Logical indicating whether the parameter values at termination should be kept. Defaults to FALSE. `control.method` If `method = c(method1, method2, ...)`, then `control.method = list(list1, list2, ...)` where `list1` is the list of control parameters for `method1`, `list2` is the list of control parameters for `method2`, and so on. If `length(method) == 1`, then `control.method` is the list of control parameters for the acceleration scheme. See *Details* of `turboem`. `control.run` List of control parameters for convergence and stopping the algorithms. See *Details* of `turboem`. `...` Arguments passed to `fixptfn` and `objfn`.

## Value

`turboSim` returns an object of class `turbosim`.

`turbosim, turboem`
 ```1 2 3``` ```########################################################################### # Examples provided in the vignette, which can be seen by typing # vignette("turboEM") ```