::ngspicetclbridge¶

Commands¶

`getCircuit`¶

Gets list with currently loaded circuit (its listing) in the form specified by the switch.

getCircuit ?-logical|-physical|-deck|-expand|-runnable|-param? sim

Parameters

-deck:: Just like the physical listing, except without the line numbers it recreates the input file verbatim (except that it does not preserve case)
-expand:: The circuit is printed with all subcircuits expanded.
-logical:: The circuit is with all continuation lines collapsed into one line.
-param:: Printing all parameters and their actual values.
-physical:: The circuits lines are printed out as they were found in the file.
-runnable:: Circuit netlist expanded, but without additional line numbers, ready to be sourced again and run in ngspice. Default version if no witch is provided.
sim:: Simulator handler that is returned by ngspicetclbridge::new

Return value

list with listing lines

`getCircuitTitle`¶

Gets title of the current circuit (first line of circuits netlist).

getCircuitTitle sim

Parameters

sim:: Not documented.

Return value

title

`getPlotDate`¶

Gets time stamp of current plot generation.

getPlotDate sim

Parameters

sim:: Not documented.

Return value

time stamp

`getPlotName`¶

Gets name of the current plot, i.e. Operating Point, AC Analysis, etc.

getPlotName sim

Parameters

sim:: Not documented.

Return value

name of the plot

`getScaleInfo`¶

Gets dictionary with information about current scale vector.

getScaleInfo sim

Parameters

sim:: Not documented.

Return value

dictionary with the information

`new`¶

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. Optionally the spinit and/or spiceinit initialization files could be forbidden for loading.

new ?-nospinit|nospiceinit|noinit? libpath

Parameters

-noinit:: Inhibit both spinit and spiceinit.
-nospiceinit:: Inhibits spiceinit.
-nospinit:: Inhibits spinit.
libpath:: 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, references as SIM later

`readVecsAsync`¶

Reads all availible vectors of the current plot asynchronously and return dictionary with vector name as a key, and data as a value. If -info switch is provided, command returns information about each availiable vector.

readVecsAsync ?-info? sim

Parameters

-info:: If provided, metainfo about vectors is returned instead of the data.
sim:: Simulator handler that is returned by ngspicetclbridge::new

Return value

dictionary

`run`¶

Runs simulation in background thread, waits for the completion, process event in the queue and returns

run sim

Parameters

sim:: Simulator handler that is returned by ngspicetclbridge::new

Return value

`SIM`¶

A command ensemble.

SIM subcommand ...

Description

The ensemble supports the following subcommands:

abort: Sets an internal abort flag and wake any waiters (useful to force waitevent to return). This does not free the instance.
asyncvector: 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). By addding -info switch, vector metadata is provided, i.e. type of the vector (current, voltage, time, etc), type of the numbers (complex or real), and length of the vector.
circuit: Sends an circuit to Ngspice in form of the Tcl list, each element is the line of the netlist. If switch -string is provided, the input netlists could be passed as ordinary string with newline character as a separator between netlists lines.
command: Sends an arbitrary Ngspice command line (e.g., bg_run, circbyline …, .save, .tran, .dc). If we provide -capture switch, it returns not only the result code, but also the next message from stdout of Ngspice. Also, if command is send in the moment background thread is starting or stopping, it will be deferred to the time is could be safely sent, and in that case -capture message and command results code are not availaible as a return of command.
destroy: Deletes the instance command. In details:
eventcounts: Gets or reset the cumulative event counters for this simulator instance.
initvectors: Returns held initial vector metadata (built from send_init_data) in a dict. dict with initial vector metadata saved in internal structure.
inputpath: Returns current path for XSPICE code models if -current switch is provided, or set current path to value provided. current path.
isrunning: Calls asynchronously to check if background thread is running.
messages: Queues of textual messages captured from Ngspice (stdout/stderr) and bridge status lines.
plot: 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: 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: Blocks until a named event is observed n number of times (or once), the instance is aborted/destroyed, or the timeout expires (if provided).

Refer to the documentation of each subcommand for details.

`SIM abort`¶

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

SIM abort

`SIM asyncvector`¶

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). By addding -info switch, vector metadata is provided, i.e. type of the vector (current, voltage, time, etc), type of the numbers (complex or real), and length of the vector.

SIM asyncvector ?-info? name

Parameters

name:: Name of the vector.
-info:: If this switch is provided, commands return dictionary with vector metadata.

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.

`SIM circuit`¶

Sends an circuit to Ngspice in form of the Tcl list, each element is the line of the netlist. If switch -string is provided, the input netlists could be passed as ordinary string with newline character as a separator between netlists lines.

SIM circuit ?-string? circuit

Parameters

-string:: Allows to pass circuit as ordinary string.
circuit:: 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

`SIM command`¶

Sends an arbitrary Ngspice command line (e.g., bg_run, circbyline …, .save, .tran, .dc). If we provide -capture switch, it returns not only the result code, but also the next message from stdout of Ngspice. Also, if command is send in the moment background thread is starting or stopping, it will be deferred to the time is could be safely sent, and in that case -capture message and command results code are not availaible as a return of command.

SIM command string

Parameters

string:: Command string.

Description

Example:

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

Return value

Ngspice result code, or dictionary with result code and the message

`SIM destroy`¶

Deletes the instance command. In details:

SIM destroy

Description

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

`SIM eventcounts`¶

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

SIM 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

`SIM initvectors`¶

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

SIM 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

`SIM inputpath`¶

Returns current path for XSPICE code models if -current switch is provided, or set current path to value provided. current path

SIM inputpath -current
SIM inputpath path

Parameters

-current:: Switch to return current path.
path:: Full path to desired location.

Return value

Returns current path for XSPICE code models if -current switch is provided, or set current path to value provided. current path

`SIM isrunning`¶

Calls asynchronously to check if background thread is running.

SIM isrunning

Return value

1 if thread is running, 0 otherwise.

`SIM messages`¶

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

SIM 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

`SIM plot`¶

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

SIM plot -all
SIM 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

`SIM vectors`¶

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

SIM 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

`SIM waitevent`¶

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

SIM waitevent name ?-n N? ?timeout_ms?

Parameters

-n N:: Number of events that should happend for termination after waiting is started.
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	`$s init`	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	`$s command 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	`$s command quit`	ngspice quits	`controlled_exit(...)`	`controlled_exit`
t12	`$s destroy`	Teardown	(no further calls)	(command removed)

Result dictionary of the command:

fired - 0|1, whether the event occurred during this wait
count - cumulative total count for that event so far
status - ok | timeout | aborted

Examples:

$sim waitevent send_stat 1000
# -> {fired 1 count 1 status ok}

$sim waitevent send_stat 1000
# -> {fired 0 count 1 status timeout}  ;# nothing new in the next 1s

If you want “fresh” waits, you can clear counts with eventcounts -clear.

Return value

dictionary with information about event

Copyright (c) George Yashin

::ngspicetclbridge¶

Commands¶

`getCircuit`¶

`getCircuitTitle`¶

`getPlotDate`¶

`getPlotName`¶

`getScaleInfo`¶

`new`¶

`readVecsAsync`¶

`run`¶

`SIM`¶

`SIM abort`¶

`SIM asyncvector`¶

`SIM circuit`¶

`SIM command`¶

`SIM destroy`¶

`SIM eventcounts`¶

`SIM initvectors`¶

`SIM inputpath`¶

`SIM isrunning`¶

`SIM messages`¶

`SIM plot`¶

`SIM vectors`¶

`SIM waitevent`¶

Table of Contents

Previous topic

Next topic

This Page

::ngspicetclbridge¶

Commands¶

getCircuit¶

getCircuitTitle¶

getPlotDate¶

getPlotName¶

getScaleInfo¶

new¶

readVecsAsync¶

run¶

SIM¶

SIM abort¶

SIM asyncvector¶

SIM circuit¶

SIM command¶

SIM destroy¶

SIM eventcounts¶

SIM initvectors¶

SIM inputpath¶

SIM isrunning¶

SIM messages¶

SIM plot¶

SIM vectors¶

SIM waitevent¶

`getCircuit`¶

`getCircuitTitle`¶

`getPlotDate`¶

`getPlotName`¶

`getScaleInfo`¶

`new`¶

`readVecsAsync`¶

`run`¶

`SIM`¶

`SIM abort`¶

`SIM asyncvector`¶

`SIM circuit`¶

`SIM command`¶

`SIM destroy`¶

`SIM eventcounts`¶

`SIM initvectors`¶

`SIM inputpath`¶

`SIM isrunning`¶

`SIM messages`¶

`SIM plot`¶

`SIM vectors`¶

`SIM waitevent`¶