::ngspicetclbridgeTop, Main, Index
CommandsTop, Main, Index
abort [::ngspicetclbridge]Top, Main, Index
Set an internal abort flag and wake any waiters (useful to force waitevent to return). This does not free the instance.
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).
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.
command [::ngspicetclbridge]Top, Main, Index
Send an arbitrary Ngspice command line (e.g., bg_run, circbyline ..., .save, .tran, .dc).
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
Delete the instance command. In details:
Description
- Marks the context as destroying
- Wakes any waiters
- Quiesces the ngspice background thread
- Defers and performs full cleanup
eventcounts [::ngspicetclbridge]Top, Main, Index
Get or reset the cumulative event counters for this simulator instance.
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
Initialize the ngspice shared instance and the bridge’s data structures.
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
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
Asynchronous call to check if background thread is running.
Return value
1 if thread is running, 0 otherwise.
messages [::ngspicetclbridge]Top, Main, Index
Queue of textual messages captured from Ngspice (stdout/stderr) and bridge status lines.
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.
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
vectors [::ngspicetclbridge]Top, Main, Index
Returns held asynchronously accumulated vector values (built from send_data events) in a dict. dict with vectors values accumulated up to this point in internal structure
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)
Warning: accumulation of data continues even if you run new circuit or analysis until you explicitly clear the data storage.
Return value
Returns held asynchronously 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
Block until a named event is observed, the instance is aborted/destroyed, or the timeout expires (if provided).
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