## output_analysis.ReplicationsAlgorithm


Automatically determine the number of simulation replications needed


Usage

``` python
output_analysis.ReplicationsAlgorithm(
    alpha=0.05,
    half_width_precision=0.1,
    initial_replications=3,
    look_ahead=5,
    replication_budget=1000,
    verbose=False,
    observer_factory=None
)
```


to achieve and maintain a target confidence interval precision.

Implements the *Replications Algorithm* from Hoad, Robinson & Davies (2010), which combines: - The **confidence interval method** to assess whether the target precision has been met. - A **sequential look-ahead procedure** to verify that precision remains stable in additional replications.


## Attributes


`alpha: float`  
Significance level for confidence interval calculations.

`half_width_precision: float`  
Target CI half-width precision (i.e. percentage deviation of the confidence interval from the mean).

`initial_replications: int`  
Number of replications to run before evaluating precision.

`look_ahead: int`  
Number of additional replications to simulate for stability checks (adjusted proportionally when `n > 100`).

`replication_budget: int`  
Maximum number of replications allowed.

`verbose: bool`  
If True, prints the current replication count during execution.

`observer_factory: callable or None`  
Callable returning a new observer instance for each metric. Should be a function, lambda, or class constructor taking no arguments. Returned object must follow the [AlgorithmObserver](output_analysis.AlgorithmObserver.md#sim_tools.output_analysis.AlgorithmObserver) protocol. If None, uses [ReplicationTabulizer](output_analysis.ReplicationTabulizer.md#sim_tools.output_analysis.ReplicationTabulizer).

`n: int`  
Current replication count (updated during execution).

`_n_solution: int`  
Solution replication count once convergence is met (or replication budget if not met).

`stats: OnlineStatistics or None`  
Tracks running mean, variance, and confidence interval metrics.


## References

Hoad, K., Robinson, S., & Davies, R. (2010). Automated selection of the number of replications for a discrete-event simulation. *Journal of the Operational Research Society*, 61(11), 1632-1644. https://www.jstor.org/stable/40926090


## Methods

| Name | Description |
|----|----|
| [__init__()](#__init__) | Initialise the replications algorithm |
| [find_position()](#find_position) | Find the first position where element is below deviation, and this is |
| [select()](#select) | Executes the replication algorithm, determining the necessary number |
| [valid_inputs()](#valid_inputs) | Checks validity of provided parameters. |

------------------------------------------------------------------------


#### \_\_init\_\_()


Initialise the replications algorithm


Usage

``` python
__init__(
    alpha=0.05,
    half_width_precision=0.1,
    initial_replications=3,
    look_ahead=5,
    replication_budget=1000,
    verbose=False,
    observer_factory=None
)
```


##### Parameters


`alpha: float | None = ``0.05`  
Significance level for confidence interval calculations (CI level = 100 \* (1 - alpha) %).

`half_width_precision: float | None = ``0.1`  
Target CI half-width precision (i.e. percentage deviation of the confidence interval from the mean).

`initial_replications: int = ``3`  
Number of replications to run before evaluating precision.

`look_ahead: int | None = ``5`  
Number of additional replications to simulate for stability checks. When the number of replications n \<= 100 the value of look ahead is used. When n \> 100 then look_ahead / 100 \* max(n, 100) is used.

`replication_budget: float | None = ``1000`  
Maximum number of replications allowed; algorithm stops if not converged by then. Useful for larger models where replication runtime is a constraint.

`verbose: bool | None = ``False`  
If True, prints replication count progress.

`observer_factory: (callable or None, optional(default=None)) = None`  
Callable returning a new observer instance for each metric. Should be a function, lambda, or class constructor taking no arguments. Returned object must follow the [AlgorithmObserver](output_analysis.AlgorithmObserver.md#sim_tools.output_analysis.AlgorithmObserver) protocol. If None, uses [ReplicationTabulizer](output_analysis.ReplicationTabulizer.md#sim_tools.output_analysis.ReplicationTabulizer).


##### Raises


`ValueError`  
If parameter values are invalid (see [valid_inputs()](output_analysis.ReplicationsAlgorithm.md#sim_tools.output_analysis.ReplicationsAlgorithm.valid_inputs)).


------------------------------------------------------------------------


#### find_position()


Find the first position where element is below deviation, and this is


Usage

``` python
find_position(lst)
```


maintained through the lookahead period.

This is used to correct the ReplicationsAlgorithm, which cannot return a solution below the initial_replications.


##### Parameters


`lst: list[float]`  
List of deviations.


##### Returns


`int or None`  
Minimum replications required to meet and maintain precision, or None if not found.


------------------------------------------------------------------------


#### select()


Executes the replication algorithm, determining the necessary number


Usage

``` python
select(model, metrics)
```


of replications to achieve and maintain the desired precision.

The process: 1. Runs `initial_replications` of the model. 2. Updates running statistics and calculates CI precision. 3. If precision met, tests stability via the look-ahead procedure. 4. Stops when stable precision is achieved or budget is exhausted.


##### Parameters


`model: ReplicationsAlgorithmModelAdapter`  
Simulation model implementing `single_run(replication_index)`.

`metrics: list[str]`  
The metrics to assess.


##### Returns


`nreps: dict[str, int or None]`  
Minimum replications required for each metric, or None if not achieved.

`summary_frame: pandas.DataFrame`  
Table summarising deviation and CI metrics for all replications.


##### Raises


`ValueError`  
If the provided `model` is not an instance of [ReplicationsAlgorithmModelAdapter](output_analysis.ReplicationsAlgorithmModelAdapter.md#sim_tools.output_analysis.ReplicationsAlgorithmModelAdapter).


##### Warns


`UserWarning`  
If convergence is not reached within the allowed replication budget.


------------------------------------------------------------------------


#### valid_inputs()


Checks validity of provided parameters.


Usage

``` python
valid_inputs()
```


Ensures: - `initial_replications` and `look_ahead` are non-negative integers. - `half_width_precision` is \> 0. - `replication_budget` is less than `initial_replications`. - `observer` is class with `.dev` and `.summary_frame()`.


##### Raises


`ValueError`  
If any conditions are not met.