How visible is the VFI Toolkit to AI? Tips and Tricks

aledinola · March 11, 2026, 10:23pm

I asked this question in ChatGPT 5.4

Are the toolkit matlab files publicly accessible? Can you access them easily? What can we do to increase their visibility to AI?

ChatGPT gave a fairly informative answer, with suggestions on how to make the toolkit more visible to AI and LLMs.

Assistant

Yes — the VFI Toolkit MATLAB code is publicly accessible, but
there are a few reasons why AI systems often don’t “see” or learn from
it well.

1. Are the MATLAB files publicly accessible?

Yes. The main implementation is here:

VFI Toolkit (MATLAB) –
GitHub - vfitoolkit/VFIToolkit-matlab: A Matlab Toolkit for Macroeconomic Models using Value Function Iteration · GitHub

and the documentation/pseudocode is here:

GitHub - robertdkirkby/vfitoolkitrawdocs: The tex files that create the pdfs for VFI Toolkit. This repo is mainly intended for AI not humans. · GitHub

Since these repositories are public GitHub repos, they are
accessible to:

search engines
web crawlers
AI browsing tools

So in principle the code is visible.

However, visibility to AI training datasets is a different issue.

2. Why AI models often don’t know these files well

Even if code is public, it may still be poorly represented in AI
models because of:

(1) Small repository footprint

Large models learn more from repositories that are:

widely used
widely forked
widely referenced

The toolkit is specialized academic code.

(2) Documentation is fragmented

The code is split across many folders:

ValueFnIter/
ValueFnIter/FHorz/
ValueFnIter/FHorz/SemiExo/
ValueFnIter/FHorz/SemiExo/GridInterpLayer/

But there is no single narrative document explaining:

architecture
algorithms
GPU implementation
interpolation layer
solver flow

AI models learn much better from long explanatory documents than raw
code.

(3) MATLAB code is underrepresented

Most open-source training data contains more:

Python
C++
JavaScript

MATLAB code is much rarer.

(4) Lack of tutorials or blog posts

The most important factor for AI visibility is actually secondary
content, such as tutorials and discussions.

3. What increases visibility to AI the most

Long technical documentation

Example:

docs/
  architecture.md
  value_function_iteration.md
  grid_interpolation_layer.md
  gpu_implementation.md
  semi_exogenous_states.md

Tutorials

Example:

tutorials/
  1_basic_vfi.m
  2_heterogeneous_agents.m
  3_grid_interpolation.m
  4_gpu_solver.m

A single “architecture overview”

User problem
   ↓
Toolkit parser
   ↓
ValueFnIter dispatcher
   ↓
solver variants
   ↓
GPU / GI / divide-and-conquer

Wiki pages

GitHub wiki pages are heavily indexed.

Example notebooks

MATLAB live scripts explaining solver flow.

4. The single best improvement

A document like:

“VFI Toolkit Architecture and Algorithms”

explaining:

solver architecture
data structures
interpolation layer
GPU parallelization
semi-exogenous states
divide-and-conquer
expectation computation

5. Something else that helps AI a lot

Add descriptive comments inside the code explaining algorithmic steps.

6. Citation

If the toolkit is cited widely in papers, its algorithms enter academic
corpora used for model training.

7. Textbook-style explanation

Example:

Computational Dynamic Programming with the VFI Toolkit

with chapters on architecture, VFI, interpolation layers, GPU
implementation, and transition paths.

8. Assessment

The toolkit is technically excellent but structurally hard to understand
without architectural documentation.

Assistant

There are several architectural choices in the VFI Toolkit that are
unusual compared with other heterogeneous-agent solvers (like HARK or
dolo). Understanding them makes the code easier to navigate.

1. Solver combinatorics

Instead of one solver with many options, the toolkit creates separate
solver variants for different feature combinations (finite horizon,
semi-exogenous shocks, grid interpolation, etc.).

2. Tensor state representation

States remain separate dimensions, e.g.

V(a, z, semiz, age)

rather than flattening the state space.

3. Grid interpolation layer

The toolkit introduces a refined set of candidate points between grid
nodes used only during maximization.

4. Separation of expectation and maximization

Expectation of the continuation value is computed before the
maximization step whenever possible.

User

Yes show

Assistant

The key performance trick in the toolkit is computing expectations over
shocks using matrix operations instead of loops.

Naive approach

for iz = 1:nz
    for iap = 1:na
        for izp = 1:nz
            EV(iap,iz) += P(iz,izp)*V(iap,izp)
        end
    end
end

Vectorized approach

EV = V * P'

This uses optimized BLAS routines.

Extension to higher dimensions

If the value function is

V(a, semiz, z)

reshape the tensor:

V2 = reshape(V, na*nsemiz, nz)
EV2 = V2 * Pz'
EV  = reshape(EV2, na, nsemiz, nz)

This removes explicit loops and is efficient on both CPU and GPU.

Semi‑exogenous shocks

When transitions depend on a decision variable, the expectation must be
recomputed for each value of that decision.

Key insight

Separate operations by dimension:

Step Dimension

expectation shocks
maximization decisions
interpolation asset grid

This structure explains the toolkit’s scalability.

robertdkirkby · March 11, 2026, 10:28pm

The first time I ever asked ChatGPT what VFI Toolkit is it told me it was software developed by Jesus Fernandez-Villaverde, so this is definitely an improvement on that

aledinola · March 11, 2026, 10:52pm

I asked for a refinement

VFI Toolkit: Architecture, Algorithms, and AI Discoverability

This document explains the internal architecture of the VFI Toolkit for MATLAB, with two goals:

Help researchers understand how the toolkit is structured.
Improve the visibility and learnability of the toolkit for AI systems.

The VFI Toolkit is a highly flexible framework for solving dynamic programming problems using Value Function Iteration (VFI). The design reflects a strong focus on:

modular solver variants
vectorized tensor operations
GPU compatibility
extensibility to many model classes

However, these strengths also make the repository difficult to understand without a high-level description.

This document explains the key architectural ideas.

1 Repository Structure

The core logic lives in the ValueFnIter directory.

Typical structure:

ValueFnIter/
    InfHorz/
    FHorz/
    ExperienceAsset/
    SemiExo/
    GridInterpLayer/
    DivideAndConquer/

The repository uses a dispatch architecture:

User model specification
        ↓
ValueFnIter dispatcher
        ↓
Select solver variant
        ↓
Call specialized solver

For example, the finite-horizon dispatcher:

ValueFnIter/FHorz/ValueFnIter_Case1_FHorz.m

detects:

finite vs infinite horizon
semi-exogenous states
experience assets
grid interpolation
divide-and-conquer options

and routes to a specialized solver.

This architecture avoids large monolithic solvers.

2 Solver Combinatorics

Instead of implementing a single solver with many conditionals, the toolkit generates solver variants for combinations of model features.

Examples:

ValueFnIter_FHorz.m
ValueFnIter_FHorz_SemiExo.m
ValueFnIter_FHorz_SemiExo_GI.m
ValueFnIter_FHorz_SemiExo_DC_GI.m

Each solver is optimized for a specific configuration.

Advantages:

simpler internal logic
fewer runtime conditionals
better vectorization
easier GPU execution

Disadvantages:

many files
harder to navigate without documentation.

This design is unusual compared to frameworks like HARK or dolo, which typically use a single configurable solver.

3 Tensor State Representation

A core design principle is preserving the tensor structure of the state space.

Instead of flattening states into a single index:

V(state_index)

the toolkit uses multidimensional arrays:

V(a, z, semiz, age)

Typical dimensions:

(na × nz × nsemiz × Nj)

Benefits:

vectorized operations
clean expectation operators
efficient GPU kernels
intuitive economic interpretation

Tensor layout also simplifies expectation computations.

4 Expectation Operator

Dynamic programming requires computing expectations such as

[
E[V(a’,z’)]
]

A naive implementation loops over shocks:

for iz = 1:nz
  for izp = 1:nz
     EV += P(iz,izp)*V(...)
  end
end

The toolkit instead converts this into matrix multiplication.

If

V(a,z)

is reshaped to

(na × nz)

then

EV = V * P'

computes expectations over the shock dimension.

For higher dimensional tensors:

V2  = reshape(V, na*nsemiz, nz)
EV2 = V2 * Pz'
EV  = reshape(EV2, na, nsemiz, nz)

This is a major performance optimization.

Advantages:

uses BLAS routines
GPU-compatible
eliminates nested loops

5 Grid Interpolation Layer

One distinctive feature of the toolkit is the Grid Interpolation Layer (GI).

Standard approaches:

restrict choices to grid points
interpolate the value function continuously

The toolkit uses a hybrid approach.

State grid:

a1   a2   a3   a4

Interpolation layer:

a1  •  •  a2  •  •  a3  •  •  a4

Key idea:

value function stored only on coarse grid
additional candidate points evaluated during maximization

This reduces discretization error while keeping memory usage low.

The GI solver variants are located in:

ValueFnIter/.../GridInterpLayer/

6 Separation of Expectation and Maximization

The toolkit separates two operations:

expectation over shocks
maximization over decisions

Typical Bellman code:

max_d u(d) + β E[V']

Many implementations compute E[V'] inside the maximization loop.

The toolkit instead computes:

EV(a',z)

first, then performs maximization.

Advantages:

expectation computed once
fewer repeated operations
cleaner GPU kernels.

7 Semi-Exogenous States

The toolkit supports semi-exogenous states, where transition probabilities depend on decisions.

Example:

π(semiz' | semiz, d)

In this case the expectation operator becomes conditional on the decision:

E[V | d]

The solver structure becomes:

for d2
    compute EV conditional on d2
    solve inner maximization
end

This architecture is implemented in

ValueFnIter/.../SemiExo/

8 Design Principle: Dimension Decomposition

The toolkit implicitly decomposes Bellman operators by dimension:

Operation	Dimension
expectation	shocks
maximization	decisions
interpolation	asset grid
backward iteration	time

This decomposition enables:

vectorization
GPU acceleration
modular solver design

9 Why the Toolkit Works Well on GPU

The architecture is well suited for GPU computation because it emphasizes:

large tensor operations
minimal branching
matrix algebra
predictable memory access

GPU kernels benefit from exactly these patterns.

10 Improving AI Discoverability

Although the toolkit is technically sophisticated, its architecture is difficult to infer from the repository alone.

The following additions would significantly improve discoverability for both humans and AI systems:

Architecture documentation

Add a document such as this one to

docs/

Tutorials

Example directory:

tutorials/
    basic_vfi.m
    heterogeneous_agents.m
    gpu_solver.m

Annotated examples

Step-by-step explanations of:

state tensor layout
expectation computation
policy storage

Code comments

Add algorithmic comments inside solver files explaining:

tensor reshaping
expectation operators
interpolation logic

11 Summary

Key architectural ideas of the VFI Toolkit:

solver combinatorics via dispatch
tensor state representation
expectation via matrix algebra
grid interpolation layer
separation of expectation and maximization
GPU-friendly design

These ideas allow the toolkit to scale to large heterogeneous-agent models while remaining flexible.

However, without high-level documentation these design principles are difficult to discover.

Providing architectural documentation greatly improves:

usability for researchers
visibility to AI systems
long-term maintainability of the toolkit.

aledinola · March 11, 2026, 11:00pm

I think the suggestions make sense:

More documentation: what is missing is a document, written in markdown, that gives an overview of the toolkit and then explains all the options. I think there is an old document but is now outdated.
More tutorials. There are two excellent tutorials now, one about OLG and another about life-cycle models. Maybe what’s missing is a tutorial on Aiyagari models in infinite horizon?

Moreover, I asked the AI specifically about grid interpolation which is my view a bit under the hood in the toolkit and here are the suggestions on improvements of visibility:

Improving Visibility of the Grid Interpolation Layer in the VFI Toolkit

The Grid Interpolation Layer (GI) algorithm used in the VFI Toolkit is documented in a separate repository:

However, the implementation of this algorithm is contained in the VFI Toolkit repository:

This separation creates several discoverability problems for both users and AI systems.

Documentation and implementation are separated

The VFI Toolkit repository contains solver files such as:

ValueFnIter_FHorz_SemiExo_GI.m
ValueFnIter_FHorz_SemiExo_DC_GI.m
ValueFnIter_postGI_nod_raw.m

These clearly implement the Grid Interpolation Layer.

However, the algorithm explanation is located in another repository.

Someone reading the toolkit code therefore sees:

GI solver files
no explanation of the GI algorithm

Unless the user already knows about the separate repository, the algorithm remains unclear.

AI systems struggle with cross-repository explanations

AI models learn primarily from textual corpora.

When algorithm descriptions and implementations are located in separate repositories, the relationship between them is weak.

The current situation is:

Repository A:
GridInterpolationLayer
Algorithm explanation and conceptual description.

Repository B:
VFI Toolkit
Implementation of the algorithm.

This separation weakens the signal that connects the algorithm description to the code.

AI systems learn most effectively when the following appear together:

algorithm description
pseudocode
implementation

Human discoverability problem

A typical user workflow is:

Search for “VFI Toolkit Matlab”
Open the VFI Toolkit repository
Inspect solver files
Notice GI options

However, unless the README or documentation clearly points to the GridInterpolationLayer repository, the user may never discover the algorithm description.

Naming mismatch

Inside the toolkit the algorithm is referred to using the abbreviation:

GI

However, the separate repository is named:

GridInterpolationLayer

Without explicit documentation connecting the two, users may not realize that they refer to the same method.

The GridInterpolationLayer repository contains excellent documentation

The GridInterpolationLayer repository actually contains:

conceptual explanation
algorithm description
pseudocode
motivation

This type of explanatory text is extremely valuable for both humans and AI training.

However, because it is detached from the implementation repository, it is less visible.

Recommended solution: add documentation inside the VFI Toolkit repo

Create a document:

docs/grid_interpolation_layer.txt

or

docs/grid_interpolation_layer.md

This document should briefly explain the GI algorithm and link to the full explanation:

The VFI Toolkit implements the Grid Interpolation Layer (GI) algorithm.

Full description:

This creates a clear connection between the two repositories.

Add references inside solver files

Inside files such as:

ValueFnIter_FHorz_SemiExo_GI.m

add comments such as:

% Grid Interpolation Layer implementation
% Algorithm description available at:
% GitHub - robertdkirkby/GridInterpolationLayer: description of grid interpolation layer algo · GitHub

This makes the algorithm discoverable directly from the code.

Update the main README

Add a section in the README:

Grid Interpolation Layer

The VFI Toolkit optionally uses the Grid Interpolation Layer (GI) algorithm to improve accuracy of value function iteration.

Full algorithm explanation:

Cross-link both repositories

In the VFI Toolkit repository:

Add a reference to the GridInterpolationLayer repository.

In the GridInterpolationLayer repository:

Add a reference indicating that the algorithm is implemented in the VFI Toolkit.

This improves navigation, indexing, and discoverability.

Optional improvement: merge documentation

An even stronger solution is to move the GI explanation directly into the VFI Toolkit documentation:

docs/grid_interpolation_layer.md

and keep the separate repository only for development history.

This would place:

algorithm description
pseudocode
implementation

in the same repository.

Why this matters for AI systems

Large language models learn most effectively when the following are co-located:

algorithm explanation
pseudocode
implementation

Currently these elements are separated across repositories.

Linking them explicitly or merging the documentation would significantly improve both human and AI discoverability.

Summary

The GridInterpolationLayer repository contains excellent algorithm documentation.

However, because it is separate from the VFI Toolkit repository, the connection between the algorithm and its implementation is not obvious.

Improving cross-referencing or merging the documentation would dramatically improve visibility, usability, and AI learnability of the toolkit.