Keep a circuit alive to alter and re-run it

spice_session() parses and builds a deck once; spice_alter() then changes element values in place and spice_rerun() runs every analysis card again without re-parsing – for interactive exploration and for fitting loops that evaluate the same circuit many times.

Usage

spice_session(
  deck,
  includes = NULL,
  options = NULL,
  warm_start = FALSE,
  tmax_divisor = NULL
)

Arguments

deck: Either the path to a deck file, or the netlist itself as a character vector: a single string containing newlines, or one element per line. A length-one string without a newline is taken as a path. As in SPICE3, the first line of a netlist is its title. A spice_pic (the extraction of a pic figure, spice_pic()) runs as its netlist, with the .include files that came with the figure; one whose diagnostics include an error is refused (spice_error_pic).
includes: For a netlist given as text only: the files its .include cards may read, as a named list (or named character vector) mapping the path exactly as written on the card to the file's text. Nothing is read from disk for a text deck. A deck given as a path resolves .include on the file system, relative to the deck's own directory, and must leave includes as NULL; so must a spice_pic.
options: NULL or a named list of simulator options that override the deck's .options card, with the card's names and units (temperatures temp/tnom in degrees Celsius): reltol, abstol, vntol, gmin, itl1, itl2, itl4, gminsteps, srcsteps, temp, tnom, pivtol, pivrel, noopiter, trtol, chgtol, method ("trap", "gear" or "trbdf2"; unset, a .tran integrates with "trbdf2"), compat ("dune" or "spice3", the 'SPICE3f5' defaults: a trapezoidal .tran, switches flipping on the time grid, ltrabkrate 0), ltrabkrate, ltrafit, maxord, nopage, defl, defw, defad, defas, seed (the transient-noise seed, a whole number >= 1; no "random"), notrnoise, devnoise, devnt (the device-noise grid step, seconds, > 0), keepopinfo and trytocompact. The flags noopiter, nopage, ltrafit, notrnoise, devnoise and keepopinfo take TRUE/FALSE (FALSE clears a flag the deck's card set). Unlike a .options card, which only warns, an unknown name or a value of the wrong type is an error.
warm_start: Continue each operating point from the previous run's (see Details).
tmax_divisor: NULL (the default) or a finite number >= 1 that divides the maximum step of every .tran card – its TMAX argument, else the default min(TSTEP, (TSTOP - TSTART) / 50). The run is, bit for bit, that of the deck with the card's TMAX edited to TMAX / tmax_divisor; with options = list(trtol = 1) it gives the "fine steps" view of a waveform. It is an argument rather than an options name because TMAX is a parameter of the analysis card, not an engine option.

Value

A spice_session.

Details

With warm_start = FALSE (the default), spice_rerun() returns exactly what spice_run() returns for the altered deck: the same plots, value for value, and the same notes and diagnostics. With warm_start = TRUE each operating point (.op, and the bias point of .ac, .noise, .tf, .sens, .pz, .disto) continues from the previous one: faster for nonlinear circuits, and equal to a fresh run to the Newton tolerances (reltol, vntol, abstol) rather than bit for bit. Transient operating points and decks with .nodeset are never warm-started.

A session is a reference object: spice_alter(), spice_set_temp() and spice_set_tmax_divisor() modify it in place (every copy of it sees the change) and return it invisibly, so calls can be piped.

Mirror of the Python package

This is spice.Session in Python: spice_alter() is Session.alter(), spice_rerun() is Session.run(), spice_set_temp() sets Session.temp, spice_set_tmax_divisor() sets Session.tmax_divisor.

Examples

s <- spice_session("divider
v1 1 0 dc 10
r1 1 2 1k
r2 2 0 1k
.op
.end")
spice_plots(spice_rerun(s))[[1]]$values[["v(2)"]]
#> [1] 5
s |> spice_alter("r2", 3e3)
spice_plots(spice_rerun(s))[[1]]$values[["v(2)"]]
#> [1] 7.5