Coverage for / home / jenkins / .local / lib / python3.10 / site-packages / hyper_parallel / components / functional / mhc_post.py: 84%
32 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 post-processing functions."""
17from typing import Any, Tuple
19import torch
21from hyper_parallel.tools.logging import get_logger
23logger = get_logger()
26class _MhcPost(torch.autograd.Function):
27 """Autograd bridge for the legacy omni NPU MHC post operator."""
29 @staticmethod
30 def forward(
31 ctx: Any,
32 x: torch.Tensor,
33 h_res: torch.Tensor,
34 h_out: torch.Tensor,
35 h_post: torch.Tensor,
36 ) -> torch.Tensor:
37 """Run the legacy omni NPU MHC post forward operator."""
38 # The package is optional and is needed only for the legacy omni backend.
39 # pylint: disable=import-outside-toplevel
40 try:
41 import omni_training_custom_ops # noqa: F401 # pylint: disable=unused-import
42 except ImportError as error:
43 raise ImportError("MHC backend='omni' requires omni_training_custom_ops") from error
44 # pylint: enable=import-outside-toplevel
45 ctx.save_for_backward(x, h_res, h_out, h_post)
46 return torch.ops.custom.npu_ai_infra_manifold_constrained_hyper_connection_post(
47 x,
48 h_res,
49 h_out,
50 h_post,
51 )
53 @staticmethod
54 def backward(
55 ctx: Any,
56 grad_output: torch.Tensor,
57 ) -> Tuple[torch.Tensor, torch.Tensor, torch.Tensor, torch.Tensor]:
58 """Run the legacy omni NPU MHC post backward operator."""
59 x, h_res, h_out, h_post = ctx.saved_tensors
60 grad_x, grad_h_res, grad_h_out, grad_h_post = torch.ops.custom.npu_ai_infra_mhc_post_grad(
61 grad_output.contiguous(),
62 x,
63 h_res,
64 h_out,
65 h_post,
66 )
67 return grad_x, grad_h_res, grad_h_out, grad_h_post
70def mhc_post(
71 x: torch.Tensor,
72 residual: torch.Tensor,
73 h_post: torch.Tensor,
74 h_res: torch.Tensor,
75 num_stream: int,
76 *,
77 backend: str = "cann",
78) -> torch.Tensor:
79 """Combine transformed and residual streams after an MHC-wrapped block.
81 Args:
82 x: Output of the wrapped block.
83 residual: Flattened residual streams.
84 h_post: Per-stream output mixing coefficients.
85 h_res: Residual stream mixing matrix.
86 num_stream: Number of residual streams.
87 backend: ``"cann"`` (default) calls the differentiable CANN
88 ops-transformer ``mhc_post`` operator and requires fp16/bf16
89 ``x``/``residual`` with fp32 ``h_post``/``h_res``; the legacy
90 ``"omni"`` backend is deprecated. CPU execution keeps the eager
91 fallback.
93 Returns:
94 Flattened mixed residual streams.
95 """
96 if backend not in ("cann", "omni"):
97 raise ValueError(f"backend must be 'cann' or 'omni', got {backend!r}")
98 x_shape = x.size()
99 residual = residual.reshape(x_shape[0], x_shape[1], num_stream, -1)
100 if x.device.type == "npu":
101 # Load only the selected optional backend so either can be used independently.
102 # pylint: disable=import-outside-toplevel
103 if backend == "cann":
104 from cann_ops_transformer.ops import mhc_post as cann_mhc_post
106 # CANN argument order: residual streams, residual matrix, block
107 # output, post coefficients.
108 return cann_mhc_post(residual, h_res, x, h_post).flatten(2)
109 logger.warning(
110 "mhc_post backend='omni' is deprecated and will be removed in a future release; "
111 "use backend='cann'."
112 )
113 return _MhcPost.apply(residual, h_res, x, h_post).flatten(2)
114 # pylint: enable=import-outside-toplevel
115 output = h_post.unsqueeze(-1) * x.unsqueeze(-2)
116 output = output + torch.sum(
117 h_res.unsqueeze(-1) * residual.unsqueeze(-2), dim=2
118 )
119 return output.flatten(2).to(x.dtype)