1 vin.diagnostics

vin.diagnostics

Diagnostics, summaries, and Plotly visualizations for VIN models.

This package owns the stable app-facing exports for encoding figures and the VIN-Core batch/model summary while implementation helpers remain in leaf modules.

1.1 Classes

Name	Description
CaptureLimits	Positive quotas for one ModelCapture instance.
ConfigFieldSpec	One field observed in a construction-free configuration walk.
ModelCapture	Capture bounded tensors from registered module instances.
ModelMetadata	Registered-module metadata for an already constructed model.
ModelStructureSpec	Construction-free description of one model configuration tree.
ModuleMetadata	Static metadata for one registered module in a constructed model.
TensorSnapshot	Complete source metadata plus a detached, bounded tensor value sample.

1.1.1 CaptureLimits

vin.diagnostics.CaptureLimits(
    max_tensors=64,
    max_samples_per_tensor=32,
    max_bytes=16 * 1024,
    max_traversal_nodes=4096,
    max_container_depth=32,
)

Positive quotas for one ModelCapture instance.

Tensor-count and byte quotas are cumulative across every call and context entrance made with the instance. Traversal quotas restart for each module invocation’s combined positional/keyword inputs and separately for its output. These limits bound inspected nodes and copied numeric payload; they do not bound the source model, source tensors, hook metadata, Python record overhead, or total process/device memory.

1.1.1.1 Attributes

Name	Description
max_tensors	Maximum tensor snapshots retained across the capture instance.
max_samples_per_tensor	Maximum row-major flattened elements copied from one source tensor.
max_bytes	Maximum source-dtype bytes copied into samples across the instance.
max_traversal_nodes	Maximum containers, leaves, and tensors visited in one input or output walk.
max_container_depth	Maximum container edges followed from an input or output root.

1.1.2 ConfigFieldSpec

vin.diagnostics.ConfigFieldSpec(path, declared_type, configured_type, value)

One field observed in a construction-free configuration walk.

1.1.2.1 Attributes

Name	Description
path	Field-name path from the root; sequence positions are decimal strings.
declared_type	Human-readable annotation declared by the field’s Pydantic model.
configured_type	Fully qualified runtime type of the currently configured value.
value	Scalar or enum value; other values use a qualified type marker.

1.1.3 ModelCapture

vin.diagnostics.ModelCapture(model, *, module_paths=None, limits=None)

Capture bounded tensors from registered module instances.

Enter the context, run the model through its ordinary caller-owned forward, and inspect :attr:snapshots after exit. Hooks never alter module outputs and are removed on both successful and exceptional exits. Inputs are sampled by an instance pre-hook before forward can mutate them. At context entry, the sampling hook follows existing instance pre-hooks and observes their transformations. Hooks added while capture is active may use PyTorch’s prepend ordering and run on either side. Shared limits may truncate either side of an invocation, so snapshots are a bounded trace rather than guaranteed input/output pairs. An exceptional forward has no output sample; leaving the context still removes every hook, and :meth:close provides the same idempotent cleanup for manual use.

max_tensors and max_bytes bound retained output records and copied numeric payload across the capture instance. max_samples_per_tensor bounds each value tuple. max_traversal_nodes and max_container_depth bound each structured input or output walk. They do not impose a total-memory limit; the source model and tensors remain owned by the caller and metadata/record overhead is additional.

1.1.3.1 Parameters

Name	Type	Description	Default
model	nn.Module	Constructed model that owns the registered modules to observe.	required
module_paths	Sequence[str] | None	Exact registered paths to capture, or None for all paths in named_modules order, including "<root>".	None
limits	CaptureLimits | None	Positive quotas, or None for CaptureLimits defaults.	None

1.1.3.2 Attributes

Name	Description
snapshots	Return a tuple of detached snapshots captured so far.
sampled_bytes	Return cumulative source-dtype bytes represented by sampled values.
active	Report whether instance hooks are currently registered.

1.1.3.3 Methods

Name	Description
close	Remove this capture’s hooks and pending calls; repeated calls are safe.

1.1.3.3.1 close

vin.diagnostics.ModelCapture.close()

Remove this capture’s hooks and pending calls; repeated calls are safe.

1.1.4 ModelMetadata

vin.diagnostics.ModelMetadata(
    model_type,
    total_parameters,
    trainable_parameters,
    modules,
)

Registered-module metadata for an already constructed model.

1.1.4.1 Attributes

Name	Description
model_type	Fully qualified runtime type of the inspected model.
total_parameters	Elements in all initialized parameters reachable from the model.
trainable_parameters	Elements in all initialized, gradient-enabled reachable parameters.
modules	Unique registered modules in traversal order, including the root.

1.1.5 ModelStructureSpec

vin.diagnostics.ModelStructureSpec(config_type, target_type, fields)

Construction-free description of one model configuration tree.

Repeated inspection of an unchanged configuration returns equal frozen records. Each call creates a new record and never calls setup_target.

1.1.5.1 Attributes

Name	Description
config_type	Fully qualified type of the inspected root Pydantic model.
target_type	Fully qualified root target_type, or None when absent.
fields	Depth-first field records in declaration and sequence-index order.

1.1.6 ModuleMetadata

vin.diagnostics.ModuleMetadata(
    path,
    module_type,
    direct_parameters,
    trainable_parameters,
    direct_buffers,
    training,
)

Static metadata for one registered module in a constructed model.

1.1.6.1 Attributes

Name	Description
path	Registration path from the model root, represented as "<root>" at the root.
module_type	Fully qualified runtime type of the registered module instance.
direct_parameters	Elements in initialized parameters registered directly on this module.
trainable_parameters	Elements in initialized, gradient-enabled parameters directly on this module.
direct_buffers	Elements in initialized buffers registered directly on this module.
training	The module’s training flag at inspection time.

1.1.7 TensorSnapshot

vin.diagnostics.TensorSnapshot(
    module_path,
    call_index,
    direction,
    tensor_path,
    shape,
    dtype,
    device,
    numel,
    sampled_bytes,
    values,
    sample_omission_reason=None,
)

Complete source metadata plus a detached, bounded tensor value sample.

Empty tensors retain their shape with an empty value sample and zero bytes. Complex, meta-device, non-strided-layout and quantized tensors are metadata-only: their values are not indexed, copied, densified or cast. sample_omission_reason distinguishes these from empty source tensors. Records remain compatible with standard dataclass serialization.

Metadata describes the full tensor at hook time. Only values is truncated: it is a row-major prefix copied to CPU and converted to immutable Python scalars, so the snapshot neither aliases source storage nor retains its autograd graph.

1.1.7.1 Attributes

Name	Description
module_path	Registered module path, using "<root>" for the model root.
call_index	Zero-based invocation index for module_path in this capture instance.
direction	Hook side observed; input and output from one call share an index.
tensor_path	Container path from args/kwargs or the output root.
shape	Complete source-tensor shape at observation time.
dtype	String form of the source-tensor dtype at observation time.
device	String form of the source device before the bounded CPU copy.
numel	Total number of elements in the full source tensor.
sampled_bytes	Source-dtype bytes represented by values in this snapshot.
values	Detached CPU scalar prefix bounded by per-tensor and shared quotas.
sample_omission_reason	Why numeric sampling is unsupported; None for supported/empty sources.

1.2 Functions

Name	Description
build_alignment_figures	Plot alignment histograms between candidates and voxel frame.
build_candidate_encoding_figures	Build Plotly figures for actual candidate encodings.
build_field_token_histograms	Overlay histograms of field values and sampled token values.
build_frustum_samples_figure	Plot frustum sample points colored by token validity (world frame).
build_prediction_alignment_figure	Scatter of predicted score vs view alignment.
build_vin_encoding_figures	Build Plotly figures from VIN forward diagnostics.
capture_model	Create an opt-in bounded capture context for one constructed model.
inspect_config	Describe a Pydantic configuration tree without constructing its target.
inspect_model	Describe registered PyTorch state without running a forward pass.
plot_vin_encodings_from_debug	Generate VIN encoding plots using Plotly and persist them as HTML.
summarize_vin_v3	Build a human-readable VIN-Core report for one oracle-labelled batch.

1.2.1 build_alignment_figures

vin.diagnostics.build_alignment_figures(debug, *, log1p_counts=False)

Plot alignment histograms between candidates and voxel frame.

1.2.2 build_candidate_encoding_figures

vin.diagnostics.build_candidate_encoding_figures(
    debug,
    *,
    lmax,
    sh_normalization,
    radius_freqs,
    pose_encoder_lff=None,
    include_legacy_sh=True,
    max_candidates=512,
    max_sh_components=64,
    max_pose_dims=128,
)

Build Plotly figures for actual candidate encodings.

1.2.3 build_field_token_histograms

vin.diagnostics.build_field_token_histograms(
    debug,
    *,
    channel_names,
    max_channels=4,
    max_samples=200000,
    log1p_counts=False,
)

Overlay histograms of field values and sampled token values.

1.2.4 build_frustum_samples_figure

vin.diagnostics.build_frustum_samples_figure(
    debug,
    *,
    p3d_cameras,
    candidate_index,
    grid_size,
    depths_m,
)

Plot frustum sample points colored by token validity (world frame).

1.2.5 build_prediction_alignment_figure

vin.diagnostics.build_prediction_alignment_figure(debug, *, expected_normalized)

Scatter of predicted score vs view alignment.

1.2.6 build_vin_encoding_figures

vin.diagnostics.build_vin_encoding_figures(
    debug,
    *,
    lmax,
    sh_normalization,
    radius_freqs,
    pose_encoder_lff=None,
    include_legacy_sh=True,
    log1p_counts=False,
)

Build Plotly figures from VIN forward diagnostics.

1.2.7 capture_model

vin.diagnostics.capture_model(model, *, module_paths=None, limits=None)

Create an opt-in bounded capture context for one constructed model.

Dense strided real, integer and boolean tensors supply bounded scalar samples. Complex, meta, non-strided and quantized tensors supply metadata only, with a reason in TensorSnapshot; no conversion is attempted. All snapshots consume the shared record quota, including metadata-only and empty sources. Once byte or traversal quotas exhaust capture stops.

1.2.7.1 Parameters

Name	Type	Description	Default
model	nn.Module	Constructed module whose registered instances may be observed.	required
module_paths	Sequence[str] | None	Exact named_modules paths to hook. None selects every registered module, including "<root>". Unknown paths are rejected when the context is entered.	None
limits	CaptureLimits | None	Positive traversal and sample quotas. Defaults to CaptureLimits.	None

1.2.7.2 Returns

Name	Type	Description
	ModelCapture	Reusable context manager. Each entrance registers instance hooks; exit
	ModelCapture	removes them even when the caller’s forward raises. Snapshots, byte
	ModelCapture	accounting, and per-module call indices remain cumulative if the same
	ModelCapture	context object is entered again.

1.2.8 inspect_config

vin.diagnostics.inspect_config(config)

Describe a Pydantic configuration tree without constructing its target.

The walk records every root field, then descends depth-first into nested Pydantic models and Pydantic models held directly in sequences. Mappings, ordinary dataclasses, and arbitrary structured values are represented by their configured type and are not traversed.

1.2.8.1 Parameters

Name	Type	Description	Default
config	BaseModel	Root Pydantic configuration. Inspection reads current field values and target_type but never calls setup_target.	required

1.2.8.2 Returns

Name	Type	Description
	ModelStructureSpec	Frozen structure metadata ordered by Pydantic field declaration and
	ModelStructureSpec	sequence index. An unchanged configuration produces equal records on
	ModelStructureSpec	repeated calls.

1.2.9 inspect_model

vin.diagnostics.inspect_model(model)

Describe registered PyTorch state without running a forward pass.

1.2.9.1 Parameters

Name	Type	Description	Default
model	nn.Module	Already constructed module. Inspection does not change training mode, initialize lazy state, move devices, or execute hooks.	required

1.2.9.2 Returns

Name	Type	Description
	ModelMetadata	Frozen metadata in named_modules registration order. Model totals
	ModelMetadata	cover recursively reachable parameters, while each module record counts
	ModelMetadata	only state registered directly on that module. Uninitialized lazy
	ModelMetadata	parameters and buffers contribute zero elements; already initialized
	ModelMetadata	state on the same lazy module is still counted.

1.2.10 plot_vin_encodings_from_debug

vin.diagnostics.plot_vin_encodings_from_debug(
    debug,
    *,
    out_dir,
    lmax,
    sh_normalization,
    radius_freqs,
    file_stem_prefix,
    pose_encoder_lff=None,
    include_legacy_sh=True,
)

Generate VIN encoding plots using Plotly and persist them as HTML.

1.2.10.1 Parameters

Name	Type	Description	Default
debug	VinForwardDiagnostics	Diagnostics from VinModel.forward_with_debug.	required
out_dir	Path	Output directory for saved figures.	required
lmax	int	Maximum SH degree to visualize (legacy plots only).	required
sh_normalization	str	Spherical harmonics normalization mode (legacy plots only).	required
radius_freqs	Iterable[float]	Frequencies for the legacy radius Fourier feature plot.	required
file_stem_prefix	str	Prefix used for output filenames.	required
pose_encoder_lff	LearnableFourierFeatures | None	Optional LFF encoder used for weight visualizations.	None
include_legacy_sh	bool	Whether to include legacy SH/Fourier plots.	True

1.2.10.2 Returns

Name	Type	Description
	dict[str, Path]	Mapping of figure labels to saved HTML paths.

1.2.11 summarize_vin_v3

vin.diagnostics.summarize_vin_v3(
    self,
    batch,
    *,
    include_torchsummary=True,
    torchsummary_depth=3,
)

Build a human-readable VIN-Core report for one oracle-labelled batch.

The summary runs a debug forward pass from the batch’s snippet view and cached actor-visible EVL evidence, then reports tensor shapes/statistics, candidate validity diagnostics, CORAL monotonicity, and optional comparison with oracle labels. Oracle values are used only in the report; they are not passed into the scorer. Correlation is labelled as a pooled candidate association over valid-prefix, candidate-valid, jointly finite pairs; it is not a within-state ranking estimate.

1.2.11.1 Parameters

Name	Type	Description	Default
self	VinModelV3	VIN-Core scorer to inspect.	required
batch	VinOracleBatch	Batch carrying candidates, camera rows, cached evidence, and optional oracle supervision.	required
include_torchsummary	bool	Include a parameter/module summary when True.	True
torchsummary_depth	int	Maximum nested module depth for that summary.	3

1.2.11.2 Returns

Name	Type	Description
	str	Rendered multiline diagnostic report. The scorer’s original training
	str	mode is restored before returning.

1.2.11.3 Raises

Name	Type	Description
	ValueError	If the oracle batch has a malformed candidate-count or candidate-pose contract. Internal mask construction errors are not converted into an unavailable correlation.