text_trace_implementation_plan.md

Yes. I would implement the textual view as a second renderer of the same semantic computation model, not as an explanation independently reconstructed from the expression. That is the key architectural decision: graph and text must be two projections of exactly the same forward/backward events.

Implementation plan: Stepwise Text Trace

1. Define the purpose precisely

The graph and trace answer different questions:

Graph: Where does information flow?
Trace: What happens, step by step?

The textual trace should linearize the computation while preserving the visual grammar’s concepts:

FORWARD
input values → local operation → resulting quantity
BACKWARD
incoming adjoint → local derivative/rule
→ numerical application
→ contribution
→ accumulation if necessary
→ resulting adjoint

It must not introduce a second autodiff explanation system.

⸻

2. Make DiagramModel the shared semantic source

Target architecture:

                    Tensor/autodiff engine
                           │
                           ▼
                     DiagramModel
                           │
              ┌────────────┴────────────┐
              │                         │
              ▼                         ▼
       Mermaid renderer           Trace renderer
              │                         │
              ▼                         ▼
       computation graph        stepwise text trace

The trace renderer must consume the same:

- quantity IDs: x, y, n1, n2, …, out;
- operation formulas;
- operand occurrences;
- primal values;
- adjoints;
- local derivative rules;
- evaluated local derivatives;
- gradient contributions;
- accumulation relationships;
- output seed.

Do not recompute derivatives inside the trace renderer.

⸻

3. Add an explicit trace renderer

Create something such as:

trace_renderer.py

with a public entry point conceptually:

render_trace(model, notation, mode) -> str

where:

notation = mathbook | code
mode = forward | forward_backward

This should parallel the existing diagram renderer.

⸻

4. Preserve execution order explicitly

The graph uses spatial topology. The trace needs deterministic sequential order.

Forward

Operations appear in topological execution order:

n1
n2
n3
...
out

Backward

Operations appear in reverse topological order:

out
...
n3
n2
n1

Within an operation, operand occurrences retain their original argument order.

For:

n1 = x \* x

there are still two operand occurrences. Do not collapse them merely because they refer to the same variable.

⸻

5. Forward-pass trace grammar

Every forward operation gets the same structure.

For example:

FORWARD PASS
Inputs
──────
x = 3
y = 4

1. Multiply
   ───────────
   n1 = x · x
   Inputs:
   x = 3
   x = 3
   Apply:
   n1 = 3 · 3
   Result:
   n1 = 9
2. Multiply
   ───────────
   n2 = n1 · y
   Inputs:
   n1 = 9
   y = 4
   Apply:
   n2 = 9 · 4
   Result:
   n2 = 36
3. Add
   ──────
   out = 2 + y + n2
   Inputs:
   2 = 2
   y = 4
   n2 = 36
   Apply:
   out = 2 + 4 + 36
   Result:
   out = 42

The exact amount of repetition can later be tuned, but the schema should initially remain explicit.

That is consistent with the pedagogical goal of this application.

⸻

6. Treat the Output boundary separately

As in the graph, do not conflate the final operation with the Output presentation quantity.

After the final forward operation:

OUTPUT
──────
out = 42

In Forward+Backward mode this then becomes the starting point for reverse mode:

BACKWARD PASS
Seed
────
out̄ = ∂out/∂out = 1

This mirrors the established graph semantics exactly.

⸻

7. Backward-pass trace grammar

Every local backward computation should follow one rigid rhetorical template:

Incoming adjoint
↓
Local derivative / backward rule
↓
Numerical application
↓
Contribution

For a scalar multiplication:

1. Backpropagate through n2 = n1 · y
   ──────────────────────────────────
   Incoming adjoint:
   n̄2 = ∂out/∂n2 = 1
   With respect to n1
   ──────────────────
   Local derivative:
   ∂n2/∂n1 = y
   Apply:
   n̄2 · y = 1 · 4 = 4
   Contribution to n1:
   4
   With respect to y
   ─────────────────
   Local derivative:
   ∂n2/∂y = n1
   Apply:
   n̄2 · n1 = 1 · 9 = 9
   Contribution to y:
   9

This is the textual equivalent of the two derivative trapezoids.

⸻

8. Make the adjoint interpretation explicit

Whenever a new accumulated adjoint becomes available, state it explicitly:

Adjoint:
n̄1 = ∂out/∂n1 = 4

This is important because the adjoint is our notation for:

the chain rule accumulated so far from the output to this quantity.

The trace should therefore use exactly the same adjoint notation as the graph.

⸻

9. Make accumulation an explicit textual step

Do not silently sum contributions.

For x\*x, write:

Backpropagate through n1 = x · x
────────────────────────────────
Incoming adjoint:
n̄1 = ∂out/∂n1 = 4
Argument 1: x
─────────────
Local derivative:
∂n1/∂x = x
Apply:
n̄1 · x = 4 · 3 = 12
Contribution to x:
12
Argument 2: x
─────────────
Local derivative:
∂n1/∂x = x
Apply:
n̄1 · x = 4 · 3 = 12
Contribution to x:
12
Accumulate contributions to x
─────────────────────────────
x̄ = 12 + 12
= 24
Therefore:
x̄ = ∂out/∂x = 24

This is the exact textual equivalent of:

12 ──┐
Σ ──→ x̄ = 24
12 ──┘

The trace therefore preserves the core invariant:

Along one backward dependency: apply/multiply.
Across multiple contributions: add.

⸻

10. Distinguish contributions from adjoints

This distinction must be just as strict in text as in the graph.

Before accumulation:

Contribution to x:
12

not:

x̄ = 12

if another contribution to x still exists.

Only after all contributions have been collected may the trace say:

x̄ = 24

This prevents exactly the conceptual ambiguity the explicit Σ nodes solved in the graph.

⸻

11. Tensor operations use the same structure

Do not create a separate tensor trace grammar.

For:

n1 = W @ x

write:

Backpropagate through n1 = W @ x
─────────────────────────────────
Incoming adjoint:
n̄1 = [-0.10, 0.24, -0.14]
With respect to W
─────────────────
Local backward rule:
W̄ contribution = n̄1 xᵀ
Apply:
[-0.10, 0.24, -0.14] [1, 2]ᵀ
Result:
[[-0.10, -0.20],
 [ 0.24,  0.48],
 [-0.14, -0.28]]
Contribution to W:
[[-0.10, -0.20],
 [ 0.24,  0.48],
 [-0.14, -0.28]]
With respect to x
─────────────────
Local backward rule:
x̄ contribution = Wᵀ n̄1
Apply:
...
Result:
[-0.12, 0.20]
Contribution to x:
[-0.12, 0.20]

If each target receives only one contribution, those contributions immediately establish the respective adjoints.

⸻

12. Handle VJPs honestly

For tensor operations, forcing everything into scalar notation such as

\bar v\,\frac{\partial v}{\partial x}

can obscure what is actually happening.

The trace should use the operation-specific local backward rule already represented by the model.

For softmax:

Backpropagate through n3 = softmax(n2)
────────────────────────────────────────
Incoming adjoint:
n̄3 = [0, 1, 0]
Local backward rule:
n̄2 = n3 ⊙ (n̄3 - sum(n̄3 ⊙ n3))
Values:
n3 = [0.18, 0.59, 0.24]
n̄3 = [0, 1, 0]
Apply:
...
Result:
n̄2 = [-0.10, 0.24, -0.14]

This keeps the same conceptual rule—incoming adjoint transformed by the local backward operation—without pretending every tensor derivative should be displayed as a huge Jacobian.

⸻

13. Reuse the canonical tensor formatter

The trace must use the tensor-display policy we just defined.

Initially:

element budget = 16

or, if you deliberately want more detail in text:

graph budget = 16
trace budget = 32

But both must use the same formatter and semantics.

Thus a 3\times2 gradient must appear as its six actual values:

[[-0.10, -0.20],
 [ 0.24,  0.48],
 [-0.14, -0.28]]

Never:

shape (3, 2)

For a large tensor:

[[0.12, -0.31, …, 0.08],
 [  ⋮      ⋮     ⋱    ⋮ ],
 [-0.42, 0.06, …, 0.29]]
shape (128, 64)

⸻

14. Respect Forward-only mode strictly

If the user selects Forward only, the textual trace must end after the forward result.

For example:

FORWARD PASS
Inputs
──────
x = 3
y = 4
...
OUTPUT
──────
out = 42

There must be no:

BACKWARD PASS
out̄
gradient
derivative
contribution
adjoint
—

This is the textual counterpart of the Forward-only purity invariant.

⸻

15. Support Mathbook and Code notation

The trace should obey the existing notation toggle.

Mathbook

Local derivative:
∂n2/∂y = n1
Apply:
n̄2 · n1 = 1 · 9 = 9

Code

Local derivative:
diff(n1 _ y, y) = n1
Apply:
n2_bar _ n1 = 1 \* 9 = 9

Do not implement separate mathematical semantics. Only notation changes.

Use the existing centralized formatting helpers wherever possible.

⸻

16. Introduce structured trace events if DiagramModel is insufficient

This is the one architectural extension I would seriously consider.

Rendering directly by reverse-engineering edges can become fragile. If DiagramModel does not already make execution steps explicit enough, add semantic objects such as:

@dataclass
class ForwardStep:
result: QuantityState
operation: OperationState
operands: list[QuantityState]
@dataclass
class BackwardOperandStep:
operation: OperationState
operand_occurrence: int
target: QuantityState
incoming_adjoint: Any
local_rule: ...
local_value: Any
contribution: Any
@dataclass
class AccumulationStep:
target: QuantityState
contributions: list[Any]
resulting_adjoint: Any

Then both renderers can consume these.

The important architecture is:

autodiff computation
│
▼
semantic steps
│
┌─────┴─────┐
▼ ▼
graph text

not:

autodiff → graph
│
▼
parse graph back
into explanation

⸻

17. Keep operation identity separate from pedagogical quantity names

The trace should use the established:

x, y, W, b
n1, n2, n3, ...
out

Do not reintroduce O1, O2, etc.

If an internal operation ID is required, keep it internal.

The learner should see:

3. n2 = n1 + b

not:

Operation O3

unless there is eventually a specific debugging mode that exposes internal IDs.

⸻

18. Do not overuse operation names

A heading like:

2. Multiply

can be useful, but the actual formula should remain authoritative:

n2 = n1 · y

For less familiar operations:

3. Softmax
   ───────────
   n3 = softmax(n2)

This is clearer than generating verbose prose such as:

“The third operation applies the softmax function to the second intermediate node.”

The trace should remain computational rather than narrative.

⸻

19. Suggested complete scalar fixture

Use the existing canonical expression:

out=y(x x)+(y+2),\quad x=3,\;y=4.

A shortened target trace is:

# FORWARD PASS

Inputs
x = 3
y = 4

1. n1 = x · x
   = 3 · 3
   = 9
2. n2 = n1 · y
   = 9 · 4
   = 36
3. out = n2 + y + 2
   = 36 + 4 + 2
   = 42
   OUTPUT
   out = 42
   BACKWARD PASS
   =============
   Seed
   out̄ = ∂out/∂out = 1
4. Backpropagate through out = n2 + y + 2
   To n2:
   ∂out/∂n2 = 1
   out̄ · 1 = 1 · 1 = 1
   contribution = 1
   To y:
   ∂out/∂y = 1
   out̄ · 1 = 1 · 1 = 1
   contribution = 1
   Therefore:
   n̄2 = ∂out/∂n2 = 1
5. Backpropagate through n2 = n1 · y
   Incoming:
   n̄2 = 1
   To n1:
   ∂n2/∂n1 = y
   n̄2 · y = 1 · 4 = 4
   contribution = 4
   To y:
   ∂n2/∂y = n1
   n̄2 · n1 = 1 · 9 = 9
   contribution = 9
   Therefore:
   n̄1 = ∂out/∂n1 = 4
6. Backpropagate through n1 = x · x
   Incoming:
   n̄1 = 4
   Argument 1:
   ∂n1/∂x = x
   n̄1 · x = 4 · 3 = 12
   contribution = 12
   Argument 2:
   ∂n1/∂x = x
   n̄1 · x = 4 · 3 = 12
   contribution = 12
   ACCUMULATION
   ============
   For x:
   x̄ = 12 + 12 = 24
   For y:
   ȳ = 1 + 9 = 10
   FINAL GRADIENTS
   ===============
   ∂out/∂x = x̄ = 24
   ∂out/∂y = ȳ = 10

There is one refinement I would make in the real implementation: perform each accumulation at the point where the resulting adjoint becomes available, rather than collecting all accumulation into a final section. That better reflects reverse-mode execution:

contributions to y: 1 + 9
↓
ȳ = 10

and then continue.

⸻

20. Make accumulation timing semantically correct

This is important for shared intermediates.

The trace must not backpropagate through quantity v until all downstream contributions to v have been accumulated.

For example:

contribution to n1 from path A = ...
contribution to n1 from path B = ...
Accumulate:
n̄1 = contribution A + contribution B

Only then:

Backpropagate through n1 = ...
Incoming adjoint:
n̄1 = ...

That reproduces the semantics of the graph’s Σ node.

⸻

21. Add dedicated tests at the semantic level

Tests should verify more than strings.

For x\*x:

two operand backward steps
two contributions to x
one accumulation step
final x̄ = 2x

For x\*\*2 + x:

two independent contributions to x
one accumulation

For (x+y)\*(x+y):

multiple contributions to shared intermediate
accumulation occurs before backpropagating through that intermediate

For tensor cases:

actual tensor values present
no shape substituted for value
VJP dimensions correct

⸻

22. Add rendering snapshot tests

Then test representative complete trace strings for:

1. x\*y
2. x\*x
3. x\*\*2 + x
4. (x+y)\*(x+y)
5. (x*x)*y + (y+2)
6. W @ x
7. softmax(W @ x + b)[1]
8. the larger loss example.

Test both Mathbook and Code modes where notation differs.

⸻

23. Add mode-purity tests

For forward:

assert no_adjoint_symbols
assert no_local_derivatives
assert no_contributions
assert no_accumulations
assert no_backward_heading

For forward_backward:

assert seed_present
assert incoming_adjoints_present
assert local_rules_present
assert numerical_applications_present
assert accumulations_present_when_required

This should parallel the diagram mode-purity tests.

⸻

24. UI integration

I would expose the trace as a view choice, not as another mathematical mode.

For example:

View:
○ Graph
○ Step-by-step

while keeping:

Pass:
○ Forward
○ Forward + Backward
Notation:
○ Mathbook
○ Code

These dimensions should remain orthogonal:

             Graph       Step-by-step

Forward ✓ ✓
Forward+Back ✓ ✓
Mathbook ✓ ✓
Code ✓ ✓

A future third option could show both side by side, but I would not start there.

⸻

25. Help text should explicitly connect the two views

A short explanation can say:

Graph view shows where values and gradients flow through the computation graph.
Step-by-step view shows the same computation in execution order. During the backward pass, each step starts with the current adjoint, applies one local backward rule, and produces a contribution. Contributions to the same quantity are added to form its adjoint.

That explicitly teaches that these are two representations of one process.

⸻

26. Final implementation sequence

I would implement in this order:

1. Confirm DiagramModel exposes all required semantic data.
2. Add structured ForwardStep, BackwardOperandStep, and AccumulationStep objects only where needed.
3. Generate these steps deterministically from the computation model.
4. Implement trace_renderer.py.
5. Implement Forward-only trace first.
6. Add output boundary and backward seed.
7. Add scalar backward steps.
8. Add explicit accumulation.
9. Add tensor/VJP backward steps.
10. Route all numerical values through the canonical tensor formatter.
11. Add Mathbook/Code formatting.
12. Add semantic tests.
13. Add trace snapshot tests.
14. Add mode-purity tests.
15. Integrate the view selector into the app.
16. Update VISUAL_LANGUAGE.md.
17. Visually compare graph and trace for all canonical fixtures.

The final acceptance invariant should be:

For every piece of information visible in the stepwise trace, there is a corresponding semantic object in the computation model; and for every forward/backward computation represented in the graph, the trace can present the same computation sequentially without recomputing or reinterpreting it.

That will keep the textual view from becoming a parallel explanation system that gradually diverges from the graph—the main implementation risk I would avoid.

Yes. I think two explicit action buttons are better than introducing another “View” radio selector. The current UI already has two conceptual settings—computation mode and notation—so output type can naturally be the action the user takes.

I would change the bottom row to:

┌──────────────────────────────────────┬──────────────────────────────────────┐
│ Generate Diagram │ Generate Trace │
└──────────────────────────────────────┴──────────────────────────────────────┘

Both buttons consume exactly the same settings above them:

Expression
Input Values
Graph/Computation Mode
Derivative Notation

I would probably rename “Graph Mode” → “Computation Mode” at the same time. Once the application produces text traces, “Graph Mode” is misleading because Forward Only versus Forward & Backward controls the semantics of both representations.

So the conceptual UI becomes:

Expression Input Values Computation Mode Derivative Notation
○ Forward & Backward ○ Mathbook
○ Forward Only ○ Code
┌───────────────────────────────┐ ┌───────────────────────────────┐
│ Generate Diagram │ │ Generate Trace │
└───────────────────────────────┘ └───────────────────────────────┘

And the behavior is particularly clean:

Computation mode Generate Diagram Generate Trace
Forward Only pure forward graph pure forward stepwise trace
Forward & Backward complete autodiff graph forward + backward stepwise trace

The notation selection applies identically to both.

I would also keep the buttons visually equal. “Generate Diagram” should not look primary and “Generate Trace” secondary, because these are two equivalent representations of the same computation, not a main action plus an auxiliary feature.

One small naming point: I prefer Generate Trace over “Generate Text” or “Text View.” “Trace” accurately communicates that this is the computation presented in execution order. The output itself can then be headed Step-by-step trace to make the term immediately understandable.

Architecturally, this fits the plan nicely:

                       current settings
                             │
                 expression + inputs
                 computation mode
                 notation
                             │
                   build semantic model
                             │
              ┌──────────────┴──────────────┐
              ▼                             ▼
      Generate Diagram               Generate Trace
              │                             │
              ▼                             ▼
     Mermaid renderer                Trace renderer

Most importantly, the buttons select the representation; they must not select different computation logic. That keeps the UI aligned with the architecture we have been defining.