11.1.10.7.3. Shared

This module provides a Python interface to the Ngspice shared library described in the ngspice as shared library or dynamic link library section of the Ngspice user manual.

In comparison to the subprocess interface, it provides an interaction with the simulator through commands and callbacks and it enables the usage of external voltage and current source in the circuit.

Warning

Since we don’t simulate a circuit in a fresh environment on demand, this approach is less safe than the subprocess approach. In case of bugs within Ngspice, we can expect some side effects like memory leaks or worse unexpected things.

This interface use the CFFI module to interface with the shared library. It is thus suited to run within the Pypy interpreter which implements JIT optimisation for Python.

It can also be used to experiment parallel simulation as explained in the Ngspice user manual. But it seems the Ngspice source code was designed with global variables which imply to use one copy of the shared library by worker as explained in the manual.

Warning

This interface can strongly slow down the simulation if the input or output callbacks is used. If the simulation time goes wrong for you then you need to implement the callbacks at a lower level than Python. You can have look to Pypy, Cython or a C extension module.

exception PySpice.Spice.NgSpice.Shared.NgSpiceCircuitError

Bases: NameError

exception PySpice.Spice.NgSpice.Shared.NgSpiceCommandError

Bases: NameError

class PySpice.Spice.NgSpice.Shared.NgSpiceShared(ngspice_id=0, send_data=False, verbose=False)

Bases: object

Set the send_data flag if you want to enable the output callback.

Set the ngspice_id to an integer value if you want to run NgSpice in parallel.

LIBRARY_PATH = 'libngspice{}.so'

MAX_COMMAND_LENGTH = 1023

NGSPICE_PATH = None

NUMBER_OF_EXEC_CALLS_TO_RELEASE_MEMORY = 10000

alter_device(device, **kwargs)

Alter device parameters

alter_model(model, **kwargs)

Alter model parameters

clear_output()

delete(debug_number)

Remove a trace or breakpoint

destroy(plot_name='all')

Release the memory holding the output data (the given plot or all plots) for the specified runs.

device_help(device)

Shows the user information about the devices available in the simulator.

exec_command(command, join_lines=True)

Execute a command and return the output.

get_isrc_data(current, time, node, ngspice_id)

Reimplement this callback in a subclass to provide external current source.

get_vsrc_data(voltage, time, node, ngspice_id)

Reimplement this callback in a subclass to provide external voltage source.

halt()

Halt the simulation in the background thread.

property has_cider

Return True if libngspice was compiled with CIDER support.

property has_xspice

Return True if libngspice was compiled with XSpice support.

property is_running

property last_plot

Return the last plot name.

property library_path

listing()

load_circuit(circuit)

Load the given circuit string.

classmethod new_instance(ngspice_id=0, send_data=False, verbose=False)

Create a NgSpiceShared instance

property ngspice_version

option(**kwargs)

Set any of the simulator variables.

plot(simulation, plot_name)

Return the corresponding plot.

property plot_names

Return the list of plot names.

quit()

remove_circuit()

Removes the current circuit from the list of circuits sourced into ngspice.

reset()

Throw out any intermediate data in the circuit (e.g, after a breakpoint or after one or more analyses have been done already), and re-parse the input file. The circuit can then be re-run from it’s initial state, overriding the affect of any set or alter commands.

ressource_usage(*ressources)

Print resource usage statistics. If any resources are given, just print the usage of that resource.

Most resources require that a circuit be loaded. Currently valid resources are:

• decklineno Number of lines in deck

• netloadtime Nelist loading time

• netparsetime Netlist parsing time

• elapsed The amount of time elapsed since the last rusage elapsed call.

• faults Number of page faults and context switches (BSD only).

• space Data space used.

• time CPU time used so far.

• temp Operating temperature.

• tnom Temperature at which device parameters were measured.

• equations Circuit Equations

• time Total Analysis Time

• totiter Total iterations

• accept Accepted time-points

• rejected Rejected time-points

• loadtime Time spent loading the circuit matrix and RHS.

• reordertime Matrix reordering time

• lutime L-U decomposition time

• solvetime Matrix solve time

• trantime Transient analysis time

• tranpoints Transient time-points

• traniter Transient iterations

• trancuriters Transient iterations for the last time point*

• tranlutime Transient L-U decomposition time

• transolvetime Transient matrix solve time

• everything All of the above.

resume(background=True)

Halt the simulation in the background thread.

run(background=False)

Run the simulation.

save(vector)

send_char(message, ngspice_id)

Reimplement this callback in a subclass to process logging messages from the simulator.

send_data(actual_vector_values, number_of_vectors, ngspice_id)

Reimplement this callback in a subclass to process the vector actual values.

send_init_data(data, ngspice_id)

Reimplement this callback in a subclass to process the initial data.

send_stat(message, ngspice_id)

Reimplement this callback in a subclass to process statistic messages from the simulator.

set(*args, **kwargs)

Set the value of variables

set_circuit(name)

Change the current circuit

classmethod setup_platform()

show(device)

showmod(device)

property simulation_type

source(file_path)

Read a ngspice input file

property spinit_not_found

status()

Display breakpoint information

property stderr

property stdout

step(number_of_steps=None)

Run a fixed number of time-points

stop(*args, **kwargs)

Set a breakpoint.

Examples:

ngspice.stop('v(out) > 1', 'v(1) > 10', after=10)

A when condition can use theses symbols: = <> > < >= <=.

trace(*args)

Trace nodes

type_to_unit(vector_type)

unset(*args)

Unset variables

where()

Identify troublesome node or device

class PySpice.Spice.NgSpice.Shared.Plot(simulation, plot_name)

Bases: dict

This class implements a plot in a simulation output.

Public Attributes:

plot_name

branches(to_float=False, abscissa=None)

elements(abscissa=None)

internal_parameters(to_float=False, abscissa=None)

nodes(to_float=False, abscissa=None)

to_analysis()

class PySpice.Spice.NgSpice.Shared.Vector(ngspice_shared, name, type_, data)

Bases: object

This class implements a vector in a simulation output.

Public Attributes:

data

name

property is_branch_current

property is_interval_parameter

property is_voltage_node

property simplified_name

to_waveform(abscissa=None, to_real=False, to_float=False)

Return a PySpice.Probe.WaveForm instance.

PySpice.Spice.NgSpice.Shared.ffi_string_utf8(_)