Merge pull request #4 from PAICookers/dev

Release: v1.1.0

Author: KafCoppelia

.github/workflows/pytest-ci.yml

@@ -0,0 +1,37 @@
+name: Python CI with pytest
+
+on:
+  pull_request:
+    branches: [master, dev]
+
+jobs:
+  pytest-ci:
+    strategy:
+      matrix:
+        python-version: ["3.8", "3.9", "3.10", "3.11"]
+        os: [ubuntu-latest, macos-latest, windows-latest]
+    runs-on: ${{ matrix.os }}
+
+    steps:
+      - uses: actions/checkout@v4
+      - name: Set up Python ${{ matrix.python-version }}
+        uses: actions/setup-python@v5
+        with:
+          python-version: ${{ matrix.python-version }}
+      - name: Install poetry
+        uses: abatilo/actions-poetry@v2
+        with:
+          poetry-version: "1.8.2"
+      - name: Install test dependencies
+        run: |
+          poetry install --with test
+      - name: Run pytest
+        uses: pavelzw/pytest-action@v2
+        with:
+          verbose: false
+          emoji: false
+          job-summary: true
+          custom-arguments: "-q"
+          custom-pytest: "poetry run pytest"
+          click-to-expand: true
+          report-title: "Test Report"

.pre-commit-config.yaml

@@ -13,7 +13,7 @@ repos:
         stages: [commit]
 
   - repo: https://github.com/psf/black
-    rev: 24.4.0
+    rev: 24.4.2
     hooks:
       - id: black
         stages: [commit]
@@ -25,6 +25,11 @@ repos:
         types_or: [markdown, yaml, json]
         stages: [commit]
 
+  - repo: https://github.com/dannysepler/rm_unneeded_f_str
+    rev: v0.2.0
+    hooks:
+      - id: rm-unneeded-f-str
+
   - repo: https://github.com/pre-commit/pre-commit-hooks
     rev: v4.6.0
     hooks:

CHANGELOG.md

@@ -6,3 +6,8 @@
 
 - 为 `ReplicaionId` 新增魔法方法
 - 为 `CoordOffset` 新增 `from_offset` 方法
+
+## v1.1.0
+
+- 添加基础路由类型以支持多芯片
+- 芯片坐标将导出为字符串类型，形如 `"(1, 0)"`

README.md

@@ -8,8 +8,8 @@
     <a href="https://github.com/PAICookers/PAIlib/blob/master/pyproject.toml">
         <img src="https://img.shields.io/pypi/pyversions/paicorelib">
     </a>
-    <a href="https://github.com/PAICookers/PAIlib/releases/tag/v1.0.0">
-        <img src="https://img.shields.io/github/v/release/PAICookers/PAIlib?include_prereleases&color=orange">
+    <a href="https://github.com/PAICookers/PAIlib/releases/tag/v1.1.0">
+        <img src="https://img.shields.io/github/v/release/PAICookers/PAIlib?color=orange">
     </a>
     <a href="https://www.codefactor.io/repository/github/PAICookers/PAIlib">
       <img src="https://img.shields.io/codefactor/grade/github/PAICookers/PAIlib/master?color=red">
@@ -20,6 +20,4 @@
 
 </p>
 
-术语对照表：[Table of Terms](docs/Table-of-Terms.md)
-
 [Changelog](./CHANGELOG.md)

paicorelib/coordinate.py

@@ -15,17 +15,21 @@
 from .hw_defs import HwParams
 
 __all__ = [
+    "ChipCoord",
     "Coord",
+    "CoordAddr",
     "CoordOffset",
     "ReplicationId",
     "CoordLike",
     "RIdLike",
     "to_coord",
+    "to_coords",
     "to_coordoffset",
     "to_rid",
 ]
 
 CoordTuple: TypeAlias = Tuple[int, int]
+CoordAddr: TypeAlias = int
 
 
 def _xy_parser(other: Union[CoordTuple, "CoordOffset"]) -> CoordTuple:
@@ -37,7 +41,7 @@ def _xy_parser(other: Union[CoordTuple, "CoordOffset"]) -> CoordTuple:
         if len(other) != 2:
             raise ValueError(f"expected a tuple of 2 elements, but got {len(other)}.")
 
-        return CoordOffset.from_tuple(other).to_tuple()
+        return CoordOffset(*other).to_tuple()  # check the range of coordoffset
     else:
         return other.to_tuple()
 
@@ -70,11 +74,7 @@ class Coord(_CoordIdentifier):
     )
 
     @classmethod
-    def from_tuple(cls, pos: CoordTuple) -> "Coord":
-        return cls(*pos)
-
-    @classmethod
-    def from_addr(cls, addr: int) -> "Coord":
+    def from_addr(cls, addr: CoordAddr) -> "Coord":
         return cls(addr >> HwParams.N_BIT_CORE_Y, addr & HwParams.CORE_Y_MAX)
 
     def __add__(self, __other: "CoordOffset") -> "Coord":
@@ -219,25 +219,22 @@ def __hash__(self) -> int:
         return hash(self.address)
 
     def __str__(self) -> str:
-        return f"({self.x}, {self.y})"
-
-    def __repr__(self) -> str:
-        return f"Coord({self.x}, {self.y})"
+        return f"({self.x},{self.y})"
 
     def to_tuple(self) -> CoordTuple:
         """Convert to tuple"""
         return (self.x, self.y)
 
     @property
-    def address(self) -> int:
+    def address(self) -> CoordAddr:
         """Convert to address, 10 bits"""
         return (self.x << HwParams.N_BIT_CORE_Y) | self.y
 
 
 @final
 class ReplicationId(Coord):
     @classmethod
-    def from_addr(cls, addr: int) -> "ReplicationId":
+    def from_addr(cls, addr: CoordAddr) -> "ReplicationId":
         return cls(addr >> HwParams.N_BIT_CORE_Y, addr & HwParams.CORE_Y_MAX)
 
     def __and__(self, __other: Union[Coord, "ReplicationId"]) -> "ReplicationId":
@@ -297,10 +294,6 @@ class CoordOffset:
         default=HwParams.CORE_Y_MIN, ge=-HwParams.CORE_Y_MAX, le=HwParams.CORE_Y_MAX
     )
 
-    @classmethod
-    def from_tuple(cls, pos: CoordTuple) -> "CoordOffset":
-        return cls(*pos)
-
     @classmethod
     def from_offset(cls, offset: int) -> "CoordOffset":
         return cls(offset >> HwParams.N_BIT_CORE_Y, offset & HwParams.CORE_Y_MAX)
@@ -488,12 +481,13 @@ def _sum_carry(cx: int, cy: int) -> CoordTuple:
     return cx, cy
 
 
-CoordLike = TypeVar("CoordLike", Coord, int, List[int], CoordTuple)
-RIdLike = TypeVar("RIdLike", ReplicationId, int, List[int], CoordTuple)
+ChipCoord: TypeAlias = Coord
+CoordLike = TypeVar("CoordLike", Coord, CoordAddr, CoordTuple)
+RIdLike = TypeVar("RIdLike", ReplicationId, CoordAddr, CoordTuple)
 
 
 def to_coord(coordlike: CoordLike) -> Coord:
-    if isinstance(coordlike, int):
+    if isinstance(coordlike, CoordAddr):
         return Coord.from_addr(coordlike)
 
     if isinstance(coordlike, (list, tuple)):
@@ -518,7 +512,7 @@ def to_coordoffset(offset: int) -> CoordOffset:
 
 
 def to_rid(ridlike: RIdLike) -> ReplicationId:
-    if isinstance(ridlike, int):
+    if isinstance(ridlike, CoordAddr):
         return ReplicationId.from_addr(ridlike)
 
     if isinstance(ridlike, (list, tuple)):

paicorelib/framelib/frames.py

@@ -102,8 +102,8 @@ def __init__(
     def _payload_reorganized(reg_dict: Dict[str, Any]) -> FrameArrayType:
         # High 8 bits & low 7 bits of tick_wait_start
         tws_high8, tws_low7 = bin_split(reg_dict["tick_wait_start"], 7, 8)
-        # High 3 bits & low 7 bits of test_chip_addrs
-        tca_high3, tca_low7 = bin_split(reg_dict["test_chip_addr"], 7, 3)
+        # High 3 bits & low 7 bits of test_chip_addr
+        tca_high3, tca_low7 = bin_split(reg_dict["test_chip_addr"].address, 7, 3)
 
         reg_frame1 = (
             (reg_dict["weight_width"] & RegF.WEIGHT_WIDTH_MASK)
@@ -571,7 +571,7 @@ def __init__(
             raise ShapeError(f"Size of data must be 1, {_data.size}.")
 
         if _data < np.iinfo(np.int8).min or _data > np.iinfo(np.int8).max:
-            raise ValueError(f"Data out of range np.int8.")
+            raise ValueError("Data out of range np.int8.")
 
         self.data = np.uint8(_data)
         self._axon = int(axon)

paicorelib/hw_defs.py

@@ -25,8 +25,10 @@ class HwParams:
     CORE_Y_MIN = 0
     CORE_Y_MAX = (1 << N_BIT_CORE_Y) - 1
 
+    N_CORE_MAX_INCHIP = 1024
     N_CORE_OFFLINE = 1008
-    """The #N of offline cores."""
+    N_CORE_ONLINE = N_CORE_MAX_INCHIP - N_CORE_OFFLINE
+
     CORE_X_OFFLINE_MIN = CORE_X_MIN
     CORE_Y_OFFLINE_MIN = CORE_Y_MIN
     CORE_X_OFFLINE_MAX = 0b11011

paicorelib/reg_model.py

@@ -1,6 +1,13 @@
 from typing import Literal
 
-from pydantic import BaseModel, ConfigDict, Field, field_serializer, model_validator
+from pydantic import (
+    BaseModel,
+    ConfigDict,
+    Field,
+    field_serializer,
+    field_validator,
+    model_validator,
+)
 from pydantic.type_adapter import TypeAdapter
 from pydantic.types import NonNegativeInt
 from typing_extensions import TypedDict  # Use `typing_extensions.TypedDict`.
@@ -155,8 +162,8 @@ def _target_lcn(self, target_lcn: LCNExtensionType) -> int:
         return target_lcn.value
 
     @field_serializer("test_chip_addr")
-    def _test_chip_addr(self, test_chip_addr: Coord) -> int:
-        return test_chip_addr.address
+    def _test_chip_addr(self, test_chip_addr: Coord) -> str:
+        return str(test_chip_addr)
 
 
 ParamsReg = CoreParams
@@ -175,7 +182,7 @@ class _ParamsRegDict(TypedDict):
     tick_wait_end: int
     snn_en: int
     target_LCN: int
-    test_chip_addr: int
+    test_chip_addr: Coord
 
 
 ParamsRegChecker = TypeAdapter(_ParamsRegDict)

paicorelib/routing_defs.py

@@ -17,6 +17,9 @@
     "get_replication_id",
 ]
 
+N_ROUTING_LEVEL = 6  # L0~L5
+MAX_ROUTING_PATH_LENGTH = N_ROUTING_LEVEL - 1
+
 
 @unique
 class RoutingLevel(IntEnum):
@@ -35,26 +38,25 @@ class RoutingLevel(IntEnum):
 
 @unique
 class RoutingDirection(Enum):
-    """Indicate the 4 children of a cluster.
-
-    NOTE: There is an X/Y coordinate priority method to specify the order.
-    """
+    """Indicate the direction of the four children in the cluster."""
 
     X0Y0 = (0, 0)
     X0Y1 = (0, 1)
     X1Y0 = (1, 0)
     X1Y1 = (1, 1)
     ANY = (-1, -1)
-    """Don't care when a level direction is `ANY`."""
 
     def to_index(self) -> int:
         """Convert the direction to index in children list."""
         if self is RoutingDirection.ANY:
-            raise TypeError(f"The direction of routing is not specified.")
+            raise TypeError("The direction of routing is not specified.")
 
         x, y = self.value
 
-        return (x << 1) + y
+        if HwParams.COORD_Y_PRIORITY:
+            return (x << 1) + y
+        else:
+            return (y << 1) + x
 
 
 @unique
@@ -80,14 +82,18 @@ class RoutingCost(NamedTuple):
     n_L2: int
     n_L3: int
     n_L4: int
+    n_L5: int = 1
 
     def get_routing_level(self) -> RoutingLevel:
-        """Return the routing cluster level.
+        """Return the routing cluster level. If the #N of Lx-level > 1, then we need a  \
+            cluster with level Lx+1. And we need the #N of routing sub-level clusters.
 
-        If the #N of Lx-level > 1, then we need a cluster with level Lx+1.
-        And we need the #N of routing sub-level clusters.
+        XXX: At present, if #N of L5 > 1, raise exception.
         """
-        for i in reversed(range(5)):
+        if self.n_L5 > 1:
+            raise ValueError(f"#N of L5-level node out of range, got {self.n_L5}.")
+
+        for i in reversed(range(N_ROUTING_LEVEL)):
             if self[i] > 1:
                 return RoutingLevel(i + 1)
 
@@ -114,24 +120,35 @@ def get_routing_level(self) -> RoutingLevel:
 class RoutingCoord(NamedTuple):
     """Use router directions to represent the coordinate of a cluster."""
 
-    L4: RoutingDirection
-    L3: RoutingDirection
-    L2: RoutingDirection
-    L1: RoutingDirection
-    L0: RoutingDirection
+    L4: RoutingDirection = RoutingDirection.ANY
+    L3: RoutingDirection = RoutingDirection.ANY
+    L2: RoutingDirection = RoutingDirection.ANY
+    L1: RoutingDirection = RoutingDirection.ANY
+    L0: RoutingDirection = RoutingDirection.ANY
+
+    def _coord_specify_check(self) -> None:
+        if RoutingDirection.ANY in self:
+            raise ValueError(
+                f"The direction of routing is not specified completely, got {self}."
+            )
+
+    def _L0_property(self) -> None:
+        if self.level > RoutingLevel.L0:
+            raise AttributeError(
+                f"This property is only for L0-level cluster, but self is {self.level}."
+            )
 
     @property
     def level(self) -> RoutingLevel:
         for i in range(len(self)):
             if self[i] is RoutingDirection.ANY:
-                return RoutingLevel(5 - i)
+                return RoutingLevel(MAX_ROUTING_PATH_LENGTH - i)
 
         return RoutingLevel.L0
 
-    @property
-    def coordinate(self) -> Coord:
-        if self.level > RoutingLevel.L0:
-            raise AttributeError("This property is only for L0-level cluster.")
+    def to_coord(self) -> Coord:
+        self._L0_property()
+        self._coord_specify_check()
 
         x = (
             (self.L4.value[0] << 4)
@@ -157,15 +174,13 @@ def get_routing_consumption(n_core: int) -> RoutingCost:
     n_sub_node = HwParams.N_SUB_ROUTING_NODE
 
     # Find the nearest #N(=2^X) to accommodate `n_core` L0-level clusters.
-    # If n_core = 5, return 8.
-    # If n_core = 20, return 32.
-    n_L0 = 1 << (n_core - 1).bit_length()
-    n_L1 = 1 if n_L0 < n_sub_node else (n_L0 // n_sub_node)
-    n_L2 = 1 if n_L1 < n_sub_node else (n_L1 // n_sub_node)
-    n_L3 = 1 if n_L2 < n_sub_node else (n_L2 // n_sub_node)
-    n_L4 = 1 if n_L3 < n_sub_node else (n_L3 // n_sub_node)
-
-    return RoutingCost(n_L0, n_L1, n_L2, n_L3, n_L4)
+    n_Lx = [0] * N_ROUTING_LEVEL
+    n_Lx[0] = 1 << (n_core - 1).bit_length()
+
+    for i in range(N_ROUTING_LEVEL - 1):
+        n_Lx[1 + i] = 1 if n_Lx[i] < n_sub_node else (n_Lx[i] // n_sub_node)
+
+    return RoutingCost(*n_Lx)
 
 
 def get_replication_id(coords: Sequence[Coord]) -> RId: