simple-circuit-engine 0.0.11 → 0.0.13

package/dist/core/setup.d.ts

@@ -0,0 +1,25 @@
+import { BehaviorRegistry } from './simulation';
+/**
+ * Register all basic component behaviors in the given registry
+ * Basic components are : Battery, Lightbulb, RectangleLED, Relay, SmallLED, Switch, double switch
+ * @public
+ * @param registry
+ * @return the input behavior registry for chaining
+ */
+export declare function registerBasicComponentsBehaviors(registry: BehaviorRegistry): BehaviorRegistry;
+/**
+ * Register all gates component behaviors in the given registry
+ * Gates components are : Inverter, NandGate (2,4,8), NorGate (2,4,8), XorGate (2,4,8)
+ * @public
+ * @param registry
+ * @return the input behavior registry for chaining
+ */
+export declare function registerGatesComponentsBehaviors(registry: BehaviorRegistry): BehaviorRegistry;
+/**
+ * Register all arithmetic component behaviors in the given registry
+ * Arithmetic components are : HalfAdder, Adder, 8bit adder, 8bit one's complement
+ * @public
+ * @param registry
+ * @return the input behavior registry for chaining
+ */
+export declare function registerArithmeticComponentsBehaviors(registry: BehaviorRegistry): BehaviorRegistry;

package/dist/core/simulation/CircuitRunner.d.ts

@@ -0,0 +1,176 @@
+import { Circuit } from '../topology/Circuit';
+import { ComponentState } from './states/ComponentState.js';
+import { SimulationState } from './states/SimulationState';
+import { StateManager } from './StateManager.js';
+import { EventQueue } from './EventQueue.js';
+import { DirtyTracker } from './DirtyTracker.js';
+import { BehaviorRegistry } from './behaviors';
+import { INodeElectricalState } from './states';
+import { IUserCommand, IRunnerOptions, IRunnerResult } from './types';
+import { UUID } from '../utils/types';
+/**
+ * Main circuit simulation controller.
+ * Manages discrete-time simulation with event-driven state propagation.
+ *
+ * Features:
+ * - Boolean electrical state (voltage/current present or not)
+ * - Event-driven delayed transitions
+ * - Dirty tracking for optimization
+ * - Configurable history storage
+ * - Registry-based component behaviors
+ *
+ * @public
+ */
+export declare class CircuitRunner {
+    readonly circuit: Circuit;
+    readonly stateManager: StateManager;
+    readonly eventQueue: EventQueue;
+    readonly commands: Map<UUID, IUserCommand>;
+    readonly dirtyTracker: DirtyTracker;
+    readonly behaviorRegistry: BehaviorRegistry;
+    /**
+     * Create a new circuit simulation runner.
+     *
+     * @param circuit - The circuit topology to simulate
+     * @param behaviorRegistry - Registry of component behaviors
+     * @param options - Simulation options (history settings)
+     */
+    constructor(circuit: Circuit, behaviorRegistry: BehaviorRegistry, options?: IRunnerOptions);
+    /**
+     * Execute one simulation tick.
+     * Process scheduled events, update state (electrical propagation), process user commands and advance tick.
+     *
+     * @returns the result of the tick execution
+     */
+    tick(): IRunnerResult;
+    /**
+     * Execute multiple simulation ticks.
+     *
+     * @param count - Number of ticks to execute
+     * @returns an array of IRunnerResult for each tick executed
+     */
+    tickN(count: number): IRunnerResult[];
+    /**
+     * Reset simulation to tick 0.
+     * Clears all state, history, and scheduled events.
+     */
+    reset(): void;
+    /**
+     * Get current simulation tick number.
+     *
+     * @returns Current tick
+     */
+    getCurrentTick(): number;
+    /**
+     * Get current simulation state snapshot.
+     *
+     * @returns Current state (readonly)
+     */
+    getCurrentState(): SimulationState;
+    /**
+     * Get electrical state of a specific ENode.
+     *
+     * @param enodeId - UUID of the ENode
+     * @returns Electrical state, or undefined if not found
+     */
+    getEnodeState(enodeId: UUID): INodeElectricalState | undefined;
+    /**
+     * Get electrical state of a specific Wire.
+     *
+     * @param wireId - UUID of the Wire
+     * @returns Electrical state, or undefined if not found
+     */
+    getWireState(wireId: UUID): INodeElectricalState | undefined;
+    /**
+     * Get component state for a specific component.
+     *
+     * @param componentId - UUID of the component
+     * @returns Component state, or undefined if not found
+     */
+    getComponentState(componentId: UUID): ComponentState | undefined;
+    /**
+     * Get historical state at a specific tick.
+     * Only works if history is enabled.
+     *
+     * @param tick - Tick number to retrieve
+     * @returns Historical state, or undefined if not available
+     */
+    getStateAtTick(tick: number): SimulationState | undefined;
+    /**
+     * Check if a component is registered in behavior registry.
+     *
+     * @param componentType - Component type to check
+     * @returns True if behavior is registered
+     */
+    hasBehavior(componentType: string): boolean;
+    /**
+     * Submit a user command to execute at the next tick.
+     * only one command per component per tick is allowed.
+     * Subsequent commands for the same component at this tick will be discarded.
+     *
+     * @param command - User command to submit
+     */
+    submitCommand(command: IUserCommand): boolean;
+    /**
+     * Process all scheduled user commands.
+     * Mark changed components as Dirty and enqueue consequent scheduled events
+     * Finally clears command queue after processing.
+     *
+     * @returns Array of IBehaviorResult for each processed command
+     */
+    private processCommands;
+    /**
+     * Helper function to extract initializationOrder from component config.
+     * Returns numeric order value, with empty string or null defaulting to 0.
+     *
+     * @param config - Component configuration map
+     * @returns Order value (lower = processed first)
+     */
+    private getInitializationOrder;
+    /**
+     * Initialize simulation state for all components.
+     * Called on construction and reset.
+     *
+     * Uses order-based initialization to resolve feedback loops:
+     * 1. Components are grouped by initializationOrder (higher = processed LAST)
+     * 2. Within each group, components are sorted by UUID (ascending) for determinism
+     * 3. Conductivity is propagated after each component
+     *
+     * In feedback circuits, the component processed LAST "wins" because earlier
+     * components react to the initial symmetric state and open, while later
+     * components see the updated (asymmetric) state and stay closed.
+     */
+    private initializeState;
+    /**
+     * Core method that orchestrates nodes, wires and components state updates
+     * enqueue resulting events and update dirty tracker accordingly
+     * @param targetTick - Tick at which to perform the update
+     */
+    private updateState;
+    /**
+     * runs BFS (Breadth First Search) on voltage and current conductivity
+     * to propagate voltage/current conductivity
+     * and update enodes/wires electrical states throughout the circuit
+     * update is performed in place and updated nodes and wires returned
+     */
+    private propagateConductivity;
+    /**
+     * given a conductivity conductivityType and a set of seed nodes, compute all reachable nodes and wires
+     * depends on componentStates to determine if conductivity is allowed through components
+     * this method doesn't mutate any state, it's a pure function
+     * @param conductivityType
+     * @param seeds
+     * @param componentStates
+     */
+    private computeReachability;
+    /**
+     * Fire ready events and update current state accordingly
+     * eventual subsequent events are enqueued
+     *
+     * @param targetTick - Tick at which to process events
+     * @param events - Events to apply
+     * @param state - Current simulation state
+     * @param targetTick - Target tick for event processing
+     */
+    private applyReadyEvents;
+}

package/dist/core/simulation/DirtyTracker.d.ts

@@ -0,0 +1,87 @@
+import { IDirtyElements } from './types';
+import { UUID } from '../utils/types';
+/**
+ * Tracks per-element changes for optimized state propagation.
+ * Provides granular dirty tracking at component/wire/enode level.
+ *
+ * Used to avoid re-processing unchanged elements during simulation ticks.
+ *
+ * @public
+ */
+export declare class DirtyTracker {
+    private dirtyComponents;
+    private dirtyWires;
+    private dirtyEnodes;
+    /**
+     * Create a new dirty tracker with no marked elements.
+     */
+    constructor();
+    /**
+     * Mark a component as having changed state this tick.
+     *
+     * @param componentId - UUID of the component
+     */
+    markComponentDirty(componentId: UUID): void;
+    /**
+     * Mark a wire as having changed electrical state this tick.
+     *
+     * @param wireId - UUID of the wire
+     */
+    markWireDirty(wireId: UUID): void;
+    /**
+     * Mark an ENode as having changed electrical state this tick.
+     *
+     * @param enodeId - UUID of the ENode
+     */
+    markEnodeDirty(enodeId: UUID): void;
+    /**
+     * Set the entire set of dirty components. Should be only used at CircuitRunner initialization.
+     * @param componentIds
+     */
+    setDirtyComponents(componentIds: Set<UUID>): void;
+    /**
+     * Set the entire set of dirty components. Should be only used at CircuitRunner initialization.
+     * @param enodeIds
+     */
+    setDirtyEnodes(enodeIds: Set<UUID>): void;
+    /**
+     * Set the entire set of dirty components. Should be only used at CircuitRunner initialization.
+     * @param wireIds
+     */
+    setDirtyWires(wireIds: Set<UUID>): void;
+    /**
+     * Get all dirty elements and clear the tracker.
+     * This is typically called at the end of a tick to collect changes.
+     *
+     * @returns Object containing sets of dirty component/wire/enode UUIDs
+     */
+    getDirtyElements(): IDirtyElements;
+    /**
+     * Check if any elements are marked dirty.
+     *
+     * @returns True if at least one element is dirty
+     */
+    hasDirtyElements(): boolean;
+    /**
+     * Clear all dirty markers without returning them.
+     */
+    clear(): void;
+    /**
+     * Get current count of dirty components (for debugging/metrics).
+     *
+     * @returns Number of dirty components
+     */
+    getDirtyComponentCount(): number;
+    /**
+     * Get current count of dirty wires (for debugging/metrics).
+     *
+     * @returns Number of dirty wires
+     */
+    getDirtyWireCount(): number;
+    /**
+     * Get current count of dirty enodes (for debugging/metrics).
+     *
+     * @returns Number of dirty enodes
+     */
+    getDirtyEnodeCount(): number;
+}

package/dist/core/simulation/EventQueue.d.ts

@@ -0,0 +1,68 @@
+import { IScheduledEvent } from './types';
+/**
+ * Min-heap priority queue for scheduling future component transitions.
+ * Events are ordered by readyAtTick (earliest first).
+ * Events with same readyAtTick are returned in FIFO order (by scheduledAtTick).
+ *
+ * @public
+ */
+export declare class EventQueue {
+    private heap;
+    /**
+     * Create a new empty event queue.
+     */
+    constructor();
+    /**
+     * Schedule a future event.
+     * Inserted with O(log N) complexity using heap operations.
+     *
+     * @param event - Event to schedule
+     */
+    schedule(event: IScheduledEvent): void;
+    /**
+     * Get all events ready to fire at or before current tick.
+     * Returns events in FIFO order for same readyAtTick.
+     * Removes returned events from the queue.
+     *
+     * @param currentTick - Current simulation tick
+     * @returns Array of ready events (removed from queue)
+     */
+    getReadyEvents(currentTick: number): IScheduledEvent[];
+    /**
+     * Check if any events are pending.
+     *
+     * @returns True if queue contains events
+     */
+    hasEvents(): boolean;
+    /**
+     * Clear all pending events.
+     */
+    clear(): void;
+    /**
+     * Schedule multiple events at once, optionally cancelling pending events for specific targets.
+     * More efficient than individual schedule() + removeEventsForTarget() calls:
+     * single filter pass for all cancellations, batch push, single heap rebuild.
+     *
+     * @param events - Events to schedule
+     * @param cancelTargets - Target IDs whose pending events should be removed before inserting
+     */
+    scheduleMany(events: ReadonlyArray<IScheduledEvent>, cancelTargets?: ReadonlySet<string>): void;
+    /**
+     * Remove all pending events targeting a specific component.
+     * Used when a behavior signals shouldCancelPending (e.g., Vcc loss, input change during transition).
+     *
+     * @param targetId - UUID of the component whose events should be removed
+     * @returns Number of events removed
+     */
+    removeEventsForTarget(targetId: string): number;
+    /**
+     * Get number of pending events.
+     *
+     * @returns Event count
+     */
+    size(): number;
+    private rebuildHeap;
+    private bubbleUp;
+    private bubbleDown;
+    private extractMin;
+}

package/dist/core/simulation/StateManager.d.ts

@@ -0,0 +1,100 @@
+import { SimulationState } from './states/SimulationState';
+/**
+ * Manages current simulation state and historical state storage.
+ * Uses a circular buffer for efficient memory-bounded history.
+ *
+ * @public
+ */
+export declare class StateManager {
+    private currentState;
+    private history;
+    private readonly historyEnabled;
+    private readonly historyLimit;
+    private historyWriteIndex;
+    /**
+     * Create a new state controllerType.
+     *
+     * @param enableHistory - Whether to store state history (default: false)
+     * @param historyLimit - Maximum number of historical states to keep (default: 1000)
+     */
+    constructor(enableHistory?: boolean, historyLimit?: number);
+    /**
+     * Get the current simulation state.
+     *
+     * @returns Current state (mutable for simulation controller use)
+     */
+    getCurrentState(): SimulationState;
+    /**
+     * Get current tick number.
+     *
+     * @returns Current simulation tick
+     */
+    getCurrentTick(): number;
+    /**
+     * Advance to next tick, optionally saving current state to history.
+     * Creates a new SimulationState for the next tick.
+     *
+     * @returns New current state for the next tick
+     */
+    advanceToNextTick(): SimulationState;
+    /**
+     * Get a historical state by tick number.
+     * Only works if history is enabled.
+     *
+     * @param tick - Tick number to retrieve
+     * @returns State at that tick, or undefined if not available
+     */
+    getStateAtTick(tick: number): SimulationState | undefined;
+    /**
+     * Get all available historical states.
+     * Returns empty array if history is disabled.
+     *
+     * @returns Array of historical states, sorted by tick (oldest first)
+     */
+    getHistory(): ReadonlyArray<SimulationState>;
+    /**
+     * Get the oldest tick number available in history.
+     *
+     * @returns Oldest tick number, or undefined if no history
+     */
+    getOldestTick(): number | undefined;
+    /**
+     * Get the newest tick number in history (not including current tick).
+     *
+     * @returns Newest historical tick, or undefined if no history
+     */
+    getNewestHistoricalTick(): number | undefined;
+    /**
+     * Clear all history.
+     */
+    clearHistory(): void;
+    /**
+     * Reset to tick 0, clearing current state and all history.
+     */
+    reset(): void;
+    /**
+     * Check if history tracking is enabled.
+     *
+     * @returns True if history is enabled
+     */
+    isHistoryEnabled(): boolean;
+    /**
+     * Get the configured history limit.
+     *
+     * @returns Maximum number of historical states
+     */
+    getHistoryLimit(): number;
+    /**
+     * Get current history size.
+     *
+     * @returns Number of states in history
+     */
+    getHistorySize(): number;
+    /**
+     * Save a state to history using circular buffer.
+     * Private helper for advanceToNextTick.
+     *
+     * @param state - State to save
+     */
+    private saveToHistory;
+}

package/dist/core/simulation/behaviors/BehaviorRegistry.d.ts

@@ -0,0 +1,70 @@
+import { IComponentBehavior } from './types';
+/**
+ * Registry for component behavior implementations.
+ * Maps component types to their behavior handlers.
+ *
+ * This allows the simulation controller to be extended with new component types
+ * without modifying core simulation logic.
+ *
+ * @public
+ */
+export declare class BehaviorRegistry {
+    private behaviors;
+    /**
+     * Create a new empty behavior registry.
+     */
+    constructor();
+    /**
+     * Register a behavior for a component type.
+     * Overwrites any existing behavior for the same type.
+     *
+     * @param behavior - The component behavior to register
+     * @throws TypeError if behavior is null/undefined or componentType is empty
+     * @returns The registry instance for chaining
+     */
+    register(behavior: IComponentBehavior): BehaviorRegistry;
+    /**
+     * Register multiple behaviors at once.
+     * Convenience method for bulk registration.
+     *
+     * @param behaviors - Array of behaviors to register
+     */
+    registerAll(behaviors: IComponentBehavior[]): void;
+    /**
+     * Get the behavior for a component type.
+     *
+     * @param componentType - Type identifier (e.g., "battery", "led")
+     * @returns The registered behavior, or undefined if not found
+     */
+    get(componentType: string): IComponentBehavior | undefined;
+    /**
+     * Check if a behavior is registered for a component type.
+     *
+     * @param componentType - Type identifier to check
+     * @returns True if behavior is registered
+     */
+    has(componentType: string): boolean;
+    /**
+     * Unregister a behavior for a component type.
+     *
+     * @param componentType - Type identifier to unregister
+     * @returns True if behavior was found and removed
+     */
+    unregister(componentType: string): boolean;
+    /**
+     * Clear all registered behaviors.
+     */
+    clear(): void;
+    /**
+     * Get all registered component types.
+     *
+     * @returns Array of component type identifiers
+     */
+    getRegisteredTypes(): string[];
+    /**
+     * Get count of registered behaviors.
+     *
+     * @returns Number of registered behaviors
+     */
+    size(): number;
+}

package/dist/core/simulation/behaviors/ComponentBehavior.d.ts

@@ -0,0 +1,53 @@
+import { Component } from '../../topology/Component';
+import { ComponentState } from '../states/ComponentState.js';
+import { IScheduledEvent, IUserCommand } from '../types';
+import { IBehaviorResult } from './types';
+import { INodeElectricalState } from '../states/types';
+import { UUID } from '../../utils/types';
+import { ComponentType, ENodeSourceType, IComponentTypeMetadata } from '../../topology/types';
+/**
+ * to factorize default implementations in component behaviors
+ */
+export declare abstract class ComponentBehaviorMixin {
+    /**
+     * Component type this behavior handles (e.g., "battery", "led", "switch").
+     * Used as the key in BehaviorRegistry.
+     */
+    protected readonly _componentType: ComponentType;
+    constructor(componentType: ComponentType);
+    get componentType(): ComponentType;
+    protected get typeMetadata(): IComponentTypeMetadata;
+    protected getPinStates(component: Component, nodeStates: ReadonlyMap<UUID, INodeElectricalState>): Map<string, INodeElectricalState>;
+    protected getChangedPins(newPinStates: Map<string, INodeElectricalState>, prevPinStates: Map<string, INodeElectricalState>): Set<string>;
+    /**
+     * Default: no custom onStart behavior
+     * @param _component
+     * @param _componentState
+     */
+    onStart(_component: Component, _componentState: ComponentState): IBehaviorResult | null;
+    /**
+     * Default: nothing happens
+     * @param _component
+     * @param componentState
+     * @param _nodeStates
+     * @param _targetTick
+     */
+    onPinsChange(_component: Component, componentState: ComponentState, _nodeStates: ReadonlyMap<UUID, INodeElectricalState>, _targetTick: number): IBehaviorResult;
+    /**
+     * Default: no conductivity between pins
+     * @param _component
+     * @param _state
+     * @param _conductivityType
+     * @param _pinId
+     * @param _otherPinId
+     */
+    allowConductivity(_component: Component, _state: ComponentState, _conductivityType: ENodeSourceType, _pinId: string, _otherPinId: string): boolean;
+    onUserCommand(_component: Component, state: ComponentState, _command: IUserCommand): IBehaviorResult;
+    onEventFiring(_component: Component, state: ComponentState, _event: IScheduledEvent): IBehaviorResult;
+}
+/**
+ * Get the transition span from component config.
+ * @param config - Component config map
+ * @returns Number of ticks for transition (minimum 1)
+ */
+export declare function getTransitionSpan(config: Map<string, string>): number;

package/dist/core/simulation/behaviors/arithmetic/AdderBehavior.d.ts

@@ -0,0 +1,28 @@
+import { Component } from '../../../topology/Component';
+import { ComponentState } from '../../states/ComponentState';
+import { INodeElectricalState } from '../../states/types';
+import { IComponentBehavior } from '../types';
+import { ArithmeticBehaviorMixin } from './ArithmeticBehaviorMixin';
+/**
+ * Behavior for the Full Adder component (two half adders + OR on carries).
+ *
+ * Three logic inputs (`inputA`, `inputB`, `carryIn`) and two logic outputs
+ * (`sum`, `carryOut`):
+ *
+ * - `sum = A XOR B XOR carryIn` (parity of the three inputs)
+ * - `carryOut = majority(A, B, carryIn)` (two or more inputs high)
+ *
+ * State encoding follows `${sumBit}${carryBit}` — see {@link AdderState}. All
+ * four stable states are reachable; `A = B = carryIn = 1` yields `'11'`.
+ *
+ * A single medium `transitionSpan` from config is used for every transition,
+ * since modeling the cumulative XOR/AND/OR delays per input-output pair would
+ * be more complexity than this library's teaching scope warrants.
+ *
+ * @public
+ */
+export declare class AdderBehavior extends ArithmeticBehaviorMixin implements IComponentBehavior {
+    constructor();
+    createInitialState(component: Component): ComponentState;
+    protected computeTargetStableState(pinStates: Map<string, INodeElectricalState>): string;
+}

package/dist/core/simulation/behaviors/arithmetic/ArithmeticBehaviorMixin.d.ts

@@ -0,0 +1,63 @@
+import { Component } from '../../../topology/Component';
+import { ComponentState } from '../../states/ComponentState';
+import { INodeElectricalState } from '../../states/types';
+import { UUID } from '../../../utils/types';
+import { ENodeSourceType } from '../../../topology/types';
+import { IBehaviorResult } from '../types';
+import { IScheduledEvent } from '../../types';
+import { ComponentBehaviorMixin } from '../ComponentBehavior';
+import { ArithmeticState } from '../../states/arithmetic/ArithmeticState';
+/**
+ * Factorises the common plumbing of arithmetic component behaviors:
+ *
+ * - `vccGuardBehavior` — on vcc loss, drop all outputs low immediately.
+ * - `nonLogicInputGuardBehavior` — on any ill-defined logic input, go to
+ *   `'indeterminate'` immediately.
+ * - `onPinsChange` is a **template method** that runs the guards then calls
+ *   `computeTargetStableState` (subclass-provided) and schedules the
+ *   transition via `scheduleTransition`.
+ * - `scheduleTransition` — encode the `to${target}` transient state, schedule
+ *   the completion event and preserve the previous stable state in
+ *   `parameters.prevState` so `allowConductivity` keeps the old outputs
+ *   energized until the transition fires.
+ * - `onEventFiring` — land on the target stable state when the scheduled
+ *   transition completes.
+ * - `allowConductivity` — generic per-output lookup driven by
+ *
+ * Subclasses must declare `outputPinLabels` in the **same order** as the
+ * state encoding used by their {@link ArithmeticState} subclass and
+ * implement `computeTargetStableState` to turn the current input pins into
+ * that encoding.
+ */
+export declare abstract class ArithmeticBehaviorMixin extends ComponentBehaviorMixin {
+    /**
+     * Compute the target stable-state encoding from the current pin states.
+     * Called only after vcc / non-logic guards have passed.
+     */
+    protected abstract computeTargetStableState(pinStates: Map<string, INodeElectricalState>): string;
+    onPinsChange(component: Component, state: ComponentState, nodeStates: ReadonlyMap<UUID, INodeElectricalState>, targetTick: number): IBehaviorResult;
+    onEventFiring(_component: Component, state: ComponentState, event: IScheduledEvent): IBehaviorResult;
+    allowConductivity(component: Component, state: ComponentState, _conductivityType: ENodeSourceType, pinId: string, otherPinId: string): boolean;
+    /**
+     * On vcc loss: all outputs go low immediately.
+     * Returns `null` when vcc is present so callers can proceed.
+     */
+    protected vccGuardBehavior(state: ArithmeticState, pinStates: Map<string, INodeElectricalState>, targetTick: number): IBehaviorResult | null;
+    /**
+     * Scan all logic inputs; if any is ill-defined (both voltage and ground,
+     * or neither), switch to `'indeterminate'` immediately. Otherwise returns
+     * `null` so the caller can proceed.
+     */
+    protected nonLogicInputGuardBehavior(state: ArithmeticState, pinStates: Map<string, INodeElectricalState>, targetTick: number): IBehaviorResult | null;
+    /**
+     * Schedule a transition toward the given stable target state. If already
+     * there (or already heading there) returns a no-change result.
+     *
+     * Preserves the currently-driving stable state in `parameters.prevState` so
+     * `allowConductivity` keeps the old outputs energized until the scheduled
+     * event fires. When the previous effective state is `'indeterminate'` the
+     * fallback is all-zeros.
+     */
+    protected scheduleTransition(component: Component, state: ArithmeticState, targetState: string, targetTick: number): IBehaviorResult;
+    protected noChange(state: ComponentState): IBehaviorResult;
+}