::ngspicetclbridgeTop, Main, Index

CommandsTop, Main, Index

abort [::ngspicetclbridge]Top, Main, Index

Sets an internal abort flag and wake any waiters (useful to force waitevent to return). This does not free the instance.

abort

asyncvector [::ngspicetclbridge]Top, Main, Index

Fetches the current values of a named vector on demand via ngspice ngGet_Vec_Info. Works after the simulation has produced any data (not necessarily the complete vector).

asyncvector name

Parameters

name Name of the vector.

Description

Example:

$sim initvectors
$sim asyncvector out
# -> {0.0 0.066666... 0.133333... ...}

$sim asyncvector V(9)
# -> {{0.01 0.00} {0.02 0.00} ...}   ;# if complex

Return value

real vectors as a flat list of doubles, complex vectors as a list of {re im} pairs. Error if vector does not exists.

circuit [::ngspicetclbridge]Top, Main, Index

Sends an circuit to Ngspice in form of the list, each element is the lineof the netlist.

circuit list

Parameters

list List of string.

Description

Example:

set resDivCircuit {
    Resistor divider
    v1 in 0 1
    r1 in out 1e3
    r2 out 0 2e3
    .dc v1 0 5 0.1
    .save all
    .end
}
$sim circuit [split $resDivCircuit \n]
$sim command bg_run

Return value

Ngspice result code

command [::ngspicetclbridge]Top, Main, Index

Sends an arbitrary Ngspice command line (e.g., bg_run, circbyline ..., .save, .tran, .dc).

command string

Parameters

string Command string.

Description

Example:

$sim command {circbyline v1 in 0 1}
$sim command bg_run

Return value

Ngspice result code

destroy [::ngspicetclbridge]Top, Main, Index

Deletes the instance command. In details:

destroy

Description

Marks the context as destroying
Wakes any waiters
Quiesces the ngspice background thread
Defers and performs full cleanup

eventcounts [::ngspicetclbridge]Top, Main, Index

Gets or reset the cumulative event counters for this simulator instance.

eventcounts ?-clear?

Parameters

-clear Zeros all counts and returns nothing.

Description

Example:

$sim eventcounts
# -> send_char N  send_stat N  controlled_exit N send_data N  send_init_data N  bg_running N

Return value

returns a dict with keys as events names, and counts for each event as a value

init [::ngspicetclbridge]Top, Main, Index

Initializes the ngspice shared instance and the bridge’s data structures.

init

Description

Example:

$sim init

Return value

Ngspice init code

initvectors [::ngspicetclbridge]Top, Main, Index

Returns held initial vector metadata (built from send_init_data) in a dict. dict with initial vector metadata saved in internal structure

initvectors ?-clear?

Parameters

-clear Empties the internal memory structure and returns nothing.

Description

Example:

$sim initvectors
# -> out {number 1 real 1} in {number 2 real 1} v-sweep {number 3 real 1}

Warning: accumulation of data do not continues after call bg_run, new metadata replace the old one in the storage.

Return value

Returns held initial vector metadata (built from send_init_data) in a dict. dict with initial vector metadata saved in internal structure

isrunning [::ngspicetclbridge]Top, Main, Index

Calls asynchronously to check if background thread is running.

isrunning

Return value

1 if thread is running, 0 otherwise.

messages [::ngspicetclbridge]Top, Main, Index

Queues of textual messages captured from Ngspice (stdout/stderr) and bridge status lines.

messages ?-clear?

Parameters

-clear Empties the internal queue structure and returns nothing.

Description

Example:

join [$sim messages] \n
# stdout ******
# stdout ** ngspice-44.x shared library
# ...
# # status[0]: --ready--

Warning: accumulation of messages continues even if you run new circuit or analysis until you explicitly clear the data storage.

Return value

list of messages

new [::ngspicetclbridge]Top, Main, Index

Load dynamic library, path should be provided in native form for target OS. Every ::ngspicetclbridge::new returns a command (e.g. ::ngspicetclbridge::s1). The following subcommands operate on that instance.

new path

Parameters

path Absolute full path to dynamic library.

Description

Example:

set sim [::ngspicetclbridge::new /usr/local/lib/libngspice.so]

Return value

command name to work with Ngspice instance

plot [::ngspicetclbridge]Top, Main, Index

Returns current plot name if no arguments provided, names of all plots or all vectors names that belongs to name of the provided plot. current plot, or list of all plots, or list of all vectors

plot -all
plot -vecs name

Parameters

`-all`	Switch to return all plots names.
`-vecs plotname`	Switch with argument to get all vectors names belonging to `name` plot.

Return value

Returns current plot name if no arguments provided, names of all plots or all vectors names that belongs to name of the provided plot. current plot, or list of all plots, or list of all vectors

vectors [::ngspicetclbridge]Top, Main, Index

Returns held synchronously accumulated vector values (built from send_data events) in a dict. dict with vectors values accumulated up to this point in internal structure

vectors ?-clear?

Parameters

-clear Empties the internal memory structure and returns nothing.

Description

Example:

$sim vectors
# -> v(out) {0.0 0.1 0.2 ...} v(in) {...} v-sweep {...}

$sim vectors -clear
# -> (no result; succeeds)

Return value

Returns held synchronously accumulated vector values (built from send_data events) in a dict. dict with vectors values accumulated up to this point in internal structure

waitevent [::ngspicetclbridge]Top, Main, Index

Blocks until a named event is observed, the instance is aborted/destroyed, or the timeout expires (if provided).

waitevent ?args?

Parameters

`name`	Name of the event.
`timeout_ms`	Timeout in miliseconds, optional.

Description

Event name	Ngspice callback function name	When it is called
`send_char`	SendChar	Whenever Ngspice produces a line of text on stdout or stderr.
`send_stat`	SendStat	When Ngspice’s simulation status changes (e.g., --ready--, tran 50.1%, convergence messages).
`controlled_exit`	ControlledExit	When Ngspice exits, either due to an error or after a quit command from Tcl/Ngspice.
`send_data`	SendData	During an analysis, whenever Ngspice sends a row of vector values (time step or sweep point) to the callback.
`send_init_data`	SendInitData	At the start of a run, when Ngspice sends metadata for all vectors in the current plot (names, types, indexes, real/complex).
`bg_running`	BGThreadRunning	When the Ngspice background thread changes state: `running=false` means it just started running, `running=true` means it has stopped.

Time	Tcl Script Action	Ngspice Core Activity	Bridge Callback Fired	Tcl Event Name Seen
t0	`set s [..::new ..]`	Library loaded	(none)	(none)
t1	`$sinit`	Initialization completed	(none)	(none)
t2	`cirPass …`	Parses circuit line	`send_char("...")`	`send_char`
t3	(more circbyline calls)	Parses circuit line	`send_char("...")`	`send_char`
t4	`$scommand bg_run`	Start background simulation	`bg_running(false)`	`bg_running`
t5	(analysis setup)	Build vector table	`send_init_data()`	`send_init_data`
t6	(analysis running)	First data point	`send_data(...)`	`send_data`
t7	(analysis running)	More points	`send_data(...)`	`send_data`
t8	(analysis running)	Status change	`send_stat("...")`	`send_stat`
t9	(analysis completed)	Simulation ready	`send_stat("--ready--")`	`send_stat`
t10	(BG thread exits)	Background thread exits	`bg_running(true)`	`bg_running`
t11	`$scommand quit`	ngspice quits	`controlled_exit(...)`	`controlled_exit`
t12	`$sdestroy`	Teardown	(no further calls)	(command removed)

Return value

dictionary with information about event