feat: rename all data structure fields and function args for clarity

Rename ~68 fields across all 8 data structures (ModelLog, LayerPassLog,
LayerLog, ParamLog, ModuleLog, BufferLog, ModulePassLog, FuncCallLocation)
plus user-facing function arguments. Key changes:

- tensor_contents → activation, grad_contents → gradient
- All *_fsize* → *_memory* (e.g. tensor_fsize → tensor_memory)
- func_applied_name → func_name, gradfunc → grad_fn_name
- is_bottom_level_submodule_output → is_leaf_module_output
- containing_module_origin → containing_module
- spouse_layers → co_parent_layers, orig_ancestors → root_ancestors
- model_is_recurrent → is_recurrent, elapsed_time_* → time_*
- vis_opt → vis_mode, save_only → vis_save_only
- Fix typo: output_descendents → output_descendants

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

Author: johnmarktaylor91

README.md

@@ -37,8 +37,8 @@ class SimpleRecurrent(nn.Module):
 simple_recurrent = SimpleRecurrent()
 model_history = tl.log_forward_pass(simple_recurrent, x,
                                     layers_to_save='all',
-                                    vis_opt='rolled')
-print(model_history['linear_1_1:2'].tensor_contents)  # second pass of first linear layer
+                                    vis_mode='rolled')
+print(model_history['linear_1_1:2'].activation)  # second pass of first linear layer
 
 '''
 tensor([[-0.0690, -1.3957, -0.3231, -0.1980,  0.7197],
@@ -88,7 +88,7 @@ import torchlens as tl
 
 alexnet = torchvision.models.alexnet()
 x = torch.rand(1, 3, 224, 224)
-model_history = tl.log_forward_pass(alexnet, x, layers_to_save='all', vis_opt='unrolled')
+model_history = tl.log_forward_pass(alexnet, x, layers_to_save='all', vis_mode='unrolled')
 print(model_history)
 
 '''
@@ -166,16 +166,16 @@ Layer conv2d_3_7, operation 8/24:
 	Params: Computed from params with shape (384,), (384, 192, 3, 3); 663936 params total (2.5 MB)
 	Parent Layers: maxpool2d_2_6
 	Child Layers: relu_3_8
-	Function: conv2d (gradfunc=ConvolutionBackward0)
+	Function: conv2d (grad_fn=ConvolutionBackward0)
 	Computed inside module: features.6
 	Time elapsed:  5.670E-04s
 	Output of modules: features.6
 	Output of bottom-level module: features.6
 	Lookup keys: -17, 7, conv2d_3_7, conv2d_3_7:1, features.6, features.6:1
 '''
 
-# You can pull out the actual output activations from a layer with the tensor_contents field:
-print(model_history['conv2d_3_7'].tensor_contents)
+# You can pull out the actual output activations from a layer with the activation field:
+print(model_history['conv2d_3_7'].activation)
 '''
 tensor([[[[-0.0867, -0.0787, -0.0817,  ..., -0.0820, -0.0655, -0.0195],
           [-0.1213, -0.1130, -0.1386,  ..., -0.1331, -0.1118, -0.0520],
@@ -194,7 +194,7 @@ will pull out all conv layers):
 
 ```python
 # Pull out conv2d_3_7, the output of the 'features' module, the fifth-to-last layer, and all linear (i.e., fc) layers:
-model_history = tl.log_forward_pass(alexnet, x, vis_opt='unrolled',
+model_history = tl.log_forward_pass(alexnet, x, vis_mode='unrolled',
                                     layers_to_save=['conv2d_3_7', 'features', -5, 'linear'])
 print(model_history.layer_labels)
 '''

scripts/render_large_graph.py

@@ -55,9 +55,9 @@ def main():
 
     # Render from ModelLog metadata (model tensors no longer in memory).
     ml.render_graph(
-        vis_opt="rolled",
+        vis_mode="rolled",
         vis_outpath=os.path.join(args.outdir, label),
-        save_only=True,
+        vis_save_only=True,
         vis_fileformat=args.format,
         vis_node_placement="elk",
     )

tests/CLAUDE.md

@@ -64,7 +64,7 @@ def test_model_descriptive_name(default_input1):
     model = example_models.MyNewModel()
     assert validate_saved_activations(model, default_input1)
     show_model_graph(
-        model, default_input1, save_only=True, vis_opt="unrolled",
+        model, default_input1, vis_save_only=True, vis_mode="unrolled",
         vis_outpath=opj(VIS_OUTPUT_DIR, "toy-networks", "my_new_model"),
     )
 ```

tests/example_models.py

@@ -1740,7 +1740,7 @@ def forward(self, x, c, t, context_mask):
 
 class ViewMutationUnsqueeze(nn.Module):
     """Mutation through unsqueeze view: y = x.unsqueeze(0); y.fill_(0); return x.
-    The fill_ mutates x's storage through the view, so x's tensor_contents at
+    The fill_ mutates x's storage through the view, so x's activation at
     logging time differs from what children actually receive."""
 
     def __init__(self):

tests/test_gc.py

@@ -174,7 +174,7 @@ def test_release_param_refs_preserves_grad_metadata(self):
                 has_any_grad = True
                 assert pl._grad_shape is not None
                 assert pl._grad_dtype is not None
-                assert pl._grad_fsize > 0
+                assert pl._grad_memory > 0
         assert has_any_grad, "Expected at least one param to have grad metadata cached"
         model_log.cleanup()
 

tests/test_internals.py

@@ -463,14 +463,14 @@ def test_cleanup_no_crash(self):
 
 class TestNestedTupleArgs:
     def test_nested_tuple_independence(self):
-        """Nested tuples/lists in creation_args should be independent copies."""
+        """Nested tuples/lists in captured_args should be independent copies."""
         model = _SimpleLinear()
         x = torch.randn(2, 10)
         log = log_forward_pass(model, x, save_function_args=True)
         found_args = False
         for label in log.layer_labels:
             entry = log[label]
-            if entry.creation_args is not None and len(entry.creation_args) > 0:
+            if entry.captured_args is not None and len(entry.captured_args) > 0:
                 found_args = True
                 break
         assert found_args or True  # OK if no args (model-dependent)
@@ -495,5 +495,5 @@ def test_shape_matches_capture_time(self):
         log = log_forward_pass(model, x, layers_to_save="all")
         for label in log.layer_labels:
             entry = log[label]
-            if entry.tensor_contents is not None:
+            if entry.activation is not None:
                 assert entry.tensor_shape is not None

tests/test_large_graphs.py

@@ -127,9 +127,7 @@ def test_nesting_depth(self):
         """Module nesting creates expected hierarchy."""
         model = RandomGraphModel(target_nodes=500, nesting_depth=4, seed=42)
         ml = log_forward_pass(model, torch.randn(2, 64))
-        max_depth = max(
-            len(ml[label].containing_modules_origin_nested) for label in ml.layer_labels
-        )
+        max_depth = max(len(ml[label].containing_modules) for label in ml.layer_labels)
         assert max_depth >= 3
         ml.cleanup()
 
@@ -325,7 +323,7 @@ def test_dot_renders_small_graph(self):
             model,
             torch.randn(2, 64),
             vis_node_placement="dot",
-            save_only=True,
+            vis_save_only=True,
             vis_outpath=os.path.join(VIS_OUTPUT_DIR, "dot_200"),
         )
 
@@ -337,7 +335,7 @@ def test_sfdp_renders_large_graph(self):
             model,
             torch.randn(2, 64),
             vis_node_placement="sfdp",
-            save_only=True,
+            vis_save_only=True,
             vis_outpath=os.path.join(VIS_OUTPUT_DIR, "sfdp_3k"),
         )
 
@@ -350,7 +348,7 @@ def test_elk_renders_3k(self):
             model,
             torch.randn(2, 64),
             vis_node_placement="elk",
-            save_only=True,
+            vis_save_only=True,
             vis_outpath=os.path.join(VIS_OUTPUT_DIR, "elk_3k"),
         )
 
@@ -363,7 +361,7 @@ def test_elk_renders_5k(self):
             model,
             torch.randn(2, 64),
             vis_node_placement="elk",
-            save_only=True,
+            vis_save_only=True,
             vis_outpath=os.path.join(VIS_OUTPUT_DIR, "elk_5k"),
         )
 
@@ -376,7 +374,7 @@ def test_elk_renders_10k(self):
             model,
             torch.randn(2, 64),
             vis_node_placement="elk",
-            save_only=True,
+            vis_save_only=True,
             vis_outpath=os.path.join(VIS_OUTPUT_DIR, "elk_10k"),
         )
 
@@ -389,7 +387,7 @@ def test_elk_renders_20k(self):
             model,
             torch.randn(2, 64),
             vis_node_placement="elk",
-            save_only=True,
+            vis_save_only=True,
             vis_outpath=os.path.join(VIS_OUTPUT_DIR, "elk_20k"),
         )
 
@@ -402,7 +400,7 @@ def test_elk_renders_50k(self):
             model,
             torch.randn(2, 64),
             vis_node_placement="elk",
-            save_only=True,
+            vis_save_only=True,
             vis_outpath=os.path.join(VIS_OUTPUT_DIR, "elk_50k"),
         )
 
@@ -416,7 +414,7 @@ def test_elk_renders_100k(self):
             model,
             torch.randn(2, 64),
             vis_node_placement="elk",
-            save_only=True,
+            vis_save_only=True,
             vis_outpath=os.path.join(VIS_OUTPUT_DIR, "elk_100k"),
         )
 
@@ -430,7 +428,7 @@ def test_elk_renders_250k(self):
             torch.randn(2, 64),
             vis_node_placement="elk",
             vis_fileformat="svg",
-            save_only=True,
+            vis_save_only=True,
             vis_outpath=os.path.join(VIS_OUTPUT_DIR, "elk_250k"),
         )
 
@@ -444,7 +442,7 @@ def test_elk_renders_1M(self):
             torch.randn(2, 64),
             vis_node_placement="elk",
             vis_fileformat="svg",
-            save_only=True,
+            vis_save_only=True,
             vis_outpath=os.path.join(VIS_OUTPUT_DIR, "elk_1M"),
         )
 
@@ -453,8 +451,8 @@ def test_vis_node_placement_forwarded(self):
         model = RandomGraphModel(target_nodes=200, seed=42)
         ml = log_forward_pass(model, torch.randn(2, 64))
         ml.render_graph(
-            vis_opt="unrolled",
-            save_only=True,
+            vis_mode="unrolled",
+            vis_save_only=True,
             vis_outpath=os.path.join(VIS_OUTPUT_DIR, "placement_test"),
             vis_node_placement="dot",
         )
@@ -485,17 +483,17 @@ def _render_both(self, model, x, name):
         show_model_graph(
             model,
             x,
-            save_only=True,
-            vis_opt="unrolled",
+            vis_save_only=True,
+            vis_mode="unrolled",
             vis_node_placement="dot",
             vis_outpath=os.path.join(self.COMPARE_DIR, f"{name}_dot"),
         )
         # ELK
         show_model_graph(
             model,
             x,
-            save_only=True,
-            vis_opt="unrolled",
+            vis_save_only=True,
+            vis_mode="unrolled",
             vis_node_placement="elk",
             vis_outpath=os.path.join(self.COMPARE_DIR, f"{name}_elk"),
         )
@@ -553,8 +551,8 @@ def test_benchmark_dot_scaling(self):
             start = time.time()
             try:
                 ml.render_graph(
-                    vis_opt="unrolled",
-                    save_only=True,
+                    vis_mode="unrolled",
+                    vis_save_only=True,
                     vis_outpath=os.path.join(VIS_OUTPUT_DIR, f"bench_{target}"),
                     vis_node_placement="dot",
                 )

tests/test_layer_log.py

@@ -83,10 +83,10 @@ def test_back_reference_set(self, simple_log):
 class TestSinglePassDelegation:
     @pytest.mark.smoke
     def test_tensor_contents_delegation(self, simple_log):
-        """tensor_contents delegates to passes[1] for single-pass."""
+        """activation delegates to passes[1] for single-pass."""
         for layer_log in simple_log.layer_logs.values():
             pass_log = layer_log.passes[1]
-            assert layer_log.tensor_contents is pass_log.tensor_contents
+            assert layer_log.activation is pass_log.activation
 
     def test_has_saved_activations_delegation(self, simple_log):
         for layer_log in simple_log.layer_logs.values():
@@ -121,12 +121,12 @@ def test_aggregate_fields_match_first_pass(self, simple_log):
         for layer_log in simple_log.layer_logs.values():
             fp = layer_log.passes[1]
             assert layer_log.layer_type == fp.layer_type
-            assert layer_log.func_applied_name == fp.func_applied_name
+            assert layer_log.func_name == fp.func_name
             assert layer_log.tensor_shape == fp.tensor_shape
             assert layer_log.tensor_dtype == fp.tensor_dtype
             assert layer_log.is_input_layer == fp.is_input_layer
             assert layer_log.is_output_layer == fp.is_output_layer
-            assert layer_log.computed_with_params == fp.computed_with_params
+            assert layer_log.uses_params == fp.uses_params
 
     def test_layer_label_is_no_pass(self, simple_log):
         for layer_log in simple_log.layer_logs.values():
@@ -155,7 +155,7 @@ def test_multi_pass_tensor_contents_raises(self, recurrent_log):
         for layer_log in recurrent_log.layer_logs.values():
             if layer_log.num_passes > 1:
                 with pytest.raises(ValueError, match="has .* passes"):
-                    _ = layer_log.tensor_contents
+                    _ = layer_log.activation
                 break
 
     def test_multi_pass_getattr_raises(self, recurrent_log):
@@ -234,17 +234,13 @@ def test_repr_eq_str(self, simple_log):
 
 
 class TestConvenienceAliases:
-    def test_layer_passes_total_alias(self, simple_log):
-        for layer_log in simple_log.layer_logs.values():
-            assert layer_log.layer_passes_total == layer_log.num_passes
-
     def test_layer_label_no_pass_alias(self, simple_log):
         for layer_log in simple_log.layer_logs.values():
             assert layer_log.layer_label_no_pass == layer_log.layer_label
 
     def test_params_accessor(self, recurrent_log):
         for layer_log in recurrent_log.layer_logs.values():
-            if layer_log.computed_with_params:
+            if layer_log.uses_params:
                 params = layer_log.params
                 assert params is not None
                 break