Circuit

Circuit

Circuit(name: str | None = None, vcd: str | None = None)

A circuit: holds the components and runs the simulation. Use it in a with statement, with Circuit(vcd="waves.vcd") as circuit:, to close the VCD file at the end.

Parameters:

Name	Type	Description	Default
name	str | None	The circuit name, needed to save the circuit.	None
vcd	str | None	A VCD file to write waveforms to, from init().	None

name property

name: str | None

Get the circuit name

time_ns property

time_ns: int

Get the current simulation time (ns)

components property

components: list[Component]

Get the components in this circuit

init

init() -> None

Initialize the circuit: set the time to 0 and all ports to "X", then let the components set their default state. Call it after adding and connecting components.

run

run(
    s: float | None = None,
    ms: float | None = None,
    us: float | None = None,
    ns: float | None = None,
    single_step: bool = False,
) -> bool

Run the simulation for a period of time. The times are added together, so run(ms=1, us=500) runs for 1.5 ms.

Parameters:

Name	Type	Description	Default
s	float | None	Seconds.	None
ms	float | None	Milliseconds.	None
us	float | None	Microseconds.	None
ns	float | None	Nanoseconds.	None
single_step	bool	Stop after the first event on a port of a top-level component, at the end of its time (the GUI's Single Step).	False

Returns:

Type	Description
bool	True if the run stopped for a single step.

run_until

run_until(
    s: float | None = None,
    ms: float | None = None,
    us: float | None = None,
    ns: float | None = None,
) -> None

Run the simulation until an absolute time, nothing happens if it has passed. The times are added together.

Parameters:

Name	Type	Description	Default
s	float | None	Seconds.	None
ms	float | None	Milliseconds.	None
us	float | None	Microseconds.	None
ns	float | None	Nanoseconds.	None

process_single_event

process_single_event(
    stop_time_ns: int | None = None,
) -> tuple[bool, bool]

Process only the next event, to step through a simulation.

Parameters:

Name	Type	Description	Default
stop_time_ns	int | None	Don't process an event after this time, keep it for later.	None

Returns:

Type	Description
bool	If an event was processed (False if there were none, or the next one is after
bool	stop_time_ns), and if it was on a port of a top-level component, rather than
tuple[bool, bool]	inside one like a Yosys component.

vcd

vcd(filename: str) -> None

Start writing waveforms to a VCD file, for GTKWave or another viewer.

Raises:

Type	Description
CircuitError	If a VCD file is already open.
OSError	If the file can't be opened.

vcd_close

vcd_close() -> None

Finish and close the VCD file, if one is open

get_component

get_component(component_name: str) -> Component

Get a component by its name.

Raises:

Type	Description
CircuitError	If the circuit has no component with the name.

get_toplevel_components

get_toplevel_components() -> list[Component]

Get toplevel components in the circuit

delete_component

delete_component(component: Component) -> None

Delete a component, and the components it is built from, from the circuit

clear

clear() -> None

Remove all components, and the events of their ports

to_json_file

to_json_file(filename: str | Path) -> None

Save the circuit in a JSON file. File paths in it, like a Verilog file, are stored relative to the file's folder. The circuit needs a name.

from_json_file

from_json_file(
    filename: str | Path, folder: str | None = None
) -> None

Load a circuit from a JSON file, replacing the circuit's components.

Parameters:

Name	Type	Description	Default
filename	str | Path	The file.	required
folder	str | None	The folder that relative file paths in the file are read from, by default the file's folder (where to_json_file() stores them relative to).	None

to_dataclass

to_dataclass(folder: str = '.') -> CircuitDataClass

The circuit as a data class, used when saving it.

Parameters:

Name	Type	Description	Default
folder	str	File paths, like a Verilog file, are stored relative to this folder.	'.'

from_dataclass

from_dataclass(
    circuit_dc: CircuitDataClass,
    folder: str = "",
    component_exceptions: bool = True,
    connect_exceptions: bool = True,
) -> list[str]

Replace the circuit's components with the ones in a data class.

Parameters:

Name	Type	Description	Default
circuit_dc	CircuitDataClass	The circuit data class, for example from a loaded file.	required
folder	str	The folder that relative file paths are read from.	''
component_exceptions	bool	Raise when a component can't be created, otherwise skip it and report it in the returned list.	True
connect_exceptions	bool	Raise when a wire can't be connected, otherwise skip it and report it in the returned list.	True

Returns:

Type	Description
list[str]	The errors for the skipped components and wires.