Class DiffusionConvLayer<T>

Namespace

AiDotNet.NeuralNetworks.Layers

Assembly

AiDotNet.dll

Implements diffusion convolution for mesh surface processing using the heat diffusion equation.

public class DiffusionConvLayer<T> : LayerBase<T>, ILayer<T>, IJitCompilable<T>, IDiagnosticsProvider, IWeightLoadable<T>, IDisposable

Type Parameters

T

The numeric type used for calculations, typically float or double.

Inheritance

object

LayerBase<T>

DiffusionConvLayer<T>

Implements

ILayer<T>

IJitCompilable<T>

IDiagnosticsProvider

IWeightLoadable<T>

IDisposable

Inherited Members

LayerBase<T>.Engine

LayerBase<T>.ScalarActivation

LayerBase<T>.VectorActivation

LayerBase<T>.UsingVectorActivation

LayerBase<T>.NumOps

LayerBase<T>.Random

LayerBase<T>.Parameters

LayerBase<T>.ParameterGradients

LayerBase<T>.InputShape

LayerBase<T>.InputShapes

LayerBase<T>.UpdateInputShape(int[])

LayerBase<T>.OutputShape

LayerBase<T>.IsTrainingMode

LayerBase<T>.InitializationStrategy

LayerBase<T>.IsInitialized

LayerBase<T>.InitializationLock

LayerBase<T>.EnsureInitialized()

LayerBase<T>.UseAutodiff

LayerBase<T>.SetTrainingMode(bool)

LayerBase<T>.GetParameterGradients()

LayerBase<T>.ClearGradients()

LayerBase<T>.GetInputShape()

LayerBase<T>.GetInputShapes()

LayerBase<T>.GetOutputShape()

LayerBase<T>.MapActivationToFused()

LayerBase<T>.CanExecuteOnGpu

LayerBase<T>.CanTrainOnGpu

LayerBase<T>.UploadWeightsToGpu()

LayerBase<T>.DownloadWeightsFromGpu()

LayerBase<T>.ZeroGradientsGpu()

LayerBase<T>.GetActivationTypes()

LayerBase<T>.Forward(params Tensor<T>[])

LayerBase<T>.ApplyActivation(Tensor<T>)

LayerBase<T>.ApplyActivation(Vector<T>)

LayerBase<T>.ActivateTensor(IActivationFunction<T>, Tensor<T>)

LayerBase<T>.ActivateTensor(IVectorActivationFunction<T>, Tensor<T>)

LayerBase<T>.CalculateInputShape(int, int, int)

LayerBase<T>.CalculateOutputShape(int, int, int)

LayerBase<T>.DerivativeTensor(IActivationFunction<T>, Tensor<T>)

LayerBase<T>.ApplyActivationDerivative(T, T)

LayerBase<T>.ApplyActivationDerivative(Tensor<T>, Tensor<T>)

LayerBase<T>.ComputeActivationJacobian(Vector<T>)

LayerBase<T>.ApplyActivationDerivative(Vector<T>, Vector<T>)

LayerBase<T>.UpdateParameters(Vector<T>)

LayerBase<T>.GetDiagnostics()

LayerBase<T>.ApplyActivationToGraph(ComputationNode<T>)

LayerBase<T>.CanActivationBeJitted()

LayerBase<T>.RegisterTrainableParameter(Tensor<T>, PersistentTensorRole)

LayerBase<T>.InvalidateTrainableParameter(Tensor<T>)

LayerBase<T>.HasGpuActivation()

LayerBase<T>.ApplyActivationForwardGpu(IDirectGpuBackend, IGpuBuffer, IGpuBuffer, int)

LayerBase<T>.ApplyActivationBackwardGpu(IDirectGpuBackend, IGpuBuffer, IGpuBuffer, IGpuBuffer, IGpuBuffer, int)

LayerBase<T>.GetFusedActivationType()

LayerBase<T>.ApplyGpuActivation(IDirectGpuBackend, IGpuBuffer, IGpuBuffer, int, FusedActivationType)

LayerBase<T>.ApplyGpuActivationBackward(IDirectGpuBackend, IGpuBuffer, IGpuBuffer, IGpuBuffer, IGpuBuffer, int, FusedActivationType, float)

LayerBase<T>.Dispose()

LayerBase<T>.Dispose(bool)

LayerBase<T>.WeightParameterName

LayerBase<T>.BiasParameterName

LayerBase<T>.SetWeights(Tensor<T>)

LayerBase<T>.SetBiases(Tensor<T>)

LayerBase<T>.GetParameterNames()

LayerBase<T>.TryGetParameter(string, out Tensor<T>)

LayerBase<T>.SetParameter(string, Tensor<T>)

LayerBase<T>.GetParameterShape(string)

LayerBase<T>.NamedParameterCount

LayerBase<T>.ValidateWeights(IEnumerable<string>, Func<string, string>)

LayerBase<T>.LoadWeights(Dictionary<string, Tensor<T>>, Func<string, string>, bool)

object.Equals(object)

object.Equals(object, object)

object.GetHashCode()

object.GetType()

object.MemberwiseClone()

object.ReferenceEquals(object, object)

object.ToString()

Remarks

DiffusionConvLayer applies learned diffusion kernels on mesh surfaces to aggregate information across geodesic neighborhoods. Instead of using fixed spatial neighborhoods, it leverages the heat diffusion equation to create adaptive receptive fields that respect the underlying geometry.

For Beginners: Think of heat spreading on a surface:

• Place a heat source at each vertex
• Let the heat diffuse across the mesh surface
• After some time, nearby vertices (in geodesic distance) will share heat
• Use this diffusion pattern to aggregate features from neighbors

Key advantages:

• Respects the true surface geometry (not just mesh connectivity)
• Adaptive receptive field based on diffusion time
• Robust to mesh discretization and vertex density

Applications:

• Shape classification and segmentation
• Surface analysis (curvature, normals, features)
• Correspondence between shapes
• Texture synthesis on surfaces

Reference: "DiffusionNet: Discretization Agnostic Learning on Surfaces" by Sharp et al.

Constructors

DiffusionConvLayer(int, int, int, int, int, IActivationFunction<T>?, bool?)

Initializes a new instance of the DiffusionConvLayer<T> class.

public DiffusionConvLayer(int inputChannels, int outputChannels, int numTimeScales = 4, int numEigenvectors = 128, int numVertices = 1, IActivationFunction<T>? activation = null, bool? preferSpectralDiffusion = null)

Parameters

inputChannels int

Number of input feature channels per vertex.

outputChannels int

Number of output feature channels per vertex.

numTimeScales int

Number of diffusion time scales to use (default: 4).

numEigenvectors int

Number of eigenvectors for spectral acceleration (default: 128).

numVertices int

Expected number of vertices (for shape calculation).

activation IActivationFunction<T>

Activation function to apply. Defaults to ReLU.

preferSpectralDiffusion bool?

Controls CPU execution when eigenbasis is missing. null = automatic (compute), true = always compute, false = use direct Laplacian method.

Exceptions

ArgumentOutOfRangeException

Thrown when parameters are non-positive.

DiffusionConvLayer(int, int, int, int, int, IVectorActivationFunction<T>?, bool?)

Initializes a new instance of the DiffusionConvLayer<T> class with vector activation.

public DiffusionConvLayer(int inputChannels, int outputChannels, int numTimeScales = 4, int numEigenvectors = 128, int numVertices = 1, IVectorActivationFunction<T>? vectorActivation = null, bool? preferSpectralDiffusion = null)

Parameters

inputChannels int

Number of input feature channels per vertex.

outputChannels int

Number of output feature channels per vertex.

numTimeScales int

Number of diffusion time scales to use.

numEigenvectors int

Number of eigenvectors for spectral acceleration.

numVertices int

Expected number of vertices (for shape calculation).

vectorActivation IVectorActivationFunction<T>

Vector activation function to apply.

preferSpectralDiffusion bool?

Controls CPU execution when eigenbasis is missing. null = automatic (compute), true = always compute, false = use direct Laplacian method.

Properties

DiffusionTimes

Gets the learned diffusion time values.

public T[] DiffusionTimes { get; }

Property Value

T[]

Remarks

These are learnable parameters that determine the spatial extent of diffusion. Typically initialized as log-spaced values from small (local) to large (global).

InputChannels

Gets the number of input feature channels per vertex.

public int InputChannels { get; }

Property Value

int

NumTimeScales

Gets the number of diffusion time scales to use.

public int NumTimeScales { get; }

Property Value

int

Remarks

Multiple time scales capture different spatial extents. Small times capture local features while large times capture global structure. Common choices are 4-8 time scales.

OutputChannels

Gets the number of output feature channels per vertex.

public int OutputChannels { get; }

Property Value

int

ParameterCount

Gets the total number of trainable parameters.

public override int ParameterCount { get; }

Property Value

int

SupportsGpuExecution

Gets a value indicating whether this layer supports GPU-accelerated forward pass.

protected override bool SupportsGpuExecution { get; }

Property Value

bool

Remarks

DiffusionConvLayer supports GPU execution for spectral diffusion operations. GPU training is supported when an eigenbasis is available.

SupportsGpuTraining

Gets a value indicating whether this layer supports GPU training.

public override bool SupportsGpuTraining { get; }

Property Value

bool

SupportsJitCompilation

Gets a value indicating whether this layer supports JIT compilation.

public override bool SupportsJitCompilation { get; }

Property Value

bool

SupportsTraining

Gets a value indicating whether this layer supports training.

public override bool SupportsTraining { get; }

Property Value

bool

Methods

Backward(Tensor<T>)

Performs the backward pass to compute gradients.

public override Tensor<T> Backward(Tensor<T> outputGradient)

Parameters

outputGradient Tensor<T>

Returns

Tensor<T>

BackwardGpu(IGpuTensor<T>)

Performs the backward pass using GPU-resident tensors.

public override IGpuTensor<T> BackwardGpu(IGpuTensor<T> outputGradient)

Parameters

outputGradient IGpuTensor<T>

GPU-resident gradient tensor.

Returns

IGpuTensor<T>

GPU-resident input gradient tensor.

Clone()

Creates a deep copy of this layer.

public override LayerBase<T> Clone()

Returns

LayerBase<T>

Deserialize(BinaryReader)

Deserializes the layer from a binary stream.

public override void Deserialize(BinaryReader reader)

Parameters

reader BinaryReader

Binary reader to deserialize from.

Remarks

Restores all learnable parameters and mesh configuration. After deserialization, the layer is ready for inference without needing to call SetEigenbasis or SetLaplacian.

ExportComputationGraph(List<ComputationNode<T>>)

Exports the layer as a computation graph for JIT compilation.

public override ComputationNode<T> ExportComputationGraph(List<ComputationNode<T>> inputNodes)

Parameters

inputNodes List<ComputationNode<T>>

Returns

ComputationNode<T>

Forward(Tensor<T>)

Performs the forward pass of diffusion convolution.

public override Tensor<T> Forward(Tensor<T> input)

Parameters

input Tensor<T>

Vertex features tensor with shape [numVertices, InputChannels] or [batch, numVertices, InputChannels].

Returns

Tensor<T>

Output tensor with shape [numVertices, OutputChannels] or [batch, numVertices, OutputChannels].

Exceptions

InvalidOperationException

Thrown when eigenbasis/laplacian is not set.

ForwardGpu(params IGpuTensor<T>[])

Performs GPU-accelerated forward pass using spectral heat diffusion.

public override IGpuTensor<T> ForwardGpu(params IGpuTensor<T>[] inputs)

Parameters

inputs IGpuTensor<T>[]

Input GPU tensors (uses first input).

Returns

IGpuTensor<T>

GPU-resident output tensor.

Remarks

The spectral diffusion is computed entirely on GPU: 1. Project input to spectral domain: coeffs = Phi^T @ input 2. Apply heat kernel: coeffs = coeffs * exp(-lambda * t) for each time scale 3. Project back: diffused_t = Phi @ coeffs 4. Concatenate all time scales 5. Linear transform: output = diffused @ weights^T + bias 6. Apply activation

If the eigenbasis is missing but a Laplacian is available, it is computed automatically before GPU execution.

GetBiases()

Gets the bias tensor.

public override Tensor<T> GetBiases()

Returns

Tensor<T>

GetParameters()

Gets all trainable parameters as a single vector.

public override Vector<T> GetParameters()

Returns

Vector<T>

GetWeights()

Gets the weight tensor.

public override Tensor<T> GetWeights()

Returns

Tensor<T>

ResetState()

Resets cached state from forward/backward passes.

public override void ResetState()

Serialize(BinaryWriter)

Serializes the layer to a binary stream.

public override void Serialize(BinaryWriter writer)

Parameters

writer BinaryWriter

Binary writer to serialize to.

Remarks

Saves all learnable parameters and mesh configuration including: - Layer configuration (channels, time scales, eigenvector count) - Weights and biases - Diffusion time parameters - Eigenvalues and eigenvectors (if available) - Laplacian and mass matrices (if available)

SetEigenbasis(T[], Tensor<T>, Tensor<T>?)

Sets the Laplacian eigenbasis for the current mesh.

public void SetEigenbasis(T[] eigenvalues, Tensor<T> eigenvectors, Tensor<T>? massMatrix = null)

Parameters

eigenvalues T[]

Eigenvalues of the mesh Laplacian.

eigenvectors Tensor<T>

Eigenvectors of the mesh Laplacian [numVertices, numEigenvalues].

massMatrix Tensor<T>

Vertex area weights (optional).

Remarks

For Beginners: The eigenbasis allows efficient computation of diffusion on the mesh surface. You can precompute this from the mesh Laplacian matrix.

Exceptions

ArgumentNullException

Thrown when required parameters are null.

SetLaplacian(Tensor<T>, Tensor<T>?)

Sets the Laplacian matrix directly for the current mesh.

public void SetLaplacian(Tensor<T> laplacian, Tensor<T>? massMatrix = null)

Parameters

laplacian Tensor<T>

The mesh Laplacian matrix [numVertices, numVertices].

massMatrix Tensor<T>

Vertex area weights (optional).

Remarks

If the eigenbasis is not precomputed, it will be derived from the Laplacian automatically unless the layer is configured to prefer the direct method. Automatic eigenbasis computation ignores the mass matrix; provide an explicit eigenbasis when massMatrix is required.

SetParameters(Vector<T>)

Sets all trainable parameters from a vector.

public override void SetParameters(Vector<T> parameters)

Parameters

parameters Vector<T>

UpdateParameters(T)

Updates layer parameters using computed gradients.

public override void UpdateParameters(T learningRate)

Parameters

learningRate T

Learning rate for gradient descent step.

Remarks

Updates weights, biases, and diffusion time parameters using gradient descent. Diffusion times are constrained to remain positive after update.

UpdateParametersGpu(IGpuOptimizerConfig)

Updates parameters on GPU using the configured optimizer.

public override void UpdateParametersGpu(IGpuOptimizerConfig config)

Parameters

config IGpuOptimizerConfig

The GPU optimizer configuration.