@celox-sim/celox / index / Simulation

Class: Simulation<P>

Defined in: packages/celox/src/simulation.ts:55

Type Parameters

P

P = Record<string, unknown>

Accessors

dut

Get Signature

get dut(): P

Defined in: packages/celox/src/simulation.ts:338

The DUT accessor object — read/write ports as plain properties.

Returns

P

---

warnings

Get Signature

get warnings(): readonly string[]

Defined in: packages/celox/src/simulation.ts:343

Analyzer warnings emitted during compilation.

Returns

readonly string[]

Methods

addClock()

addClock(name, opts): void

Defined in: packages/celox/src/simulation.ts:353

Register a periodic clock.

Parameters

name

string

Clock event name (must match a clock port).

opts

period in time units; optional initialDelay.

initialDelay?

number

period

number

Returns

void

---

dispose()

dispose(): void

Defined in: packages/celox/src/simulation.ts:578

Release native resources.

Returns

void

---

dump()

dump(timestamp): void

Defined in: packages/celox/src/simulation.ts:572

Write current signal values to VCD at the given timestamp.

Parameters

timestamp

number

Returns

void

---

fourState()

fourState(portName): FourStateValue

Defined in: packages/celox/src/simulation.ts:559

Read the raw 4-state (value + mask) pair for the named port.

Parameters

portName

string

Returns

FourStateValue

---

nextEventTime()

nextEventTime(): number | null

Defined in: packages/celox/src/simulation.ts:431

Peek at the time of the next scheduled event without advancing.

Returns

number | null

The time of the next event, or null if no events are scheduled.

---

reset()

reset(signal, opts?): void

Defined in: packages/celox/src/simulation.ts:511

Assert and release a reset signal.

The active level is determined automatically from the Veryl type:

• reset / reset_async_high / reset_sync_high → active-high (1)
• reset_async_low / reset_sync_low → active-low (0)

For sync resets (with an associated clock from FfDeclaration), advances activeCycles worth of the associated clock's period using runUntil. For async resets without an associated clock, duration must be specified. An explicit duration overrides cycle-based calculation for either type.

Parameters

signal

string

opts?

activeCycles?

number

duration?

number

Returns

void

---

runUntil()

runUntil(endTime, opts?): void

Defined in: packages/celox/src/simulation.ts:383

Run the simulation until the given time. Processes all scheduled events up to and including endTime.

When maxSteps is provided, steps are counted in TS and a SimulationTimeoutError is thrown if the budget is exhausted before reaching endTime. Without maxSteps the fast Rust path is used.

Parameters

endTime

number

opts?

maxSteps?

number

Returns

void

---

schedule()

schedule(name, opts): void

Defined in: packages/celox/src/simulation.ts:369

Schedule a one-shot value change for a signal.

Parameters

name

string

Event/signal name.

opts

time — absolute time to apply; value — value to set.

time

number

value

number

Returns

void

---

step()

step(): number | null

Defined in: packages/celox/src/simulation.ts:413

Advance to the next scheduled event.

Returns

number | null

The time of the processed event, or null if no events remain.

---

time()

time(): number

Defined in: packages/celox/src/simulation.ts:421

Current simulation time.

Returns

number

---

waitForCycles()

waitForCycles(clock, count, opts?): number

Defined in: packages/celox/src/simulation.ts:472

Wait for count rising edges of the given clock.

Detects actual 0→1 transitions by reading the clock signal directly from the shared buffer (clock ports are excluded from the DUT proxy). The clock must have been registered via addClock.

Parameters

clock

string

count

number

opts?

maxSteps?

number

Returns

number

The simulation time after the edges are observed.

Throws

SimulationTimeoutError if maxSteps is exceeded.

---

waitUntil()

waitUntil(condition, opts?): number

Defined in: packages/celox/src/simulation.ts:442

Step until condition() returns true.

Parameters

condition

() => boolean

opts?

maxSteps?

number

Returns

number

The simulation time when the condition became true.

Throws

SimulationTimeoutError if maxSteps is exceeded.

---

create()

static create<P>(module, options?): Simulation<P>

Defined in: packages/celox/src/simulation.ts:105

Create a Simulation for the given module.

import { Top } from "./generated/Top.js";
const sim = Simulation.create(Top);
sim.addClock("clk", { period: 10 });

Type Parameters

P

P

Parameters

module

ModuleDefinition<P>

options?

SimulatorOptions & object

Returns

Simulation<P>

---

fromProject()

static fromProject<P>(projectPath, top, options?): Simulation<P>

Defined in: packages/celox/src/simulation.ts:267

Create a Simulation from a Veryl project directory.

Searches upward from projectPath for Veryl.toml, gathers all .veryl source files, and builds the simulation using the project's clock/reset settings.

const sim = Simulation.fromProject<MyPorts>("./my-project", "Top");
sim.addClock("clk", { period: 10 });

Type Parameters

P

P = Record<string, unknown>

Parameters

projectPath

string

top

string

options?

SimulatorOptions & object

Returns

Simulation<P>

---

fromSource()

static fromSource<P>(source, top, options?): Simulation<P>

Defined in: packages/celox/src/simulation.ts:187

Create a Simulation directly from Veryl source code.

Automatically discovers ports from the NAPI layout — no ModuleDefinition needed.

const sim = Simulation.fromSource<CounterPorts>(COUNTER_SOURCE, "Counter");
sim.addClock("clk", { period: 10 });
sim.runUntil(100);

Type Parameters

P

P = Record<string, unknown>

Parameters

source

string

top

string

options?

SimulatorOptions & object

Returns

Simulation<P>