Geometry and structural losses

Reduce Local Frame Point Errors

MediumRaw PyTorchAbout 20 min2 public examples plus private tests

AlphaFold2AlphaFold-MultimerOpenFold

Free account with email, Google or GitHub. Your code runs in an isolated PyTorch sandbox.

Your task

Compare predicted and target points that are already expressed in their respective local frames. Return one masked, scaled distance loss per batch item.

Function signature

masked_frame_point_error(
    predicted: torch.Tensor,
    target: torch.Tensor,
    valid_pairs: torch.Tensor,
    eps_distance: float = 1e-08,
    eps_count: float = 1e-08,
    clamp_distance: None | float = None,
    length_scale: float = 10.0,
) -> torch.Tensor

Worked example

Mask the large error

The included displacement has length approximately 5, giving a scaled loss approximately 0.5. The large masked error contributes nothing.

import torch

predicted = torch.tensor([[[[3.0, 4.0, 0.0], [100.0, 0.0, 0.0]]]], dtype=torch.float64, requires_grad=True)
target = torch.tensor([[[[0.0, 0.0, 0.0], [0.0, 0.0, 0.0]]]], dtype=torch.float64, requires_grad=True)
valid_pairs = torch.tensor([[[True, False]]], dtype=torch.bool)
eps_distance = 1e-08
eps_count = 1e-08
clamp_distance = None
length_scale = 10.0

result = masked_frame_point_error(predicted=predicted, target=target, valid_pairs=valid_pairs, eps_distance=eps_distance, eps_count=eps_count, clamp_distance=clamp_distance, length_scale=length_scale)

Expected return

torch.tensor([0.4999999951000001], dtype=torch.float64)

Parameters

Parameter	Shape and meaning
`predicted`torch.Tensor	$(B,F,P,3)$ Predicted point coordinates in each predicted local frame.
`target`torch.Tensor	$(B,F,P,3)$ Corresponding target point coordinates in each target local frame.
`valid_pairs`torch.Tensor	$(B,F,P)$ True includes this frame-point pair in the loss.
`eps_distance`floatDefault `1e-08`	Epsilon under the distance square root.
`eps_count`floatDefault `1e-08`	Epsilon in the masked count denominator.
`clamp_distance`None \| floatDefault `None`	None disables clamping. Otherwise use a finite nonnegative distance cap after the square root and before length scaling.
`length_scale`floatDefault `10.0`	Positive distance scale that converts the loss into a dimensionless value.

Return

torch.Tensor · $[B]$

Return Floating [B] masked, scaled FAPE; no reduction across batch.

Required behavior

For each frame-point pair, compute $d=\sqrt{\sum_{c=1}^{3}(p_c-q_c)^2+\varepsilon_d}$ . If clamp_distance is provided, clamp d to that value before dividing by length_scale.
True in valid_pairs includes a pair. Sum the scaled distances over both frame and point axes, then divide by the valid-pair count plus eps_count. Do not reduce the batch axis.
eps_distance and eps_count are finite and strictly positive, each defaulting to $10^{-8}$ . length_scale is finite and positive, default 10. clamp_distance is None or a finite nonnegative number.
Perfectly matching points have stabilized distance $\sqrt{\varepsilon_d}$ , not zero. A batch item with no valid pairs returns exactly zero.
B is positive; F or P may be zero. Inputs are finite and may be strided. Gradients are checked for predicted and target coordinates; masks and settings are not differentiated.

Why this matters

Each residue frame supplies its own coordinate system. Comparing local coordinates measures structural agreement without first choosing one global protein alignment; the numbers of frames and points may differ.

Starter code

You write the body of this function in the BioTorch workspace. Your code runs in an isolated PyTorch sandbox; Run checks the public examples and Submit grades the full test suite, including gradients.

import torch


def masked_frame_point_error(
    predicted: torch.Tensor,  # (B,F,P,3)
    target: torch.Tensor,  # (B,F,P,3)
    valid_pairs: torch.Tensor,  # (B,F,P)
    eps_distance: float = 1e-08,
    eps_count: float = 1e-08,
    clamp_distance: None | float = None,
    length_scale: float = 10.0,
) -> torch.Tensor:
    """Return a tensor with shape (B,)."""
    # Implement the operation. Inputs and test setup are supplied by BioTorch.
    raise NotImplementedError("Implement masked_frame_point_error")

Ready to implement it?

3 progressive hints, a solution walkthrough, and grading that checks values, shapes and gradients are waiting in the workspace.

Write and run your solution Sign in

Free account with email, Google or GitHub. Your code runs in an isolated PyTorch sandbox.

Related exercises

Sources and further reading

A primitive exercise, not an end-to-end reproduction of the named models. No affiliation or endorsement is implied.