output_analysis.ReplicationsAlgorithm

Automatically determine the number of simulation replications needed

Usage

Source

output_analysis.ReplicationsAlgorithm()

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 protocol. If None, uses 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__() Initialise the replications algorithm
find_position() Find the first position where element is below deviation, and this is
select() Executes the replication algorithm, determining the necessary number
valid_inputs() Checks validity of provided parameters.

__init__()

Initialise the replications algorithm

Usage

Source

__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: Optional[float] = 0.05

Significance level for confidence interval calculations (CI level = 100 * (1 - alpha) %).

half_width_precision: Optional[float] = 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: Optional[int] = 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: Optional[float] = 1000

Maximum number of replications allowed; algorithm stops if not converged by then. Useful for larger models where replication runtime is a constraint.

verbose: Optional[bool] = 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 protocol. If None, uses ReplicationTabulizer.
Raises
ValueError
If parameter values are invalid (see valid_inputs()).

find_position()

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

Usage

Source

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

Source

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.
Warns
UserWarning
If convergence is not reached within the allowed replication budget.

valid_inputs()

Checks validity of provided parameters.

Usage

Source

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.