@celox-sim/celox / index / Simulation
Class: Simulation<P>
Defined in: packages/celox/src/simulation.ts:56
Type Parameters
P
P = Record<string, unknown>
Accessors
dut
Get Signature
get dut():
P
Defined in: packages/celox/src/simulation.ts:390
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:395
Analyzer warnings emitted during compilation.
Returns
readonly string[]
Methods
addClock()
addClock(
name,opts):void
Defined in: packages/celox/src/simulation.ts:405
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
checkpoint()
checkpoint():
SimulationCheckpoint
Defined in: packages/celox/src/simulation.ts:683
Save the design state, simulation time, clocks and pending events.
The checkpoint can be restored any number of times, into this simulation or into another one created from the same design.
Returns
dispose()
dispose():
void
Defined in: packages/celox/src/simulation.ts:753
Release native resources.
Returns
void
dump()
dump(
timestamp):void
Defined in: packages/celox/src/simulation.ts:672
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:655
Read the raw 4-state (value + mask) pair for the named port.
Like an output read through dut, this evaluates combinational logic first when inputs changed since the last evaluation.
Parameters
portName
string
Returns
isFinished()
isFinished():
boolean
Defined in: packages/celox/src/simulation.ts:502
Whether a process of the design requested the end of the simulation. Once it has, step() and nextEventTime() return null.
Returns
boolean
loadState()
loadState(
bytes):void
Defined in: packages/celox/src/simulation.ts:742
Load state file bytes saved by Simulation.saveState(), including the simulation time, clocks and pending events.
Throws without changing anything if the file does not match this design or was saved from a Simulator, or if VCD output has already passed the saved time; call switchVcd() first then.
Parameters
bytes
Uint8Array
Returns
void
nextEventTime()
nextEventTime():
number|null
Defined in: packages/celox/src/simulation.ts:493
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:584
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
restore()
restore(
checkpoint):void
Defined in: packages/celox/src/simulation.ts:697
Return to the state saved in checkpoint, including its simulation time.
Throws if the checkpoint comes from another design, or if VCD output has already passed the checkpoint's time; call switchVcd() first then.
Parameters
checkpoint
Returns
void
runUntil()
runUntil(
endTime,opts?):void
Defined in: packages/celox/src/simulation.ts:435
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
saveState()
saveState():
Uint8Array
Defined in: packages/celox/src/simulation.ts:724
Save the value of every state object, by signal path, together with the simulation time, clocks and pending events, as state file bytes.
Returns
Uint8Array
schedule()
schedule(
name,opts):void
Defined in: packages/celox/src/simulation.ts:421
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:475
Advance to the next scheduled event.
Returns
number | null
The time of the processed event, or null if no events remain.
switchVcd()
switchVcd(
path):void
Defined in: packages/celox/src/simulation.ts:712
Finish the current VCD file and continue the waveform in a new file at path, whose timestamps start over. Call it before restore() or loadState() returns to a time the current file has already passed.
Parameters
path
string
Returns
void
time()
time():
number
Defined in: packages/celox/src/simulation.ts:483
Current simulation time.
Returns
number
waitForCycles()
waitForCycles(
clock,count,opts?):number
Defined in: packages/celox/src/simulation.ts:545
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:513
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()
staticcreate<P>(module,options?):Simulation<P>
Defined in: packages/celox/src/simulation.ts:106
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
options?
SimulatorOptions & object
Returns
Simulation<P>
fromFrontendArtifact()
staticfromFrontendArtifact<P>(artifactJson,options?):Simulation<P>
Defined in: packages/celox/src/simulation.ts:251
Create a timed Simulation from an external frontend artifact.
Type Parameters
P
P = Record<string, unknown>
Parameters
artifactJson
string
options?
SimulatorOptions & object
Returns
Simulation<P>
fromProject()
staticfromProject<P>(projectPath,top,options?):Simulation<P>
Defined in: packages/celox/src/simulation.ts:314
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()
staticfromSource<P>(source,top,options?):Simulation<P>
Defined in: packages/celox/src/simulation.ts:177
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>