XPP - VSCode Extension for XPPAUT Files

Write XPPAUT models (.ode, .inc) with highlighting, refactoring and checks that catch the mistakes XPP itself accepts silently.

• Diagnostics: missing done, unbalanced brackets, reserved or duplicate names, undefined and unused names, options XPP would silently ignore or misread, and operator-precedence traps such as 2*-3 or 2*3<4.
• Custom colours per variable, parameter or category, shared by every model in a folder.
• Descriptions on hover: document a name in a # comment, like a docstring, and hovering it shows the text.
• Rename (F2) and highlight-all-occurrences for variables, parameters and functions, across #included files; "Extract to Variable" from the context menu.
• Syntax highlighting, bracket matching, and commenting with Ctrl+/.
• A "Run ODE File" button that starts xppaut on the current file, with setup notes for Linux, macOS and Windows.

What's new in 0.4.1

• Operator-precedence checks: an error for a sign XPP rejects (2*-3) and for operators XPP does not have (!=, &&), with quick fixes; a warning where a comparison, & or | silently regroups arithmetic (2*3<4 is 2*(3<4)).
• Initial values checked the way XPP reads them: init y=2*3 starts y at 2, and y(0)=a at 0.
• @ option values checked the way XPP reads them: @ total=2*3 is 2.
• Descriptions on hover from # comments and from .xppsettings.json.
• .xppcolors.json becomes .xppsettings.json and xpp-ode.identifierColors becomes xpp-ode.variables; the old names still work for now (how to move).

Every release is listed in the changelog.

Diagnostics

The extension checks each .ode/.inc file as you type and reports:

• Errors, for what stops XPP loading the file or makes it ignore a line: missing done, unbalanced brackets, reserved words used as names, duplicate or conflicting names, solv lines with spaces around =, a sign where XPP allows none (2*-3, x^-2), operators XPP does not have (!=, &&, ||, !x), an if not written if(c)then(a)else(b), an init value that is not a plain number (init y=2*3 starts at 2), @ options XPP drops because they are not exactly name=value, and numeric @ values that are not plain numbers (@ total=2*3 is 2, not 6).
• Warnings, for what loads but probably does not mean what you wrote: text after done (shown dimmed; XPP stops reading there), undefined names, unused parameters, fixed variables and functions (shown faded), initial conditions for names that are not state variables, lines XPP silently skips, unknown @ option names, fixed variables named like a keyword (p=1), a comparison, & or | next to arithmetic (2*3<4, -1<0, a<b<c, a|b-c), a formula in y(0)= (y starts at 0), and a division by a literal 0 (XPP silently gives 4.5e14, not an error).
• Information, for legal surprises: 2^3^2 is (2^3)^2, -2^2 is -(2^2), and in if(c)then(a)else(b)+5 the +5 applies to the whole if.

Names defined in #included files count as defined. Inside an .inc file the undefined-name check is off, because the including .ode file may define them.

Operator precedence

XPP's expression parser groups some expressions differently from ordinary maths, and refuses others outright. This is long-standing XPPAUT behaviour that existing models rely on; the extension only makes it visible. Hover over ^, ** or a comparison for the rule, and use the quick fix (Ctrl+.) on a rejected sign.

It all follows from one priority table: comparisons bind tighter than all arithmetic, the opposite of nearly every other language, and unary minus binds more weakly than both ^ and the comparisons.

x'=-a*x^2^3        # XPP: (x^2)^3, i.e. x^6
x'=-a*(x^2)^3      # the same thing, written so it cannot be misread
x'=-a*x^(2^3)      # what ordinary notation would have meant: x^8

aux e=-x^2         # -(x^2): negative for every x  -- and normally what you meant
aux e=(-x)^2       # x^2: positive for every x

2*3<4              # XPP: 2*(3<4) = 2      -- not (2*3)<4 = 0
3-1<2              # XPP: 3-(1<2) = 2      -- not (3-1)<2 = 0
1+2<3+4            # XPP: 1+(2<3)+4 = 6    -- not (1+2)<(3+4) = 1
1/2<1              # XPP: 1/(2<1) -- a division by zero
(2*3)<4            # bracket what you want compared

f(t)=if(-t<0)then(a)else(b)     # XPP: if(-(t<0)) -- always -0, i.e. always the else branch
f(t)=if((-t)<0)then(a)else(b)   # what you meant

x'=2*-3            # rejected -- write 2*(-3)
x'=x^-2            # rejected -- write x^(-2)
x'=a+-b            # rejected -- write a+(-b)
f(t)=if(t<-1.3)... # rejected -- write if(t<(-1.3))
x'=+2*a            # rejected -- XPP has no unary "+" at all, not even as "(+2)"
x'=-3E-5*a         # fine: the sign starts the expression
par a=-3E-5        # fine: a declaration value is a plain number, not an expression

0<x<1              # XPP: (0<x)<1 -- true only when x is NOT above 0
(0<x)&(x<1)        # what you meant

1+1&1              # XPP: 1+(1&1) = 2   -- not (1+1)&1 = 1
a|b-c              # XPP: (a|b)-c       -- not a|(b-c)
a*b&c              # (a*b)&c, as expected: no warning
(a+b)&c            # bracket what you want combined

The error is always reported, like everything else XPP rejects. The advisory findings have one setting each:

// .vscode/settings.json -- "warning", "information", "hint" or "off"
"xpp-ode.precedence.power": "information",   // 2^3^2 and -2^2
"xpp-ode.precedence.comparison": "warning",  // 2*3<4, 1+2<3+4, -1<0, a<b<c
"xpp-ode.precedence.logical": "warning"      // 1+1&1, a|b-c

@ option values

An @ line is not made of expressions. XPP splits it on commas and spaces (@ dt=.05 meth=cvode total=100 sets all three), and every piece must be exactly name=value. Numeric values are read with atof(), which stops at the first character that cannot be part of a number and never reports an error:

Work the value out yourself, or put it in a par and use that in your equations. Options that take a name, a file or a keyword (meth=cvode, xp=x, output=out.dat) are left alone.

Initial values

Like @ values, init values are plain numbers read with atof(), and an initial condition y(0)= is a number too:

Work the value out yourself, or, for an array, use the x[1..n](https://github.com/MuhammadMoustafa/XPP-ODE-Extension/blob/HEAD/0)= form.

Custom colours for variables and parameters

Give any name in your models its own look, independent of the theme: the membrane voltage always red, every parameter bold green, builtins italic, one variable in a box. The colours follow the parser, so a parameter is coloured everywhere it is used, not only on its par line.

Put a .xppsettings.json in a folder, and it applies to every .ode/.inc file in that folder and its subfolders:

{
    "variables": {
        "@states":     "#ff7b72",
        "@parameters": { "color": "#7ee787", "fontWeight": "bold" },
        "@fixed":      { "color": "#d2a8ff" },
        "@builtins":   { "fontStyle": "italic" },
        "@options":    { "opacity": 0.6 },

        "v":    { "color": "#ffffff", "borderColor": "#ff7b72", "borderRadius": "3px" },
        "g_*":  { "textDecoration": "underline" },
        "iapp": { "light": { "color": "#a00000" }, "dark": { "color": "#ff8888" } }
    }
}

Reading it: state variables are salmon and parameters bold green everywhere they appear. v is white in a salmon box, because an exact name wins over its group. Every name starting with g_ (g_na, g_k, g_l) is underlined in the theme's colour, because a wildcard wins over its group and replaces it entirely. iapp is dark red on light themes and pale red on dark ones. Option names on @ lines are faded.

Hex colours show a swatch you can click for the colour picker. Completion (Ctrl+Space, or typing " or @) offers the groups, every name declared in the folder's models with its kind, and the style properties with their allowed values; misspelled properties and invalid values are underlined. Changes apply immediately.

Where to put the configuration

Both places take the same object: the setting holds it directly, the file under its "variables" key. Files override the setting, key by key (see Which rule applies).

Keys

Comments and text after done are never coloured.

Which rule applies

Every name gets at most one entry, chosen by these rules in order:

1. Exact name ("v"). For an array name, its members too ("u" covers u0...u9), unless a member has its own entry.
2. Wildcard ("g_*"). When several match, the one listed last wins.
3. Group ("@parameters"). A name belongs to one group only, so groups never compete.

The chosen entry replaces the others; properties are not combined. With "@parameters": { "fontWeight": "bold" } and "gna": "#ff0000", gna is red and not bold. Whatever the entry leaves out comes from the theme, not from a lower rule; to keep the bold, write it again: "gna": { "color": "#ff0000", "fontWeight": "bold" }.

When the same key appears in several places, the one closest to the file wins: the setting, then each .xppsettings.json from the workspace root down to the file's own folder, each overriding the one before for that key. The look and the description are overridden separately, so an entry that only adds a description keeps the colours given further up. The order above is applied afterwards, whatever the source: an exact name in your user settings still beats a wildcard in the folder's .xppsettings.json. Wildcards from all sources form one list, with the closer files' wildcards after (and so above) the setting's.

Inside a style, light/dark properties override the base properties for that kind of theme.

Values

A value is either a hex colour string or a style object.

"v": "#ff7b72"
"v": { "color": "#ff7b72", "fontWeight": "bold" }

Every VS Code theme declares itself as light, dark or high-contrast; light/dark entries are layered on top of the base properties for that kind of theme. Entries the extension cannot use (unknown group, bad colour, unknown top-level key, ...) are skipped and reported once as a warning; the rest still apply.

Moving from .xppcolors.json

.xppcolors.json and the xpp-ode.identifierColors setting are deprecated. They still work in this release, with a warning, but will be removed:

• move the content of a .xppcolors.json under "variables" in a .xppsettings.json in the same folder, then delete the old file. While both exist, .xppsettings.json wins key by key;
• rename the setting xpp-ode.identifierColors to xpp-ode.variables; its value is unchanged. While both are set, xpp-ode.variables wins key by key.

Descriptions on hover

Write what a name means in a # comment, like a docstring, and hovering the name anywhere in the code shows it with the name's kind:

par gna=120   # Maximal sodium conductance (mS/cm^2)

gna — parameter

Maximal sodium conductance (mS/cm^2) (line 1)

Names declared in #included files show their descriptions too.

Where to write a description

After the code, on the declaration line (or on any line of a line continued with \):

The comment is split into parts only when every part is name: text for a name on that line; otherwise it is plain text, so par gna=120 # units: mS/cm^2 describes gna as "units: mS/cm^2".

Above the declaration, one # name: text line per name, directly above it (no blank line in between). Handy for long lists; other comment lines, such as section headers, are ignored:

# ---- sodium current ----
# gna: maximal sodium conductance (mS/cm^2)
# ena: sodium reversal potential (mV)
par gna=120, ena=50

Keys are case-insensitive.

Arrays

An array such as x[1..10] is one name for a plain comment, and keys can pick its members:

# x: membrane voltage of cell j (mV)
# x[1..3]: excitatory cells
# x7: the pacemaker cell
x[1..10]'=-x[j]+i_syn[j]

A key for a member the array does not have (x11: or x[9..12]: above) is a warning.

Several descriptions for one name

A name can have descriptions at several levels, and the hover shows them all, most specific first:

1. its own: x7:, or the plain comment on its own line;
2. a selection: x[1..3]:, x[3,5]:;
3. inherited: x: seen from a member, or a comment shared by the names of a line.

x7 — state variable (array x[1..10])

the pacemaker cell (line 3)

membrane voltage of cell j (mV) (line 1) — from x

Two descriptions at the same level (1 or 2) are a mistake: x3 above described by both x[1..3]: and a later x[3,5]:, or gna described both above its line and after it. The later one wins (a comment after the code counts as later than the lines above), and the other is marked with a warning "Description of "x3" is overridden by line 12" that links to the winner. Its quick fix (Ctrl+.) removes the overridden description.

Descriptions in .xppsettings.json

For names in files you cannot edit, or shared by a folder of models, add a description to the entry in .xppsettings.json or xpp-ode.variables. An entry may hold only a description, which leaves the colours alone:

{
    "variables": {
        "gna":         { "color": "#7ee787", "description": "Maximal sodium conductance (mS/cm^2)" },
        "v":           { "description": "Membrane potential (mV)" },
        "g_*":         { "description": "A conductance" },
        "@parameters": { "description": "Units: mS/cm^2 unless stated" }
    }
}

These are shown after the comments, each with its key. Unlike colours, the levels do not hide each other: a name gets the description of its own entry, of every matching wildcard (last listed first) and of its group. An array member also gets its array's ("x" for x7). Keys with a selection ("x[1..3]") are not supported here.

Run ODE File

The "Run ODE File" button (editor title bar of any .ode file) saves the file, opens an integrated terminal in the file's folder, and runs:

<xpp-ode.runCommand> "<file name>.ode"

It runs in the file's folder because xppaut looks for #included files, table files and dll_lib libraries relative to the directory it is started from, and writes its output files there too.

The default command is xppaut, which works when xppaut is on your PATH. To change it: Settings (Ctrl + , / Cmd + ,) > search "XPP-ODE" > Run Command. Typical values:

Since only the file name is passed, wsl xppaut works without translating Windows paths: WSL starts in the same folder. The setting can be set per workspace (.vscode/settings.json), so a project can carry its own command.

{
    "xpp-ode.runCommand": "C:\\xppall\\xppaut.exe",
    "xpp-ode.xServer": "\"C:\\Program Files (x86)\\Xming\\Xming.exe\" :0 -multiwindow -clipboard"
}

Settings

Future work

• Handle active comments.
• .ani animation files: highlighting, and counting their references as uses of the .ode names.

Feedback and credits

Found a problem or want a feature? Open an issue or email me.

• This extension is a fork of Joe-McCann's XPP-ODE-Extension, which added the first highlighting of reserved functions, derivatives and comments, for any theme.
• Logo designed by Manar Moustafa.
• Thanks to Nianqi Deng for suggesting the Run ODE File button, and to Leqi (Sammy) Wang for suggesting custom colours.