1# Copyright 2026 Huawei Technologies Co., Ltd
2#
3# Licensed under the Apache License, Version 2.0 (the "License");
4# you may not use this file except in compliance with the License.
5# You may obtain a copy of the License at
6#
7# http://www.apache.org/licenses/LICENSE-2.0
8#
9# Unless required by applicable law or agreed to in writing, software
10# distributed under the License is distributed on an "AS IS" BASIS,
11# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
12# See the License for the specific language governing permissions and
13# limitations under the License.
14# ============================================================================
15"""Affine state-summary operations used by GDN State-P2P."""
16
17
18__all__ = [
19 "apply_gdn_state_gradient_summary",
20 "apply_gdn_state_summary",
21 "chunk_gated_delta_rule_state_gradient_summary_bwd",
22 "chunk_gated_delta_rule_state_summary_fwd",
23]
24
25from typing import Optional
26
27import torch
28import triton
29
30from ._triton.gated_delta_net.state_summary import (
31 gdn_packed_state_summary_kernel,
32 gdn_state_grad_ext_kernel,
33)
34
35
36def _validate_fixed_summary_shape(
37 key_dim: int,
38 value_dim: int,
39 chunk_size: int,
40) -> None:
41 if key_dim != 128 or value_dim != 128 or chunk_size != 64:
42 raise NotImplementedError(
43 "Triton GDN state summary requires key_dim=value_dim=128 and "
44 "chunk_size=64."
45 )
46
47
48@torch.compiler.disable
49def chunk_gated_delta_rule_state_summary_fwd(
50 key: torch.Tensor,
51 w: torch.Tensor,
52 u: torch.Tensor,
53 g: torch.Tensor,
54 *,
55 chunk_size: int = 64,
56 block_size: int = 128,
57 output_transition: bool = True,
58) -> tuple[torch.Tensor, Optional[torch.Tensor]]:
59 """Return S and optionally M of ``state_out = M @ state_in + S``.
60
61 Set output_transition=False only when the caller has no consumer for M.
62 Both modes retain the same packed kernel; omitting M avoids its output
63 copy and saved-state lifetime, not its arithmetic.
64 """
65 if (key.ndim, w.ndim, u.ndim, g.ndim) != (4, 4, 4, 3):
66 raise ValueError("GDN state summary expects key/w/u [B,T,H,D] and g [B,T,H].")
67 batch, seq_len, heads, key_dim = key.shape
68 value_dim = u.shape[-1]
69 _validate_fixed_summary_shape(key_dim, value_dim, chunk_size)
70 if block_size not in (64, 128):
71 raise ValueError(f"GDN state-summary block_size must be 64 or 128, got {block_size}.")
72 if seq_len <= 0:
73 raise ValueError("State summary requires a nonempty sample fragment.")
74 if w.shape != key.shape or u.shape[:3] != key.shape[:3] or g.shape != key.shape[:3]:
75 raise ValueError(
76 "Incompatible GDN state-summary shapes: "
77 f"key={tuple(key.shape)}, w={tuple(w.shape)}, "
78 f"u={tuple(u.shape)}, g={tuple(g.shape)}."
79 )
80
81 key, w, u, g = (tensor.contiguous() for tensor in (key, w, u, g))
82 packed_summary = torch.empty(
83 batch,
84 heads,
85 key_dim,
86 value_dim + key_dim,
87 device=key.device,
88 dtype=torch.float32,
89 )
90 gdn_packed_state_summary_kernel[
91 (triton.cdiv(value_dim + key_dim, block_size), batch * heads)
92 ](
93 key,
94 w,
95 u,
96 g,
97 packed_summary,
98 seq_len,
99 H=heads,
100 K=key_dim,
101 V=value_dim,
102 BT=chunk_size,
103 BV=block_size,
104 NT=triton.cdiv(seq_len, chunk_size),
105 )
106 state_ext = packed_summary[..., :value_dim].contiguous()
107 if not output_transition:
108 return state_ext, None
109 transition = packed_summary[..., value_dim:].contiguous()
110 return state_ext, transition
111
112
113def _validate_gdn_gradient_summary_inputs(
114 query: torch.Tensor,
115 key: torch.Tensor,
116 w: torch.Tensor,
117 g: torch.Tensor,
118 grad_output: torch.Tensor,
119 dv: torch.Tensor,
120 chunk_size: int,
121) -> tuple[int, int, int, int, int]:
122 """Validate the reverse summary inputs before launching its kernel."""
123 batch, seq_len, heads, key_dim = query.shape
124 value_dim = grad_output.shape[-1]
125 _validate_fixed_summary_shape(key_dim, value_dim, chunk_size)
126 if seq_len <= 0:
127 raise ValueError("State summary requires a nonempty sample fragment.")
128 qk_shape = (batch, seq_len, heads, key_dim)
129 value_shape = (batch, seq_len, heads, value_dim)
130 if (key.shape, w.shape, g.shape, grad_output.shape, dv.shape) != (
131 qk_shape, qk_shape, qk_shape[:3], value_shape, value_shape
132 ):
133 raise ValueError(
134 "Incompatible GDN state-gradient summary shapes: "
135 f"query={tuple(query.shape)}, key={tuple(key.shape)}, "
136 f"w={tuple(w.shape)}, g={tuple(g.shape)}, "
137 f"grad_output={tuple(grad_output.shape)}, dv={tuple(dv.shape)}."
138 )
139 return batch, seq_len, heads, key_dim, value_dim
140
141
142@torch.compiler.disable
143def chunk_gated_delta_rule_state_gradient_summary_bwd(
144 query: torch.Tensor,
145 key: torch.Tensor,
146 w: torch.Tensor,
147 g: torch.Tensor,
148 grad_output: torch.Tensor,
149 dv: torch.Tensor,
150 scale: float,
151 *,
152 chunk_size: int = 64,
153) -> torch.Tensor:
154 """Return the local-loss contribution to the incoming state gradient."""
155 batch, seq_len, heads, key_dim, value_dim = _validate_gdn_gradient_summary_inputs(
156 query, key, w, g, grad_output, dv, chunk_size
157 )
158
159 query, key, w, g, grad_output, dv = (
160 tensor.contiguous() for tensor in (query, key, w, g, grad_output, dv)
161 )
162 grad_state_ext = torch.empty(
163 batch,
164 heads,
165 key_dim,
166 value_dim,
167 device=query.device,
168 dtype=torch.float32,
169 )
170 gdn_state_grad_ext_kernel[(1, batch * heads)](
171 query,
172 key,
173 w,
174 g,
175 grad_output,
176 dv,
177 grad_state_ext,
178 scale,
179 seq_len,
180 H=heads,
181 K=key_dim,
182 V=value_dim,
183 BT=chunk_size,
184 BV=128,
185 NT=triton.cdiv(seq_len, chunk_size),
186 )
187 return grad_state_ext
188
189
190def apply_gdn_state_summary(
191 state_ext: torch.Tensor,
192 transition: Optional[torch.Tensor],
193 initial_state: Optional[torch.Tensor],
194) -> torch.Tensor:
195 """Apply a local affine state summary in FP32."""
196 if initial_state is None:
197 return state_ext
198 return torch.matmul(transition, initial_state.float()) + state_ext
199
200
201def apply_gdn_state_gradient_summary(
202 grad_state_ext: torch.Tensor,
203 transition: Optional[torch.Tensor],
204 grad_final_state: Optional[torch.Tensor],
205) -> torch.Tensor:
206 """Apply the adjoint affine summary to a gradient from the next rank."""
207 if grad_final_state is None:
208 return grad_state_ext
209 return (
210 torch.matmul(transition.transpose(-2, -1), grad_final_state.float())
211 + grad_state_ext
212 )