Class Reference ngspice

In-process ngspice session loaded from pluginNgspice. More...

Member

Detailed Description

In-process ngspice session loaded from pluginNgspice. The simulator is linked into that Qt plugin (same LayoutEditor release). There is no extra libngspice file and no PATH fallback to a system ngspice binary.

ngspice is a SPICE circuit simulator: you give it a netlist (text that lists voltage sources, resistors, capacitors, transistors, and analysis commands such as .tran), it computes voltages and currents versus time or frequency, and you plot those results.

The class ngspice is part of LayoutScript: it works in C++ macros and in Python (from LayoutScript import *). It is not an #include <…> binding. Create an object, then call methods with the object.method() syntax:

ngspice sim;
if (!sim.available()) { /* plugin missing */ }

All ngspice objects share one simulator instance. A second ngspice object does not start a second engine. Do not spawn an external ngspice process.

Menus Utilities → NGSpice in the Schematic Editor and the Text Editor use the same plugin. GUI usage is described under NGspice. Waveforms are plotData vectors; schematicDisplay::setProbeMode enables click-to-plot on nets.

Typical sequence:

1. ngspice sim;
2. sim.available() — is the plugin there?
3. sim.loadCircuit(net) or sim.loadFile(path)
4. sim.run()
5. plotData pd = sim.results();
6. On failure, read sim.error() and sim.log().

   Example — netlist string (C++ macro)

int main(){
    ngspice sim;
    if (!sim.available()){
        debug(sim.error());
        debug.show();
        return 1;
    }

    string net = "* rc low-pass\n";
    net = net + "V1 in 0 DC 0 PULSE(0 1 0 1n 1n 10n 20n)\n";
    net = net + "R1 in out 1k\n";
    net = net + "C1 out 0 1n\n";
    net = net + ".tran 0.1n 100n\n";
    net = net + ".end\n";

    if (!sim.loadCircuit(net)){
        debug(sim.error());
        debug(sim.log());
        debug.show();
        return 1;
    }
    if (!sim.run()){
        debug(sim.error());
        debug.show();
        return 1;
    }

    plotData pd = sim.results();
    schematic->drawing->setProbeMode(pd);
}

Example — schematic netlist (C++ macro)

Generate a spice netlist from the open schematic, simulate, then enter probe mode:

int main(){
    ngspice sim;
    if (!sim.available()) return 1;

    string net = schematic->drawing->generateNetList("ngspice");
    if (!sim.loadCircuit(net)){
        debug(sim.error());
        debug.show();
        return 1;
    }
    if (!sim.run()){
        debug(sim.error());
        debug.show();
        return 1;
    }

    plotData pd = sim.results();
    schematic->drawing->setProbeMode(pd);
}

Example — Python (in-process)

from LayoutScript import *

sim = ngspice()
if not sim.available():
    print(sim.error())
else:
    net = """* rc low-pass
V1 in 0 DC 0 PULSE(0 1 0 1n 1n 10n 20n)
R1 in out 1k
C1 out 0 1n
.tran 0.1n 100n
.end
"""
    if sim.loadCircuit(net) and sim.run():
        pd = sim.results()
        print("vectors:", sim.vectors())
        sch = project.currentSchematic()
        if sch is not None:
            sch.drawing.setProbeMode(pd)
    else:
        print(sim.error())
        print(sim.log())

Example — load a file

int main(){
    ngspice sim;
    if (!sim.loadFile("/tmp/circuit.cir")){
        debug(sim.error());
        debug.show();
        return 1;
    }
    sim.run();
    plotData pd = sim.results();
    int n = pd.items();
    debug("plot rows: ");
    debug(n);
    debug.show();
}

Member Function Documentation

ngspice::ngspice()

Creates a session object. The underlying simulator is the shared plugin. Nothing is simulated yet.

Parameters: none.

Returns: a ngspice object. In a macro you write ngspice sim; (declaration). In Python: sim = ngspice().

bool ngspice::available()

Checks that pluginNgspice could be loaded from the editor plugin path.

Parameters: none.

Returns: true if the simulator is ready, false if the plugin is missing or failed to load. On false, read error() for a message.

Call this before loadCircuit. If it is false, later calls also fail.

string ngspice::error()

Last error from load or run (empty if the last successful path cleared it, or a human-readable reason if something failed).

Parameters: none.

Returns: string — for example a parse error, a missing file, or “plugin not found”. Always print this together with log() when a call returns false.

bool ngspice::loadCircuit(string netlist)

Parses a complete SPICE netlist from a string. Lines must be separated by newline (\n). Leading and trailing spaces on each line are trimmed.

A minimal transient netlist looks like:

* title
V1 in 0 DC 1
R1 in out 1k
C1 out 0 1n
.tran 1n 1u
.end

Parameters:

• netlist (string) — the full deck, including .end. You can build it with + in C++, or take schematic->drawing->generateNetList("ngspice") from the open schematic.

Returns: true if ngspice accepted the circuit, false on parse error or if the plugin is unavailable. On false, use error() / log(). Unknown devices (for example unsupported XSPICE a-devices) are errors, not silent success.

bool ngspice::loadFile(string path)

Reads a .cir (or other SPICE) file from disk and passes its contents to loadCircuit.

Parameters:

• path (string) — file name, for example "/tmp/circuit.cir". Relative paths are relative to the process working directory.

Returns: true on success. false if the file cannot be opened or the netlist does not parse. Opening failure sets error() to a “cannot open …” message.

bool ngspice::command(string cmd)

Sends one ngspice control command (Nutmeg / .control language), for example setplot or destroy all. Do not send graphics commands (plot, GUI windows). LayoutEditor displays waveforms via results() and plotData.

Parameters:

• cmd (string) — a single command without a trailing newline requirement.

Returns: true if the command was accepted, false on error (see error()).

bool ngspice::run()

bool ngspice::run(int timeoutMs)

Runs the circuit that was loaded (bg_run) and waits until the simulation finishes or the timeout expires. The call stays on the caller thread and keeps the GUI responsive (processEvents).

Parameters:

• none — waits up to 300000 ms (5 minutes).
• or timeoutMs (int) — maximum wait in milliseconds. Example: sim.run(60000) waits at most one minute.

Returns: true if the run completed successfully, false on timeout, simulator error, or missing plugin. Check error() and log() on false.

You must loadCircuit or loadFile first. run without a circuit fails.

bool ngspice::stop()

Asks a running background simulation to halt.

Parameters: none.

Returns: true if the stop request was issued (plugin present). It does not wait until ngspice has fully stopped; use isRunning() if you need to poll.

bool ngspice::isRunning()

Whether a background run is still in progress.

Parameters: none.

Returns: true while a simulation started by run has not finished (or has not been stopped). false if idle or if the plugin is missing.

string ngspice::log()

Simulator stdout/stderr captured by the plugin, plus the last error() text if that is set.

Parameters: none.

Returns: string — may be several lines. Useful after a failed loadCircuit (syntax) or run (convergence, timestep).

stringList ngspice::plots()

Names of plots currently held by ngspice (for example tran1, ac1). A plot here is a named set of vectors from one analysis, not a GUI window.

Parameters: none.

Returns: stringList of plot names. Empty if nothing has been simulated or the plugin is missing.

stringList ngspice::vectors()

stringList ngspice::vectors(string plot)

Names of the vectors (waveforms) in a plot: typically time or frequency, node voltages such as v(out), currents such as i(v1).

Parameters:

• none — use the current plot.
• or plot (string) — name from plots(). Empty string means the current plot.

Returns: stringList of vector names. Empty if the plot does not exist.

plotData ngspice::results()

Copies the current plot into a plotData object so LayoutEditor can display or probe it.

Complex vectors (AC analysis) are stored as magnitude plus a second row named name_phase in degrees. Scale vectors (time, frequency) are placed first so they can be used as the X axis. sourceType is ngspice.

Parameters: none.

Returns: plotData. On plugin failure the object has an error set (pd may still be empty). Use pd.items() for the number of rows. Pass the object to schematic->drawing->setProbeMode(pd) to click nets in the schematic.