Skip to content

Commit ad84c67

Browse files
jishengyang-caljishengyang-cal
committed
Bootstrap GATL AD lab
0 parents  commit ad84c67

11 files changed

Lines changed: 1621 additions & 0 deletions

File tree

‎.gitignore‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1 @@
1+
/target

‎AGENTS.md‎

Lines changed: 13 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,13 @@
1+
# Agent Instructions
2+
3+
This repository is an external numeric lab for `gatl-core` risk-model artifacts.
4+
5+
Rules:
6+
7+
- Do not modify `/home/jisheng-yang/projects/gatl-core` from this repo.
8+
- Do not add real ML/AD frameworks unless explicitly authorized.
9+
- Do not add network calls, background workers, secret handling, or production
10+
command execution.
11+
- Keep checks deterministic and local.
12+
- Record numeric assumptions, especially the current `const` primitive value.
13+
- Use `cargo fmt`, `cargo test`, and `make check` before committing.

‎Cargo.lock‎

Lines changed: 105 additions & 0 deletions
Some generated files are not rendered by default. Learn more about customizing how changed files appear on GitHub.

‎Cargo.toml‎

Lines changed: 7 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,7 @@
1+
[package]
2+
name = "gatl-ad-lab"
3+
version = "0.1.0"
4+
edition = "2021"
5+
6+
[dependencies]
7+
serde_json = "1"

‎Makefile‎

Lines changed: 23 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,23 @@
1+
.PHONY: check fmt test validate eval gradient clean
2+
3+
INPUTS=--input action_features=2.0 --input user_features=3.0 --const 1.0
4+
5+
check: fmt test validate eval gradient
6+
7+
fmt:
8+
cargo fmt --check
9+
10+
test:
11+
cargo test
12+
13+
validate:
14+
cargo run -- validate examples/risk-models.valid.json
15+
16+
eval:
17+
cargo run -- eval examples/risk-models.valid.json $(INPUTS) --out target/gatl-ad-lab/evaluation.json
18+
19+
gradient:
20+
cargo run -- check-gradient examples/risk-models.valid.json $(INPUTS) --epsilon 0.000001 --tolerance 0.00001 --out target/gatl-ad-lab/ad-check.json
21+
22+
clean:
23+
rm -rf target

‎README.md‎

Lines changed: 72 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,72 @@
1+
# GATL AD Lab
2+
3+
GATL AD Lab is an external numeric check harness for `gatl-core` risk-model
4+
artifacts. It consumes `gatl risk-models` JSON, evaluates the typed scalar RPN
5+
expression, executes the exported reverse derivative instruction skeleton, and
6+
compares it with a local finite-difference estimate.
7+
8+
This repo is intentionally outside `gatl-core`. It does not change GATL
9+
language semantics and does not add an AD runtime to the language core.
10+
11+
## Scope
12+
13+
v0.1 supports:
14+
15+
- `gatl-core/v0.1-risk-model-analysis`;
16+
- `typedExpression.format = rpn/scalar-v0.1`;
17+
- scalar primitives `const`, `add`, `sub`, `mul`, `div`, `exp`, `log`,
18+
`sigmoid`, `dot`, and `matmul`;
19+
- reverse pullbacks from `derivativeProgram.instructions`;
20+
- finite-difference gradient comparison.
21+
22+
`const` has no literal in current `gatl-core`, so this lab treats it as an
23+
external numeric assumption. The CLI default is `--const 1.0`, and reports
24+
record that value.
25+
26+
## Usage
27+
28+
Generate risk-model artifacts:
29+
30+
```bash
31+
cd /home/jisheng-yang/projects/gatl-core
32+
./gatl risk-models examples/valid-fill-kinds.gir --out target/gatl/risk-models.json
33+
```
34+
35+
Run AD checks externally:
36+
37+
```bash
38+
cd /home/jisheng-yang/projects/gatl-ad-lab
39+
cargo run -- validate /home/jisheng-yang/projects/gatl-core/target/gatl/risk-models.json
40+
cargo run -- eval /home/jisheng-yang/projects/gatl-core/target/gatl/risk-models.json \
41+
--input action_features=2.0 \
42+
--input user_features=3.0 \
43+
--const 1.0 \
44+
--out target/gatl-ad-lab/evaluation.json
45+
cargo run -- check-gradient /home/jisheng-yang/projects/gatl-core/target/gatl/risk-models.json \
46+
--input action_features=2.0 \
47+
--input user_features=3.0 \
48+
--const 1.0 \
49+
--epsilon 0.000001 \
50+
--tolerance 0.00001 \
51+
--out target/gatl-ad-lab/ad-check.json
52+
```
53+
54+
Local example:
55+
56+
```bash
57+
make check
58+
```
59+
60+
## Boundary
61+
62+
This is a local numeric lab, not a production AD engine:
63+
64+
- no TensorFlow, PyTorch, JAX, ONNX, or autograd framework;
65+
- no external proof checker;
66+
- no network;
67+
- no secrets;
68+
- no runtime worker;
69+
- no modification of `gatl-core`.
70+
71+
Future proof-oriented work should consume the generated AD check report or add
72+
a separate proof fixture format, not move numeric execution into `gatl-core`.

‎docs/ad-check-report.md‎

Lines changed: 37 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,37 @@
1+
# AD Check Report
2+
3+
`gatl-ad-lab check-gradient` emits:
4+
5+
```text
6+
format = gatl-ad-lab/v0.1-ad-check-report
7+
```
8+
9+
The report includes:
10+
11+
- selected `modelId`;
12+
- numeric assumptions;
13+
- primal value;
14+
- reverse gradients from `derivativeProgram.instructions`;
15+
- finite-difference gradients;
16+
- per-input absolute errors;
17+
- pass/fail summary.
18+
19+
## Comparison
20+
21+
The finite-difference estimate is central difference:
22+
23+
```text
24+
(f(x + epsilon) - f(x - epsilon)) / (2 * epsilon)
25+
```
26+
27+
Each input passes when:
28+
29+
```text
30+
abs(reverse - finiteDifference) <= tolerance
31+
```
32+
33+
## Boundary
34+
35+
This report is not a formal proof. It is a local executable check that the
36+
current exported derivative instruction skeleton agrees with a numerical
37+
finite-difference baseline under declared assumptions.

‎docs/architecture.md‎

Lines changed: 57 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,57 @@
1+
# Architecture
2+
3+
`gatl-ad-lab` is an external consumer of `gatl-core` risk-model artifacts. It
4+
does not define the GATL language. It checks that the exported typed numeric
5+
expression and derivative instruction skeleton behave consistently under local
6+
scalar numeric assumptions.
7+
8+
## Pipeline
9+
10+
```text
11+
gatl-core risk-models.json
12+
-> contract validation
13+
-> typed scalar expression evaluation
14+
-> reverse derivative instruction interpretation
15+
-> finite-difference comparison
16+
-> AD check report
17+
```
18+
19+
## Trusted Boundary
20+
21+
The v0.1 trusted boundary is:
22+
23+
- JSON parsing;
24+
- `gatl-core/v0.1-risk-model-analysis` validation;
25+
- scalar RPN node evaluation;
26+
- local pullback rules for smooth scalar primitives;
27+
- central finite-difference comparison.
28+
29+
The lab does not prove AD correctness. It provides an external executable
30+
sanity check and a report that future proof tooling can consume.
31+
32+
## Primitive Semantics
33+
34+
Supported scalar primitives:
35+
36+
- `const`: external assumption, default `1.0`;
37+
- `add`;
38+
- `sub`;
39+
- `mul`;
40+
- `div`;
41+
- `exp`;
42+
- `log`;
43+
- `sigmoid`;
44+
- `dot`: scalar multiply in v0.1 lab;
45+
- `matmul`: scalar multiply in v0.1 lab.
46+
47+
Non-smooth or nondeterministic primitives remain outside this lab.
48+
49+
## Non Goals
50+
51+
- No production AD engine.
52+
- No TensorFlow, PyTorch, JAX, ONNX, or autograd integration.
53+
- No proof assistant integration.
54+
- No network access.
55+
- No secret handling.
56+
- No background worker.
57+
- No changes to `gatl-core`.

0 commit comments

Comments
 (0)