NAME

AI::TensorFlow::Libtensorflow::Tensor - A multi-dimensional array of elements of a single data type

SYNOPSIS

  use aliased 'AI::TensorFlow::Libtensorflow::Tensor' => 'Tensor';
  use AI::TensorFlow::Libtensorflow::DataType qw(FLOAT);
  use List::Util qw(product);

  my $dims = [3, 3];

  # Allocate a 3 by 3 ndarray of type FLOAT
  my $t = Tensor->Allocate(FLOAT, $dims);
  is $t->ByteSize, product(FLOAT->Size, @$dims), 'correct size';

  my $scalar_dims = [];
  my $scalar_t = Tensor->Allocate(FLOAT, $scalar_dims);
  is $scalar_t->ElementCount, 1, 'single element';
  is $scalar_t->ByteSize, FLOAT->Size, 'single FLOAT';

DESCRIPTION

A TFTensor is an object that contains values of a single type arranged in an n-dimensional array.

For types other than STRING, the data buffer is stored in row major order.

Of note, this is different from the definition of tensor used in mathematics and physics which can also be represented as a multi-dimensional array in some cases, but these tensors are defined not by the representation but by how they transform. For more on this see

Lim, L.-H. (2021). Tensors in computations. Acta Numerica, 30, 555–764. Cambridge University Press. DOI: https://doi.org/10.1017/S0962492921000076.

CONSTRUCTORS

New

New( $dtype, $dims, $data, $deallocator, $deallocator_arg )

Creates a TFTensor from a data buffer $data with the given specification of data type $dtype and dimensions $dims.

  # Create a buffer containing 0 through 8 single-precision
  # floating-point data.
  my $data = pack("f*",  0..8);

  $t = Tensor->New(
    FLOAT, [3,3], \$data, sub { undef $data }, undef
  );

  ok $t, 'Created 3-by-3 float TFTensor';

Implementation note: if $dtype is not a STRING or RESOURCE, then the pointer for $data is checked to see if meets the TensorFlow's alignment preferences. If it does not, the contents of $data are copied into a new buffer and $deallocator is called during construction. Otherwise the contents of $data are not owned by the returned TFTensor.

Parameters

TFDataType $dtype

DataType for the TFTensor.

Dims $dims

An ArrayRef of the size of each dimension.

ScalarRef[Bytes] $data

Data buffer for the contents of the TFTensor.

CodeRef $deallocator

A callback used to deallocate $data which is passed the parameters $deallocator->( opaque $pointer, size_t $size, opaque $deallocator_arg).

Ref $deallocator_arg [optional, default: undef]

Argument that is passed to the $deallocator callback.

Returns

TFTensor

A new TFTensor with the given data and specification.

C API: TF_NewTensor

Allocate

Allocate($dtype, $dims, $len = )

This constructs a TFTensor with the memory for the TFTensor allocated and owned by the TFTensor itself. Unlike with "New" the allocated memory satisfies TensorFlow's alignment preferences.

See "Data" for how to write to the data buffer.

  use AI::TensorFlow::Libtensorflow::DataType qw(DOUBLE);

  # Allocate a 2-by-2 ndarray of type DOUBLE
  $dims = [2,2];
  my $t = Tensor->Allocate(DOUBLE, $dims, product(DOUBLE->Size, @$dims));

Parameters

TFDataType $dtype

DataType for the TFTensor.

Dims $dims

An ArrayRef of the size of each dimension.

size_t $len [optional]

Number of bytes for the data buffer. If a value is not given, this is calculated from $dtype and $dims.

Returns

TFTensor

A TFTensor with memory allocated for data buffer.

C API: TF_AllocateTensor

ATTRIBUTES

Data

Provides a way to access the data buffer for the TFTensor. The ScalarRef that it returns is read-only, but the underlying pointer can be accessed as long as one is careful when handling the data (do not write to memory outside the size of the buffer).

  use AI::TensorFlow::Libtensorflow::DataType qw(DOUBLE);
  use FFI::Platypus::Buffer qw(scalar_to_pointer);
  use FFI::Platypus::Memory qw(memcpy);

  my $t = Tensor->Allocate(DOUBLE, [2,2]);

  # [2,2] identity matrix
  my $eye_data = pack 'd*', (1, 0, 0, 1);

  memcpy scalar_to_pointer(${ $t->Data }),
         scalar_to_pointer($eye_data),
         $t->ByteSize;

  ok ${ $t->Data } eq $eye_data, 'contents are the same';

Returns

ScalarRef[Bytes]

Returns a read-only ScalarRef for the TFTensor's data buffer.

C API: TF_TensorData

ByteSize

Returns

size_t

Returns the number of bytes for the TFTensor's data buffer.

C API: TF_TensorByteSize

Type

Returns

TFDataType

The TFTensor's data type.

C API: TF_TensorType

NumDims

Returns

Int

The number of dimensions for the TFTensor.

C API: TF_NumDims

ElementCount

Returns

int64_t

Number of elements in the TFTensor.

C API: TF_TensorElementCount

METHODS

Dim

Dim( $dim_index )

Parameters

Int $dim_index

The zero-based index for a given dimension.

Returns

Int

The extent of the given dimension.

C API: TF_Dim

MaybeMove

Returns

Maybe[TFTensor]

Deletes the TFTensor and returns a new TFTensor with the same content if possible. Returns undef and leaves the TFTensor untouched if not.

C API: TF_TensorMaybeMove

IsAligned

C API: TF_TensorIsAligned

SetShape

SetShape( $dims )

Set a new shape for the TFTensor.

Parameters

Dims $dims

C API: TF_SetShape

libtensorflow version: v2.10.0

BitcastFrom

C API: TF_TensorBitcastFrom

DESTRUCTORS

DESTROY

Default destructor.

C API: TF_DeleteTensor

SEE ALSO

PDL

Provides ndarrays for access from Perl.

AUTHOR

Zakariyya Mughal <zmughal@cpan.org>

COPYRIGHT AND LICENSE

This software is Copyright (c) 2022-2023 by Auto-Parallel Technologies, Inc.

This is free software, licensed under:

  The Apache License, Version 2.0, January 2004

cpanm AI::TensorFlow::Libtensorflow

perl -MCPAN -e shell
install AI::TensorFlow::Libtensorflow