Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension


Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
76 changes: 76 additions & 0 deletions .github/workflows/tests.yml
Original file line number Diff line number Diff line change
@@ -0,0 +1,76 @@
# SPDX-License-Identifier: Apache-2.0
# Copyright 2026 Evan Gress
#
# Lint, format check, type check and the full pytest suite, with GNU Octave
# installed from the Ubuntu LTS apt package (docs/design.md section 12), so
# every rule case is executed in both languages.

name: tests

on:
push:
branches: [main]
pull_request:
branches: [main]

permissions:
contents: read

jobs:
checks:
name: ruff + mypy
runs-on: ubuntu-24.04
steps:
- uses: actions/checkout@v4

- name: Install uv
uses: astral-sh/setup-uv@v6
with:
enable-cache: true

- name: Sync dependencies
run: uv sync --all-groups

- name: Lint (ruff)
run: uv run ruff check .

- name: Check formatting (ruff format)
run: uv run ruff format --check .

- name: Type check (mypy)
run: uv run mypy dualect

- name: Type check the rule translators (mypy)
run: uv run python tools/mypy_rules.py

pytest:
name: pytest (Python ${{ matrix.python-version }}, Octave from apt)
runs-on: ubuntu-24.04
strategy:
fail-fast: false
matrix:
python-version: ["3.11", "3.13"]
env:
# Fail, rather than skip, any test that needs Octave: in CI a missing
# Octave is a broken setup, not a reason to pass.
DUALECT_REQUIRE_OCTAVE: "1"
steps:
- uses: actions/checkout@v4

- name: Install GNU Octave (Ubuntu LTS package)
run: |
sudo apt-get update
sudo apt-get install -y --no-install-recommends octave
octave --version | head -n 1

- name: Install uv
uses: astral-sh/setup-uv@v6
with:
enable-cache: true
python-version: ${{ matrix.python-version }}

- name: Sync dependencies
run: uv sync --all-groups

- name: Run pytest
run: uv run pytest
24 changes: 20 additions & 4 deletions CLAUDE.md
Original file line number Diff line number Diff line change
Expand Up @@ -14,16 +14,28 @@ architecture, the rule format and the milestones.

## Current state

Design only. No package code exists yet. Next step is milestone 1 in
docs/design.md (skeleton, rule schema, verify harness, Octave in CI).
Milestones 1-6 of docs/design.md are done. Both directions work end to end:
`.m` -> Python (dualect/lower.py, infer.py, emit.py; 30 of 35 rules mechanical)
and Python -> `.m` (dualect/pyinfer.py, lift.py, memit.py; 29 mechanical), one
rule folder per construct serving both (`from_python:` in rule.yaml, `lift()` in
translate.py, status per direction). `dualect rules check` enforces that every
status is earned; `dualect mcp` serves scan/get_rule/translate/verify;
`llms.txt` is generated (`dualect llms-txt -o llms.txt`) and must stay current.
Adversarial probes live in tests/test_adversarial.py and tests/test_reverse.py.
Next: more rules (the guided ones, `cumsum`, `filter`, printing), cell arrays
and structs.

## Core ideas to preserve

- **One rule per construct or built-in**, in `rules/<category>/<rule-id>/`
(`rule.yaml`, optional `translate.py`, `cases/*.m` + `*.py`). Keep rules small
and independent so a language change touches one folder.
- **Status lifecycle**: `unsupported` → `guided` → `mechanical`. Only promote a
rule to `mechanical` when its `translate.py` passes all its cases.
rule to `mechanical` when its `translate.py` passes all its cases: output equal
to the hand-written `.py` (comments ignored) *and* verified against Octave.
A translator that cannot translate a form correctly raises `Decline` (the
statement becomes a reported hole); a shape guess must go through
`ctx.assume` so the output says so.
- **A behavior change in MATLAB/Octave is a new variant rule** with
`since`/`until`, not an edit that breaks the old behavior.
- **Never translate silently wrong.** Unknown constructs raise a named
Expand All @@ -34,15 +46,19 @@ docs/design.md (skeleton, rule schema, verify harness, Octave in CI).
- `rule.yaml` `why`/`pitfalls` text is written for both a human learner and an
LLM; keep it precise and short.

## Tooling (planned; match first-principles-code conventions)
## Tooling (matches first-principles-code conventions)

Python 3.11+ managed with **uv**; ruff, mypy, pytest.

```bash
uv sync --all-groups # install
uv run pytest # tests (Octave-dependent tests skip if Octave is absent)
uv run pytest -m 'not octave' # only the tests that need no Octave
uv run ruff check . && uv run ruff format .
uv run mypy dualect
uv run python tools/mypy_rules.py # mypy over rules/**/translate.py
uv run dualect rules check # every rule earns its status, both directions
uv run dualect llms-txt -o llms.txt # after adding or changing a rule
```

Octave is needed for execution tests (`brew install octave` on macOS).
Expand Down
82 changes: 77 additions & 5 deletions README.md
Original file line number Diff line number Diff line change
Expand Up @@ -3,7 +3,9 @@
Translate numeric code between Octave/MATLAB-style `.m` files and Python/NumPy,
in both directions, with every translation **verified by running both sides**.

> **Status: design phase.** Nothing is installable yet. See [docs/design.md](docs/design.md).
> **Status: early.** Both directions work end to end: `.m` → Python with 30 of 35
> rules mechanical, Python → `.m` with 29 mechanical, every case verified by running
> both languages. See [docs/design.md](docs/design.md) section 11.

## Why

Expand All @@ -16,14 +18,84 @@ or built-in (indexing with `end`, `*` vs `.*`, `linspace`, ...). Dependable rule
a scripted translator; the rest are handed to an LLM as focused context; every
result is executed and compared.

## Planned usage
## Usage

```bash
dualect scan script.m # which rules does this file need?
dualect translate script.m -o script.py # translate (scripted + LLM-guided)
dualect verify script.m script.py # run both, compare outputs
uv sync --all-groups # install (Python 3.11+, uv)
uv run pytest # rules, translators, corpus, both directions
uv run ruff check . && uv run ruff format --check .
uv run mypy dualect && uv run python tools/mypy_rules.py
```

### `.m` → Python

```bash
uv run dualect translate script.m -o script.py # translate, then verify by running both
uv run dualect scan script.m # which rules does it need? what has none?
uv run dualect context script.m # those rules as LLM-ready prompt context
uv run dualect verify script.m script.py # run both sides, compare every variable
```

`translate` handles each statement with the rules' deterministic translators. A
statement it cannot translate correctly is left as a `TODO(dualect)` hole that raises
`NotImplementedError`, and is reported; `dualect context` prints the rules an LLM
needs to fill it, and `--strict` refuses to write anything incomplete. The first line
of the output says whether it was verified against the `.m` source. Where a shape had
to be assumed the line says so (`# dualect: assumed ...`), and `# dualect: index k`
marks a variable stored 0-based because it only ever holds positions.

The `.m` side may use Octave syntax (`#` comments, `!=`, `++`, `+=`,
`do ... until`, `endfunction`); `--dialect matlab` reports it as Octave-only.

### Python → `.m`

```bash
uv run dualect translate model.py -o model.m # the direction follows the suffix
uv run dualect scan model.py # rules needed, Python constructs with none
uv run dualect context model.py
```

The same rules translate back: a 1-D NumPy array becomes a `1xN` row, `A @ v`
becomes `(A * v.').'`, `x[i]` becomes `x(i + 1)` (variables keep their Python
values), and the output is checked by running the `.py` and the `.m`. Holes are
`% TODO(dualect)` comments followed by `error(...)`. Python behaviour with no `.m`
counterpart is declined, not imitated: writing through a NumPy view or alias, a
function writing into its array argument, a lambda that reads a variable changed
later, `max` of data that may hold NaN, and the like (design section 5.5).

### Rules

```bash
uv run dualect rules list [--status guided] [--direction from-python]
uv run dualect rules check [RULE_ID ...] # does each rule earn its status, both ways?
uv run dualect rules new indexing/foo # scaffold a rule folder
uv run dualect llms-txt -o llms.txt # regenerate the one-line-per-rule index
```

`rules check` runs every rule's translator on its cases in each direction, compares
the result with the hand-written target and runs both sides; it fails when a rule
marked `mechanical` does not qualify, or a `guided` one does (promote it).
[`llms.txt`](llms.txt) lists every rule in one line for an LLM.

### MCP server

```bash
uv run dualect mcp # stdio; tools: scan, get_rule, translate, verify
```

A client configuration (Claude Code, Claude Desktop, ...) looks like:

```json
{"mcpServers": {"dualect": {"command": "uv",
"args": ["run", "--directory", "/path/to/dualect", "dualect", "mcp"]}}}
```

The server gives the client's model the rules and the checks; dualect itself never
calls an LLM API, and anything the model writes can be checked with `verify`.

`translate`, `verify` and the execution tests need GNU Octave (`brew install octave`,
`apt install octave`).

## License

Apache-2.0. MATLAB is a registered trademark of The MathWorks, Inc. dualect is not
Expand Down
39 changes: 39 additions & 0 deletions corpus/beam_deflection.m
Original file line number Diff line number Diff line change
@@ -0,0 +1,39 @@
% Deflection of a simply supported steel beam under a uniform load and a
% point load, by superposition of the Euler-Bernoulli closed-form solutions.
L = 4.0; % span [m]
E = 200e9; % Young's modulus [Pa]
I = 8.5e-6; % second moment of area [m^4]
w = 5e3; % uniform load [N/m]
P = 12e3; % point load [N]
a = 1.5; % position of the point load from the left support [m]
b = L - a;

n = 81;
x = linspace(0, L, n);

% Uniform load: v(x) = w x (L^3 - 2 L x^2 + x^3) / (24 E I)
v_uniform = w * x .* (L^3 - 2*L*x.^2 + x.^3) / (24*E*I);

% Point load at x = a: the solution is piecewise.
v_point = zeros(1, n);
for k = 1:n
if x(k) <= a
v_point(k) = P*b*x(k)*(L^2 - b^2 - x(k)^2) / (6*E*I*L);
else
v_point(k) = P*a*(L - x(k))*(2*L*x(k) - x(k)^2 - a^2) / (6*E*I*L);
end
end

v = v_uniform + v_point;
[v_max, k_max] = max(v);
x_max = x(k_max);

% Support reactions and the bending moment along the beam.
R_left = w*L/2 + P*b/L;
R_right = w*L + P - R_left;
M = R_left*x - w*x.^2/2;
right_of_load = x > a;
M(right_of_load) = M(right_of_load) - P*(x(right_of_load) - a);
M_max = max(M);

fprintf('max deflection %.2f mm at x = %.2f m\n', v_max*1e3, x_max);
27 changes: 27 additions & 0 deletions corpus/ode_rk4.m
Original file line number Diff line number Diff line change
@@ -0,0 +1,27 @@
% Damped harmonic oscillator x'' + 2 zeta w0 x' + w0^2 x = 0, integrated with
% the classic fourth-order Runge-Kutta method and compared with the exact
% solution.
w0 = 2*pi; % natural frequency [rad/s]
zeta = 0.1; % damping ratio
f = @(t, y) [y(2); -2*zeta*w0*y(2) - w0^2*y(1)];

t_end = 3;
h = 0.01;
t = 0:h:t_end;
n = numel(t);
y = zeros(2, n);
y(:, 1) = [1; 0]; % x(0) = 1, x'(0) = 0

for k = 1:n-1
k1 = f(t(k), y(:, k));
k2 = f(t(k) + h/2, y(:, k) + h/2*k1);
k3 = f(t(k) + h/2, y(:, k) + h/2*k2);
k4 = f(t(k) + h, y(:, k) + h*k3);
y(:, k+1) = y(:, k) + h/6*(k1 + 2*k2 + 2*k3 + k4);
end

wd = w0*sqrt(1 - zeta^2);
x_exact = exp(-zeta*w0*t) .* (cos(wd*t) + zeta*w0/wd*sin(wd*t));
err = max(abs(y(1, :) - x_exact));
energy = 0.5*y(2, :).^2 + 0.5*w0^2*y(1, :).^2;
decay = energy(end) / energy(1);
41 changes: 41 additions & 0 deletions corpus/signal_filter.m
Original file line number Diff line number Diff line change
@@ -0,0 +1,41 @@
% Moving-average (FIR) and first-order low-pass (IIR) filtering of a noisy
% sine, written out as loops and checked against the built-in filter().
fs = 200; % sample rate [Hz]
t = (0:1/fs:1-1/fs)'; % sample times, as a column
clean = sin(2*pi*5*t);
noise = 0.3*sin(2*pi*60*t) + 0.1*cos(2*pi*90*t); % deterministic "noise"
x = clean + noise;

% Moving average over N samples.
N = 9;
b = ones(N, 1) / N;
y_fir = zeros(size(x));
for n = 1:numel(x)
acc = 0;
for k = 1:N
if n - k + 1 >= 1
acc = acc + b(k) * x(n - k + 1);
end
end
y_fir(n) = acc;
end

% First-order low-pass: y(n) = alpha x(n) + (1 - alpha) y(n-1).
fc = 10;
alpha = 1 - exp(-2*pi*fc/fs);
y_iir = zeros(size(x));
y_iir(1) = alpha * x(1);
for n = 2:numel(x)
y_iir(n) = alpha * x(n) + (1 - alpha) * y_iir(n-1);
end

% The same filters with the built-in.
y_fir_ref = filter(b, 1, x);
y_iir_ref = filter(alpha, [1, alpha - 1], x);
fir_err = max(abs(y_fir - y_fir_ref));
iir_err = max(abs(y_iir - y_iir_ref));

% Residual noise power once the moving average has filled up.
settled = t >= (N - 1) / fs;
p_fir = mean((y_fir(settled) - clean(settled)).^2);
p_iir = mean((y_iir(settled) - clean(settled)).^2);
Loading
Loading