# DigiSim Simulation Engine

> Technical documentation for DigiSim's dual simulation engines: event-driven and iterative simulators for accurate digital circuit behavior with real-time processing and state management.

## Simulation Architecture

DigiSim employs a dual-engine simulation system to handle different circuit types and performance requirements:

### Event-Driven Simulator
- **Primary Engine**: Main simulation system for real-time circuit evaluation
- **Real-time Processing**: Handles timing-dependent components like clocks and oscilloscopes
- **State Management**: Maintains flip-flop, counter, and memory states across cycles
- **Performance Optimized**: Efficient event scheduling and propagation
- **Bus Contention Resolution**: Manages multiple drivers on shared connections

### Legacy Iterative Simulator
- **Fallback Engine**: Alternative simulation for specific circuit types
- **Iterative Evaluation**: Step-by-step component evaluation
- **Compatibility**: Supports older circuit formats and edge cases
- **Debugging**: Detailed step-by-step analysis capabilities

## Component Evaluation System

### Combinational Logic
Components evaluated immediately based on current inputs:
- **Logic Gates**: AND, OR, NOT, XOR, NAND, NOR, XNOR
- **Arithmetic**: Adders, comparators, ALU operations
- **Data Routing**: Multiplexers, demultiplexers, encoders, decoders

### Sequential Elements
State-based evaluation with clock edge detection:
- **Flip-flops**: D, JK, T flip-flops with preset/clear
- **Latches**: SR and D latches with enable control
- **Registers**: Multi-bit storage with parallel load
- **Counters**: Binary and modulo counters with enable/clear

### Memory Components
Address-based data storage and retrieval:
- **RAM**: Random access memory with read/write operations
- **ROM**: Read-only memory with pre-programmed data
- **Register Files**: Multi-port register arrays

### Timing Components
Real-time signal generation and analysis:
- **Clock Generators**: Configurable frequency oscillators
- **Oscilloscopes**: Multi-channel signal visualization
- **Timing Analysis**: Setup and hold time verification

## Event Scheduling System

### Event Types
- **Clock Events**: Periodic timing signals
- **Input Changes**: User-initiated input modifications
- **State Updates**: Sequential element state changes
- **Output Propagation**: Combinational logic updates

### Event Processing
1. **Event Queue**: Priority-based event scheduling
2. **Time Management**: Simulation time advancement
3. **Dependency Resolution**: Component evaluation ordering
4. **State Synchronization**: Consistent state updates

## Bus Contention Management

### Multiple Driver Detection
- **Conflict Identification**: Detect multiple active drivers
- **Resolution Strategy**: High-impedance state for conflicts
- **Warning System**: User notification of bus contention
- **Educational Value**: Demonstrates real-world bus design issues

### Tri-state Logic
- **High-Z States**: Proper tri-state buffer simulation
- **Bus Resolution**: Combine multiple tri-state outputs
- **Enable Control**: Output enable signal handling

## Performance Optimization

### Efficient Evaluation
- **Change Detection**: Only evaluate components with input changes
- **Event Batching**: Group related events for processing
- **State Caching**: Minimize redundant calculations
- **Memory Management**: Efficient resource allocation

### Scalability
- **Large Circuits**: Handle complex multi-component systems
- **Real-time Constraints**: Maintain responsive user interface
- **Memory Efficiency**: Optimize state storage and retrieval

## Animation Playback Engine

DigiSim includes an animation engine for educational circuit demonstrations:

### Animation Features
- **Step-by-Step Playback**: Watch circuits being built progressively
- **State Tracking**: Accurate circuit state at any point in the animation
- **Synchronized Audio**: Voice narration timed with visual changes
- **Visual Effects**: Component highlighting and camera movements

### Supported Animation Actions
- **Component Placement**: Add logic gates and other components
- **Wire Connections**: Draw connections between pins
- **State Toggling**: Change input switch values
- **Visual Highlighting**: Emphasize specific components
- **Camera Control**: Focus on relevant circuit areas