view release on metacpan or  search on metacpan

lib/AI/TensorFlow/Libtensorflow/Tensor.pm  view on Meta::CPAN

=head1 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';

=head1 DESCRIPTION

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

For types other than L<STRING|AI::TensorFlow::Libtensorflow::DataType/STRING>,
the data buffer is stored in L<row major order|https://en.wikipedia.org/wiki/Row-_and_column-major_order>.

Of note, this is different from the definition of I<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

=over 4

Lim, L.-H. (2021). L<Tensors in computations|https://galton.uchicago.edu/~lekheng/work/acta.pdf>.
Acta Numerica, 30, 555–764. Cambridge University Press.
DOI: L<https://doi.org/10.1017/S0962492921000076>.

=back

=head1 CONSTRUCTORS

=head2 New

=over 2

C<<<
New( $dtype, $dims, $data, $deallocator, $deallocator_arg )
>>>

=back

Creates a C<TFTensor> from a data buffer C<$data> with the given specification
of data type C<$dtype> and dimensions C<$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 C<$dtype> is not a
L<STRING|AI::TensorFlow::Libtensorflow::DataType/STRING>
or
L<RESOURCE|AI::TensorFlow::Libtensorflow::DataType/RESOURCE>,
then the pointer for C<$data> is checked to see if meets the
TensorFlow's alignment preferences. If it does not, the
contents of C<$data> are copied into a new buffer and
C<$deallocator> is called during construction.
Otherwise the contents of C<$data> are not owned by the returned
C<TFTensor>.

B<Parameters>

=over 4

=item L<TFDataType|AI::TensorFlow::Libtensorflow::Lib::Types/TFDataType> $dtype

DataType for the C<TFTensor>.

=item L<Dims|AI::TensorFlow::Libtensorflow::Lib::Types/Dims> $dims

An C<ArrayRef> of the size of each dimension.

=item ScalarRef[Bytes] $data

Data buffer for the contents of the C<TFTensor>.

=item CodeRef $deallocator

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

=item Ref $deallocator_arg [optional, default: C<undef>]

Argument that is passed to the C<$deallocator> callback.

=back

B<Returns>

=over 4

=item L<TFTensor|AI::TensorFlow::Libtensorflow::Lib::Types/TFTensor>

A new C<TFTensor> with the given data and specification.

=back

B<C API>: L<< C<TF_NewTensor>|AI::TensorFlow::Libtensorflow::Manual::CAPI/TF_NewTensor >>

=head2 Allocate

=over 2

C<<<
Allocate($dtype, $dims, $len = )
>>>

=back

This constructs a C<TFTensor> with the memory for the C<TFTensor>
allocated and owned by the C<TFTensor> itself. Unlike with L</New>
the allocated memory satisfies TensorFlow's alignment preferences.

See L</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));

B<Parameters>

=over 4

=item L<TFDataType|AI::TensorFlow::Libtensorflow::Lib::Types/TFDataType> $dtype

DataType for the C<TFTensor>.

=item L<Dims|AI::TensorFlow::Libtensorflow::Lib::Types/Dims> $dims

An C<ArrayRef> of the size of each dimension.

=item size_t $len [optional]

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

=back

B<Returns>

lib/AI/TensorFlow/Libtensorflow/Tensor.pm  view on Meta::CPAN

B<C API>: L<< C<TF_NumDims>|AI::TensorFlow::Libtensorflow::Manual::CAPI/TF_NumDims >>

=head2 ElementCount

B<Returns>

=over 4

=item int64_t

Number of elements in the C<TFTensor>.

=back

B<C API>: L<< C<TF_TensorElementCount>|AI::TensorFlow::Libtensorflow::Manual::CAPI/TF_TensorElementCount >>

=head1 METHODS

=head2 Dim

=over 2

C<<<
Dim( $dim_index )
>>>

=back

B<Parameters>

=over 4

=item Int $dim_index

The zero-based index for a given dimension.

=back

B<Returns>

=over 4

=item Int

The extent of the given dimension.

=back

B<C API>: L<< C<TF_Dim>|AI::TensorFlow::Libtensorflow::Manual::CAPI/TF_Dim >>

=head2 MaybeMove

B<Returns>

=over 4

=item Maybe[TFTensor]

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

=back

B<C API>: L<< C<TF_TensorMaybeMove>|AI::TensorFlow::Libtensorflow::Manual::CAPI/TF_TensorMaybeMove >>

=head2 IsAligned

B<C API>: L<< C<TF_TensorIsAligned>|AI::TensorFlow::Libtensorflow::Manual::CAPI/TF_TensorIsAligned >>

=head2 SetShape

=over 2

C<<<
SetShape( $dims )
>>>

=back

Set a new shape for the C<TFTensor>.

B<Parameters>

=over 4

=item L<Dims|AI::TensorFlow::Libtensorflow::Lib::Types/Dims> $dims

=back

B<C API>: L<< C<TF_SetShape>|AI::TensorFlow::Libtensorflow::Manual::CAPI/TF_SetShape >>

C<libtensorflow> version: v2.10.0

=head2 BitcastFrom

B<C API>: L<< C<TF_TensorBitcastFrom>|AI::TensorFlow::Libtensorflow::Manual::CAPI/TF_TensorBitcastFrom >>

=head1 DESTRUCTORS

=head2 DESTROY

Default destructor.

B<C API>: L<< C<TF_DeleteTensor>|AI::TensorFlow::Libtensorflow::Manual::CAPI/TF_DeleteTensor >>

=head1 SEE ALSO

=over 4

=item L<PDL>

Provides ndarrays for access from Perl.

=back

=head1 AUTHOR

Zakariyya Mughal <zmughal@cpan.org>