Class ConversionsHelper

Namespace

AiDotNet.Helpers

Assembly

AiDotNet.dll

Provides utility methods for converting between different data structures used in machine learning models.

public static class ConversionsHelper

Inheritance

object

ConversionsHelper

Inherited Members

object.Equals(object)

object.Equals(object, object)

object.GetHashCode()

object.GetType()

object.MemberwiseClone()

object.ReferenceEquals(object, object)

object.ToString()

Remarks

For Beginners: This helper class contains methods to convert between different mathematical objects used in AI (Tensor, Matrix, Vector). Think of it like a universal adapter that lets different parts of your AI system work together even when they expect different data formats.

For example, if one algorithm outputs a Matrix but another needs a Tensor, these methods help you convert between them without writing complex conversion code yourself.

Methods

ConvertFitFunction<T, TInput, TOutput>(Func<TInput, TOutput>)

Converts a fit function that works with generic types to one that works with Matrix and Vector.

public static Func<Matrix<T>, Vector<T>> ConvertFitFunction<T, TInput, TOutput>(Func<TInput, TOutput> fitFunction)

Parameters

fitFunction Func<TInput, TOutput>

The original fit function that works with TInput and TOutput.

Returns

Func<Matrix<T>, Vector<T>>

A converted function that works with Matrix<T> and Vector<T>.

Type Parameters

T

The numeric type used for calculations (e.g., double, float).

TInput

The type of the input data (must be either Matrix<T> or Tensor<T>).

TOutput

The type of the output data (must be either Vector<T> or Tensor<T>).

Remarks

For Beginners: This method adapts a machine learning function so it can work with different data types.

Think of it like an adapter that lets you plug a device from one country into a power socket in another country. It converts the input data to the format expected by the function, runs the function, and then converts the output back to the format you need.

Exceptions

InvalidOperationException

Thrown when the conversion between types cannot be performed.

ConvertObjectToVector<T>(object?)

Converts a generic object to a Vector.

public static Vector<T>? ConvertObjectToVector<T>(object? obj)

Parameters

obj object

The object to convert, which must be either Vector<T> or Tensor<T>.

Returns

Vector<T>

A Vector<T> representation of the object, or null if the input is null.

Type Parameters

T

The numeric type used for calculations (e.g., double, float).

Remarks

For Beginners: This method is useful when you have an object but don't know its exact type.

It checks if the object is a vector or tensor, and converts it to a vector if possible. This is helpful when working with dynamic data where the type might not be known at compile time.

Exceptions

InvalidOperationException

Thrown when the object cannot be converted to a Vector<T>.

ConvertToMatrix<T, TInput>(TInput)

Converts an input of generic type to a Matrix.

public static Matrix<T> ConvertToMatrix<T, TInput>(TInput input)

Parameters

input TInput

The input data to convert.

Returns

Matrix<T>

A Matrix<T> representation of the input data.

Type Parameters

T

The numeric type used for calculations (e.g., double, float).

TInput

The type of the input data (must be either Matrix<T> or Tensor<T>).

Remarks

For Beginners: This method takes data in one format and converts it to a matrix format. A matrix is like a table of numbers arranged in rows and columns.

If your data is already a matrix, it simply returns it. If it's a tensor (which can have more dimensions), it flattens or reshapes it to fit into a 2D matrix structure.

Exceptions

InvalidOperationException

Thrown when the input cannot be converted to a Matrix<T>.

ConvertToScalar<T, TOutput>(TOutput)

Converts an output value to a scalar value of type T.

public static T ConvertToScalar<T, TOutput>(TOutput output)

Parameters

output TOutput

The output value to convert.

Returns

T

A scalar value of type T extracted from the output.

Type Parameters

T

The numeric type to convert to (e.g., float, double).

TOutput

The type of the output value.

Remarks

For Beginners: This method extracts a single number from more complex data structures. It's like finding the first item in a list or the first cell in a table.

If your data is already a single value, it simply returns it. If it's a vector, it returns the first element. If it's a tensor or matrix, it returns the first element.

Exceptions

InvalidOperationException

Thrown when the output cannot be converted to a scalar value of type T.

ConvertToTensor<T>(object)

Converts a Matrix or Vector to a Tensor.

public static Tensor<T> ConvertToTensor<T>(object input)

Parameters

input object

The input data to convert (Matrix<T> or Vector<T>).

Returns

Tensor<T>

A Tensor<T> representation of the input data.

Type Parameters

T

The numeric type used for calculations (e.g., double, float).

Remarks

For Beginners: This method takes data in matrix or vector format and converts it to a tensor format. A tensor is a multi-dimensional array that can represent matrices (2D), vectors (1D), or higher dimensions.

If your data is a matrix, it creates a 2D tensor. If it's a vector, it creates a 1D tensor. If it's already a tensor, it simply returns it.

Exceptions

InvalidOperationException

Thrown when the input cannot be converted to a Tensor<T>.

ConvertToVector<T, TOutput>(TOutput)

Converts an output of generic type to a Vector.

public static Vector<T> ConvertToVector<T, TOutput>(TOutput output)

Parameters

output TOutput

The output data to convert.

Returns

Vector<T>

A Vector<T> representation of the output data.

Type Parameters

T

The numeric type used for calculations (e.g., double, float).

TOutput

The type of the output data (can be Vector<T>, Tensor<T>, T[], or T scalar).

Remarks

For Beginners: This method takes data in various formats and converts it to a vector format. A vector is essentially a list of numbers arranged in a specific order.

If your data is already a vector, it simply returns it. If it's a tensor (which can have multiple dimensions), it flattens it into a one-dimensional vector. If it's an array, it wraps it in a Vector. For scalar values (single numbers), it creates a 2-element vector for binary classification.

Exceptions

InvalidOperationException

Thrown when the output cannot be converted to a Vector<T>.

ConvertVectorToInputWithoutReference<T, TInput>(Vector<T>)

Converts a Vector to the generic TInput type (Vector, Tensor, Matrix, T[], or scalar T) without requiring a reference input.

public static TInput ConvertVectorToInputWithoutReference<T, TInput>(Vector<T> vector)

Parameters

vector Vector<T>

The vector to convert.

Returns

TInput

The vector converted to TInput type with inferred shape.

Type Parameters

T

The numeric type for calculations.

TInput

The target type (Vector<T>, Tensor<T>, Matrix<T>, T[], or scalar T).

Remarks

For Beginners: This method converts a flat vector to the target type without needing a reference sample. It infers reasonable default shapes based on the target type.

Production Use Case: This is designed for pipeline parallelism and distributed training where intermediate stages receive activation vectors from previous stages and need to convert them to the expected input type without having access to the original input's shape.

Shape Inference Rules:

• For Vector<T>: Returns the vector as-is
• For Tensor<T>: Creates a batch-size-1 tensor with shape [1, vector.Length]
• For Matrix<T>: Creates a row matrix with shape [1, vector.Length]
• For T[]: Converts vector to array
• For scalar T: Returns the first element (for single-output models)

Example Usage:

// Pipeline stage receives 128-element activation vector from previous stage
Vector<double> receivedActivations = GetActivationsFromPreviousStage();

// Convert to Tensor<double> with shape [1, 128] for this stage's model
Tensor<double> stageInput = ConversionsHelper.ConvertVectorToInputWithoutReference<double, Tensor<double>>(receivedActivations);

Exceptions

InvalidOperationException

Thrown when conversion is not supported.

ConvertVectorToInput<T, TInput>(Vector<T>, TInput)

Converts a Vector to the generic TInput type (Vector, Matrix, or Tensor) using a reference input for shape information.

public static TInput ConvertVectorToInput<T, TInput>(Vector<T> vector, TInput referenceInput)

Parameters

vector Vector<T>

The vector to convert.

referenceInput TInput

A reference input providing shape information for Matrix or Tensor conversion.

Returns

TInput

The vector converted to TInput type with the same shape as referenceInput.

Type Parameters

T

The numeric type for calculations.

TInput

The target type (Vector<T>, Matrix<T>, or Tensor<T>).

Remarks

For Beginners: This method converts a flat vector back to its original format (vector, matrix, or tensor) by using a reference sample to determine the correct shape.

Think of it like taking apart LEGO blocks into a line, then using the original picture to rebuild them into the correct structure.

Exceptions

InvalidOperationException

Thrown when conversion is not supported.

GetSampleCount<T, TData>(TData)

Gets the sample count from supported input/output data types.

public static int GetSampleCount<T, TData>(TData data)

Parameters

data TData

The data instance to inspect.

Returns

int

The number of samples in the data.

Type Parameters

T

The numeric type used for calculations.

TData

The data type to inspect.

MatrixToTensor<T>(Matrix<T>, int[])

Converts a matrix to a tensor with the specified shape.

public static Tensor<T> MatrixToTensor<T>(Matrix<T> matrix, int[] shape)

Parameters

matrix Matrix<T>

The matrix to convert.

shape int[]

The shape of the resulting tensor.

Returns

Tensor<T>

A Tensor<T> representation of the matrix with the specified shape.

Type Parameters

T

The numeric type used for calculations (e.g., double, float).

Remarks

For Beginners: This method transforms a 2D matrix into a tensor with a specific shape.

It's like taking a flat sheet of paper (the matrix) and folding it into a 3D structure (the tensor). The amount of data stays the same, but it's organized in a different dimensional structure.

Exceptions

ArgumentException

Thrown when the matrix size doesn't match the product of the shape dimensions.

TensorToMatrix<T>(Tensor<T>, int, int)

Converts a tensor to a matrix with the specified dimensions.

public static Matrix<T> TensorToMatrix<T>(Tensor<T> tensor, int rows, int columns)

Parameters

tensor Tensor<T>

The tensor to convert.

rows int

The number of rows in the resulting matrix.

columns int

The number of columns in the resulting matrix.

Returns

Matrix<T>

A Matrix<T> representation of the tensor with the specified dimensions.

Type Parameters

T

The numeric type used for calculations (e.g., double, float).

Remarks

For Beginners: This method reshapes a tensor into a matrix with specific dimensions.

It's like taking a ball of clay and reshaping it into a rectangular form with a specific number of rows and columns. The total amount of clay (data) remains the same, but its arrangement changes.

Exceptions

ArgumentException

Thrown when the tensor size doesn't match the specified dimensions.

VectorToTensor<T>(Vector<T>, int[])

Converts a vector to a tensor with the specified shape.

public static Tensor<T> VectorToTensor<T>(Vector<T> vector, int[] shape)

Parameters

vector Vector<T>

The vector to convert.

shape int[]

The shape of the resulting tensor.

Returns

Tensor<T>

A Tensor<T> representation of the vector with the specified shape.

Type Parameters

T

The numeric type used for calculations (e.g., double, float).

Remarks

For Beginners: This method transforms a one-dimensional vector into a multi-dimensional tensor.

Imagine taking a long string of beads (the vector) and arranging them into a specific three-dimensional shape. The number of beads stays the same, but they're now organized in a structured multi-dimensional form.

Exceptions

ArgumentException

Thrown when the vector length doesn't match the product of the shape dimensions.