Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
115 changes: 115 additions & 0 deletions pyg_lib/csrc/ops/autograd/scatter_kernel.cpp
Original file line number Diff line number Diff line change
Expand Up @@ -139,13 +139,128 @@ at::Tensor scatter_mul_autograd(const at::Tensor& src,
return ScatterMul::apply(src, index, dim, optional_out, dim_size)[0];
}

// Autograd Function for `pyg::scatter_mean`.
//
// Composite op: forward dispatches to `scatter_sum` twice (numerator over
// `src` and denominator over a `ones`-tensor sized like `index`) and then
// divides. Because there is no dedicated CPU/CUDA kernel, the wrapper is
// registered to `CompositeExplicitAutograd` rather than `Autograd`: that
// key routes the call here for *all* backends and regardless of whether
// any input requires grad. `Function::apply` itself decides whether to
// record on the autograd tape based on input grad state, so this single
// registration handles both `requires_grad=True` and `requires_grad=False`
// callers correctly.
//
// Backward formula (upstream pytorch_scatter `scatter.cpp:149-160`):
//
// grad_src = (grad_out.gather(dim, index_b)) / count.gather(dim, index_b)
//
// where `count` is the broadcast per-bucket count tensor saved from forward.
class ScatterMean : public torch::autograd::Function<ScatterMean> {
public:
static variable_list forward(torch::autograd::AutogradContext* ctx,
const at::Tensor& src,
const at::Tensor& index,
int64_t dim,
const std::optional<at::Tensor>& optional_out,
std::optional<int64_t> dim_size) {
at::AutoDispatchBelowADInplaceOrView g;

const int64_t dim_norm = dim < 0 ? src.dim() + dim : dim;

// Broadcast `index` up to `src.shape` for the sum dispatch and so
// backward's `gather` can use it directly.
auto index_b = broadcast(index, src, dim_norm);

// Numerator: per-bucket sum of `src` values.
auto out_tensor =
scatter_sum(src, index_b, dim_norm, optional_out, dim_size);

// Denominator: per-bucket count. Use the *original* (non-broadcast)
// `index` against a 1-D `ones` of length `index.size(...)`. Upstream
// mirrors the same trick to avoid double-counting when `index` is
// broadcast across multiple non-`dim` axes. The reduction `dim` for
// this auxiliary call is the last axis of `index` if `index` has
// fewer dims than `dim_norm` (i.e. `index` is 1-D and the broadcast
// adds leading singletons), else `dim_norm`.
const int64_t count_dim =
index.dim() <= dim_norm ? index.dim() - 1 : dim_norm;
auto ones = at::ones(index.sizes(), src.options());
auto count = scatter_sum(ones, index, count_dim, std::nullopt,
out_tensor.size(dim_norm));
count.masked_fill_(count < 1, 1);

// Broadcast `count` (1-D along `dim_norm`) up to `out_tensor.shape`
// so it aligns for in-place division along the reduction axis.
auto count_b = broadcast(count, out_tensor, dim_norm);

if (out_tensor.is_floating_point()) {
out_tensor.true_divide_(count_b);
} else {
out_tensor.div_(count_b, "floor");
}

// Save the *broadcast* count: backward's `gather(count_b, dim, index_b)`
// expects `count` to be shaped like `out_tensor` so gather aligns.
ctx->save_for_backward({index_b, count_b});
ctx->saved_data["dim"] = dim_norm;

if (optional_out.has_value()) {
ctx->mark_dirty({optional_out.value()});
}

return {out_tensor};
}

static variable_list backward(torch::autograd::AutogradContext* ctx,
variable_list grad_outs) {
const auto grad_out = grad_outs[0];
const auto saved = ctx->get_saved_variables();
const auto index_b = saved[0];
const auto count_b = saved[1];
const auto dim = ctx->saved_data["dim"].toInt();

// `grad_src[i] = grad_out[index[i]] / count[index[i]]`. Gather both
// along `dim` using the broadcast index so per-position counts line up.
auto count_gathered = count_b.gather(dim, index_b);
auto grad_src = grad_out.gather(dim, index_b).true_divide_(count_gathered);

// 5 input slots: (src, index, dim, out, dim_size).
return {grad_src, at::Tensor(), at::Tensor(), at::Tensor(), at::Tensor()};
}
};

at::Tensor scatter_mean_autograd(const at::Tensor& src,
const at::Tensor& index,
int64_t dim,
const std::optional<at::Tensor>& optional_out,
std::optional<int64_t> dim_size) {
return ScatterMean::apply(src, index, dim, optional_out, dim_size)[0];
}

} // namespace

TORCH_LIBRARY_IMPL(pyg, Autograd, m) {
m.impl(TORCH_SELECTIVE_NAME("pyg::scatter_sum"),
TORCH_FN(scatter_sum_autograd));
m.impl(TORCH_SELECTIVE_NAME("pyg::scatter_mul"),
TORCH_FN(scatter_mul_autograd));
// `scatter_mean` is also registered to `Autograd` (in addition to
// `CompositeExplicitAutograd` below) to silence the runtime warning
// emitted when PyTorch finds no Autograd-key kernel and falls back to
// the not-implemented sentinel; the same wrapper handles both paths.
m.impl(TORCH_SELECTIVE_NAME("pyg::scatter_mean"),
TORCH_FN(scatter_mean_autograd));
}

// `scatter_mean` has no dedicated CPU/CUDA kernel; it is fully composed of
// other dispatcher calls. Registering to `CompositeExplicitAutograd` makes
// the dispatcher route the call to our wrapper for *every* backend (and
// regardless of `requires_grad`), so non-grad callers do not fall through
// to an empty backend kernel slot.
TORCH_LIBRARY_IMPL(pyg, CompositeExplicitAutograd, m) {
m.impl(TORCH_SELECTIVE_NAME("pyg::scatter_mean"),
TORCH_FN(scatter_mean_autograd));
}

} // namespace ops
Expand Down
32 changes: 32 additions & 0 deletions pyg_lib/csrc/ops/scatter.cpp
Original file line number Diff line number Diff line change
Expand Up @@ -64,13 +64,45 @@ PYG_API at::Tensor scatter_mul(const at::Tensor& src,
return op.call(src, index, dim, out, dim_size);
}

PYG_API at::Tensor scatter_mean(const at::Tensor& src,
const at::Tensor& index,
int64_t dim,
const std::optional<at::Tensor>& out,
std::optional<int64_t> dim_size) {
at::TensorArg src_arg{src, "src", 0};
at::TensorArg index_arg{index, "index", 1};
at::CheckedFrom c{"scatter_mean"};

at::checkAllDefined(c, {src_arg, index_arg});
TORCH_CHECK(src.device() == index.device(),
"scatter_mean: src and index must be on the same device "
"(got src=",
src.device(), ", index=", index.device(), ")");
if (out.has_value()) {
at::TensorArg out_arg{out.value(), "out", 3};
at::checkAllDefined(c, {out_arg});
TORCH_CHECK(src.device() == out.value().device(),
"scatter_mean: src and out must be on the same device "
"(got src=",
src.device(), ", out=", out.value().device(), ")");
}

static auto op = c10::Dispatcher::singleton()
.findSchemaOrThrow("pyg::scatter_mean", "")
.typed<decltype(scatter_mean)>();
return op.call(src, index, dim, out, dim_size);
}

TORCH_LIBRARY_FRAGMENT(pyg, m) {
m.def(TORCH_SELECTIVE_SCHEMA(
"pyg::scatter_sum(Tensor src, Tensor index, int dim=-1, "
"Tensor? out=None, int? dim_size=None) -> Tensor"));
m.def(TORCH_SELECTIVE_SCHEMA(
"pyg::scatter_mul(Tensor src, Tensor index, int dim=-1, "
"Tensor? out=None, int? dim_size=None) -> Tensor"));
m.def(TORCH_SELECTIVE_SCHEMA(
"pyg::scatter_mean(Tensor src, Tensor index, int dim=-1, "
"Tensor? out=None, int? dim_size=None) -> Tensor"));
}

} // namespace ops
Expand Down
19 changes: 19 additions & 0 deletions pyg_lib/csrc/ops/scatter.h
Original file line number Diff line number Diff line change
Expand Up @@ -36,5 +36,24 @@ PYG_API at::Tensor scatter_mul(
const std::optional<at::Tensor>& out = std::nullopt,
std::optional<int64_t> dim_size = std::nullopt);

// Averages all values from `src` into `out` at the indices specified in
// `index` along a given axis `dim`.
//
// Implemented as two `scatter_sum` calls: one to accumulate the per-bucket
// sum, and one (over a ones tensor sized to match `index`) to compute the
// per-bucket count. The final result is the sum divided by the count, with
// empty buckets producing `0` (the count is `masked_fill`-ed up to `1` so
// the division does not generate NaNs). Integer dtypes use floor division
// to match the upstream contract; floating dtypes use true division.
//
// When `out` is provided, the accumulation happens in the caller's buffer
// (no zero-init), matching the upstream `scatter_sum` contract.
PYG_API at::Tensor scatter_mean(
const at::Tensor& src,
const at::Tensor& index,
int64_t dim = -1,
const std::optional<at::Tensor>& out = std::nullopt,
std::optional<int64_t> dim_size = std::nullopt);

} // namespace ops
} // namespace pyg
29 changes: 29 additions & 0 deletions pyg_lib/ops/__init__.py
Original file line number Diff line number Diff line change
Expand Up @@ -411,6 +411,34 @@ def scatter_mul(
return torch.ops.pyg.scatter_mul(src, index, dim, out, dim_size)


def scatter_mean(
src: Tensor,
index: Tensor,
dim: int = -1,
out: Optional[Tensor] = None,
dim_size: Optional[int] = None,
) -> Tensor:
r"""Reduces all values from the :obj:`src` tensor into :obj:`out` at the
indices specified in the :obj:`index` tensor along a given axis
:obj:`dim`, using ``mean`` as the reduction. Empty buckets yield zero.

For floating-point inputs, division is exact. For integer inputs,
floor-division is used (matching upstream ``pytorch_scatter``).

Args:
src: The source tensor.
index: The indices of elements to scatter.
dim: The axis along which to index.
out: The destination tensor.
dim_size: If :obj:`out` is not given, automatically create output with
size :obj:`dim_size` at dimension :obj:`dim`.

Returns:
The reduced tensor.
"""
return torch.ops.pyg.scatter_mean(src, index, dim, out, dim_size)


def spline_basis(
pseudo: Tensor,
kernel_size: Tensor,
Expand Down Expand Up @@ -652,6 +680,7 @@ def edge_sample(
'scatter_sum',
'scatter_add',
'scatter_mul',
'scatter_mean',
'spline_basis',
'spline_weighting',
'grid_cluster',
Expand Down
Loading
Loading