[GP-02] Support the power operator ^ in the expression language

[aoustry]

Process ID

Process: GP-02

Closes #287.

Description

Adds the binary power operator ^ to the GEMS expression language. It was previously not even a lexer token, so a library YAML using ^ failed to parse.

Grammar (grammar/Expr.g4) — ^ is right-associative and binds tighter than unary minus and than * /, following standard mathematical notation, so -2^2 parses as -(2^2) and 2^3^2 as 2^(3^2).

Time shifts — ^ means inside x[...] exactly what it means in a general expression; what differs is the machinery needed to get there. Time shifts are parsed by a separate sub-grammar (shift / shift_expr / right_expr), which exists because a shift must begin with an explicit + or - and that sign has to bind loosely (t - d + 1 is (t - d) + 1, not t - (d + 1)). Unlike expr, that sub-grammar is a hand-written cascade of rules, so precedence is not implicit in the order of the alternatives — it is encoded in which rule each operand recurses into. Adding ^ to expr therefore gives it nothing inside a shift: the same precedence has to be restated there, as a new tier shift_operand / shift_primary sitting above right_expr. Two operands go through it:

• the leading sign's operand is widened from a bare atom to shift_operand, so the exponent binds tighter than the sign and x[t-2^2] shifts by -4 rather than +4 — matching -2^2 = -(2^2) in expr. It cannot simply be right_expr, which would also swallow * / / and make t - 2*3 ambiguous;
• the right-hand side of ^ is shift_operand rather than right_expr, which is the muldiv tier and would be entered at precedence 0 and greedily swallow * / / — so x[t-2^2*3] shifts by -12, not -64, again matching expr.

As a consequence signedAtom and signedExpression merge into a single signedOperand alternative. The one deliberate divergence from expr is that the exponent is unsigned here, so a signed exponent is rejected inside a time shift (x[t+2^-1] is a parse error), a fractional shift being meaningless, while 2^-1 remains available in a general expression. ** is not accepted as an alias anywhere.

Degree — ^ adds no rule of its own; where it may be used follows from the existing linearity requirement, as for floor / ceil / abs / round / min / max. ExpressionDegreeVisitor gains the corresponding case, and the linear builder handles the literal exponents 0 and 1, which the degree check lets through.

AST — new PowerNode(BinaryOperatorNode), plus __pow__ / __rpow__ on ExpressionNode and __pow__ on the SupportsOperations protocol, so ExpressionVisitorOperations supplies a default power and only the visitors that do not derive from it need an explicit implementation.

Also fixes the stale output path in grammar/generate-parser.sh and grammar/README.md, which still pointed at the pre-rename src/gems/....

Note on the diff size

Most of the diff is regenerated ANTLR output, not hand-written code:

file	changed lines	of which bare integers
ExprLexer.py	525	512 (97%)
ExprParser.py	1584	952 (60%)

Those integers are the serialized ATN, ANTLR's state machine, emitted as a flat list that black puts one entry per line. Two things inflate it further: ANTLR numbers implicit literal tokens in the order they appear in the grammar, and the power alternative has to sit above negation for the precedence to be right — so '^' lands at index 2 and shifts every later token by one, renumbering the whole automaton and both .tokens files.

None of it is formatting churn: the previously committed files already pass black --check, so the entire diff comes from regeneration. The reviewable unit is grammar/Expr.g4; the rest is reproducible by running grammar/generate-parser.sh.

Impact Analysis

Affected modules: expression/ (grammar, AST, parsing, all visitors), model/ (resolve_library, port), simulation/ (linearize, vectorized_builder).

No change to solver output for existing studies. This is purely additive: ^ was previously a parse error, so no GEMS file in circulation can contain it, and the precedence of the existing operators is unchanged — power is inserted above muldiv and negation, which does not reorder any + - * / parse. The full suite passes unchanged, including all e2e reference studies.

The only behavioural change is that expressions previously rejected at parse time are now accepted, and ^ applied to a variable outside extra-outputs is rejected with the existing non-linearity error rather than a parse error.

Tests

51 new tests (585 → 636 passing): parsing and precedence, print/re-parse round-trip, degree, printer / equality / copy, library-level accept and reject, numeric evaluation, the linear builder (parameter powers match the manually expanded expression), extra-outputs, and a new YAML-driven e2e test asserting hand-computed values.

Checklist

• Unit tests pass (pytest) — 636 passed, 6 skipped, 2 xfailed
• Type checking passes (mypy) — no issues in 66 source files
• Formatting passes (black, isort)
• pyproject.toml version bumped if applicable — not bumped: Unreleased already carries two features with version = "0.1.3" untouched, so versioning looks like a release-time step here. Say if it should be bumped in this PR.
• AGENTS.md reviewed for impact and updated if needed — reviewed, no change needed