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

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.""" 

16 

17from typing import Any, Optional, Tuple 

18 

19import torch 

20 

21from hyper_parallel.components.functional.sinkhorn import sinkhorn 

22from hyper_parallel.tools.logging import get_logger 

23 

24logger = get_logger() 

25 

26 

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 ) 

36 

37 

38class _MhcPre(torch.autograd.Function): 

39 """Autograd bridge for the legacy omni NPU MHC pre operator.""" 

40 

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 

77 

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) 

94 

95 

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. 

108 

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 ) 

117 

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) 

126 

127 

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. 

142 

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. 

158 

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