Apsi
Sign inCreate account
Browse the docs · Apsi 2.4.4

Docs 2.4.4 · 4 min read

Debugging

Apsi has a real debugger: breakpoints, stepping, the call stack, variables and tensors — in VS Code and the other VS Code-family editors (F5) or in the terminal. It works on the compiled engine: Apsi lines are mapped back from the generated code, so breakpoints, step and the stack follow your source, also through imported .apsi files and converted Python programs.

In VS Code

Install the Apsi extension (apsi editors install vscode), open a .apsi file, click left of a line number to set a breakpoint and press F5. The extension starts apsi dap (the Debug Adapter Protocol server) for you.

  • Breakpoints: plain, conditional (x > 10), hit counts (5, >= 100), and log points (loss = {loss}).
  • Stop on uncaught errors (on by default): the program pauses where the error happened, with all variables.
  • Variables: locals and globals of each frame; lists, dicts, records and objects expand; values can be changed while paused.
  • Tensors show shape, dtype, min/max/mean and the first values instead of a wall of numbers.
  • Watch / Debug Console: any Apsi expression in the paused frame.
  • Program output appears in the Debug Console.

Without a launch.json, F5 debugs the open file. With one:

{ "type": "apsi", "request": "launch", "name": "Run app.apsi", "program": "${file}",
  "args": ["--epochs", "3"], "stopOnEntry": false }

In the terminal

apsi debug app.apsi                      # stops at the first line
apsi debug app.apsi -b 42 -b "57 if loss > 1" -- --epochs 3
command
c continue
n next line (step over)
s step into a call
o step out of the function
b LINE, b FILE:LINE, b LINE if COND add a breakpoint
p EXPR print an expression (tensors summarised)
l local variables
bt call stack
q quit

Without a debugger

  • print(x) of a tensor gives its shape, dtype and values.
  • Errors name the file, line and column and show the line with a caret, plus the chain of Apsi function calls.
  • apsi check app.apsi finds type, unit and name errors without running anything.

Breakpoints in detail

Kind In VS Code In the terminal Stops when
Line click left of the line number b 42 or b model.apsi:42 the line is reached
Conditional right-click → Add Conditional Breakpoint → expression b 42 if loss > 1 the expression is true in that frame
Hit count right-click → Hit Count → 5 or >= 5, > 5, == 5, % 10 — from the 5th hit on, after the 5th, only the 5th, every 10th
Log point right-click → Add Logpoint → epoch {epoch}: loss = {loss} — never: the message is printed and the program continues
Uncaught error Breakpoints panel → Uncaught errors (on by default) always on an error is about to end the program

Conditions and log-point expressions are Apsi expressions evaluated in the paused frame: names, attributes, indexing, arithmetic, comparisons and calls. A condition that cannot be evaluated (a typo, a name that does not exist yet) stops at the breakpoint, so you see the problem instead of silently missing the stop.

What the variables view shows

  • Locals and globals of every frame in the call stack. Module-level globals are limited to the names your program declared, not everything imported.
  • Tensors and arrays: tensor (64, 128) float32 min -0.91 max 1.2 mean 0.003 [0.12, -0.04, …]. Expand them to see rows.
  • Quantities with units show as Apsi prints them (9.81 m/s^2).
  • Changing a value: double-click it in the VS Code variables view and type any Apsi expression; the program continues with the new value.

Debugging servers, tests and converted Python

  • Web servers: set a breakpoint inside a route and send a request; the request waits while you are paused.
  • Tests: apsi debug tests/test_model.apsi runs the test file under the debugger; a failing assert stops with its values visible when Uncaught errors is on.
  • Converted Python: apsi convert script.py then apsi debug script.apsi. Breakpoints and the stack refer to the Apsi lines, which match the Python structure line for line.
  • Permissions are the same as for apsi run: pass --allow-read, --allow-net and so on after the file.

Cost

The debugger traces only frames of Apsi code (not the standard library or NumPy), and only while it is attached. apsi run has no tracing at all, so there is no reason to remove breakpoints or debug code before deploying.

Found a mistake? Report it · Markdown source