Why Use Φ_ML's Tensors

  •   🌐 Φ_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

%%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.

from phiml import math
from phiml.math import channel, batch, spatial, instance, dual  # dimension types

math.wrap([0, 1, 2], channel('integers'))

(0, 1, 2) along integersᶜ int64

data = math.random_uniform(batch(examples=2), spatial(x=4, y=3))
data

(examplesᵇ=2, xˢ=4, yˢ=3) 0.495 ± 0.290 (8e-02...1e+00)

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:

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

(examplesᵇ=2, xˢ=4, yˢ=3) float32 4.94503e-01 ± 2.89850e-01 (7.71975e-02...9.74600e-01)

print(f"{data:full:color:shape:dtype:.3f}")

examples=0  
 0.405, 0.810, 0.866, 0.156,
 0.111, 0.975, 0.871, 0.077,
 0.288, 0.450, 0.495, 0.602  along (xˢ=4, yˢ=3)
examples=1  
 0.399, 0.179, 0.237, 0.877,
 0.462, 0.583, 0.824, 0.131,
 0.361, 0.163, 0.607, 0.938  along (xˢ=4, yˢ=3)

print(f"{data:numpy:no-color:no-shape:no-dtype:.2f}")

[[[0.29 0.11 0.41]
  [0.45 0.97 0.81]
  [0.49 0.87 0.87]
  [0.60 0.08 0.16]]

 [[0.36 0.46 0.40]
  [0.16 0.58 0.18]
  [0.61 0.82 0.24]
  [0.94 0.13 0.88]]]

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.

math.use('torch')
math.tensor([0, 1, 2], batch('examples'))

(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.

data.native('examples,x,y')

array([[[0.28807494, 0.11122419, 0.4050429 ],
        [0.450335  , 0.9746001 , 0.8097292 ],
        [0.4947539 , 0.87081677, 0.8657818 ],
        [0.60230553, 0.07719752, 0.15571558]],

       [[0.3610983 , 0.4624843 , 0.39913565],
        [0.16342373, 0.58331376, 0.17922853],
        [0.60698134, 0.82416594, 0.23666404],
        [0.9375892 , 0.13148437, 0.87692326]]], dtype=float32)

Similarly, you can get the NumPy representation:

data.numpy('examples,x,y')

array([[[0.28807494, 0.11122419, 0.4050429 ],
        [0.450335  , 0.9746001 , 0.8097292 ],
        [0.4947539 , 0.87081677, 0.8657818 ],
        [0.60230553, 0.07719752, 0.15571558]],

       [[0.3610983 , 0.4624843 , 0.39913565],
        [0.16342373, 0.58331376, 0.17922853],
        [0.60698134, 0.82416594, 0.23666404],
        [0.9375892 , 0.13148437, 0.87692326]]], 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