# Class: Simulator

## Simulator(scene, ctxMain, ctxBelowLight, ctxAboveLight, ctxGrid, ctxVirtual, enableTimer, rayCountLimitopt, useFloatColorRendereropt)

The simulator class, which simulates the optical system described by the `Scene` class and renders the scene (optical elements, decorations, rays, etc) on the canvas layers.

When a ray interacts with an object (optical element) in the scene, the object itself is responsible for handling the interaction, and the simulator only call the related methods of the object. See `onSimulationStart`, `checkRayIntersects` and `onRayIncident` in the `BaseSceneObj` class for more information. The rendering of the object is also a method `draw` of the object itself called by the simulator.

In the Ray Optics Simulator web app, a single instance of this class is used in the entire session to simulate the scene interactively. `updateSimulation` is called whenever the scene is updated. If the simulation is too long, the simulator will automatically pause and resume to prevent the browser from not responding, and emit the `simulationPause` event to notify the UI to update the simulation status. When exporting the scene to PNG or SVG, a new instance of this class is created and `updateSimulation` is called once to render the scene without pausing.

This class can also be used by other projects, including those running in a standalone environment (e.g. Node.js) to simulate and render the scene without the UI. Note however that even if one is only interested in the numerical results (e.g. detector readings), the canvas layers are still required for the simulator to work properly. In the future, a headless mode may be implemented to allow the simulator to run without the canvas layers.

## Constructor

#### new Simulator(scene, ctxMain, ctxBelowLight, ctxAboveLight, ctxGrid, ctxVirtual, enableTimer, rayCountLimitopt, useFloatColorRendereropt)

Creates a new Simulator instance.

##### Parameters:

Name | Type | Attributes | Default | Description
--- | --- | --- | --- | ---
`scene` | Scene |  |  | The scene to be simulated.
`ctxMain` | CanvasRenderingContext2D | C2S |  |  | The default context for drawing the scene.
`ctxBelowLight` | CanvasRenderingContext2D | C2S |  |  | The context for drawing the scene below the light layer.
`ctxAboveLight` | CanvasRenderingContext2D | C2S |  |  | The context for drawing the scene above the light layer.
`ctxGrid` | CanvasRenderingContext2D | C2S |  |  | The context for drawing the grid layer.
`ctxVirtual` | CanvasRenderingContext2D |  |  | The virtual context for color adjustment.
`enableTimer` | boolean |  |  | Whether to enable the timer for the simulation.
`rayCountLimit` | number | <optional> | Infinity | The maximum number of processed rays in the simulation.
`useFloatColorRenderer` | boolean | <optional> | false | Whether to use the FloatColorRenderer for the light layer.

Source:
  - Simulator.js, line 49

### Members

#### MIN_RAY_SEGMENT_LENGTH

The minimal length between two interactions with rays (when smaller than this, the interaction will be ignored). Also the threshold for surface merging.

Source:
  - Simulator.js, line 54

#### brightnessScale

##### Properties:

Name | Type | Description
--- | --- | ---
`brightnessScale` | number | The brightness scale of the simulation. 0 if undetermined, -1 if inconsistent.

Source:
  - Simulator.js, line 132

#### ctxAboveLight

##### Properties:

Name | Type | Description
--- | --- | ---
`ctxAboveLight` | CanvasRenderingContext2D | C2S | The context for drawing the this.scene above the light layer.

Source:
  - Simulator.js, line 91

#### ctxBelowLight

##### Properties:

Name | Type | Description
--- | --- | ---
`ctxBelowLight` | CanvasRenderingContext2D | C2S | The context for drawing the this.scene below the light layer.

Source:
  - Simulator.js, line 88

#### ctxGrid

##### Properties:

Name | Type | Description
--- | --- | ---
`ctxGrid` | CanvasRenderingContext2D | C2S | The context for drawing the grid layer.

Source:
  - Simulator.js, line 94

#### ctxMain

##### Properties:

Name | Type | Description
--- | --- | ---
`ctxMain` | CanvasRenderingContext2D | C2S | The default context for drawing the this.scene. If other layers are present, this is the context for drawing the light layer only.

Source:
  - Simulator.js, line 85

#### ctxVirtual

##### Properties:

Name | Type | Description
--- | --- | ---
`ctxVirtual` | CanvasRenderingContext2D | The virtual context for color adjustment.

Source:
  - Simulator.js, line 97

#### dpr

##### Properties:

Name | Type | Description
--- | --- | ---
`dpr` | number | The device pixel ratio of the canvases.

Source:
  - Simulator.js, line 105

#### enableTimer

##### Properties:

Name | Type | Description
--- | --- | ---
`enableTimer` | boolean | Whether to enable the timer for the simulation so that it automatically pauses and resumes when the simulation is too long.

Source:
  - Simulator.js, line 108

#### error

##### Properties:

Name | Type | Description
--- | --- | ---
`error` | string | The error message of the simulation.

Source:
  - Simulator.js, line 138

#### eventListeners

##### Properties:

Name | Type | Description
--- | --- | ---
`eventListeners` | object | The event listeners of the simulator.

Source:
  - Simulator.js, line 144

#### isSVG

##### Properties:

Name | Type | Description
--- | --- | ---
`isSVG` | boolean | Whether the canvas is being exported to SVG.

Source:
  - Simulator.js, line 101

#### pendingRays

##### Properties:

Name | Type | Description
--- | --- | ---
`pendingRays` | Array.<Ray> | The rays to be processed.

Source:
  - Simulator.js, line 117

#### processedRayCount

##### Properties:

Name | Type | Description
--- | --- | ---
`processedRayCount` | number | The number of rays processed in the simulation.

Source:
  - Simulator.js, line 135

#### rayCountLimit

##### Properties:

Name | Type | Description
--- | --- | ---
`rayCountLimit` | number | The maximum number of processed rays in the simulation. When this limit is reached, the simulation will stop.

Source:
  - Simulator.js, line 111

#### scene

##### Properties:

Name | Type | Description
--- | --- | ---
`scene` | Scene | The scene to be simulated.

Source:
  - Simulator.js, line 80

#### shouldSimulatorStop

##### Properties:

Name | Type | Description
--- | --- | ---
`shouldSimulatorStop` | boolean | Whether the simulation should stop immediately in the next step of the timer.

Source:
  - Simulator.js, line 123

#### simulationStartTime

##### Properties:

Name | Type | Description
--- | --- | ---
`simulationStartTime` | Date | The time when the simulation starts.

Source:
  - Simulator.js, line 126

#### simulationTimerId

##### Properties:

Name | Type | Description
--- | --- | ---
`simulationTimerId` | number | The ID of the timer for the simulation.

Source:
  - Simulator.js, line 120

#### totalTruncation

##### Properties:

Name | Type | Description
--- | --- | ---
`totalTruncation` | number | The total truncated brightness of rays in the infinite series of internal reflection during the simulation.

Source:
  - Simulator.js, line 129

#### useFloatColorRenderer

##### Properties:

Name | Type | Description
--- | --- | ---
`useFloatColorRenderer` | boolean | Whether to use the FloatColorRenderer for the light layer.

Source:
  - Simulator.js, line 114

#### warning

##### Properties:

Name | Type | Description
--- | --- | ---
`warning` | string | The warning message of the simulation.

Source:
  - Simulator.js, line 141

### Methods

#### emit(eventName, data)

Emit an event.

##### Parameters:

Name | Type | Description
--- | --- | ---
`eventName` | string | The name of the event.
`data` | any | The data to be passed to the callback functions.

Source:
  - Simulator.js, line 169

#### on(eventName, callback)

Add an event listener to the simulator.

##### Parameters:

Name | Type | Description
--- | --- | ---
`eventName` | string | The name of the event.
`callback` | function | The callback function.

Source:
  - Simulator.js, line 157

#### stopSimulation() → {void}

Stop the simulation.

Source:
  - Simulator.js, line 752

##### Returns:

Type
  void

#### updateSimulation(skipLight, skipGrid) → {void}

Run the simulation and draw the this.scene on the canvases.

##### Parameters:

Name | Type | Description
--- | --- | ---
`skipLight` | boolean | Whether to skip the light layer.
`skipGrid` | boolean | Whether to skip the grid layer.

Source:
  - Simulator.js, line 206

##### Returns:

Type
  void

#### validate() → {void}

Check the simulation and display warnings or errors if necessary.

Source:
  - Simulator.js, line 762

##### Returns:

Type
  void

### Events

#### simulationComplete

The event emitted when the simulation completes (all the rays are processed completely).

Source:
  - Simulator.js, line 185

#### simulationPause

The event emitted when the simulation pauses (when the timer is enabled and the maximum continue running time is exceeded).

Source:
  - Simulator.js, line 180

#### simulationStart

The event emitted when the simulation starts.

Source:
  - Simulator.js, line 175

#### simulationStop

The event emitted when the simulation stops (when the maximum number of processed rays is reached or if the user force stop the simulation).

Source:
  - Simulator.js, line 190