I am a process protocol for communicating with an instance of Ngspice running in server mode via STDIO pipes.

The same instance of the application remains running for repeated simulations. That just seems like a more efficient way to do things than spawning new batch-mode instances, though it was quite a pain to set up.

Instance Variable	running	`None` before the simulator has started, `True` after it has, `False` if it's stopped, and `0` if its process has terminated
Method	__init__	Undocumented
Method	__repr__	Undocumented
Method	shutdown	Shuts me down if I'm running, immediately.
Method	cmd	Assembles a single-line command from the supplied args and *kw and sends it to the simulator via STDIN.
Method	registerWatcher	Registers callables to be called whenever Ngspice sends a line on STDOUT or STDERR.
Method	unregisterWatchers	Sets one or more callables to be unregistered as watchers.
Method	registerConsumer	Constructs and registers an instance of `ProgressProducer` that serves the supplied consumer and returns it.
Method	cancel	Tells any pending call to `response` to stop waiting and sends a series of CTRL+C chars to Ngspice to interrupt what it's doing.
Method	response	Returns a `Deferred` that fires with the simulator's next N response lines.
Method	connectionMade	Upon connection to the Ngspice process via stdio, tells the `NgspiceRunner` I serve to proceed with its startup, running the setup method of its `Commander`.
Method	linerator	Generates all non-blank lines in the supplied text, stripped of leading and trailing whitespace if stripLine is set.
Method	outReceived	Processes some data from the simulator, which comes in chunk-wise even though it's just STDIO.
Method	errReceived	Deals with stderr from the simulator.
Method	processExited	When Ngspice quits, set the 'exited' event.
Method	processEnded	Calls `processExited` with the reason Ngspice quit.
Method	_setup	This gets called as soon as the 'ready' event occurs. It should be the first method called once the `Commander` is ready.

running =

None before the simulator has started, True after it has, False if it's stopped, and 0 if its process has terminated

def __init__(self, cfg, waiter):

Undocumented

def _setup(self):

This gets called as soon as the 'ready' event occurs. It should be the first method called once the Commander is ready.

Sets the 'running' event of the shared waiter and my running flag.

def __repr__(self):

Undocumented

def shutdown(self):

Shuts me down if I'm running, immediately.

Neutralizes my DeferredQueue to stop the loop in response, and kills the Ngspice executable.

Don't call this unless you're sure that there are no pending calls to response.

def cmd(self, *args, **kw):

Assembles a single-line command from the supplied *args and **kw and sends it to the simulator via STDIN.

Returns the line as sent, except with the trailing newline stripped.

def registerWatcher(self, out=None, err=None):

Registers callables to be called whenever Ngspice sends a line on STDOUT or STDERR.

Calling with just one arg will register a STDOUT processor, since Python maps that to the first-defined keyword.

Parameters	out	A callable for processing a line of STDOUT.
	err	A callable for processing a line of STDERR.

def unregisterWatchers(self, *args):

Sets one or more callables to be unregistered as watchers.

It doesn't matter whether a callable is registered for STDOUT, STDERR, or not registered at all. If it's registered when you call this, it won't be any more.

def registerConsumer(self, consumer):

Constructs and registers an instance of ProgressProducer that serves the supplied consumer and returns it.

You must call its stopProducing method to get me to discard it.

def cancel(self):

Tells any pending call to response to stop waiting and sends a series of CTRL+C chars to Ngspice to interrupt what it's doing.

Returns a Deferred that fires when enough lines of STDERR have been received to indicate that Ngspice complied.

def response(self, N=None, func=None):

Returns a Deferred that fires with the simulator's next N response lines.

Works by requesting tokens from a DeferredQueue. Each token is an integer number of lines to read from my lines list, a None object indicating that there was an error, or a ShuttingDownToken indicating that I should quit waiting for a response.

If N is not specified, I send an echo command to Ngspice with a unique string. I wait for that same string to come back on STDIO, and then know that all the response lines I actually want have been received.

Parameters func Called with each line as it arrives. If the callable returns a value (not None, it will be appended to the result list instead of the line itself.

def connectionMade(self):

Upon connection to the Ngspice process via stdio, tells the NgspiceRunner I serve to proceed with its startup, running the setup method of its Commander.

def linerator(self, text, stripLine=False):

Generates all non-blank lines in the supplied text, stripped of leading and trailing whitespace if stripLine is set.

def outReceived(self, data):

Processes some data from the simulator, which comes in chunk-wise even though it's just STDIO.

When enough chunkage for one or more lines has been accumulated, turns it into a list of lines, appends to the existing line buffer, and puts into the deferred queue the (integer) number of lines added.

def errReceived(self, data):

Deals with stderr from the simulator.

Sometimes it spits out blank lines on stderr for no good reason.

def processExited(self, reason):

When Ngspice quits, set the 'exited' event.

def processEnded(self, reason):

Calls processExited with the reason Ngspice quit.

API Documentation for pingspice, generated by pydoctor at 2021-09-18 08:41:11.

pingspice.ngspice.stdio.NgspiceProtocol(protocol.ProcessProtocol) class documentation

`pingspice.ngspice.stdio.NgspiceProtocol(protocol.ProcessProtocol)` class documentation