Twice differentiable

TensorType = TypeVar('TensorType', bound=Sequence) module-attribute

Type variable for tensors, i.e. sequences of numbers

ModelType = TypeVar('ModelType', bound='TwiceDifferentiable') module-attribute

Type variable for twice differentiable models

DataLoaderType = TypeVar('DataLoaderType', bound=Iterable) module-attribute

Type variable for data loaders

InverseHvpResult dataclass

Bases: Generic[TensorType]

Container class for results of solving a problem \(Ax=b\)

PARAMETER	DESCRIPTION
x	solution of a problem \(Ax=b\) TYPE: TensorType
info	additional information, to couple with the solution itself TYPE: Dict[str, Any]

TwiceDifferentiable

Bases: ABC, Generic[TensorType]

Abstract base class for wrappers of differentiable models and losses. Meant to be subclassed for each supported framework. Provides methods to compute gradients and second derivative of the loss wrt. the model parameters

num_params: int abstractmethod property

Returns the number of parameters of the model

parameters: List[TensorType] abstractmethod property

Returns all the model parameters that require differentiation

grad(x, y, create_graph=False)

Calculates gradient of model parameters with respect to the model parameters.

PARAMETER	DESCRIPTION
x	A matrix representing the features \(x_i\). TYPE: TensorType
y	A matrix representing the target values \(y_i\). TYPE: TensorType
create_graph	Used for further differentiation on input parameters. TYPE: bool DEFAULT: False

RETURNS	DESCRIPTION
TensorType	An array with the gradients of the model.

Source code in src/pydvl/influence/twice_differentiable.py

def grad(
    self, x: TensorType, y: TensorType, create_graph: bool = False
) -> TensorType:
    r"""
    Calculates gradient of model parameters with respect to the model parameters.

    Args:
        x: A matrix representing the features \(x_i\).
        y: A matrix representing the target values \(y_i\).
        create_graph: Used for further differentiation on input parameters.

    Returns:
        An array with the gradients of the model.
    """

    pass

hessian(x, y)

Calculates the full Hessian of \(L(f(x),y)\) with respect to the model parameters given data \(x\) and \(y\).

PARAMETER	DESCRIPTION
x	An array representing the features \(x_i\). TYPE: TensorType
y	An array representing the target values \(y_i\). TYPE: TensorType

RETURNS	DESCRIPTION
TensorType	A tensor representing the Hessian of the model, i.e. the second derivative with respect to the model parameters.

Source code in src/pydvl/influence/twice_differentiable.py

def hessian(self, x: TensorType, y: TensorType) -> TensorType:
    r"""
    Calculates the full Hessian of \(L(f(x),y)\) with respect to the model parameters given data \(x\) and \(y\).

    Args:
        x: An array representing the features \(x_i\).
        y: An array representing the target values \(y_i\).

    Returns:
        A tensor representing the Hessian of the model, i.e. the second derivative
            with respect to the model parameters.
    """

    pass

mvp(grad_xy, v, backprop_on, *, progress=False) abstractmethod staticmethod

Calculates the second order derivative of the model along directions \(v\). The second order derivative can be selected through the backprop_on argument.

PARAMETER	DESCRIPTION
grad_xy	An array [P] holding the gradients of the model parameters with respect to input \(x\) and labels \(y\). \(P\) is the number of parameters of the model. Typically obtained through self.grad. TYPE: TensorType
v	An array ([DxP] or even one-dimensional [D]) which multiplies the matrix. \(D\) is the number of directions. TYPE: TensorType
progress	If True, progress is displayed. TYPE: bool DEFAULT: False
backprop_on	Tensor used in the second backpropagation. The first one is along \(x\) and \(y\) as defined via grad_xy. TYPE: TensorType

RETURNS	DESCRIPTION
TensorType	A matrix representing the implicit matrix-vector product of the model along the given directions. Output shape is [DxM], where \(M\) is the number of elements of backprop_on.

Source code in src/pydvl/influence/twice_differentiable.py

@staticmethod
@abstractmethod
def mvp(
    grad_xy: TensorType,
    v: TensorType,
    backprop_on: TensorType,
    *,
    progress: bool = False,
) -> TensorType:
    r"""
    Calculates the second order derivative of the model along directions \(v\).
    The second order derivative can be selected through the `backprop_on` argument.

    Args:
        grad_xy: An array [P] holding the gradients of the model parameters with respect to input \(x\) and
            labels \(y\). \(P\) is the number of parameters of the model. Typically obtained through `self.grad`.
        v: An array ([DxP] or even one-dimensional [D]) which multiplies the matrix.
            \(D\) is the number of directions.
        progress: If `True`, progress is displayed.
        backprop_on: Tensor used in the second backpropagation. The first one is along \(x\) and \(y\)
            as defined via `grad_xy`.

    Returns:
        A matrix representing the implicit matrix-vector product of the model along the given directions.
            Output shape is [DxM], where \(M\) is the number of elements of `backprop_on`.
    """

TensorUtilities

Bases: Generic[TensorType, ModelType], ABC

__init_subclass__(**kwargs)

Automatically registers non-abstract subclasses in the registry.

This method checks if twice_differentiable_type is defined in the subclass and if it is of the correct type. If either attribute is missing or incorrect, a TypeError is raised.

PARAMETER	DESCRIPTION
kwargs	Additional keyword arguments. DEFAULT: {}

RAISES	DESCRIPTION
TypeError	If the subclass does not define twice_differentiable_type, or if it is not of the correct type.

Source code in src/pydvl/influence/twice_differentiable.py

def __init_subclass__(cls, **kwargs):
    """
    Automatically registers non-abstract subclasses in the registry.

    This method checks if `twice_differentiable_type` is defined in the subclass and if it is of the correct type.
    If either attribute is missing or incorrect, a `TypeError` is raised.

    Args:
        kwargs: Additional keyword arguments.

    Raises:
        TypeError: If the subclass does not define `twice_differentiable_type`, or if it is not of the correct type.
    """

    if not hasattr(cls, "twice_differentiable_type") or not isinstance(
        cls.twice_differentiable_type, type
    ):
        raise TypeError(
            f"'twice_differentiable_type' must be a Type[TwiceDifferentiable]"
        )

    cls.registry[cls.twice_differentiable_type] = cls

    super().__init_subclass__(**kwargs)

einsum(equation, *operands) abstractmethod staticmethod

Sums the product of the elements of the input operands along dimensions specified using a notation based on the Einstein summation convention.

Source code in src/pydvl/influence/twice_differentiable.py

@staticmethod
@abstractmethod
def einsum(equation, *operands) -> TensorType:
    """Sums the product of the elements of the input `operands` along dimensions specified using a notation
    based on the Einstein summation convention.
    """

cat(a, **kwargs) abstractmethod staticmethod

Concatenates a sequence of tensors into a single torch tensor

Source code in src/pydvl/influence/twice_differentiable.py

@staticmethod
@abstractmethod
def cat(a: Sequence[TensorType], **kwargs) -> TensorType:
    """Concatenates a sequence of tensors into a single torch tensor"""

stack(a, **kwargs) abstractmethod staticmethod

Stacks a sequence of tensors into a single torch tensor

Source code in src/pydvl/influence/twice_differentiable.py

@staticmethod
@abstractmethod
def stack(a: Sequence[TensorType], **kwargs) -> TensorType:
    """Stacks a sequence of tensors into a single torch tensor"""

unsqueeze(x, dim) abstractmethod staticmethod

Add a singleton dimension at a specified position in a tensor

Source code in src/pydvl/influence/twice_differentiable.py

@staticmethod
@abstractmethod
def unsqueeze(x: TensorType, dim: int) -> TensorType:
    """Add a singleton dimension at a specified position in a tensor"""

get_element(x, idx) abstractmethod staticmethod

Get the tensor element x[i] from the first non-singular dimension

Source code in src/pydvl/influence/twice_differentiable.py

@staticmethod
@abstractmethod
def get_element(x: TensorType, idx: int) -> TensorType:
    """Get the tensor element x[i] from the first non-singular dimension"""

slice(x, start, stop, axis=0) abstractmethod staticmethod

Slice a tensor in the provided axis

Source code in src/pydvl/influence/twice_differentiable.py

@staticmethod
@abstractmethod
def slice(x: TensorType, start: int, stop: int, axis: int = 0) -> TensorType:
    """Slice a tensor in the provided axis"""

shape(x) abstractmethod staticmethod

Slice a tensor in the provided axis

Source code in src/pydvl/influence/twice_differentiable.py

@staticmethod
@abstractmethod
def shape(x: TensorType) -> Tuple[int, ...]:
    """Slice a tensor in the provided axis"""

reshape(x, shape) abstractmethod staticmethod

Reshape a tensor to the provided shape

Source code in src/pydvl/influence/twice_differentiable.py

@staticmethod
@abstractmethod
def reshape(x: TensorType, shape: Tuple[int, ...]) -> TensorType:
    """Reshape a tensor to the provided shape"""

cat_gen(a, resulting_shape, model) abstractmethod staticmethod

Concatenate tensors from a generator. Resulting tensor is of shape resulting_shape and compatible to model

Source code in src/pydvl/influence/twice_differentiable.py

@staticmethod
@abstractmethod
def cat_gen(
    a: Generator[TensorType, None, None],
    resulting_shape: Tuple[int, ...],
    model: ModelType,
) -> TensorType:
    """Concatenate tensors from a generator. Resulting tensor is of shape resulting_shape
    and compatible to model
    """

from_twice_differentiable(twice_diff) classmethod

Factory method to create an instance of a subclass TensorUtilities from an instance of a subclass of TwiceDifferentiable.

PARAMETER	DESCRIPTION
twice_diff	An instance of a subclass of TwiceDifferentiable for which a corresponding TensorUtilities object is required. TYPE: TwiceDifferentiable

RETURNS	DESCRIPTION
Type[TensorUtilities]	An subclass of TensorUtilities registered to the provided subclass instance of TwiceDifferentiable object.

RAISES	DESCRIPTION
KeyError	If there's no registered TensorUtilities for the provided TwiceDifferentiable type.

Source code in src/pydvl/influence/twice_differentiable.py

@classmethod
def from_twice_differentiable(
    cls,
    twice_diff: TwiceDifferentiable,
) -> Type["TensorUtilities"]:
    """
    Factory method to create an instance of a subclass
    [TensorUtilities][pydvl.influence.twice_differentiable.TensorUtilities] from an instance of a subclass of
    [TwiceDifferentiable][pydvl.influence.twice_differentiable.TwiceDifferentiable].

    Args:
        twice_diff: An instance of a subclass of
            [TwiceDifferentiable][pydvl.influence.twice_differentiable.TwiceDifferentiable]
            for which a corresponding [TensorUtilities][pydvl.influence.twice_differentiable.TensorUtilities]
            object is required.

    Returns:
        An subclass of [TensorUtilities][pydvl.influence.twice_differentiable.TensorUtilities]
            registered to the provided subclass instance of
            [TwiceDifferentiable][pydvl.influence.twice_differentiable.TwiceDifferentiable] object.

    Raises:
        KeyError: If there's no registered [TensorUtilities][pydvl.influence.twice_differentiable.TensorUtilities]
            for the provided [TwiceDifferentiable][pydvl.influence.twice_differentiable.TwiceDifferentiable] type.
    """

    tu = cls.registry.get(type(twice_diff), None)

    if tu is None:
        raise KeyError(
            f"No registered TensorUtilities for the type {type(twice_diff).__name__}"
        )

    return tu

---

Last update: 2023-09-02
Created: 2023-09-02