What We Can and Cannot Infer from a GNN Library's Source Code

Reading a library's source code is the most reliable way to understand what
it actually does. But source code has limits as an information source. You can
infer architecture and API; you cannot infer runtime performance or real-world
generalization just by reading. This article maps the boundary between what
source review tells you and what it doesn't.

What Source Code Reliably Tells You

1. Algorithm Implementation

Source code tells you exactly which algorithm is implemented. For TGraphX's
TensorMessagePassingLayer, reading _scatter.py confirms:
- Aggregation uses index_add_ and scatter_reduce_
- There is no Python loop over nodes
- float16 is upcast to float32 before attention softmax

These are facts about implementation, not performance. Knowing which primitive
is used tells you about algorithmic complexity and correctness properties, but
not about wall-clock speed.

2. API Contract

Source code tells you the function signatures, expected arguments, and
return types. For TGraphX's Graph:
- __init__ takes node_features, edge_index, edge_features, node_labels
- Construction validates shapes and devices
- .to(device) moves all tensors

Reading __init__.py tells you exactly what is exported from the public API.
Anything not exported is internal and subject to change without notice.

3. Scope Boundaries

Source code tells you what is explicitly not provided. TGraphX's
distributed.py documents that no distributed training framework is shipped.
The absence of .cu files tells you there are no custom CUDA kernels.
The absence of a sampling module tells you there is no built-in graph sampling.

These absence-based inferences are reliable because they are falsifiable:
if a CUDA kernel existed, there would be a .cu file. If distributed
training were implemented, there would be DDP wrappers.

4. Error Handling

Source code tells you when errors are raised and what information they
contain. Construction-time validation in Graph.__init__ tells you that
shape errors surface at construction. Code that lacks validation tells you
errors will surface later (or not at all).

5. Test Coverage

The test suite tells you which behaviors the developers consider important
enough to test. Well-tested aggregation logic gives you more confidence than
untested code. Missing tests for edge cases suggest those cases haven't been
thought through.

6. Dependencies

pyproject.toml tells you what the library depends on and what versions are
acceptable. For TGraphX, PyTorch is the primary dependency. No C/CUDA
compilation is required. This matters for installation reliability.

Inferrable vs Not-Inferrable Table

What Source Code Cannot Tell You

Runtime Performance

Source code tells you which primitives are used, but not how fast they are
on specific hardware with specific graph sizes. index_add_ is a PyTorch
built-in that runs on GPU — but whether it is fast for your graphs, your batch
sizes, and your GPU depends on measurement, not reading.

Importantly: using a good primitive does not guarantee good performance.
A well-chosen primitive can still be the bottleneck if called with the wrong
shapes, with unnecessary copies, or in a tight loop with overhead elsewhere.

Real-World Generalization

Source code cannot tell you whether a model architecture will generalize to
your data distribution. A layer that is provably expressive in theory may
fail empirically on your specific graphs. This requires empirical evaluation.

Bug Presence in Untested Paths

Source code can tell you which paths are tested. It cannot tell you whether
untested paths are correct. A library with high test coverage for common cases
may have silent bugs in edge cases that tests don't reach.

Documentation Accuracy

Reading the implementation can tell you whether the documentation matches the
code. But documentation is often written separately from code and may drift.
Always prefer the implementation over the documentation when they conflict,
and treat discrepancies as bugs worth reporting.

How to Use Source Review Honestly

When writing about a library from source:

1. Mark the source — "confirmed by reading _scatter.py" is more
   credible than "the library uses scatter operations"

2. Distinguish what you read from what you infer — "the code uses
   index_add_; therefore there is no Python loop per node" is an inference
   (correct, but labeled as such)

3. Do not infer performance from primitives — "uses scatter_reduce_ for
   aggregation" does not imply "is fast"

4. Note what you did not read — "I did not read the benchmarks module;
   the claims about OGBNodeEvaluator are from docstrings only"

This discipline produces documentation that readers can trust and verify —
which is more valuable than documentation that sounds authoritative but can
be contradicted by anyone willing to read the source.

Applying This to TGraphX

For TGraphX specifically, source review supports these claims:
- No Python loops per node in message passing ✓ (from _scatter.py)
- float16 upcast to float32 in attention ✓ (from _scatter.py)
- No distributed training ✓ (from distributed.py docstring)
- Construction-time validation ✓ (from Graph.init)
- Exported APIs ✓ (from init.py)

Source review does not support claims about:
- Speed compared to other libraries
- Performance on specific graph sizes
- Whether the library is suitable for any specific research task
- Absence of bugs in untested code

This is a precise, honest position. The value of that precision is that it
can be defended to any reader willing to check the source themselves.