Skip to contents

Extract the netlist of a pic figure

Source: R/pic.R
spice_pic.Rd

Compiles an rpic figure drawn with the dune spice.pic prelude (resistor(), vsource(), npn(), ...; the figure opts in with spice = 1) and extracts its SPICE3 netlist: one card per labeled element (the label is the refdes), nodes from the wires, ground blocks and named places, and the figure's column-1 . lines as the deck's analysis and control cards. The result runs directly: spice_pic("fig.pic") |> spice_run().

Usage

spice_pic(src, snap = NULL, includes = NULL)

Arguments

src

The figure: the path to a .pic file, or the figure text 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 spice_run().

snap

NULL (the default, 0.001 inch) or the distance, in pic inches, under which two terminals are the same point. A positive finite number.

includes

For a figure given as text only: the files its netlist's .include cards read, as in spice_run() – a named list (or named character vector) mapping the path written on the card to the file's text. A figure given as a path reads its .include files from disk, relative to the figure's own directory (as dune pic --run does), at extraction time, and must leave includes as NULL.

Value

A spice_pic: a list with

  • netlist: the SPICE3 netlist, one string ending in .end;

  • diagnostics: a tibble with one row per extraction problem: severity ("error" or "warning"), kind ("dangling-pin", "floating-net", "missing-value", "duplicate-refdes", "unknown-element", "missing-pin", "unlabeled-element", "node-name-conflict", "prelude"), message, and the span in the figure: file (NA for the figure itself, "spice.pic" for the prelude), 1-based line, column and an exclusive end_column;

  • map: the overlay map from netlist names back to the drawing of spice_pic_svg() (the SVG group <g id="sN"> is shape N):

    • elements: a tibble, one row per card in card order: refdes; shape_start/shape_end, the half-open range of the element's shape numbers, and ids, the same as "sN..sM"; principal, the parameter spice_alter(s, refdes, value) changes (NA for M, S, W, X, T, O, K); value, the value argument verbatim as written in the figure, and its range value_line, value_col, value_end_line, value_end_col (1-based, end exclusive, columns in characters) – all NA when there is no range an editor can trust (no value argument, a user wrapper macro, a K);

    • pins: a tibble, one row per terminal in card order: refdes, pin (the prelude's pin name, P, N, C, B, E, ...), net (the node name on the card) and the point x, y in pic inches;

    • params: a tibble of the alterable parameters spelled inside each value (refdes, name as spice_alter() names it, text, line, col, end_line, end_col);

    • nets: a tibble of the named nets (name, and shapes, a list of the wire, dot and ground shape numbers of each);

    • canvas: the SVG frame, list(w, h, origin, rescale): the page size in inches (the viewBox is 0 0 w*96 h*96) and the pic origin; the point (x, y) is at SVG user units ((x + origin[1]) * 96, (h - (y + origin[2])) * 96);

  • includes: the .include files the netlist reads, as a named character vector (path as written on the card = text);

  • source: the figure text;

  • path: the figure's path, or NA for figure text.

Details

Extraction problems in a figure that compiles – a dangling pin, a floating net, an element without a value – are not errors here: the netlist is still emitted and the problems are listed in diagnostics. Running a figure whose diagnostics include an error (with spice_run(), spice_session(), spice_sweep() or spice_pss()) is refused with a spice_error_pic condition, as dune pic --run refuses it.

Errors

A figure that yields no netlist is signalled with cli::cli_abort() as a condition of class spice_error_pic (and spice_error): rpic rejected it (a syntax error, an unknown label, ...) or it is not marked spice = 1. The message carries the figure's line:col; the condition's fields line and column hold them (NA when there is no position), and diagnostics holds the one diagnostic, of kind "compile" or "not-marked". An unreadable figure file is a spice_error_io, a bad snap a spice_error_input.

Mirror of the Python package

This is spice.pic.extract() in Python; spice_run(spice_pic(...)) is spice.simulate(spice.pic.extract(...)).

See also

spice_pic_svg() to draw the figure, spice_run() to simulate it.

Examples

fig <- ".PS
spice = 1
In: (0,1); Out: (2,1)
V1: vsource(In, (0,0), DC 5)
R1: resistor(In, Out, 1k)
C1: capacitor(Out, (2,0), 1u)
line from C1.N to V1.N; ground(V1.N)
.tran 10u 5m
.PE"
p <- spice_pic(fig)
p
#> <spice_pic> figure text: 3 elements, 3 named nets, 0 errors, 0 warnings
#>   * netlist extracted by dune-pic
#>   V1 In 0 DC 5
#>   R1 In Out 1k
#>   C1 Out 0 1u
#>   .tran 10u 5m
#>   .end
cat(p$netlist)
#> * netlist extracted by dune-pic
#> V1 In 0 DC 5
#> R1 In Out 1k
#> C1 Out 0 1u
#> .tran 10u 5m
#> .end
p$map$pins
#> # A tibble: 6 × 5
#>   refdes pin   net       x     y
#>   <chr>  <chr> <chr> <dbl> <dbl>
#> 1 V1     P     In        0     1
#> 2 V1     N     0         0     0
#> 3 R1     P     In        0     1
#> 4 R1     N     Out       2     1
#> 5 C1     P     Out       2     1
#> 6 C1     N     0         2     0

# The extraction runs as a deck
res <- spice_run(p)
tail(spice_plots(res)[[1]]$values[["v(out)"]], 1)
#> [1] 5