Coverage for / home / jenkins / .local / lib / python3.10 / site-packages / hyper_parallel / components / functional / mhc_pre.py: 80%
49 statements
« prev ^ index » next coverage.py v7.13.1, created at 2026-11-19 05:29 +0800
« prev ^ index » next coverage.py v7.13.1, created at 2026-11-19 05:29 +0800
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"""Manifold hyper-connection pre-processing functions."""
17from typing import Any, Optional, Tuple
19import torch
21from hyper_parallel.components.functional.sinkhorn import sinkhorn
22from hyper_parallel.tools.logging import get_logger
24logger = get_logger()
27def _mhc_pre_backward(ctx, dh_in, dh_post, dh_res, dh_x):
28 """Invoke the legacy omni MHC gradient operator with the saved forward state."""
29 x, phi, alpha, gamma, h_post, inv_rms, h_mix, h_pre = ctx.saved_tensors
30 return torch.ops.custom.npu_manifold_constrained_hyper_connection_pre_grad(
31 x, phi, alpha, dh_in, dh_post, dh_res, inv_rms, h_mix, h_pre, h_post,
32 gamma=gamma,
33 hc_eps=ctx.hc_eps,
34 grad_x_post=dh_x,
35 )
38class _MhcPre(torch.autograd.Function):
39 """Autograd bridge for the legacy omni NPU MHC pre operator."""
41 @staticmethod
42 def forward(
43 ctx: Any,
44 x: torch.Tensor,
45 phi: torch.Tensor,
46 alpha: torch.Tensor,
47 bias: torch.Tensor,
48 gamma: Optional[torch.Tensor] = None,
49 out_flag: bool = True,
50 norm_eps: float = 1e-6,
51 hc_eps: float = 1e-6,
52 ) -> Tuple[torch.Tensor, torch.Tensor, torch.Tensor, torch.Tensor, torch.Tensor]:
53 """Run the legacy omni NPU MHC pre forward operator."""
54 # The package is optional and is needed only for the legacy omni backend.
55 # pylint: disable=import-outside-toplevel
56 try:
57 import omni_training_custom_ops # noqa: F401 # pylint: disable=unused-import
58 except ImportError as error:
59 raise ImportError("MHC backend='omni' requires omni_training_custom_ops") from error
60 # pylint: enable=import-outside-toplevel
61 hin, h_post, h_comb_before, inv_rms, h_mix, h_pre = (
62 torch.ops.custom.npu_manifold_constrained_hyper_connection_pre(
63 x,
64 phi,
65 alpha,
66 bias,
67 gamma=gamma,
68 out_flag=out_flag,
69 norm_eps=norm_eps,
70 hc_eps=hc_eps,
71 )
72 )
73 ctx.save_for_backward(x, phi, alpha, gamma, h_post, inv_rms, h_mix, h_pre)
74 ctx.hc_eps = hc_eps
75 ctx.has_gamma = gamma is not None
76 return hin, h_pre, h_post, h_comb_before, x
78 @staticmethod
79 def backward(
80 ctx: Any,
81 dh_in: torch.Tensor,
82 dh_pre: torch.Tensor,
83 dh_post: torch.Tensor,
84 dh_res: torch.Tensor,
85 dh_x: torch.Tensor,
86 ) -> tuple:
87 """Run the legacy omni NPU MHC pre backward operator."""
88 del dh_pre
89 dx, dphi, dalpha, dbias, dgamma = _mhc_pre_backward(ctx, dh_in, dh_post, dh_res, dh_x)
90 if not ctx.has_gamma:
91 dgamma = None
92 grads = [dx, dphi, dalpha, dbias, dgamma, None, None, None]
93 return tuple(grads)
96def _cann_mhc_pre(
97 x: torch.Tensor,
98 phi: torch.Tensor,
99 alpha: torch.Tensor,
100 bias: torch.Tensor,
101 num_stream: int,
102 sinkhorn_iters: int,
103 norm_eps: float,
104 hc_eps: float,
105 gamma: Optional[torch.Tensor],
106) -> Tuple[torch.Tensor, torch.Tensor, torch.Tensor]:
107 """Run the fused ops-transformer MHC pre and Sinkhorn operator.
109 The CANN operator has no RMS-scale input, so an optional gamma is folded
110 into the projection as a differentiable ``phi * gamma`` product; autograd
111 then keeps the phi and gamma gradients exact.
112 """
113 # The package is optional and is needed only for this selected CANN path.
114 from cann_ops_transformer.ops import ( # pylint: disable=import-outside-toplevel
115 mhc_pre_sinkhorn,
116 )
118 if gamma is not None:
119 phi = phi * gamma.reshape(1, -1).to(phi.dtype)
120 hin, h_post, h_res = mhc_pre_sinkhorn(
121 x, phi, alpha, bias, num_stream, sinkhorn_iters, hc_eps, norm_eps
122 )
123 # The operator returns the flattened [.., N*N] residual matrix while the
124 # shared post path consumes the square [.., N, N] layout.
125 return hin, h_post, h_res.reshape(*h_res.shape[:-1], num_stream, num_stream)
128def mhc_pre(
129 x: torch.Tensor,
130 phi: torch.Tensor,
131 branch_alpha: torch.Tensor,
132 branch_beta: torch.Tensor,
133 num_stream: int,
134 sinkhorn_iters: int = 20,
135 norm_eps: float = 1e-6,
136 hc_eps: float = 1e-6,
137 gamma: Optional[torch.Tensor] = None,
138 *,
139 backend: str = "cann",
140) -> tuple[torch.Tensor, torch.Tensor, torch.Tensor, torch.Tensor]:
141 """Prepare an input and its mixing coefficients for an MHC-wrapped block.
143 Args:
144 x: Flattened residual streams.
145 phi: MHC projection weight.
146 branch_alpha: Learned scale for each coefficient group.
147 branch_beta: Learned bias for each coefficient group.
148 num_stream: Number of residual streams.
149 sinkhorn_iters: Number of Sinkhorn iterations.
150 norm_eps: RMS normalization epsilon.
151 hc_eps: Hyper-connection numerical stability epsilon.
152 gamma: Optional RMS normalization scale.
153 backend: ``"cann"`` (default) calls the CANN ops-transformer
154 ``mhc_pre_sinkhorn`` operator; the legacy ``"omni"`` backend is
155 deprecated. CANN constraints: fp32 phi/alpha/beta, fp16/bf16
156 ``x`` with a 128-aligned tail axis, and fixed N=4 streams with 20
157 Sinkhorn iterations on Atlas A2/A3 series.
159 Returns:
160 Block input, post coefficients, residual coefficients, and residual buffer.
161 """
162 if backend not in ("cann", "omni"):
163 raise ValueError(f"backend must be 'cann' or 'omni', got {backend!r}")
164 shape = x.size()
165 x = x.reshape(shape[0], shape[1], num_stream, -1)
166 if gamma is not None:
167 gamma = gamma.reshape(num_stream, -1).float()
168 if backend == "cann":
169 hin, h_post, h_res = _cann_mhc_pre(
170 x,
171 phi.float(),
172 branch_alpha.float(),
173 branch_beta.float(),
174 num_stream,
175 sinkhorn_iters,
176 norm_eps,
177 hc_eps,
178 gamma,
179 )
180 return hin, h_post, h_res, x.reshape(shape[0], shape[1], -1)
181 logger.warning(
182 "mhc_pre backend='omni' is deprecated and will be removed in a future release; "
183 "use backend='cann'."
184 )
185 y, _, h_post, h_comb_before, residual = _MhcPre.apply(
186 x,
187 phi.float(),
188 branch_alpha.float(),
189 branch_beta.float(),
190 gamma,
191 True,
192 norm_eps,
193 hc_eps,
194 )
195 h_res = sinkhorn(h_comb_before, sinkhorn_iters, hc_eps)
196 residual = residual.reshape(shape[0], shape[1], -1)
197 return y, h_post, h_res, residual