Coverage for  / home / jenkins / .local / lib / python3.10 / site-packages / hyper_parallel / auto_parallel / config_adapter / _normalized_config.py: 100%

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"""Shared type definitions for auto parallel strategy search configuration.""" 

16 

17from dataclasses import dataclass, field 

18from typing import Any, Dict, List, Optional, Literal 

19 

20from hyper_parallel.auto_parallel._model_spec import ModelSpec, model_fields 

21 

22 

23@dataclass 

24class NormalizedConfig: 

25 """Aggregate container for a parallel strategy search task. 

26 

27 Holds all configuration sections as plain dicts for maximum 

28 compatibility with PR631's Config class (sapp_nd.nd.common.config). 

29 ``model_spec`` holds the model IR in its mapping form: the fields of 

30 :class:`~hyper_parallel.auto_parallel._model_spec.ModelSpec`, which owns 

31 the list of them and what each one requires. Call :meth:`model` for the 

32 typed, validated object. Keys the IR does not declare are carried 

33 through untouched for the adapter's own use, such as the micro-batch 

34 size; how the run loads, computes and optimizes the model is ``run``'s. 

35 

36 Args: 

37 model_spec: Model architecture parameters, in the shape 

38 :class:`ModelSpec` defines. 

39 cluster_spec: Hardware cluster description. 

40 search_space: Parallel dimension candidate values, e.g. 

41 ``{"dp": [1,2,4], "tp": [1,2,4,8], "pp": [1,2], "cp": [1], "ep": [1]}``. 

42 constraint: User-imposed constraints (global_batch_size, 

43 memory_limit_gb, fixed_*_degree). 

44 estimator: Estimation algorithm parameters. Optional key: 

45 ``cp_algo`` (``"colossalai_cp"`` | ``"ulysses_cp"`` | ``"hybrid_cp"``, 

46 default ``"colossalai_cp"``). 

47 pp_config: Pipeline-parallel specific configuration. 

48 run: What the train.yaml states about the run, in its own sections 

49 and names: the model's dtypes, FSDP's precision and resharding, 

50 the optimizer, gradient clipping and the accelerator's settings. 

51 The search runner lays the strategy it searches over it, so the 

52 rest reaches the cost model as the train.yaml states it. 

53 parallelism_summary: One line naming what every parallelism 

54 dimension resolved to, so a dimension that was silently pinned 

55 or silently freed is visible. 

56 resolved_strategy: Final resolved strategy, populated after search. 

57 """ 

58 

59 model_spec: Dict[str, Any] = field(default_factory=dict) 

60 cluster_spec: Dict[str, Any] = field(default_factory=dict) 

61 search_space: Dict[str, List[int]] = field(default_factory=dict) 

62 constraint: Dict[str, Any] = field(default_factory=dict) 

63 estimator: Dict[str, Any] = field(default_factory=dict) 

64 pp_config: Dict[str, Any] = field(default_factory=dict) 

65 run: Dict[str, Any] = field(default_factory=dict) 

66 parallelism_summary: str = "" 

67 resolved_strategy: Optional[Dict[str, Any]] = None 

68 

69 def model(self) -> ModelSpec: 

70 """Return ``model_spec`` as the typed, validated model IR. 

71 

72 Returns: 

73 The parsed spec. 

74 

75 Raises: 

76 ModelSpecError: If a required field is missing or the declared 

77 fields contradict each other. 

78 """ 

79 return ModelSpec.from_dict(model_fields(self.model_spec)) 

80 

81 def to_dict(self) -> Dict[str, Any]: 

82 """Serialize all config sections to a nested dictionary.""" 

83 result: Dict[str, Any] = { 

84 "model_spec": dict(self.model_spec), 

85 "cluster_spec": dict(self.cluster_spec), 

86 "search_space": dict(self.search_space), 

87 "constraint": dict(self.constraint), 

88 "estimator": dict(self.estimator), 

89 "pp_config": dict(self.pp_config), 

90 "run": dict(self.run), 

91 } 

92 if self.resolved_strategy is not None: 

93 result["resolved_strategy"] = dict(self.resolved_strategy) 

94 return result 

95 

96 

97@dataclass 

98class ValidationError: 

99 """A single validation error or warning discovered during config validation. 

100 

101 Args: 

102 field_path: Dot-separated path to the offending field 

103 (e.g. ``"model_spec.dim"``). 

104 message: Human-readable description of the problem. 

105 severity: Error severity level (``"error"`` or ``"warning"``). 

106 """ 

107 

108 field_path: str 

109 message: str 

110 severity: Literal["error", "warning"] = "error" 

111 

112 

113ValidationSeverity = Literal["error", "warning"]