Why Use ΦML's Tensors¶

Colab   •   🌐 ΦML   •   📖 Documentation   •   🔗 API   •   ▶ Videos   •   Examples

While you can call many ΦML function directly with native tensors, such as Jax tensors or NumPy arrays, we recommend wrapping them in ΦML tensors. These provide several benefits over the native tensors and allow you to write easy-to-read, more concise, more explicit, less error-prone code.

For an introduction into tensors and dimensions, check out the introduction notebook.

This notebook is work in progress. It will explain

  • Comparisons to native libraries.
  • show easy-to-read, more concise, more explicit, less error-prone code
In [1]:
%%capture
!pip install phiml

Named Dimensions¶

All tensor dimensions in ΦML are required to have a name and type. These properties are part of the tensor shape. When creating a ΦML tensor, you need to specify the names and types of all dimensions.

In [2]:
from phiml import math
from phiml.math import channel, batch, spatial, instance, dual  # dimension types

math.wrap([0, 1, 2], channel('integers'))
Out[2]:
(0, 1, 2) along integersᶜ int64
In [3]:
data = math.random_uniform(batch(examples=2), spatial(x=4, y=3))
data
Out[3]:
(examplesᵇ=2, xˢ=4, yˢ=3) 0.390 ± 0.273 (9e-03...9e-01)

Printing Options¶

As you can see, ΦML summarizes tensors by default and color-codes the result text. The Python formatting options let you customize how a tensor is printed, with options being separated by colons. Here are some examples:

In [4]:
print(f"{data:summary:color:shape:dtype:.5e}")

(examplesᵇ=2, xˢ=4, yˢ=3) float32 3.90150e-01 ± 2.73051e-01 (8.91884e-03...9.42276e-01)
In [5]:
print(f"{data:full:color:shape:dtype:.3f}")

examples=0  
 0.942, 0.475, 0.406, 0.879,
 0.137, 0.038, 0.268, 0.812,
 0.161, 0.598, 0.031, 0.080  along (xˢ=4, yˢ=3)
examples=1  
 0.346, 0.457, 0.645, 0.202,
 0.661, 0.386, 0.578, 0.513,
 0.251, 0.464, 0.009, 0.023  along (xˢ=4, yˢ=3)
In [6]:
print(f"{data:numpy:no-color:no-shape:no-dtype:.2f}")

[[[0.16 0.14 0.94]
  [0.60 0.04 0.48]
  [0.03 0.27 0.41]
  [0.08 0.81 0.88]]

 [[0.25 0.66 0.35]
  [0.46 0.39 0.46]
  [0.01 0.58 0.65]
  [0.02 0.51 0.20]]]

The order of the formatting arguments is not important. Supported options are:

Layout: The layout determines what is printed and where. The following options are available:

  • summary Summarizes the values by mean, standard deviation, minimum and maximum value.
  • row Prints the tensor as a single-line vector.
  • full Prints all values in the tensors as a multi-line string.
  • numpy Uses the formatting of NumPy

Number format: You can additionally specify a format string for floating-point numbers like .3f or .2e.

Color: Use the keywords color or no-color. Currently color will use ANSI color codes which are supported by most terminals, IDEs as well as Jupyter notebooks.

Additional tensor information: The keywords shape, no-shape, dtype and no-dtype can be used to show or hide additional properties of the tensor.

Wrapping and Unwrapping¶

You can wrap existing tensors in ΦML tensors using wrap() or tensor(). While tensor() will convert the data to the default backend, wrap() will keep the data as-is. In either case, you need to specify the dimension names and types when wrapping a native tensor.

In [7]:
math.use('torch')
math.tensor([0, 1, 2], batch('examples'))
Out[7]:
(0, 1, 2) along examplesᵇ int64

To unwrap a tensor, you can use tensor.native() or math.reshaped_native() for more control over the result shape. In both cases, the requested dimension order needs to be specified.

In [8]:
data.native('examples,x,y')
Out[8]:
array([[[0.16087435, 0.13711604, 0.9422762 ],
        [0.5976694 , 0.03823091, 0.4753787 ],
        [0.03099525, 0.26839933, 0.4061108 ],
        [0.07997929, 0.81173575, 0.8794992 ]],

       [[0.2509363 , 0.6613298 , 0.3464606 ],
        [0.46408644, 0.3861803 , 0.4574289 ],
        [0.00891884, 0.57796794, 0.64523077],
        [0.02250077, 0.51273525, 0.20156278]]], dtype=float32)

Similarly, you can get the NumPy representation:

In [9]:
data.numpy('examples,x,y')
Out[9]:
array([[[0.16087435, 0.13711604, 0.9422762 ],
        [0.5976694 , 0.03823091, 0.4753787 ],
        [0.03099525, 0.26839933, 0.4061108 ],
        [0.07997929, 0.81173575, 0.8794992 ]],

       [[0.2509363 , 0.6613298 , 0.3464606 ],
        [0.46408644, 0.3861803 , 0.4574289 ],
        [0.00891884, 0.57796794, 0.64523077],
        [0.02250077, 0.51273525, 0.20156278]]], dtype=float32)

Further Reading¶

Check out the examples to see how using ΦML's tensors is different from the other libraries.

Learn more about the dimension types and their advantages.

ΦML unifies data types as well and lets you set the floating point precision globally or by context.

While the dimensionality of neural networks must be specified during network creation, this is not the case for math functions. These automatically adapt to the number of spatial dimensions of the data that is passed in.

🌐 ΦML   •   📖 Documentation   •   🔗 API   •   ▶ Videos   •   Examples