Factorization model¶
After creating a FunFact tensor expression, it can be evaluated by means of a FunFact factorization model. The essential approach is straightfoward:
import funfact as ff
# initialize tensors, indices, and create your favorite tensor expression
tsrex = ...
fac = ff.Factorization.from_tsrex(tsrex)
This instantiates a factorization model based on the input tensor expression.
The .from_tsrex
factory method optionally takes two additional keyword
arguments:
dtype
: the numerical type of the model, the available types depend on the backend that is used.initialize
: boolean that indicates if the leaf tensors are initialized in Factorization model. By default this is set toTrue
.
Warning
Direct initialization of a factorization model (ff.Factorization(tsrex)
)
is NOT recommended and can lead to undesired behavior.
Properties of factorization models¶
A factorization model has properties that can be queried. We illustrate their usage for the following concrete example of a factorization model for a \(3 \times 2\) rank-1 matrix initialized from concrete data:
import funfact as ff
import numpy as np
# instantiate data arrays:
a = np.array([1.0, 2.0, 3.0])
b = np.array([-1.0, 4.0])
# instantiate tensors from concrete data:
a = ff.tensor('a', a, optimizable=False)
b = ff.tensor('b', b, optimizable=True, prefer=ff.conditions.NonNegative())
i, j = ff.indices('i, j')
# create tensor expression and factorization model:
tsrex = a[i] * b[j]
fac = ff.Factorization.from_tsrex(tsrex)
- The tensor expression stored in the factorization model can be retrieved
through the
.tsrex
property. This tensor expression has its own set of properties. For our example, running renders a LaTeX representation for the tensor expression in a Jupyter notebook:
Warning
The tensor expression is compiled upon instantiation of the factorization
model. For more complicated expression, the internal fac.tsrex
can differ
from the input, but always is functionally equivalent.
-
The shape of a factorization model can be accessed with the
.shape
property: -
The dimensionality of a factorization model can be accessed through the
.ndim
property:
Note
Both .shape
and .ndim
properties are forwarded from the tensor
expression of the factorization model.
- The optimizable factor (or leaf) tensors in the factorization model can
be accessed through the
.factors
property:Only the data for thefactors = fac.factors factors # >>> <'data' field of tensor b> factors[0] # >>> DeviceArray([-1., 4.], dtype=float32)
b
tensor is returned asa
is not an optimizable tensor.
Warning
The .factors
can be assigned to new data as a setter
method is
implemented. However, this is NOT recommended and only used during the
optimization loop when factorizing a model for a target
tensor.
- All factor tensors irrespective of the optimizable flag, can be accessed
through the
.all_factors
property:
Evaluation¶
A FunFact factorization model can be evaluated simply by calling it or equivalenty by using the forward method:
This performs all the operations and contractions as specified in the tensor expression that was used when instantiating the model based on the tensor data in the leaf tensors and returns the end result. For our example, this returns:Partial evaluation¶
A factorization model can also be evaluated for just certain elements or slices of the full model. FunFact follows largely the same pattern as NumPy array slicing:
fac[0,0]
# >>> DeviceArray([[-1.]], dtype=float32)
fac[-1,-1]
# >>> DeviceArray([[12.]], dtype=float32)
fac[1:3,-1]
# >>> DeviceArray([[ 8.],
# [12.]], dtype=float32)
Note
The requested array slices are analyzed and only the necessary parts of the factor tensors are used to compute the result. This avoids evaluation of the full model.
Factors¶
The factors of a factorization model can also be accessed by name with the []
operation:
fac['a']
# >>> DeviceArray([1., 2., 3.], dtype=float32)
fac['b']
# >>> DeviceArray([-1., 4.], dtype=float32)
Penalties¶
The penalties on the optimizable factors of a factorization model can
evaluated through the .penalties
method:
This method takes two keyword arguments:
sum_leafs
: a boolean flag indicating if the penalties are summed over all the leaf tensors.sum_vec
: a boolean flag indicating if the penalties are summed over all instances in a vectorized model, see the factorization page for more information about vectorization.