From e2f3e74c93779d0ee9bdd151dfbe70bb850a2886 Mon Sep 17 00:00:00 2001
From: KafCoppelia <k740677208@gmail.com>
Date: Thu, 7 Mar 2024 16:58:35 +0800
Subject: [PATCH 01/68] =?UTF-8?q?=E2=9A=A1=EF=B8=8F=20added=20`Identity`.?=
 =?UTF-8?q?=20Renamed=20&=20exposed=20`SynConnType`=20to=20pb?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

---
 docs/Guide-of-PAIBox.md       | 18 +++++++++++-------
 paibox/__init__.py            |  3 ++-
 paibox/synapses/__init__.py   |  4 ++--
 paibox/synapses/synapses.py   | 29 +++++++++--------------------
 paibox/synapses/transforms.py | 16 ++++++++--------
 5 files changed, 32 insertions(+), 38 deletions(-)

diff --git a/docs/Guide-of-PAIBox.md b/docs/Guide-of-PAIBox.md
index 2e631565..96eddcf1 100644
--- a/docs/Guide-of-PAIBox.md
+++ b/docs/Guide-of-PAIBox.md
@@ -178,7 +178,7 @@ print(output)
 PAIBox中，突触用于连接不同神经元组，并包含了连接关系以及权重信息。以全连接类型的突触为实例：
 
 ```python
-s1= pb.synapses.NoDecay(source=n1, dest=n2, weights=weight1, conn_type=pb.synapses.ConnType.All2All, name='s1')
+s1= pb.synapses.NoDecay(source=n1, dest=n2, weights=weight1, conn_type=pb.SynConnType.All2All, name='s1')
 ```
 
 其中：
@@ -210,7 +210,7 @@ s1= pb.synapses.NoDecay(source=n1, dest=n2, weights=weight1, conn_type=pb.synaps
 
 两组神经元之间依次单对单连接，这要求**前向与后向神经元数目相同**。其权重 `weights` 主要有以下几种输入类型：
 
-- 标量：默认为1。这表示前层的各个神经元输出线性地输入到后层神经元。这种情况等同于 `ConnType.BYPASS` 旁路连接。
+- 标量：默认为1。这表示前层的各个神经元输出线性地输入到后层神经元，即 $\lambda\cdot\mathbf{I}$
 
   ```python
   n1 = pb.neuron.IF(shape=5,threshold=1)
@@ -242,6 +242,10 @@ s1= pb.synapses.NoDecay(source=n1, dest=n2, weights=weight1, conn_type=pb.synaps
 
   其权重实际上为 `N*N` 矩阵，其中 `N` 为前向/后向神经元组数目。
 
+#### Identity 恒等映射
+
+具有缩放因子的单对单连接，即 `One2One` 中权重项为标量的特殊情况。
+
 #### MatConn 一般连接
 
 普通的神经元连接类型，仅可以通过矩阵设置其权重 `weights`。
@@ -473,8 +477,8 @@ class fcnet(pb.Network):
         self.i1 = pb.InputProj(input=pe, shape_out=(784,))
         self.n1 = pb.neuron.IF(128, threshold=128, reset_v=0, tick_wait_start=1)
         self.n2 = pb.neuron.IF(10, threshold=128, reset_v=0, tick_wait_start=2)
-        self.s1 = pb.synapses.NoDecay(self.i1, self.n1, weights=weight1, conn_type=pb.synapses.ConnType.All2All)
-        self.s2 = pb.synapses.NoDecay(self.n1, self.n2, weights=weight2, conn_type=pb.synapses.ConnType.All2All)
+        self.s1 = pb.synapses.NoDecay(self.i1, self.n1, weights=weight1, conn_type=pb.SynConnType.All2All)
+        self.s2 = pb.synapses.NoDecay(self.n1, self.n2, weights=weight2, conn_type=pb.SynConnType.All2All)
 ```
 
 #### 容器类型
@@ -507,7 +511,7 @@ class ReusedStructure(pb.Network):
         self.pre_n = pb.LIF((10,), 10)
         self.post_n = pb.LIF((10,), 10)
         self.syn = pb.NoDecay(
-            self.pre_n, self.post_n, conn_type=pb.synapses.ConnType.All2All, weights=weight
+            self.pre_n, self.post_n, conn_type=pb.SynConnType.All2All, weights=weight
         )
 
 class Net(pb.Network):
@@ -518,12 +522,12 @@ class Net(pb.Network):
         self.s1 = pb.NoDecay(
             self.inp1,
             subnet1.pre_n,
-            conn_type=pb.synapses.ConnType.One2One,
+            conn_type=pb.SynConnType.One2One,
         )
         self.s2 = pb.NoDecay(
             subnet1.post_n,
             subnet2.pre_n,
-            conn_type=pb.synapses.ConnType.One2One,
+            conn_type=pb.SynConnType.One2One,
         )
 
         super().__init__(subnet1, subnet2) # Necessary!
diff --git a/paibox/__init__.py b/paibox/__init__.py
index 863ef168..e66df694 100644
--- a/paibox/__init__.py
+++ b/paibox/__init__.py
@@ -10,7 +10,7 @@
 from .projection import InputProj as InputProj
 from .simulator import Probe as Probe
 from .simulator import Simulator as Simulator
-from .synapses import NoDecay as NoDecay
+from .synapses import NoDecay as NoDecay, SynConnType as SynConnType
 
 __all__ = [
     "Mapper",
@@ -20,6 +20,7 @@
     "NodeList",
     "InputProj",
     "Simulator",
+    "SynConnType",
     "Probe",
     "BACKEND_CONFIG",
     "FRONTEND_ENV",
diff --git a/paibox/synapses/__init__.py b/paibox/synapses/__init__.py
index d7518cb4..53355470 100644
--- a/paibox/synapses/__init__.py
+++ b/paibox/synapses/__init__.py
@@ -1,6 +1,6 @@
 from .synapses import RIGISTER_MASTER_KEY_FORMAT
 from .synapses import NoDecay as NoDecay
 from .synapses import SynSys as SynSys
-from .transforms import ConnType as ConnType
+from .transforms import ConnType as SynConnType
 
-__all__ = ["NoDecay", "SynSys"]
+__all__ = ["NoDecay", "SynSys", "SynConnType"]
diff --git a/paibox/synapses/synapses.py b/paibox/synapses/synapses.py
index 56be7a4d..f6c054a6 100644
--- a/paibox/synapses/synapses.py
+++ b/paibox/synapses/synapses.py
@@ -18,18 +18,10 @@
 
 
 class Synapses:
-    """A map connected between neurons of the previous `Node`, \
-        and axons of the following `Node`.
-
-    User can use connectivity matrix or COO to represent the \
-        connectivity of synapses.
-    """
-
     def __init__(
         self,
         source: Union[NeuDyn, InputProj],
         dest: NeuDyn,
-        /,
         conn_type: ConnType,
     ) -> None:
         """
@@ -43,7 +35,7 @@ def __init__(
         self._check(conn_type)
 
     def _check(self, conn_type: ConnType) -> None:
-        if conn_type is ConnType.One2One or conn_type is ConnType.BYPASS:
+        if conn_type is ConnType.One2One or conn_type is ConnType.Identity:
             if self.num_in != self.num_out:
                 raise ShapeError(
                     f"The number of source & destination neurons must "
@@ -124,8 +116,13 @@ def __init__(
 
         if conn_type is ConnType.One2One:
             self.comm = OneToOne(self.num_in, weights)
-        elif conn_type is ConnType.BYPASS:
-            self.comm = ByPass(self.num_in)
+        elif conn_type is ConnType.Identity:
+            if not isinstance(weights, (int, np.integer)):
+                raise TypeError(
+                    f"Expected type int, np.integer, but got type {type(weights)}"
+                )
+
+            self.comm = Identity(self.num_in, weights)
         elif conn_type is ConnType.All2All:
             self.comm = AllToAll((self.num_in, self.num_out), weights)
         else:  # MatConn
@@ -161,7 +158,7 @@ def update(
 
     def reset_state(self, *args, **kwargs) -> None:
         # TODO Add other initialization methods in the future.
-        self.reset()  # Call reset of `StatusMemory`.
+        self.reset_memory()  # Call reset of `StatusMemory`.
 
     @property
     def output(self) -> NDArray[np.int32]:
@@ -179,11 +176,3 @@ def weight_precision(self) -> WP:
     def connectivity(self):
         """The connectivity matrix in `np.ndarray` format."""
         return self.comm.connectivity
-
-    def __repr__(self) -> str:
-        name = self.__class__.__name__
-        return (
-            f"{name}(name={self.name}, \n"
-            f'{" " * len(name)} source={self.source}, \n'
-            f'{" " * len(name)} dest={self.dest})'
-        )
diff --git a/paibox/synapses/transforms.py b/paibox/synapses/transforms.py
index 34577e12..800b9108 100644
--- a/paibox/synapses/transforms.py
+++ b/paibox/synapses/transforms.py
@@ -6,10 +6,10 @@
 from paicorelib import WeightPrecision as WP
 
 from paibox.exceptions import ShapeError
-from paibox.types import DataArrayType, WeightType
+from paibox.types import DataArrayType, IntScalarType, WeightType
 from paibox.utils import is_shape
 
-__all__ = ["ConnType", "OneToOne", "ByPass", "AllToAll", "MaskedLinear"]
+__all__ = ["ConnType", "OneToOne", "AllToAll", "Identity", "MaskedLinear"]
 
 
 MAX_INT1 = np.int8(1)
@@ -30,7 +30,8 @@ class ConnType(Enum):
     One2One = auto()
     """One-to-one connection."""
 
-    BYPASS = auto()
+    Identity = auto()
+    """Identity connection with scaling factor."""
 
     All2All = auto()
     """All-to-all connection."""
@@ -126,15 +127,14 @@ def connectivity(self):
         )
 
 
-class ByPass(OneToOne):
-    def __init__(self, num: int) -> None:
+class Identity(OneToOne):
+    def __init__(self, num: int, scaling_factor: IntScalarType = 1) -> None:
         """
         Arguments:
             - num: number of neurons.
-
-        NOTE: The weights are always 1.
+            - scaling_factor: scaling factor.
         """
-        super().__init__(num, 1)
+        super().__init__(num, scaling_factor)
 
 
 class AllToAll(Transform):

From 6a561320403bae2ae2a4807e8d248941c4d40205 Mon Sep 17 00:00:00 2001
From: KafCoppelia <k740677208@gmail.com>
Date: Thu, 7 Mar 2024 16:59:32 +0800
Subject: [PATCH 02/68] =?UTF-8?q?=E2=9C=85=20sync=20changes?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

---
 examples/mnist/example1/model.py  |  8 ++--
 tests/backend/conftest.py         | 80 +++++++++++++++----------------
 tests/conftest.py                 | 24 +++++-----
 tests/neuron/conftest.py          | 14 +++---
 tests/simulator/test_simulator.py | 18 +++----
 tests/synapses/test_synapses.py   | 32 ++++++-------
 tests/test_network.py             | 26 +++++-----
 7 files changed, 101 insertions(+), 101 deletions(-)

diff --git a/examples/mnist/example1/model.py b/examples/mnist/example1/model.py
index 566ec65c..ab711ddb 100644
--- a/examples/mnist/example1/model.py
+++ b/examples/mnist/example1/model.py
@@ -13,13 +13,13 @@ def __init__(self, weight1, Vthr1, weight2, Vthr2):
             self.i1,
             self.n1,
             weights=weight1[:392],
-            conn_type=pb.synapses.ConnType.All2All,
+            conn_type=pb.SynConnType.All2All,
         )
         self.s2 = pb.synapses.NoDecay(
             self.i2,
             self.n1,
             weights=weight1[392:],
-            conn_type=pb.synapses.ConnType.All2All,
+            conn_type=pb.SynConnType.All2All,
         )
 
         # tick_wait_start = 2 for second layer
@@ -33,13 +33,13 @@ def __init__(self, weight1, Vthr1, weight2, Vthr2):
             self.n1,
             self.n2,
             weights=weight2[:, :5],
-            conn_type=pb.synapses.ConnType.All2All,
+            conn_type=pb.SynConnType.All2All,
         )
         self.s4 = pb.synapses.NoDecay(
             self.n1,
             self.n3,
             weights=weight2[:, 5:],
-            conn_type=pb.synapses.ConnType.All2All,
+            conn_type=pb.SynConnType.All2All,
         )
 
         self.probe1 = pb.simulator.Probe(target=self.n2, attr="spike")
diff --git a/tests/backend/conftest.py b/tests/backend/conftest.py
index 629ac717..030ab0ae 100644
--- a/tests/backend/conftest.py
+++ b/tests/backend/conftest.py
@@ -98,13 +98,13 @@ def __init__(self):
         self.n2 = pb.TonicSpiking(1200, 3, name="n2_1", tick_wait_start=2)
         self.n3 = pb.TonicSpiking(800, 4, name="n3_1", tick_wait_start=3)
         self.s1 = pb.NoDecay(
-            self.inp1, self.n1, conn_type=pb.synapses.ConnType.All2All, name="s1_1"
+            self.inp1, self.n1, conn_type=pb.SynConnType.All2All, name="s1_1"
         )
         self.s2 = pb.NoDecay(
-            self.n1, self.n2, conn_type=pb.synapses.ConnType.All2All, name="s2_1"
+            self.n1, self.n2, conn_type=pb.SynConnType.All2All, name="s2_1"
         )
         self.s3 = pb.NoDecay(
-            self.n2, self.n3, conn_type=pb.synapses.ConnType.All2All, name="s3_1"
+            self.n2, self.n3, conn_type=pb.SynConnType.All2All, name="s3_1"
         )
 
 
@@ -121,13 +121,13 @@ def __init__(self):
         self.n1 = pb.TonicSpiking(30, 3, name="n1_2", tick_wait_start=1)
         self.n2 = pb.TonicSpiking(20, 3, name="n2_2", tick_wait_start=2)
         self.s1 = pb.NoDecay(
-            self.inp1, self.n1, conn_type=pb.synapses.ConnType.All2All, name="s1_2"
+            self.inp1, self.n1, conn_type=pb.SynConnType.All2All, name="s1_2"
         )
         self.s2 = pb.NoDecay(
-            self.inp2, self.n1, conn_type=pb.synapses.ConnType.All2All, name="s2_2"
+            self.inp2, self.n1, conn_type=pb.SynConnType.All2All, name="s2_2"
         )
         self.s3 = pb.NoDecay(
-            self.n1, self.n2, conn_type=pb.synapses.ConnType.All2All, name="s3_2"
+            self.n1, self.n2, conn_type=pb.SynConnType.All2All, name="s3_2"
         )
 
 
@@ -146,19 +146,19 @@ def __init__(self):
         self.n4 = pb.TonicSpiking(300, 4, name="n4", tick_wait_start=2)
 
         self.s1 = pb.NoDecay(
-            self.inp, self.n1, conn_type=pb.synapses.ConnType.One2One, name="s1"
+            self.inp, self.n1, conn_type=pb.SynConnType.One2One, name="s1"
         )
         self.s2 = pb.NoDecay(
-            self.n1, self.n2, conn_type=pb.synapses.ConnType.All2All, name="s2"
+            self.n1, self.n2, conn_type=pb.SynConnType.All2All, name="s2"
         )
         self.s3 = pb.NoDecay(
-            self.n2, self.n3, conn_type=pb.synapses.ConnType.All2All, name="s3"
+            self.n2, self.n3, conn_type=pb.SynConnType.All2All, name="s3"
         )
         self.s4 = pb.NoDecay(
-            self.n1, self.n4, conn_type=pb.synapses.ConnType.All2All, name="s4"
+            self.n1, self.n4, conn_type=pb.SynConnType.All2All, name="s4"
         )
         self.s5 = pb.NoDecay(
-            self.n4, self.n2, conn_type=pb.synapses.ConnType.All2All, name="s5"
+            self.n4, self.n2, conn_type=pb.SynConnType.All2All, name="s5"
         )
 
 
@@ -176,19 +176,19 @@ def __init__(self):
         self.n3 = pb.TonicSpiking(400, 4, name="n3", tick_wait_start=2)
         self.n4 = pb.TonicSpiking(400, 4, name="n4", tick_wait_start=3)
         self.s1 = pb.NoDecay(
-            self.inp1, self.n1, conn_type=pb.synapses.ConnType.All2All, name="s1"
+            self.inp1, self.n1, conn_type=pb.SynConnType.All2All, name="s1"
         )
         self.s2 = pb.NoDecay(
-            self.n1, self.n2, conn_type=pb.synapses.ConnType.All2All, name="s2"
+            self.n1, self.n2, conn_type=pb.SynConnType.All2All, name="s2"
         )
         self.s3 = pb.NoDecay(
-            self.n1, self.n3, conn_type=pb.synapses.ConnType.All2All, name="s3"
+            self.n1, self.n3, conn_type=pb.SynConnType.All2All, name="s3"
         )
         self.s4 = pb.NoDecay(
-            self.n2, self.n4, conn_type=pb.synapses.ConnType.One2One, name="s4"
+            self.n2, self.n4, conn_type=pb.SynConnType.One2One, name="s4"
         )
         self.s5 = pb.NoDecay(
-            self.n3, self.n4, conn_type=pb.synapses.ConnType.One2One, name="s5"
+            self.n3, self.n4, conn_type=pb.SynConnType.One2One, name="s5"
         )
 
 
@@ -206,13 +206,13 @@ def __init__(self):
         self.n2 = pb.TonicSpiking(20, 3, name="n2", tick_wait_start=2)
 
         self.s1 = pb.NoDecay(
-            self.inp1, self.n1, conn_type=pb.synapses.ConnType.All2All, name="s1"
+            self.inp1, self.n1, conn_type=pb.SynConnType.All2All, name="s1"
         )
         self.s2 = pb.NoDecay(
-            self.n1, self.n2, conn_type=pb.synapses.ConnType.All2All, name="s2"
+            self.n1, self.n2, conn_type=pb.SynConnType.All2All, name="s2"
         )
         self.s3 = pb.NoDecay(
-            self.inp2, self.n2, conn_type=pb.synapses.ConnType.All2All, name="s3"
+            self.inp2, self.n2, conn_type=pb.SynConnType.All2All, name="s3"
         )
 
 
@@ -230,19 +230,19 @@ def __init__(self, connect_n4: bool = False):
         self.n3 = pb.TonicSpiking(30, 4, name="n3", tick_wait_start=2)
 
         self.s1 = pb.NoDecay(
-            self.inp1, self.n1, conn_type=pb.synapses.ConnType.All2All, name="s1"
+            self.inp1, self.n1, conn_type=pb.SynConnType.All2All, name="s1"
         )
         self.s2 = pb.NoDecay(
-            self.n1, self.n2, conn_type=pb.synapses.ConnType.All2All, name="s2"
+            self.n1, self.n2, conn_type=pb.SynConnType.All2All, name="s2"
         )
         self.s3 = pb.NoDecay(
-            self.n1, self.n3, conn_type=pb.synapses.ConnType.All2All, name="s3"
+            self.n1, self.n3, conn_type=pb.SynConnType.All2All, name="s3"
         )
 
         if connect_n4:
             self.n4 = pb.TonicSpiking(50, 4, name="n4", tick_wait_start=3)
             self.s4 = pb.NoDecay(
-                self.n3, self.n4, conn_type=pb.synapses.ConnType.All2All, name="s4"
+                self.n3, self.n4, conn_type=pb.SynConnType.All2All, name="s4"
             )
 
 
@@ -261,16 +261,16 @@ def __init__(self):
         self.n3 = pb.TonicSpiking(30, 3, name="n3", tick_wait_start=2)
 
         self.s1 = pb.NoDecay(
-            self.inp1, self.n1, conn_type=pb.synapses.ConnType.All2All, name="s1"
+            self.inp1, self.n1, conn_type=pb.SynConnType.All2All, name="s1"
         )
         self.s2 = pb.NoDecay(
-            self.n1, self.n2, conn_type=pb.synapses.ConnType.All2All, name="s2"
+            self.n1, self.n2, conn_type=pb.SynConnType.All2All, name="s2"
         )
         self.s3 = pb.NoDecay(
-            self.inp2, self.n1, conn_type=pb.synapses.ConnType.All2All, name="s3"
+            self.inp2, self.n1, conn_type=pb.SynConnType.All2All, name="s3"
         )
         self.s4 = pb.NoDecay(
-            self.n1, self.n3, conn_type=pb.synapses.ConnType.All2All, name="s4"
+            self.n1, self.n3, conn_type=pb.SynConnType.All2All, name="s4"
         )
 
 
@@ -293,7 +293,7 @@ def __init__(self, n_onodes: int):
                 pb.NoDecay(
                     self.inp1,
                     self.n_list[i],
-                    conn_type=pb.synapses.ConnType.All2All,
+                    conn_type=pb.SynConnType.All2All,
                     name=f"s_{i}",
                 )
             )
@@ -321,35 +321,35 @@ def __init__(self, seed: int):
             self.inp1,
             self.n1,
             weights=rng.randint(-8, 8, size=(10, 10), dtype=np.int8),
-            conn_type=pb.synapses.ConnType.MatConn,
+            conn_type=pb.SynConnType.MatConn,
             name="s1",
         )
         self.s2 = pb.NoDecay(
             self.n1,
             self.n2,
             weights=rng.randint(-8, 8, size=(10, 10), dtype=np.int8),
-            conn_type=pb.synapses.ConnType.MatConn,
+            conn_type=pb.SynConnType.MatConn,
             name="s2",
         )
         self.s3 = pb.NoDecay(
             self.n1,
             self.n3,
             weights=rng.randint(-8, 8, size=(10, 10), dtype=np.int8),
-            conn_type=pb.synapses.ConnType.MatConn,
+            conn_type=pb.SynConnType.MatConn,
             name="s3",
         )
         self.s4 = pb.NoDecay(
             self.n2,
             self.n4,
             weights=rng.randint(-8, 8, size=(10, 4), dtype=np.int8),
-            conn_type=pb.synapses.ConnType.MatConn,
+            conn_type=pb.SynConnType.MatConn,
             name="s4",
         )
         self.s5 = pb.NoDecay(
             self.n3,
             self.n4,
             weights=rng.randint(-8, 8, size=(10, 4), dtype=np.int8),
-            conn_type=pb.synapses.ConnType.MatConn,
+            conn_type=pb.SynConnType.MatConn,
             name="s5",
         )
 
@@ -373,35 +373,35 @@ def __init__(self, seed: int) -> None:
             self.inp1,
             self.n1,
             weights=rng.randint(-128, 128, size=(10, 10), dtype=np.int8),
-            conn_type=pb.synapses.ConnType.MatConn,
+            conn_type=pb.SynConnType.MatConn,
             name="s1",
         )
         self.s2 = pb.NoDecay(
             self.n1,
             self.n2,
             weights=rng.randint(-128, 128, size=(10, 10), dtype=np.int8),
-            conn_type=pb.synapses.ConnType.MatConn,
+            conn_type=pb.SynConnType.MatConn,
             name="s2",
         )
         self.s3 = pb.NoDecay(
             self.n1,
             self.n3,
             weights=rng.randint(-128, 128, size=(10, 10), dtype=np.int8),
-            conn_type=pb.synapses.ConnType.MatConn,
+            conn_type=pb.SynConnType.MatConn,
             name="s3",
         )
         self.s4 = pb.NoDecay(
             self.n2,
             self.n4,
             weights=rng.randint(-128, 128, size=(10, 4), dtype=np.int8),
-            conn_type=pb.synapses.ConnType.MatConn,
+            conn_type=pb.SynConnType.MatConn,
             name="s4",
         )
         self.s5 = pb.NoDecay(
             self.n3,
             self.n4,
             weights=rng.randint(-128, 128, size=(10, 4), dtype=np.int8),
-            conn_type=pb.synapses.ConnType.MatConn,
+            conn_type=pb.SynConnType.MatConn,
             name="s5",
         )
 
@@ -425,10 +425,10 @@ def __init__(self):
         self.n_list = n_list
 
         self.s1 = pb.synapses.NoDecay(
-            n_list[0], n_list[1], conn_type=pb.synapses.ConnType.All2All
+            n_list[0], n_list[1], conn_type=pb.SynConnType.All2All
         )
         self.s2 = pb.synapses.NoDecay(
-            n_list[1], n_list[2], conn_type=pb.synapses.ConnType.All2All
+            n_list[1], n_list[2], conn_type=pb.SynConnType.All2All
         )
 
         self.probe1 = pb.Probe(self.n_list[1], "output", name="n2_out")
diff --git a/tests/conftest.py b/tests/conftest.py
index 3706630b..fa715e11 100644
--- a/tests/conftest.py
+++ b/tests/conftest.py
@@ -13,7 +13,7 @@ def __init__(self):
         self.inp1 = pb.InputProj(1, shape_out=(1,))
         self.n1 = pb.TonicSpiking(1, 3, tick_wait_start=2, delay=1)
         self.s1 = pb.NoDecay(
-            self.inp1, self.n1, weights=1, conn_type=pb.synapses.ConnType.One2One
+            self.inp1, self.n1, weights=1, conn_type=pb.SynConnType.One2One
         )
 
         self.probe1 = pb.Probe(self.s1, "output", name="s2_out")
@@ -34,10 +34,10 @@ def __init__(self):
         self.n2 = pb.TonicSpiking(1, 2, tick_wait_start=3)
 
         self.s1 = pb.NoDecay(
-            self.inp1, self.n1, weights=1, conn_type=pb.synapses.ConnType.One2One
+            self.inp1, self.n1, weights=1, conn_type=pb.SynConnType.One2One
         )
         self.s2 = pb.NoDecay(
-            self.n1, self.n2, weights=1, conn_type=pb.synapses.ConnType.All2All
+            self.n1, self.n2, weights=1, conn_type=pb.SynConnType.All2All
         )
 
         self.probe1 = pb.Probe(self.s2, "output", name="s2_out")
@@ -70,10 +70,10 @@ def __init__(self):
         self.n_list = n_list
 
         self.s1 = pb.synapses.NoDecay(
-            n_list[0], n_list[1], conn_type=pb.synapses.ConnType.All2All
+            n_list[0], n_list[1], conn_type=pb.SynConnType.All2All
         )
         self.s2 = pb.synapses.NoDecay(
-            n_list[1], n_list[2], conn_type=pb.synapses.ConnType.All2All
+            n_list[1], n_list[2], conn_type=pb.SynConnType.All2All
         )
 
         self.probe1 = pb.Probe(self.n_list[1], "output", name="n2_out")
@@ -91,15 +91,15 @@ def __init__(self):
         self.n1 = pb.neuron.TonicSpiking(2, 3)
         self.n2 = pb.neuron.TonicSpiking(2, 3)
         self.s1 = pb.synapses.NoDecay(
-            self.n1, self.n2, conn_type=pb.synapses.ConnType.All2All
+            self.n1, self.n2, conn_type=pb.SynConnType.All2All
         )
         self.n3 = pb.neuron.TonicSpiking(2, 4)
         self.n4 = pb.neuron.TonicSpiking(2, 3)
         self.s2 = pb.synapses.NoDecay(
-            self.n2, self.n4, conn_type=pb.synapses.ConnType.All2All
+            self.n2, self.n4, conn_type=pb.SynConnType.All2All
         )
         self.s3 = pb.synapses.NoDecay(
-            self.n3, self.n4, conn_type=pb.synapses.ConnType.All2All
+            self.n3, self.n4, conn_type=pb.SynConnType.All2All
         )
 
 
@@ -118,16 +118,16 @@ def __init__(self):
         self.n3 = pb.TonicSpiking(30, 3, name="n3", tick_wait_start=2)
 
         self.s1 = pb.NoDecay(
-            self.inp1, self.n1, conn_type=pb.synapses.ConnType.All2All, name="s1"
+            self.inp1, self.n1, conn_type=pb.SynConnType.All2All, name="s1"
         )
         self.s2 = pb.NoDecay(
-            self.n1, self.n2, conn_type=pb.synapses.ConnType.All2All, name="s2"
+            self.n1, self.n2, conn_type=pb.SynConnType.All2All, name="s2"
         )
         self.s3 = pb.NoDecay(
-            self.inp2, self.n1, conn_type=pb.synapses.ConnType.All2All, name="s3"
+            self.inp2, self.n1, conn_type=pb.SynConnType.All2All, name="s3"
         )
         self.s4 = pb.NoDecay(
-            self.n1, self.n3, conn_type=pb.synapses.ConnType.All2All, name="s4"
+            self.n1, self.n3, conn_type=pb.SynConnType.All2All, name="s4"
         )
 
 
diff --git a/tests/neuron/conftest.py b/tests/neuron/conftest.py
index 047f86b4..14317c5e 100644
--- a/tests/neuron/conftest.py
+++ b/tests/neuron/conftest.py
@@ -46,7 +46,7 @@ def __init__(self):
         self.inp1 = pb.InputProj(fakeout, shape_out=(2,))
         self.n1 = pb.neuron.IF((2,), 3)
         self.s1 = pb.synapses.NoDecay(
-            self.inp1, self.n1, conn_type=pb.synapses.ConnType.One2One
+            self.inp1, self.n1, conn_type=pb.SynConnType.One2One
         )
 
         self.probe1 = pb.simulator.Probe(self.inp1, "output")
@@ -66,13 +66,13 @@ def __init__(self):
         self.inp1 = pb.InputProj(1, shape_out=(2, 2))
         self.n1 = pb.neuron.LIF((2, 2), 600, reset_v=1, leaky_v=-1)
         self.s1 = pb.synapses.NoDecay(
-            self.inp1, self.n1, weights=127, conn_type=pb.synapses.ConnType.All2All
+            self.inp1, self.n1, weights=127, conn_type=pb.SynConnType.All2All
         )
         self.s2 = pb.synapses.NoDecay(
-            self.inp1, self.n1, weights=127, conn_type=pb.synapses.ConnType.All2All
+            self.inp1, self.n1, weights=127, conn_type=pb.SynConnType.All2All
         )
         self.s3 = pb.synapses.NoDecay(
-            self.inp1, self.n1, weights=127, conn_type=pb.synapses.ConnType.All2All
+            self.inp1, self.n1, weights=127, conn_type=pb.SynConnType.All2All
         )
 
         self.probe1 = pb.simulator.Probe(self.inp1, "output")
@@ -90,10 +90,10 @@ def __init__(self):
         self.n1 = pb.neuron.LIF((2, 2), 100, reset_v=1, leaky_v=-1)
         self.n2 = pb.neuron.LIF((2, 2), 100, reset_v=1, leaky_v=-1)
         self.s1 = pb.synapses.NoDecay(
-            self.inp1, self.n1, weights=10, conn_type=pb.synapses.ConnType.All2All
+            self.inp1, self.n1, weights=10, conn_type=pb.SynConnType.All2All
         )
         self.s2 = pb.synapses.NoDecay(
-            self.n1, self.n2, weights=10, conn_type=pb.synapses.ConnType.All2All
+            self.n1, self.n2, weights=10, conn_type=pb.SynConnType.All2All
         )
 
         self.probe1 = pb.simulator.Probe(self.n1, "voltage", name="n1_v")
@@ -108,7 +108,7 @@ def __init__(self):
         self.inp1 = pb.InputProj(fakeout, shape_out=(2,))
         self.n1 = pb.neuron.TonicSpiking((2,), 3)
         self.s1 = pb.synapses.NoDecay(
-            self.inp1, self.n1, conn_type=pb.synapses.ConnType.One2One
+            self.inp1, self.n1, conn_type=pb.SynConnType.One2One
         )
 
         self.probe1 = pb.simulator.Probe(self.s1, "output")
diff --git a/tests/simulator/test_simulator.py b/tests/simulator/test_simulator.py
index 53aa4ea0..267e2f64 100644
--- a/tests/simulator/test_simulator.py
+++ b/tests/simulator/test_simulator.py
@@ -18,7 +18,7 @@ def __init__(self, n_neuron: int):
             self.inp,
             self.n1,
             weights=np.random.randint(-128, 128, size=(n_neuron,), dtype=np.int8),
-            conn_type=pb.synapses.ConnType.One2One,
+            conn_type=pb.SynConnType.One2One,
         )
         self.s1 = pb.NoDecay(
             self.n1,
@@ -26,7 +26,7 @@ def __init__(self, n_neuron: int):
             weights=np.random.randint(
                 -128, 128, size=(n_neuron, n_neuron), dtype=np.int8
             ),
-            conn_type=pb.synapses.ConnType.All2All,
+            conn_type=pb.SynConnType.All2All,
         )
 
         # Probes inside
@@ -54,13 +54,13 @@ def __init__(self, n: int):
             self.inp1,
             self.n1,
             weights=np.ones((n,), dtype=np.int8),
-            conn_type=pb.synapses.ConnType.One2One,
+            conn_type=pb.SynConnType.One2One,
         )
         self.s1 = pb.NoDecay(
             self.inp2,
             self.n1,
             weights=np.ones((n,), dtype=np.int8),
-            conn_type=pb.synapses.ConnType.One2One,
+            conn_type=pb.SynConnType.One2One,
         )
 
         # Probes inside
@@ -83,13 +83,13 @@ def __init__(self, n: int):
             self.inp1,
             self.n1,
             weights=np.ones((n,), dtype=np.int8),
-            conn_type=pb.synapses.ConnType.One2One,
+            conn_type=pb.SynConnType.One2One,
         )
         self.s1 = pb.NoDecay(
             self.inp2,
             self.n1,
             weights=np.ones((n,), dtype=np.int8),
-            conn_type=pb.synapses.ConnType.One2One,
+            conn_type=pb.SynConnType.One2One,
         )
 
         # Probes inside
@@ -109,7 +109,7 @@ def __init__(self):
 
         w = np.ones((10, 10), dtype=np.int8)
         self.syn = pb.NoDecay(
-            self.pre_n, self.post_n, conn_type=pb.synapses.ConnType.All2All, weights=w
+            self.pre_n, self.post_n, conn_type=pb.SynConnType.All2All, weights=w
         )
 
         self.probe_in_subnet = pb.Probe(self.pre_n, "spike")
@@ -127,12 +127,12 @@ def __init__(self):
         self.s1 = pb.NoDecay(
             self.inp1,
             self.n1,
-            conn_type=pb.synapses.ConnType.One2One,
+            conn_type=pb.SynConnType.One2One,
         )
         self.s2 = pb.NoDecay(
             self.n1,
             subnet.pre_n,
-            conn_type=pb.synapses.ConnType.One2One,
+            conn_type=pb.SynConnType.One2One,
         )
 
         self.probe1 = pb.Probe(self.inp1, "spike")
diff --git a/tests/synapses/test_synapses.py b/tests/synapses/test_synapses.py
index 92e315af..eb3fc159 100644
--- a/tests/synapses/test_synapses.py
+++ b/tests/synapses/test_synapses.py
@@ -13,7 +13,7 @@ def test_SynSys_Attrs():
         n1,
         n2,
         weights=np.array([[1, 1, 0], [0, 1, 1], [0, 1, 1]], dtype=np.int8),
-        conn_type=pb.synapses.ConnType.MatConn,
+        conn_type=pb.SynConnType.MatConn,
     )
 
     assert np.array_equal(s1.n_axon_each, np.array([1, 3, 2]))
@@ -68,7 +68,7 @@ class TestNoDecay:
     )
     def test_NoDecay_One2One_scalar(self, n1, n2, scalar_weight, expected_wp):
         s1 = pb.synapses.NoDecay(
-            n1, n2, scalar_weight, conn_type=pb.synapses.ConnType.One2One
+            n1, n2, scalar_weight, conn_type=pb.SynConnType.One2One
         )
 
         assert np.array_equal(s1.weights, scalar_weight)
@@ -102,7 +102,7 @@ def test_NoDecay_One2One_scalar(self, n1, n2, scalar_weight, expected_wp):
     )
     def test_NoDecay_One2One_scalar_illegal(self, n1, n2):
         with pytest.raises(ShapeError):
-            s1 = pb.synapses.NoDecay(n1, n2, conn_type=pb.synapses.ConnType.One2One)
+            s1 = pb.synapses.NoDecay(n1, n2, conn_type=pb.SynConnType.One2One)
 
     def test_NoDecay_One2One_matrix(self):
         weight = np.array([2, 3, 4], np.int8)
@@ -110,7 +110,7 @@ def test_NoDecay_One2One_matrix(self):
             pb.neuron.TonicSpiking((3,), 3),
             pb.neuron.TonicSpiking((3,), 3),
             weight,
-            conn_type=pb.synapses.ConnType.One2One,
+            conn_type=pb.SynConnType.One2One,
         )
 
         assert (s1.num_in, s1.num_out) == (3, 3)
@@ -125,7 +125,7 @@ def test_NoDecay_One2One_matrix(self):
             pb.neuron.TonicSpiking((2, 2), 3),
             pb.neuron.TonicSpiking((2, 2), 3),
             weight,
-            conn_type=pb.synapses.ConnType.One2One,
+            conn_type=pb.SynConnType.One2One,
         )
 
         assert (s2.num_in, s2.num_out) == (4, 4)
@@ -161,7 +161,7 @@ def test_NoDecay_One2One_matrix(self):
         ],
     )
     def test_NoDecay_All2All(self, n1, n2):
-        s1 = pb.synapses.NoDecay(n1, n2, conn_type=pb.synapses.ConnType.All2All)
+        s1 = pb.synapses.NoDecay(n1, n2, conn_type=pb.SynConnType.All2All)
 
         assert (s1.num_in, s1.num_out) == (n1.num_out, n2.num_in)
         assert np.array_equal(s1.weights, 1)
@@ -173,14 +173,14 @@ def test_NoDecay_All2All_with_weights(self):
 
         """1. Single weight."""
         weight = 2
-        s1 = pb.synapses.NoDecay(n1, n2, weight, conn_type=pb.synapses.ConnType.All2All)
+        s1 = pb.synapses.NoDecay(n1, n2, weight, conn_type=pb.SynConnType.All2All)
 
         assert np.array_equal(s1.weights, weight)
         assert s1.weight_precision is WP.WEIGHT_WIDTH_4BIT
 
         """2. Weights matrix."""
         weight = np.array([[1, 2, 3], [4, 5, 6], [7, 8, 9]])
-        s2 = pb.synapses.NoDecay(n1, n2, weight, conn_type=pb.synapses.ConnType.All2All)
+        s2 = pb.synapses.NoDecay(n1, n2, weight, conn_type=pb.SynConnType.All2All)
 
         assert np.array_equal(s2.weights, weight)
         assert np.array_equal(s2.connectivity, weight)
@@ -188,7 +188,7 @@ def test_NoDecay_All2All_with_weights(self):
         # Wrong shape
         with pytest.raises(ShapeError):
             s3 = pb.synapses.NoDecay(
-                n1, n2, np.array([1, 2, 3]), conn_type=pb.synapses.ConnType.All2All
+                n1, n2, np.array([1, 2, 3]), conn_type=pb.SynConnType.All2All
             )
 
         with pytest.raises(ShapeError):
@@ -196,7 +196,7 @@ def test_NoDecay_All2All_with_weights(self):
                 n1,
                 n2,
                 np.array([[1, 2, 3], [4, 5, 6]]),
-                conn_type=pb.synapses.ConnType.All2All,
+                conn_type=pb.SynConnType.All2All,
             )
 
         with pytest.raises(ShapeError):
@@ -204,7 +204,7 @@ def test_NoDecay_All2All_with_weights(self):
                 n1,
                 n2,
                 np.array([[1, 2], [4, 5], [6, 7]]),
-                conn_type=pb.synapses.ConnType.All2All,
+                conn_type=pb.SynConnType.All2All,
             )
 
         with pytest.raises(ShapeError):
@@ -212,7 +212,7 @@ def test_NoDecay_All2All_with_weights(self):
                 n1,
                 n2,
                 np.array([[1, 2, 3], [4, 5, 6], [6, 7, 8], [1, 2, 3]]),
-                conn_type=pb.synapses.ConnType.All2All,
+                conn_type=pb.SynConnType.All2All,
             )
 
     @pytest.mark.parametrize(
@@ -234,7 +234,7 @@ def test_NoDecay_MatConn(self, n1, n2):
             -128, 128, size=(n1.num_out, n2.num_in), dtype=np.int8
         )
 
-        s = pb.synapses.NoDecay(n1, n2, weight, conn_type=pb.synapses.ConnType.MatConn)
+        s = pb.synapses.NoDecay(n1, n2, weight, conn_type=pb.SynConnType.MatConn)
 
         assert np.array_equal(s.weights, weight)
         assert (s.num_in, s.num_out) == (n1.num_out, n2.num_in)
@@ -242,12 +242,12 @@ def test_NoDecay_MatConn(self, n1, n2):
 
         # Wrong weight type
         with pytest.raises(TypeError):
-            s = pb.synapses.NoDecay(n1, n2, 1, conn_type=pb.synapses.ConnType.MatConn)
+            s = pb.synapses.NoDecay(n1, n2, 1, conn_type=pb.SynConnType.MatConn)
 
         # Wrong shape
         with pytest.raises(ShapeError):
             s = pb.synapses.NoDecay(
-                n1, n2, np.array([1, 2, 3]), conn_type=pb.synapses.ConnType.MatConn
+                n1, n2, np.array([1, 2, 3]), conn_type=pb.SynConnType.MatConn
             )
 
         # Wrong shape
@@ -256,5 +256,5 @@ def test_NoDecay_MatConn(self, n1, n2):
                 n1,
                 n2,
                 np.array([[1, 2, 3], [4, 5, 6]]),
-                conn_type=pb.synapses.ConnType.MatConn,
+                conn_type=pb.SynConnType.MatConn,
             )
diff --git a/tests/test_network.py b/tests/test_network.py
index 009d9771..67755fec 100644
--- a/tests/test_network.py
+++ b/tests/test_network.py
@@ -18,7 +18,7 @@ def __init__(self):
 
         w = np.random.randint(-128, 127, (10, 10), dtype=np.int8)
         self.syn = pb.NoDecay(
-            self.pre_n, self.post_n, conn_type=pb.synapses.ConnType.All2All, weights=w
+            self.pre_n, self.post_n, conn_type=pb.SynConnType.All2All, weights=w
         )
 
 
@@ -114,12 +114,12 @@ def __init__(self):
                 self.s1 = pb.NoDecay(
                     self.inp1,
                     subnet1.pre_n,
-                    conn_type=pb.synapses.ConnType.One2One,
+                    conn_type=pb.SynConnType.One2One,
                 )
                 self.s2 = pb.NoDecay(
                     subnet1.post_n,
                     subnet2.pre_n,
-                    conn_type=pb.synapses.ConnType.One2One,
+                    conn_type=pb.SynConnType.One2One,
                 )
 
                 super().__init__(subnet1, subnet2)
@@ -159,7 +159,7 @@ def __init__(self, n: pb.neuron.Neuron):
                 self.s1 = pb.NoDecay(
                     n,
                     subnet.pre_n,
-                    conn_type=pb.synapses.ConnType.One2One,
+                    conn_type=pb.SynConnType.One2One,
                 )
 
                 super().__init__(subnet)
@@ -175,7 +175,7 @@ def __init__(self):
                 self.s1 = pb.NoDecay(
                     self.inp1,
                     self.n1,
-                    conn_type=pb.synapses.ConnType.One2One,
+                    conn_type=pb.SynConnType.One2One,
                 )
 
                 super().__init__(net_level2)
@@ -241,8 +241,8 @@ def test_Collector_operations(self):
     def test_add_components(self, build_NotNested_Net_Exp):
         net: pb.Network = build_NotNested_Net_Exp
         n3 = pb.LIF((3,), 10)
-        s1 = pb.synapses.NoDecay(net.n1, n3, conn_type=pb.synapses.ConnType.All2All)
-        s2 = pb.synapses.NoDecay(net.n2, n3, conn_type=pb.synapses.ConnType.All2All)
+        s1 = pb.synapses.NoDecay(net.n1, n3, conn_type=pb.SynConnType.All2All)
+        s2 = pb.synapses.NoDecay(net.n2, n3, conn_type=pb.SynConnType.All2All)
 
         with pytest.raises(ValueError):
             net.diconnect_neudyn_succ(n3)
@@ -307,10 +307,10 @@ def test_insert_neudyn(self, build_Network_with_container):
         # Insert n3 between n_list[0] & n_list[1]
         n_insert = pb.LIF((3,), 10)
         s_insert1 = pb.synapses.NoDecay(
-            net.n_list[0], n_insert, conn_type=pb.synapses.ConnType.All2All
+            net.n_list[0], n_insert, conn_type=pb.SynConnType.All2All
         )
         s_insert2 = pb.synapses.NoDecay(
-            n_insert, net.n_list[1], conn_type=pb.synapses.ConnType.All2All
+            n_insert, net.n_list[1], conn_type=pb.SynConnType.All2All
         )
 
         # Replace s1 with s_insert1->n_insert->s_insert2
@@ -367,7 +367,7 @@ def test_Subnets(self, build_Network_with_subnet):
 def test_Sequential_build():
     n1 = pb.neuron.TonicSpiking(10, fire_step=3)
     n2 = pb.neuron.TonicSpiking(10, fire_step=5)
-    s1 = pb.synapses.NoDecay(n1, n2, conn_type=pb.synapses.ConnType.All2All)
+    s1 = pb.synapses.NoDecay(n1, n2, conn_type=pb.SynConnType.All2All)
     sequential = pb.network.Sequential(n1, s1, n2)
 
     assert isinstance(sequential, pb.network.Sequential)
@@ -381,7 +381,7 @@ def __init__(self):
             self.n1 = pb.neuron.TonicSpiking(5, fire_step=3)
             self.n2 = pb.neuron.TonicSpiking(5, fire_step=5)
             self.s1 = pb.synapses.NoDecay(
-                self.n1, self.n2, conn_type=pb.synapses.ConnType.All2All
+                self.n1, self.n2, conn_type=pb.SynConnType.All2All
             )
 
     seq = Seq()
@@ -393,9 +393,9 @@ def __init__(self):
 def test_Sequential_getitem():
     n1 = pb.neuron.TonicSpiking(10, fire_step=3, name="n1")
     n2 = pb.neuron.TonicSpiking(10, fire_step=5, name="n2")
-    s1 = pb.synapses.NoDecay(n1, n2, conn_type=pb.synapses.ConnType.All2All)
+    s1 = pb.synapses.NoDecay(n1, n2, conn_type=pb.SynConnType.All2All)
     n3 = pb.neuron.TonicSpiking(10, fire_step=5, name="n3")
-    s2 = pb.synapses.NoDecay(n2, n3, conn_type=pb.synapses.ConnType.All2All)
+    s2 = pb.synapses.NoDecay(n2, n3, conn_type=pb.SynConnType.All2All)
     sequential = pb.network.Sequential(n1, s1, n2, s2, n3, name="Sequential_2")
 
     assert isinstance(sequential.children, NodeDict)

From 1890ee264b99563ef46c3e60e41c40fcf0c35a72 Mon Sep 17 00:00:00 2001
From: KafCoppelia <k740677208@gmail.com>
Date: Fri, 8 Mar 2024 15:54:07 +0800
Subject: [PATCH 03/68] =?UTF-8?q?=F0=9F=90=9B=20fixed=20the=20situation=20?=
 =?UTF-8?q?when=20there=20are=20no=20input=20nodes=20in=20the=20graph?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

---
 paibox/backend/graphs.py | 15 +++++++++++----
 1 file changed, 11 insertions(+), 4 deletions(-)

diff --git a/paibox/backend/graphs.py b/paibox/backend/graphs.py
index fc2269fd..367a8dea 100644
--- a/paibox/backend/graphs.py
+++ b/paibox/backend/graphs.py
@@ -203,6 +203,7 @@ def group_edges(self) -> List[FrozenSet[EdgeType]]:
         seen_edges: Set[EdgeType] = set()  # Check if all edges are traversed
 
         for node in self.ordered_nodes:
+            """Process the predecessor nodes of nodes first, then process the successor nodes."""
             if self.degree_of_nodes[node].in_degree > 1:
                 edge_group = self._find_pred_edges(self.succ_dg, node)
                 # Get the edges traversed for the first time
@@ -468,7 +469,7 @@ def get_longest_path(
     Return:
         A tuple containing the longest path in the graph and its distance.
     """
-    distances: Dict[_NT, int] = defaultdict(int)  # init value = 0
+    distances: Dict[_NT, int] = {node: 0 for node in ordered_nodes}
     pred_nodes: Dict[_NT, _NT] = dict()
 
     for node in ordered_nodes:
@@ -487,6 +488,7 @@ def get_longest_path(
 
     distance = distances[node]
     path = [node]
+
     # Construct the longest path by following the predecessors
     while path[-1] in pred_nodes:
         path.append(pred_nodes[path[-1]])
@@ -515,9 +517,13 @@ def get_shortest_path(
     distances: Dict[_NT, int] = defaultdict(lambda: MAX_DISTANCE)
     pred_nodes: Dict[_NT, _NT] = dict()
 
-    # Set initial value for all inputs nodes.
-    for inode in input_nodes:
-        distances[inode] = 0
+    # Set initial value for all inputs nodes. If there is no input node,
+    # the first node after topological sorting will be used as the starting node.
+    if input_nodes:
+        for inode in input_nodes:
+            distances[inode] = 0
+    else:
+        distances[ordered_nodes[0]] = 0
 
     for node in ordered_nodes:
         for neighbor, edge_attr in edges_with_d[node].items():
@@ -535,6 +541,7 @@ def get_shortest_path(
 
     distance = distances[node]
     path = [node]
+
     # Construct the shortest path by following the predecessors
     while path[-1] in pred_nodes:
         path.append(pred_nodes[path[-1]])

From 1dd83f018db64aff1d44db9f01ec0dc669cece94 Mon Sep 17 00:00:00 2001
From: KafCoppelia <k740677208@gmail.com>
Date: Fri, 8 Mar 2024 16:00:51 +0800
Subject: [PATCH 04/68] =?UTF-8?q?=F0=9F=9A=9A=20renamed=20arguments=20due?=
 =?UTF-8?q?=20to=20paicorelib?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

---
 paibox/neuron/base.py        |  69 +++++++------
 paibox/neuron/neurons.py     | 190 +++++++++++------------------------
 tests/neuron/conftest.py     |   6 +-
 tests/neuron/test_neurons.py |   2 +-
 4 files changed, 96 insertions(+), 171 deletions(-)

diff --git a/paibox/neuron/base.py b/paibox/neuron/base.py
index f3cc51cc..6f47110e 100644
--- a/paibox/neuron/base.py
+++ b/paibox/neuron/base.py
@@ -36,13 +36,13 @@ def __init__(
         shape: Shape,
         reset_mode: RM,
         reset_v: int,
-        leaking_comparison: LCM,
+        leak_comparison: LCM,
         threshold_mask_bits: int,
         neg_thres_mode: NTM,
         neg_threshold: int,
         pos_threshold: int,
-        leaking_direction: LDM,
-        leaking_integration_mode: LIM,
+        leak_direction: LDM,
+        leak_integration_mode: LIM,
         leak_v: int,
         synaptic_integration_mode: SIM,
         bit_truncation: int,
@@ -58,13 +58,13 @@ def __init__(
         # They will be exported to the parameter verification model.
         self.reset_mode: RM = reset_mode
         self.reset_v: int = reset_v  # Signed 30-bit
-        self.leaking_comparison: LCM = leaking_comparison
+        self.leak_comparison: LCM = leak_comparison
         self.threshold_mask_bits: int = threshold_mask_bits
         self.neg_thres_mode: NTM = neg_thres_mode
         self.neg_threshold: int = neg_threshold  # Unsigned 29-bit
         self.pos_threshold: int = pos_threshold  # Unsigned 29-bit
-        self.leaking_direction: LDM = leaking_direction
-        self.leaking_integration_mode: LIM = leaking_integration_mode
+        self.leak_direction: LDM = leak_direction
+        self.leak_integration_mode: LIM = leak_integration_mode
         self.leak_v: int = leak_v  # Signed 30-bit
         self.synaptic_integration_mode: SIM = synaptic_integration_mode
         self.bit_truncation: int = bit_truncation  # Unsigned 5-bit
@@ -110,13 +110,13 @@ def _neuronal_charge(
         return v_charged
 
     def _neuronal_leak(self, vjt: VoltageType) -> VoltageType:
-        r"""2. Leaking integration.
+        r"""2. Leak integration.
 
-        2.1 Leaking direction, forward or reversal.
-            If leaking direction is `MODE_FORWARD`, the `_ld` is 1, else is \sgn{`vjt`}.
+        2.1 Leak direction, forward or reversal.
+            If leak direction is `MODE_FORWARD`, the `_ld` is 1, else is \sgn{`vjt`}.
 
-        2.2 Random leaking.
-            If leaking integration is `MODE_DETERMINISTIC`, then
+        2.2 Random leak.
+            If leak integration is `MODE_DETERMINISTIC`, then
                 `vjt` = `vjt` + `_ld` * `leak_v`
             else (`MODE_STOCHASTIC`)
                 if abs(`leak_v`) >= `_rho_j_lambda`, then
@@ -126,14 +126,14 @@ def _neuronal_leak(self, vjt: VoltageType) -> VoltageType:
 
                 `vjt` = `vjt` + \sgn{`leak_v`}* `_ld` * `_F`
         """
-        _rho_j_lambda = 2  # Random leaking, unsigned 29-bit.
+        _rho_j_lambda = 2  # Random leak, unsigned 29-bit.
 
-        if self.leaking_direction is LDM.MODE_FORWARD:
+        if self.leak_direction is LDM.MODE_FORWARD:
             _ld = np.ones(self.varshape, dtype=np.bool_)
         else:
             _ld = np.sign(vjt)
 
-        if self.leaking_integration_mode is LIM.MODE_DETERMINISTIC:
+        if self.leak_integration_mode is LIM.MODE_DETERMINISTIC:
             v_leaked = np.add(vjt, _ld * self.leak_v).astype(np.int32)
         else:
             raise NotImplementedError(
@@ -329,7 +329,7 @@ def update(
         v_charged = self._neuronal_charge(incoming_v, vjt_pre)
 
         # 2. Leak & fire
-        if self.leaking_comparison is LCM.LEAK_BEFORE_COMP:
+        if self.leak_comparison is LCM.LEAK_BEFORE_COMP:
             v_leaked = self._neuronal_leak(v_charged)
             spike = self._neuronal_fire(v_leaked)
         else:
@@ -375,18 +375,18 @@ class Neuron(MetaNeuron, NeuDyn):
     def __init__(
         self,
         shape: Shape,
-        reset_mode: RM,
-        reset_v: int,
-        leaking_comparison: LCM,
-        threshold_mask_bits: int,
-        neg_thres_mode: NTM,
-        neg_threshold: int,
-        pos_threshold: int,
-        leaking_direction: LDM,
-        leaking_integration_mode: LIM,
-        leak_v: int,
-        synaptic_integration_mode: SIM,
-        bit_truncation: int,
+        reset_mode: RM = RM.MODE_NORMAL,
+        reset_v: int = 0,
+        leak_comparison: LCM = LCM.LEAK_AFTER_COMP,
+        threshold_mask_bits: int = 0,
+        neg_thres_mode: NTM = NTM.MODE_RESET,
+        neg_threshold: int = -1,
+        pos_threshold: int = 1,
+        leak_direction: LDM = LDM.MODE_FORWARD,
+        leak_integration_mode: LIM = LIM.MODE_DETERMINISTIC,
+        leak_v: int = 0,
+        synaptic_integration_mode: SIM = SIM.MODE_DETERMINISTIC,
+        bit_truncation: int = 0,
         *,
         delay: int = 1,
         tick_wait_start: int = 1,
@@ -432,13 +432,13 @@ def __init__(
             shape,
             reset_mode,
             reset_v,
-            leaking_comparison,
+            leak_comparison,
             threshold_mask_bits,
             neg_thres_mode,
             (-neg_threshold),  # In `MetaNeuron`, it is unsgined.
             pos_threshold,
-            leaking_direction,
-            leaking_integration_mode,
+            leak_direction,
+            leak_integration_mode,
             leak_v,
             synaptic_integration_mode,
             bit_truncation,
@@ -520,8 +520,7 @@ def update(
         return self._inner_spike
 
     def reset_state(self, *args, **kwargs) -> None:
-        """Initialization, not the neuronal reset."""
-        self.reset()  # Call reset of `StatusMemory`.
+        self.reset_memory()  # Call reset of `StatusMemory`.
 
     def __copy__(self) -> "Neuron":
         """Same as `__deepcopy__`."""
@@ -539,13 +538,13 @@ def __deepcopy__(self) -> "Neuron":
             self._shape,
             self.reset_mode,
             self.reset_v,
-            self.leaking_comparison,
+            self.leak_comparison,
             self.threshold_mask_bits,
             self.neg_thres_mode,
             self.neg_threshold,
             self.pos_threshold,
-            self.leaking_direction,
-            self.leaking_integration_mode,
+            self.leak_direction,
+            self.leak_integration_mode,
             self.leak_v,
             self.synaptic_integration_mode,
             self.bit_truncation,
diff --git a/paibox/neuron/neurons.py b/paibox/neuron/neurons.py
index 6340fefd..2a1cfb73 100644
--- a/paibox/neuron/neurons.py
+++ b/paibox/neuron/neurons.py
@@ -1,6 +1,6 @@
 from typing import Optional
 
-from paicorelib import LCM, LDM, LIM, NTM, RM, SIM
+from paicorelib import LCM, LDM, NTM, RM
 
 from paibox.types import Shape
 
@@ -16,51 +16,36 @@ def __init__(
         threshold: int,
         reset_v: int = 0,
         *,
-        delay: int = 1,
-        tick_wait_start: int = 1,
-        tick_wait_end: int = 0,
-        unrolling_factor: int = 1,
         keep_shape: bool = False,
         name: Optional[str] = None,
+        **kwargs,
     ) -> None:
         """
         Arguments:
-            - shape    : the shape of the neuron(s). It can be an integer, tuple or list.
-            - Threshold: When the membrane potential exceeds the threshold, neurons will fire
-            - reset_v  : Membrane potential after firing
-
-        Description:
-            IF neuron : intergration + firing
+            - shape: shape of neurons.
+            - threshold: when the membrane potential exceeds the threshold, neurons will fire.
+            - reset_v: reset membrane potential after firing
+            - delay: delay between neurons. Default is 1.
+            - tick_wait_start: set the neuron group to start at the `N`-th timestep. 0 means not to     \
+                start. Default is 1.
+            - tick_wait_end: set the neuron group to continue working for `M` timesteps, 0 means working\
+                forever. Default is 0.
+            - unrolling_factor: the argument is related to the backend. It means that neurons will be   \
+                unrolled & deployed to more physical cores to reduce latency and increase throughput.   \
+                Default is 1.
+            - keep_shape: whether to maintain size information when recording data in the simulation.   \
+                Default is `False`.
+            - name: name of the object.
         """
-        _sim = SIM.MODE_DETERMINISTIC
-        _lim = LIM.MODE_DETERMINISTIC
-        _ld = LDM.MODE_FORWARD
-        _lc = LCM.LEAK_AFTER_COMP
-        _pos_thres = threshold
-        _reset_v = reset_v
-        _ntm = NTM.MODE_SATURATION
-        _reset_mode = RM.MODE_NORMAL
-
         super().__init__(
             shape,
-            _reset_mode,
-            _reset_v,
-            _lc,
-            0,
-            _ntm,
-            0,
-            _pos_thres,
-            _ld,
-            _lim,
-            0,
-            _sim,
-            0,
-            delay=delay,
-            tick_wait_start=tick_wait_start,
-            tick_wait_end=tick_wait_end,
-            unrolling_factor=unrolling_factor,
+            reset_v=reset_v,
+            neg_thres_mode=NTM.MODE_SATURATION,
+            neg_threshold=0,
+            pos_threshold=threshold,
             keep_shape=keep_shape,
             name=name,
+            **kwargs,
         )
 
 
@@ -72,57 +57,32 @@ def __init__(
         shape: Shape,
         threshold: int,
         reset_v: int = 0,
-        leaky_v: int = 0,
+        leak_v: int = 0,
         *,
-        delay: int = 1,
-        tick_wait_start: int = 1,
-        tick_wait_end: int = 0,
-        unrolling_factor: int = 1,
         keep_shape: bool = False,
         name: Optional[str] = None,
+        **kwargs,
     ) -> None:
         """
         Arguments:
-            - shape: the shape of the neuron(s). It can be an integer, tuple or list.
-            - threshold: When the membrane potential exceeds the threshold, neurons will fire
-            - reset_v: Membrane potential after firing
-            - leaky_v: The leakage value will be directly added to the membrane potential.
-                If it is positive, the membrane potential will increase.
-                If is is negative, the membrane potential will decrease.
-
-        Description:
-            LIF: leaky + intergration + firing
+            - shape: shape of neurons.
+            - threshold: when the membrane potential exceeds the threshold, neurons will fire.
+            - reset_v: reset membrane potential after firing
+            - leak_v: the signed leak voltage will be added directly to the membrane potential.
+                - If it is positive, the membrane potential will increase.
+                - If is is negative, the membrane potential will decrease.
         """
-        _sim = SIM.MODE_DETERMINISTIC
-        _lim = LIM.MODE_DETERMINISTIC
-        _ld = LDM.MODE_FORWARD
-        _lc = LCM.LEAK_AFTER_COMP
-        _leak_v = leaky_v
-        _pos_thres = threshold
-        _reset_v = reset_v
-        _ntm = NTM.MODE_SATURATION
-        _reset_mode = RM.MODE_NORMAL
-
         super().__init__(
             shape,
-            _reset_mode,
-            _reset_v,
-            _lc,
-            0,
-            _ntm,
-            0,
-            _pos_thres,
-            _ld,
-            _lim,
-            _leak_v,
-            _sim,
-            0,
-            delay=delay,
-            tick_wait_start=tick_wait_start,
-            tick_wait_end=tick_wait_end,
-            unrolling_factor=unrolling_factor,
+            reset_mode=RM.MODE_NORMAL,
+            reset_v=reset_v,
+            neg_thres_mode=NTM.MODE_SATURATION,
+            neg_threshold=0,
+            pos_threshold=threshold,
+            leak_v=leak_v,
             keep_shape=keep_shape,
             name=name,
+            **kwargs,
         )
 
 
@@ -134,42 +94,25 @@ def __init__(
         shape: Shape,
         fire_step: int,
         *,
-        delay: int = 1,
-        tick_wait_start: int = 1,
-        tick_wait_end: int = 0,
-        unrolling_factor: int = 1,
         keep_shape: bool = False,
         name: Optional[str] = None,
+        **kwargs,
     ) -> None:
         """
         Arguments:
-            - shape: the shape of the neuron(s). It can be an integer, tuple or list.
+            - shape: shape of neurons.
             - fire_step: every `N` spike, the neuron will fire positively.
 
-        Description:
-            The neuron receives `N` spikes and fires, then resets to 0.
-            `N` stands for firing steps.
+        NOTE: The neuron receives `N` spikes and fires, then it will reset to 0.
         """
         super().__init__(
             shape,
-            RM.MODE_NORMAL,
-            0,
-            LCM.LEAK_AFTER_COMP,
-            0,
-            NTM.MODE_SATURATION,
-            0,
-            fire_step,
-            LDM.MODE_FORWARD,
-            LIM.MODE_DETERMINISTIC,
-            0,
-            SIM.MODE_DETERMINISTIC,
-            0,
-            delay=delay,
-            tick_wait_start=tick_wait_start,
-            tick_wait_end=tick_wait_end,
-            unrolling_factor=unrolling_factor,
+            neg_thres_mode=NTM.MODE_SATURATION,
+            neg_threshold=0,
+            pos_threshold=fire_step,
             keep_shape=keep_shape,
             name=name,
+            **kwargs,
         )
 
 
@@ -182,48 +125,31 @@ def __init__(
         time_to_fire: int,
         neg_floor: int = -10,
         *,
-        delay: int = 1,
-        tick_wait_start: int = 1,
-        tick_wait_end: int = 0,
-        unrolling_factor: int = 1,
         keep_shape: bool = False,
         name: Optional[str] = None,
+        **kwargs,
     ) -> None:
         """
         Arguments:
-            - shape: the shape of the neuron(s). It can be an integer, tuple or list.
-            - time_to_fire: after `time_to_fire` spikes, the neuron will fire positively.
-            - neg_floor: the negative floor that the neuron stays once firing. Default is -10.
+            - shape: shape of neurons.
+            - time_to_fire: after `N` spikes, the neuron will fire positively.
+            - neg_floor: once fired, the neurons will remain at this negative membrane potential.   \
+                Default is -10.
 
-        Description:
-            The neuron receives `N` spikes and fires, then resets the membrane potential to 0,
-            and never fires again.
-
-            `N` stands for `time_to_fire`.
+        NOTE: Once the neuron receives `N` spikes and fires, it will reset to the negative floor &  \
+            never fires again. `N` stands for `time_to_fire`.
         """
         leak_v = 1
-        pos_thres = (1 + leak_v) * time_to_fire
-        _neg_thres = neg_floor
-        reset_v = -1 - _neg_thres
-
         super().__init__(
             shape,
-            RM.MODE_NORMAL,
-            reset_v,
-            LCM.LEAK_BEFORE_COMP,
-            0,
-            NTM.MODE_SATURATION,
-            neg_floor,
-            pos_thres,
-            LDM.MODE_REVERSAL,
-            LIM.MODE_DETERMINISTIC,
-            leak_v,
-            SIM.MODE_DETERMINISTIC,
-            0,
-            delay=delay,
-            tick_wait_start=tick_wait_start,
-            tick_wait_end=tick_wait_end,
-            unrolling_factor=unrolling_factor,
+            reset_v=(-1 - neg_floor),
+            leak_comparison=LCM.LEAK_BEFORE_COMP,
+            neg_thres_mode=NTM.MODE_SATURATION,
+            neg_threshold=neg_floor,
+            pos_threshold=(1 + leak_v) * time_to_fire,
+            leak_direction=LDM.MODE_REVERSAL,
+            leak_v=leak_v,
             keep_shape=keep_shape,
             name=name,
+            **kwargs,
         )
diff --git a/tests/neuron/conftest.py b/tests/neuron/conftest.py
index 14317c5e..f5990dfc 100644
--- a/tests/neuron/conftest.py
+++ b/tests/neuron/conftest.py
@@ -64,7 +64,7 @@ class Net2(pb.Network):
     def __init__(self):
         super().__init__()
         self.inp1 = pb.InputProj(1, shape_out=(2, 2))
-        self.n1 = pb.neuron.LIF((2, 2), 600, reset_v=1, leaky_v=-1)
+        self.n1 = pb.neuron.LIF((2, 2), 600, reset_v=1, leak_v=-1)
         self.s1 = pb.synapses.NoDecay(
             self.inp1, self.n1, weights=127, conn_type=pb.SynConnType.All2All
         )
@@ -87,8 +87,8 @@ class Net3(pb.Network):
     def __init__(self):
         super().__init__()
         self.inp1 = pb.InputProj(1, shape_out=(2, 2))
-        self.n1 = pb.neuron.LIF((2, 2), 100, reset_v=1, leaky_v=-1)
-        self.n2 = pb.neuron.LIF((2, 2), 100, reset_v=1, leaky_v=-1)
+        self.n1 = pb.neuron.LIF((2, 2), 100, reset_v=1, leak_v=-1)
+        self.n2 = pb.neuron.LIF((2, 2), 100, reset_v=1, leak_v=-1)
         self.s1 = pb.synapses.NoDecay(
             self.inp1, self.n1, weights=10, conn_type=pb.SynConnType.All2All
         )
diff --git a/tests/neuron/test_neurons.py b/tests/neuron/test_neurons.py
index d1a819ef..c8a9361b 100644
--- a/tests/neuron/test_neurons.py
+++ b/tests/neuron/test_neurons.py
@@ -339,7 +339,7 @@ def test_IF_simple_sim(self):
         print(output)
 
     def test_LIF_simple_sim(self):
-        n1 = pb.neuron.LIF(shape=1, threshold=5, reset_v=2, leaky_v=1)  # leak + 1
+        n1 = pb.neuron.LIF(shape=1, threshold=5, reset_v=2, leak_v=1)  # leak + 1
         # [0, 0, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1]
         inp_data = np.concatenate((np.zeros((2,), np.bool_), np.ones((10,), np.bool_)))
         # inp_data = np.ones((12,), dtype=np.bool_)

From 66db0c07ccdaf57d9551ecaaaa194369400e0781 Mon Sep 17 00:00:00 2001
From: KafCoppelia <k740677208@gmail.com>
Date: Fri, 8 Mar 2024 19:33:22 +0800
Subject: [PATCH 05/68] =?UTF-8?q?=F0=9F=92=AC=20updated=20comments?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

---
 paibox/backend/conf_template.py |  8 ++++----
 paibox/backend/placement.py     |  5 ++---
 paibox/base.py                  |  2 +-
 paibox/mixin.py                 |  2 +-
 paibox/projection.py            | 10 +++++-----
 paibox/types.py                 |  4 ++--
 tests/test_projection.py        |  4 ++--
 7 files changed, 17 insertions(+), 18 deletions(-)

diff --git a/paibox/backend/conf_template.py b/paibox/backend/conf_template.py
index a5e6490b..7c881254 100644
--- a/paibox/backend/conf_template.py
+++ b/paibox/backend/conf_template.py
@@ -154,8 +154,8 @@ def encapsulate(
             - addr_offset: offset of the RAM address.
             - axon_segs: the destination axon segments.
             - dest_core_coords: coordinates of the core of the destination axons.
-            - dest_chip_coord: coordinate of the chip of the destination axons. \
-                The default is `output_chip_addr` in the backend context.
+            - dest_chip_coord: coordinate of the chip of the destination axons. Default is \
+                `output_chip_addr` in the backend context.
         """
         attrs = NeuronAttrs.model_validate(neuron.export_params(), strict=True)
         dest_rid = get_replication_id(dest_core_coords)
@@ -271,7 +271,7 @@ def gen_config_frames_by_coreconf(
     write_to_file: bool,
     fp: Path,
     split_by_coord: bool,
-    format: Literal["txt", "bin", "npy"] = "bin",
+    format: Literal["txt", "bin", "npy"],
 ) -> Dict[Coord, FrameArrayType]:
     """Generate configuration frames by given the `CorePlacementConfig`.
 
@@ -281,7 +281,7 @@ def gen_config_frames_by_coreconf(
         - write_to_file: whether to write frames to file.
         - fp: If `write_to_file` is `True`, specify the path.
         - split_by_coord: whether to split the generated frames file by the core coordinates.
-        - format: it can be `txt`, `bin`, or `npy`. `bin` & `npy` are recommended.
+        - format: `txt`, `bin`, or `npy`. `bin` & `npy` are recommended.
     """
 
     def _write_to_f(name: str, array: np.ndarray) -> None:
diff --git a/paibox/backend/placement.py b/paibox/backend/placement.py
index b2908d97..85ca673a 100644
--- a/paibox/backend/placement.py
+++ b/paibox/backend/placement.py
@@ -281,13 +281,12 @@ def n_neuron_of_plm(self) -> List[int]:
 
         # Get #N of neurons on each `CorePlacement` according to the
         # maximum address required of neuron segments on each `CorePlacement`.
-        assert [] not in self.neuron_segs_of_cb  # FIXME if it never happens, remove it.
+        assert [] not in self.neuron_segs_of_cb  # TODO if it never happens, remove it.
 
-        n = [
+        return [
             sum(seg.n_neuron for seg in neuron_segs)
             for neuron_segs in self.neuron_segs_of_cb
         ]
-        return n
 
     @cached_property
     def raw_weight_of_dest(self) -> List[WeightType]:
diff --git a/paibox/base.py b/paibox/base.py
index 3af72fd2..7ae8d428 100644
--- a/paibox/base.py
+++ b/paibox/base.py
@@ -240,7 +240,7 @@ def export_params(self) -> Dict[str, Any]:
             if sys.version_info >= (3, 9):
                 params.update({k.removeprefix("_"): v})
             else:
-                params.update({k.lstrip("_"): v})
+                params.update({k.lstrip("_"): v})  # compatible for py3.8
 
         return params
 
diff --git a/paibox/mixin.py b/paibox/mixin.py
index 508e245e..4759a70d 100644
--- a/paibox/mixin.py
+++ b/paibox/mixin.py
@@ -194,7 +194,7 @@ def set_memory(self, name: str, value: Any) -> None:
         self._memories[name] = value
         self.set_reset_value(name, value)
 
-    def reset(self, name: Optional[str] = None) -> None:
+    def reset_memory(self, name: Optional[str] = None) -> None:
         if isinstance(name, str):
             if name in self._memories:
                 self._memories[name] = deepcopy(self._memories_rv[name])
diff --git a/paibox/projection.py b/paibox/projection.py
index c23efe36..7e1cf62b 100644
--- a/paibox/projection.py
+++ b/paibox/projection.py
@@ -68,7 +68,7 @@ def __init__(
     def update(self, **kwargs) -> SpikeType:
         _spike = self._get_neumeric_input(**kwargs)
 
-        if isinstance(_spike, (int, np.integer)):
+        if isinstance(_spike, (int, np.bool_, np.integer)):
             self._inner_spike = np.full((self.num_out,), _spike, dtype=np.bool_)
         elif isinstance(_spike, np.ndarray):
             try:
@@ -80,14 +80,14 @@ def update(self, **kwargs) -> SpikeType:
         else:
             # Should be never
             raise TypeError(
-                f"Excepted type int, np.integer or np.ndarray, "
+                f"Excepted type int, np.bool_, np.integer or np.ndarray, "
                 f"but got {_spike}, type {type(_spike)}."
             )
 
         return self._inner_spike
 
     def reset_state(self) -> None:
-        self.reset()  # Call reset of `StatusMemory`.
+        self.reset_memory()  # Call reset of `StatusMemory`.
 
     def _get_neumeric_input(self, **kwargs):
         # If `_func_input` is `None` while `input` is numeric, use `input` as input to the projection.
@@ -130,9 +130,9 @@ def input(self):
     @input.setter
     def input(self, value: DataType) -> None:
         """Set the input at the beginning of running the simulation."""
-        if not isinstance(value, (int, np.integer, np.ndarray)):
+        if not isinstance(value, (int, np.bool_, np.integer, np.ndarray)):
             raise TypeError(
-                f"Excepted type int, np.integer or np.ndarray, "
+                f"Excepted type int, np.bool_, np.integer or np.ndarray, "
                 f"but got {value}, type {type(value)}"
             )
 
diff --git a/paibox/types.py b/paibox/types.py
index 794c3392..f5607ac0 100644
--- a/paibox/types.py
+++ b/paibox/types.py
@@ -25,9 +25,9 @@
 ArrayType = TypeVar("ArrayType", List[int], Tuple[int, ...], np.ndarray)
 Scalar = TypeVar("Scalar", int, float, np.generic)
 IntScalarType = TypeVar("IntScalarType", int, np.integer)
-DataType = TypeVar("DataType", int, np.integer, np.ndarray)
+DataType = TypeVar("DataType", int, np.bool_, np.integer, np.ndarray)
 DataArrayType = TypeVar(
-    "DataArrayType", int, np.integer, List[int], Tuple[int, ...], np.ndarray
+    "DataArrayType", int, np.bool_, np.integer, List[int], Tuple[int, ...], np.ndarray
 )
 SpikeType: TypeAlias = NDArray[np.bool_]
 WeightType: TypeAlias = NDArray[np.int8]  # raw int8 weights
diff --git a/tests/test_projection.py b/tests/test_projection.py
index 7fc285e7..9fca4a27 100644
--- a/tests/test_projection.py
+++ b/tests/test_projection.py
@@ -164,12 +164,12 @@ def test_input_PeriodicEncoder(self):
         assert len(sim.data[prob]) == 10
 
     def test_illegal_input(self):
-        def fakeout_with_t(t):
+        def fakeout_with_t(t, **kwargs):
             return np.ones((10, 10), dtype=np.int8) * t
 
         inp1 = pb.InputProj(None, shape_out=(4, 4), keep_shape=True)
         with pytest.raises(TypeError):
-            inp1.input = fakeout_with_t
+            inp1.input = fakeout_with_t  # type: ignore
 
         sim = pb.Simulator(inp1)
 

From 2e362545bb5e771fa1879a6c2c7c7ede82716847 Mon Sep 17 00:00:00 2001
From: KafCoppelia <k740677208@gmail.com>
Date: Fri, 8 Mar 2024 19:36:47 +0800
Subject: [PATCH 06/68] =?UTF-8?q?=E2=9C=85=20refactored=20parameterized=20?=
 =?UTF-8?q?test=20data=20format?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

---
 tests/backend/__init__.py    |   0
 tests/backend/conftest.py    | 253 +++++++++++++++++++++++++++++++++++
 tests/backend/test_graphs.py | 228 ++++---------------------------
 tests/conftest.py            |   9 ++
 4 files changed, 286 insertions(+), 204 deletions(-)
 create mode 100644 tests/backend/__init__.py

diff --git a/tests/backend/__init__.py b/tests/backend/__init__.py
new file mode 100644
index 00000000..e69de29b
diff --git a/tests/backend/conftest.py b/tests/backend/conftest.py
index 030ab0ae..0164b867 100644
--- a/tests/backend/conftest.py
+++ b/tests/backend/conftest.py
@@ -26,6 +26,8 @@
 from paibox.generic import clear_name_cache
 from paibox.node import NodeList
 
+from tests.conftest import ParametrizedTestData
+
 
 @pytest.fixture(scope="module")
 def ensure_dump_dir():
@@ -596,3 +598,254 @@ def packbits2():
 @pytest.fixture
 def packbits1():
     return partial(packbits_ref, count=1)
+
+
+class TestData:
+
+    toposort_data = ParametrizedTestData(
+        args="nodes",
+        data=[
+            (
+                {
+                    "inp1": {"n1"},
+                    "n1": {"n2", "n4"},
+                    "n2": {"n3"},
+                    "n3": {},
+                    "n4": {"n2"},
+                }
+            ),
+            (
+                {
+                    "inp1": {"n1"},
+                    "n1": {"n2", "n5"},
+                    "n2": {"n3"},
+                    "n3": {"n4", "n6"},
+                    "n4": {},
+                    "n5": {"n3", "n6"},
+                    "n6": {"n7"},
+                    "n7": {"n4"},
+                }
+            ),
+            (
+                {
+                    "inp1": {"n1"},
+                    "inp2": {"n4"},
+                    "n1": {"n2"},
+                    "n2": {"n3"},
+                    "n3": {},
+                    "n4": {"n5"},
+                    "n5": {"n3"},
+                }
+            ),
+            (
+                {
+                    "inp1": {"n1"},
+                    "n1": {"n2", "n3"},
+                    "n2": {"n4"},
+                    "n3": {"n4"},
+                    "n4": {},
+                }
+            ),
+            (
+                {
+                    "inp1": {"n1"},
+                    "n1": {"n2"},
+                    "n2": {"n4"},
+                    "n3": {"n2"},  # Headless neuron N3
+                    "n4": {},
+                }
+            ),
+        ],
+        ids=[
+            "one_input_1",
+            "one_input_2",
+            "multi_inputs_1",
+            "one_input_3",
+            "headless_neuron_1",
+        ],
+    )
+
+    get_longest_path_data = ParametrizedTestData(
+        args="edges, expected_path, expected_distance",
+        data=[
+            (
+                # inp1 -> n1 -> n4 -> n2 -> n3, 1+1+1+1=4
+                {
+                    "inp1": {"n1": 1},
+                    "n1": {"n2": 1, "n4": 1},
+                    "n2": {"n3": 1},
+                    "n3": {},
+                    "n4": {"n2": 1},
+                },
+                ["inp1", "n1", "n4", "n2", "n3"],
+                4,
+            ),
+            (
+                # inp1 -> n1 -> n3 -> n4, 1+2+5=8
+                {
+                    "inp1": {"n1": 1},
+                    "n1": {"n2": 3, "n3": 2},
+                    "n2": {"n4": 2},
+                    "n3": {"n4": 5},
+                    "n4": {},
+                },
+                ["inp1", "n1", "n3", "n4"],
+                8,
+            ),
+            (
+                # inp1 -> n1 -> n2 -> n3, 1+2+1=4
+                {
+                    "inp1": {"n1": 1},
+                    "inp2": {"n2": 1},
+                    "n1": {"n2": 2},
+                    "n2": {"n3": 1},
+                    "n3": {},
+                },
+                ["inp1", "n1", "n2", "n3"],
+                4,
+            ),
+            (
+                # inp1 -> n1 -> n3 -> n5, 1+2+1=4
+                {
+                    "inp1": {"n1": 1},
+                    "n1": {"n2": 1, "n3": 2},
+                    "n2": {"n4": 1, "n5": 1},
+                    "n3": {"n4": 1},
+                    "n4": {},
+                    "n5": {},
+                },
+                ["inp1", "n1", "n3", "n4"],
+                4,
+            ),
+            (
+                # inp2 -> n5 -> n4, 4+1=5
+                {
+                    "inp1": {"n1": 1},
+                    "inp2": {"n5": 4},
+                    "n1": {"n2": 1, "n3": 1},
+                    "n2": {"n5": 1},
+                    "n3": {"n4": 1},
+                    "n4": {},
+                    "n5": {"n4": 1},
+                },
+                ["inp2", "n5", "n4"],
+                5,
+            ),
+            (
+                {"n1": {"n2": 1}, "n2": {}},
+                ["n1", "n2"],
+                1,
+            ),
+            (
+                {"n1": {}},
+                ["n1"],
+                0,
+            ),
+        ],
+        ids=[
+            "one_input_1",
+            "one_input_2",
+            "multi_inputs_1",
+            "multi_outputs_1",
+            "multi_inputs_outputs_1",
+            "headless_neuron_1",
+            "headless_neuron_2",
+        ],
+    )
+
+    get_shortest_path_data = ParametrizedTestData(
+        args="edges, inodes, expected_path, expected_distance",
+        data=[
+            (
+                # inp1 -> n1 -> n2 -> n3, 1+1+1=3
+                {
+                    "inp1": {"n1": 1},
+                    "n1": {"n2": 1, "n4": 1},
+                    "n2": {"n3": 1},
+                    "n3": {},
+                    "n4": {"n2": 1},
+                },
+                ["inp1"],
+                ["inp1", "n1", "n2", "n3"],
+                3,
+            ),
+            (
+                # inp1 -> n1 -> n2 -> n3 -> n6 -> n7 -> n4 =
+                # 1+1+3+2+2+3=12
+                {
+                    "inp1": {"n1": 1},
+                    "n1": {"n2": 1, "n5": 5},
+                    "n2": {"n3": 3},
+                    "n3": {"n4": 10, "n6": 2},
+                    "n4": {},
+                    "n5": {"n3": 5, "n6": 7},
+                    "n6": {"n7": 2},
+                    "n7": {"n4": 3},
+                },
+                ["inp1"],
+                ["inp1", "n1", "n2", "n3", "n6", "n7", "n4"],
+                12,
+            ),
+            (
+                # inp2 -> n2 -> n3, 1+1=2
+                {
+                    "inp1": {"n1": 1},
+                    "inp2": {"n2": 1},
+                    "n1": {"n2": 2},
+                    "n2": {"n3": 1},
+                    "n3": {},
+                },
+                ["inp1", "inp2"],
+                ["inp2", "n2", "n3"],
+                2,
+            ),
+            (
+                # inp1 -> n1 -> n2 -> n4, 1+1+1=3
+                {
+                    "inp1": {"n1": 1},
+                    "n1": {"n2": 1, "n3": 2},
+                    "n2": {"n4": 1},
+                    "n3": {"n4": 1},
+                    "n4": {},
+                },
+                ["inp1"],
+                ["inp1", "n1", "n2", "n4"],
+                3,
+            ),
+            (
+                # inp1 -> n1 -> n2 -> n4, 1+1+1=3
+                {
+                    "inp1": {"n1": 1},
+                    "n1": {"n2": 1, "n3": 1},
+                    "n2": {"n4": 2},
+                    "n3": {"n5": 1},
+                    "n4": {},
+                    "n5": {},
+                },
+                ["inp1"],
+                ["inp1", "n1", "n3", "n5"],
+                3,
+            ),
+            (
+                {"n1": {"n2": 1}, "n2": {}},
+                [],
+                ["n1", "n2"],
+                1,
+            ),
+            (
+                {"n1": {}},
+                [],
+                ["n1"],
+                0,
+            ),
+        ],
+        ids=[
+            "one_input_1",
+            "one_input_2",
+            "multi_inputs_1",
+            "multi_outputs_1",
+            "multi_outputs_2",
+            "headless_neuron_1",
+            "headless_neuron_2",
+        ],
+    )
diff --git a/tests/backend/test_graphs.py b/tests/backend/test_graphs.py
index d4005bb0..e8ebdc2b 100644
--- a/tests/backend/test_graphs.py
+++ b/tests/backend/test_graphs.py
@@ -7,56 +7,16 @@
 from paibox.backend.graphs import _degree_check
 from paibox.exceptions import NotSupportedError
 
+from .conftest import TestData
+
 
 class TestTopoSort:
     @pytest.mark.parametrize(
-        "edges",
-        [
-            (
-                {
-                    "inp1": {"n1"},
-                    "n1": {"n2", "n4"},
-                    "n2": {"n3"},
-                    "n3": {},
-                    "n4": {"n2"},
-                }
-            ),
-            (
-                {
-                    "inp1": {"n1"},
-                    "n1": {"n2", "n5"},
-                    "n2": {"n3"},
-                    "n3": {"n4", "n6"},
-                    "n4": {},
-                    "n5": {"n3", "n6"},
-                    "n6": {"n7"},
-                    "n7": {"n4"},
-                }
-            ),
-            (
-                {
-                    "inp1": {"n1"},
-                    "inp2": {"n4"},
-                    "n1": {"n2"},
-                    "n2": {"n3"},
-                    "n3": {},
-                    "n4": {"n5"},
-                    "n5": {"n3"},
-                }
-            ),
-            (
-                {
-                    "inp1": {"n1"},
-                    "n1": {"n2", "n3"},
-                    "n2": {"n4"},
-                    "n3": {"n4"},
-                    "n4": {},
-                }
-            ),
-        ],
-        ids=["one_input_1", "one_input_2", "multi_inputs_1", "one_input_3"],
+        TestData.toposort_data["args"],
+        TestData.toposort_data["data"],
+        ids=TestData.toposort_data["ids"],
     )
-    def test_toposort(self, edges):
+    def test_toposort(self, nodes):
         """
         Test #1: one input 1
             INP1 -> N1 -> N2 -> N3
@@ -77,9 +37,13 @@ def test_toposort(self, edges):
         Test #4: one input 3
             INP1 -> N1 -> N2 -> N4
             N1 -> N3 -> N4
+
+        Test #5: headless neuron 1
+            INP1 -> N1 -> N2 -> N4
+            N3 -> N2
         """
-        ordered = toposort(edges)
-        assert len(ordered) == len(edges)
+        ordered = toposort(nodes)
+        assert len(ordered) == len(nodes)
 
     @pytest.mark.parametrize(
         "edges",
@@ -481,7 +445,7 @@ def get_longest_path_proto(
 
         Return: the longest distance in the graph.
         """
-        distances: Dict[NodeName, int] = defaultdict(int)  # init value = 0
+        distances: Dict[NodeName, int] = {node: 0 for node in ordered_nodes}
         pred_nodes: Dict[NodeName, NodeName] = defaultdict()
 
         for node in ordered_nodes:
@@ -508,79 +472,9 @@ def get_longest_path_proto(
         return path, distance
 
     @pytest.mark.parametrize(
-        "edges, expected_path, expected_distance",
-        [
-            (
-                # inp1 -> n1 -> n4 -> n2 -> n3, 1+1+1+1=4
-                {
-                    "inp1": {"n1": 1},
-                    "n1": {"n2": 1, "n4": 1},
-                    "n2": {"n3": 1},
-                    "n3": {},
-                    "n4": {"n2": 1},
-                },
-                ["inp1", "n1", "n4", "n2", "n3"],
-                4,
-            ),
-            (
-                # inp1 -> n1 -> n3 -> n4, 1+2+5=8
-                {
-                    "inp1": {"n1": 1},
-                    "n1": {"n2": 3, "n3": 2},
-                    "n2": {"n4": 2},
-                    "n3": {"n4": 5},
-                    "n4": {},
-                },
-                ["inp1", "n1", "n3", "n4"],
-                8,
-            ),
-            (
-                # inp1 -> n1 -> n2 -> n3, 1+2+1=4
-                {
-                    "inp1": {"n1": 1},
-                    "inp2": {"n2": 1},
-                    "n1": {"n2": 2},
-                    "n2": {"n3": 1},
-                    "n3": {},
-                },
-                ["inp1", "n1", "n2", "n3"],
-                4,
-            ),
-            (
-                # inp1 -> n1 -> n3 -> n5, 1+2+1=4
-                {
-                    "inp1": {"n1": 1},
-                    "n1": {"n2": 1, "n3": 2},
-                    "n2": {"n4": 1, "n5": 1},
-                    "n3": {"n4": 1},
-                    "n4": {},
-                    "n5": {},
-                },
-                ["inp1", "n1", "n3", "n4"],
-                4,
-            ),
-            (
-                # inp2 -> n5 -> n4, 4+1=5
-                {
-                    "inp1": {"n1": 1},
-                    "inp2": {"n5": 4},
-                    "n1": {"n2": 1, "n3": 1},
-                    "n2": {"n5": 1},
-                    "n3": {"n4": 1},
-                    "n4": {},
-                    "n5": {"n4": 1},
-                },
-                ["inp2", "n5", "n4"],
-                5,
-            ),
-        ],
-        ids=[
-            "one_input_1",
-            "one_input_2",
-            "multi_inputs_1",
-            "multi_outputs_1",
-            "multi_inputs_outputs_1",
-        ],
+        TestData.get_longest_path_data["args"],
+        TestData.get_longest_path_data["data"],
+        ids=TestData.get_longest_path_data["ids"],
     )
     def test_get_longest_path_proto(self, edges, expected_path, expected_distance):
         ordered = toposort(edges)
@@ -608,8 +502,11 @@ def get_shortest_path_proto(
         pred_nodes: Dict[NodeName, NodeName] = defaultdict()
 
         # Set initial value for all inputs nodes.
-        for inode in input_nodes:
-            distances[inode] = 0
+        if input_nodes:
+            for inode in input_nodes:
+                distances[inode] = 0
+        else:
+            distances[ordered_nodes[0]] = 0
 
         for node in ordered_nodes:
             for neighbor in edges_with_d[node]:
@@ -635,86 +532,9 @@ def get_shortest_path_proto(
         return path, distance
 
     @pytest.mark.parametrize(
-        "edges, inodes, expected_path, expected_distance",
-        [
-            (
-                # inp1 -> n1 -> n2 -> n3, 1+1+1=3
-                {
-                    "inp1": {"n1": 1},
-                    "n1": {"n2": 1, "n4": 1},
-                    "n2": {"n3": 1},
-                    "n3": {},
-                    "n4": {"n2": 1},
-                },
-                ["inp1"],
-                ["inp1", "n1", "n2", "n3"],
-                3,
-            ),
-            (
-                # inp1 -> n1 -> n2 -> n3 -> n6 -> n7 -> n4 =
-                # 1+1+3+2+2+3=12
-                {
-                    "inp1": {"n1": 1},
-                    "n1": {"n2": 1, "n5": 5},
-                    "n2": {"n3": 3},
-                    "n3": {"n4": 10, "n6": 2},
-                    "n4": {},
-                    "n5": {"n3": 5, "n6": 7},
-                    "n6": {"n7": 2},
-                    "n7": {"n4": 3},
-                },
-                ["inp1"],
-                ["inp1", "n1", "n2", "n3", "n6", "n7", "n4"],
-                12,
-            ),
-            (
-                # inp2 -> n2 -> n3, 1+1=2
-                {
-                    "inp1": {"n1": 1},
-                    "inp2": {"n2": 1},
-                    "n1": {"n2": 2},
-                    "n2": {"n3": 1},
-                    "n3": {},
-                },
-                ["inp1", "inp2"],
-                ["inp2", "n2", "n3"],
-                2,
-            ),
-            (
-                # inp1 -> n1 -> n2 -> n4, 1+1+1=3
-                {
-                    "inp1": {"n1": 1},
-                    "n1": {"n2": 1, "n3": 2},
-                    "n2": {"n4": 1},
-                    "n3": {"n4": 1},
-                    "n4": {},
-                },
-                ["inp1"],
-                ["inp1", "n1", "n2", "n4"],
-                3,
-            ),
-            (
-                # inp1 -> n1 -> n2 -> n4, 1+1+1=3
-                {
-                    "inp1": {"n1": 1},
-                    "n1": {"n2": 1, "n3": 1},
-                    "n2": {"n4": 2},
-                    "n3": {"n5": 1},
-                    "n4": {},
-                    "n5": {},
-                },
-                ["inp1"],
-                ["inp1", "n1", "n3", "n5"],
-                3,
-            ),
-        ],
-        ids=[
-            "one_input_1",
-            "one_input_2",
-            "multi_inputs_1",
-            "multi_outputs_1",
-            "multi_outputs_2",
-        ],
+        TestData.get_shortest_path_data["args"],
+        TestData.get_shortest_path_data["data"],
+        ids=TestData.get_shortest_path_data["ids"],
     )
     def test_get_shortest_path_proto(
         self, edges, inodes, expected_path, expected_distance
diff --git a/tests/conftest.py b/tests/conftest.py
index fa715e11..c5a17f29 100644
--- a/tests/conftest.py
+++ b/tests/conftest.py
@@ -1,8 +1,17 @@
+from typing import Any, List, NotRequired, TypedDict
 import pytest
 
 import paibox as pb
 
 
+class ParametrizedTestData(TypedDict):
+    """Parametrized test data in dictionary format."""
+
+    args: str
+    data: List[Any]
+    ids: NotRequired[List[str]]
+
+
 class Input_to_N1(pb.DynSysGroup):
     """Not nested network
     inp1 -> n1 -> s1 -> n2, n3

From 68eca96e60a1550f0d6a452b18465b741fa5e669 Mon Sep 17 00:00:00 2001
From: KafCoppelia <k740677208@gmail.com>
Date: Fri, 8 Mar 2024 19:52:08 +0800
Subject: [PATCH 07/68] =?UTF-8?q?=F0=9F=93=9D=20updated=20README?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

---
 .pre-commit-config.yaml |  1 -
 README.md               |  2 +-
 docs/Guide-of-PAIBox.md | 12 ++++++------
 poetry.lock             |  8 ++++----
 pyproject.toml          |  4 ++--
 5 files changed, 13 insertions(+), 14 deletions(-)

diff --git a/.pre-commit-config.yaml b/.pre-commit-config.yaml
index 67f8991b..0b05799e 100644
--- a/.pre-commit-config.yaml
+++ b/.pre-commit-config.yaml
@@ -43,7 +43,6 @@ repos:
     rev: 1.7.1
     hooks:
       - id: poetry-check
-      - id: poetry-lock
       - id: poetry-export
         args: ["-f", "requirements.txt"]
       - id: poetry-install
diff --git a/README.md b/README.md
index 935fc03c..c9dd7e93 100644
--- a/README.md
+++ b/README.md
@@ -8,7 +8,7 @@
     <a href="https://github.com/PAICookers/PAIBox/blob/master/pyproject.toml">
         <img src="https://img.shields.io/pypi/pyversions/paibox">
     </a>
-    <a href="https://github.com/PAICookers/PAIBox/releases/tag/v1.0.0a3">
+    <a href="https://github.com/PAICookers/PAIBox/releases/tag/v1.0.0a4">
         <img src="https://img.shields.io/github/v/release/PAICookers/PAIBox?include_prereleases&color=orange">
     </a>
     <a href="https://www.codefactor.io/repository/github/PAICookers/PAIBox">
diff --git a/docs/Guide-of-PAIBox.md b/docs/Guide-of-PAIBox.md
index 96eddcf1..4d8b4bfe 100644
--- a/docs/Guide-of-PAIBox.md
+++ b/docs/Guide-of-PAIBox.md
@@ -18,7 +18,7 @@ poetry install
 python = "^3.8"
 pydantic = "^2.0"
 numpy = "^1.23.0"
-paicorelib = "0.0.12"
+paicorelib = "0.0.13"
 ```
 
 通过pip安装PAIBox：
@@ -72,8 +72,9 @@ n1 = pb.neuron.IF(shape=10, threshold=127, reset_v=0, keep_shape=False, delay=1,
 - `reset_v`：神经元的重置膜电位。
 - `keep_shape`：是否在仿真记录数据时保持尺寸信息，默认为 `False`。实际进行运算的尺寸仍视为一维。
 - `delay`：设定该神经元组输出的延迟。默认为1，即本时间步的计算结果，**下一时间步**传递至后继神经元。
-- `tick_wait_start`: 设定该神经元组在第 `N` 个时间步时启动，0表示不启动。默认为1。
-- `tick_wait_end`: 设定该神经元组持续工作 `M` 个时间步，0表示**永远持续工作**。默认为0。
+- `tick_wait_start`：设定该神经元组在第 `N` 个时间步时启动，0表示不启动。默认为1。
+- `tick_wait_end`：设定该神经元组持续工作 `M` 个时间步，0表示**永远持续工作**。默认为0。
+- `unrolling_factor`：该参数与后端相关。展开因子表示神经元将被展开，部署至更多的物理核上，以降低延迟，并提高吞吐率。
 - `name`：可选，为该对象命名。
 
 #### LIF神经元
@@ -81,10 +82,10 @@ n1 = pb.neuron.IF(shape=10, threshold=127, reset_v=0, keep_shape=False, delay=1,
 LIF神经元实现了“泄露-积分-发射”神经元模型，其调用方式及参数如下：
 
 ```python
-n1 = pb.neuron.LIF(shape=128, threshold=127, reset_v=0, leaky_v=-1, keep_shape=False, name='n1')
+n1 = pb.neuron.LIF(shape=128, threshold=127, reset_v=0, leak_v=-1, keep_shape=False, name='n1')
 ```
 
-- `leaky_v`：LIF神经元的泄露值（有符号）。其他参数含义与IF神经元相同。
+- `leak_v`：LIF神经元的泄露值（有符号）。其他参数含义与IF神经元相同。
 
 #### Tonic Spiking神经元
 
@@ -223,7 +224,6 @@ s1= pb.synapses.NoDecay(source=n1, dest=n2, weights=weight1, conn_type=pb.SynCon
   ```
 
   其权重以标量的形式储存。由于在运算时标量会随着矩阵进行广播，因此计算正确且节省了存储开销。
-
 - 数组：尺寸要求为 `(N2,)`，可以自定义每组对应神经元之间的连接权重。如下例所示，设置 `weights` 为 `[1, 2, 3, 4, 5]`，
 
   ```python
diff --git a/poetry.lock b/poetry.lock
index 0d56ac62..0e708efa 100644
--- a/poetry.lock
+++ b/poetry.lock
@@ -130,13 +130,13 @@ reference = "tsinghua"
 
 [[package]]
 name = "paicorelib"
-version = "0.0.12"
+version = "0.0.13"
 description = "Library of PAICORE 2.0 in Python."
 optional = false
 python-versions = ">=3.8,<4.0"
 files = [
-    {file = "paicorelib-0.0.12-py3-none-any.whl", hash = "sha256:182de7dd543fdbffb2b59cec61982028210d7cc4a7caf7d932085055ddaf7505"},
-    {file = "paicorelib-0.0.12.tar.gz", hash = "sha256:d84910710e3c634d4316c50f071224dfa1763f8438d49b2ce986601add83bf07"},
+    {file = "paicorelib-0.0.13-py3-none-any.whl", hash = "sha256:0e6f56b55d59cffe0ced7920396c096e4024aa9774b71fab57a6ec02ebc25f8a"},
+    {file = "paicorelib-0.0.13.tar.gz", hash = "sha256:0112a5097ecd3899409f6d51930d88071922a576bd780038f84fa30120d90286"},
 ]
 
 [package.dependencies]
@@ -350,4 +350,4 @@ reference = "tsinghua"
 [metadata]
 lock-version = "2.0"
 python-versions = "^3.8"
-content-hash = "e4c053aefe29f7d01e3bda3d670b36a95b8834fa54e999ac239a04d0e2dbaf65"
+content-hash = "295f008b50237c89eb3f089a3ee5300773b140e93e4d879f87ba469b20e6ac36"
diff --git a/pyproject.toml b/pyproject.toml
index ca9a6e57..cf43b98f 100644
--- a/pyproject.toml
+++ b/pyproject.toml
@@ -1,6 +1,6 @@
 [tool.poetry]
 name = "paibox"
-version = "1.0.0a3"
+version = "1.0.0a4"
 description = "New toolbox of PAICORE 2.0."
 authors = ["Ziru Pan <zrpan@stu.pku.edu.cn>"]
 maintainers = ["Ziru Pan <zrpan@stu.pku.edu.cn>"]
@@ -21,7 +21,7 @@ exclude = ["paibox/backend/experimental"]
 python = "^3.8"
 pydantic = "^2.0"
 numpy = "^1.23.0"
-paicorelib = "0.0.12"
+paicorelib = "0.0.13"
 
 
 [tool.poetry.group.test.dependencies]

From 6ecb5d1d2927822bce7ba5cf785cec8e9a10a604 Mon Sep 17 00:00:00 2001
From: "pre-commit-ci[bot]"
 <66853113+pre-commit-ci[bot]@users.noreply.github.com>
Date: Fri, 8 Mar 2024 12:03:50 +0000
Subject: [PATCH 08/68] :rotating_light: auto fix by pre-commit hooks

---
 docs/Guide-of-PAIBox.md   | 1 +
 paibox/__init__.py        | 3 ++-
 tests/backend/conftest.py | 1 -
 tests/conftest.py         | 1 +
 4 files changed, 4 insertions(+), 2 deletions(-)

diff --git a/docs/Guide-of-PAIBox.md b/docs/Guide-of-PAIBox.md
index 4d8b4bfe..ee7ac977 100644
--- a/docs/Guide-of-PAIBox.md
+++ b/docs/Guide-of-PAIBox.md
@@ -224,6 +224,7 @@ s1= pb.synapses.NoDecay(source=n1, dest=n2, weights=weight1, conn_type=pb.SynCon
   ```
 
   其权重以标量的形式储存。由于在运算时标量会随着矩阵进行广播，因此计算正确且节省了存储开销。
+
 - 数组：尺寸要求为 `(N2,)`，可以自定义每组对应神经元之间的连接权重。如下例所示，设置 `weights` 为 `[1, 2, 3, 4, 5]`，
 
   ```python
diff --git a/paibox/__init__.py b/paibox/__init__.py
index e66df694..60c75a9b 100644
--- a/paibox/__init__.py
+++ b/paibox/__init__.py
@@ -10,7 +10,8 @@
 from .projection import InputProj as InputProj
 from .simulator import Probe as Probe
 from .simulator import Simulator as Simulator
-from .synapses import NoDecay as NoDecay, SynConnType as SynConnType
+from .synapses import NoDecay as NoDecay
+from .synapses import SynConnType as SynConnType
 
 __all__ = [
     "Mapper",
diff --git a/tests/backend/conftest.py b/tests/backend/conftest.py
index 0164b867..97a12417 100644
--- a/tests/backend/conftest.py
+++ b/tests/backend/conftest.py
@@ -25,7 +25,6 @@
 from paibox.backend.routing import RoutingCluster
 from paibox.generic import clear_name_cache
 from paibox.node import NodeList
-
 from tests.conftest import ParametrizedTestData
 
 
diff --git a/tests/conftest.py b/tests/conftest.py
index c5a17f29..6b582148 100644
--- a/tests/conftest.py
+++ b/tests/conftest.py
@@ -1,4 +1,5 @@
 from typing import Any, List, NotRequired, TypedDict
+
 import pytest
 
 import paibox as pb

From 78ff5af4cd4bcf47bbef4cdf9fb79f7a8778604e Mon Sep 17 00:00:00 2001
From: KafCoppelia <k740677208@gmail.com>
Date: Mon, 11 Mar 2024 15:10:24 +0800
Subject: [PATCH 09/68] =?UTF-8?q?=F0=9F=90=9B=20bugfix:=20added=20MAX=5FNE?=
 =?UTF-8?q?STED=5FLEVEL=20to=20implement=20parsing=20of=20nested=20structu?=
 =?UTF-8?q?res?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

---
 paibox/backend/graphs.py | 4 +++-
 paibox/network.py        | 7 ++++++-
 2 files changed, 9 insertions(+), 2 deletions(-)

diff --git a/paibox/backend/graphs.py b/paibox/backend/graphs.py
index 367a8dea..f2edec9f 100644
--- a/paibox/backend/graphs.py
+++ b/paibox/backend/graphs.py
@@ -98,7 +98,9 @@ def build(
         _edges: Collector[EdgeName, EdgeType] = Collector()
 
         for network in networks:
-            sub_nodes = network.nodes(level=1, include_self=False)
+            # FIXME MAX_NESTED_LEVEL is set manually in DynSysGroup.
+            # Do we need to take precautions in advance?
+            sub_nodes = network.nodes(level=network.MAX_NESTED_LEVEL, include_self=False)
             _nodes += sub_nodes.include(InputProj, NeuDyn).unique()
             _edges += sub_nodes.subset(SynSys).unique()
 
diff --git a/paibox/network.py b/paibox/network.py
index f3ae7bb5..fa478559 100644
--- a/paibox/network.py
+++ b/paibox/network.py
@@ -1,5 +1,5 @@
 import warnings
-from typing import Callable, List, Optional, Tuple, Type, Union
+from typing import Callable, ClassVar, List, Optional, Tuple, Type, Union
 
 import numpy as np
 from typing_extensions import TypeAlias
@@ -18,6 +18,8 @@
 
 
 class DynSysGroup(DynamicSys, Container):
+    MAX_NESTED_LEVEL: ClassVar[int] = 9
+
     def __init__(
         self,
         *components_as_tuple,
@@ -37,6 +39,9 @@ def update(self, **kwargs) -> None:
 
         TODO Prove that the operation sequence I->S->N can be divided into Ix->Sx->Nx->Iy->Sy->Ny & it has  \
             nothing to do with the network topology.
+            
+            The above expression cannot be completely established, and the condition needs to be met: the   \
+            dependent synapses of the neuron are in the same subgraph.
         """
         nodes = self.nodes(level=1, include_self=False).subset(DynamicSys).unique()
 

From f7afe1354aa08e9342c90f8a4e9b3672cb9ec006 Mon Sep 17 00:00:00 2001
From: KafCoppelia <k740677208@gmail.com>
Date: Mon, 11 Mar 2024 15:14:03 +0800
Subject: [PATCH 10/68] =?UTF-8?q?=E2=9C=85=20added=20tests=20for=20parsing?=
 =?UTF-8?q?=20of=20nested=20structures?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

---
 tests/backend/conftest.py    | 64 ++++++++++++++++++++++++++++++++++++
 tests/backend/test_mapper.py | 51 +++++++++++++++++++---------
 tests/test_network.py        | 10 ++++--
 3 files changed, 106 insertions(+), 19 deletions(-)

diff --git a/tests/backend/conftest.py b/tests/backend/conftest.py
index 97a12417..a529079e 100644
--- a/tests/backend/conftest.py
+++ b/tests/backend/conftest.py
@@ -3,6 +3,7 @@
 import tempfile
 from functools import partial
 from pathlib import Path
+from typing import Optional
 
 import numpy as np
 import pytest
@@ -435,6 +436,59 @@ def __init__(self):
         self.probe1 = pb.Probe(self.n_list[1], "output", name="n2_out")
 
 
+class ReusedStruct(pb.Network):
+    """Reused structure: pre_n -> syn -> post_n, 8-bit"""
+
+    def __init__(self, tws: int = 1, name: Optional[str] = None):
+        super().__init__(name=name)
+
+        self.pre_n = pb.LIF((10,), 10, 2, tick_wait_start=tws)
+        self.post_n = pb.LIF((10,), 10, 2, tick_wait_start=tws + 1)
+
+        w = np.random.randint(-128, 127, (10, 10), dtype=np.int8)
+        self.syn = pb.NoDecay(
+            self.pre_n, self.post_n, conn_type=pb.SynConnType.All2All, weights=w
+        )
+
+
+class Nested_Net_level_2(pb.DynSysGroup):
+    """Level 2 nested network: inp1 -> s1 -> ReusedStruct -> s2 -> ReusedStruct"""
+
+    def __init__(self, tws: int = 1, name: Optional[str] = None):
+        self.inp1 = pb.InputProj(1, shape_out=(10,))
+        subnet1 = ReusedStruct(tws=tws, name="Named_Reused_0")
+        subnet2 = ReusedStruct(tws=tws + 2, name="Named_Reused_1")
+
+        self.s1 = pb.NoDecay(
+            self.inp1,
+            subnet1.pre_n,
+            conn_type=pb.SynConnType.One2One,
+        )
+        self.s2 = pb.NoDecay(
+            subnet1.post_n,
+            subnet2.pre_n,
+            conn_type=pb.SynConnType.One2One,
+        )
+
+        super().__init__(subnet1, subnet2, name=name)
+
+
+class Nested_Net_level_3(pb.DynSysGroup):
+    """Level 3 nested network: inp1 -> s1 -> Nested_Net_level_2"""
+
+    def __init__(self):
+        self.inp1 = pb.InputProj(1, shape_out=(10,))
+        subnet1 = Nested_Net_level_2(name="Named_Nested_Net_level_2")
+
+        self.s1 = pb.NoDecay(
+            self.inp1,
+            subnet1["Named_Reused_0"].pre_n,
+            conn_type=pb.SynConnType.One2One,
+        )
+
+        super().__init__(subnet1)
+
+
 @pytest.fixture(scope="class")
 def build_example_net1():
     return NetForTest1()
@@ -500,6 +554,16 @@ def build_Network_with_container():
     return Network_with_container()
 
 
+@pytest.fixture(scope="class")
+def build_Nested_Net_level_2():
+    return Nested_Net_level_2()
+
+
+@pytest.fixture(scope="class")
+def build_Nested_Net_level_3():
+    return Nested_Net_level_3()
+
+
 @pytest.fixture(scope="class")
 def get_mapper() -> pb.Mapper:
     return pb.Mapper()
diff --git a/tests/backend/test_mapper.py b/tests/backend/test_mapper.py
index 539fb99a..a0b3d028 100644
--- a/tests/backend/test_mapper.py
+++ b/tests/backend/test_mapper.py
@@ -37,7 +37,6 @@ def test_multi_inputproj(
     ):
         net = build_multi_inputproj_net
         mapper: pb.Mapper = get_mapper
-
         mapper.build(net)
         mapper.compile()
         mapper.export(
@@ -54,7 +53,6 @@ def test_multi_inputproj2(
     ):
         net = build_multi_inputproj_net2
         mapper: pb.Mapper = get_mapper
-
         mapper.build(net)
         mapper.compile()
         mapper.export(
@@ -71,9 +69,9 @@ def test_multi_output_nodes(
     ):
         net = build_multi_onodes_net
         mapper: pb.Mapper = get_mapper
-
         mapper.build(net)
         mapper.compile()
+
         assert len(mapper.graph_info["output"]) == 2
 
         mapper.export(
@@ -88,7 +86,6 @@ def test_multi_output_nodes2(
     ):
         net = build_multi_onodes_net2
         mapper: pb.Mapper = get_mapper
-
         mapper.build(net)
         mapper.compile()
 
@@ -106,12 +103,32 @@ def test_multi_inodes_onodes(
     ):
         net = build_multi_inodes_onodes
         mapper: pb.Mapper = get_mapper
-
         mapper.build(net)
         mapper.compile()
+
         assert len(mapper.graph_info["input"]) == 2
         assert len(mapper.graph_info["output"]) == 2
 
+    def test_nested_net_L2_compile(self, get_mapper, build_Nested_Net_level_2):
+        net = build_Nested_Net_level_2
+        mapper: pb.Mapper = get_mapper
+        mapper.build(net)
+        mapper.compile()
+
+        assert len(mapper.graph.nodes.keys()) == 5
+        assert len(mapper.graph_info["input"]) == 1
+        assert len(mapper.graph_info["output"]) == 1
+
+    def test_nested_net_L3_compile(self, get_mapper, build_Nested_Net_level_3):
+        net2 = build_Nested_Net_level_3
+        mapper: pb.Mapper = get_mapper
+        mapper.build(net2)
+        mapper.compile()
+
+        assert len(mapper.graph.edges.keys()) == 5
+        assert len(mapper.graph_info["input"]) == 2
+        assert len(mapper.graph_info["output"]) == 1
+
 
 class TestMapperDebug:
     def test_build_graph(self, get_mapper, build_example_net1, build_example_net2):
@@ -120,22 +137,23 @@ def test_build_graph(self, get_mapper, build_example_net1, build_example_net2):
         net2 = build_example_net2
 
         mapper: pb.Mapper = get_mapper
-        mapper.clear()
         mapper.build(net1, net2)
+        mapper.compile()
 
-        assert mapper.graph.has_built == True
+        assert len(mapper.graph.nodes.keys()) == 8
+        assert len(mapper.graph_info["input"]) == 3
+        assert len(mapper.graph_info["output"]) == 2
 
     @pytest.fixture
-    def test_simple_net(self, get_mapper, build_example_net1):
-        """Go throught the backend"""
+    def compile_simple_net(self, get_mapper, build_example_net1):
+        """Reused fixture."""
         net = build_example_net1
 
         mapper: pb.Mapper = get_mapper
-        mapper.clear()
         mapper.build(net)
         mapper.compile()
 
-    @pytest.mark.usefixtures("test_simple_net")
+    @pytest.mark.usefixtures("compile_simple_net")
     def test_export_config_json(self, ensure_dump_dir, get_mapper):
         """Export all the configs into json"""
         mapper: pb.Mapper = get_mapper
@@ -149,7 +167,7 @@ def test_export_config_json(self, ensure_dump_dir, get_mapper):
         )
         print()
 
-    @pytest.mark.usefixtures("test_simple_net")
+    @pytest.mark.usefixtures("compile_simple_net")
     def test_find_neuron(self, get_mapper, build_example_net1):
         net: pb.Network = build_example_net1
         mapper: pb.Mapper = get_mapper
@@ -159,7 +177,7 @@ def test_find_neuron(self, get_mapper, build_example_net1):
 
         print()
 
-    @pytest.mark.usefixtures("test_simple_net")
+    @pytest.mark.usefixtures("compile_simple_net")
     def test_find_axon(self, get_mapper, build_example_net1):
         net: pb.Network = build_example_net1
         mapper: pb.Mapper = get_mapper
@@ -171,13 +189,14 @@ def test_find_axon(self, get_mapper, build_example_net1):
 
     def test_network_with_container(self, get_mapper, build_Network_with_container):
         net: pb.Network = build_Network_with_container
-
         mapper: pb.Mapper = get_mapper
-        mapper.clear()
         mapper.build(net)
         mapper.compile()
 
-        print()
+        assert len(mapper.graph.nodes.keys()) == 4
+        # Input projectioon is discnnected!
+        assert len(mapper.graph_info["input"]) == 0
+        assert len(mapper.graph_info["output"]) == 1
 
 
 class TestMapper_Export:
diff --git a/tests/test_network.py b/tests/test_network.py
index 67755fec..a9ed0a20 100644
--- a/tests/test_network.py
+++ b/tests/test_network.py
@@ -1,3 +1,4 @@
+from typing import Optional
 import numpy as np
 import pytest
 
@@ -10,8 +11,8 @@
 class Nested_Net_level_1(pb.DynSysGroup):
     """Level 1 nested network: pre_n -> syn -> post_n"""
 
-    def __init__(self):
-        super().__init__()
+    def __init__(self, name: Optional[str] = None):
+        super().__init__(name=name)
 
         self.pre_n = pb.LIF((10,), 10)
         self.post_n = pb.LIF((10,), 10)
@@ -110,7 +111,7 @@ class Nested_Net_level_2(pb.DynSysGroup):
             def __init__(self):
                 self.inp1 = pb.InputProj(1, shape_out=(10,))
                 subnet1 = Nested_Net_level_1()
-                subnet2 = Nested_Net_level_1()
+                subnet2 = Nested_Net_level_1(name="Named_SubNet")
                 self.s1 = pb.NoDecay(
                     self.inp1,
                     subnet1.pre_n,
@@ -144,6 +145,9 @@ def __init__(self):
             .unique()
             .not_subset(pb.DynSysGroup)
         )
+        
+        assert isinstance(net[f"{Nested_Net_level_1.__name__}_0"], pb.Network)
+        assert isinstance(net["Named_SubNet"], pb.Network)
 
         assert len(nodes) == 5
         assert len(nodes_excluded) == 3

From 6daa8e5ece99068c4df3d6bd4d72c85b2ecb8ef7 Mon Sep 17 00:00:00 2001
From: KafCoppelia <k740677208@gmail.com>
Date: Mon, 11 Mar 2024 15:26:01 +0800
Subject: [PATCH 11/68] =?UTF-8?q?=F0=9F=93=9D=20updated=20building=20a=20n?=
 =?UTF-8?q?ested=20network=20doc?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

---
 docs/Guide-of-PAIBox.md | 17 +++++++++--------
 1 file changed, 9 insertions(+), 8 deletions(-)

diff --git a/docs/Guide-of-PAIBox.md b/docs/Guide-of-PAIBox.md
index ee7ac977..77ca3efc 100644
--- a/docs/Guide-of-PAIBox.md
+++ b/docs/Guide-of-PAIBox.md
@@ -224,7 +224,6 @@ s1= pb.synapses.NoDecay(source=n1, dest=n2, weights=weight1, conn_type=pb.SynCon
   ```
 
   其权重以标量的形式储存。由于在运算时标量会随着矩阵进行广播，因此计算正确且节省了存储开销。
-
 - 数组：尺寸要求为 `(N2,)`，可以自定义每组对应神经元之间的连接权重。如下例所示，设置 `weights` 为 `[1, 2, 3, 4, 5]`，
 
   ```python
@@ -504,13 +503,15 @@ for i in range(5):
 有时网络中会重复出现类似的结构，这时先构建子网络，再多次例化复用是个不错的选择。
 
 ```python
+froom typing import Optional
 import paibox as pb
 
 class ReusedStructure(pb.Network):
-    def __init__(self, weight):
-        super().__init__()
-        self.pre_n = pb.LIF((10,), 10)
-        self.post_n = pb.LIF((10,), 10)
+    def __init__(self, weight, tws, name: Optional[str] = None):
+        super().__init__(name=name)
+
+        self.pre_n = pb.LIF((10,), 10, tick_wait_start=tws)
+        self.post_n = pb.LIF((10,), 10, tick_wait_start=tws+1)
         self.syn = pb.NoDecay(
             self.pre_n, self.post_n, conn_type=pb.SynConnType.All2All, weights=weight
         )
@@ -518,8 +519,8 @@ class ReusedStructure(pb.Network):
 class Net(pb.Network):
     def __init__(self, w1, w2):
         self.inp1 = pb.InputProj(1, shape_out=(10,))
-        subnet1 = ReusedStructure(w1)
-        subnet2 = ReusedStructure(w2)
+        subnet1 = ReusedStructure(w1, tws=1, name="Reused_Struct_0")
+        subnet2 = ReusedStructure(w2, tws=3, name="Reused_Struct_1")
         self.s1 = pb.NoDecay(
             self.inp1,
             subnet1.pre_n,
@@ -538,7 +539,7 @@ w2 = ...
 net = Net(w1, w2)
 ```
 
-上述示例代码中，我们先创建需复用的子网络 `ReusedStructure`，其结构为 `pre_n` -> `syn` -> `post_n`。而后，在父网络 `Net` 中实例化两个子网络 `subnet1`、 `subnet2`，并与父网络其他部分连接，此时网络结构为：`inp1` -> `s1` -> `subnet1` -> `s2` -> `subnet2`。最后，在为 `pb.Network` 初始化时，传入子网络 `subnet1`、 `subnet2`。由此，父网络 `Net` 才能发现子网络组件。
+上述示例代码中，我们先创建需复用的子网络 `ReusedStructure`，其结构为 `pre_n` -> `syn` -> `post_n`。而后，在父网络 `Net` 中实例化两个子网络 `subnet1`、 `subnet2`，并与父网络其他部分连接，此时网络结构为：`inp1` -> `s1` -> `subnet1` -> `s2` -> `subnet2`。最后，在为 `pb.Network` 初始化时，传入子网络 `subnet1`、 `subnet2`。由此，父网络 `Net` 才能发现子网络组件。如果想取到 `Net` 内的 `subnet1` 对象，可通过索引其名字 `Net["Reused_Struct_0"]` 取到。
 
 上述示例为一个二级嵌套网络，对于三级嵌套网络或更高（不推荐使用），可参考上述方式构建。
 

From 7ad909473933da8109a6c985003df4dadf5295a4 Mon Sep 17 00:00:00 2001
From: "pre-commit-ci[bot]"
 <66853113+pre-commit-ci[bot]@users.noreply.github.com>
Date: Mon, 11 Mar 2024 07:26:29 +0000
Subject: [PATCH 12/68] :rotating_light: auto fix by pre-commit hooks

---
 docs/Guide-of-PAIBox.md  | 1 +
 paibox/backend/graphs.py | 4 +++-
 paibox/network.py        | 2 +-
 tests/test_network.py    | 3 ++-
 4 files changed, 7 insertions(+), 3 deletions(-)

diff --git a/docs/Guide-of-PAIBox.md b/docs/Guide-of-PAIBox.md
index 77ca3efc..7bbc06be 100644
--- a/docs/Guide-of-PAIBox.md
+++ b/docs/Guide-of-PAIBox.md
@@ -224,6 +224,7 @@ s1= pb.synapses.NoDecay(source=n1, dest=n2, weights=weight1, conn_type=pb.SynCon
   ```
 
   其权重以标量的形式储存。由于在运算时标量会随着矩阵进行广播，因此计算正确且节省了存储开销。
+
 - 数组：尺寸要求为 `(N2,)`，可以自定义每组对应神经元之间的连接权重。如下例所示，设置 `weights` 为 `[1, 2, 3, 4, 5]`，
 
   ```python
diff --git a/paibox/backend/graphs.py b/paibox/backend/graphs.py
index f2edec9f..c488c0d7 100644
--- a/paibox/backend/graphs.py
+++ b/paibox/backend/graphs.py
@@ -100,7 +100,9 @@ def build(
         for network in networks:
             # FIXME MAX_NESTED_LEVEL is set manually in DynSysGroup.
             # Do we need to take precautions in advance?
-            sub_nodes = network.nodes(level=network.MAX_NESTED_LEVEL, include_self=False)
+            sub_nodes = network.nodes(
+                level=network.MAX_NESTED_LEVEL, include_self=False
+            )
             _nodes += sub_nodes.include(InputProj, NeuDyn).unique()
             _edges += sub_nodes.subset(SynSys).unique()
 
diff --git a/paibox/network.py b/paibox/network.py
index fa478559..fe9d5fd4 100644
--- a/paibox/network.py
+++ b/paibox/network.py
@@ -39,7 +39,7 @@ def update(self, **kwargs) -> None:
 
         TODO Prove that the operation sequence I->S->N can be divided into Ix->Sx->Nx->Iy->Sy->Ny & it has  \
             nothing to do with the network topology.
-            
+
             The above expression cannot be completely established, and the condition needs to be met: the   \
             dependent synapses of the neuron are in the same subgraph.
         """
diff --git a/tests/test_network.py b/tests/test_network.py
index a9ed0a20..2a742a32 100644
--- a/tests/test_network.py
+++ b/tests/test_network.py
@@ -1,4 +1,5 @@
 from typing import Optional
+
 import numpy as np
 import pytest
 
@@ -145,7 +146,7 @@ def __init__(self):
             .unique()
             .not_subset(pb.DynSysGroup)
         )
-        
+
         assert isinstance(net[f"{Nested_Net_level_1.__name__}_0"], pb.Network)
         assert isinstance(net["Named_SubNet"], pb.Network)
 

From 7868e394204035e2b952b64df580deb96b72d8e6 Mon Sep 17 00:00:00 2001
From: KafCoppelia <k740677208@gmail.com>
Date: Tue, 12 Mar 2024 14:19:44 +0800
Subject: [PATCH 13/68] =?UTF-8?q?=E2=9C=A8=20implemented=20recursive=20sea?=
 =?UTF-8?q?rch=20for=20all=20child=20nodes?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

---
 paibox/backend/graphs.py |  6 +----
 paibox/base.py           | 58 +++++++++++++++++++++++++++++++---------
 paibox/network.py        | 25 ++++++++---------
 3 files changed, 58 insertions(+), 31 deletions(-)

diff --git a/paibox/backend/graphs.py b/paibox/backend/graphs.py
index c488c0d7..0b663997 100644
--- a/paibox/backend/graphs.py
+++ b/paibox/backend/graphs.py
@@ -98,11 +98,7 @@ def build(
         _edges: Collector[EdgeName, EdgeType] = Collector()
 
         for network in networks:
-            # FIXME MAX_NESTED_LEVEL is set manually in DynSysGroup.
-            # Do we need to take precautions in advance?
-            sub_nodes = network.nodes(
-                level=network.MAX_NESTED_LEVEL, include_self=False
-            )
+            sub_nodes = network.nodes(include_self=False, find_recursive=True)
             _nodes += sub_nodes.include(InputProj, NeuDyn).unique()
             _edges += sub_nodes.subset(SynSys).unique()
 
diff --git a/paibox/base.py b/paibox/base.py
index 7ae8d428..898c5998 100644
--- a/paibox/base.py
+++ b/paibox/base.py
@@ -23,7 +23,12 @@ class PAIBoxObject:
     def __init__(self, name: Optional[str] = None) -> None:
         self._name: str = self.unique_name(name)
 
-    def __eq__(self, other) -> bool:
+    def __eq__(self, other: "PAIBoxObject") -> bool:
+        if not isinstance(other, PAIBoxObject):
+            raise TypeError(
+                f"Cannot compare {type(self).__name__} with {type(other).__name__}."
+            )
+
         if self is other:
             return True
 
@@ -59,44 +64,66 @@ def nodes(
         method: Literal["absolute", "relative"] = "absolute",
         level: int = -1,
         include_self: bool = True,
+        find_recursive: bool = False,
     ) -> Collector[str, "PAIBoxObject"]:
-        """Collect all the children nodes."""
-        return self._find_nodes(method, level, include_self)
+        """Collect all child nodes.
+
+        Args:
+            - method: the method to find the nodes.
+                - "absolute": the name of the node it is looking for will be `v.name`.
+                - "relative": the name will be its attribute name, `x` in `self.x = v`.
+            - level: the level at which the search ends.
+            - include_self: whether to include the current node itself.
+            - find_recursive: whether to search for nodes recursively until they are not found.
+        """
+        return self._find_nodes(method, level, include_self, find_recursive)
 
     def _find_nodes(
         self,
         method: Literal["absolute", "relative"] = "absolute",
         level: int = -1,
         include_self: bool = True,
-        lid: int = 0,
+        find_recursive: bool = False,
+        _lid: int = 0,
         _paths: Optional[Set[_IdPathType]] = None,
+        _iter_termination: bool = False,
     ) -> Collector[str, "PAIBoxObject"]:
         if _paths is None:
             _paths = set()
 
         gather = Collector()
+
         if include_self:
             if method == "absolute":
                 gather[self.name] = self
             else:
                 gather[""] = self
 
-        if (level > -1) and (lid >= level):
-            return gather
+        if find_recursive:
+            if _iter_termination:
+                return gather
+        else:
+            if (level > -1) and (_lid >= level):
+                return gather
+
+        iter_termi = True  # iteration termination flag
 
         def _find_nodes_absolute() -> None:
-            nonlocal gather, nodes
+            nonlocal gather, nodes, iter_termi
 
             for v in self.__dict__.values():
                 if isinstance(v, PAIBoxObject):
+                    iter_termi = False
                     _add_node2(self, v, _paths, gather, nodes)
                 elif isinstance(v, NodeList):
                     for v2 in v:
                         if isinstance(v2, PAIBoxObject):
+                            iter_termi = False
                             _add_node2(self, v2, _paths, gather, nodes)
                 elif isinstance(v, NodeDict):
                     for v2 in v.values():
                         if isinstance(v2, PAIBoxObject):
+                            iter_termi = False
                             _add_node2(self, v2, _paths, gather, nodes)
 
             # finding nodes recursively
@@ -106,24 +133,29 @@ def _find_nodes_absolute() -> None:
                         method=method,
                         level=level,
                         include_self=include_self,
-                        lid=lid + 1,
+                        find_recursive=find_recursive,
+                        _lid=_lid + 1,
                         _paths=_paths,
+                        _iter_termination=iter_termi,
                     )
                 )
 
         def _find_nodes_relative() -> None:
-            nonlocal gather, nodes
+            nonlocal gather, nodes, iter_termi
 
             for k, v in self.__dict__.items():
                 if isinstance(v, PAIBoxObject):
+                    iter_termi = False
                     _add_node1(self, k, v, _paths, gather, nodes)
                 elif isinstance(v, NodeList):
                     for i, v2 in enumerate(v):
                         if isinstance(v2, PAIBoxObject):
+                            iter_termi = False
                             _add_node1(self, f"{k}-{str(i)}", v2, _paths, gather, nodes)
                 elif isinstance(v, NodeDict):
                     for k2, v2 in v.items():
                         if isinstance(v2, PAIBoxObject):
+                            iter_termi = False
                             _add_node1(self, f"{k}.{k2}", v2, _paths, gather, nodes)
 
             # finding nodes recursively
@@ -132,8 +164,10 @@ def _find_nodes_relative() -> None:
                     method=method,
                     level=level,
                     include_self=include_self,
-                    lid=lid + 1,
+                    find_recursive=find_recursive,
+                    _lid=_lid + 1,
                     _paths=_paths,
+                    _iter_termination=iter_termi,
                 ).items():
                     if k2:
                         gather[f"{k1}.{k2}"] = v2
@@ -149,7 +183,7 @@ def _find_nodes_relative() -> None:
 
 
 def _add_node1(
-    obj: object,
+    obj: Any,
     k: str,
     v: PAIBoxObject,
     _paths: Set[_IdPathType],
@@ -165,7 +199,7 @@ def _add_node1(
 
 
 def _add_node2(
-    obj: object,
+    obj: Any,
     v: PAIBoxObject,
     _paths: Set[_IdPathType],
     gather: Collector[str, PAIBoxObject],
diff --git a/paibox/network.py b/paibox/network.py
index fe9d5fd4..ab314151 100644
--- a/paibox/network.py
+++ b/paibox/network.py
@@ -1,5 +1,5 @@
 import warnings
-from typing import Callable, ClassVar, List, Optional, Tuple, Type, Union
+from typing import Callable, List, Optional, Tuple, Type, Union
 
 import numpy as np
 from typing_extensions import TypeAlias
@@ -18,7 +18,6 @@
 
 
 class DynSysGroup(DynamicSys, Container):
-    MAX_NESTED_LEVEL: ClassVar[int] = 9
 
     def __init__(
         self,
@@ -43,7 +42,11 @@ def update(self, **kwargs) -> None:
             The above expression cannot be completely established, and the condition needs to be met: the   \
             dependent synapses of the neuron are in the same subgraph.
         """
-        nodes = self.nodes(level=1, include_self=False).subset(DynamicSys).unique()
+        nodes = (
+            self.nodes(include_self=False, find_recursive=True)
+            .subset(DynamicSys)
+            .unique()
+        )
 
         for node in nodes.subset(Projection).values():
             node(**kwargs)
@@ -54,13 +57,12 @@ def update(self, **kwargs) -> None:
         for node in nodes.subset(NeuDyn).values():
             node()
 
-        for node in (
-            nodes.not_subset(Projection).not_subset(SynSys).not_subset(NeuDyn).values()
-        ):
-            node()
-
     def reset_state(self) -> None:
-        nodes = self.nodes(level=1, include_self=False).subset(DynamicSys).unique()
+        nodes = (
+            self.nodes(include_self=False, find_recursive=True)
+            .subset(DynamicSys)
+            .unique()
+        )
 
         for node in nodes.subset(Projection).values():
             node.reset_state()
@@ -71,11 +73,6 @@ def reset_state(self) -> None:
         for node in nodes.subset(NeuDyn).values():
             node.reset_state()
 
-        for node in (
-            nodes.not_subset(Projection).not_subset(SynSys).not_subset(NeuDyn).values()
-        ):
-            node.reset_state()
-
     def __call__(self, **kwargs) -> None:
         return self.update(**kwargs)
 

From 868702e23c4a5cb55c81151a7165cbbd8dfcff18 Mon Sep 17 00:00:00 2001
From: KafCoppelia <k740677208@gmail.com>
Date: Tue, 12 Mar 2024 14:26:59 +0800
Subject: [PATCH 14/68] =?UTF-8?q?=E2=9C=85=20added=20tests=20for=20recursi?=
 =?UTF-8?q?ve=20search=20for=20nodes=20&=20removed=20useless=20test=20obje?=
 =?UTF-8?q?cts?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

---
 tests/conftest.py                 |  98 ++++++++++++++++-------
 tests/simulator/test_simulator.py |  52 +------------
 tests/test_network.py             | 125 ++++++------------------------
 3 files changed, 95 insertions(+), 180 deletions(-)

diff --git a/tests/conftest.py b/tests/conftest.py
index 6b582148..14b3e65d 100644
--- a/tests/conftest.py
+++ b/tests/conftest.py
@@ -1,5 +1,6 @@
-from typing import Any, List, NotRequired, TypedDict
-
+from typing import Any, List, Optional, TypedDict
+from typing_extensions import NotRequired
+import numpy as np
 import pytest
 
 import paibox as pb
@@ -89,30 +90,6 @@ def __init__(self):
         self.probe1 = pb.Probe(self.n_list[1], "output", name="n2_out")
 
 
-class MoreInput_Net(pb.DynSysGroup):
-    """Nested network, level 1.
-    n1 -> s1 -> n2 -> s2 -> n4
-
-    n3 -> s3 -> n4
-    """
-
-    def __init__(self):
-        super().__init__()
-        self.n1 = pb.neuron.TonicSpiking(2, 3)
-        self.n2 = pb.neuron.TonicSpiking(2, 3)
-        self.s1 = pb.synapses.NoDecay(
-            self.n1, self.n2, conn_type=pb.SynConnType.All2All
-        )
-        self.n3 = pb.neuron.TonicSpiking(2, 4)
-        self.n4 = pb.neuron.TonicSpiking(2, 3)
-        self.s2 = pb.synapses.NoDecay(
-            self.n2, self.n4, conn_type=pb.SynConnType.All2All
-        )
-        self.s3 = pb.synapses.NoDecay(
-            self.n3, self.n4, conn_type=pb.SynConnType.All2All
-        )
-
-
 class Network_with_multi_inodes_onodes(pb.Network):
     """
     INP1 -> S1 -> N1 -> S2 -> N2
@@ -141,6 +118,66 @@ def __init__(self):
         )
 
 
+class Nested_Net_L1(pb.DynSysGroup):
+    """Level 1 nested network: pre_n -> syn -> post_n"""
+
+    def __init__(self, name: Optional[str] = None):
+        super().__init__(name=name)
+
+        self.pre_n = pb.LIF((10,), 10)
+        self.post_n = pb.LIF((10,), 10)
+
+        w = np.random.randint(-128, 127, (10, 10), dtype=np.int8)
+        self.syn = pb.NoDecay(
+            self.pre_n, self.post_n, conn_type=pb.SynConnType.All2All, weights=w
+        )
+
+
+class Nested_Net_L2(pb.DynSysGroup):
+    """Level 2 nested network: inp1 -> s1 -> Nested_Net_L1 -> s2 -> Nested_Net_L1"""
+
+    def __init__(self, name: Optional[str] = None):
+        self.inp1 = pb.InputProj(1, shape_out=(10,))
+        subnet1 = Nested_Net_L1()
+        subnet2 = Nested_Net_L1(name="Named_SubNet_L1_1")
+        self.s1 = pb.NoDecay(
+            self.inp1,
+            subnet1.pre_n,
+            conn_type=pb.SynConnType.One2One,
+        )
+        self.s2 = pb.NoDecay(
+            subnet1.post_n,
+            subnet2.pre_n,
+            conn_type=pb.SynConnType.One2One,
+        )
+
+        super().__init__(subnet1, subnet2, name=name)
+        self.probe1 = pb.Probe(self.inp1, "spike")  # won't be discovered in level 3
+
+
+class Nested_Net_L3(pb.DynSysGroup):
+    """Level 3 nested network: inp1 -> s1 -> Named_Nested_Net_L2"""
+
+    def __init__(self):
+        self.inp1 = pb.InputProj(1, shape_out=(10,))
+        subnet1 = Nested_Net_L2(name="Named_Nested_Net_L2")
+
+        subnet1_of_subnet1 = subnet1[f"{Nested_Net_L1.__name__}_0"]
+
+        self.s1 = pb.NoDecay(
+            self.inp1,
+            subnet1_of_subnet1.pre_n,
+            conn_type=pb.SynConnType.One2One,
+        )
+
+        super().__init__(subnet1)
+
+        self.probe1 = pb.Probe(self.inp1, "spike")
+        self.probe2 = pb.Probe(subnet1_of_subnet1.pre_n, "spike")
+        self.probe3 = pb.Probe(subnet1_of_subnet1.pre_n, "voltage")
+        self.probe4 = pb.Probe(subnet1.s1, "output")
+
+
 @pytest.fixture(scope="class")
 def build_Input_to_N1():
     return Input_to_N1()
@@ -167,5 +204,10 @@ def build_multi_inodes_onodes():
 
 
 @pytest.fixture(scope="class")
-def build_MoreInput_Net():
-    return MoreInput_Net()
+def build_Nested_Net_L2():
+    return Nested_Net_L2()
+
+
+@pytest.fixture(scope="class")
+def build_Nested_Net_L3():
+    return Nested_Net_L3()
diff --git a/tests/simulator/test_simulator.py b/tests/simulator/test_simulator.py
index 267e2f64..935184ef 100644
--- a/tests/simulator/test_simulator.py
+++ b/tests/simulator/test_simulator.py
@@ -98,52 +98,6 @@ def __init__(self, n: int):
         self.n1_output = pb.Probe(self.n1, "spike")
 
 
-class Nested_Net_level_1(pb.DynSysGroup):
-    """Level 1 nested network: pre_n -> syn -> post_n"""
-
-    def __init__(self):
-        super().__init__()
-
-        self.pre_n = pb.LIF((10,), 2, tick_wait_start=2)
-        self.post_n = pb.LIF((10,), 10, tick_wait_start=3)
-
-        w = np.ones((10, 10), dtype=np.int8)
-        self.syn = pb.NoDecay(
-            self.pre_n, self.post_n, conn_type=pb.SynConnType.All2All, weights=w
-        )
-
-        self.probe_in_subnet = pb.Probe(self.pre_n, "spike")
-
-
-class Nested_Net_level_2(pb.DynSysGroup):
-    """Level 2 nested network: -> s1 -> Nested_Net_level_1"""
-
-    def __init__(self):
-        self.inp1 = pb.InputProj(None, shape_out=(10,))
-        self.n1 = pb.LIF((10,), 2, tick_wait_start=1)
-
-        subnet = Nested_Net_level_1()
-
-        self.s1 = pb.NoDecay(
-            self.inp1,
-            self.n1,
-            conn_type=pb.SynConnType.One2One,
-        )
-        self.s2 = pb.NoDecay(
-            self.n1,
-            subnet.pre_n,
-            conn_type=pb.SynConnType.One2One,
-        )
-
-        self.probe1 = pb.Probe(self.inp1, "spike")
-        self.probe2 = pb.Probe(self.n1, "spike")
-        self.probe3 = pb.Probe(self.n1, "voltage")
-        self.probe4 = pb.Probe(subnet.pre_n, "spike")
-        self.probe5 = pb.Probe(subnet.post_n, "spike")
-
-        super().__init__(subnet)
-
-
 class TestSimulator:
     def test_probe(self):
         net = Net1(100)
@@ -237,12 +191,12 @@ def test_sim_specify_inputs_2(self):
 
         sim.reset()
 
-    def test_sim_nested_net(self):
-        net = Nested_Net_level_2()
+    def test_sim_nested_net(self, build_Nested_Net_L3):
+        net = build_Nested_Net_L3
         sim = pb.Simulator(net, start_time_zero=False)
 
         # The probes defined in the subnets cannot be discovered.
-        assert len(sim.probes) == 5
+        assert len(sim.probes) == 4
 
         net.inp1.input = np.ones((10,), dtype=np.int8)
         sim.run(20)
diff --git a/tests/test_network.py b/tests/test_network.py
index 2a742a32..ff8962a8 100644
--- a/tests/test_network.py
+++ b/tests/test_network.py
@@ -1,5 +1,3 @@
-from typing import Optional
-
 import numpy as np
 import pytest
 
@@ -9,41 +7,7 @@
 from paibox.node import NodeDict
 
 
-class Nested_Net_level_1(pb.DynSysGroup):
-    """Level 1 nested network: pre_n -> syn -> post_n"""
-
-    def __init__(self, name: Optional[str] = None):
-        super().__init__(name=name)
-
-        self.pre_n = pb.LIF((10,), 10)
-        self.post_n = pb.LIF((10,), 10)
-
-        w = np.random.randint(-128, 127, (10, 10), dtype=np.int8)
-        self.syn = pb.NoDecay(
-            self.pre_n, self.post_n, conn_type=pb.SynConnType.All2All, weights=w
-        )
-
-
 class TestNetwork_Components_Discover:
-    def test_flatten_hzynet(self, build_MoreInput_Net):
-        net = build_MoreInput_Net
-
-        nodes1 = net.nodes(method="relative", level=1, include_self=True)
-        assert nodes1[""] == net
-        assert len(nodes1) == 8
-
-        # 2. Relative + include_self == False
-        nodes2 = net.nodes(method="relative", level=1, include_self=False)
-        assert len(nodes2) == 7
-
-        # 3. Absolute + include_self == True
-        nodes3 = net.nodes(method="absolute", level=1, include_self=True)
-        assert len(nodes3) == 8
-
-        # 4. Absolute + include_self == False
-        nodes4 = net.nodes(method="absolute", level=1, include_self=False)
-        assert len(nodes4) == 7
-
     def test_flatten_nodes(self, build_NotNested_Net):
         net = build_NotNested_Net
 
@@ -72,7 +36,7 @@ def test_flatten_nodes(self, build_NotNested_Net):
         )
         assert len(nodes4) == 3
 
-    def test_nested_net_level_1(self, build_Network_with_container):
+    def test_nested_net_L1(self, build_Network_with_container):
         net = build_Network_with_container
 
         # 1. Relative + include_self == True
@@ -105,28 +69,9 @@ def test_nested_net_level_1(self, build_Network_with_container):
         sim.run(10)
         sim.reset()
 
-    def test_nested_net_level_2(self):
-        class Nested_Net_level_2(pb.DynSysGroup):
-            """Level 2 nested network: inp1 -> s1 -> Nested_Net_level_1 -> s2 -> Nested_Net_level_1"""
-
-            def __init__(self):
-                self.inp1 = pb.InputProj(1, shape_out=(10,))
-                subnet1 = Nested_Net_level_1()
-                subnet2 = Nested_Net_level_1(name="Named_SubNet")
-                self.s1 = pb.NoDecay(
-                    self.inp1,
-                    subnet1.pre_n,
-                    conn_type=pb.SynConnType.One2One,
-                )
-                self.s2 = pb.NoDecay(
-                    subnet1.post_n,
-                    subnet2.pre_n,
-                    conn_type=pb.SynConnType.One2One,
-                )
-
-                super().__init__(subnet1, subnet2)
-
-        net = Nested_Net_level_2()
+    def test_nested_net_L2(self, build_Nested_Net_L2):
+        net: pb.Network = build_Nested_Net_L2
+
         nodes = net.nodes(level=1, include_self=False).subset(DynamicSys).unique()
         nodes_excluded = (
             net.nodes(level=1, include_self=False)
@@ -147,67 +92,41 @@ def __init__(self):
             .not_subset(pb.DynSysGroup)
         )
 
-        assert isinstance(net[f"{Nested_Net_level_1.__name__}_0"], pb.Network)
-        assert isinstance(net["Named_SubNet"], pb.Network)
+        from .conftest import Nested_Net_L1
+
+        assert isinstance(net[f"{Nested_Net_L1.__name__}_0"], pb.Network)
+        assert isinstance(net["Named_SubNet_L1_1"], pb.Network)
 
         assert len(nodes) == 5
         assert len(nodes_excluded) == 3
         assert len(nodes2) == 3 + 3 * 2
         assert len(nodes9) == len(nodes2)
 
-    def test_nested_net_level_3(self):
-        class Nested_Net_level_2(pb.DynSysGroup):
-            """Level 2 nested network: -> s1 -> Nested_Net_level_1"""
+        del Nested_Net_L1
 
-            def __init__(self, n: pb.neuron.Neuron):
-                subnet = Nested_Net_level_1()
-                self.s1 = pb.NoDecay(
-                    n,
-                    subnet.pre_n,
-                    conn_type=pb.SynConnType.One2One,
-                )
+    def test_nested_net_L2_find_nodes_recursively(self, build_Nested_Net_L2):
+        net: pb.Network = build_Nested_Net_L2
 
-                super().__init__(subnet)
-
-        class Nested_Net_level_3(pb.DynSysGroup):
-            """Level 3 nested network: inp1 -> s1 -> n1 -> Nested_Net_level_2 -> s1 -> Nested_Net_level_1"""
-
-            def __init__(self):
-                self.inp1 = pb.InputProj(1, shape_out=(10,))
-                self.n1 = pb.LIF((10,), 10)
-
-                net_level2 = Nested_Net_level_2(self.n1)
-                self.s1 = pb.NoDecay(
-                    self.inp1,
-                    self.n1,
-                    conn_type=pb.SynConnType.One2One,
-                )
-
-                super().__init__(net_level2)
-
-        net = Nested_Net_level_3()
-        nodes_excluded = (
-            net.nodes(level=1, include_self=False)
-            .subset(DynamicSys)
-            .unique()
-            .not_subset(pb.DynSysGroup)
-        )
-        nodes2 = (
-            net.nodes(level=2, include_self=False)
+        nodes = (
+            net.nodes(level=-1, include_self=False, find_recursive=True)
             .subset(DynamicSys)
             .unique()
             .not_subset(pb.DynSysGroup)
         )
-        nodes3 = (
-            net.nodes(level=3, include_self=False)
+
+        assert len(nodes) == 3 + 3 * 2
+
+    def test_nested_net_L3_find_nodes_recursively(self, build_Nested_Net_L3):
+        net: pb.Network = build_Nested_Net_L3
+
+        nodes = (
+            net.nodes(level=-1, include_self=False, find_recursive=True)
             .subset(DynamicSys)
             .unique()
             .not_subset(pb.DynSysGroup)
         )
 
-        assert len(nodes_excluded) == 3
-        assert len(nodes2) == 3 + 1
-        assert len(nodes3) == 3 + 1 + 3
+        assert len(nodes) == 2 + 3 + 2 * 3
 
 
 class TestNetwork_Components_Oprations:

From 0d646b4444c7bf62265fa6d36852e16a769f504e Mon Sep 17 00:00:00 2001
From: KafCoppelia <k740677208@gmail.com>
Date: Fri, 15 Mar 2024 16:09:03 +0800
Subject: [PATCH 15/68] =?UTF-8?q?=E2=9C=A8=20supported=202d=20convolution?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

---
 paibox/base.py                |  35 +++++-
 paibox/synapses/__init__.py   |  10 +-
 paibox/synapses/base.py       | 201 +++++++++++++++++++++++++++++++
 paibox/synapses/conv_utils.py | 171 ++++++++++++++++++++++++++
 paibox/synapses/synapses.py   | 221 +++++++++++-----------------------
 paibox/synapses/transforms.py | 175 ++++++++++++++++++---------
 6 files changed, 601 insertions(+), 212 deletions(-)
 create mode 100644 paibox/synapses/base.py
 create mode 100644 paibox/synapses/conv_utils.py

diff --git a/paibox/base.py b/paibox/base.py
index 898c5998..52dcecf5 100644
--- a/paibox/base.py
+++ b/paibox/base.py
@@ -1,5 +1,7 @@
 import sys
-from typing import Any, Dict, List, Literal, Optional, Set, Tuple
+import numpy as np
+from typing import Any, ClassVar, Dict, List, Literal, Optional, Set, Tuple, Union
+from numpy.typing import NDArray
 
 if sys.version_info >= (3, 10):
     from typing import TypeAlias
@@ -10,6 +12,8 @@
 from .generic import get_unique_name, is_name_unique
 from .mixin import ReceiveInputProj, StatusMemory, TimeRelatedNode
 from .node import NodeDict, NodeList
+from .types import WeightType
+
 
 __all__ = []
 
@@ -306,3 +310,32 @@ def unrolling_factor(self, factor: int) -> None:
             raise ValueError(f"'unrolling_factor' must be positive, but got {factor}.")
 
         self._unrolling_factor = factor
+
+
+class SynSys(DynamicSys):
+    CFLAG_ENABLE_WP_OPTIMIZATION: ClassVar[bool] = True
+    """Compilation flag for weight precision optimization."""
+
+    @property
+    def weights(self) -> WeightType:
+        raise NotImplementedError
+
+    @property
+    def weight_precision(self):
+        raise NotImplementedError
+
+    @property
+    def connectivity(self) -> NDArray[Union[np.bool_, np.int8]]:
+        raise NotImplementedError
+
+    @property
+    def n_axon_each(self) -> np.ndarray:
+        return np.sum(self.connectivity, axis=0)
+
+    @property
+    def num_axon(self) -> int:
+        return np.count_nonzero(np.any(self.connectivity, axis=1))
+
+    @property
+    def num_dendrite(self) -> int:
+        return np.count_nonzero(np.any(self.connectivity, axis=0))
diff --git a/paibox/synapses/__init__.py b/paibox/synapses/__init__.py
index 53355470..9b94bd66 100644
--- a/paibox/synapses/__init__.py
+++ b/paibox/synapses/__init__.py
@@ -1,6 +1,8 @@
-from .synapses import RIGISTER_MASTER_KEY_FORMAT
+from .base import RIGISTER_MASTER_KEY_FORMAT
+from .base import SynSys
+from .synapses import FullConn as FullConn
 from .synapses import NoDecay as NoDecay
-from .synapses import SynSys as SynSys
-from .transforms import ConnType as SynConnType
+from .synapses import Conv2d as Conv2d
+from .transforms import GeneralConnType as GeneralConnType
 
-__all__ = ["NoDecay", "SynSys", "SynConnType"]
+__all__ = ["Conv2d", "FullConn", "NoDecay", "GeneralConnType"]
diff --git a/paibox/synapses/base.py b/paibox/synapses/base.py
new file mode 100644
index 00000000..81bff250
--- /dev/null
+++ b/paibox/synapses/base.py
@@ -0,0 +1,201 @@
+import numpy as np
+
+from typing import ClassVar, Literal, Optional, Tuple, Union
+from paicorelib import HwConfig, WeightPrecision as WP
+
+from paibox.base import NeuDyn, SynSys
+from paibox.exceptions import ShapeError
+from paibox.neuron import Neuron
+from paibox.projection import InputProj
+from paibox.types import DataArrayType, SynOutType, WeightType
+
+from .conv_utils import _fm_ndim2_check
+from .transforms import (
+    Conv2dForward,
+    GeneralConnType as GConnType,
+    OneToOne,
+    AllToAll,
+    Identity,
+    MaskedLinear,
+    Transform,
+)
+
+RIGISTER_MASTER_KEY_FORMAT = "{0}.output"
+
+
+def _check_equal(num_in: int, num_out: int) -> int:
+    if num_in != num_out:
+        raise ShapeError(
+            f"The number of source & destination neurons must "
+            f"be equal, but {num_in} != {num_out}."
+        )
+
+    return num_in
+
+
+class Synapses:
+    def __init__(
+        self,
+        source: Union[NeuDyn, InputProj],
+        dest: NeuDyn,
+    ) -> None:
+        self.source = source
+        self.dest = dest
+
+    @property
+    def shape_in(self) -> Tuple[int, ...]:
+        return self.source.shape_out
+
+    @property
+    def shape_out(self) -> Tuple[int, ...]:
+        return self.dest.shape_in
+
+    @property
+    def num_in(self) -> int:
+        return self.source.num_out
+
+    @property
+    def num_out(self) -> int:
+        return self.dest.num_in
+
+
+class FullConnectedSyn(Synapses, SynSys):
+    def __init__(
+        self,
+        source: Union[NeuDyn, InputProj],
+        dest: NeuDyn,
+        name: Optional[str] = None,
+    ) -> None:
+        super().__init__(source, dest)
+        super(Synapses, self).__init__(name)
+
+        self.set_memory("_synout", np.zeros((self.num_out,), dtype=np.int32))
+
+        # Register `self` for the destination `NeuDyn`.
+        dest.register_master(RIGISTER_MASTER_KEY_FORMAT.format(self.name), self)
+
+    def __call__(self, *args, **kwargs) -> SynOutType:
+        return self.update(*args, **kwargs)
+
+    def update(self, spike: Optional[np.ndarray] = None, *args, **kwargs) -> SynOutType:
+        # Retrieve the spike at index `timestamp` of the dest neurons
+        if self.dest.is_working:
+            if isinstance(self.source, InputProj):
+                synin = self.source.output.copy() if spike is None else spike
+            else:
+                idx = self.dest.timestamp % HwConfig.N_TIMESLOT_MAX
+                synin = self.source.output[idx].copy() if spike is None else spike
+        else:
+            # Retrieve 0 to the dest neurons if it is not working
+            synin = np.zeros_like(self.source.spike, dtype=np.bool_)
+
+        self._synout = self.comm(synin).astype(np.int32)
+        return self._synout
+
+    def reset_state(self, *args, **kwargs) -> None:
+        # TODO Add other initialization methods in the future.
+        self.reset_memory()  # Call reset of `StatusMemory`.
+
+    def _set_comm(self, comm: Transform) -> None:
+        self.comm = comm
+
+    @property
+    def output(self) -> SynOutType:
+        return self._synout
+
+    @property
+    def weights(self) -> WeightType:
+        return self.comm.weights
+
+    @property
+    def weight_precision(self) -> WP:
+        return self.comm._get_wp(self.CFLAG_ENABLE_WP_OPTIMIZATION)
+
+    @property
+    def connectivity(self):
+        """The connectivity matrix in `np.ndarray` format."""
+        return self.comm.connectivity
+
+
+class FullConnSyn(FullConnectedSyn):
+    def __init__(
+        self,
+        source: Union[NeuDyn, InputProj],
+        dest: NeuDyn,
+        weights: DataArrayType,
+        conn_type: GConnType,
+        name: Optional[str] = None,
+    ) -> None:
+        super().__init__(source, dest, name)
+
+        if conn_type is GConnType.One2One:
+            comm = OneToOne(_check_equal(self.num_in, self.num_out), weights)
+        elif conn_type is GConnType.Identity:
+            if not isinstance(weights, (int, np.bool_, np.integer)):
+                raise TypeError(
+                    f"Expected type int, np.bool_, np.integer, but got type {type(weights)}"
+                )
+            comm = Identity(_check_equal(self.num_in, self.num_out), weights)
+        elif conn_type is GConnType.All2All:
+            comm = AllToAll((self.num_in, self.num_out), weights)
+        else:  # MatConn
+            if not isinstance(weights, np.ndarray):
+                raise TypeError(
+                    f"Expected type np.ndarray, but got type {type(weights)}"
+                )
+            comm = MaskedLinear((self.num_in, self.num_out), weights)
+
+        self._set_comm(comm)
+
+
+class Conv2dSyn(FullConnectedSyn):
+    _spatial_ndim: ClassVar[int] = 2
+
+    def __init__(
+        self,
+        source: Union[Neuron, InputProj],
+        dest: Neuron,
+        kernel: np.ndarray,
+        stride: Tuple[int, int],
+        # padding: Tuple[int, int],
+        fm_order: Literal["CHW", "HWC"],
+        order: Literal["OIHW", "IOHW"],
+        name: Optional[str] = None,
+    ) -> None:
+        super().__init__(source, dest, name)
+
+        if kernel.ndim != self._spatial_ndim + 2:
+            raise ShapeError(
+                f"The convolution kernel dimension must be {self._spatial_ndim + 2}, but got {kernel.ndim}."
+            )
+
+        if order == "IOHW":
+            _kernel = kernel.transpose(1, 0, 2, 3)
+        else:
+            _kernel = kernel.copy()
+
+        # O,I,H,W
+        out_channels, in_channels, kernel_h, kernel_w = _kernel.shape
+
+        # C,H,W
+        in_ch, in_h, in_w = _fm_ndim2_check(source._shape, fm_order)
+        out_ch, out_h, out_w = _fm_ndim2_check(dest._shape, fm_order)
+
+        if in_ch != in_channels:
+            raise ShapeError(f"Input channels mismatch: {in_ch} != {in_channels}")
+
+        if out_ch != out_channels:
+            raise ShapeError(f"Output channels mismatch: {out_ch} != {out_channels}")
+
+        # If padding is considered, the implementation of convolution unrolling
+        # is extremely complex, so fix it.
+        padding = (0, 0)
+
+        assert (in_h + 2 * padding[0] - kernel_h) // stride[0] + 1 == out_h
+        assert (in_w + 2 * padding[1] - kernel_w) // stride[1] + 1 == out_w
+
+        comm = Conv2dForward(
+            (in_h, in_w), (out_h, out_w), _kernel, stride, padding, fm_order
+        )
+
+        self._set_comm(comm)
diff --git a/paibox/synapses/conv_utils.py b/paibox/synapses/conv_utils.py
new file mode 100644
index 00000000..1f2f9668
--- /dev/null
+++ b/paibox/synapses/conv_utils.py
@@ -0,0 +1,171 @@
+from itertools import repeat
+from functools import partial
+from typing import Any, Iterable, Literal, Tuple, TypeVar, Union
+
+import numpy as np
+from numpy.typing import NDArray
+from paibox.exceptions import ShapeError
+from paibox.types import SynOutType, WeightType
+
+
+T = TypeVar("T")
+
+_TupleAnyType = Union[T, Tuple[T, ...]]
+_Tuple1Type = Union[T, Tuple[T]]
+_Tuple2Type = Union[T, Tuple[T, T]]
+_Tuple3Type = Union[T, Tuple[T, T, T]]
+_Tuple4Type = Union[T, Tuple[T, T, T, T]]
+
+_SizeAnyType = _TupleAnyType[int]
+_Size1Type = _Tuple1Type[int]
+_Size2Type = _Tuple2Type[int]
+_Size3Type = _Tuple3Type[int]
+_Size4Type = _Tuple4Type[int]
+
+Size2Type = Tuple[int, int]
+
+
+def _ntuple(x, n: int) -> Tuple[Any, ...]:
+    if isinstance(x, Iterable):
+        return tuple(x)
+
+    return tuple(repeat(x, n))
+
+
+_single = partial(_ntuple, n=1)
+_pair = partial(_ntuple, n=2)
+_triple = partial(_ntuple, n=3)
+_quadruple = partial(_ntuple, n=4)
+
+
+def _fm_ndim1_check(
+    fm_shape: _TupleAnyType, fm_order: Literal["CHW", "HWC"]
+) -> Size2Type:
+    if len(fm_shape) < 1 or len(fm_shape) > 2:
+        raise ShapeError()
+
+    if len(fm_shape) == 1:
+        channels, l = (1, *fm_shape)
+    else:
+        if fm_order is "CHW":
+            channels, l = fm_shape
+        else:
+            l, channels = fm_shape
+
+    return channels, l
+
+
+def _fm_ndim2_check(
+    fm_shape: _TupleAnyType, fm_order: Literal["CHW", "HWC"]
+) -> Tuple[int, int, int]:
+    if len(fm_shape) < 2 or len(fm_shape) > 3:
+        raise ShapeError()
+
+    if len(fm_shape) == 2:
+        channels, h, w = (1, *fm_shape)
+    else:
+        if fm_order is "CHW":
+            channels, h, w = fm_shape
+        else:
+            h, w, channels = fm_shape
+
+    return channels, h, w
+
+
+def _conv2d_unroll(
+    in_shape: Size2Type,
+    out_shape: Size2Type,
+    kernel: WeightType,
+    stride: Size2Type,
+    # padding: Size2Type,
+) -> WeightType:
+    """Unroll the convolution kernel of 2d convolution into a matrix."""
+    cout, cin, kh, kw = kernel.shape
+
+    ih, iw = in_shape
+    oh, ow = out_shape
+    in_size = ih * iw
+    out_size = oh * ow
+
+    w_unrolled = np.zeros((cin * in_size, cout * out_size), dtype=kernel.dtype)
+    zeros_image = np.zeros((cin * ih, iw * cout, out_size), dtype=kernel.dtype)
+
+    for i in range(oh):
+        for j in range(ow):
+            for ch_idx in np.ndindex(kernel.shape[:2]):
+                # [0] -> o_ch, [1] -> i_ch
+                zeros_image[
+                    i * stride[0]
+                    + ch_idx[1] * ih : i * stride[0]
+                    + ch_idx[1] * ih
+                    + kh,
+                    j * stride[1]
+                    + ch_idx[0] * iw : j * stride[1]
+                    + ch_idx[0] * iw
+                    + kw,
+                    i * ow + j,
+                ] = kernel[ch_idx[0], ch_idx[1], :, :]
+
+            t = (
+                zeros_image[:, :, i * ow + j]
+                .reshape(cin * ih, cout, iw)
+                .transpose(1, 0, 2)
+            )
+            for o_ch in range(cout):
+                w_unrolled[:, i * ow + j + o_ch * out_size] = t[o_ch].flatten()
+
+    return w_unrolled
+
+
+def _conv2d_faster(
+    x_chw: np.ndarray,
+    out_shape: Size2Type,
+    kernel: WeightType,
+    stride: Size2Type,
+    padding: Size2Type,
+) -> SynOutType:
+    xc, xh, xw = x_chw.shape
+
+    # (O, I, H, W)
+    cout, cin, kh, kw = kernel.shape
+    assert xc == cin
+
+    x_padded = np.pad(
+        x_chw,
+        ((0, 0), (padding[0], padding[0]), (padding[1], padding[1])),
+        mode="constant",
+    )
+
+    assert (xh + padding[0] * 2 - kh) // stride[0] + 1 == out_shape[0]
+    assert (xw + padding[1] * 2 - kw) // stride[1] + 1 == out_shape[1]
+
+    # kernel: (cout, cin, kh, kw) -> (cin*kh*kw, cout)
+    col_kernel = kernel.transpose(1, 2, 3, 0).reshape(-1, cout)
+
+    # padded: (cin, xh+2*p[0]-kh, xw+2*p[1]-kw) -> (oh*ow, cin*kh*kw)
+    col_fm = _im2col(x_padded, out_shape[0], out_shape[1], kh, kw, stride)
+
+    # out = np.zeros((cout,) + out_shape, dtype=np.int64)
+    # (oh*ow, cin*kh*kw) * (cin*kh*kw, cout) = (oh*ow, cout)
+    out = col_fm @ col_kernel  # + self.bias
+
+    # (oh*ow, cout) -> (oh, ow, cout) -> (cout, oh, ow)
+    out = out.reshape(out_shape + (cout,)).transpose(2, 0, 1)
+
+    return out.astype(np.int32)
+
+
+def _im2col(
+    x_padded: np.ndarray, oh: int, ow: int, kh: int, kw: int, stride: Size2Type
+) -> NDArray[np.int64]:
+    cols = np.zeros((oh * ow, x_padded.shape[0] * kh * kw), dtype=np.int64)
+
+    _, ph, pw = x_padded.shape
+
+    idx = 0
+    for i in range(0, ph - kh + 1, stride[0]):
+        for j in range(0, pw - kw + 1, stride[1]):
+            cols[idx] = x_padded[:, i : i + kh, j : j + kw].reshape(-1)
+            idx += 1
+
+    return cols
diff --git a/paibox/synapses/synapses.py b/paibox/synapses/synapses.py
index f6c054a6..67718c5e 100644
--- a/paibox/synapses/synapses.py
+++ b/paibox/synapses/synapses.py
@@ -1,106 +1,28 @@
-from typing import ClassVar, Optional, Tuple, Union
-
+import warnings
 import numpy as np
-from numpy.typing import NDArray
-from paicorelib import HwConfig
-from paicorelib import WeightPrecision as WP
-
-from paibox.base import DynamicSys, NeuDyn
-from paibox.exceptions import ShapeError
-from paibox.projection import InputProj
-from paibox.types import DataArrayType, WeightType
-
-from .transforms import *
-
-__all__ = ["NoDecay"]
-
-RIGISTER_MASTER_KEY_FORMAT = "{0}.output"
-
-
-class Synapses:
-    def __init__(
-        self,
-        source: Union[NeuDyn, InputProj],
-        dest: NeuDyn,
-        conn_type: ConnType,
-    ) -> None:
-        """
-        Args:
-            - source: the source group of neurons.
-            - dest: the destination group of neurons.
-            - conn_type: the type of connection.
-        """
-        self.source = source
-        self.dest = dest
-        self._check(conn_type)
-
-    def _check(self, conn_type: ConnType) -> None:
-        if conn_type is ConnType.One2One or conn_type is ConnType.Identity:
-            if self.num_in != self.num_out:
-                raise ShapeError(
-                    f"The number of source & destination neurons must "
-                    f"be equal, but {self.num_in} != {self.num_out}."
-                )
-
-    @property
-    def shape_in(self) -> Tuple[int, ...]:
-        return self.source.shape_out
-
-    @property
-    def shape_out(self) -> Tuple[int, ...]:
-        return self.dest.shape_in
-
-    @property
-    def num_in(self) -> int:
-        return self.source.num_out
-
-    @property
-    def num_out(self) -> int:
-        return self.dest.num_in
-
-
-class SynSys(Synapses, DynamicSys):
-    CFLAG_ENABLE_WP_OPTIMIZATION: ClassVar[bool] = True
-    """Compilation flag for weight precision optimization."""
-
-    def __call__(self, *args, **kwargs) -> NDArray[np.int32]:
-        return self.update(*args, **kwargs)
-
-    @property
-    def weights(self) -> WeightType:
-        raise NotImplementedError
 
-    @property
-    def weight_precision(self) -> WP:
-        raise NotImplementedError
+from typing import Literal, Optional, Union
 
-    @property
-    def connectivity(self) -> NDArray[Union[np.bool_, np.int8]]:
-        raise NotImplementedError
-
-    @property
-    def n_axon_each(self) -> np.ndarray:
-        return np.sum(self.connectivity, axis=0)
-
-    @property
-    def num_axon(self) -> int:
-        return np.count_nonzero(np.any(self.connectivity, axis=1))
+from paibox.base import NeuDyn
+from paibox.neuron import Neuron
+from paibox.projection import InputProj
+from paibox.types import DataArrayType
 
-    @property
-    def num_dendrite(self) -> int:
-        return np.count_nonzero(np.any(self.connectivity, axis=0))
+from .base import Conv2dSyn, FullConnSyn
+from .conv_utils import _pair, _Size2Type
+from .transforms import GeneralConnType as GConnType
 
+__all__ = ["FullConn", "Conv2d"]
 
-class NoDecay(SynSys):
-    """Synapses model with no decay."""
 
+class FullConn(FullConnSyn):
     def __init__(
         self,
         source: Union[NeuDyn, InputProj],
         dest: NeuDyn,
         weights: DataArrayType = 1,
         *,
-        conn_type: ConnType = ConnType.MatConn,
+        conn_type: GConnType = GConnType.MatConn,
         name: Optional[str] = None,
     ) -> None:
         """
@@ -111,68 +33,69 @@ def __init__(
             - conn_type: the type of connection.
             - name: name of this synapses. Optional.
         """
-        super().__init__(source, dest, conn_type)
-        super(Synapses, self).__init__(name)
-
-        if conn_type is ConnType.One2One:
-            self.comm = OneToOne(self.num_in, weights)
-        elif conn_type is ConnType.Identity:
-            if not isinstance(weights, (int, np.integer)):
-                raise TypeError(
-                    f"Expected type int, np.integer, but got type {type(weights)}"
-                )
-
-            self.comm = Identity(self.num_in, weights)
-        elif conn_type is ConnType.All2All:
-            self.comm = AllToAll((self.num_in, self.num_out), weights)
-        else:  # MatConn
-            if not isinstance(weights, np.ndarray):
-                raise TypeError(
-                    f"Expected type int, np.integer or np.ndarray, but got type {type(weights)}"
-                )
-
-            self.comm = MaskedLinear((self.num_in, self.num_out), weights)
-
-        self.weights.setflags(write=False)
-        self.set_memory("_synout", np.zeros((self.num_out,), dtype=np.int32))
+        super().__init__(source, dest, weights, conn_type, name)
 
-        # Register `self` for the destination `NeuDyn`.
-        dest.register_master(RIGISTER_MASTER_KEY_FORMAT.format(self.name), self)
 
-    def update(
-        self, spike: Optional[np.ndarray] = None, *args, **kwargs
-    ) -> NDArray[np.int32]:
-        # Retrieve the spike at index `timestamp` of the dest neurons
-        if self.dest.is_working:
-            if isinstance(self.source, InputProj):
-                synin = self.source.output.copy() if spike is None else spike
-            else:
-                idx = self.dest.timestamp % HwConfig.N_TIMESLOT_MAX
-                synin = self.source.output[idx].copy() if spike is None else spike
-        else:
-            # Retrieve 0 to the dest neurons if it is not working
-            synin = np.zeros_like(self.source.spike, dtype=np.bool_)
-
-        self._synout = self.comm(synin).astype(np.int32)
-        return self._synout
-
-    def reset_state(self, *args, **kwargs) -> None:
-        # TODO Add other initialization methods in the future.
-        self.reset_memory()  # Call reset of `StatusMemory`.
+class NoDecay(FullConn):
+    def __init__(
+        self,
+        source: Union[NeuDyn, InputProj],
+        dest: NeuDyn,
+        weights: DataArrayType = 1,
+        *,
+        conn_type: GConnType = GConnType.MatConn,
+        name: Optional[str] = None,
+    ) -> None:
+        warnings.warn(
+            "The `NoDecay` class will be deprecated in future versions, "
+            "use `FullConn` instead.",
+            DeprecationWarning,
+        )
 
-    @property
-    def output(self) -> NDArray[np.int32]:
-        return self._synout
+        super().__init__(source, dest, weights, conn_type=conn_type, name=name)
 
-    @property
-    def weights(self):
-        return self.comm.weights
 
-    @property
-    def weight_precision(self) -> WP:
-        return self.comm._get_wp(self.CFLAG_ENABLE_WP_OPTIMIZATION)
+class Conv2d(Conv2dSyn):
+    def __init__(
+        self,
+        source: Union[Neuron, InputProj],
+        dest: Neuron,
+        kernel: np.ndarray,
+        *,
+        stride: _Size2Type = 1,
+        # padding: _Size2Type = 0,
+        fm_order: Literal["CHW", "HWC"] = "CHW",
+        kernel_order: Literal["OIHW", "IOHW"] = "OIHW",
+        name: Optional[str] = None,
+    ) -> None:
+        """2d convolution synapses in fully-unrolled format.
 
-    @property
-    def connectivity(self):
-        """The connectivity matrix in `np.ndarray` format."""
-        return self.comm.connectivity
+        Arguments:
+            - source: source neuron(s). The dimensions need to be expressed explicitly as (C, H, W) or  \
+                (H, W, C). The feature map dimension order is specified by `fm_order`.
+            - dest: destination neuron(s).
+            - kernel: convolution kernel. Its dimension order must be (O,I,H,W) or (I,O,H,W), depending \
+                on the argument `kernel_order`.
+            - stride: the step size of the kernel sliding. It can be a scalar or a tuple of 2 integers.
+            - fm_order: dimension order of feature map. The order of input & output feature maps must be\
+                consistent, (C, H, W) or (H, W, C).
+            - kernel_order: dimension order of kernel, (O, I, H, W) or (I, O, H, W). (O, I, H, W) stands\
+                for (output channels, input channels, height, width).
+            - name: name of the 2d convolution. Optional.
+        """
+        if fm_order not in ("CHW", "HWC"):
+            raise ValueError(f"Unknown feature map order '{fm_order}'.")
+
+        if kernel_order not in ("OIHW", "IOHW"):
+            raise ValueError(f"Unknown kernel order '{kernel_order}'.")
+
+        super().__init__(
+            source,
+            dest,
+            kernel,
+            _pair(stride),
+            # _pair(padding),
+            fm_order,
+            kernel_order,
+            name=name,
+        )
diff --git a/paibox/synapses/transforms.py b/paibox/synapses/transforms.py
index 800b9108..94d22c7c 100644
--- a/paibox/synapses/transforms.py
+++ b/paibox/synapses/transforms.py
@@ -1,15 +1,23 @@
 from enum import Enum, auto, unique
-from typing import Tuple, Type, Union
+from typing import Literal, Type, Union
 
 import numpy as np
 from numpy.typing import NDArray
 from paicorelib import WeightPrecision as WP
 
+from .conv_utils import _conv2d_faster, _conv2d_unroll, Size2Type
 from paibox.exceptions import ShapeError
-from paibox.types import DataArrayType, IntScalarType, WeightType
+from paibox.types import DataArrayType, IntScalarType, SynOutType, WeightType
 from paibox.utils import is_shape
 
-__all__ = ["ConnType", "OneToOne", "AllToAll", "Identity", "MaskedLinear"]
+__all__ = [
+    "GeneralConnType",
+    "OneToOne",
+    "AllToAll",
+    "Identity",
+    "MaskedLinear",
+    "Conv2dForward",
+]
 
 
 MAX_INT1 = np.int8(1)
@@ -22,8 +30,14 @@
 MIN_INT8 = np.iinfo(np.int8).min
 
 
-@unique
 class ConnType(Enum):
+    """Basic connection enum type."""
+
+    pass
+
+
+@unique
+class GeneralConnType(ConnType):
     MatConn = auto()
     """General matrix connection."""
 
@@ -59,10 +73,13 @@ def _get_weight_precision(weight: np.ndarray, enable_wp_opt: bool) -> WP:
 
 
 class Transform:
-    weights: WeightType
-    """The actual weights in synapse. Must stored in `np.int8` format."""
+    def __init__(self, weights: WeightType) -> None:
+        self.weights = weights
+        """The actual weights in synapse. Must stored in `np.int8` format."""
+        self.weights.setflags(write=False)
 
-    def __call__(self, *args, **kwargs) -> NDArray[np.int32]:
+    def __call__(self, *args, **kwargs) -> SynOutType:
+        """Ensure that in all subclasses, the output dimensions are (M,)."""
         raise NotImplementedError
 
     def _get_wp(self, enable_wp_opt: bool) -> WP:
@@ -89,31 +106,33 @@ def __init__(self, num: int, weights: DataArrayType) -> None:
         Arguments:
             - num: number of neurons.
             - weights: synaptic weights. The shape must be a scalar or array (num,).
-                If `weights` is a scalar(ndim = 0), the connectivity matrix will be:
-                [[x, 0, 0]
-                 [0, x, 0]
-                 [0, 0, x]]
-
-                Or `weights` is an array(ndim = 1), [x, y, z] corresponding to the weights of \
-                    the post-neurons respectively. The connectivity matrix will be:
-                [[x, 0, 0]
-                 [0, y, 0]
-                 [0, 0, z]]
+                - weights is a scalar(ndim = 0), the connectivity matrix will be:
+                    [[x, 0, 0]
+                     [0, x, 0]
+                     [0, 0, x]]
+                - weights is an array(ndim = 1), [x, y, z] corresponding to the weights \
+                    of the post-neurons respectively. The connectivity matrix will be:
+                    [[x, 0, 0]
+                     [0, y, 0]
+                     [0, 0, z]]
         """
         self.num = num
 
         if isinstance(weights, np.ndarray) and not is_shape(weights, (num,)):
             raise ShapeError(
-                f"Excepted shape is ({num},), but we got shape {weights.shape}"
+                f"Expected shape is ({num},), but we got shape {weights.shape}"
             )
 
         # The ndim of weights = 0 or 1.
-        self.weights = np.asarray(weights, dtype=np.int8)
+        _w = np.asarray(weights, dtype=np.int8)
+
+        if _w.ndim not in (0, 1):
+            raise ShapeError(f"The ndim of weights must be 0 or 1, but got {_w.ndim}.")
 
-        if not self.weights.ndim in (0, 1):
-            raise ShapeError(f"The ndim of weights must be 0 or 1.")
+        super().__init__(_w)
 
-    def __call__(self, x: np.ndarray, *args, **kwargs) -> NDArray[np.int32]:
+    def __call__(self, x: np.ndarray, *args, **kwargs) -> SynOutType:
+        # (N,) * (N,) -> (N,)
         output = x * self.weights.copy()
 
         return output.astype(np.int32)
@@ -138,48 +157,48 @@ def __init__(self, num: int, scaling_factor: IntScalarType = 1) -> None:
 
 
 class AllToAll(Transform):
-    def __init__(self, conn_size: Tuple[int, int], weights: DataArrayType) -> None:
+    def __init__(self, conn_size: Size2Type, weights: DataArrayType) -> None:
         """
         Arguments:
-            - num_in: number of source neurons.
-            - num_out: number of destination neurons.
+            - conn_size: size of connections.
             - weights: synaptic weights. The shape must be a scalar or a matrix.
-                If `weights` is a scalar(ndim = 0), the connectivity matrix will be:
-                [[x, x, x]
-                 [x, x, x]
-                 [x, x, x]]
-
-                Or `weights` is a matrix(ndim = 2), then the connectivity matrix will be:
-                [[a, b, c]
-                 [d, e, f]
-                 [g, h, i]]
+                - when weights is a scalar(ndim = 0), the connectivity matrix will be:  \
+                    x * I
+                - when weights is a matrix(ndim = 2), the connectivity matrix will be:  \
+                    [[a, b, c]
+                     [d, e, f]
+                     [g, h, i]]
         """
         self.conn_size = conn_size
 
         if isinstance(weights, np.ndarray) and not is_shape(weights, conn_size):
             raise ShapeError(
-                f"Excepted shape is {conn_size}, but we got shape {weights.shape}"
+                f"Expected shape is {conn_size}, but we got shape {weights.shape}"
             )
 
-        self.weights = np.asarray(weights, dtype=np.int8)
+        _w = np.asarray(weights, dtype=np.int8)
 
-        if not self.weights.ndim in (0, 2):
-            raise ShapeError(f"The ndim of weights must be 0 or 2.")
+        if _w.ndim not in (0, 2):
+            raise ShapeError(f"The ndim of weights must be 0 or 2, but got {_w.ndim}.")
 
-    def __call__(self, x: np.ndarray, *args, **kwargs) -> NDArray[np.int32]:
+        super().__init__(_w)
+
+    def __call__(self, x: np.ndarray, *args, **kwargs) -> SynOutType:
         """
-        - When weights is a scalar, the output is a scalar. (Risky, DO NOT USE)
-        - When weights is a matrix, the output is the dot product of `x` & `weights`.
+        NOTE: 
+            - When weights is a scalar, the output is a scalar (sum * w) & repeated     \
+                `conn_size[1]` times.
+            - When weights is a matrix, the output is the dot product of `x` & weights.
         """
         if self.weights.ndim == 0:
             sum_x = np.sum(x, axis=None, dtype=np.int32)
-            output = self.weights * np.full((self.conn_size[1],), sum_x, dtype=np.int32)
-            # Risky
-            # output = self.weights * sum_x
+            # (M,)
+            output = np.full((self.conn_size[1],), self.weights * sum_x, dtype=np.int32)
         else:
+            # (N,) @ (N, M) -> (M,)
             output = x @ self.weights.copy().astype(np.int32)
 
-        return output.astype(np.int32)
+        return output
 
     @property
     def connectivity(self):
@@ -195,25 +214,19 @@ def connectivity(self):
 class MaskedLinear(Transform):
     def __init__(
         self,
-        conn_size: Tuple[int, int],
+        conn_size: Size2Type,
         weights: np.ndarray,
     ) -> None:
-        """
-        Arguments:
-            - conn: connector. Only support `MatConn`.
-            - weights: unmasked weights.
-        """
-        self.conn_size = conn_size
-
-        if not is_shape(weights, self.conn_size):
+        if not is_shape(weights, conn_size):
             raise ShapeError(
-                f"Excepted shape is {conn_size}, but we got {weights.shape}"
+                f"Expected shape is {conn_size}, but we got {weights.shape}"
             )
 
-        # Element-wise Multiplication
-        self.weights = np.asarray(weights, dtype=np.int8)
+        _w = np.asarray(weights, dtype=np.int8)
+        super().__init__(_w)
 
-    def __call__(self, x: np.ndarray, *args, **kwargs) -> NDArray[np.int32]:
+    def __call__(self, x: np.ndarray, *args, **kwargs) -> SynOutType:
+        # (N,) @ (N, M) -> (M,)
         output = x @ self.weights.copy().astype(np.int32)
 
         return output.astype(np.int32)
@@ -221,3 +234,49 @@ def __call__(self, x: np.ndarray, *args, **kwargs) -> NDArray[np.int32]:
     @property
     def connectivity(self):
         return self.weights.astype(self.conn_dtype)
+
+
+class Conv2dForward(Transform):
+    def __init__(
+        self,
+        in_shape: Size2Type,
+        out_shape: Size2Type,
+        kernel: np.ndarray,
+        stride: Size2Type,
+        padding: Size2Type,
+        fm_order: Literal["CHW", "HWC"],
+    ) -> None:
+        self.in_shape = in_shape
+        self.out_shape = out_shape
+        self.stride = stride
+        self.padding = padding
+        self.fm_order = fm_order
+
+        _w = kernel.astype(np.int8)
+        super().__init__(_w)
+
+    def __call__(self, x: np.ndarray, *args, **kwargs) -> SynOutType:
+        cin = self.weights.shape[1]
+
+        if self.fm_order == "HWC":
+            # (N,) -> (H, W, C) -> (C, H, W)
+            _x = x.reshape(self.in_shape + (cin,))
+            _x = _x.transpose(2, 0, 1)
+        else:
+            _x = x.reshape((cin,) + self.in_shape)
+
+        o_conv2d = _conv2d_faster(
+            _x,
+            self.out_shape,
+            self.weights,
+            self.stride,
+            self.padding,
+        )
+
+        return o_conv2d.flatten()
+
+    @property
+    def connectivity(self):
+        return _conv2d_unroll(
+            self.in_shape, self.out_shape, self.weights, self.stride
+        ).astype(self.conn_dtype)

From 19f290faff164b16f35806d27c9bc8de1fb3e906 Mon Sep 17 00:00:00 2001
From: KafCoppelia <k740677208@gmail.com>
Date: Fri, 15 Mar 2024 16:10:07 +0800
Subject: [PATCH 16/68] =?UTF-8?q?=E2=9C=A8=20improved=20typing=20&=20libra?=
 =?UTF-8?q?ries=20import?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

---
 paibox/__init__.py              | 43 +++++++++++++++++++++------------
 paibox/backend/conf_template.py | 16 ++++++++++--
 paibox/backend/mapper.py        |  2 +-
 paibox/collector.py             |  4 +--
 paibox/neuron/__init__.py       |  2 +-
 paibox/neuron/base.py           |  2 +-
 paibox/projection.py            | 21 +++++++---------
 paibox/simulator/encoder.py     |  6 ++---
 paibox/tools.py                 | 13 ++++++++++
 paibox/types.py                 | 13 +++-------
 paibox/utils.py                 |  5 +---
 11 files changed, 77 insertions(+), 50 deletions(-)
 create mode 100644 paibox/tools.py

diff --git a/paibox/__init__.py b/paibox/__init__.py
index 60c75a9b..ffe52dc7 100644
--- a/paibox/__init__.py
+++ b/paibox/__init__.py
@@ -10,22 +10,10 @@
 from .projection import InputProj as InputProj
 from .simulator import Probe as Probe
 from .simulator import Simulator as Simulator
+from .synapses import Conv2d as Conv2d
+from .synapses import FullConn as FullConn
 from .synapses import NoDecay as NoDecay
-from .synapses import SynConnType as SynConnType
-
-__all__ = [
-    "Mapper",
-    "DynSysGroup",
-    "Network",
-    "NodeDict",
-    "NodeList",
-    "InputProj",
-    "Simulator",
-    "SynConnType",
-    "Probe",
-    "BACKEND_CONFIG",
-    "FRONTEND_ENV",
-]
+from .synapses import GeneralConnType as SynConnType
 
 from importlib.metadata import version
 
@@ -33,3 +21,28 @@
     __version__ = version("paibox")
 except Exception:
     __version__ = None
+
+from paibox import tools
+
+# Minimum required version of paicorelib
+__plib_minimum_version__ = "0.0.13"
+
+try:
+    import paicorelib as plib
+
+    if hasattr(plib, "get_version"):  # For plib <= 0.0.12
+        raise ImportError(
+            tools.PLIB_UPDATE_INTRO.format(
+                __plib_minimum_version__, ".".join(map(str, plib.get_version()))
+            )
+        ) from None
+
+    if plib.__version__ < __plib_minimum_version__:  # For plib > 0.0.12
+        raise ImportError(
+            tools.PLIB_UPDATE_INTRO.format(__plib_minimum_version__, plib.__version__)
+        ) from None
+
+    del tools, plib
+
+except ModuleNotFoundError:
+    raise ModuleNotFoundError(tools.PLIB_INSTALL_INTRO) from None
diff --git a/paibox/backend/conf_template.py b/paibox/backend/conf_template.py
index 7c881254..7b6e3709 100644
--- a/paibox/backend/conf_template.py
+++ b/paibox/backend/conf_template.py
@@ -23,8 +23,9 @@
     WeightPrecision,
     get_replication_id,
 )
+
+from paicorelib.framelib import types
 from paicorelib.framelib.frame_gen import OfflineFrameGen
-from paicorelib.framelib.types import FRAME_DTYPE, FrameArrayType
 from paicorelib.framelib.utils import np2bin, np2npy, np2txt
 from typing_extensions import NotRequired, TypeAlias
 
@@ -33,6 +34,17 @@
 from .context import _BACKEND_CONTEXT
 from .graphs_types import NodeName
 
+# Prevent import errors caused by changes in type definitions in paicorelib.
+if hasattr(types, "FRAME_DTYPE"):
+    FRAME_DTYPE = types.FRAME_DTYPE
+else:
+    FRAME_DTYPE = np.uint64
+
+if hasattr(types, "FrameArrayType"):
+    FrameArrayType = types.FrameArrayType
+else:
+    FrameArrayType = NDArray[FRAME_DTYPE]
+
 
 class CoreConfig(NamedTuple):
     """Configurations of core."""
@@ -284,7 +296,7 @@ def gen_config_frames_by_coreconf(
         - format: `txt`, `bin`, or `npy`. `bin` & `npy` are recommended.
     """
 
-    def _write_to_f(name: str, array: np.ndarray) -> None:
+    def _write_to_f(name: str, array: FrameArrayType) -> None:
         nonlocal fp, format
 
         _fp = fp / (name + f".{format}")
diff --git a/paibox/backend/mapper.py b/paibox/backend/mapper.py
index de171248..6700801d 100644
--- a/paibox/backend/mapper.py
+++ b/paibox/backend/mapper.py
@@ -132,7 +132,7 @@ def compile(
                 occupied cores, or both. The default is specified by the corresponding compilation option in the\
                 backend configuration item (`both` by default).
 
-        Return: compiled network information in dictionary form.
+        Return: network information after compilation in dictionary format.
         """
         if weight_bit_optimization is not None:
             set_cflag(enable_wp_opt=weight_bit_optimization)
diff --git a/paibox/collector.py b/paibox/collector.py
index bf15c24e..b8f41359 100644
--- a/paibox/collector.py
+++ b/paibox/collector.py
@@ -30,7 +30,7 @@ def update(
     ) -> Union["Collector[_KT, _VT]", "Collector[_KT, _T]"]:
         if not isinstance(other, (dict, list, tuple)):
             raise TypeError(
-                f"Excepted a dict, list or sequence, but we got {other}, type {type(other)}"
+                f"Expected a dict, list or sequence, but we got {other}, type {type(other)}"
             )
 
         if isinstance(other, dict):
@@ -75,7 +75,7 @@ def __sub__(
     ) -> Union["Collector[_KT, _VT]", "Collector[str, _T]"]:
         if not isinstance(other, (dict, list, tuple)):
             raise TypeError(
-                f"Excepted a dict, list or sequence, but we got {other}, type {type(other)}"
+                f"Expected a dict, list or sequence, but we got {other}, type {type(other)}"
             )
 
         gather = type(self)(self)
diff --git a/paibox/neuron/__init__.py b/paibox/neuron/__init__.py
index 3b2a4223..59b21939 100644
--- a/paibox/neuron/__init__.py
+++ b/paibox/neuron/__init__.py
@@ -1,4 +1,4 @@
-from .base import Neuron as Neuron
+from .base import Neuron
 from .neurons import IF as IF
 from .neurons import LIF as LIF
 from .neurons import PhasicSpiking as PhasicSpiking
diff --git a/paibox/neuron/base.py b/paibox/neuron/base.py
index 6f47110e..741ea50e 100644
--- a/paibox/neuron/base.py
+++ b/paibox/neuron/base.py
@@ -97,7 +97,7 @@ def _neuronal_charge(
 
         if self.synaptic_integration_mode is SIM.MODE_STOCHASTIC:
             raise NotImplementedError(
-                f"Mode {SIM.MODE_STOCHASTIC.name} not implemented."
+                f"Mode {SIM.MODE_STOCHASTIC.name} is not implemented."
             )
         else:
             if incoming_v.ndim == 2:
diff --git a/paibox/projection.py b/paibox/projection.py
index 7e1cf62b..ca0d4b1f 100644
--- a/paibox/projection.py
+++ b/paibox/projection.py
@@ -60,7 +60,7 @@ def __init__(
             self._num_input = input
             self._func_input = _func_bypass
 
-        self._shape_out = as_shape(shape_out)
+        self._shape = as_shape(shape_out)
         self.keep_shape = keep_shape
 
         self.set_memory("_inner_spike", np.zeros((self.num_out,), dtype=np.bool_))
@@ -71,16 +71,15 @@ def update(self, **kwargs) -> SpikeType:
         if isinstance(_spike, (int, np.bool_, np.integer)):
             self._inner_spike = np.full((self.num_out,), _spike, dtype=np.bool_)
         elif isinstance(_spike, np.ndarray):
-            try:
-                self._inner_spike = _spike.reshape((self.num_out,)).astype(np.bool_)
-            except ValueError:
+            if shape2num(_spike.shape) != self.num_out:
                 raise ShapeError(
-                    f"Cannot reshape input value from {_spike.shape} to ({self.num_out},)."
+                    f"Cannot reshape output value from {_spike.shape} to ({self.num_out},)."
                 )
+            self._inner_spike = _spike.flatten().astype(np.bool_)
         else:
-            # Should be never
+            # should never be reached
             raise TypeError(
-                f"Excepted type int, np.bool_, np.integer or np.ndarray, "
+                f"Expected type int, np.bool_, np.integer or np.ndarray, "
                 f"but got {_spike}, type {type(_spike)}."
             )
 
@@ -113,7 +112,7 @@ def num_in(self) -> int:
 
     @property
     def num_out(self) -> int:
-        return shape2num(self._shape_out)
+        return shape2num(self._shape)
 
     @property
     def shape_in(self) -> Tuple[int, ...]:
@@ -121,7 +120,7 @@ def shape_in(self) -> Tuple[int, ...]:
 
     @property
     def shape_out(self) -> Tuple[int, ...]:
-        return self._shape_out
+        return self._shape
 
     @property
     def input(self):
@@ -132,7 +131,7 @@ def input(self, value: DataType) -> None:
         """Set the input at the beginning of running the simulation."""
         if not isinstance(value, (int, np.bool_, np.integer, np.ndarray)):
             raise TypeError(
-                f"Excepted type int, np.bool_, np.integer or np.ndarray, "
+                f"Expected type int, np.bool_, np.integer or np.ndarray, "
                 f"but got {value}, type {type(value)}"
             )
 
@@ -167,8 +166,6 @@ def _call_with_ctx(f: Callable[..., DataType], *args, **kwargs) -> DataType:
     try:
         ctx = _FRONTEND_CONTEXT.get_ctx()
         bound = inspect.signature(f).bind(*args, **ctx, **kwargs)
-        # warnings.warn(_input_deprecate_msg, UserWarning)
         return f(*bound.args, **bound.kwargs)
-
     except TypeError:
         return f(*args, **kwargs)
diff --git a/paibox/simulator/encoder.py b/paibox/simulator/encoder.py
index 3f5d37d5..669bdd85 100644
--- a/paibox/simulator/encoder.py
+++ b/paibox/simulator/encoder.py
@@ -21,7 +21,7 @@ def __init__(
         seed: Optional[int] = None,
         name: Optional[str] = None,
     ) -> None:
-        self._shape_out = as_shape(shape_out)
+        self._shape = as_shape(shape_out)
 
         super().__init__(name)
         self.rng = self._get_rng(seed)
@@ -32,7 +32,7 @@ def _get_rng(self, seed: Optional[int] = None) -> np.random.RandomState:
 
     @property
     def num_out(self) -> int:
-        return shape2num(self._shape_out)
+        return shape2num(self._shape)
 
     @property
     def shape_in(self) -> Tuple[int, ...]:
@@ -40,7 +40,7 @@ def shape_in(self) -> Tuple[int, ...]:
 
     @property
     def shape_out(self) -> Tuple[int, ...]:
-        return self._shape_out
+        return self._shape
 
 
 class StatelessEncoder(Encoder):
diff --git a/paibox/tools.py b/paibox/tools.py
new file mode 100644
index 00000000..12fa09e6
--- /dev/null
+++ b/paibox/tools.py
@@ -0,0 +1,13 @@
+_PLIB_BASE_INTRO = """
+To install or update to the latest version, pip install paicorelib.
+
+To use the development version, pip install --pre paicorelib."""
+
+PLIB_INSTALL_INTRO = (
+    "\nPAIBox requires paicorelib, please install it.\n" + _PLIB_BASE_INTRO
+)
+
+PLIB_UPDATE_INTRO = (
+    "\nThe minimum required version of paicorelib is {0}, but the current version is {1}.\n"
+    + _PLIB_BASE_INTRO
+)
diff --git a/paibox/types.py b/paibox/types.py
index f5607ac0..c3fdd844 100644
--- a/paibox/types.py
+++ b/paibox/types.py
@@ -1,4 +1,3 @@
-import sys
 from typing import (
     AbstractSet,
     Any,
@@ -16,21 +15,17 @@
 import numpy as np
 from numpy.typing import NDArray
 
-if sys.version_info >= (3, 10):
-    from typing import TypeAlias
-else:
-    from typing_extensions import TypeAlias
-
 Shape = TypeVar("Shape", int, Tuple[int, ...], List[int])
 ArrayType = TypeVar("ArrayType", List[int], Tuple[int, ...], np.ndarray)
 Scalar = TypeVar("Scalar", int, float, np.generic)
-IntScalarType = TypeVar("IntScalarType", int, np.integer)
+IntScalarType = TypeVar("IntScalarType", int, np.bool_, np.integer)
 DataType = TypeVar("DataType", int, np.bool_, np.integer, np.ndarray)
 DataArrayType = TypeVar(
     "DataArrayType", int, np.bool_, np.integer, List[int], Tuple[int, ...], np.ndarray
 )
-SpikeType: TypeAlias = NDArray[np.bool_]
-WeightType: TypeAlias = NDArray[np.int8]  # raw int8 weights
+SpikeType = NDArray[np.bool_]
+SynOutType = NDArray[np.int32]
+WeightType = NDArray[np.int8]  # raw int8 weights
 
 _T = TypeVar("_T")
 
diff --git a/paibox/utils.py b/paibox/utils.py
index fdf5f327..8bb86b91 100644
--- a/paibox/utils.py
+++ b/paibox/utils.py
@@ -60,16 +60,13 @@ def shape2num(shape: Shape) -> int:
     """Convert a shape to a number"""
     if isinstance(shape, int):
         return shape
-
-    if isinstance(shape, (list, tuple)):
+    else:
         a = 1
         for b in shape:
             a *= b
 
         return a
 
-    raise TypeError(f"Unsupported type: {type(shape)}")
-
 
 def as_shape(shape, min_dim: int = 0) -> Tuple[int, ...]:
     """Convert a shape to a tuple, like (1,), (10,), or (10, 20)"""

From 913778799df9a3ededb610bd8a1daed2abdbbc01 Mon Sep 17 00:00:00 2001
From: KafCoppelia <k740677208@gmail.com>
Date: Fri, 15 Mar 2024 16:12:48 +0800
Subject: [PATCH 17/68] =?UTF-8?q?=F0=9F=90=9B=20bugfix:=20wrong=20shape=20?=
 =?UTF-8?q?of=20stateful=20variables=20in=20neurons=20when=20keep=5Fshape?=
 =?UTF-8?q?=20is=20enabled?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

---
 paibox/neuron/base.py | 56 +++++++++++++++++++++++++------------------
 1 file changed, 33 insertions(+), 23 deletions(-)

diff --git a/paibox/neuron/base.py b/paibox/neuron/base.py
index 741ea50e..f41315f3 100644
--- a/paibox/neuron/base.py
+++ b/paibox/neuron/base.py
@@ -23,9 +23,6 @@
 __all__ = ["Neuron"]
 
 VoltageType: TypeAlias = NDArray[np.int32]
-VJT_MAX_LIMIT: int = 2**29 - 1
-VJT_MIN_LIMIT: int = -(2**29)
-VJT_LIMIT: int = 2**30
 
 
 class MetaNeuron:
@@ -129,7 +126,7 @@ def _neuronal_leak(self, vjt: VoltageType) -> VoltageType:
         _rho_j_lambda = 2  # Random leak, unsigned 29-bit.
 
         if self.leak_direction is LDM.MODE_FORWARD:
-            _ld = np.ones(self.varshape, dtype=np.bool_)
+            _ld = np.ones((self._n_neuron,), dtype=np.bool_)
         else:
             _ld = np.sign(vjt)
 
@@ -213,7 +210,7 @@ def _neuronal_reset(self, vjt: VoltageType) -> VoltageType:
 
         def _when_exceed_pos() -> VoltageType:
             if self.reset_mode is RM.MODE_NORMAL:
-                return np.full(self.varshape, self.reset_v, dtype=np.int32)
+                return np.full((self._n_neuron,), self.reset_v, dtype=np.int32)
 
             elif self.reset_mode is RM.MODE_LINEAR:
                 return np.subtract(
@@ -225,7 +222,7 @@ def _when_exceed_pos() -> VoltageType:
         def _when_exceed_neg() -> VoltageType:
             if self.neg_thres_mode is NTM.MODE_RESET:
                 if self.reset_mode is RM.MODE_NORMAL:
-                    return np.full(self.varshape, -self.reset_v, dtype=np.int32)
+                    return np.full((self._n_neuron,), -self.reset_v, dtype=np.int32)
                 elif self.reset_mode is RM.MODE_LINEAR:
                     return np.add(
                         vjt,
@@ -236,7 +233,7 @@ def _when_exceed_neg() -> VoltageType:
                     return vjt
 
             else:
-                return np.full(self.varshape, -self.neg_threshold, dtype=np.int32)
+                return np.full((self._n_neuron,), -self.neg_threshold, dtype=np.int32)
 
         # USE "=="!
         v_reset = np.where(
@@ -281,11 +278,11 @@ def _relu(self, vj: VoltageType) -> VoltageType:
 
         def _when_exceed_pos() -> VoltageType:
             if self._spike_width_format is SpikeWidthFormat.WIDTH_1BIT:
-                return np.ones(self.varshape, dtype=np.int32)
+                return np.ones((self._n_neuron,), dtype=np.int32)
 
             if self.bit_truncation >= 8:
                 return np.full(
-                    self.varshape,
+                    (self._n_neuron,),
                     ((vj >> self.bit_truncation) - 8) & ((1 << 8) - 1),
                     dtype=np.int32,
                 )
@@ -293,17 +290,17 @@ def _when_exceed_pos() -> VoltageType:
                 _mask = (1 << self.bit_truncation) - 1
                 _truncated_vj = vj & _mask
                 return np.full(
-                    self.varshape,
+                    (self._n_neuron,),
                     _truncated_vj << (8 - self.bit_truncation),
                     dtype=np.int32,
                 )
             else:
-                return np.zeros(self.varshape, dtype=np.int32)
+                return np.zeros((self._n_neuron,), dtype=np.int32)
 
         y = np.where(
             vj >= self.pos_threshold,
             _when_exceed_pos(),
-            np.zeros(self.varshape, dtype=np.int32),
+            np.zeros((self._n_neuron,), dtype=np.int32),
         ).astype(np.int32)
 
         return y
@@ -498,17 +495,7 @@ def update(
         if x is None:
             x = self.sum_inputs()
 
-        # If the incoming membrane potential (30-bit signed) overflows, the chip will automatically handle it.
-        # This behavior needs to be implemented during simulation.
-        incoming_v = np.where(
-            x > VJT_MAX_LIMIT,
-            x - VJT_LIMIT,
-            np.where(
-                x < VJT_MIN_LIMIT,
-                x + VJT_LIMIT,
-                x,
-            ),
-        ).astype(np.int32)
+        incoming_v = _vjt_overflow(x)
 
         self._inner_spike, self._vjt, self._debug_thres_mode = super().update(
             incoming_v, self._vjt
@@ -590,3 +577,26 @@ def feature_map(self) -> SpikeType:
     @property
     def voltage(self) -> VoltageType:
         return self._vjt.reshape(self.varshape)
+
+
+VJT_MAX_LIMIT: int = 2**29 - 1
+VJT_MIN_LIMIT: int = -(2**29)
+VJT_LIMIT: int = 2**30
+
+
+def _vjt_overflow(x: np.ndarray) -> VoltageType:
+    """Handle the overflow of the membrane potential.
+
+    NOTE: If the incoming membrane potential (30-bit signed) overflows, the chip\
+        will automatically handle it. This behavior needs to be implemented in  \
+        simulation.
+    """
+    return np.where(
+        x > VJT_MAX_LIMIT,
+        x - VJT_LIMIT,
+        np.where(
+            x < VJT_MIN_LIMIT,
+            x + VJT_LIMIT,
+            x,
+        ),
+    ).astype(np.int32)

From 160ea3a0fa9a85cecc05fd76989643b3c0b5719a Mon Sep 17 00:00:00 2001
From: KafCoppelia <k740677208@gmail.com>
Date: Fri, 15 Mar 2024 16:22:36 +0800
Subject: [PATCH 18/68] =?UTF-8?q?=E2=9C=85=20added=20tests=20for=202d=20co?=
 =?UTF-8?q?nv?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

---
 tests/simulator/test_simulator.py |  33 +++
 tests/synapses/test_synapses.py   | 160 +++++-----
 tests/synapses/test_transforms.py | 473 ++++++++++++++++++------------
 3 files changed, 415 insertions(+), 251 deletions(-)

diff --git a/tests/simulator/test_simulator.py b/tests/simulator/test_simulator.py
index 935184ef..9edd50c1 100644
--- a/tests/simulator/test_simulator.py
+++ b/tests/simulator/test_simulator.py
@@ -98,6 +98,30 @@ def __init__(self, n: int):
         self.n1_output = pb.Probe(self.n1, "spike")
 
 
+class Conv2d_Net(pb.Network):
+    def __init__(self):
+        super().__init__()
+
+        pe1 = pb.simulator.PoissonEncoder()
+
+        self.inp1 = pb.InputProj(pe1, shape_out=(8, 24, 24))
+        self.n1 = pb.IF((16, 22, 22), threshold=10, reset_v=0, keep_shape=True)
+
+        kernel = np.random.randint(-128, 128, size=(8, 16, 3, 3), dtype=np.int8)
+        stride = 1
+
+        self.conv1 = pb.Conv2d(
+            self.inp1,
+            self.n1,
+            kernel,
+            stride=stride,
+            kernel_order="IOHW",
+        )
+
+        self.prob1 = pb.Probe(self.n1, "spike")
+        self.prob2 = pb.Probe(self.n1, "feature_map")
+
+
 class TestSimulator:
     def test_probe(self):
         net = Net1(100)
@@ -202,3 +226,12 @@ def test_sim_nested_net(self, build_Nested_Net_L3):
         sim.run(20)
 
         sim.reset()
+
+    def test_sim_conv2d_net(self):
+        net = Conv2d_Net()
+        sim = pb.Simulator(net, start_time_zero=False)
+
+        net.inp1.input = np.random.rand(8, 24, 24)
+        sim.run(10)
+
+        sim.reset()
diff --git a/tests/synapses/test_synapses.py b/tests/synapses/test_synapses.py
index eb3fc159..c851dd3c 100644
--- a/tests/synapses/test_synapses.py
+++ b/tests/synapses/test_synapses.py
@@ -4,12 +4,13 @@
 
 import paibox as pb
 from paibox.exceptions import ShapeError
+from paibox.utils import shape2num
 
 
 def test_SynSys_Attrs():
-    n1 = pb.neuron.TonicSpiking(3, 3)
-    n2 = pb.neuron.TonicSpiking(3, 3)
-    s1 = pb.synapses.NoDecay(
+    n1 = pb.TonicSpiking(3, 3)
+    n2 = pb.TonicSpiking(3, 3)
+    s1 = pb.FullConn(
         n1,
         n2,
         weights=np.array([[1, 1, 0], [0, 1, 1], [0, 1, 1]], dtype=np.int8),
@@ -23,53 +24,51 @@ def test_SynSys_Attrs():
     assert s1.weights.dtype == np.int8
 
 
-class TestNoDecay:
+class TestFullConn:
     @pytest.mark.parametrize(
         "n1, n2, scalar_weight, expected_wp",
         [
             (
-                pb.neuron.TonicSpiking(10, 3),
-                pb.neuron.TonicSpiking(10, 3),
+                pb.TonicSpiking(10, 3),
+                pb.TonicSpiking(10, 3),
                 1,
                 WP.WEIGHT_WIDTH_1BIT,
             ),
             (
-                pb.neuron.TonicSpiking((3, 3), 3),
-                pb.neuron.TonicSpiking((3, 3), 3),
+                pb.TonicSpiking((3, 3), 3),
+                pb.TonicSpiking((3, 3), 3),
                 4,
                 WP.WEIGHT_WIDTH_4BIT,
             ),
             (
-                pb.neuron.TonicSpiking((5,), 3),
-                pb.neuron.TonicSpiking((5,), 3),
+                pb.TonicSpiking((5,), 3),
+                pb.TonicSpiking((5,), 3),
                 -1,
                 WP.WEIGHT_WIDTH_2BIT,
             ),
             # TODO 3-dimension shape is correct for data flow?
             (
-                pb.neuron.TonicSpiking((10, 2, 3), 3),
-                pb.neuron.TonicSpiking((10, 2, 3), 3),
+                pb.TonicSpiking((10, 2, 3), 3),
+                pb.TonicSpiking((10, 2, 3), 3),
                 16,
                 WP.WEIGHT_WIDTH_8BIT,
             ),
             (
-                pb.neuron.TonicSpiking((10, 2), 3),
-                pb.neuron.TonicSpiking((4, 5), 3),
+                pb.TonicSpiking((10, 2), 3),
+                pb.TonicSpiking((4, 5), 3),
                 -100,
                 WP.WEIGHT_WIDTH_8BIT,
             ),
             (
-                pb.neuron.TonicSpiking(10, 3),
-                pb.neuron.TonicSpiking((2, 5), 3),
+                pb.TonicSpiking(10, 3),
+                pb.TonicSpiking((2, 5), 3),
                 7,
                 WP.WEIGHT_WIDTH_4BIT,
             ),
         ],
     )
-    def test_NoDecay_One2One_scalar(self, n1, n2, scalar_weight, expected_wp):
-        s1 = pb.synapses.NoDecay(
-            n1, n2, scalar_weight, conn_type=pb.SynConnType.One2One
-        )
+    def test_FullConn_One2One_scalar(self, n1, n2, scalar_weight, expected_wp):
+        s1 = pb.FullConn(n1, n2, scalar_weight, conn_type=pb.SynConnType.One2One)
 
         assert np.array_equal(s1.weights, scalar_weight)
         assert (s1.num_in, s1.num_out) == (n1.num_out, n2.num_in)
@@ -83,32 +82,32 @@ def test_NoDecay_One2One_scalar(self, n1, n2, scalar_weight, expected_wp):
         "n1, n2",
         [
             (
-                pb.neuron.TonicSpiking(10, 3),
-                pb.neuron.TonicSpiking(100, 4),
+                pb.TonicSpiking(10, 3),
+                pb.TonicSpiking(100, 4),
             ),
             (
-                pb.neuron.TonicSpiking((10, 10), 3),
-                pb.neuron.TonicSpiking((5, 10), 4),
+                pb.TonicSpiking((10, 10), 3),
+                pb.TonicSpiking((5, 10), 4),
             ),
             (
-                pb.neuron.IF((10,), 3),
-                pb.neuron.TonicSpiking((5,), 4),
+                pb.IF((10,), 3),
+                pb.TonicSpiking((5,), 4),
             ),
             (
-                pb.neuron.TonicSpiking(10, 3),
-                pb.neuron.TonicSpiking((5, 10), 4),
+                pb.TonicSpiking(10, 3),
+                pb.TonicSpiking((5, 10), 4),
             ),
         ],
     )
-    def test_NoDecay_One2One_scalar_illegal(self, n1, n2):
+    def test_FullConn_One2One_scalar_illegal(self, n1, n2):
         with pytest.raises(ShapeError):
-            s1 = pb.synapses.NoDecay(n1, n2, conn_type=pb.SynConnType.One2One)
+            s1 = pb.FullConn(n1, n2, conn_type=pb.SynConnType.One2One)
 
-    def test_NoDecay_One2One_matrix(self):
+    def test_FullConn_One2One_matrix(self):
         weight = np.array([2, 3, 4], np.int8)
-        s1 = pb.synapses.NoDecay(
-            pb.neuron.TonicSpiking((3,), 3),
-            pb.neuron.TonicSpiking((3,), 3),
+        s1 = pb.FullConn(
+            pb.TonicSpiking((3,), 3),
+            pb.TonicSpiking((3,), 3),
             weight,
             conn_type=pb.SynConnType.One2One,
         )
@@ -121,9 +120,9 @@ def test_NoDecay_One2One_matrix(self):
         assert s1.weight_precision is WP.WEIGHT_WIDTH_4BIT
 
         weight = np.array([1, 0, 1, 0], np.int8)
-        s2 = pb.synapses.NoDecay(
-            pb.neuron.TonicSpiking((2, 2), 3),
-            pb.neuron.TonicSpiking((2, 2), 3),
+        s2 = pb.FullConn(
+            pb.TonicSpiking((2, 2), 3),
+            pb.TonicSpiking((2, 2), 3),
             weight,
             conn_type=pb.SynConnType.One2One,
         )
@@ -141,58 +140,58 @@ def test_NoDecay_One2One_matrix(self):
     @pytest.mark.parametrize(
         "n1, n2",
         [
-            (pb.neuron.TonicSpiking(10, 3), pb.neuron.TonicSpiking(10, 3)),
+            (pb.TonicSpiking(10, 3), pb.TonicSpiking(10, 3)),
             (
-                pb.neuron.TonicSpiking((3, 3), 3),
-                pb.neuron.TonicSpiking((3, 3), 3),
+                pb.TonicSpiking((3, 3), 3),
+                pb.TonicSpiking((3, 3), 3),
             ),
             (
-                pb.neuron.TonicSpiking((5,), 3),
-                pb.neuron.TonicSpiking((5,), 3),
+                pb.TonicSpiking((5,), 3),
+                pb.TonicSpiking((5,), 3),
             ),
             (
-                pb.neuron.TonicSpiking(10, 3),
-                pb.neuron.TonicSpiking(100, 3),
+                pb.TonicSpiking(10, 3),
+                pb.TonicSpiking(100, 3),
             ),
             (
-                pb.neuron.TonicSpiking((10, 10), 3),
-                pb.neuron.TonicSpiking((5, 5), 3),
+                pb.TonicSpiking((10, 10), 3),
+                pb.TonicSpiking((5, 5), 3),
             ),
         ],
     )
-    def test_NoDecay_All2All(self, n1, n2):
-        s1 = pb.synapses.NoDecay(n1, n2, conn_type=pb.SynConnType.All2All)
+    def test_FullConn_All2All(self, n1, n2):
+        s1 = pb.FullConn(n1, n2, conn_type=pb.SynConnType.All2All)
 
         assert (s1.num_in, s1.num_out) == (n1.num_out, n2.num_in)
         assert np.array_equal(s1.weights, 1)
         assert np.array_equal(s1.connectivity, np.ones((n1.num_out, n2.num_in)))
 
-    def test_NoDecay_All2All_with_weights(self):
-        n1 = pb.neuron.TonicSpiking(3, 3)
-        n2 = pb.neuron.TonicSpiking(3, 3)
+    def test_FullConn_All2All_with_weights(self):
+        n1 = pb.TonicSpiking(3, 3)
+        n2 = pb.TonicSpiking(3, 3)
 
         """1. Single weight."""
         weight = 2
-        s1 = pb.synapses.NoDecay(n1, n2, weight, conn_type=pb.SynConnType.All2All)
+        s1 = pb.FullConn(n1, n2, weight, conn_type=pb.SynConnType.All2All)
 
         assert np.array_equal(s1.weights, weight)
         assert s1.weight_precision is WP.WEIGHT_WIDTH_4BIT
 
         """2. Weights matrix."""
         weight = np.array([[1, 2, 3], [4, 5, 6], [7, 8, 9]])
-        s2 = pb.synapses.NoDecay(n1, n2, weight, conn_type=pb.SynConnType.All2All)
+        s2 = pb.FullConn(n1, n2, weight, conn_type=pb.SynConnType.All2All)
 
         assert np.array_equal(s2.weights, weight)
         assert np.array_equal(s2.connectivity, weight)
 
         # Wrong shape
         with pytest.raises(ShapeError):
-            s3 = pb.synapses.NoDecay(
+            s3 = pb.FullConn(
                 n1, n2, np.array([1, 2, 3]), conn_type=pb.SynConnType.All2All
             )
 
         with pytest.raises(ShapeError):
-            s3 = pb.synapses.NoDecay(
+            s3 = pb.FullConn(
                 n1,
                 n2,
                 np.array([[1, 2, 3], [4, 5, 6]]),
@@ -200,7 +199,7 @@ def test_NoDecay_All2All_with_weights(self):
             )
 
         with pytest.raises(ShapeError):
-            s3 = pb.synapses.NoDecay(
+            s3 = pb.FullConn(
                 n1,
                 n2,
                 np.array([[1, 2], [4, 5], [6, 7]]),
@@ -208,7 +207,7 @@ def test_NoDecay_All2All_with_weights(self):
             )
 
         with pytest.raises(ShapeError):
-            s3 = pb.synapses.NoDecay(
+            s3 = pb.FullConn(
                 n1,
                 n2,
                 np.array([[1, 2, 3], [4, 5, 6], [6, 7, 8], [1, 2, 3]]),
@@ -218,23 +217,23 @@ def test_NoDecay_All2All_with_weights(self):
     @pytest.mark.parametrize(
         "n1, n2",
         [
-            (pb.neuron.TonicSpiking(10, 3), pb.neuron.TonicSpiking(10, 3)),
+            (pb.TonicSpiking(10, 3), pb.TonicSpiking(10, 3)),
             (
-                pb.neuron.TonicSpiking((3, 3), 3),
-                pb.neuron.TonicSpiking((3, 3), 3),
+                pb.TonicSpiking((3, 3), 3),
+                pb.TonicSpiking((3, 3), 3),
             ),
             (
-                pb.neuron.TonicSpiking((5,), 3),
-                pb.neuron.TonicSpiking((5,), 3),
+                pb.TonicSpiking((5,), 3),
+                pb.TonicSpiking((5,), 3),
             ),
         ],
     )
-    def test_NoDecay_MatConn(self, n1, n2):
+    def test_FullConn_MatConn(self, n1, n2):
         weight = np.random.randint(
             -128, 128, size=(n1.num_out, n2.num_in), dtype=np.int8
         )
 
-        s = pb.synapses.NoDecay(n1, n2, weight, conn_type=pb.SynConnType.MatConn)
+        s = pb.FullConn(n1, n2, weight, conn_type=pb.SynConnType.MatConn)
 
         assert np.array_equal(s.weights, weight)
         assert (s.num_in, s.num_out) == (n1.num_out, n2.num_in)
@@ -242,19 +241,46 @@ def test_NoDecay_MatConn(self, n1, n2):
 
         # Wrong weight type
         with pytest.raises(TypeError):
-            s = pb.synapses.NoDecay(n1, n2, 1, conn_type=pb.SynConnType.MatConn)
+            s = pb.FullConn(n1, n2, 1, conn_type=pb.SynConnType.MatConn)
 
         # Wrong shape
         with pytest.raises(ShapeError):
-            s = pb.synapses.NoDecay(
+            s = pb.FullConn(
                 n1, n2, np.array([1, 2, 3]), conn_type=pb.SynConnType.MatConn
             )
 
         # Wrong shape
         with pytest.raises(ShapeError):
-            s = pb.synapses.NoDecay(
+            s = pb.FullConn(
                 n1,
                 n2,
                 np.array([[1, 2, 3], [4, 5, 6]]),
                 conn_type=pb.SynConnType.MatConn,
             )
+
+
+class TestConv2d:
+    def test_Conv2d_instance(self):
+        in_shape = (32, 32)
+        kernel_size = (5, 5)
+        stride = 2
+        out_shape = ((32 - 5) // 2 + 1, (32 - 5) // 2 + 1)
+        in_channels = 8
+        out_channels = 16
+        korder = "IOHW"
+
+        n1 = pb.IF((in_channels,) + in_shape, 3)  # CHW
+        n2 = pb.IF((out_channels,) + out_shape, 3)
+
+        weight = np.random.randint(
+            -128, 128, size=(in_channels, out_channels) + kernel_size, dtype=np.int8
+        )
+        s1 = pb.Conv2d(
+            n1, n2, weight, stride=stride, fm_order="CHW", kernel_order=korder
+        )
+
+        assert s1.num_in == in_channels * shape2num(in_shape)
+        assert s1.connectivity.shape == (
+            in_channels * shape2num(in_shape),
+            out_channels * shape2num(out_shape),
+        )
diff --git a/tests/synapses/test_transforms.py b/tests/synapses/test_transforms.py
index 59ead01a..a2451328 100644
--- a/tests/synapses/test_transforms.py
+++ b/tests/synapses/test_transforms.py
@@ -1,187 +1,292 @@
 import numpy as np
 import pytest
 
-from paibox.synapses.transforms import AllToAll, MaskedLinear, OneToOne
-
-
-@pytest.mark.parametrize(
-    "weight",
-    [
-        (np.array([1, 2, 3], dtype=np.int8)),
-        (np.array([1, 0, 1], dtype=np.bool_)),
-        (np.array([1, 0, 1], dtype=np.int8)),
-        (10),
-        (np.int8(-1)),
-        (np.array([127, 0, 1], dtype=np.int8)),
-        (np.array([-128, 1, 127], dtype=np.int8)),
-    ],
-    ids=[
-        "array_1",
-        "array_2",
-        "array_3",
-        "scalar_pos",
-        "scalar_neg",
-        "array_int8_1",
-        "array_int8_2",
-    ],
-)
-def test_OneToOne_dtype(weight):
-    num = 3
-    f = OneToOne(num, weight)
-    x = np.array([1, 0, 1], dtype=np.bool_)
-    y = f(x)
-    expected = x * weight
-
-    assert y.dtype == np.int32
-    assert y.shape == (num,)
-    assert np.array_equal(y, expected)
-    assert f.connectivity.shape == (num, num)
-
-
-def test_OneToOne():
-    weight = np.array([1, 2, 3, 4], dtype=np.int8)
-    f = OneToOne(4, weight)
-    assert f.connectivity.shape == (4, 4)
-
-    # The last spike is an array.
-    x1 = np.array([1, 2, 3, 4], dtype=np.int8)
-    y = f(x1)
-    assert y.shape == (4,)
-
-    # The last spike is a scalar.
-    x2 = np.array(2, dtype=np.int8)
-    y = f(x2)
-    assert y.shape == (4,)
-
-
-@pytest.mark.parametrize(
-    "weight, expected_dtype",
-    [
-        (1, np.bool_),
-        (-1, np.int8),
-        (10, np.int8),
-        (-100, np.int8),
-        (-128, np.int8),
-        (127, np.int8),
-    ],
-    ids=[
-        "scalar_1",
-        "scalar_-1",
-        "scalar_10",
-        "scalar_-100",
-        "scalar_-128",
-        "scalar_-127",
-    ],
-)
-def test_AllToAll_weight_scalar(weight, expected_dtype):
-    """Test `AllToAll` when weight is a scalar"""
-
-    num_in, num_out = 10, 20
-    x = np.random.randint(2, size=(10,))
-    f = AllToAll((num_in, num_out), weight)
-    y = f(x)
-    expected = np.full((num_out,), np.sum(x, axis=None), dtype=np.int32) * weight
-
-    assert f.conn_dtype == expected_dtype
-    assert y.dtype == np.int32
-    assert y.shape == (num_out,)
-    assert y.ndim == 1
-    assert np.array_equal(y, expected)
-    assert f.connectivity.shape == (num_in, num_out)
-
-
-@pytest.mark.parametrize(
-    "shape, x, weights, expected_dtype",
-    [
-        (
-            (3, 4),
-            np.random.randint(2, size=(3,), dtype=np.bool_),
-            np.random.randint(2, size=(3, 4), dtype=np.bool_),
-            np.bool_,
-        ),
-        (
-            (10, 20),
-            np.random.randint(2, size=(10,), dtype=np.bool_),
-            np.random.randint(127, size=(10, 20), dtype=np.int8),
-            np.int8,
-        ),
-        (
-            (20, 10),
-            np.random.randint(2, size=(20,), dtype=np.bool_),
-            np.random.randint(2, size=(20, 10), dtype=np.int8),
-            np.bool_,
-        ),
-        (
-            (2, 2),
-            np.array([1, 1], dtype=np.bool_),
-            np.array([[1, 2], [3, 4]], dtype=np.int8),
-            np.int8,
-        ),
-        (
-            (2, 2),
-            np.array([1, 1], dtype=np.bool_),
-            np.array([[127, 0], [3, -128]], dtype=np.int8),
-            np.int8,
-        ),
-    ],
-    ids=[
-        "weights_bool_1",
-        "weights_int8_1",
-        "weights_int8_2",
-        "weights_int8_3",
-        "weights_int8_4",
-    ],
-)
-def test_AllToAll_array(shape, x, weights, expected_dtype):
-    """Test `AllToAll` when weights is an array"""
-
-    f = AllToAll(shape, weights)
-    y = f(x)
-    expected = x @ weights.copy().astype(np.int32)
-
-    assert f.conn_dtype == expected_dtype
-    assert np.array_equal(y, expected)
-    assert f.connectivity.shape == shape
-
-
-@pytest.mark.parametrize(
-    "shape, x, weights, expected_dtype",
-    [
-        (
-            (3, 4),
-            np.array([1, 1, 1], dtype=np.bool_),
-            np.array([[1, 2, 3, 4], [5, 6, 7, 8], [9, 10, 11, 12]], dtype=np.int8),
-            np.int8,
-        ),
-        (
-            (10, 20),
-            np.random.randint(2, size=(10,), dtype=np.bool_),
-            np.random.randint(-10, 10, size=(10, 20), dtype=np.int8),
-            np.int8,
-        ),
-        (
-            (20, 10),
-            np.ones((20,), dtype=np.bool_),
-            np.random.randint(2, size=(20, 10), dtype=np.int8),
-            np.bool_,
-        ),
-        (
-            (2, 2),
-            np.array([1, 1], dtype=np.bool_),
-            np.array([[127, 0], [3, -128]], dtype=np.int8),
-            np.int8,
-        ),
-    ],
-    ids=["weights_int8_1", "weights_int8_2", "weights_bool", "weights_int8_3"],
-)
-def test_MaskedLinear_conn(shape, x, weights, expected_dtype):
-    f = MaskedLinear(shape, weights)
-    y = f(x)
-    expected = x @ weights.copy().astype(np.int32)
-
-    assert f.conn_dtype == expected_dtype
-    assert f.connectivity.dtype == expected_dtype
-    assert y.shape == (shape[1],)
-    assert y.dtype == np.int32
-    assert np.array_equal(y, expected)
-    assert f.connectivity.shape == shape
+from typing import Tuple
+
+from paibox.synapses.transforms import *
+from paibox.utils import shape2num
+
+
+class TestTransforms:
+    @pytest.mark.parametrize(
+        "weight",
+        [
+            (np.array([1, 2, 3], dtype=np.int8)),
+            (np.array([1, 0, 1], dtype=np.bool_)),
+            (np.array([1, 0, 1], dtype=np.int8)),
+            (10),
+            (np.int8(-1)),
+            (np.array([127, 0, 1], dtype=np.int8)),
+            (np.array([-128, 1, 127], dtype=np.int8)),
+        ],
+        ids=[
+            "array_1",
+            "array_2",
+            "array_3",
+            "scalar_pos",
+            "scalar_neg",
+            "array_int8_1",
+            "array_int8_2",
+        ],
+    )
+    def test_OneToOne_dtype(self, weight):
+        num = 3
+        f = OneToOne(num, weight)
+        x = np.array([1, 0, 1], dtype=np.bool_)
+        y = f(x)
+        expected = x * weight
+
+        assert y.dtype == np.int32
+        assert y.shape == (num,)
+        assert np.array_equal(y, expected)
+        assert f.connectivity.shape == (num, num)
+
+    def test_OneToOne(self):
+        weight = np.array([1, 2, 3, 4], dtype=np.int8)
+        f = OneToOne(4, weight)
+        assert f.connectivity.shape == (4, 4)
+
+        # The last spike is an array.
+        x1 = np.array([1, 2, 3, 4], dtype=np.int8)
+        y = f(x1)
+        assert y.shape == (4,)
+
+        # The last spike is a scalar.
+        x2 = np.array(2, dtype=np.int8)
+        y = f(x2)
+        assert y.shape == (4,)
+
+    @pytest.mark.parametrize(
+        "weight, expected_dtype",
+        [
+            (1, np.bool_),
+            (-1, np.int8),
+            (10, np.int8),
+            (-100, np.int8),
+            (-128, np.int8),
+            (127, np.int8),
+        ],
+        ids=[
+            "scalar_1",
+            "scalar_-1",
+            "scalar_10",
+            "scalar_-100",
+            "scalar_-128",
+            "scalar_-127",
+        ],
+    )
+    def test_AllToAll_weight_scalar(self, weight, expected_dtype):
+        """Test `AllToAll` when weight is a scalar"""
+
+        num_in, num_out = 10, 20
+        x = np.random.randint(2, size=(10,))
+        f = AllToAll((num_in, num_out), weight)
+        y = f(x)
+        expected = np.full((num_out,), np.sum(x, axis=None), dtype=np.int32) * weight
+
+        assert f.conn_dtype == expected_dtype
+        assert y.dtype == np.int32
+        assert y.shape == (num_out,)
+        assert y.ndim == 1
+        assert np.array_equal(y, expected)
+        assert f.connectivity.shape == (num_in, num_out)
+
+    @pytest.mark.parametrize(
+        "shape, x, weights, expected_dtype",
+        [
+            (
+                (3, 4),
+                np.random.randint(2, size=(3,), dtype=np.bool_),
+                np.random.randint(2, size=(3, 4), dtype=np.bool_),
+                np.bool_,
+            ),
+            (
+                (10, 20),
+                np.random.randint(2, size=(10,), dtype=np.bool_),
+                np.random.randint(127, size=(10, 20), dtype=np.int8),
+                np.int8,
+            ),
+            (
+                (20, 10),
+                np.random.randint(2, size=(20,), dtype=np.bool_),
+                np.random.randint(2, size=(20, 10), dtype=np.int8),
+                np.bool_,
+            ),
+            (
+                (2, 2),
+                np.array([1, 1], dtype=np.bool_),
+                np.array([[1, 2], [3, 4]], dtype=np.int8),
+                np.int8,
+            ),
+            (
+                (2, 2),
+                np.array([1, 1], dtype=np.bool_),
+                np.array([[127, 0], [3, -128]], dtype=np.int8),
+                np.int8,
+            ),
+        ],
+        ids=[
+            "weights_bool_1",
+            "weights_int8_1",
+            "weights_int8_2",
+            "weights_int8_3",
+            "weights_int8_4",
+        ],
+    )
+    def test_AllToAll_array(self, shape, x, weights, expected_dtype):
+        """Test `AllToAll` when weights is an array"""
+
+        f = AllToAll(shape, weights)
+        y = f(x)
+        expected = x @ weights.copy().astype(np.int32)
+
+        assert f.conn_dtype == expected_dtype
+        assert np.array_equal(y, expected)
+        assert f.connectivity.shape == shape
+
+    @pytest.mark.parametrize(
+        "shape, x, weights, expected_dtype",
+        [
+            (
+                (3, 4),
+                np.array([1, 1, 1], dtype=np.bool_),
+                np.array([[1, 2, 3, 4], [5, 6, 7, 8], [9, 10, 11, 12]], dtype=np.int8),
+                np.int8,
+            ),
+            (
+                (10, 20),
+                np.random.randint(2, size=(10,), dtype=np.bool_),
+                np.random.randint(-10, 10, size=(10, 20), dtype=np.int8),
+                np.int8,
+            ),
+            (
+                (20, 10),
+                np.ones((20,), dtype=np.bool_),
+                np.random.randint(2, size=(20, 10), dtype=np.int8),
+                np.bool_,
+            ),
+            (
+                (2, 2),
+                np.array([1, 1], dtype=np.bool_),
+                np.array([[127, 0], [3, -128]], dtype=np.int8),
+                np.int8,
+            ),
+        ],
+        ids=["weights_int8_1", "weights_int8_2", "weights_bool", "weights_int8_3"],
+    )
+    def test_MaskedLinear_conn(self, shape, x, weights, expected_dtype):
+        f = MaskedLinear(shape, weights)
+        y = f(x)
+        expected = x @ weights.copy().astype(np.int32)
+
+        assert f.conn_dtype == expected_dtype
+        assert f.connectivity.dtype == expected_dtype
+        assert y.shape == (shape[1],)
+        assert y.dtype == np.int32
+        assert np.array_equal(y, expected)
+        assert f.connectivity.shape == shape
+
+    @staticmethod
+    def _conv2d_golden(
+        x: np.ndarray,
+        out_shape: Tuple[int, int],
+        kernel: np.ndarray,
+        stride: Tuple[int, int],
+        padding: Tuple[int, int],
+        fm_order: str,
+    ):
+        cout, cin, kh, kw = kernel.shape
+
+        if fm_order == "HWC":
+            _x = x.transpose(2, 0, 1)
+        else:
+            _x = x.copy()
+
+        xcin, ih, iw = _x.shape
+
+        assert cin == xcin
+
+        oh = (ih - kh + 2 * padding[0]) // stride[0] + 1
+        ow = (iw - kw + 2 * padding[1]) // stride[1] + 1
+
+        assert oh, ow == out_shape
+
+        out = np.zeros((cout,) + out_shape, dtype=np.int64)
+
+        x_padded = np.pad(
+            _x,
+            ((0, 0), (padding[0], padding[0]), (padding[1], padding[1])),
+            mode="constant",
+        )
+
+        for o in range(cout):
+            for i in range(cin):
+                conv_result = np.zeros((oh, ow), dtype=np.int64)
+                for h in range(oh):
+                    for w in range(ow):
+                        window = x_padded[
+                            i,
+                            h * stride[0] : h * stride[0] + kh,
+                            w * stride[1] : w * stride[1] + kw,
+                        ]
+                        conv_result[h, w] = np.sum(window * kernel[o, i, :, :])
+
+                out[o] += conv_result
+
+        return out
+
+    @pytest.mark.parametrize(
+        "in_shape, in_channels, out_channels, kernel_size, stride, padding, fm_order",
+        # Padding is fixed at (0, 0)
+        [
+            ((28, 28), 16, 8, (3, 3), (1, 1), (0, 0), "CHW"),
+            ((28, 28), 24, 12, (3, 3), (2, 2), (0, 0), "CHW"),
+            ((28, 28), 24, 12, (5, 5), (2, 1), (0, 0), "CHW"),
+            ((16, 16), 8, 16, (3, 3), (2, 2), (0, 0), "CHW"),
+            ((28, 28), 16, 8, (3, 3), (1, 1), (0, 0), "HWC"),
+            ((24, 32), 8, 8, (3, 4), (2, 1), (0, 0), "HWC"),
+            ((24, 24), 8, 16, (7, 7), (2, 2), (0, 0), "HWC"),
+            ((32, 16), 4, 12, (5, 7), (1, 2), (0, 0), "HWC"),
+        ],
+    )
+    def test_Conv2dForward(
+        self,
+        in_shape,
+        in_channels,
+        out_channels,
+        kernel_size,
+        stride,
+        padding,
+        fm_order,
+    ):
+        kernel = np.random.randint(
+            -128, 127, size=(out_channels, in_channels) + kernel_size, dtype=np.int8
+        )
+
+        out_shape = (
+            (in_shape[0] + 2 * padding[0] - kernel_size[0]) // stride[0] + 1,
+            (in_shape[1] + 2 * padding[1] - kernel_size[1]) // stride[1] + 1,
+        )
+
+        f = Conv2dForward(in_shape, out_shape, kernel, stride, padding, fm_order)
+
+        if fm_order == "CHW":
+            fm_shape = (in_channels,) + in_shape
+        else:
+            fm_shape = in_shape + (in_channels,)
+
+        x = np.random.randint(0, 2, size=fm_shape, dtype=np.bool_)
+        xf = x.copy().flatten()
+
+        y = f(xf)
+        expected = self._conv2d_golden(x, out_shape, kernel, stride, padding, fm_order)
+
+        # Flattened output
+        y = y.reshape((out_channels,) + out_shape)
+
+        assert y.shape == expected.shape
+        assert np.array_equal(y, expected)
+        assert f.connectivity.shape == (
+            shape2num((kernel.shape[1],) + in_shape),
+            shape2num((kernel.shape[0],) + out_shape),
+        )

From f7a2cf330c24afbc83b23509586a1e99a61595be Mon Sep 17 00:00:00 2001
From: KafCoppelia <k740677208@gmail.com>
Date: Fri, 15 Mar 2024 16:27:00 +0800
Subject: [PATCH 19/68] =?UTF-8?q?=E2=9C=85=20sync=20changes?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

---
 tests/backend/conftest.py           | 98 ++++++++++++++---------------
 tests/backend/test_mapper.py        |  5 +-
 tests/backend/test_placement.py     |  4 +-
 tests/backend/test_segment_utils.py | 12 ++--
 tests/conftest.py                   | 36 +++++------
 tests/neuron/conftest.py            | 58 ++++++++---------
 tests/neuron/test_neurons.py        | 24 +++----
 tests/simulator/test_simulator.py   | 12 ++--
 tests/test_network.py               | 32 +++++-----
 9 files changed, 137 insertions(+), 144 deletions(-)

diff --git a/tests/backend/conftest.py b/tests/backend/conftest.py
index a529079e..e1b64fe2 100644
--- a/tests/backend/conftest.py
+++ b/tests/backend/conftest.py
@@ -99,13 +99,13 @@ def __init__(self):
         self.n1 = pb.TonicSpiking(2000, 3, name="n1_1", tick_wait_start=1)
         self.n2 = pb.TonicSpiking(1200, 3, name="n2_1", tick_wait_start=2)
         self.n3 = pb.TonicSpiking(800, 4, name="n3_1", tick_wait_start=3)
-        self.s1 = pb.NoDecay(
+        self.s1 = pb.FullConn(
             self.inp1, self.n1, conn_type=pb.SynConnType.All2All, name="s1_1"
         )
-        self.s2 = pb.NoDecay(
+        self.s2 = pb.FullConn(
             self.n1, self.n2, conn_type=pb.SynConnType.All2All, name="s2_1"
         )
-        self.s3 = pb.NoDecay(
+        self.s3 = pb.FullConn(
             self.n2, self.n3, conn_type=pb.SynConnType.All2All, name="s3_1"
         )
 
@@ -122,13 +122,13 @@ def __init__(self):
         self.inp2 = pb.InputProj(input=1, shape_out=(50,), name="inp2_2")
         self.n1 = pb.TonicSpiking(30, 3, name="n1_2", tick_wait_start=1)
         self.n2 = pb.TonicSpiking(20, 3, name="n2_2", tick_wait_start=2)
-        self.s1 = pb.NoDecay(
+        self.s1 = pb.FullConn(
             self.inp1, self.n1, conn_type=pb.SynConnType.All2All, name="s1_2"
         )
-        self.s2 = pb.NoDecay(
+        self.s2 = pb.FullConn(
             self.inp2, self.n1, conn_type=pb.SynConnType.All2All, name="s2_2"
         )
-        self.s3 = pb.NoDecay(
+        self.s3 = pb.FullConn(
             self.n1, self.n2, conn_type=pb.SynConnType.All2All, name="s3_2"
         )
 
@@ -147,19 +147,19 @@ def __init__(self):
         self.n3 = pb.TonicSpiking(400, 4, name="n3", tick_wait_start=4)
         self.n4 = pb.TonicSpiking(300, 4, name="n4", tick_wait_start=2)
 
-        self.s1 = pb.NoDecay(
+        self.s1 = pb.FullConn(
             self.inp, self.n1, conn_type=pb.SynConnType.One2One, name="s1"
         )
-        self.s2 = pb.NoDecay(
+        self.s2 = pb.FullConn(
             self.n1, self.n2, conn_type=pb.SynConnType.All2All, name="s2"
         )
-        self.s3 = pb.NoDecay(
+        self.s3 = pb.FullConn(
             self.n2, self.n3, conn_type=pb.SynConnType.All2All, name="s3"
         )
-        self.s4 = pb.NoDecay(
+        self.s4 = pb.FullConn(
             self.n1, self.n4, conn_type=pb.SynConnType.All2All, name="s4"
         )
-        self.s5 = pb.NoDecay(
+        self.s5 = pb.FullConn(
             self.n4, self.n2, conn_type=pb.SynConnType.All2All, name="s5"
         )
 
@@ -177,19 +177,19 @@ def __init__(self):
         self.n2 = pb.TonicSpiking(400, 4, name="n2", tick_wait_start=2)
         self.n3 = pb.TonicSpiking(400, 4, name="n3", tick_wait_start=2)
         self.n4 = pb.TonicSpiking(400, 4, name="n4", tick_wait_start=3)
-        self.s1 = pb.NoDecay(
+        self.s1 = pb.FullConn(
             self.inp1, self.n1, conn_type=pb.SynConnType.All2All, name="s1"
         )
-        self.s2 = pb.NoDecay(
+        self.s2 = pb.FullConn(
             self.n1, self.n2, conn_type=pb.SynConnType.All2All, name="s2"
         )
-        self.s3 = pb.NoDecay(
+        self.s3 = pb.FullConn(
             self.n1, self.n3, conn_type=pb.SynConnType.All2All, name="s3"
         )
-        self.s4 = pb.NoDecay(
+        self.s4 = pb.FullConn(
             self.n2, self.n4, conn_type=pb.SynConnType.One2One, name="s4"
         )
-        self.s5 = pb.NoDecay(
+        self.s5 = pb.FullConn(
             self.n3, self.n4, conn_type=pb.SynConnType.One2One, name="s5"
         )
 
@@ -207,13 +207,13 @@ def __init__(self):
         self.n1 = pb.TonicSpiking(80, 2, name="n1", tick_wait_start=1)
         self.n2 = pb.TonicSpiking(20, 3, name="n2", tick_wait_start=2)
 
-        self.s1 = pb.NoDecay(
+        self.s1 = pb.FullConn(
             self.inp1, self.n1, conn_type=pb.SynConnType.All2All, name="s1"
         )
-        self.s2 = pb.NoDecay(
+        self.s2 = pb.FullConn(
             self.n1, self.n2, conn_type=pb.SynConnType.All2All, name="s2"
         )
-        self.s3 = pb.NoDecay(
+        self.s3 = pb.FullConn(
             self.inp2, self.n2, conn_type=pb.SynConnType.All2All, name="s3"
         )
 
@@ -231,19 +231,19 @@ def __init__(self, connect_n4: bool = False):
         self.n2 = pb.TonicSpiking(20, 3, name="n2", tick_wait_start=2)
         self.n3 = pb.TonicSpiking(30, 4, name="n3", tick_wait_start=2)
 
-        self.s1 = pb.NoDecay(
+        self.s1 = pb.FullConn(
             self.inp1, self.n1, conn_type=pb.SynConnType.All2All, name="s1"
         )
-        self.s2 = pb.NoDecay(
+        self.s2 = pb.FullConn(
             self.n1, self.n2, conn_type=pb.SynConnType.All2All, name="s2"
         )
-        self.s3 = pb.NoDecay(
+        self.s3 = pb.FullConn(
             self.n1, self.n3, conn_type=pb.SynConnType.All2All, name="s3"
         )
 
         if connect_n4:
             self.n4 = pb.TonicSpiking(50, 4, name="n4", tick_wait_start=3)
-            self.s4 = pb.NoDecay(
+            self.s4 = pb.FullConn(
                 self.n3, self.n4, conn_type=pb.SynConnType.All2All, name="s4"
             )
 
@@ -262,16 +262,16 @@ def __init__(self):
         self.n2 = pb.TonicSpiking(20, 3, name="n2", tick_wait_start=2)
         self.n3 = pb.TonicSpiking(30, 3, name="n3", tick_wait_start=2)
 
-        self.s1 = pb.NoDecay(
+        self.s1 = pb.FullConn(
             self.inp1, self.n1, conn_type=pb.SynConnType.All2All, name="s1"
         )
-        self.s2 = pb.NoDecay(
+        self.s2 = pb.FullConn(
             self.n1, self.n2, conn_type=pb.SynConnType.All2All, name="s2"
         )
-        self.s3 = pb.NoDecay(
+        self.s3 = pb.FullConn(
             self.inp2, self.n1, conn_type=pb.SynConnType.All2All, name="s3"
         )
-        self.s4 = pb.NoDecay(
+        self.s4 = pb.FullConn(
             self.n1, self.n3, conn_type=pb.SynConnType.All2All, name="s4"
         )
 
@@ -292,7 +292,7 @@ def __init__(self, n_onodes: int):
 
         for i in range(n_onodes):
             self.s_list.append(
-                pb.NoDecay(
+                pb.FullConn(
                     self.inp1,
                     self.n_list[i],
                     conn_type=pb.SynConnType.All2All,
@@ -319,35 +319,35 @@ def __init__(self, seed: int):
         self.n2 = pb.TonicSpiking(10, 4, name="n2", tick_wait_start=2)
         self.n3 = pb.TonicSpiking(10, 4, name="n3", tick_wait_start=2)
         self.n4 = pb.TonicSpiking(4, 4, name="n4", tick_wait_start=3)
-        self.s1 = pb.NoDecay(
+        self.s1 = pb.FullConn(
             self.inp1,
             self.n1,
             weights=rng.randint(-8, 8, size=(10, 10), dtype=np.int8),
             conn_type=pb.SynConnType.MatConn,
             name="s1",
         )
-        self.s2 = pb.NoDecay(
+        self.s2 = pb.FullConn(
             self.n1,
             self.n2,
             weights=rng.randint(-8, 8, size=(10, 10), dtype=np.int8),
             conn_type=pb.SynConnType.MatConn,
             name="s2",
         )
-        self.s3 = pb.NoDecay(
+        self.s3 = pb.FullConn(
             self.n1,
             self.n3,
             weights=rng.randint(-8, 8, size=(10, 10), dtype=np.int8),
             conn_type=pb.SynConnType.MatConn,
             name="s3",
         )
-        self.s4 = pb.NoDecay(
+        self.s4 = pb.FullConn(
             self.n2,
             self.n4,
             weights=rng.randint(-8, 8, size=(10, 4), dtype=np.int8),
             conn_type=pb.SynConnType.MatConn,
             name="s4",
         )
-        self.s5 = pb.NoDecay(
+        self.s5 = pb.FullConn(
             self.n3,
             self.n4,
             weights=rng.randint(-8, 8, size=(10, 4), dtype=np.int8),
@@ -371,35 +371,35 @@ def __init__(self, seed: int) -> None:
         self.n2 = pb.TonicSpiking(10, 4, name="n2")
         self.n3 = pb.TonicSpiking(10, 4, name="n3")
         self.n4 = pb.TonicSpiking(4, 4, name="n4")
-        self.s1 = pb.NoDecay(
+        self.s1 = pb.FullConn(
             self.inp1,
             self.n1,
             weights=rng.randint(-128, 128, size=(10, 10), dtype=np.int8),
             conn_type=pb.SynConnType.MatConn,
             name="s1",
         )
-        self.s2 = pb.NoDecay(
+        self.s2 = pb.FullConn(
             self.n1,
             self.n2,
             weights=rng.randint(-128, 128, size=(10, 10), dtype=np.int8),
             conn_type=pb.SynConnType.MatConn,
             name="s2",
         )
-        self.s3 = pb.NoDecay(
+        self.s3 = pb.FullConn(
             self.n1,
             self.n3,
             weights=rng.randint(-128, 128, size=(10, 10), dtype=np.int8),
             conn_type=pb.SynConnType.MatConn,
             name="s3",
         )
-        self.s4 = pb.NoDecay(
+        self.s4 = pb.FullConn(
             self.n2,
             self.n4,
             weights=rng.randint(-128, 128, size=(10, 4), dtype=np.int8),
             conn_type=pb.SynConnType.MatConn,
             name="s4",
         )
-        self.s5 = pb.NoDecay(
+        self.s5 = pb.FullConn(
             self.n3,
             self.n4,
             weights=rng.randint(-128, 128, size=(10, 4), dtype=np.int8),
@@ -416,9 +416,9 @@ def __init__(self):
 
         self.inp = pb.InputProj(1, shape_out=(3,))
 
-        n1 = pb.neuron.TonicSpiking((3,), 2)
-        n2 = pb.neuron.TonicSpiking((3,), 3)
-        n3 = pb.neuron.TonicSpiking((3,), 4)
+        n1 = pb.TonicSpiking((3,), 2)
+        n2 = pb.TonicSpiking((3,), 3)
+        n3 = pb.TonicSpiking((3,), 4)
 
         n_list = pb.NodeList()
         n_list.append(n1)
@@ -426,10 +426,10 @@ def __init__(self):
         n_list.append(n3)
         self.n_list = n_list
 
-        self.s1 = pb.synapses.NoDecay(
+        self.s1 = pb.FullConn(
             n_list[0], n_list[1], conn_type=pb.SynConnType.All2All
         )
-        self.s2 = pb.synapses.NoDecay(
+        self.s2 = pb.FullConn(
             n_list[1], n_list[2], conn_type=pb.SynConnType.All2All
         )
 
@@ -446,7 +446,7 @@ def __init__(self, tws: int = 1, name: Optional[str] = None):
         self.post_n = pb.LIF((10,), 10, 2, tick_wait_start=tws + 1)
 
         w = np.random.randint(-128, 127, (10, 10), dtype=np.int8)
-        self.syn = pb.NoDecay(
+        self.syn = pb.FullConn(
             self.pre_n, self.post_n, conn_type=pb.SynConnType.All2All, weights=w
         )
 
@@ -459,12 +459,12 @@ def __init__(self, tws: int = 1, name: Optional[str] = None):
         subnet1 = ReusedStruct(tws=tws, name="Named_Reused_0")
         subnet2 = ReusedStruct(tws=tws + 2, name="Named_Reused_1")
 
-        self.s1 = pb.NoDecay(
+        self.s1 = pb.FullConn(
             self.inp1,
             subnet1.pre_n,
             conn_type=pb.SynConnType.One2One,
         )
-        self.s2 = pb.NoDecay(
+        self.s2 = pb.FullConn(
             subnet1.post_n,
             subnet2.pre_n,
             conn_type=pb.SynConnType.One2One,
@@ -480,7 +480,7 @@ def __init__(self):
         self.inp1 = pb.InputProj(1, shape_out=(10,))
         subnet1 = Nested_Net_level_2(name="Named_Nested_Net_level_2")
 
-        self.s1 = pb.NoDecay(
+        self.s1 = pb.FullConn(
             self.inp1,
             subnet1["Named_Reused_0"].pre_n,
             conn_type=pb.SynConnType.One2One,
@@ -605,7 +605,7 @@ def MockNeuronConfig() -> NeuronConfig:
     offset = random.randint(1, 100)
     interval = random.randint(1, 2)
 
-    neuron = pb.neuron.IF((n,), 3, reset_v=-1)
+    neuron = pb.IF((n,), 3, reset_v=-1)
     ns = NeuronSegment(slice(0, 0 + n, 1), offset, interval)
 
     axon_coords = [AxonCoord(0, i) for i in range(0, n)]
@@ -618,7 +618,7 @@ def MockNeuronConfig() -> NeuronConfig:
 
 @pytest.fixture
 def MockCorePlacementConfig(MockCoreConfigDict, MockNeuronConfig):
-    neuron = pb.neuron.IF((100,), 3, reset_v=-1)
+    neuron = pb.IF((100,), 3, reset_v=-1)
 
     cpc = CorePlacementConfig.encapsulate(
         random.randint(1, 200),
diff --git a/tests/backend/test_mapper.py b/tests/backend/test_mapper.py
index a0b3d028..0f276527 100644
--- a/tests/backend/test_mapper.py
+++ b/tests/backend/test_mapper.py
@@ -200,11 +200,14 @@ def test_network_with_container(self, get_mapper, build_Network_with_container):
 
 
 class TestMapper_Export:
-    def test_export_multi_nodes_more_than_32(self, build_Network_with_N_onodes):
+    def test_export_multi_nodes_more_than_32(
+        self, build_Network_with_N_onodes, ensure_dump_dir
+    ):
         net = build_Network_with_N_onodes
         mapper = pb.Mapper()
         mapper.build(net)
         mapper.compile()
+        mapper.export(fp=ensure_dump_dir)
 
         assert len(mapper.graph_info["output"].keys()) == net.n_onodes
 
diff --git a/tests/backend/test_placement.py b/tests/backend/test_placement.py
index 8e948c58..8a639044 100644
--- a/tests/backend/test_placement.py
+++ b/tests/backend/test_placement.py
@@ -28,8 +28,8 @@ def test_get_raw_weight_ref():
 
     w_of_neurons = [w1, w2]
 
-    n1 = pb.neuron.LIF((20,), 1)
-    n2 = pb.neuron.LIF((30,), 1)
+    n1 = pb.LIF((20,), 1)
+    n2 = pb.LIF((30,), 1)
 
     dest = [n1, n2]
 
diff --git a/tests/backend/test_segment_utils.py b/tests/backend/test_segment_utils.py
index 289c741e..2de467aa 100644
--- a/tests/backend/test_segment_utils.py
+++ b/tests/backend/test_segment_utils.py
@@ -342,10 +342,10 @@ def test_get_neu_segments_both(self, neurons, capacity, wp, lcn_ex, expected):
 @pytest.mark.parametrize(
     "axons",
     [
-        [pb.neuron.LIF(600, 2), pb.neuron.LIF(800, 2), pb.neuron.LIF(256, 2)],
-        [pb.neuron.LIF(384, 3), pb.neuron.LIF(383, 3), pb.neuron.LIF(385, 3)],
-        [pb.neuron.LIF(1153, 2)],
-        [pb.neuron.LIF(2222, 1), pb.neuron.LIF(2378, 1)],
+        [pb.LIF(600, 2), pb.LIF(800, 2), pb.LIF(256, 2)],
+        [pb.LIF(384, 3), pb.LIF(383, 3), pb.LIF(385, 3)],
+        [pb.LIF(1153, 2)],
+        [pb.LIF(2222, 1), pb.LIF(2378, 1)],
     ],
 )
 def test_get_axon_segments(axons):
@@ -362,8 +362,8 @@ def test_get_axon_segments(axons):
 @pytest.mark.parametrize(
     "axons",
     [
-        [pb.neuron.LIF(1151, 2), pb.neuron.LIF(1153, 2)],
-        [pb.neuron.LIF(1151 * 2, 2), pb.neuron.LIF(1153 * 2, 2)],
+        [pb.LIF(1151, 2), pb.LIF(1153, 2)],
+        [pb.LIF(1151 * 2, 2), pb.LIF(1153 * 2, 2)],
     ],
 )
 def test_get_axon_segments_boundary(axons):
diff --git a/tests/conftest.py b/tests/conftest.py
index 14b3e65d..609e9d2b 100644
--- a/tests/conftest.py
+++ b/tests/conftest.py
@@ -23,7 +23,7 @@ def __init__(self):
         super().__init__()
         self.inp1 = pb.InputProj(1, shape_out=(1,))
         self.n1 = pb.TonicSpiking(1, 3, tick_wait_start=2, delay=1)
-        self.s1 = pb.NoDecay(
+        self.s1 = pb.FullConn(
             self.inp1, self.n1, weights=1, conn_type=pb.SynConnType.One2One
         )
 
@@ -44,10 +44,10 @@ def __init__(self):
         self.n1 = pb.TonicSpiking(1, 2, tick_wait_start=2, delay=3)
         self.n2 = pb.TonicSpiking(1, 2, tick_wait_start=3)
 
-        self.s1 = pb.NoDecay(
+        self.s1 = pb.FullConn(
             self.inp1, self.n1, weights=1, conn_type=pb.SynConnType.One2One
         )
-        self.s2 = pb.NoDecay(
+        self.s2 = pb.FullConn(
             self.n1, self.n2, weights=1, conn_type=pb.SynConnType.All2All
         )
 
@@ -70,9 +70,9 @@ def __init__(self):
 
         self.inp = pb.InputProj(1, shape_out=(3,))
 
-        n1 = pb.neuron.TonicSpiking((3,), 2)
-        n2 = pb.neuron.TonicSpiking((3,), 3)
-        n3 = pb.neuron.TonicSpiking((3,), 4)
+        n1 = pb.TonicSpiking((3,), 2)
+        n2 = pb.TonicSpiking((3,), 3)
+        n3 = pb.TonicSpiking((3,), 4)
 
         n_list: pb.NodeList[pb.neuron.Neuron] = pb.NodeList()
         n_list.append(n1)
@@ -80,12 +80,8 @@ def __init__(self):
         n_list.append(n3)
         self.n_list = n_list
 
-        self.s1 = pb.synapses.NoDecay(
-            n_list[0], n_list[1], conn_type=pb.SynConnType.All2All
-        )
-        self.s2 = pb.synapses.NoDecay(
-            n_list[1], n_list[2], conn_type=pb.SynConnType.All2All
-        )
+        self.s1 = pb.FullConn(n_list[0], n_list[1], conn_type=pb.SynConnType.All2All)
+        self.s2 = pb.FullConn(n_list[1], n_list[2], conn_type=pb.SynConnType.All2All)
 
         self.probe1 = pb.Probe(self.n_list[1], "output", name="n2_out")
 
@@ -104,16 +100,16 @@ def __init__(self):
         self.n2 = pb.TonicSpiking(20, 3, name="n2", tick_wait_start=2)
         self.n3 = pb.TonicSpiking(30, 3, name="n3", tick_wait_start=2)
 
-        self.s1 = pb.NoDecay(
+        self.s1 = pb.FullConn(
             self.inp1, self.n1, conn_type=pb.SynConnType.All2All, name="s1"
         )
-        self.s2 = pb.NoDecay(
+        self.s2 = pb.FullConn(
             self.n1, self.n2, conn_type=pb.SynConnType.All2All, name="s2"
         )
-        self.s3 = pb.NoDecay(
+        self.s3 = pb.FullConn(
             self.inp2, self.n1, conn_type=pb.SynConnType.All2All, name="s3"
         )
-        self.s4 = pb.NoDecay(
+        self.s4 = pb.FullConn(
             self.n1, self.n3, conn_type=pb.SynConnType.All2All, name="s4"
         )
 
@@ -128,7 +124,7 @@ def __init__(self, name: Optional[str] = None):
         self.post_n = pb.LIF((10,), 10)
 
         w = np.random.randint(-128, 127, (10, 10), dtype=np.int8)
-        self.syn = pb.NoDecay(
+        self.syn = pb.FullConn(
             self.pre_n, self.post_n, conn_type=pb.SynConnType.All2All, weights=w
         )
 
@@ -140,12 +136,12 @@ def __init__(self, name: Optional[str] = None):
         self.inp1 = pb.InputProj(1, shape_out=(10,))
         subnet1 = Nested_Net_L1()
         subnet2 = Nested_Net_L1(name="Named_SubNet_L1_1")
-        self.s1 = pb.NoDecay(
+        self.s1 = pb.FullConn(
             self.inp1,
             subnet1.pre_n,
             conn_type=pb.SynConnType.One2One,
         )
-        self.s2 = pb.NoDecay(
+        self.s2 = pb.FullConn(
             subnet1.post_n,
             subnet2.pre_n,
             conn_type=pb.SynConnType.One2One,
@@ -164,7 +160,7 @@ def __init__(self):
 
         subnet1_of_subnet1 = subnet1[f"{Nested_Net_L1.__name__}_0"]
 
-        self.s1 = pb.NoDecay(
+        self.s1 = pb.FullConn(
             self.inp1,
             subnet1_of_subnet1.pre_n,
             conn_type=pb.SynConnType.One2One,
diff --git a/tests/neuron/conftest.py b/tests/neuron/conftest.py
index f5990dfc..d218677d 100644
--- a/tests/neuron/conftest.py
+++ b/tests/neuron/conftest.py
@@ -44,15 +44,13 @@ class Net1(pb.Network):
     def __init__(self):
         super().__init__()
         self.inp1 = pb.InputProj(fakeout, shape_out=(2,))
-        self.n1 = pb.neuron.IF((2,), 3)
-        self.s1 = pb.synapses.NoDecay(
-            self.inp1, self.n1, conn_type=pb.SynConnType.One2One
-        )
+        self.n1 = pb.IF((2,), 3)
+        self.s1 = pb.FullConn(self.inp1, self.n1, conn_type=pb.SynConnType.One2One)
 
-        self.probe1 = pb.simulator.Probe(self.inp1, "output")
-        self.probe2 = pb.simulator.Probe(self.s1, "output")
-        self.probe3 = pb.simulator.Probe(self.n1, "output")
-        self.probe4 = pb.simulator.Probe(self.n1, "voltage")
+        self.probe1 = pb.Probe(self.inp1, "output")
+        self.probe2 = pb.Probe(self.s1, "output")
+        self.probe3 = pb.Probe(self.n1, "output")
+        self.probe4 = pb.Probe(self.n1, "voltage")
 
 
 class Net2(pb.Network):
@@ -64,21 +62,21 @@ class Net2(pb.Network):
     def __init__(self):
         super().__init__()
         self.inp1 = pb.InputProj(1, shape_out=(2, 2))
-        self.n1 = pb.neuron.LIF((2, 2), 600, reset_v=1, leak_v=-1)
-        self.s1 = pb.synapses.NoDecay(
+        self.n1 = pb.LIF((2, 2), 600, reset_v=1, leak_v=-1)
+        self.s1 = pb.FullConn(
             self.inp1, self.n1, weights=127, conn_type=pb.SynConnType.All2All
         )
-        self.s2 = pb.synapses.NoDecay(
+        self.s2 = pb.FullConn(
             self.inp1, self.n1, weights=127, conn_type=pb.SynConnType.All2All
         )
-        self.s3 = pb.synapses.NoDecay(
+        self.s3 = pb.FullConn(
             self.inp1, self.n1, weights=127, conn_type=pb.SynConnType.All2All
         )
 
-        self.probe1 = pb.simulator.Probe(self.inp1, "output")
-        self.probe2 = pb.simulator.Probe(self.s1, "output")
-        self.probe3 = pb.simulator.Probe(self.n1, "output")
-        self.probe4 = pb.simulator.Probe(self.n1, "voltage")
+        self.probe1 = pb.Probe(self.inp1, "output")
+        self.probe2 = pb.Probe(self.s1, "output")
+        self.probe3 = pb.Probe(self.n1, "output")
+        self.probe4 = pb.Probe(self.n1, "voltage")
 
 
 class Net3(pb.Network):
@@ -87,33 +85,31 @@ class Net3(pb.Network):
     def __init__(self):
         super().__init__()
         self.inp1 = pb.InputProj(1, shape_out=(2, 2))
-        self.n1 = pb.neuron.LIF((2, 2), 100, reset_v=1, leak_v=-1)
-        self.n2 = pb.neuron.LIF((2, 2), 100, reset_v=1, leak_v=-1)
-        self.s1 = pb.synapses.NoDecay(
+        self.n1 = pb.LIF((2, 2), 100, reset_v=1, leak_v=-1)
+        self.n2 = pb.LIF((2, 2), 100, reset_v=1, leak_v=-1)
+        self.s1 = pb.FullConn(
             self.inp1, self.n1, weights=10, conn_type=pb.SynConnType.All2All
         )
-        self.s2 = pb.synapses.NoDecay(
+        self.s2 = pb.FullConn(
             self.n1, self.n2, weights=10, conn_type=pb.SynConnType.All2All
         )
 
-        self.probe1 = pb.simulator.Probe(self.n1, "voltage", name="n1_v")
-        self.probe2 = pb.simulator.Probe(self.n2, "voltage", name="n2_v")
-        self.probe3 = pb.simulator.Probe(self.n1, "output", name="n1_out")
-        self.probe4 = pb.simulator.Probe(self.n2, "output", name="n2_out")
+        self.probe1 = pb.Probe(self.n1, "voltage", name="n1_v")
+        self.probe2 = pb.Probe(self.n2, "voltage", name="n2_v")
+        self.probe3 = pb.Probe(self.n1, "output", name="n1_out")
+        self.probe4 = pb.Probe(self.n2, "output", name="n2_out")
 
 
 class TonicSpikingNet(pb.Network):
     def __init__(self):
         super().__init__()
         self.inp1 = pb.InputProj(fakeout, shape_out=(2,))
-        self.n1 = pb.neuron.TonicSpiking((2,), 3)
-        self.s1 = pb.synapses.NoDecay(
-            self.inp1, self.n1, conn_type=pb.SynConnType.One2One
-        )
+        self.n1 = pb.TonicSpiking((2,), 3)
+        self.s1 = pb.FullConn(self.inp1, self.n1, conn_type=pb.SynConnType.One2One)
 
-        self.probe1 = pb.simulator.Probe(self.s1, "output")
-        self.probe2 = pb.simulator.Probe(self.n1, "output")
-        self.probe3 = pb.simulator.Probe(self.n1, "voltage")
+        self.probe1 = pb.Probe(self.s1, "output")
+        self.probe2 = pb.Probe(self.n1, "output")
+        self.probe3 = pb.Probe(self.n1, "voltage")
 
 
 @pytest.fixture(scope="class")
diff --git a/tests/neuron/test_neurons.py b/tests/neuron/test_neurons.py
index c8a9361b..7942c274 100644
--- a/tests/neuron/test_neurons.py
+++ b/tests/neuron/test_neurons.py
@@ -10,7 +10,7 @@
 
 
 def test_NeuronParams_instance(ensure_dump_dir):
-    n1 = pb.neuron.LIF((100,), 3)
+    n1 = pb.LIF((100,), 3)
 
     attrs = NeuronAttrs.model_validate(n1.export_params(), strict=True)
 
@@ -22,13 +22,13 @@ def test_NeuronParams_instance(ensure_dump_dir):
 
 def test_NeuronParams_check():
     with pytest.raises(ValueError):
-        n1 = pb.neuron.LIF((100,), threshold=-1)
+        n1 = pb.LIF((100,), threshold=-1)
 
     with pytest.raises(ValueError):
-        n2 = pb.neuron.IF((100,), 1, delay=-1)
+        n2 = pb.IF((100,), 1, delay=-1)
 
     with pytest.raises(ValueError):
-        n3 = pb.neuron.IF((100,), 1, delay=1, tick_wait_start=-1, tick_wait_end=100)
+        n3 = pb.IF((100,), 1, delay=1, tick_wait_start=-1, tick_wait_end=100)
 
 
 class TestNeuronBehavior:
@@ -245,14 +245,14 @@ def test_vjt_overflow(self, incoming_v, expected_v, expected_spike):
 )
 def test_neuron_instance(shape):
     # keep_shape = True
-    n1 = pb.neuron.TonicSpiking(shape, 5, keep_shape=True)
+    n1 = pb.TonicSpiking(shape, 5, keep_shape=True)
 
     assert n1.shape_in == as_shape(shape)
     assert n1.shape_out == as_shape(shape)
     assert len(n1) == shape2num(shape)
 
     # keep_shape = False
-    n2 = pb.neuron.TonicSpiking(shape, 5)
+    n2 = pb.TonicSpiking(shape, 5)
 
     assert n2.shape_in == as_shape(shape2num(shape))
     assert n2.shape_out == as_shape(shape2num(shape))
@@ -260,8 +260,8 @@ def test_neuron_instance(shape):
 
 
 def test_neuron_keep_shape():
-    n1 = pb.neuron.TonicSpiking((4, 4), 5, keep_shape=True)
-    n2 = pb.neuron.TonicSpiking((4, 4), 5, keep_shape=False)
+    n1 = pb.TonicSpiking((4, 4), 5, keep_shape=True)
+    n2 = pb.TonicSpiking((4, 4), 5, keep_shape=False)
 
     assert n1.spike.shape == (16,)
     assert n1.voltage.shape == (4, 4)
@@ -300,7 +300,7 @@ def test_neuron_copy():
 
 class TestNeuronSim:
     def test_TonicSpiking_simple_sim(self):
-        n1 = pb.neuron.TonicSpiking(shape=1, fire_step=3)
+        n1 = pb.TonicSpiking(shape=1, fire_step=3)
         inp_data = np.ones((10,), dtype=np.bool_)
         output = np.full((10, 1), 0, dtype=np.bool_)
         voltage = np.full((10, 1), 0, dtype=np.int32)
@@ -312,7 +312,7 @@ def test_TonicSpiking_simple_sim(self):
         print(output)
 
     def test_PhasicSpiking_simple_sim(self):
-        n1 = pb.neuron.PhasicSpiking(shape=1, time_to_fire=3)
+        n1 = pb.PhasicSpiking(shape=1, time_to_fire=3)
         # [0, 0, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1]
         inp_data = np.concatenate((np.zeros((2,), np.bool_), np.ones((10,), np.bool_)))
         output = np.full((12, 1), 0, dtype=np.bool_)
@@ -325,7 +325,7 @@ def test_PhasicSpiking_simple_sim(self):
         print(output)
 
     def test_IF_simple_sim(self):
-        n1 = pb.neuron.IF(shape=1, threshold=5, reset_v=2)
+        n1 = pb.IF(shape=1, threshold=5, reset_v=2)
         # [0, 0, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1]
         inp_data = np.concatenate((np.zeros((2,), np.bool_), np.ones((10,), np.bool_)))
         # inp_data = np.ones((12,), dtype=np.bool_)
@@ -339,7 +339,7 @@ def test_IF_simple_sim(self):
         print(output)
 
     def test_LIF_simple_sim(self):
-        n1 = pb.neuron.LIF(shape=1, threshold=5, reset_v=2, leak_v=1)  # leak + 1
+        n1 = pb.LIF(shape=1, threshold=5, reset_v=2, leak_v=1)  # leak + 1
         # [0, 0, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1]
         inp_data = np.concatenate((np.zeros((2,), np.bool_), np.ones((10,), np.bool_)))
         # inp_data = np.ones((12,), dtype=np.bool_)
diff --git a/tests/simulator/test_simulator.py b/tests/simulator/test_simulator.py
index 9edd50c1..a0461a38 100644
--- a/tests/simulator/test_simulator.py
+++ b/tests/simulator/test_simulator.py
@@ -14,13 +14,13 @@ def __init__(self, n_neuron: int):
         self.inp = pb.InputProj(pe, shape_out=(n_neuron,), keep_shape=True)
         self.n1 = pb.LIF(n_neuron, threshold=3, reset_v=0, tick_wait_start=1)
         self.n2 = pb.IF(n_neuron, threshold=3, reset_v=1, tick_wait_start=2)
-        self.s0 = pb.NoDecay(
+        self.s0 = pb.FullConn(
             self.inp,
             self.n1,
             weights=np.random.randint(-128, 128, size=(n_neuron,), dtype=np.int8),
             conn_type=pb.SynConnType.One2One,
         )
-        self.s1 = pb.NoDecay(
+        self.s1 = pb.FullConn(
             self.n1,
             self.n2,
             weights=np.random.randint(
@@ -50,13 +50,13 @@ def __init__(self, n: int):
         self.inp1 = pb.InputProj(fake_out_1, shape_out=(n,), keep_shape=True)
         self.inp2 = pb.InputProj(fake_out_2, shape_out=(n,), keep_shape=True)
         self.n1 = pb.LIF(n, threshold=3, reset_v=0, tick_wait_start=1)
-        self.s0 = pb.NoDecay(
+        self.s0 = pb.FullConn(
             self.inp1,
             self.n1,
             weights=np.ones((n,), dtype=np.int8),
             conn_type=pb.SynConnType.One2One,
         )
-        self.s1 = pb.NoDecay(
+        self.s1 = pb.FullConn(
             self.inp2,
             self.n1,
             weights=np.ones((n,), dtype=np.int8),
@@ -79,13 +79,13 @@ def __init__(self, n: int):
         self.inp1 = pb.InputProj(pe1, shape_out=(n,), keep_shape=True)
         self.inp2 = pb.InputProj(pe2, shape_out=(n,), keep_shape=True)
         self.n1 = pb.LIF(n, threshold=3, reset_v=0, tick_wait_start=1)
-        self.s0 = pb.NoDecay(
+        self.s0 = pb.FullConn(
             self.inp1,
             self.n1,
             weights=np.ones((n,), dtype=np.int8),
             conn_type=pb.SynConnType.One2One,
         )
-        self.s1 = pb.NoDecay(
+        self.s1 = pb.FullConn(
             self.inp2,
             self.n1,
             weights=np.ones((n,), dtype=np.int8),
diff --git a/tests/test_network.py b/tests/test_network.py
index ff8962a8..c760886b 100644
--- a/tests/test_network.py
+++ b/tests/test_network.py
@@ -165,8 +165,8 @@ def test_Collector_operations(self):
     def test_add_components(self, build_NotNested_Net_Exp):
         net: pb.Network = build_NotNested_Net_Exp
         n3 = pb.LIF((3,), 10)
-        s1 = pb.synapses.NoDecay(net.n1, n3, conn_type=pb.SynConnType.All2All)
-        s2 = pb.synapses.NoDecay(net.n2, n3, conn_type=pb.SynConnType.All2All)
+        s1 = pb.FullConn(net.n1, n3, conn_type=pb.SynConnType.All2All)
+        s2 = pb.FullConn(net.n2, n3, conn_type=pb.SynConnType.All2All)
 
         with pytest.raises(ValueError):
             net.diconnect_neudyn_succ(n3)
@@ -230,10 +230,10 @@ def test_insert_neudyn(self, build_Network_with_container):
 
         # Insert n3 between n_list[0] & n_list[1]
         n_insert = pb.LIF((3,), 10)
-        s_insert1 = pb.synapses.NoDecay(
+        s_insert1 = pb.FullConn(
             net.n_list[0], n_insert, conn_type=pb.SynConnType.All2All
         )
-        s_insert2 = pb.synapses.NoDecay(
+        s_insert2 = pb.FullConn(
             n_insert, net.n_list[1], conn_type=pb.SynConnType.All2All
         )
 
@@ -289,9 +289,9 @@ def test_Subnets(self, build_Network_with_subnet):
 
 @pytest.mark.skip(reason="'Sequential is not used'")
 def test_Sequential_build():
-    n1 = pb.neuron.TonicSpiking(10, fire_step=3)
-    n2 = pb.neuron.TonicSpiking(10, fire_step=5)
-    s1 = pb.synapses.NoDecay(n1, n2, conn_type=pb.SynConnType.All2All)
+    n1 = pb.TonicSpiking(10, fire_step=3)
+    n2 = pb.TonicSpiking(10, fire_step=5)
+    s1 = pb.FullConn(n1, n2, conn_type=pb.SynConnType.All2All)
     sequential = pb.network.Sequential(n1, s1, n2)
 
     assert isinstance(sequential, pb.network.Sequential)
@@ -302,11 +302,9 @@ def test_Sequential_build():
     class Seq(pb.network.Sequential):
         def __init__(self):
             super().__init__()
-            self.n1 = pb.neuron.TonicSpiking(5, fire_step=3)
-            self.n2 = pb.neuron.TonicSpiking(5, fire_step=5)
-            self.s1 = pb.synapses.NoDecay(
-                self.n1, self.n2, conn_type=pb.SynConnType.All2All
-            )
+            self.n1 = pb.TonicSpiking(5, fire_step=3)
+            self.n2 = pb.TonicSpiking(5, fire_step=5)
+            self.s1 = pb.FullConn(self.n1, self.n2, conn_type=pb.SynConnType.All2All)
 
     seq = Seq()
     nodes2 = seq.nodes(method="absolute", level=1, include_self=False)
@@ -315,11 +313,11 @@ def __init__(self):
 
 @pytest.mark.skip(reason="'Sequential is not used'")
 def test_Sequential_getitem():
-    n1 = pb.neuron.TonicSpiking(10, fire_step=3, name="n1")
-    n2 = pb.neuron.TonicSpiking(10, fire_step=5, name="n2")
-    s1 = pb.synapses.NoDecay(n1, n2, conn_type=pb.SynConnType.All2All)
-    n3 = pb.neuron.TonicSpiking(10, fire_step=5, name="n3")
-    s2 = pb.synapses.NoDecay(n2, n3, conn_type=pb.SynConnType.All2All)
+    n1 = pb.TonicSpiking(10, fire_step=3, name="n1")
+    n2 = pb.TonicSpiking(10, fire_step=5, name="n2")
+    s1 = pb.FullConn(n1, n2, conn_type=pb.SynConnType.All2All)
+    n3 = pb.TonicSpiking(10, fire_step=5, name="n3")
+    s2 = pb.FullConn(n2, n3, conn_type=pb.SynConnType.All2All)
     sequential = pb.network.Sequential(n1, s1, n2, s2, n3, name="Sequential_2")
 
     assert isinstance(sequential.children, NodeDict)

From e0e971746c12f7ad5e017cc6ac189a8bf8d52274 Mon Sep 17 00:00:00 2001
From: KafCoppelia <k740677208@gmail.com>
Date: Fri, 15 Mar 2024 16:28:10 +0800
Subject: [PATCH 20/68] =?UTF-8?q?=F0=9F=93=A6=20added=20an=20example=20for?=
 =?UTF-8?q?=20conv2d=20network?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

---
 examples/mnist/example2/README.md             |   8 ++
 .../example2/examples-mnist-ex2-network.png   | Bin 0 -> 60375 bytes
 examples/mnist/example2/main.py               | 117 ++++++++++++++++++
 .../mnist/example2/weights/Vthr_conv1.npy     | Bin 0 -> 136 bytes
 .../mnist/example2/weights/Vthr_conv2.npy     | Bin 0 -> 136 bytes
 examples/mnist/example2/weights/Vthr_fc1.npy  | Bin 0 -> 136 bytes
 .../mnist/example2/weights/weight_conv1.npy   | Bin 0 -> 200 bytes
 .../mnist/example2/weights/weight_conv2.npy   | Bin 0 -> 416 bytes
 .../mnist/example2/weights/weight_fc1.npy     | Bin 0 -> 92288 bytes
 9 files changed, 125 insertions(+)
 create mode 100644 examples/mnist/example2/README.md
 create mode 100644 examples/mnist/example2/examples-mnist-ex2-network.png
 create mode 100644 examples/mnist/example2/main.py
 create mode 100644 examples/mnist/example2/weights/Vthr_conv1.npy
 create mode 100644 examples/mnist/example2/weights/Vthr_conv2.npy
 create mode 100644 examples/mnist/example2/weights/Vthr_fc1.npy
 create mode 100644 examples/mnist/example2/weights/weight_conv1.npy
 create mode 100644 examples/mnist/example2/weights/weight_conv2.npy
 create mode 100644 examples/mnist/example2/weights/weight_fc1.npy

diff --git a/examples/mnist/example2/README.md b/examples/mnist/example2/README.md
new file mode 100644
index 00000000..f02cb7a0
--- /dev/null
+++ b/examples/mnist/example2/README.md
@@ -0,0 +1,8 @@
+该示例构建了常规的卷积网络，由两层卷积与一层全连接组成。
+
+- 权重及阈值：`./weights`
+- 测试数据：`../data`，数字7
+- 网络结构：
+  <p align="center">
+        <img src="examples-mnist-ex2-network.png" alt="MNIST-ex2 网络结构" style="zoom:50%">
+    </p>
diff --git a/examples/mnist/example2/examples-mnist-ex2-network.png b/examples/mnist/example2/examples-mnist-ex2-network.png
new file mode 100644
index 0000000000000000000000000000000000000000..59b6432347869691c7e150edf2c0575648145da4
GIT binary patch
literal 60375
zcmeFZbx<7b_AWYuI|M>-cPBuC!vF~yAh>IAf(N%DSb_wH;2vCq2A2ePcL@^Q-EI&0
z_Wqqyb<V!~-&=L7x@IO#_sr5~J!`#h=kr?yDNHnCG!O`cDI@(#83aNO0D-`SC`iDW
zs$#i(;0^4gEF}&q9VFcX{()*Qt>pv)2?JLN2Y@Gv%RYcWlpvW`VybTXyQ#=^c&{&h
zE$N1wE+Qa^iHSj24~+tgP@e5V(TvNWs$#EmSQtk`KO(*Yi**L&=j(<%MP&VyZ}{5d
zAT^nT;k|fta%IEJKz!qg(8K19+_#jg)SgscPnSWrR&h95$bWY%%fgXs42Hx|gK;VU
zy8{H@u8Z(rf4wps21>(tManbONYH<Ea8mZa_%CILz_HV{Ld)gI`YfaVyDyJ~2@n7O
z3;%!g#s6>l|D#zRPyT;7Y@n%d?d~AbY&q#xFhZR=*)naC^dmS##v{~8<>k(i@mrRv
zN&N_yi~+I;qK&(p78h^px|UO~PPX-uSRRfx(hOnr%C36dsa68QM*zJ6385@2lZCdB
zLOsEaNQQY|&I@cEpF!n7pBCDES)l76pXc2;EAC*Z07#bk-7e@54@v<h<+ULF{=)$-
z-4yf--VGj7qeVH*@h?b#TES_b<;-|URIdoIXxsSezqXqMy+wlffY8DH6Z{m}$^3rU
zXE`JK=DvTkR}ycyuxvGa2^S)t+b##fBDN_8-)R+4bTc%=PaJ19b1jFqvP(k|q+4m>
zdbZKHSD{xR9t3-G5C^m+c9Zz#jj`dCh^aHAjveX>Dn>p;fjSdI65tM>LS1?#@~uGk
z!^0vIYIetn<~MMW{8B8w@PsIa9|tpRj6izeDh;?c-27O>@3(eZpyR-p)<aDYb@N3Y
zG34V>N~hGvy#p4Z_18$*AFp0Ip$<^}gR4?F!&wXilO$&F-$(D~LAJ=lXss_o?iVo(
z3l5fikvP#?UCrRjH5Gr6=(A94%Y+i32Qxh0`biEF+AJHOjP<%Z^xd(ptgPkI_oBVe
z#JPt~EN5|VV!T!bb<ioci=O&8@I8fD)PgcHtdx@mi?L-%km>04mS~mq{I0XX%irem
zZhiyD-o3rh@)WfA<uw$<(%G2!pK-0`QlLO_A=4>nIVn6v2}0w9m(&J)B<~XK*P@zk
zop=gR{yvF04RkXWx=x-8zw&_uDh5(OE}wMOzI?XCS2TfTXe^v}%v8u3ud){b@7DK9
zayJP9W`5wH6aZIyaN&D&yrIytY`N99C~2(IRC2dg*Z)JBjR0L|(=G~Cxq7Rp-Q>t8
z@)!^h9yqJBIARY+H?hhIHOzwd3DEMmYbvO}*J>HHuvdQBxEHrpFzm~fr66UcoGe(3
zTF!LwE{M<$&^7pLA?awWujeAcP66Dq2IzS7>qzihwuQW6G?bP<p{1@DO=Qzct{<xt
zdaD_zAz9~+XzCfSpEV!_EFsvp^ztJW%4D2#EqS>XS!fWo;?fPXgjOk~7&;=Zx9Pcq
z9J3@AD{rKJ5}K(yaHYe6L^ST*y0;EQ%sv_~{kyIhAyoa5`F<8OQ(DpMBhz#G68ftb
zVcl>49jN(*XFKtYD;MD3@If=@zcp6{)nY`$3L`OJ_vD%O6g$|c=v0Cc{rGcB$SDxX
z$|rj!WUvc4)1l;gMrNdMS3^Q$pN=qiIaGgZo*tZfLb%5NN%x4kg6DIpOo{@Q5wRBQ
zTwXB>O5c{+=O06dxwAHz(OD_bxYlGLujujKfjCBQ3nxLOfOVe0l#EE~tFEpq$7pl#
zGzjwS{56RDY@M!!3k_MO!8IFA#NbN#K({1iGBW#u1+S_ezO_M?Ol#K<*^4=dt1*P+
z@)LyyDDsTK+7r4GJ5BYkbcWD^+5Wm5Tg%iJeo45Eg2@%3@7C;kF|27WL3t}OF=k?<
zmgMrS;<mj|@?YE~Q~<(UnY&KtB$+%niwv$^eJl7a=^CCdK3!k%wd_D`tn*_+3&DAO
z2%K?%e10yAqZy)G#H=wY$r5d&QHl{qU6KB9Wh{ydd0DAhshBH3$y(q{Cx7~E>G`e`
z2tk>c0gmY+>?uOIMge16?TaVjyU%b2i%1znJ6yYx8d0ejG9!L{&7Z#!6j~FBgH-Rt
zLflwI5?C(EyEh%FobO&ydT-q;s3?&41<okbe!7hbago$;z)KGWv!3VTMShUDxK^f;
z=OTV~L-Q{xg@Oy@yh<i-|A%n3b2)8VcR$V+u6hk`B8ypO4$35cgA(tC&j7HgAAJ8C
z`p_sKc358g?tOvhXegE@-1A+O-v*CS9XX(66gzXio8g|BD+K#2F3FB%2WB?t5yB||
zZ@;0~R|<E{-`<>2LS;cNonL=+%F~4&)c0;Kcuh?;zZas<@k*C9g=n(BxmQ4yM!V&W
zMz~Bra5R5{;%8h7JsfB@+zD=`w8vf_tbR4NmocA5s;#(~6N}eW5z_dRGE^xf%-K3i
zEOy9O1@8Db-I3r#I&Lqlc;ltWF|ycbVqZa`NAuW03n6N#_rIywC91_lOu;aT*^ggn
zH+F9o;QKn1nJ8F@x##*nZ|~08c;z!Vvm?CxYb)sxsJeHY1*iKYBheO@H?sJeU%3!`
zEQY(Eu`^^E?GC3m3`l;;?5np1bl1O*ogNb+9y;=){S#kCj>SCzgvqpU3^bo;I6D+%
z;vWZc#02exy<R_H%e_%8gll(XR#PaSJV$LiYsQOJ1Cz?(rjbrGbLL<-AO_H>oo>kr
zm{+UB-L5ADsV+W?{>GtA5&eS$2jQOTqg3N_3HWyP1@E1gB6P7;%hAC;amVi%CO_L(
z@A#elgK<y<g(t(=kDfkND%?v5u3loyb2rh?vZQ?xeS2B)&Vd9-dBIYy*;laAyHB4X
zWk5$wjZClx@^4h7Z_}s`9#R0WsO|(y>jM#wNHh?9%{;;zpAIX@PzQwmVSLF>upm4k
zG1tILDvhRJNlht>abL|cI^~|HVzkBXs}!K2Tp$mtWKuuecyR^9)}VXYk?KDgjaYzd
zw~q6iTw8osO?T?E1R=S?{fWlfE8O82A`wCW0n)=c>*)MyQHU`|^#?_3=PS%Nm-FFX
z;)?HGFLL=Q-ox>_$o$hvY{^0*(%u9va*k0HRJG7T58|q1xET1KuyQb4jZ~UdewwT$
z0dV}A2fl+4%s<k0a2}^>LdK44i5AE*ZHx>7HFKPlDYADsJt1DJzDxb965er(zMFiW
zxRie5PdK$TKCJ^<N?=RNrdt_*j&AlK0M+kkgy{OS5QRo0L%B_FRGH!0qtQ0XB0+0f
zy}k^6Hl@)%^urOv4D^EEX3yJSXrujkwb#dp&Qhh{2tBj_?TIt@eO{Tv!=T1KU!$#z
zrD+~taO|o`d8J_Lz>=;laxcn4x!!E86{Dkq8vpK}(1psO{uzlW7$q^IQmnp<0au|V
z_D`dvT22a`o$siNjK_FrAk6)})`AXj<WCYBQ4s%6nv1;`h=;k#GYSj=DkT)+?oo=j
z_*V23+bku%WSZ%)a#e)~D2c!-{SwQ~@A%j=qXk|zQUgnqo>?xg*wW7<`sx)|2BDsE
zjbbh}r4RyyATSc4Zw*t7rdQ+1*4MqKI0|MyxH*{fGx3b3AC?zmhL31*gqgp9?N}HR
zazoY_u;;~6!UhW7Tf2%JA4}jPcB40s|B1Fv3;cH}=7%%e>d{oU93kl$=uer{-m`;S
z4#iPfvmzMbCh31ZbgaKO80;~6OeYQxi)>0Z6vC3SUzhqJb~~Qk%y%M0;=@3gnvfQ$
ziN5;sTI6Ue85XFC6GJty;urZ9NJwf<<4T8CbFZV9pT`h-%RpB2X<u4?B{w$&({<Qp
zNY8GSGS69+#7BGg?n2AgTH*!$*V#CjXh0uEWvM0aOb9-TnGw#)2RT~t){gF&gGwW~
z#mSdszPxCT9WoCZk2>|KWDJ(FWVpcWV=`u10$ZRgmuGTw)^al(qTbO^F(EQv`Jn9a
z5}<qjB~O%K4LnX2MM?NPHM?odX7ZbLebRaghPP|B!u2X$;XhFU7+R=1=3{_GY&iiq
z`z%hV;reN7M6XQJaM92_4$fpYg}AVS$kCK9^W|HEnH@Wv5`fa#1D86#W=u8t4b7Y?
zm2HV`d!-+up(3tgD0deKDpehOE0r3%t73*6K!L<5Vsh+yrQFq61TR@d-@}gJ-_Kc<
z><D@pc*<y}-W+WhumkG<qP&T@KF|+EX?eqcr8Hc-OmMSrZ~1Kv!utV^-gN^(BmzG2
zX{ev^1la(6!^Z^}Fu>?~FUr>fhHQE9h(&24419RYY6E2fAM%kh-RG6Gy_&~!V)EK_
z_-5MbkBYMCkduCe1;c0%H0oNmR5T_G8VJ%wfb4Ifv)Q7cSWjSQo-m|e8WgD>Wj4zu
zi`u0y0{DZ75H^k<wZTAw9NTZcE+G)ty5rAGR2|X%iv{^11TIn{Q8MALt~4i}a?Q5x
zI>Vo$cf~o|k+N@4F!yEIPtZW;`Gh&h(9P`e8>Chnkk#d@D+W-=<+Yc5{nE4ygFn2A
z6C4F<Bl-m->NIq!@Q|wLFDU?CUojYdOAC9MrQc*k@L*Z(8+1Umzen}U4&m)c9vdBA
z`0Y(Nh!)}{0OBX3nelzKB&{v#ez{Y%iU4G)f{t2M0!-l)sa9!kd_MP+uZkRDp&#2Z
z!A2$5R8QfrIv;#;U<LK$USY%-h=ENUPGyZ(g93?s%a$N4FiN=p`AO5CMIE}?Nf52S
zwndaVO|n|elrkILO>81~r4qE}7cImWO`V6j_Mwok^;2}eIH$1}_ch9V0+qLQldn2l
zJ1*fD*5l#Qoah=&1=2nV(Y$92ho8NyPx(MHiRD8D!<M}N@Fq>^*7w3hHdZ}<FwvC|
zgC~uBjX-nWKe+8atwb+K=`Y7pNVkis^MjY^Ktlq%<K=h&f0|uMenkSy)z&7!OB%;1
zGUt;KUe_z}gx#>%&7u&09;tYHpu`MR&iV^GVslA2T0=H4jq~fOL|Qy#A(GbFPYUS>
zlow=0OatIX0wpCZ14%Opr7?{x0j8O}ehic)jOC6<t$X+k*(@#VOQFQT45P2HYH_vr
z0a1KDc?SdVTE&jYCGn#Jt_CNePwa#cX8VNgqwKgXw&u2fD6G=tHJ}H8Vt8d}RGw=O
z#QgpzaG`i8UrQKhhzK)zi`NP#eE9Ef90J;oag$T9(m;mM9CQ7$bckzoy?w!FG~05i
zo+T+&K^3W;!5+%~@3i6`0S$r&&OVJ3!qEd8@<IiA<;+Gf96TVJMLsB;l<Aj!qi7=I
z8cFx6<y<iH=2IKSmVSDn$>jj4?-l<bZK32OZ=G>3-z#UAxwk&kt*mBJrNQN$&c#j1
zDpi(_p7@<_pLh?$xJKHHiqIm+NKeKpwbi=~n-P2E^ur=t>m2A+dC;>SYj%cDbcVZ~
ztF$7~A{FW=Cj3ncW1ojDx&P(TH!zp-3um7OsZCeSa{MUw45%0bb;|`kyiN>22w{N7
zX(G}VfG4z_$axXALkq+#F==1n-&P_Cg)p;>w&9ZyMhSWbD#%@upomYHvRF+N1sUiL
zXiI?lnY*Qk$nr=MnBgS<gt)=e;UPD|wSN3Gc!12QG|{hMCVEAgRjP~4JY|un^kxa>
zP+zp=YaHh2LcZe_C9dIUEtH-xYson;kU9%Pehg}goX38%?6wFhXfwpPnDt!B%lS*<
z^CvOaABfXi?-;<O$5Imej%NSrYH^1pVH#S6D|txFVT2czblod@+4a3de=a63Nl_0c
zsVpn^G8q!ZV#EwTZ8rY_<Dkb9fLu%ixZTLVUZgS%XpXj~SwpN$h<gY}p6US`315q8
z0#RF*tOhiDm*$TbhA|ihlzuW-<8o*X0&Tqh;DZd^Vty_y#9diR>JffHozh#Ht<L?|
zfnWuhhbN5DE(!|G#A<+ok~4;?qVTbl`_I<*WQ7xy`^fC0hZ+kU!}J2KZkiv8$bL%8
z7<jQjJ0#^>*L+fbnHO?I+@?~!SsTETN$>pkG&Lg}I^)4LPE2zeR5L@QqZ4u0a_KWa
zj`93m^Ffy~4Zhg|qM__7VRxpAh>#j}H3wpV^A)M1b<x4vfeSoobpumoY;oUXy@-j{
zgz$X}I1>ddl${Z5fbofG_5@$|-uW)^Nx;YuaIFSyC0`<+VO8u%38>pA<6G4iN6a15
z=3U0n37$!%u2b*ce&`|ny2yNMqtw;@ue}U-@nZTORs{F~=^sTWpxcc38x~8K$`7ZS
zvQK_*!e1)$Z&7`0jI1=Ii|{nL>UW(AohNY>?{X`6zxqnV?p5P$IT>V2Rs6T+KW*$X
zE}Yp;4~QO6Hm>_@wuKxLh|{rzNZGdd>UHI?wCvWH1T#B4j(dxJmXGpTJsyntSvlL2
z!s@8BC|u8<qSa;$3l?xJh!R`NSH*9r0OnUeuT>6|A^?jDF54^7U`b*@3k)mXa;pM<
z-EKA~ZIQyrTK_SL3~nSJ(Z{;)0YkV$wqQ_e#P3b)5wVBf%cPkNq5F;#R!KGELwnZm
z+RLP0A7hg81&hvRNqnhb86C8%rr`b_WlL&QT8>knz3&UFfA%~{UI)Th5?|bqG)OVv
zZPbCd&lqFHJD9M*Vb1~newGu-EpDf|<!7?HlqocfIV~z6-qD$y@JGEqi1zIookYcY
zT^wgt*q$noqc3%&c^(H4y00jSyy-0Q=)AMy%{3J;P<AE&cRqv~zW{h2!5!6aRREjc
zOHdN&Wt!pkbb{Ak=cGRIuY%`PA7}-oAy7WA8dk<=C6C*yevDlf$`rv~vT6*J%?~Z}
zo1SHkwcRS(8o|mBHXv7)hZfdhs^`~Rdp8%|JU++E`^M|!e5oDDv;75LNZ?PWc?cU#
z-$so$|K&h-xPsvr@qUyhBf2X<DME){4W52(W(GVqo2nGTNvE^Vy;RO>PRu}*>g}7+
zJlet!0U>%sBN}y02M;CmTO=!;3$w>5P$e%i$YA7WOGi=%P-q?kQ^@7M2O+=|!(CG8
zrAfIy=(>pX)_rM$P*{As*RMZ|d2YMF>{`TB9imCkk_S(ls+)mv@p@2jCle=Iz7o9+
zqVmCcVj^Mm$`ph<9G6j^W@z*$ce=en2x{X{j5_a)tNr>oT5j<}13tsa=e5Qqg8T%*
zG%Z-AdpxS1aOx-$XYy7JbWhLr%yPIs$o$BL5TQY?RaMpsqbX>Z)z7wOTPAoEl*kxP
zGSl9SP_J-4lGGreV=j^uDC3t4n6?EQHNj%ia~2Cg8eDIZEB?orWXRCa$R}f(;WISx
z>~Wz_R2Yvv0+C}C)V1aX($br&KmUs}UEe|jBHh`jOLQxTqxDdFzNEjonFBQ<L-voF
z=su5oP%!TOjK2cC(xqdL0ac+E(6-6e->hq91u@;uZ+S_+nonT6I7y8X_aP1WN3D7B
z);GeIv5Vy))lbe_4jPc(UZckLP$in<4isTP*`CDpze$blPU{{@1$er0QJ2<ZUm*=)
z12<jwVu6LLoyK)Ii0&XFM+I}h#58Wv4(YK~fxL(Fa1PY|*7FOz&SO6m*(QQG{APXG
z0M3F``QkN5vFLqKUeez@t1s4Kx0yVF%3u})Y&_|Ce?E;Jju)08BGlTeAP{?t^p!GB
zUqVUbs1F>d9!F3qs^PuH%_vP8k#YqRbP4yxn~_c1<r8}7jf7hd-S5miJLQ1rj(^x3
z^f&6)T!!#b5_Ry)-ur#f8nS$bh5MWu&w5*AO#}5lO-)F6*bWkqVd|xnUx3l`W3Q}X
z5C>;pkHr&Bc2FGYa&gHOy^DTzVA?#!OY-5=`a_J#87x9S!6KCCuEgkZL=5^ffp0ZK
zM}i#ISh>9PX<AcA@cz><Cobu|cFBssc4D()A`wo!^vxMn%sozPi2!A%6^ybDKb_F)
z@ouU#q>W2!B&yYM?n}X6S3UR==}S%+H6)}zwFeGEE1)z$d$O!fP<t3PwlpAN=mWP*
zU$o-r^)ED`1aqI}M0s?e<w(wQa1_hT{((dh;IGFXDB<J9cshw!?{<M~)kg+*nQd1j
zge}iyjUFB&vl-~~HI6LUk?obF14ltMa~LgA*J3;4-3%hnX#mW$)JrW^gxTaX>emvM
z=x}&hj8jn%K9ALtdN|cI_wKegOwm;G*L+cgpZAHs9jKTg1t7z_ahYsa`b~|6Q=4}H
z{`C8nzb#8%XUZft&ytlh9Xch$zka+kEC8$!fN>5pNf{1udT}X_2YLC~SnVV=wdOme
z6rjAAeluO0dCltW>(ekvfn)hCoaBy7_L*d1MUs*4ns9rTN{iC-=lokVc6~^_-k?S0
zk->gu+f_in4Oyed*=Xb<LfE9nXA5GYVL6`ow4s4vZ0%iusa1uo0Yt{sw37XisL>eK
zlyXvIU1C59#J|x@)%nC4dL)82g2su~Lc3%{&7O^2Fmc1T!>R4pVLr_s>n5te>HnZ_
zu|&<jZc?5z5fl7=hX;f8sz3c?f%mqB(S{b^fo*+hU1W6_Z{{e7kp$OpvAA(2vZReZ
zyXZ&w5HV;%oU&)jke{yqe=YP;9;2*HnKqKw*2$(13(ZfZ?Sj9)z<?0on=S5-Wpc-Q
z=zvv~_0?5J#$%ane*;?favA0QwG9a1;Z{&UOBL?4cmcC5WVV-)ieB21z%X~Tl1uBc
z9|6W4IvRvekYh2-absAr-dGxU#-)##%_@HG>oE_G;~8_5o$faV;L{9JM+>!~V$eiX
zJ)#|>4Q@}%o5y~3S?lD$Wl$ea&0y!rRA4=Mv;RBJQ$F5e3-Ws5N3)>1$w+Tj)Q$AL
z>WF0FC%ajY+l1@Tp~@4cG<d!4mcC?E<#TvO3I}Yt;!JjMx#kt;qJ-!%cwFQuX8B+d
z!o3sI1Et^j7`WSC`Pn})O$oL^2pf$t+kT$6Lnq@~#X}ntp(~^OI`CU8WhFvPuFxNJ
zls-M)5wxq$O}ucTvz(e1yyD0Fr3F}%(zWbfz6YF#!W6dEjI{9aXGJ+|pgyv(L^{jB
z#tgt%Vh4?870T6-2kx#eQg&eurlm6@D3N}@&kLG}!}h#UmXd?=sXrI5%~|7z0%X9C
zd&#x<x)(>*(Y*Vjr=-l#y8c9c{}SbCi8sM<6aLk^&fMWHa8(%JOiEb2W1+?u_ddP%
z2Zbm|ayS(rC>Mww-X011PBw#g_Kq3R`@B?L!Q@k_Fj%OpeR&Ebl*8(!HJ<7E1UV^Y
zs7Dl|;<B^dEA8NZS&fQ9HtDcP^)f*1--Rd(;A)CV1zqzQ2>~9MpsbSDI<oFE?o`hw
zlVaa6vUqdQZ@?c0a%6bfgoUi(rDLDbK5R#UIFQ`R{<RkX7WJC1DYd+Ff7+ISg=_yH
zSBC*9&r||i=_nPNe4LQ}2Kszh$|IREX_WgQL$ENU-QimQ5TfkAU3EXM=)_sCA61G;
z_spR!HF1GlIvChHy+_ISq*fl?(sMMfB^_cX8}-X6NiN9j*Z{3XZ*)@=yw*6+?VT&i
zEVED}0bdeAbwyI&M2Xmb8S`V6>@j8cGeISno3-GNA}#7}%)9#7g?k$x?220+rVa>~
zuIVK)#vq$2<z<&F4f>x66NJLg<P=!Q>u2+j5u))>QHE@u=e`!myuHX%(xqpLf92WR
z_f?dU$o{-uS25`)P{Wp%5NiJJK9Ej>a9zvp{LzN@upQN~(u`8{lGTP$MJ?xI2^i@7
z!sV2MB@IUEmX>T#m2xkY%;%EVW~ai)t>Sd&b!`{8jV5z<99ZnxALL|LWr5ktx=C?s
zbnQ(}7<gEur<(q%dHs{i<|m)EoL#+MOT-rv-7<!#VZiFay=`TZg7J71veoE?rOfFQ
zi&^S5pBl}Dp7uCFD>?|f9kVp?mXgS1W?l$gYSlb4!~EJ(pc=qeqP$}iy+kU!s1jn3
z*$EP2;qhZ*rjb|?UBn(y5&~x_11STBrsPgB`q4k>Tpy&FEk^dU-mQ5=AN4+Pq|0qk
zxX-98>c+*i9aow+T0ifWTB@cRkFmVU`w~MBkW;@{+~K0KQ^JB58JjQfB0mvbbu#3{
zVW&^gX*=Aez*qy&7zLGbGGh_)>+n;ta<s@bzA;Wn1@$YH+S`=m#Km8A-#Zm?jFsxX
zASolv)lohsZ3QN8P~sKzPtI>Y-L0bAPL9?ub}~g%YwuHi(O6rFOF53~z7us|?%hI?
z*<-Ox%#{|bKTuPcm7O(}X(_HHeS1AJCo-(CL3Py?k^d(@0QXa@;Cw(-%C6=PI_N+N
z?x$MZg8}(=k6zE`{VF;N{NZfXD8Wlw2#2X#ECIpkS+Dv(MFgk_r+<1>|2(hVqSG?n
zWac1P%(<l$$g!}hCy*|EaYfWB4Js?rj9$xz!#&Fpk$(UB(W;R=VBu@op$u4{jAI|w
z0fSbx+&IPJ#mh#8q1pr+SZ+du!Py@IM;ux$xEXgExU9<^EtD&B+~YPWlwD&S!{c*e
z;#nI$hbaA^qkEhx$Hk(5Jz-fJL^!mg4q>|1{h03vr$NfT^=%GBhz7|z8v53alpP%9
z`Dup*`vi`udi_;7!f%ay-A-_Fw^Xw08r7C0Xw}~zM2o^vFz`P#HJSz@oJcAvT(X|~
zN~T^<X{0xrS>`kcA)xvx@3u^0i;@?$ma?LimR_;kU)3<c+eIdSwB{yDu6tPv$2H8N
zOj}^qvJZi#I=^NWO~s<bgHE#tbNMQdzV4eS)|RcjaqK-WP(=tp)HPVzn$t%UlM%j%
zewM^kJg3Az!IbxY>CH-=0ueBB_be=lex_&D^heP7zDk8uP7nsZzya(F$Y%id1>n;w
zD=I4%YSI_~t%Q-(aN`<Ga5l%B;~L`{^c>G!9@$4B3g2su{G>OyaaH?$Orb2f%#^Ho
z{&YX|<@w2U_3C$CqJI0v6Q|NX08&-|5|qsK$zPBz{c=zTHKT@OqV)j8ez?%U!1U~Y
zj1)!%5w^sTD)P)s%So&9!2E|v`Kch}m(5oY=a<3WqWRH*T9k)pA5zMh{C(1!-_#*j
z6)^zu@HOb!&FJ$@wSBd?8?`;vL6wh_WmluOBDM@2?~T!~I$b+4n*~eFnV9O=@2%>8
z2mE^)-l_>V9`oz?jkDc&%y>+Jz7uK0qd6#_13u^s+tu~I4!Q0f+=;0HhW$Ad;D#Nv
z@4{Km1`3wCOmSc%@Esvk1GIa-Fr$Oq>T5QpG1H=Z+X!m4?7eHaQLT|nuv)`g8gq}m
zIUPJ&Ae+~#j}+3IMB4n<YDxh;5E)jhzrv)1WrQvJWsN!hCWRSJMl+Xx;gz?tfs#RD
zOD`YX-;TskLod^tepcIJAwh*)L)IChd3bh_nzdV?JIG4#GJW{h_~C5yFOQ_rqF29p
zi9|kr7o<(^yeGj}mH~0V|B0^?u>OaGgHUN@pdMT@P$pXi;Y32dGZSOU;=gcZ$PV6S
zak?U25Ij>e&KlSFOjLmc`}MD{TWx=|7rP@}PkiUd^GdIzreuYtT`W+|!?)@*3kDt_
zFTa>0QMxYMZuou1wA3>=2M#;Wt@LU8c0sHI{Uu6!l~3c#3#|o*sVKA-S^w1jC;uUE
zJ-8WZZ{jnq_6is#o_|YI?fP8(x3cy#K)g*wew#>TG%HI*Udxg(Og>f#Zq#Wpjj#MI
zCaV_lyDI8H0E~BlB$>okYM!M$ZGHlMwMWO;)Um6!(t6*+P%*Zz1lM-#*iqg&q2>Qi
zizVG^2>2Zd{zaYOc26gyfB}!&81rxQJC2*tEX!tBlC5MwM=$9e_w~u6(IAB=nk6j#
zX?bbhGnJ3KC-}11p`SrD;5zhHm+ws-_cE;@I7F`td29rGJdk_LyC|@CB`jS39^OED
zojJT?u|@@UIrODx{~dvL0vi6rUwsASn8GQs4FLAi$Z+HM3{CGJccy4kt|1L8p_aaQ
z6Ff1*FOUX#2Gx=+JfiuMj>+(sf<xd286d)2UKHQvF!CA327aeJ?x*3400HA{ulW6E
zDh9bXXv?=imhZlS{(vh790zRRDVIiv<1^gEmz$G@P_<U~=Kky3&S_hPXVZK#)%a2E
zOB~hyh6`UH=z=xREyTsK#1RvA3VMf{bFyUBw`rRPEx$`(W~2Q_%YUo;fBS&^#1Jwq
zHkeiLZ}0!Ve8>m{_Uma|R6O<t|Bl}O@PY3Wa08a(Gx^7f+y70D|Mff@0wK<%c<3Vy
z{R@Ww`L$IHxWOgzy9F~WFaDduf(qE9_)PmBeE*lN|AXdO)W8k?DX&%jLFfN05b#$B
zIv6RSde~U+e^u;1eYVE|ZXjD@O_KeGr2GeI{{BfD7^xQrKHG`@?{toY`U5xYQksvb
z{wF#9l^?KchQ*;^Bep8d$L{Da1pMb$(pRk~?k75pSd|Ii0I@o$?DxX3ucCuP)ume$
z$yb)l39e#PWbELYY)OY&hPIjz-V5F^NSdkji)<IH^mLaZmF1y9xtGQGTUCe;pIv|g
z8zCZYLiKkshaM50&<=e=(d8LLx7xPQ0nojF*G(<2;5!>h{e!Y>0h7|&y&OwTZ9D)h
ztS_97*=Zo&>s-M<ECj|i*d6KfvO<6aWPVdx(0MoYqV&VUtGWkz7bf`jM>ORN0z&kQ
zLmaaNQ@)y!F&(Zw0{Gt0F(6sj&SY*;E08P1z4XwdDZxW1ADM$4;q7eBXFGr7CC?_!
zjU%^b<_G8Oq;tGZEi&&aba3CwL$76DFssvo=KxtMn?gt1A=^b&_S_7KP|%s02iueV
zmaTQWhQauoGLa#`gApV;QBXEiPRjRkwSQiQeAMO@cnRG6WEq=&uAbHgW1EMyXdks~
z(}SZ?9>i1Swt6Cb*x$2$G)TV4e<BrXvvO!D3%zERCmXVChz68oS=jz0qh!F}F3-ai
z2o!5&lsO~`hlgrEywP!l{gxiVH1NtAQ6(~NIVKQsHows%Ffub<BG3p@fpu_zAJwU&
zvI+acNnNDwQj<s5SVwj^S+&_IT(r`5LqxQ=MI&fdTA3GK)f)~Y0)Ny7ne<TK8srvj
zmL&3?#l4v4FXTpfYrx;3D5=$RH^mseD}@Q(Z?R%5D2t(?oX?k1JS)+P0qBh~+=)IR
z&Px&a_V^zihix>7XM1M?gd#|S0CaH%x8C$g208aryxFifD_cRB#Z0_`cKxoG>XTU(
zs&~pXseoft$^nHu>kV#4Jjpb?Z)A+*;5c3%2o!R6q;f6QJ!Gsk^lWN9!eg-Cokk@U
z@qk0drugY6AyskEYP37!ODK3j-uYz#*<tq*m2E%q;LL*|e9L1ZS(_LDwm(!5@7!SG
zxk#umpvp`K_Ldpqnc5Hcl#>Ywz`58jHmg?dcSsHDdzANEHr!&sMox8=8o1J^fIU?{
z&Qyvq=Cer*`N>dP!rivT@`$@+L__8hDtk@Wj;aEuZoVenK;@pXL61#CR!@~*zpYWF
zddi^-S(lzI+?#d9(WyD;`nKm;;jlx#JMHvV9(iv0s4>aAU(n_KMgM>maXA*M1sxz@
z9N|t3)Eg#X7lCbUz;*8)`NnM+Jy4-}lswP6?xytb?Z3a6_Z_%khi~8D-aw%>BnAYO
zm#_}~!jx~bf<!C^_XFh+IfniH`y9VkJeu#!W)u<{ibw+O=<Bz(r&xvRte?625+J!_
zp_$TcUc{2mOSc!{gDY&uY;V6iFx+dm(D-zbcZ;n(A*$yzQ4Q`t`=!;ECJoAHUS$T>
zY=N@vSbC6R%zqZABJ^5tPZE0FYfJuol6=4A*RhEmP|qIZ7YYp_e9p!ExTu5*0Mv9u
z%@#_aS?SdK|B8gt1IEiiC1A0p9IkOy&kQq8BZppWx%n;2u7_mKCgv*bg(-I@Gt>q>
z=`Zs*opva`vlE=W|Bkuy^5Bbb2C}}}k?}dXkZ6tFhR+GxZ<H+vkR)V{{ro@TfF#io
zw!Ul3FDt$Pv)R7{_?7t$N7UK8FW!^YO%Fh@2{{E{U^Cv?_jhu*<tYF-#5c66!ZYT}
z|Lhx-X;lRzGhtq=+H1TUuD1azrfU{to~#dqCz;1d41Dj+cop^W%W{>|0l4_yiADXP
zo+vniJi_$kW$T>zhlHYE0>;Wbqmw}Pyx$`ymV$Et(#OH?s~8kUY{Q)6Yypy4Klgjy
zcVW+<$PDmf(p>_u{ZL&9Sh9i#5d1yp6^W~un9aM*VIEv*2vqcI-K#L#!_LTJBz<fo
zumxesQdZ#c%B@pxwnFuBclW1c;aTbL7<(*&bD?q8ysLRjyv9TK9TnGU2S=-0N_yN0
z!~%SRax4Jlv0S%Rm^1|>)7^L*nkV6n{{b-7PwNrP4i$s?w$O^r*1M^Nd-=27x(Drs
z2QJE#ZTz7l=~f8vJOK&HSdgC5+qq#Tp3exXxB!mCWoWWd`JH!cocT}P=vIXUqOWzl
ze!-HVaCVG(<DeWEXZ_On=QifFE2pI4^zSXvA5Pi&3Q2f2)!2YPZZ1E@M?%#BnY2Gw
z_^<-+O5JY_j?iNefHr`3nLmT+!T_1Chl<|uq1xxc6f#X^@GMCNZUk20_MOGV_G}*<
zUH0i)Dc<a#+cBF>xoD~{U~ovn*ReVZDFz{9TB)`F+*JG6m5BTikNVWZZ@s0sV^nQt
zdEi{KsD*LP|NNbx`Tf^&ZgomO9N@=wv1pfdf%n0)R6W+b=B(z*KJ5?5WaApPCl;4p
zbq_!0S_;0BT^QW#wqT&-8UJ*`z~%f5gblr4wM^~P@s|z=1C(GggiC)JWS*C(xE8!0
z_G!o?Hr3psXy!c!6HV=VuHuw(44bPcYc5)iSg*DWZtsUCQ%=rWcg{R0NXFI+k1WCd
zF+2f)Kd1<2P*F9-fo#IvEhUP*-i~D{DAWC3Y{UIzn`N%9{i#IVL(<0=HUjJS)@4BG
ztW;fXJ7n3?0tAMn$-_$F>G=LRhxw*05X5V?4@vwD=Mvu~!4?$!K{>(Ax9!|YCCZlE
z!L>F^)>Aeeyh{&wEa9hrM)bJS%S(=U`qg1^yN*RH0ha_ok7fJMUMk>B76<Y+i;sL5
zHGn=(WjxP2?xxaw96qYe`|i~Oak3j=hh;<SM+l>77o!;&F15b=g06T#khtDVh0O>b
zJE|8nk~hL*CrO?gWXo#tG+wf<4aD??Ws;3;j=W>w^u40EJUd{_3v9Yv%_ne;@a1x9
zct`(Af(<}wQ&bl$S-2orhlcP@+gaQ@ZhGOdOOiAOJocH0zaHtrfWdQ!c&`3|e#3U+
zz7J||yp+@UtGh>q)2;p0+F%^|-CS+Q0`E(?dQ8$`BAApx>8IK<VkHTrb5YPUz;8Vs
z6ns4&v1lr-Ow$h);Duh$>@^qqycic~NQwFO?ng<{{d8FUQb{=17guLV_8~G@mE>AL
z!CD5|S&c8wWS9(KAj_Xvz$#1NGvFnhz&aS<2aXpZ%lA9B55&TP`z^DdzIi-2zlYQ<
zlDQg9EjCRzdJBF@=ZlJTToiJT<gn9^WmJE<E|<{eZk`?}x04p}EkQ2`_jM@!`}9Jz
zKJ}7z{EK-4QiYH0qP~21YRszAaj2wS|8V0EUuDHg;E9tXq4F@ymnU5Tai<YpPvGmX
zrGef00+MtpEx<gsZ^=yMp1HKLD%-8blieInjJ}wz*fi{1PAefNwG%0n`yE(N8$u)C
z2gD&><0}#wU?2H5ODRS*5Ch}UXk}8~xd5F3k8AAfBR&Ecjd|Cd2E~Bte#;k36y)K3
zVSAAOQp&QZ5=qfhc1=({m!r`|vp0WXN<1%zHg5y?ZnpY$!RpU5_x@J(7<2CsWY06K
z9f!%UBNkpV@bFSb8n!Uzt|LU`P5!^fG4YEA7Y<+Na0Z$wDbR87xmLBY3{U-9N|oZ1
z)KA}YG?Tusx!zX$NSRDXEbij*Mz~iVC49bK-rSM`%EF!3AW=gwpp&PU<;I)*vgm9%
z?>N$y4>t1N>$XEq56-o|;Ynl{OKZ~KtR9@bAbilPZDfjHSrk4f+4uW>9GNRW39{Xy
zsPBE3T$d>~*mQ!Pt1O*8*jYpw9-dP9J6JCK=y7N7ncS&;FSanJWBAY(lSkHBszx#R
zs-j(pESgqZ<E1%dI?fhTA>`xi!u|U0ygY#G^Lqv~W_h=o*H0m7!}nGif@FzjgD;Ig
zRc+B&&rn>t?|tjOB0n)puk#aIsnS9!WRUgFCB|oohVH>w!601?_owS#z64+au8WJz
zBdgi5HlZE{Rg(Q*ZpxlKRXjI3zu!rM+7Cr#A0Btsws$|=tP?QmRGO&THJ)xDoRV`t
z(=X$_bocYRI=rgWc-!J)^IIrCJMX~v4nLb-QA|=2>BoXE#bAl@YblQR(O9s=sZC(Y
z2MX8V-~udbfMVg|!Z60TeocLBatI)9d+w%&Ld{Lp`<BZ*--_D==O`!9wYJaS-cY2*
z%TaIS6qMDGOSjeo;gqt|psK0hZ7O8C&GI|(N43;8ORdNGTH_<w_6&Zxv8zOIs^JBk
zBM)&~TVwhoVq!tq<OVh>n06QrCFH$pDu0RJ8{dY_y(kg&5i$IN){_?O52M+fZ<C#+
z#B8{Ohe>gVVfB-zRrY%!nWV`?ugJ=k!13U++_tJ@lXl!_SWv~7UX2x5eDN)Bmdem%
znC@bcluN&^>8{1@Kmkn1ZT?w#I4{b97dXj4__!DOU-t^t*ls6Y_sTE!^Am_H+1L8U
zBm$vh^5>_W^(4&PhnE*-86B-+Mo;m8ZO(zG`~$X~gTkKev%)vs9d7#-QUfRSp7dZ?
zv-TcGI@v`+%tobam=*V}7$B-DM7D!DqA^8{*)GUcWVwJyz#GXwTnA&sm&YB*vvVHO
z2a^q#-;&0P3IIo3R~;I$#WjR{wSLUg6Ah%ZxT~;K5xBFsF=4_bpGWb|09%&nJ8sV<
zRy_Qmr@WmFyEy7ZhwreUM?;ZYuYphNO6C?tv1Z5%c({FE<1tiDkE;0!AZwwmc@~;z
z+fV&AIB5;xfPRS!T!{YTy(sODliM)Q2j(|;HjVGHziAw=hK}fQm%Z@eIsd~0prOJE
z;U3-N7_p8x>j}`V4g3IJFwOJ6h{FUf_?~=ICZMpT9(rSEC1iVgpL`Bp(K;c>aNlI-
zZ>-%IQ+&I1I;Qel?Ta{^0N~DIycCHfrMH5eN<1+LS+E9%JyaTQFW4*`Zdl}W$@*{B
z(6i#9n6TZzi<T`sojG|dXPicSE?bm<K##KtKNR4TF7CL-WGR4X)>m`xAGTQpJsI5R
zfJSj>*hcv9O43T$YVA>+IP1xb`_vLgH~afe-lG-)XXPEOFOqP?FmaxI?I=`vE7)(u
zlYk%&KrLQ^1f!pe#HPrqpSkXz7PS&h+<{VzK2muLB)qTHhA&_=x>$pwG2+XX<Aj@k
zu(2x^P({}t+w@PAz%+_Z%-i&i7-%IIkzJ~Qs{cj*`5-;Op({Q}D0(#;g%gC&`i_ZE
zHd@ZTRJHWb!{Xqgd_T~>kv|IrP;q#|m=z$+z&l{ar2?#_EDZwr)pS&Dn}L=(&=r@L
zWPwKHnfx}jU79X}DYajAm%?%rzo>Cnntz_;QEM`$E?<q)Mg%?9K&j0e;KzRrW?Irl
z0*x$w0?Jw3nKf|AgJOCF4zQKSPrl^32jZ^LE#af9AZKzOs|WcT=wXuY{p-{@+o6>n
z1JNrKpensxUzzZ|52Wz9!%wcUliJs<xA)i@%~!9-W#_xlbrWhc_bt4RmhDnZY0X1_
zwtPm!UEwrD&gx+vU05S{vHSBQe&5khP&l9CDPsr$(?@QW*e)&e6u%JDKI1En7Q?Q6
z;X0=8O6~VK5wAsWq2Y5iR5Ud3xgq!x6CwBxlSKGRm734J4$pMQ^R@9e(^Z6x4E)fz
z%GQf~+6qPQTfZzcDCNARie*tla~=|wda={p_R@ACWXquc=wc*azo|UJb#EcGES~-6
z(hl$CUQ4-|yst1XK2pHK+CYj^=Kn@*H2QXDu?Mb^T1_);_ARstfYLfSin+5*TW;DV
z^5%wGYS(q-4|`(5&TjMosRCfi6|9^qOJIJ$T(Us%(j5rHDIim;Z}<2F&f>_Lj8o+2
zeZ${vou&cwdq<4se5nc>Mb7Y~)OMjmNGr?YN%6xqi!UXQI={y*A-&fjm85)Pi0EWV
zsCJ3?441`NG0_iUdr`EFp>+G|+gf+-#gr>Bz1QWFmv&40Wd`3&P>XLI73OP#zmT>$
zWlR39COWu*Z$ms@muMb47KiJMTHhy0UO8*_Ha=%~`GJrRC7mtSJONVC9(V`dzC)H!
zP-iSL*cl_SvHkIUrLpE<Hqa<$@mFVr$T{-IY<yJK+NKkQd8e^(RR2HvWdsK7TC3>?
zyNKux)Pf|6qL-lSD(jtt>*bXWLQY#DeRo&l0C|g^Vgm}h^Mf7i*@jGj*duZLN`ptN
zZn*24sZR#^a@NnaSeZ}xOgH)*dZeS5_^RDm<vY9ZSL>Chff3a2Du|p~bVwFsy2gAz
zY)Up^{7KW}3j<KPgH+N<h7zFC_zC_1Ypm=N0A7MAc8w9w;`D@!zK{Vu^U8LWe*MF2
z$Ge{W7E1~opE^Z@#=9d1qs7LZ>m5!b$ir9i`?Io^;f*cw`<T-8zF4umm#)9BS=cYq
zQ|`=vOTM|;bqY(oX8%Gax_=;{uqo@Sq5HvTTqL1HJCH!%lgxlsJ8XA%w_M;euoe0C
z{dIS?X3aLi{B%Cmwde@>W{Uea(R^mVX{PU@5)T>%Kbzqh;C~#!wYNN+V3&F<Q+4;u
zmR>CSW0mM+e)x=g?_&L+x0yax2b@AM$<0Sa@lAPw9dWjEAiCvs<o;r$Vql@}^!5iI
zn;rRWqYK+F`E)<*%|Xn;`nD@)PWNF-X-?tF_jC1Q6skV&Hr_li{TaqZK?zN*b=}9{
zzalFd7r1%Pns)p0c%$cCgq;JfI`F^<f)FxKZiWjq#)2BPlM?8&bcq!)daRbu3}qNU
z6RY(uC&|snm2@(t-8=RW-(FwDb2<s@>v9!ZZz$*W`?(MUgOpyvFS~&V#Q?^cB0779
z%Xph|_yWA8k3wBr!rPS2`=o2*-df~cLj=%u>XXZwJ;?7s57Qs+g3*&|15(a0pYr41
zE;Oi6igj45=PgYw|L7t=NpFr*DM^p;oJddNuVj5NePQd?$acQFbnw9VV3}w1t30#r
zN85wr_}%@K!5w(2l1^^<>Zr_UCFH>085a?F`tAUz&X;3!Ll6m{qkruM@G*Tet}@Va
zd&B_PUaW<!0(f+(x8^?8Rc!m*>-5RP!)q25k<@VHG(q>T)JhOdxV?z;odaygC8sfY
zw`z@{{PU*!`!_;I?X89xTFTBt?lz=@j08R&8;j&atBv1>&Tp)TckC_|*^xsK0_+;T
zJumevX2T*E2uLpL?Y!Dd@xQ%N=$Mjg`N?py5iGx%TdH>pw#y?x3P{~=yF6EU+c4LX
zlG=a@(E5hEA~P4D_6@)fbH1&$_w%yw?g(t;)x;FS+wS%jj1j#fzriBM+Vj5u!_K^~
z{Jf3a#gYuDcRSNgCb-h^z<jb2A$2M3x>sK$r@1mgw74qhx>xpkBVyog%IlX4h2KqC
zlTd8`eR2(Wr3o1;W2+-#HF(Jf{bVENVj&bvmiB4eh=2XMr9oR_l(|o@jb$-;Lo}SE
zNP2c%N6-b$hgEFFE>A)1jGLwF{mEW$oQ2yGeB01(fCn+^6&$^|Z~gNrFTFjRO{a5L
z<74Swx-XR(#BK5x(PFVawB-()``gU{@)xyz_iw=ui;HgHm0Z!1&KKCCtD<ylu7ti1
zi#$LdVb?E`P9)Nvt}gJ_<d#llQLLHJhL(}7Z3|*KQ-xX?&nER736nENM<bR|o9BJ;
z;=5m~KY151?vpR~@)Egs&*UeKFyY$;GWhdR5vw0Z{*)g9u*toMwh;YbtJBI&AKUJn
zkRECkH}7B?sM6HnvhdRDT)yrcxp7a@wce^&W%E@-HPG9Q4u-Kwx3U8?ad#EfdKUnh
zAkQqNf->AEvJpcCW%GOH`z^q9B5TIsLH<>D($E<IHAFc2^=6pl+Y`vgEt%`3J7rxY
zch{Ybf|p14@V6I8a+V`GsEg#M;^KC-KHHX!59=Cj9?>t|S8{5N7h_l~(^&Mq<;#5<
zq4pLyyr)<T7Lqc<b+cy!w+yk_z`~$+_uH@(p`S}1&RO0$OgwCNrOa)MKC}n2Y5&4N
zk;AD2I1Ob%b#B=95eB)fkEgDB^!1PZJ+^Y&v2TV=gBMk8tqNq>H6+)Qw5Np6xh@k^
zcFFHmU4=%o+{dqv;UGVYh=Ws+mU!%J$Hx{>Q?0VmFi_^YiRizIi`l@b0*|aQQ3F5$
ztX+2)&7Kc3$0|Lg{`hfZ$!U<)|62l=S{2#++0WIbqZ?5j3Hh1$CS<j)^8um6$>5)7
zfDLsIj1`7|!anTIBdBCISJoaBl<n@Nt7=Ml$D#F3hPT~K37o4(^xsWcVRup(4BhW+
zL+w9jy?&d$t#yxAm>Wvakx3(U%kXji)M}YrSByDN##8v7k=%NQi{40vL+@sC&foP`
zf%p<`P1P!k`eJRe;dg1d)d42iYRdtyHb0DSysYE7R01Ai>%<m4UK(P_RXtkO<UjH5
zPI(t+E)~`ppDLJ*6mW1bgRWwpF66+{wyfCo<ug%Lynx2M69>8FA}OpmcG=r`pFStw
zo8!1Vc<{MG?2TtlM8TI-OblT#Ajd6c$n&4_5<qVUws0v3A>TLcrMengT-Z8v;Uuq@
zu0x{6mz@hW6fF``S%3z?{D9Vu1kw2zV+J1Bt^_m)#ng6pbpQfjA{>5b#RW!P7mIGs
zL!S1VH#t;+Jh4fC>7=s;^UisO1a)!S17%V869a6>og19aFXsvy+2$Ec^oLx_V$$tw
zzctY6T4bkDF_`&@w=oUam$X#jPaFUNO*!Td&cJi}b`3R}EvD$|cSp#Rc8ec{Z_dRO
zvYxSP;^c-90JA=8>hC_@RTi@dh{r#Dr5XHWQ8kfzhba1ARrkiJmVA=asr8%3BW1+3
zk5j3ukZnfi!18&@LCJctTJvZ0g=VcwwUyiEPrv75nq`_z#ITA<jx8Gd?vE`8_RoAK
z21OLPD7@k9G;gGzXarxZHb}V5v%I#r>h?qWoV?ic{NeM;`r?=aeK)*HLt=8)M85Y_
z8|As(R9U0*-;rvq`K$)toMPTPW#Nq~KR>QIpR#KV>SM2i#M!u%bVAGZgx`hfJstmL
zZ^A)qhzN8yl^=hcy%TxPRg`ssFxiH#*qZdWOWfwkKI4|gMvpJi4yI#y5PqSB-I%7E
z&r>L|aeYb|x%fS&S=R2s>3k5F%&)(H*s4yumgT4)ugQijYBz*SdYke_5L#nj7`$^A
z$mQK{89a=gyqlT;8&xx?;MJ=u;H5h+U{2Sase07w$vqR>M^IOxJ}8T8_)yFGmEgo@
z{+3_@J<afoZ}1^GK>x|sR2?#a(HS!Kq6<q}<AI1OqmE>_`@KNa1zBH9Pr<u-6|GTW
zg8p;^H3Q#bonY<S`DevCWs~mrPiL&;vTrC3)0eSg`#2hL44Onlq)vLii~RI&@<4vj
zlLzWrH?A~R?2ta$jxSYfPaxQc!IPt6@9FsC8rpOm0FpBk+#9nKwwjZi5d^7l*-zOc
zu`d>MvC|CQrst1l8U*0<IXI89O{ZNC?aTe9LRa4XFmq9#g16>R1bA6YlhoW;Dr}9c
z6a-A<FH^63iF~;FWVczqch6=U?6;gBN)(nX-zQtGUjG{V0n8PPKb{!uOl5D#*CJSZ
z2$7R&SG;-M7o#SUB1qsWG9z4kpXEw_rN}77g2+)Cfj2XAAF&G5_!IE&UpEgNm1{kz
zB#sP@Q#bpc-HrLG!V#L1MXm{-u^L2WbI3?6oDT|8StimoxisP?{nFlkQSAD>ned{}
zN?lK%IIQA80evz7a{A>px>Hrc>16bVz}s<z0J^4{X#&R2`?BgbRe|_KI5jvvXhGjH
z6u>4}VsP}Z{wt<+wr;M5!!)k1+dn)r&!0rk>)Ey{huyoPv8gK9NPO{FR1tjGn(U3S
z-sLhhpVF*4`fg)fV{65Ha5NQwzxk~xx9`9#CmtvvDeD|GCArO9(ckW_SMRMw)4$q0
zxiI*SN;20H4_h?A-_1@<Tew(ImL67<zuG%!QMx#PW~3%c$`3cC@1r%op$)Ll?!D*6
zv_bM7f>s7ZL_~G`-=BEYdXsLd7vN6K3*TJ)2HK0~7jp+$b8(`g<d!3(3;Qh`W`>uE
zD>UuzE$w~C`jZd85x=<?_`Q_uhXs!uII&cJnM}&mM1&*q`4iY^Lar|gpDF+E|61Y$
z44q?r&@=DK-S3vqL<qjRkBDE{AIP7LVh8w}-A;D(m76~lsI(utT}SNC{~0F<#!5n$
zS5pL5-Go^tX~7M^yr42!s=pR^F30PaWCTDRd6djgrM%ZMM7OG=VRMW@8(_)Ay;%je
zK2h9Wt77gObmNJXesHDpzCQ__pTFqa`^Dx3UtU{_#Fr+VwuAj)v$}E+zF|KE2f?OG
z>d9L?M+$A}gL<d+b`@+9s5yl@AujC~waV|`kATU@i1{wdbhWG9xRs-<+nXVChn)$H
z^~+nJI&-f0WBWho@9ciB@VaiW;=I~<b90M6Klgj4{5pAK;PnypO7VX*$uMiZPR<9z
z4Gn!&eCMHpNFPd4p5GL{OHf3Xd$ek|IiOSAKG1a-*0tPbg3T&0|Ggxk-&as}8vVVL
z>@3cCw}ccJKK&16BLOJef>87{dG!qku-dJ)nqAB~KT@ruIRFr`wyRB5jS*tL4{InP
z2Dm=Nmpi=r9i{}jIMq#Q(DDx-ZaY!C7k+Rwo(tSB)IGOaVoTy_)8WAQMDjE~sNrI-
z<5TTY+n)jzU`@4+)LUkDH*=w3<w#IF$a~WHu#b@YOchk8xzau@Br1o`P;mM)>u257
zXRNksM>Nl&(VzUgrjScoYNP-)4mK(EoD7$oISU@tOMu3zc(4VyNNk8KAGs}}^a~g)
z&b$4oLF(>aUT<^JN1d6`ZxnH2!lDo+=Na2M6ZwDmdds+|yYCBBNs$mmKpGW9S~?{K
zlvI$8A*5sIhCxzkLApV@yBPuL?rxB728Mx|xnF$#zkA=^m-0b{bN1PL?X}k4Bbc|Z
zzBjQj>)~I+&H`Xr4uU84cb2JbgmTo@q^4(q_6h)EJ?XTJ?!)3pC)EUAU9C)3)^)xI
z#EDhxL;iv#2nDf5`{hC$>)1&fZikifv(XWVTzPU8dR6jg(`|o6(W&yYeSp5k5p=y3
zTt>l3F6abkQ|fF7jMg)U(?$!2maG(e01A)GW}G2BoqLLImWaKPoBIuT9c!}K#o#0Z
z<mrUr89_^;aXd0&mLsL@62flAsrPL`*p;ZRT)&huUMVHHQv)YZ<%N-i))cp^4dX+r
zo~Fp)SU^Iutiu6Fgk;=IBg1*}>4I+qoZleoa>>uD4xORbYhZ8mKH}re->9RQx!yXQ
ziHcu<n#dRtO%v^BiUpUL=e~$1P`r~!q;Y^eft8aZoYm&|vzeD_0IA8tEhhko4|-RH
zb9X1Ow$dpVm3<HwVZXUEW_XBe*Gy{S6`ao>IW;v+Bl2lC`Bi(=)|blEH<9X-IDruO
zp}=jW9nIz>xW@71#OMOzLM_|ELlN^(_@g`-Yp@Gw=qr{p=GM}PnA}ixQMNK{CqI1#
zJm-Ho0`(h#YCq-w`KvYlV&*G1c#d1|W@p35<&~KDJvRgLbZ(L9#g!BuT-)@c$G7nB
z8l`XGeH?(TfZqEF9%cti+i#*WDak{_?Xim*CIC<FR$~c=_ZG$ZV2Fnd!;j3!vjP2e
z7qh*cXQ}b(-f|MmXO@85G3&B7GO3tals%aiAo@uYaPb5afSTjvlRxDMECcv+pq>GA
zJ*f9Ve3P1mnKnz$79pi38GAn((Rs-Yl^g#ZQD2L8^CjG>Z`|+@=p5INImHwbJ+&#>
zbYb{q4cp6x3vGw<h~x8!y8{v*P7e7Io4;B-)6<i7*SXy#QY3ROrpys6?#2gmt1lrW
z(;`dij`20Q+=6+IIc>fs@UT{`h+NEJ%TL3U@!yW45@=6H-UOgsZ}=j(uDc|Q-Ycw(
zL_VV^5dn9kSlIifQQO|-l)(E&>I40iajy$#_Jt{xF+`uI%35dsze(0H*RjifK)rV2
zo8NgpVr?;_((e37jpX!Sk}XI$H}9r+2iRr0TqH4u8GqxB11hHmkWy-%RD*l~Dfar0
zVpu`>;4f>R72r^=B#YR98q6~OHzL;JANhXk#WQMT=stRyA(WA$SEw31n#KpYpX^2?
zUMRekOYWe%QA~0ve%cvzq6I~vJg?9GcFoUKe{6d9J@K#xsF|az$T&_CaYm<v1RRrt
z<_Uijj#S>qFsrGDsCukGs9p<}_)zL&H?b#AQ7ihTm5xKntKP1h`qa~TH_=%r373C(
z2RedymY=|p7CnW0>m}*ms=Al%MHH``L|qFsb4-;0V`2Y6s0jnRHfKq0V<Ppgp&P*f
z8oFgpzj`ynZcTxL;Paw*1-g42iMyN-+wK{Knc%@c)t=4?viV2v9NMXcg6^EJ4V3>=
zCqzo))j*bvW>CbW=H>bKBr?Dl`e6pq)`-?Q4*0D78!4dvYlw<z?2huUz@ld)rqE${
zpxx;0A-yBtZ`vs5K3AkRx4{5AU++5(%r%JQPsEC0%w*f@yE*FeBU1TOTll*R7Qmd&
zXn(t+>6AU4K+?h9EcX5Xy0DE)=KPecpH7*#fMgS`HvIL)eWOMuc);UMhb7X4o<oJB
z2l37Rxv5TnlZ5<xQ|iGz*Y$jlL>O=3H0)dlg+~rIaU_FrlmhKQ+PZ~_(Y}46#L>!Y
zmEtCr6cpllh3ET<scdW0rR9aB2i`Dlf4)i2>K+c7=ZlZl6z~S~qM;9dKUDLao@K_a
zl{Mrj^o5^1_C_CGX<c0jA1qaq2ZfQzUWaZuI0S@!toUf9I!Y_#h?U_3r^svJ!iJXU
zMI58`zfLHN4Alj0`-+jzF;$JhgS+c0e~2e4It1CG#Bj}KECI=W!{C-!c%er}&%edP
zF$IG@P2{cP<{Pm@e!N=Ff{=47km2jloSw*ysjK)vSkgiOez4o{?bzto@n)U{Z%ASJ
zxYKi0P}fy64ZJ`*2^au+ZCPfL0v!QH(0%e7+so1xDsB3tZ06x~M0CR6)*0p3O04)k
zUS*@7YucH>fIVJjS38!5DaYkYu&HFwjPc)}SEq;B#}!6PIMgDZ1g6TI0XUkx68pHi
zIi3+#o^Y!1?#L0I7fjvA8DdR2SL2jp&MT1GE!FgH`jSYc&8~nJ^axBX<lPHJYm|SY
za^Wb*XThu_!zVd}mf<}R7qH^RQAvE({p###37P%aUK#3~Q*Rz&_g-gHViyKC**QIt
z=4wWH9P02k6!R&6F~14O4_i(Ol)`@arv$Ro`}iqzvubr4`+U0xz@<6UkFWyIH-{sx
z!Aie__^bd*<p|Z9+u4_Sir$-Szx@slo+88wEY>Lb))l)V3-Gumms2Kx-V>;g%ep~U
zeJ`w6IOLY<0Z1Hmc}RYH6&_CD&2^-%=P(w;b>riLaCWA=h(Vt>mqBSsa8j-4=H4rd
z3>0p!(v|SLnS9(<cF?~yEMHC(-JdW_+m$xxR!WM9(I<<q1BA|}w@ddH*Y~xT1>xgA
zAAfeWa+54|q%6sc`8|9n!es{+9CSCw+04@W(wD|0ki2M5IPYp5!eX9QSfyz@#eZ9W
zf8v#L=Z%_~@l~1HuG%3bv4No5b6G;ltw(@{+)80Uopa=gVf*=F>hGghK8sIks)km!
z{nAtj(q=mGkI%oN%XBIklJzM>*{EHFLx^bpL?n?LqT5<$8%=bjK4L#4lj>779lb5P
zIdRXYb<dlS)~d4SsI!^-M$!|-WK*6iwe~`$(s+o7T}iRr>tObiV#Y0w0fiW`t^oMY
zxpa4y%swt5o!hkk6x<qF*yy$D;rcm2mh+j|M}(^d5E6GLK&icAII0elj-53IA&<{K
z<zjn&m4uM59pTly^?{8%Lm6`prt#p%Tys`^!?AH$*>Eq=*L=#ZqvwRKqyz-rU~Ub$
zx@*+DI*3Nt{Q;&I(VxLWy48|B^J`EY`Y>Uo!sUFLUd_YIXC&t;Q(=UoH;%Q_IUgIR
z;`}`P{ewk_k~SIe*B#M(T~L&AJ$S)C0U;itP1h2((G$7#tiU<Rac8ttKxY|AEJ_<?
z6#QoaqEABHw)Zup0^W0y00$k6Q_vjS**<%}yHg#s0$16hRipjgm&aA&B_KLqB@^jz
zCz|9%i3Qi9%g*!5(s_KTi!!u@%HE3KUQ%&by0~ejiHoO1JT!I63nan{%ymqPVLUl4
z_=Mse7z_Osk6PVtL`@7jt#~idJtboQ>Q`}_vN(5xs>ph+U7{6Pc1b7t4PSTht4j+1
zwVDL_jfv;rs>99)<K2RHW7&y9-dd9)U&+}(Ujfpw<EwOt{TwzqTm@I*ji`pDz$$hN
zmy_9v$%iF&=9Z1PL0sBDF?5iJ8Xj#XxX!Itw9+$jMIt6ZkgivqOy7_8K96~{RQ0<;
zAG?-$a-wB|E&&~={K&PVj{SRpw4-YM)v7^5<JM5{r<?5&$eV`a0j-lMf5YI=(cwcf
zVuL1oX4zK3haK!60k5Nt&}`$&g<BsY2`h14Yg)hHujv0wB)UFLJ1*$k?~gfQ?MyuR
ze^)uc;cdKD7-hXSl(2}g0Nl%sR%WoVJ=)y<!UC?qFl9Y?hWjIj6zs}RL?;$lnj&Dd
zfiricOe#ciwvXtn)53gmkS^r&q?^cxmTDU9B@az{N^Ah@F&jj3@Y?bMXmR~S0M~Y{
zFY_@F1*)JqYokO<LYTUDlg9bjhL>3Mv^2XB74VbhwaM?W>XYWRA}JBDod+I$9G`?*
zZz-Pf7~xo@apKOza87FW@hFZ4*tS7kfkh`VHv#Ol9mmkyNMGrjwYp|I*oLUXEfx;U
z^Re2psLN8;tyeLw&e|NgXW|hrljz8|K!Dr-X=?O;i84%Gy!5wpX>y_P1AB$AW-fa;
z6%e=y&%1&6qoE^SZUxifgi{@>xB>jl&waR9tAlhWD@mTqw3O#%N09q36>*!DTGm-M
zfOcAh?6U)!VhsAr%*=}Ke*K4oW_U}oyVt11=faQAkKO=On8W~wit%!lsS#}R>Atnk
z%^eyuLeo+b$3FttAts&rj)3~5U>?>~#W?n_x<YT?9-edFW~jLP-m_~(6j8ed0^9ne
z@eIWQ+1_G#lkzF2>K`;t)~|u1+jYYdfUzPSi0>+?%yF=bV{zE#J%I_Fbiil)?>h?(
zvE@U$aPS<#OO+%%P!uKD2mS;7)TNlJtfzo><PRZE7|o3MGT99gH9=&Wh$e?3756g%
zJr7eNFNUS7Us2+C%Nx`M^j91TtBuoh=GG3-(mg=)O%_Q%^U0NpqU1P>VEDRLu1Lit
z-{bmpvM?3W6kdB-U)ylg%|8nTL-UxgC>E*M=Qq76KBzItZ?UJ;t%sP3XIj-3CEj*_
zK{IcS8UxE6e~r@$Sun)2Yp0te11l6xTV5{At{+!NTQ7(df0X@nfS>EWG6ehh%TP?o
zP{w2_QJdV__lB`#N#P~aYJ9xylS@8Fdr&y-xOmBO?@a#MyjeYyO|$6)P7Aj&eO?<M
zhr7-f7$hWGL?u1YcBqKH>2TvJAHL0S|Gd|D8t+bBFj<#dqZIXe^f2l$rSLGSTHA1O
ztem|K3b>236u+BE`jBQs)4&<djA}-%C3GI~soUC|-X+nva$a?WJz`;JdCgbJ_Kf`X
zH)gsap3P9AJyxY1m_}XK)r=iN-d9a@^j4Bhw}pVP-11u`I0|or71}<(yhMcGCg#zV
z^R%!3@-R8KHvzP8EL0omG=3i5E98Jy-!~nC*_<M`P{ng#JgQsd_OXTUQtoWM+oQA1
zzAzSZO}U`ZxaWmA5R`+=WI_$?;R$ck<+JDtFdymq;hhU=rg?+oV7{5$5mdVPma6=H
z=-=_Ku#NcvP6hX<Qp!wKxueFztA0U6^t#i*Vzq!(_4%+EzDkW%P&3#D2T!Y;Wu;8-
zyI02HcS7Ad9L)S5F1f8(mg00*4~NS>_n{rWNC?&_(Qj2_{n~1{c1ZvosT5N02RZ^@
z9!*H~i;wNNc|`5^t9lqRZ`p7hpE8!Ozd(I|PwQM4)<d@=a!ER<-GU`2HEtUcIaaXT
z6@4)gu{Rag_W_Z3vL@%7(Zlkjh0IISM{t5J99rW-WwTJr!{$ysr*UL?G}=T8*nu*1
zt`_oW0gTuvwLCumfc`AeTOPC1m1Ht+OnD=6YiLrJ8{7r5MxW)svhp-h<89s5NmZ*B
zK1+9{<hPv-^l<uny`uNF0xj{3xez_fbeuUHv_?S})75BxMXRT=aaQr!*!97KE3YCt
zU-%L3WOI#}>)~S19Ni#M3JYdOpXV~yq3!9FwnZ%+|FN)pYkQCuU~H>tlU%V3O;-^M
z-aT%i{fi}3s#B?YOMd*TUEsX!4<^ucPHWf#CuFe>f9#&6sfmVgpnXI_pAIE4z9MCP
zr}}!y^$`8B#Qj66=C;&rgE6y)H>>V(p)s&WLpJet_aR`^-V2g;7oE9dt*So{zE$e3
z=(<V(md6xFAXwU>4twPei#CBpV83{0s=HRq_gIH~!xmPd5Ojx&=H#V$%#WX=L%MJM
z2D@i+RO71YDNIm$HzH;}Z>G>M(y>OQ6p|dbPOm%EUw>|RKQ0RlLPfm!gj)wk%`1WW
z6pmUmemc=elqBqKHFg|o3iQM)>E6Q5$a|x@pzKo1EgmFXGq;Ts>E`d0qi@R15{hjN
z!|s4-?UAac3b*6pINbOaIin-GSVnc^QQ)J6Q{U?4YBD%_Kk<#7yH-d{rR{L`lwgjd
zx(g;_0jc$!Lvfav1;_bCVGbkVDU?dU_&kyZ726BAt-1ix9}BY{hk&FWUr4(du%w_Z
zSJC|7(+s`%$zjJoEmBF`4QJV5*?Fmv(}h?z=!F)FeSX_+1ba%Q*NQKM(i{&<fgaHx
z#wi7Owp^4fM^H$u+s>%j3K!P8<K+nd>+>x6pinsIP$xQ*EzA`#9$TB|Wp(k~GhU*B
zM_9<;16l8=IH@<|Sq+gG1_WZ|wer!Nb!HlGg+4<e-b@zIAUWKH+82(}UE#28P$%N2
z;mPFOnq}k@qN41MExz&-Tz$+gqWea8pUK%Zcr7N>4%53!uFSE~DFB-q>7qh9fEL5=
zca^S2c=@H@FR3j~iyZVsR7DbaptQrONPS^lBj}?Z%X~&(5ud64V+Y+>gwgU8P*S?D
zRvg&LhR_dJZX1Zsh)0WFfCtIgT~*2D{ou(8)`p!BG}aIo4}EIw!6QJUSF>m1d}FAX
zFt}Y}yf*H@js~i9qqAv{V%WcM>X#ep2f~T(r}IqZ?J*B5&Td7<c6N76BM~{~tmmPw
zMnHM`N<NN*s&@Gd43%8CvFka~7wHg#{PJ-Vo#UB)`50EG3Mw>@d#5x2g}P2?&VW2I
zQONzxTAq#k$WGIw1eq>Y&Ta9fBTJj5D#Ew8m+v<A%auC_D^r9IJ!Cf(0gG`J8%CNA
z3P^<3C6Jy7>cE-qmhdrfO9)PadG~?nMc1uFuCfYDW?^`Q()eS^9UU!wQbqEl;%?R^
z&oP1e@C>WzOX?>@LV^XQk16sZN+Qr!2d9I%THFaS2sxudkFM44<+omA*&h^2&~84@
zN>#{w4^&__Uo3T?%+uuy#0TR<_t&V!-{%d!E9YqSM-Tc{{9yfk>7$Lh(tc1&7Y`F^
zv7pSH+Kh3sw~O1kx_tFQcyG%$8ja5m1q=TjIg2THU$ko$G5n}FkBOeG-4O2~q;XT=
zb6GZLMOv@M+YC2r2&Y&wm(VQvhKBwBya1EHf+sKp+?C1*&ETF0;FNV6ZqbNZvLT7}
z+gbtbv0jxc1JGWqj+Ks&HTKc3sgL9OJ!f|vXOmAt&Kl5hI?P?0uU4^AZA{gR`K1bn
zYWkuagpQgDv(UT_nLjzyi0~nLxP8=#iomYF;Pkz^cnIY1SGlitBPDxE4M9h2!cN3+
zN!~mU7fT!Xe4FBjnG;%Rdc$Es_uo~dLLMEgY>U4>IZOP2BCmQ9CjxH4SmD%tQsRnK
zVt?c9JzVTS0wXy**Se#FJuRvT@n!?>E<{Aipzl*`3kajL_5L8=_zMv{tC!ndZOTvX
zT6#UVK3F2W{oQ2qrm?yf*$Bu#<k(%X#BN0Lt;39uTai_Hooe+!^4hVuN?LEViG-G_
zWqotLkG(v>gJM{j^`183Y7QM>X)&#FFBkLO!lL`*P;!n;eES-}9yZjY4m15M0sr%z
zq@l(Yy9KsPo$8fdS-7LF#2}md)u+j*qqx&QBbkDDx%QZT8TCb`fN??At#6WiOT}#b
z2yDH3muHvo!-0nZIUM}o!-y#|*#+`!@h@-kX?SZN*zm-U7Vg+r-ag3s-IGrEM5smB
z*ifr>4qs#aV2_W4FXBcBrmhOF;jO#4v1an&v%Fn!ube47P@wzb<G06GWN8F=>zc(!
zzF`4~^@7m|_+M|z9Z+%M<_c|n9koMtnp3;YvE4bES9R@8Gb@WvI(sN$@wle}w|NE2
zOvMwt**h{f??z^M9KqSI-%*KUuyZ4!`hn`nv%1(!{xoMwBKqA(aSsStw~~kY#6gO_
z?@JVF<Jd4oPFO5Fa>RLZQZBn+z`!9EZLlFxX(9n%0Jn8v4$%?J_xjntC~rD)Qb3D|
z|I;TMAdr&;U`%T5G(KT3*e1lU;u)vwqP>E`=eIX{OHN!(Yu^$O@Z%Z0r@+b<?rzoz
z@{QS3lJ-;4Mu+YKqNKG#itzL=2$=c*oowX)&&ke}MP)kz1<NvHD&AICVB_q3#BXMw
zkU#0op_ATpMddt)@id@xQf4I+u_00OA3%MzdX8_UG6xZVNj?iThf)SJ7n@uGVN4HX
zlr~=Adw`yF3Ce{VZB3=KwD=m{s5g~qdaV4#qvmdu;oT%$2yZqKI7w!Q$i+u<ppEyA
z#toc)<-B$H#db`RX@jD({K8)Wk9>|qJ4S)F?gG^eGUF)9jY%2b6=5F|GFBK;d4Da1
zYS~}h7yVK&m<F?><9J#32><RBb$ln-Zf+KjwmfFsxm%ntCIS68JYH#U&(&Waqoaw*
z(71C<8ey_&IH#&YR*l&)v3>h(XyFRG=iJOIIozXaEa8<hmwt2I!Ht5?))Awe59tcj
z^>2=u>DkvBO8E~nl?OnoRv&M}cRgA2I?nvGu@69sTkG#H<XVnG=iyF=<?RsP^Q94c
zj~we5ejuPN1Fb|V4({S{>hx<Q-0E^h(yW>s656lMT5Osa<LL@Xe~kC_1}q;RWV!+f
zq|B$_Nl7Wp4#(C`O$A@+Af92~!Ay(0mma)kD#sA*3DnE{z{ctN8mS1K)tg5`T&cM|
zs=!l!ds!VJgw-A8PWTch@`0<JY`+B)K)s?by=oe-)9G<>0*AE0{Kr#O(2>KCVOxCn
zZY=m@i4Iu=)#sUru={JXJKaQHw4I=zx)jQHCj(;F514}3;&JsZ*xijh?YVMLb-ys2
z1D<MV7&j#_!vo)cLFzqOq9_)vA<eui9FM%~HRs(vxY?s=W{k&f)sAbaesJrAX9Hj5
z``;<Rw2FHw?aLTWM6|_pxvAocKC2GAVT2u^L|;C^xLWzihCk2-U4*EuuM`A$^O|rs
z)k0^`+WR*P*;l`R1XGgO-c1U9{BsbFrK;d}f9>b#QEn=HN+h!kXz#IL-7u=tiO{&&
zI#a4hYO(Nj#?TzuLrTGV4Z_X-xU8@~l+VrS#97Ae)g-N`J#m-9Q|Tl}Q+r7y{>NVy
zkM(`ZP#%0_-nGO-cFp%mSv3jvO^{85S^xpydb}7^m7gHps=z7Rc(&ynVd9db8QkJO
z77*a@y5(l>^JH6Q-K%P#llMPPDEr+_m{MWgqx_UZ6$>CagOXjWIyO!LzqOKJj>g|d
zd7BhP2kkL;_wa=<7*_?yrsbEi>11&(`Z*?M2ip8tan+P%MG!@$Tb0ntVEy6e7xsl(
zrqFlq=CbX7D11NAVc>9JpR0n^b3T_kswH8U`u4F3to`B!KoLiSX-OgjNl8w_sY%zZ
z86)WPk+dtH<!z+ccIuVTvD5Ol3)r?5vqR*Px@%e=!pQoi`=o*P(=l@kt@e-rhGZjT
z7j$jLfY9vs2nv8~+0|IVGx|R?m486X6NZL<!P>f3M9crM<t@E1+en_R^GM5$3QywR
z=s}u47m3GUzbMCG+)=y9T!hM=mIr<g`3p92>M*0Kk-+HCDGB**Oz_~wSxHWH3;2dq
zNPye-)`ct~4YstX4w;PK9mjPqq-C!;BwE+4P{2m@w{1V)VKk8#N@xjep7Dy|(U0bz
zA>Kup_MEf|uyHcZ62Xd0i|L#1UmnjLt4_2$+79}~YKJf*Q6T>G;Ro*@P-ODATGr|H
z?g%R8<X_6Mlv^2`A(31(pPIZa%U_hE-Dp_jOa3hGI#rr)(<&hQ&R=C2$A!kD$+nTz
z_dD5;a~VNDU)fUfTAs3a67B}oSWXCEoR0)SK2|#`^=79x$8hKiZ}!KM6xWqIYH#JT
zaOxsZ$MX;(sQKW}$9N(e&(X(ViVKwCV2Z=BXexE1qt<4wd@kD?PDv!E7)`{~fab;?
zRFj>Xp#ZWytUmw&u<BEv5Z`alTgAA&`z>;y5)SR-E3Av#u96;Na#8OSF-Z)nt#q5$
zH(qPJNf_zZrNUyR*MrVaz#abz6y-6TQTe9?d*TLO(Fp}i=|WVdyTcnD-exBkzUAnz
zCVtS5R6vKK;)-vgP;uM&s`TEI-pgZ9)z~~aZQ$RZfQ}Ef*@+aL-^L0$?xfRwKF)ph
zjL)HtMIQJb>>SnSKwt#yg47{-!pa$<IX|Ov4N4KUZ>-MV*W1=;J*qw)+}WoXHWWl7
zoIS8rg<fBAZm&ov{)H^WGNELL&Z0KH9tgd;NpW%C9Fs!fJ57vF-2ydrFOfMK>*6Ia
z4CGr9>-u0ILC5N;%-1zTp-FOd<F_Mlm*LId!|2RoUHxULp#H5N%ucVU-#R{x-N-XU
zQc`rZs+PL)g(nJP>`ts~$46k9n3}f-egdrn{ByxXCQ)*&FQH7v>rkpHU6&iqL}6E!
z%fmJ|gCAIlAj{<kNU{Bd7ly1*I$`?<PWdC9<JT*z{aX+kL@iF>OsPSLL7KSVfvl@$
za?2PNrnri-j8!Sq{qYEE0Ym%pc4h;%FK!n<uVa7k>1ssH_+$MPfsV~p@n~Z#Wkk`L
zQMhI1&fyPL-XtuMaUDBDsPsKuJ~62J|3-Qd{Ek!5{8(V|+<AYAFfKd2{$#1%oGvdC
z`S5J~WmEqO!>k><tf=(t4(CU2BUNYZBJ~eMiBqs^YMK;!y35bCM46vpG42d1{Lmhf
zaKDpW1$1UdtcSXIPB-|09pxSkG3sVghAk3$6|TgxzhRtR^zZr~k0MdI5E*p;6jBb|
zf3DUC60;KD-vJdWP3DL$WsF>uJJ*6khf%GL6kDO&-G{pMY*3{PC@_blsVT#Z&@3{%
zkok6W1+KVd{mOmPDjDs<wt(n*B))MwcU}k4EHc2mGH+P<3N#}bvip&xYHy~D-wwvD
zg}0@zmGEqXKz2~S{XJi_BZ_d=OboxlVMBPHw=^u4DRQm2k@ZvN$4?oiuPs;qy?Q*M
z>F4(YfO!`!&CXtV^a{(tlR8aL62Ikpn`pJ4hJuq-#kGgUhbLDV5Z!TNm1LgBN!4bq
zqe>V}<<oZlm|l-&QOm1Sh-Z`nlckafm*WtbYI0p)I&Q~rjI;ZC@9dz7zHqZ;)ddxG
zYmN4T!W?=L$5I)LWG))xkF^?n2TQONX`jNE_t$vxhqI5HeNH7VaoHqi{be4mcEeJ%
zD&4UeU|F^AS3Q>Z8ebb!H7G2hMK72rXDkjXbm3`<ZlhaB3mNhiCOY5H@_cVwym|Q(
z{!z!ZMeNVa+EY~v+O8Dk%asr3XisPZ5q7&QEi0#Q2b5R0i!}ZuTAD<oP#4UT*H(+X
z1azW+#gl^ga>>!#=qye99=kI{Os=QwhVab-Ej9bz+pvQ<Zur|kL##liZo<x!C<MJx
z58dK(8}r6<^76HPQt>%tSB(Hi-h8YtRRUq_e*u6!3UzE@+XZ>FDIvEu4*y<lyCF1D
zAJ3a3jz-K8n!XG2alxz!>=N~tS25W?IdmU8#WQBKQ(EBuOY2TvOUEmQaLuCvcnY^p
zG3<?|ComOy&PVfs&>0F5LhpHb^bM~b9oPIGS*XwKHR*c1l*75#y7-xdQEvzsskQb`
zmiiz;2f&y8&bhLL=l2j+qs0fj``gsdrWdl}X|mWUYifRdi>E({3GA{PnR5}7Q%q!A
zIw5>0t|5p`dqba7|GN^4O_$%|yT15wRo{=*N~|CHq<G=e9J)O*>2o^C^_G!cPGq_m
z6}G~4Uw?(vk>Lp|{J!b26`x04>J;bgpp$Nff~0Q<y9Pg0+rU8XjU2&{ByNj6d1w=<
z!SAiGgj1x7b@cNbbo-0q0}2xJ^=edxHi`miVD5Y{HnzX@y7_xo8TaL)hm%QPQy1-s
z<<V?534ckPNqH<jW`_Y+e!*{Sg_R`iS*e+ACubXfQRg!q7rU7XYHl<84950_*^7q{
zRvLY%dZLg);DkY$#cxse`_oE*2Rz&fHczOiUA2TNX98X=?U|W0ikA4k{xJxld1WJm
zX1Pwzg=}4;U?D0JDp-#qc0rah)1`X)|DJArxpYXH4%Gh`+I;13S<-d-TC+0L>LHN1
z33EC9om(NW%W~1LCrtDuQ=W+;Z-J=VQjP3wYFY+rFs!kAI71}B66E_;8x+ww1t}MF
z)>*r@ddB5T=J>Zir--}kF9@*r$S4{yWO4$l2Vh%-5@F>v2e@m*|E{gt)!bXCGg~D;
zJ#DnnoT=VVpd0*0q+A5&r3q8S`yWrPXF)ym+q*g=_y%<jg^c=@`DZs^XwHYUy!d;0
zwc#m3Wa`#)Rn@}0ZbXJ=eaYAxP}(R}({$Ilp}&Dc(d1ax9wl%SEox|QseBJwEV5|}
z^n0oKYIrU#t#;p6KV(o_l#aR8WPqr~Hy2PCtpaF~URd6h%WW=HF8woIg(UeOGwtuQ
zg@V4_9Gz49Jvl0$w(;-8eWZ(Us~1@?5Gr22gaA5`+c{8d-OTRSjl!-M8Tr?$C@OMQ
z-19%k{Hnfz|Cy;Qpdr4@g&YyP{sJ^PTg61^)TJDWy{V$&XEIP?RoMs@aLT)&F=!Q3
z>h5`gkZT*~B)>y&F3P?Aa+THp-P0sjvbZV{&0>hBdV1BDY^&J|LINseoVf8~T^1yl
zMLD<Q|E@~%?y9;x6PaiLM~^3koXuMx4u+xg2IeU<kSNYz!rw<Ah`;x*<1*3I<4=Ry
zb@v<3#Y&Q;{=2D81xbcX@%!ZWjgWDMQ98umaNii7R1pygB~vCG7Ri9flFU^yWYQd6
zY`-q>iI;UtUoV2cHF=!BN}lmrs!Guc#gc<+L!UOD|8*R#bW2#)5{4vgfwA$)f1eEv
zkVa%#r`TyVJC>H(RX*veIJv>*SZKQ%_R^~Sl6zRsnHMfKL~h-5DA#t&rdCk0Wjd4X
zH9a_c>2<aaEe;+lZK5|)_dm=x2=H1PA_BWpD=6O3YMmcamMk`5T+<HaTP&ut3}pzd
zIPxnOeJ(ti$}W7ZmKCm<blF_JMX&>Fp79dh*T(ASICKme5dPI?CNayp_motRO$)&h
z$R7Uw_nCKOq*63m#ajJMlQ!codDAmpP%UQ1)k?;F%klZi>Rp!&gv(-!N2jC;u&8Iq
z^{R}*!6`<?vB7Jbzq?g)0K8C@mGxj0nhl9t_x}aFI9gapRJ_|;BrE$ajygZGICCA>
zSh()bS(j7vOLM!D*$VtQ+TOAv*^BbeU6#B?O*fj$_u!Po(^hW>W7Ca@i7(A?P_&d-
zg6KWNd<AmO)y-2AL7zRr%Oe!F<GW7ON(_(5eDTMs&lH28%C4%*Vp)fD$o)lQ2`$2^
zpOP4oz{Vo`=->O3hpVPE)Slzq^r9YvU&3$Qf965~z+3xE@KWQ;)ovZ(g8gYmSi#3e
z<50tjQ~@%WqD${E1~ZIus&jiI#Dm28+6S2o+qsZ64{557AO6F$mHuI@O=afM=}-&U
z29m%N$f{AeQ<>4PqR}06j@H`iWoW($-2Xny@@1jh)?#LpJ!S9~``n}}9{k*#xS3^p
zI8{2r+<N`GXvAo-#38i%pfIMQ1XOsRL%(Iy<*H6S(!N~3j0k{=w$~F*Q|Z;Ic%{F3
z%Z{XRiROv`OJ`uR2@Qu9Vwmlx&L-;_K|gd9#{)mUreG=8gRy=DlW{{;gkIG1OmDJu
zW!7{iCeNa;CFvWohE7eknVx|TKO!lOnmC@tf$Nj}V6X6VDL)h`l65~<9)LDV`;X{K
z=`b(KYhF?7U0;;@cR~h&Yb};)hFc#+ZTp6V#uXQrJwUQf{h(CNOh?7lx8DG_1)!Cb
zNP-7mFaNB-7>H?7TJ8t$Qz4>P>X`3$iXR2&Ll54Mtuei1TATW7`}q??*R3@-u;f?+
zn>{F6!X6mWq^3UdgcapWvv2RADt2)PM!#(DUNBBz(Ejz;#($H!Es>JynzryF4;22Q
zai)AlqVdHR^|<VSN28-%nbYo#o%ldf`*bz~J=->s0*i(9oQpTPYX0RdY-&KAYCUQN
zT~V8K0zECzYpohMRs5Fb$JM#MS{V6)_(R+>prC5785rR?tE8UiW^;C>PI%Ub*@Yyw
zEs?tHivoT`QX{8=KX+v*NHy%Xt3TVORNzOwAzs*g)>Gm-$8<gyHk_;7Zl1t24p9!R
z;PJGbjIxXJ9guc8H9|A}_&Ed)chh76%b?|jia(Zkj6gkKGKe?e^P&5Tj$!-gEZ<sH
zLB#fRXD<l7aL>im<~Wec@HC|HrY4|g{PrMV%~(l@$Hb5OM&Lkrb2^rk5IuF#dHIgd
z_Are%>JwOzhHl^R=!uGWm`w3e=@_ogGh(8j^b4_m?RTToZvqPPhwJa*5E@JyHMhQJ
zcYBb)sdFD~a6L1wKb5Thd2R|Jd4a1{M=vB(gXP3nP+Y?sY88liLo{F1JW&i$gs|O$
z&M1D%V|2K%w)jEOw+pYlW-38Hgq5tKiiXm}9tC(2)=m8|tibY43;U&4rk+POzLYQ=
z!!f_aVVp}H&#4y)^Z^yAt+&uEkglp8D|5yp%1FzNSj-#1RsAkSxipR!8?z(yjYr8J
z?1A4Dl%M^#?x1?bTrYFZ+e6@d<0i*UX$QW>QMqlb$vu4bRN#%>X3sO&+`SZEx+wS)
zC7qfHMNl5^Bthw8tO+QF1bS~d_dO8D?7N(FrC?`-rVa^FvNu9gQVMMpRnLXqXD(PN
zppXqup*U$SZZ;Z)K8*Pa+tqMG_b*g<6F#u6r2VTThZETPc>P%T@#<|ciG|9Nv-Qeg
zjO@J57aETqRCRBRdSnby$s1E=!`s<pECRXTG7__BOaejyVQCfy731$O%*Nk0lREM<
z`q9atfV^`=<CyZf=HY_@kKZGkoVNS<2TrD3wqu(2A5~hW&73ThL+3V~ccy8VJl)jT
z>g7Uc;Q+AJMLx-uH#~B4QmvU`rN3RNMYAzil<PGak4e6=_&~+Jn{zmD#X6m>yI|)I
zmQblVDqy>}Pt@Oz#63lXvEKpV#8zYevn_}g7j!y8$D~JNAomM1W-v@{LLi03YQ(SN
zg(59$qgKV{xsZKHI>Qda`{+rE{T#t;+wi}-t&q}v{CF>kd)}Zg!Rlu>+%oJLab1Ap
zzv`XgUDkrv!2RkKOV~=csWjvNs&_V!@aqTyqhhGUqJ;s>o3*W}`>%B0R{dCsARA5!
zUOsLMG9M6++CA5Nso!*S8^2Zh9LWj}<h|CPxzXfA%i}SF0IH)D2zed?j1Ik(6SK|V
zzB4e?)-6?HC5ElfI{ee*YxJ|D#WuIi?4L5l^*Mjk`mAB7%Qc|;>9>GbR?*-+^8>ii
zCMqLhKNRIf6ZZ!@#|z~izmx0g?N7O1)E6oqKIQNO3osoYz}#9mKbM5$$VJX4*IUeB
z_=p{qYAyc0!ZAV(Ue_U_NFfAa8?kN}x{y&;dNw2>6<jD!CDCqT7pT3NGphzfCRS)2
zuWwFtP##+CYEyMlgY8hqZijQvA&1ir8Sh#Pme2&Yqu3IhI8eu0K!~mFG98>&r*%U9
z2f<xlIn(-%AODr-;*)>b$o9@`Ac^B<lX{OU;lOhf95nfuKPfRSKOD2>aF#~M@$cp1
zdfzG7@^kNhKzBVlbK{Gi;-oYpLhyyxI1Dvq-5!G?&1AsDN3x=~iP+Q0z9KSocD``N
zqT;3l)p}=Ocf^zU4XVY2b=gLb1p6U**NnoGXuf^SWLIUhyjsgq;Jzn%Zwtiyd{;q2
zixo1Il75%bpPoX2uLGSY3N~Hl@zzFB%U12(-@jF)dUR?#VRip7lh5<sCI-Vdcb$n9
zF?-uEg5$K;&v%-peK==qAS*tt-1K2wtqZ3JsGepvR51y2;lWY?f>p5M%1_A-)-=Us
zHgC}-8%FaajM*fAelMZ?Gp!oA;)gMV5x<kloSsvuAaeVwBmFSir0OqHx16WF(Odyr
zD-aqKKBpLnE+U!lPxKGzr%_Xl*{NBJbq=}*3$2ep!|8sGBMIl)8WH1s4tsx?b(`Iq
zpb;FcO|N4*{|kPHc5eG%vG=1$AmcP23H-LXk<XE7HUIH;p>^9&oKfq(5yW|_Ib!+#
z+W%TY!ioP{LeD4>f5gOplmNg9?K6c_qVlIlIPS8IYjpX|c@ip4>=L=(OJ{*FX8h8d
zi071GD^Vso54n;>%hN5)!?JIX#R-tyz+are$30DVw(R!#RR~BuMm8VaF+ZyyFi3?e
zN|KJDe2xQj#Y)Rc2Imeez6Qwu)rAzwXulO;%g7~Fnm8e2+_?mVvdQA5N3_f|zslK#
za{;4i&9DB-_z@=WNKZo0iDkph)qxy<HEnF?1@`^e_v>a+$oF66PL}xR2ue!?GrlgI
zm6GisKlRged*TGjoDYL#O_ugt>Lf3y0MES+)a<(61^4up?;PN}tV!LsFKL`DCrDG)
z1zxz0zn?78l%{x-uQP0pHSL~-BMX5Az0f9jz}m4{`GlMe(|jiY3!q2FD)G*UD{?g~
zKDRQ^_HCfAIe^dJuCD`57OJBEXC1zD`LHx9?0eDQPFQbI+kd?_AN54HO11WPR2-Px
zrU9X8b)C^RcG1d@WCa?;QK_qK9%S*olH7{jxe2CIodA{w)C%9AK@)8h8C!ORso~TP
z2)lbEYPx9!>WR=?c85P9Ce!}^O6d!P+tOW6&<<VZ{{soBHz)^xddF{Ny8@AoJD~X&
z)B#|yl>~+_z@N^7o!j_-mR32sR-lWKSDrr?A8}WD5n$=YO-y9jsTMO|9xYpMsAf50
zD<+9+b1{7&L>}obRazWM>81ck<IQtd|HBpTtWu;0yW{py?)#%vg8(i!M9UYC30Y}Z
z3K4REPu3N%>C#nNSeSf$t7UZ8w13f*fvHY?s(63jyY<#u#>BadK_u$N`7mG$AKDfD
zBVepR`z3VqeNH_Hf(u;6-2C=n8VNv~vPTBhciaUN@cD)Qxo)y7QxE#jg*@MNP$$|S
zD-hqSWfhAw#*TZtpceti`B$0&z%3x<h7DoUE3u^9CU$yJ1!gSz<xe->(*rCdk`<wO
zQBDnh$A?rYrE|Q4g*LHtKY_z%wLSDY%{aHXmM2UVMG2U(hxU*#rcc*Ni|hhym^3>L
z_7>_6!^lnmpWREgZ?x?EMPimJ>l^azKXMZYadBh?#So~iemiqER>f#{K12Oe|36xj
z#ez8y%U>Fx`<EI98rvOx1E8i#;}q?o812)_K!k@}QiUePnhAx2&sshdXys;SbGcbA
zkyc@94HwqNr-`FN$zZyIHOC?~oXPbXb!DjGeVR%x-<;gmUuFhZ`@+AV;yw?3E{Gn4
zVQ{K@P=pXsSM9ziEK#8r`Pz1T*=cSPlI^?U1#-Do9W>*?xupJv4dQ%PE_u8$RKN0h
zQE!~O&)A?_k;2yYRru`_6EUg{dXw?g@9t&uP6k`TxPfle^L7ehhqaZ;q~R!xE^LJ~
zjzF*NrhSxmB<+tAA;ld_8q=<PTA8^g*GO7k%#Ne6T^i!$%I(*6M+jE!=RCnZuy69|
zi??;$R8926KW`H5(0Q(#2?Jcy>Lx>e4xtNB(9lh9JMw?`ka75{p*?OOVRUawN6^_`
zJa1V0J5XZF8xDbKU$))ci9DtJh6pDafS<}a&o}yb1OmD-@W=lb?BtZ23+|6x&!otx
z-~789(A2?pedbo!HhrFng2Ij6@uPR!iEX|ERp6a}3?pgHL!$7%|MLPomBMJhTSvvQ
zh<Po%fAfpS-{&Egu3T=u^dXD;&B@D0Cc|z{Cx(}}qW<ys{`%2kRtWk&re#GXO6zZP
zveS8Gzb5PARIO2%LJ=%#9M?EL;9qci0x+|wmQGxo0h>Jjj5O!FvH1?`#~a^PD53xv
z0paY>Z@jo_ApHj1E$VzUhnME*s=A1}EM2geDj;1xLh%<(78qMIF}G07cuz?xCp|QM
zV|%J;a4muxC~&y+4VU)9o94BKR&J;)<m)<qtbFh#+bfH^3Jh2Fvn)|>T@P~1F~jcJ
z&fvt7g@`?Hcu74%BW}M}_u?_`<)I|9K$XZvP9;682}Z?g1-_66Gy~|0D==4_QP*jF
zL`|;dlR738l<6zk3{V<Ve*g-FEr9^ZdgZ1J+@KCTLq|Mp2V|)<`$F8}jy0U0y*kSc
zvpCn$zio39cr~cyFF$3)e6+Lq9eQfD6slF};3iSXx(i~KrM2kFT>6*J=!I|tHEpiR
zqR2caZFztKBD!mN0V6P95<+`6?|r_0YXOuIkop06bo5noO?S+7H5;8_DSG!!m6_KY
zdXMSu|ELa0h35>!)OTgOLtm`VK`-}e`EdRZi=(W)W1GRTt?K0HLYCcFCZp@o>~3aH
ztO{vQFZ0Xi?MB-#!roUEyTda_KD9Yw_a3QjR~a4RINPi}TcqamV6d9Hx_#0Fz7lKE
zDeh|}{XUpf;kf@$G_e!*1#VQ|rp4{{y>$PB6VqB_QMw!dOz8;*3Z+)%x55fVwUStl
z=Y6taoa1@|^x%4p&RyfO<8Sbzh?eGabdT*qx8BRl&57)^O2((PgIzrEm&Cm_9lW$h
z56LI!0Hs#siSKv0J>Ei^`8w+}vN~JmTiWM&V7HnuyY0%T|DiCKmR1R74Xv(Fk-7tk
zec=2V`jciHFKa(N1SL9Gz8g&+Ned}2HkCJxH@U~gs1iA7p|imCdLRGmNXSL^ugb`o
z<7FsXni88X;b8gtCFM-%>gZB09%!R0xGsFUt-!dUX}CEb_YqZy8Q67Ham1t8ZGE!Q
zYs8iLZ*$(fiI+yKA|2b_lLzzv2}<<}LQig4*^w$>Z_Mj7lsf&z(|W@BI|N}&#a!mT
zJ1%Z9QNwY0ycE>HeEzAm?o3fb1cGR<(k*oFQ;o0t`V^u0b@aT@cJv6;iey#!JkM(v
zc9>GXP{gKP|4b%~6!t(h4E9EahSKM4r?%TLRBR~(r9m{09JrnV#THH+^=7S{8rP~e
z`0SJ65YPmWm5LO-eCBtDHH@ZCREhC+RDe7@lyrk|(eMUx@O^Cm(wuRCZq775_blH4
z#6coMM*4-5+64Ay6({kZR8I(&kOOuK_tfSW-Bx_GQY(57$rD<eFS^IC2W+^jw+AB`
z_v76cJr<Fr&q@q@Ij6Y=UEfebQK7mfZq`>EZD<XClNHttvq+gKovUGedrd1bU3{jf
zj2dLi;Z<pGDqpn<`J_2!uu*pckBzNrzH*TIg68w%P7l(7MyG8Kv4d&c0WvnZGSSA-
z0&VFiTgDyl{b_c+##>I5@CB3awFA=^+<_FDWr_0kR@E98^NB=XE{lairO>pFDnUWd
zoo9-aZ~G*tGuJRrtrU8ex<hdbKXt)Yz!LfKeRNcxi}eXj%>P(UrW_kzcWjFA(CK0U
zjHjuyl-RlLz}#7U48M|<v(4UHn&xJ%%e{HBux&<hm0!z$^?RauG-=DVo=kg()vvhE
zWi9{Ca&T{ji5M&dO9hSKTy^|(cxh8~NedU6Z<)~Nnd%u?@Yk(Bp506tU;V+QpA%_0
zZS>_K(cXVib8bs+2>^RketZ-kfI7!(dx`e$Vy5Y`)gHyBBTyQEgdTSAn6hL_<?hjn
zM7y=82$XHCi<4Iz*Qdq1s&*^s1}3|J9=;bsXx?8_n-?s&Dqlv$F};q+rd<2o7Es5c
z_E$wVs6Uc!RJeWyAmh@~WkDnM(<$fW;|rt5o|3JAV1cl$e@bY2M00*^*o&(@67NM+
z&TAcUb3C$IhgmqYzGWp?ffnF(&lLjN?ZR~Kd;e67;?Ts7_Yxo==~xdptE>y7dmegz
zcrW}?D^8-K77FN7VcTr7&?6*!vwqyq&xNXM)eaewuI5dwPYmPrJH%}e?HXI(V^j<~
zW;TAj)Qo&OloxsP@FmWQ?(Nmj{?U10zux}Fh%{t=^8$Gx%?qAbEESt6Gmy?*kE6j@
zancx;?K78Wp{Obyu7pOe1%<-cM7(p~&+m+Ze6qBHv0PUGK4_Zlk@v=&Ki~OtMg2HH
z{*oTI5?QEmz8<%@*1-SyS{<WMEkF3zhh$;bBF2w)ZPwl5<fzK;vDM%A`HIZ1b>~7&
z*$@5oQ35asykUfipO1m&dOfhKU1MNc9F)i_AoDR}gu4mo_jv9(>c}Bv1I$k)%&sEa
zL|!<8r#;#PQKG3W7SCOJl=b~|V4@I)7cg1x+vjc6=SczZ?jfCxiBGY70{*l#&K||g
z8tkAi`+E_tV>?%;ua%lm+x>ildY7@S2h{+%*T}oeRuzN;`zKw>?;eszqT&ot`KsM*
z(>ahWR<4YF+`F!@-`uOw)_!l3tHw^1JOn*U7d>k8=u1z$e$P|WQiqwx$YMXmRfUbr
zWoY|Jxn8@F+h1xcQQe8NwU*j<&>0FEFZUIPe1L8j!TgtFz{AkC#ZccV!o9m3!<o`(
zb72?qSF4g&s8}{KwQ;P?Nrl%M<{J9D;>$WbQ&(g_k6n9ov(s1GT(h_#<!%T!?9EoR
z1o7SGHfHB*VTJ7QxwjWD3bSw-yD<c;vOZK$?``2H==ygEfR`@>O9&`<410T@7u=}Q
zly@fRclk8=S}ed=39HNoLT46QBdbUUv`{zYFCj+lCD^l7zQtPv%WgN$(tyso)E`gZ
z-$HTD)i7fiB3vcyHs12#wN`^fXkB*CC?H)SDmk}U<9fb*@AMI4s-K`rtMnc63@i9&
zbs!xnEGqSp|JVfZ`Lj(%#hR|mEKfaJ9<*s^q;fB)Bf)=t0#I*p1Y4dq79~IpeZ8-t
zcst`wtSC70Q3#81{)~=*bg3twk9_%|5(ESxZ$3tNkbfa>OkJ=6F)X=;xw6{>L;F6Y
z#hyNGZwezP4Gc#!MzR$zdIOIQgAea({qr%5*3Yh8JDI<^%@NZQG}n1(_{eO;63=_u
z<CHWZ%)Z`k>5l+@Tla5+u?CL`uIhl6ch27RkCrWFC|)o<4GRZvjbrajm9if#DjSUc
z;BhhT8IhXWbNL}0arPN4|Lj2A5vRBwm994xsP3?ov&UjNARLN^^<Ud7-#0}GgwrxA
z|H*LMbk@Ic+QUWOg%gukW9jX77A8O%b0|}bQ&#*YvlTY_ou7jlBaLRE_m-!^MWP7f
zA*PSsi_N1m6~MPuNOD}ev#&QmTk~nZOUEF99q82NSV>p_PXsybHYm3~8wB&e)4yQ@
zb{tdy_$iI!Ht)0Qn?8Myl4`JS!xutWkCcl`VstMp(|wy+wkS`3@*!sNPBkr#OvWh1
zDqCs!e!WuK0dG7%IdAi6Xt2c}&sUI>V7U{@WfGZXU^vmhBI{GPIXpIKans9L?I1(p
z$vcXn6UR3aa4krT_s@~z@lINPTyWGldWlVY+V{X(v#jf9Lt(sMda-`*lip%|DF3o=
zeZa!g$#J8bnR%0|;kR`>-uleXo1*}Ez%R=|y3%xsj9^EI_^h^|S)x9i)%++GZgcSQ
zr%zc)w!?=L9p@jb=T%Ars=o|fnf~~a*JMYEevY{qITWskvB+Yy#QgQ#N0c(p=0nBb
z0%C3O@LLgG|3XepTMN7g=EE^~ga$r%K*t{35k-1A9}-W>&txNeT;{{Ze|1smpSsOP
z_pCSa?<4UaQEUNf@Qz>1SDE4&rp{?5B*BUIgtmKB<;jM^3aVsUh;E_ivMk9-o;#<(
zaJrb~0QYK{QIqr4bItUS(M=eCJU#f>ZKb1bXx|=nV5tX1W%Qsn8{=PU(ryl)6O;LF
zyQep3$^?9t93}t=a%v6`0@v+`A>YnbL(ac_uIlZ#M<IW*eRIr;EK({q9vz4!dZ+qP
zz%6VPKZ~mes(p)-7`+p2qncVNcR`Ffcyef#XQ=%7C^3KrAaRK%zqso^T@Du7WH3uW
z&8nnE_!@RyY9p_`1YBnTI#FG5P3iq8ptU139Tn#y*~Ql<zpK$!FZJojrMEP)vu&3p
z<KsPTW&wgMXx=lJhkO{iY}fAR`v?JKECKo(Azm@JOWvkha4^ln;xSDuTLfdeFIg?f
zCNSPscnw8RmLc=iYReArSP6ctvdQrO4PsI@T))KzhT;Vp>~~`h-Eab@pjyv}H8Lz?
z-pv`fV@UAl)ABQ<J#JC1PCvxLoye*yasWIHw-p{D%DU9n^x(FZ*Pz1G5fRHYk2FD7
z3@_KC_PGi3)8n|}-WYcLhve*m`SRk}c*?=5mJ<!^1~#8Z?9C6FOkOuzx!KHpoyZ@i
z*KcwL%t7Aq=gtR>BkBA-j{Fz+oHKlX>=r&Y(Uvrw1%2QtrdYpb%L$`xJi<;KVl8<&
zl+K5#(*iFs!^}54#PdcTst7`MbsXhhskJs7O-*WlnleCs+-WBUXn^964WI8JG_#DD
zT5Eqnaw#07MKb^m-E1ZEVICw`$X6OLteuokzA6P2@_Em_=TYb7W<LoXfETO2(gvZP
z4Qp+7TOZsdX>dRabDQ;t<I)ZSjwZ*fO&-%b3UbeFk6~=-&eHUE=Vg9C0EDIs_obZC
zR-O`vTQg7xP_;mZiBODXxWsrfsodl}&2!H$m9#_`PcB49!2RGGmcODOr(!b2Z{iVi
z3jO^1cuA_JU8FZZ>U<m7s=g4EM(OZYfBuHo<_#0h^QrEX+;2{Z_E^j;fJocCmerWK
z`wdxNf?iBUV2P4sLUQLwjlbQ6*w6tLZ#%$dNP@osU3eTv9gz-GDuhq^?vKDPcuAOS
zsB#V%OC@;};4a?lgA_K`FwLi|TErWF2fHR^!f0>+S`PtiHP-UUySKT|CS=1Trz&rO
zht*>}9!s9(To53c<`d&5j0HSKA~`1JU=J}}SSTRChCfy>MVA?ry_SF4m(#b({8<;n
z3ndr?Kg2y0(WWCOQCC_pcq!jxbOgMT$1Y0_6-KgtsJK@+e1mr&@YN+@(MN=4@`k`5
zfEMMQba87jhoQ-<z#j*$HA!x8)C=<OxWvrlSKcB}`(19@GK0>w0~{b~>jf}7_IR*Q
zX#EmmU9rlie&Gg5?S5p%>at=ml)&&d8vpb9?uV3{VRY4};~AvWMgKp%ePvV@O4l|e
z0!m0IDM)upOG~G8ceiwhASm4+-Q6jTbazODba&S`x95G{FMph0-&(Bu$k7EeJFmI+
z-ZNU1I!=>i@|w}V6!L4~;%t5gck~R;b20roUrk6bPcxmj_$dB&9n_hn+$d~=pg26<
znGSvkXqoG55x|lF3%n12v`v~>@1;AnfdxXo<$N;N2gY^r9^7DquQ=iFyoIV#_WkS)
z!`xq)UK;<EX{z{3gs05!hJ;_oGcI3Y7e)K{A{>7e$1uR&ys;!$Y$U;uSY+cK#yNUl
z@C~q*rZ7H&HScWys{=v61s5X~XNt!>kBvtpTd`xI^}LMu^mZ-1!yoE_M*5{$0>lQS
zfemE*wSk1cHgNfm4G7qPZ_mnrs1xOE{;>h+YiG^kUy|2n*NF4{0LCnDg6uOgDTcly
zhu4QY`4!HCr0os)vddSygYDmrt<c8vwJW$-L4W!LrSJ$O*d7j!sfrhk)9B~^A(=DY
z!|xU*gOzL)t470xKomSio0-B3I5>l%c*9#2w@5Y-zVosWz2_y>pi+gUw$`_CZ}B1N
zx-ha1a(vVIUfH4#BilTV{rvHMKsgOsuWK7q#gJc>sW75gERc(INF+zRO%OOvr2V^(
z;hOB&#`b)B-_ExB0s^KaMNoVgv3H`b7dhOhIg5~`a^HPkEV@AT%lM2y4|Mp)NB|~7
z(&tfWdu~`|2=u&447yzG=-`ZytDAp(l8|ip6+d*te$6&22~5u|a=Mi8uaxF0!d?1u
zz?BP+B%+r1AVNMxfduTCD-tCZI43rpPEWdm2i?MW(@hg&;ru|H(YeU|+lntB?m}|y
z7cGvEtLm$)yRQQ(OcpmIC~MNOxMZTv!E+c)XvCK3KzV~J_|~eg(!H^iH_th+LAbKA
zfPC<ISLb<epw^6<b=<H!SYqYpCVRt@VJ}=tKw5MBEV9ZEn;oKaf4grp!nWh8gGW4(
zS8@5@6PUwd`%-5U$rVXiC3D-$urQ+<js#rm{9%nQi`Q*o+!3C`e)!l!UJNTYRVckf
zahfsC@+>qXnNa=SbsK6|v@cR*E_RNAO>qBOZO$=W?le~?Y-P){XWya>LU!kta~6Fi
zg1%LGXIhOQ2i%sKWTI8Rn@ZDsto3v;3Ut1hbidw31K|ioG)rRj-a>J}H0#Zl&T@Ug
zI3!XYT^hak3hDsL2-H62FA<(YF~B8`XP`in2&V@rNho)Lau+L}Ywhz&y|WhS#J(9x
zMxBInVyh4@uJCU*p#Gk#S|grDkG$lT10$cqj3XpKSi^DO<26~L*xsYuqEx2vgcb7R
z!$_S7^-PQVOh{jF?dt8&JX@b}RsG`cw^MnA3s_w^-++C>;`kN*1|}iz!~{P6<p%Ja
zpjS2OYz+2>bv|GJW=gKNg}%ybMMd4}58X<m`noV%MN_-E*yvnge)jsl+L__D+WSR;
ze2$&z-I|U2Nk^&HPuIQINFVMQ&6SFMq;Qxi<Bl{>w)>*5^{%Xwxtvj+v|4@fXDe5C
z^ux0hEA+(<ChNv!=yjUS$36|8JY3DOuDcN7oo)_(50d2zeO_t!iMrdW`N?{rZ8OdL
z*K(fB>OS8Sk;dkr%Vpmm%7;!2#vf7$?}<G2&&|NJ=Zn1I)Q+0HnMfWD<rrFZOhB}X
zCQcS$?J>B~tDiM@DO=&PR@Y$gO0HqhHpIK0iYt26R_p%|Dd_bn|3sS+`qm-8W>unq
zH2pcS^&Np(RZn0>$<PrKg-Wp|FES?AQ1K+i&DZ#Kw~l%$R`b>^*`S8IyFP9Z=N^;u
zKT$Uw42*qc2bQyHrK6IS<&EXWmIwJz5HbJ&N$!2=%i-4Uno#A$&yQ0<#ZGpy!>xK4
zXuR&LFuaKzh*hmx(1_>t)U4DoJw9Pa>6(2})_s!vmqldDy1SWOar}8P-p=>BFZiu*
zZ%oedd11J(o(_qGV2b^+xU;}0r)TAEJL|H+@5zGeiz`_Ad7dZ=)FqpFcpFx)E_6dB
zc~a>!6NTKBq-!|MR#z5b48&YzIt_S2C)4mPiCB5!@r*FWT|#!0;2E!Q8kI6NujurP
zltyQ|rw7Bx_Uk`>+S|7~a;@?r3>tNB)1;F9buN#b3+DaQsxs}*jJL-cumEn~QhxFb
zL^U{V7ru78sr%`&fz%&I=^M(DtF|jy-fGqQ$l-mGS@JM1ouqn>lGE;EOQ|;CthFO|
z_xCbVN|0_1F(tS2M9+I2{q)$bsxA{)72K-b3W~ju$|=$irF0r#;~$$-7lsXS(Px^~
zz0;mm2#7)Aiu`6~CFu%32z%>VXy;{uBb$&9V{=nbTSX4)j{S8r^RsqLf@Qc>J#tE>
zbo_>$7N(ts&HCdWuV*AVV1`^SloT0s-p*DUcBl2og8Kfl-q@9e9$OM!HJR<rry2U~
z$4xx8+f$A9OM--IU1(Bl*SleY=L4#+?S!73uhOIvU(WLEmr6aY8#F1`g{cf^|8zhc
zT0Z)E!R_S_=ecY#f%|Er|D9xR2*>%=GWO$?L+{VxjV@{>#=R=p&rhCL^|5qo*DilZ
zU#5KMVh-r8F;{m1SHQwmN;(Y;>%8LjY@kb^gWgnTX!Rd!=HqXuHf!Fc#qu}Gdq=1S
zQ{090x-)%SCSR!{6U<xpi4G?~Bic!hsy&i(yO(VIsik`h`?E5*UMa2R+NlE`Y!t<&
z<vc1U++yabV_L^quYJL_mZ-TmX0iQ+Xcw{fQd2Fj^+MD4E{ioLvtNRij~j0Snbct0
zY1pj=qZ8gz?bF73r}Ck8y?7(v*^UqkE|2(vRXyR0QsZPv^#iV&9AwiHL_ArqJUv8L
z`J67q1iia2W$HiLU3M!1L-J@@+e=|7$`5;l`bec1mz%!^b~h6`9tF$Am6HJ{vXmb1
z6@~&%^h(z-@7;JS5?#^+_;4>MpnITUHN%yCy`{4@`_Uql<H=lFRqLi@u=O1wTHIn9
z0X&M}4|Fm{?@rtG{zqM;M08cpk{<U6hw*9jD?P%2QVlALx(A;h1958dR8KZt5|W8V
zcXmd1Y)#w_*txXohKR4(@|BTq?6$i5s!W(1PtYY3O)MfGQ9T+L3|17zg=Rb(v&c#u
zXVGQ#XMb}@HW=LzLoWuE)pZ{FJ-70<)-HS7a%);XU$k)`;K%fkloPkyia)xHzVAp+
ztg?&9ZsD3?M>crlfqi&ZKCiq>uUZ9P;^u7%4z`UY;7%O=fb$)Nb0)iPsq?oN!a=R>
zpfN>eP5ofr;L6tzd#0>Ra?xnZIrxgNEwMzys*;dF4hqj$N@!Z@2dy{Wd+QIi2Xj`4
zVm(jCepWM;_vFy4IB8xX;5w=-(?`+ItEXfGqOg}nYau(Yll&$0_&F45H_}oa@*mc^
zl}UBs0D@%xf^|NVarVtWk{n~H<}#U6$gLWnbWC#BF`ZR}gHJ6ODVIYin)Pw_tC_R@
zp9~sB9mC~FU$I&OO&MAL10a!D{HXC!9%#O%f6)wmREj`GTR+^<c{U4$>pXI!V$cSU
z1?pMp0iWduW^UNCVcRQ7YRvc8;&gY1zn<}=26H>~E55|%9uA;cd$=+<8YiO~#^SZR
z=SVd@u7sVI8PcxW4<VSyW5-o2+C5H!^Gmau8+><hJeZM|E`BgaUxq!)gg2F2LMB|j
z{jk==8MjhdMBL~ZD0Mx)ny2%6umj_({Go0QYP;JDd`bQ~bx?7yFbS8gg$pP9wqLsc
z`z%S=29c5v+|TKi%-utB6rk0(+9;hw(CLbVP`5udk8T@RJs(9puN9fnM~2(-#s2Bu
zpy>1vkB+Ij(duC8^6C?d$*NyumgQ5NkL~T<xSA8eK&j~szwYnJvf~?-2_o)bov@(x
z<kb$$yiK-t5?^RN5>)|if^9jAp13G+ehUbWPb_EJaK=fA81Z;6df<$x;<5WFhAwhB
z0ZBAp`9HHw;Y)B;RII1rJGhRtf{`C5%Xf5yW9m77Gm-%R8GKo2%W+<Y`31=iFwg>Q
z{1J^H2^qqgF7RyWghJyfe%R9S!|fKQ)7e^%KtUKlQRg&Kmgm2+T<p*Ks`<?A&e`L+
z=Ui)S=Az$-lAW02{iH#--py~0_{Q*@&#g?K<I*#0dT(k;miBh!)2>82_0MOXs_v(+
z4p8Er>S^qT4+gXvxbE*SOoZqP(hq_|4t{h?TW&p*wAK8Qn%Z9q`}|llm>qwdoZ(iV
zbXTb~IrB%dkY<MK3&3i1o+dRe_FN*f-(O>xJG;ya#5IDOKE7GsTZfSGKW-%|y>(Uz
z=I6Y-@?I`2?~Bvwr<m@_Gp*YS=ab7dW6@}?HXC30L6ORTKiOBylCjYv`Sch(u{E5v
zopmEbjZNFYLWGZtYV2K;Ep))ZSxe%(g0b>K;n)g|7CBS2^bXG0-p1l7SCPEhTn=81
zId`xSotA*4etAHp%;2_?P_M=Ph~q~#^Lu*oe&Z^!O$<Z>AXh}?P3(?XsD~okn&PX^
z03Z%iCa{7Qhv*ij+gxv>m)xc~&$e_*dU18=w{#5Vd(&>%4Po0)_$)=6!%}Ept8wb#
zlbY@o^wzhAPnQDH=Ey!rLhXy+@Wz<BqwVdz>wKClY3JInVzq@JXOx8&OeN$qk(aWc
zbeu5W6g@@J*}AXH8=-71bFoKg6)CCL)b5kV5t~IC1s)64+i@z^phoa2uYB59ua+B&
zovRj=rIl7SDY`pf3ttVKz4|hB+2wWhIW7d}Wag@fC)J47%IJ+<*cOe(Fn#T7XXw@Z
z+Jkb(t+ITz3Yc8)`$&~VgS?TpZ#yjbyM3%gCXDm(t+FYCV{R8#-ce^+bt6AQDS|OC
z=S1@r!Ml0?ulVvMOX$BS06i$q65J2kL~nLKT)Eg{>X)IwDO=qTv_83ZKiZfaX$xk2
z_RD-EE9@l#7R|gr_$hz_0;|ka$g(m)caHq=E@%*Z>z;KEXidtvQ4v(oMQ)4y4BRFY
zYDMO~xg3FvP)Eptz!FdYqL(<T@FqOA&tymaE6=4qY%gc)^yyI;A-+=#mvh6>vEGL>
zbA|b|qFB1%qZa%$LH1c;@XUA42Y{YXN>vY)yk}ErOjfmjx*$#s#7n+<34v=!Qza(c
zgf}$}j*Jh{;m!TANOrZSG>iD*5|RmA&#)wUtSlJJVuM*-5PM{oH8`TvOZMZG<^8{x
zSG-n%)?1}*f~6~UqLY-<`EoZczuEWa_xlN^2z=AlU)Cc&w&ir`R!;zkZb<Hsrjr36
zY9>B&U72OD#tofYahcd6SAZR~S=aR~l<ynk<nhW_m1@0N>qPHh%9?&5MH&r8z}jX6
zKH{iGomu^VdI4JhVEy;0PzD*C3JU~2dE%UxO`6~aq3`H?&76wa8@y5BEV3=`yO~K)
zzHoj-p7kkDKBFm!%JH}u(_II++GHSGJOw<S@F6KP1&;segID{dvkkP~R(ft@N{{36
z;WtNaC)IUjYAxJl+0^Z-;bG)ldi4+)LbB&R?$vG>gwFO-EC;0+v&~6W@>qe@V-V!&
zbwrxy=Ct%cTTo9XTo)zZAg-{_v(8CGTaacHSQUed)t@CwGg8pHctNw1O4e(wL#p~H
zHnd)qyzz21lqE{Rod(BmY!5WlI=pz6OGvQWc3r`W2p0{dlki1+8QW8|M}53pvBo?a
zlFVEx-jC-<TfKZnA{Crecet`=<J}!=F#}rqdFjau)%`QRU9XO}23<?~KnW%Qk49rl
zl_&%!Kg4VaeK1i5$NaJr7#%E$8#c_=@^Nih)Y#`oB|-64E?<B^aL@pUMQx{4TT-Ui
zvoK4kR-JF&8QeOF78p)Y)pzz90F<h)I{79=4BVDRc_sF*QiPqU7!*tWyL3X3RJYhX
z?+h-3*3TTs5@-apa)gI}$5uI&bg7l0iiEZ2|ERKT^}e-cckn(#7XA|p=YKGw=*3Bm
zWH0JbDpngMvBjX>*)bJ8q5;SkMAm60bZD+gkxF>SchJj#b?IZ*UR7-z_~wsfj8Qum
ze(?QE{imYLEd!bM$gi)utBv=Lemi%*Q+h9DtcX8BVxIKsJPYL(fa)AVi_4EN<`CYE
zZEQ3e%-5;1WqBLXy2B~p-KzY`F7sSY_O3CpJb%maggYSkj}$=pzf$P8y0RxHw9-J_
zry*)}IRA|gE5%r;RXdd2(JHd{%(^LQHaFy6bB#0Pc`A*y*poL)v;7hh1KQ0Mx<j}c
zN?X<aHFM5w-DzI64{rf*Ynr;oBFoGmC9?E>tWa;vE$L?>D(;mkHq?c2$VaxsFBE~%
z2HX4|{|)Wi+j?up!A-Br_l5B^LFmHxRf!RCwQ!gBpOH@HQMsJ-nUTNmX&-1O;>LX=
z29YImaOhV64u~vz#&UdtLQnm&w$$ud-Z{*pXm0?w-HF_L5qiv)E|Il%UxeNZ)dk1(
z6ky1I9sh9m>Et4g&7s4sGu<M12KM8R1<hce;~!^lB3hO0ZuP}KH@Tl=`Z#)>Ziqne
zJ{xCBVspUnt7Xtfd?uQv+n;I3W0+U7|FbquJ~T=9DUzht+xztd!J>Mt9I1{t|Id>~
zCJ0gwZYuu4ygGRcmmozheA=v}4?4BpJz6_}jfYyl+ZBa5M6~@Cr4ks+?_k+Z4mC25
z;aVa?1)TLqgaZ*sA6SE0H52uDL!jmu>i}Mu!H$5?0=QqPBYgy6AQ&OY#~h3jSOC)M
z*M?2!65xr(sCRcdZ&Y~VGU&gb+1S$Mci-bhL9c>i-P#Y8q`7VO!cPQMe1y4)tknnz
zIuA#DhTbie(xQlNsY~T3YRtwj#f~b=SbGlr`ncZ$oECIbL4rAOe;ho9&Ey$S;#E^=
zbg~$~X7xmW+8)f|bX$F}+`Mca2%W-39aTn3w2(RTT=nOsds0){=1^C(FcMAFQ3*P1
z`x3&5a~4Lrkd?!WPkiXMvVa?F;wpyY3YDUaMY_f@{@vm-07&!1N&2ocf7TYMb<LC;
z(B5&MW6{U+L$~Ec%-b0rYT+1F14qgwBDifGoK7@FKe&64UHVZ?_2&E^m5yIZK2f{u
zhb{nWkwk;Sc9G)=ewa~{)b<fMm24`}TL_E<HqEnnHaKuJnUlR8Oq`+!E}m<8=9nrg
zvu0^kEX=QJDA{i+PGCjH!utRxy+?Y4tDJdX)=Jnm5l)fDqta^szGXSl<6JGn<EGqs
z2c0aF)-ibm;c%e|N2F<HVtVN&WHmmsP;cqmYS20jB7*bHx`LE?`6#*UFh!hwkSA3;
zschJOZwgPN5DUD&XGU*>2q}Ny+&AS68PfC+5b<I@2gRtTfHaYyYsW#8E!VQ2uao1F
zO@shm+53n6<vzCxxH+g`nxcRge&=M408HSe9z3-Gj2CeCjW@OBRv(|JIdXHnvG5N?
zj$#3?Nr#!>1vt62H`XPbPw+jN=0kr&o%<F2sd7;mz*iPo%K-UBJW<i{?aw_EkG}`F
zn<~*13oY*bOw{3=dS-uYM?d0POrfPX^5T87_HW)T?^-s$9@#dEX!7|-I__}PlKa=F
z8~r(ArS|;FPHzV24J=%#8fcVlX7%r!Q}H=%4W}f8%~C+rYfZRdb?XYN?(=4}c)hPy
z`8#i=1+HsDb1h)1h&u$ZgTnDpG&l)RfFHyQER6Jd1Mu`8vOiKpTx@zF_%xPJS5d-e
z#D$ix+Q)tP+r#+E?^eW3`aT2a(0aceMl1w4vm!L+*Ggp26hJaA;vm`|vVth_^FDNe
z`+v2H1yWm2A)VktPDnIRwQU_Q;a0X>FeOQ&w^FxE<Rp;giEDD7j#krl$-_vcR2<!K
zZB&2e?~X#~`}2t`ZG`5w1e*^9pa}(sXRP0Mpl6|Jx31NL;cAO&t@lPBgHhd94|1h3
z`#kC;ReEL2sO$ocBBz$$3EiI8)~3m%ei2xUQV<(J9q8%KFz!Oq-T>`$BUW<|vW=tq
z&UKmh!^|J#z}9B<qSwZrmjx;}@_GZqDft)5&+qGRxz|081p?VXC$M0z1Uxw~ptkM|
zbJCTsz<^x7|0G7^AztN9kn4G@W0u|Qv6tnO(4|KIeY&S}eNvYdhCZZ<HA7NZ8nh^<
z_zfNKE|~#YbEHsUOo;&&gpfvffPBL}DFG^@#w=cM4NLZZFnKdfSKpEm?l_g|EyPCj
z!G4FinvkQ{_qL<nUT-M-dt7=!9`ol%7>5T3%GyVp*Qr#>w8BayFzuyZ>cV-?(bz_k
z!|+i*tbE!kd(9xw^N#R8=@qmoru2{nVOC5=FSaiQJ>dKT(bE=zO;SU=N3-Q-4@I9k
zmOhj<y5*dDnUl!l!=t<5NZgP>-2Nr~qn*&b>%D)+@-m>u0DI=H_;fl|6sLQ-_6$jP
zHUBrJBN!z$_Wa)iEyyq`fiy4#0Tk<ECd_4led`f44Sy8EGcCX0`{%;=61a!y@0GSD
zlm56`YO*NgsxX=4#A-<YhDHHQs1sT2f+P{x*EhD-`Cp*I^4I{<D$knSk?*5YzQ$<P
zW3qS0e9L24*jZWYdQ9DfJ_LXrm(16F0+kC6uiFsVUz)RoA2ri>BdV-Zf@dwef6v;}
zQUzHk=KJJ)&e9t9ZhDlw-ur0hbJ~AtC6+`Usv-Fu1%f#4n%gI2^%hkWw5H3ZbLnay
z8U|MD#$`YF&Zc?8Bce2pb6Q_odZ2M5ecBjMbK2sHKVq{I=_n1`IvjrVz{Z`jmCD#(
zu-<xH{<M1WI*!kzFX2_IXB9^my~d5SlLCe1^5N)xR;ku#l_O2KicLYcboo>7D~%K$
z$=4ZTk1@e1I>Slf)<S%e?}}z$IMQ+d)Jj42T)+NY?eYXGiF9}|k(&vKPO3Rz#2fn?
zgvJzk^U7X(ICYy1vb=V3rH5b0mReyL4{h^*U;tFpL@Gw)fO!0s%E2nHW>c$GjPmnU
zm>Hd}6UVZjz-n7xqn8?Uig@gtrh!9UK9BDeKjJEc6y#8iH29_noSJy*bg4)Bsh^v~
z+hVl!G+xuN2GF!imz(!^OP9!o4j|TLY}J=2pV{=n`#+mGy}%<fiy<4`(=^<&>A;=(
z#HhmyW-r?xJ4DNMFK{J&<mHJab<4N2N}csTU@8&3q1USY?hw2CyM=Fdk@}aJMP&8V
z<<|Y&%%bB8RAJLB?u^ZngPa;nrA^Z$lp_sKc%c18_tev4M|kT4{45Tw72r@!IFEiS
z@hidA9Lx|t-8p@g&V}ptPGz528(y0Me4_AjSxxni(N;orc8}Q&rEQt5@J2`B!6cjP
z-&C}XUeCku!u1qd?IPGqj{;4>-~^_pm~E>_<K^!bcjusGW|Kjm09Nz#b_Fsz1J0)r
zVaw|s3R-Qva6ERKOzEru>}9|+HOr=O2g1}uv%vP>^hBw1B_qMMuNn@;7-R?$EM0DF
zw<m#M(LUee8&)d0e-%3<){NBla9NqaJLg?VKS2ro^uso9I3XdiZ)@;+`I$xlA_QRR
zi=mJZBaXHPiB-|Oeg8nym5-?c3f9<4o!~!MOYu+;Ol^}6kQN^0ub6|HWN#rZBHDcT
z@H8J;a_P(Ow;{580ux*{SkGSNjE|gcWw@*gTHk$p(&OHB+&8?_`jS8~Lq;UMJ4ru3
zsM>&OgNplyIpUyD08HC59;}5g?9y71wk?!PvKP-+bdYB%R`i?<C5(Y|>W)-VF=3KE
z^5)7(tWg5%U_tkmUGijjC5DSnr4W;g-6nup_O<BlWI=`141Gv4FNUaW$``l*qxjMq
zg!o*?UG+!ho7wR=r)fJ-gHSY^f~OefIJ~|zRK?M0S5f#&?H1SG#Ou)d8sD8xG}XIQ
zis_}5z9CToGrqmkh??wNlfEq3aOeoH!BOv7u*dfKyzBK<jZ}fW_Y0zu=4rCvO<~1Z
z;tUovSkuJ6O&KoZYS9{-jn3Nm^HrO;u=!$GFF%4Jq;H6Tl31H4uyPN$*S=HWkY@tM
z>~<?c;Ka|%+UNWKMi}!D5MgjJkNQU49+7W+%K2~gr)RcVc3&)rFZ|do$d-vkTD!aI
zN@5^8+N>#iS`NkAKJCj(sIjc~OHjw6(VsR+BeuwuqUw}{sxk{t1zDjPrL_wj?_jxF
z{O-nc><h;Cv1sU^m1j403k>@spfTXjJBn(|U7HIHRX*QA!&)_Z<@^FwgY-3vGBucT
zRKva?zOc7llU>0TPV=Z@@oXg<$xF`5raMZtifHt9VHNw^7m7%Hr{Bm3>h_nG+_%ex
zl*Y1zqE*Jq-7YZAev)0(X16SP9;d5#l0r4Vw+<O_7$0|8UhR1Ode|xQES3TV7fO7B
z0Oc$6s%?4Z9n)wAip`y!!>TlZkf2OcBNBf;eja)zvnqH~ndQ{g6G>mP7ye>umv3@o
zp~>+%=(7p~b#rdi4ZgEQZUz=?{N2~nBHo}o+%`uMebf)&X&%ZzFG4U>SM~0psO?(V
z9F#U!tz3s&|Niuz8+OJhx1m<OS7@&%-5;-EJw?NRCDLhV!3P*o>}~NF99y3Jp`x|l
zynptw#wu_vPc~0%!?J|7(erF`5E1d*$)lveNaZveJVgoEpaB_G72)v@Tm7j7+;4{K
zvJ0H((UT9bxRI8v=3)d*X0aB28cV+nI`kL3IlXaUrIS_-T%E`@=t<?FcYbHm^yKxv
zPz{z4yk*G-9;!qkYrFHZEGA3ePcGExzIK`*-@bEtE=HJ>^u7i>d=T+?8+<|QyF!6f
zzidY5xzyzN0@6JJ4x>a=X<(>y`tVXj^4xT>KT2f2UM%PURW#g5?B>9n7O3>g)m(M$
zZ<ZKvc|?XK&r!of#^vxgR<X8xNQFmn09&@qeJ6ID)|OX+!+rW?zS=4iIJ3;UNZ|2j
zO>C8|+*v)heH>?{u#z&7`uRXT@e!|03|`6iF;)Oss78z*8pIPMqKcreK=@DeaNwqo
z&jvIg%Dd=1`^Uy1S=9Ue1^9-X$WqwzFwMJsH81V+{h-;xPuCZ&_UmnDBOm-=Q2Ex=
zSRG6qFWa9L-<^o|qNpKO@<y?vX7<MkUs}$>>^^|HWgI~zx@t2x+rRBi#sPJfkF!x^
zn(+CaJ5mm@RUWd*Ji&M4xx&9ZP)Q0kIiJ@<vfcUBVxWq}OeNem0NMqHG2?trXT2W<
z;-qjstw-MH%WtX;3>(L}gAy^y5sfd3qsx4J)(aZ|R*`J(3V9kzbx31=y7zo|!<chz
zSK(HlN%@I1d`>H%x{1d-S@7OT1;=R6T_K09nXN%%GBx5YQS3|%kc9M!JO`qw1PBDV
zE*&x)U>r*d%#E{a7axfImCdVvWD^c#WApJM)w_e9Xdlmdn%sAk9L(aI&W|KrI^;vf
zYe{uAA?1KltB^vqz*R)f@gIyY$R|Hfp8(=Ou0|^Io9sI}s+j2~7lga8WEnFN7UjkF
zSsR_HpQscDv8T2tX(+(~>)A7IZZc>kNcH)d!AC^Uhq$<KUe?5-k9-9F*3|^FpOxb&
zpz`8N7WbCU(Sjc<XeZfUWGfbc2_OS4MS9X%LHZ8)O25RwAOt2vG)R}_+wTF8f9Yeo
z^~-QL;%%(N8~(9-&JO+L7L-4L1^az|miE)`prI)DFQWH|?YoT>2Rk>MOUXh(1yQlR
zBkULUvj>`)Nl=nlGk-b43z)Awt&*%ikmNsQ2a<m%JLFxa4J_GN(sU+pCkQJ%zTpYz
z2C{^5l7)dr18gzW@o&t(XDq2)M8=NwkhK$-dbyJw(MU3b+iygUH@l9O4;Kvgk6S-t
z)>!+@Xf~a@yA{*0Uomos{UZz#Fj+4L!~)sSPRyfHB^6l3kdak_?`SJ?2-W*f{-Ak9
zl|+OR(8Z88NzuWQ9^U{Gu$Ydq!ajq{|2+k}g_KV8`pXv#euF)3viAn$wIXFCp;77}
zszOji#oIZv<-pmO_t*2EEa&YpHye#r2tZr3;Q7zPPuw*#0X+T~5LVStI*e=_EGg)H
za1oz2WUg$owUF`?WRXXEK4&&A^D5zh>tY>-bT_<J`EW-B9SUgzex>U7El0=-O-K$I
z{n!s+f_tBCa(cx7bgZcGN#O371oMUDy>+K7-ag>6h2cBkIi%-#ultvVDe+cCPV^fK
z1-82=S4Dy@mjeDY6)958e+zCEmwlqvKYGpz4@O}ByMT+xIs{JT-jM#j$wS;-Nf@WU
zJ~Z%u_|Ps-13d{kb%HcDQhH%gOO>%icpjlQf-IINLV^6(&A8P@=b_(@$8cT`4{-Dk
zd#A~|IJa)mID{cPuWF=i@XA|{-vP+(Vc8e?@hy-~q=`M9DBzhzK&M&U8+HHQT!2>s
z{vyUHcVIMr+z_L=!WwxL;}-_)^F;^~KAGEcc%zhx-{COPS6)O5$`x;7`2I7-MC6lP
zikmAN58w4-OW>rv{#Z9Igtrex8FWsU=^tgVfMyp=&=h+h6I$its;en=0q$>!eh5H?
zD9S)GjPw+us1HedO!^Q-o&OweZ$^bA96d<FS=J2=1EkI0?it6fDjjq=Uode^&Hug}
zfol?;4Mm9rngN91PRWlnFe&h)h7z$@gzf&?j2#C~EBCII8K%C;l(%9i*^)^jG>-RC
z?w}zH|Nagi<<a%EsH~O)LkAp-F0R{E=1nw&p1&w!VI%&pvvLIgHsn0mP|MN)O79_n
zoHB6$J{Mx0(RL0X9X4OBldR8K*`vyH*!Ei%lW@{>Twu~lLS|wDfW$L<O)U%)1nCfa
zMXrqG!yi9}cyqWUfQm6Xq@b(XKpDfpjr8H1=yYo+fEH)s`DoFTG=olaSQZ7tpAn2V
zw%5O1N4`igCLR3=Ry1SMmzv2pc)aS5BaMgx7Nw0viq-&P&ezfdL1BB)cBD_WYxW+p
zHse>07pwP0^s*9?;$UrFD&WS0+X`b@(sVA!+C<GMeZks{P^g7qcwYfE%KlX4gn~&4
zAX^uYot{KAKI1-=7oQIv0mReW{#YzmdqaUk{2#~sn=hfy4_kKlR7zLR>%BjpE*K?q
z*duN+Xeo@3s3k~Y94;}3<6U`8QjsC62EuuOqIbWFez7b}H!!<?j#>m~X|USHubjL!
z058iY<yWi&=ZoWMSHlBU4h_&ic7Rj$9DOtds5UW!)gSaj2Qb3M5<#~@$X*6ZOH3l)
zVUj=diBh@j(27db)K-a;y{UAtZwI5G)mU;wH$!$JPaYk5BX|kGaU-<aOo0TzW=1ly
zJhmj?dFR8G=@RarUS}w!TCLxUo)$Y}i)KFWEbslay}=#UX$k<dFO*6GyCv*NLoD5w
z`Mgu{BE^z0kDwoF1C_P*9kc=X6R3NAOneQFTSI^F%lLrsZ-nR^<^YvOpz$>tG<nrj
z7zg>3vn|R|BS!eVg#)$lKbN!uJhvu<yXdw~`BSknW~BTuZs^;~y2NQCZZP4;Ee&3g
za(@oB6ciH1uo>U5lcP*%CzLZPQJ*!9EoNR~D~Ot7g+a8OrNo&l2I(V^rz1@M3_1r;
zoG)>4A%7E)GC3Y~R;Er$C5i|=+$upyRR#vm?UakfVFD;X&RLaSkN)D2@7dnfPpWGQ
zNrBa_?dtW;qU13R25eI-9h&p;DIK^1YBpcY9L=L$yYfL4W!?4D7jGj0-r2-2M&tpB
znS>evb7J84C3fYPO@m(yCJI$gIRQofHZmJ|Yq_mt$j5f&C6zDSOUNW`M}i=h@U~ph
zmq<aeHZ%x6LSXsWg#M3r4k^xBvhkTPXV4B(maH%6@%>8qipZBV^jnYlN9{th=@N&v
z++?d)zdj4P93+lT$$`NzI1opR(vy6Upwhj&27KT^dvK&9mhEFGtvjA$HK1gwUc$CR
zAQL(xDX??ke4yAXbimHVMhe{lvGY|a!LLyW4xk8qbSOQ6k*nw&+-^yYu<|M);yL36
z+#qU#kCZVHk5umaICA4ND-7Gkm-jCc9-#+K^t!2_ygLke^;?p5bqgIfJq;Q}2uKXk
z8Hs^_M5>V-iJ_l>h)%=tG|XfHQn?J7^{W8?gE@|;dOF~&Y}%h{SqCQByE%Hz)oBT*
z0v<5}>R)~NLv|uGZmF0EC+737zM3HO<J=_EM9}E}>dQBR6u>00#88Rof48IvA7_vZ
z+)X-hfhqs1FSIB~Iuoz@WcKft1dV<y11#t$MAh$KZ5c>LFbV{XcV=wV(*JHr{4h(1
z;BEVqR~G+L5fS`iU~+@wZwu?cQ-oL>H_%-(K!*Qz*9hW3uz}gL`S1UgZGe@#K>XWT
z1fa`*r3ikQcjDj%-iY^jvE={KJfM$&?*1Nf{^hQTNP%GSql~l0|K*ZMS5koP{(m~f
zXdu5jRNeVbP&4FW3zwAJ&@g22zuWu5?{lV%mR=>9hIq_%frEnwu?`<%7>^d}_D%_S
zqBe^uD3NreRWPEudR)gODh5M}mI#*#<p6)o?863S{B@HN(@YDltp`dOD&a7v>j8?I
z>@<Q673ya~?-m0T9+c*%$)pqN@1Y8?s)iq?<V|DV@(V+CK^sc{@y2d*gL)GF_ILn2
z2{-z@EdvdkMTzvUmc&30X8%>uyEi^E;zP9*Hx@0DW3|HhcY)_+AO_AYk;KS=b-2PA
zhGww(I6<W<Fy6O|gXu0Pv8I)mK7`Qsx#=ZQ)X$>NT__7q&7d@(@fF8a^$32*7Qwin
z`{4K#D|PObD^I>R3;j5W55JNq=;@~>y}y9eMhf*tQJz%pksC@1j`3NWR;)uNHZW!i
zV5VnLf1}G9T5r^LdCQOL?Mwd@bsK*(epPL`04NvkF+DH7z8!lLWVMicw5!*_hGQf3
zy~BULe)q;lSaDuUn9L$)APs#|gVKRDHPdaLfZk5I&K$*R^P@kH(Y4hacL~8xP*L!%
zx88t-*JHwN+k!g8{_Ug~3JD0rkVMc{>azi56Cr!_pI!iMDRidS{0_Q*6s-t$A2Sjk
zzZdFaAt@*TP6H{U3K!y1ltgmWX2?6(J}6LOZl-7Q`cN)tP-bg|_|V5xK4nk~%A<Am
zvCQH}gHsFD56}2tf<k9+Et`1sb;WJtcfx`z3C;N4RnjdTsOaeF=xT(?{^w_S(Y&Ye
zrS{~v5?e6X!PC-T!)>FGDJyH0-+!jt4Ts`Z3Vu=$-*elF<~5YtGw_EB?Aatm(}u)D
z26wynz(q2|iLiW_#DA?w(FdS~L9Z@AZIZSqen`BYGV_FT=Sh&kw?w?$RMK7AgIfAj
zKB4MMIaD|)hLqg@v$(4lTF+Ha6_H<iy(v})dQ!rpo@1{hGpyAj=ZOZ&m?F%X#m87&
zM{bXU)=BtpgaGA`2bz(`*r*p`uU~BVF<3CkgCoa-P{}<8nUhjhnDQ;?3+Uhi7uk`b
z^}!jc9RKVLG1nn|Ca`!=9dq8q+#}hhDjr#^TZy6UghE4S1C5Q!4-=3Yw7+?f@N@Gl
zNB)=71-KRCWjZsI8fsK{?FNt5mzh)cn*<FfiX&K}Uq}3YX_wT-@Z}i%?;81VS&3+I
zF5RHE;oH0xnMQre=kCccQi`AYN}cM-n~YwauSMx$pntOj<|bPE!084|Zw)P?`d1@{
zUv?LI>!4=Tc6E@wHQg%cLU0&4y~t}y_~u7Xm9`j*E)LB;ySOG9snru@-Yq69ujL&R
z)84Db03M3p2>yiV!W$i9C$61JDqX3WR$0ZF^r9^Z{eVX230H5Xc>0!ILJFCcVJCQR
zPU@Xi_Izl=-!Sl(mSKSFQ$CAUFn*l{=P$I#H#x_5vb@``ZeGIoKx5>jO9zSdw&cfZ
z@|UcAozu%NQVYa;qHhF0@veLG?rc-q93)a02}b|!$jO$nMwc2+!#<|@5feA39RT;0
zEO?IE=F5Rs{7Oc#idc}Tns<Km&+h8!g63?IxXBq*irmph7V#$x-t*Oh-RkV>flJ2_
zu=Dhq{nR+!@?$%CUpW7oKWWfy&f<GtE8Vr2p)0|<^FM-A8p|*L65;^)V!Gg7lN{y9
zRZO(ucn&s1>>vet2K36&?b2SA>_({GFWDSdXVG75fX+@8v`KMEbLcTCW?IBNBcJ?&
zoDe_8cwo`oiV<l#DfSLTdNP^wtA5#y%GLOidMaPvBV$$}s{vK<ohqG~D^yfIZR90f
zf`rw@sE$*1uqPRE{JygM-iACG9H!7;V~l{1yQh)@^3XPtw?u<2v9Dm-S62vkSJNo#
zYL8eiM$;Z+kDT;gpcDD_l8-W&Iq!ezwD(SO5g2PfRAuHgQE}QNCvCYSd`@IRb9z$e
zVW`vf6`xZ=a9ZyJ79w;1uo|a~#Cc+*3)~cPBm8OOzD!(r;X!aRg{9WhCw*x|TnRMQ
zpyWlGf(R|FKHhhYGC94timq6^x^KEGW&UV}V4~5dVyebEGKoJtn2%eVxu?J)B3Sh4
zlnPbEZd1%eSeEL(gZ|G!G#de;c)1@SWJam?sJD|5(Kd=3eLgwKJ~It;TQ$}~h<bzh
zS#!e@M@6{hTys-@Og?!DiF&?U=d<16;j_l>DyUw`gc@unB3df9by|GRWmo?|-xmh1
zu2MECqAmR;I}Eh3b2|mC+4<%O{PM;FGPay~-@g8ZM{TMAj8oP1Y<;&^8|hq=>U>@$
z>u2ikV+%5b+bu;uU1?KpD#Wp^-+;%wA^sGlt}^~HO-9`&lA!)D$m5*sN9$YhK^S80
zAR~$sY4+GGjH)l8mE43g>e5c95{#o-ky<UN&@N*gH(hqsfga}!ztr!D)z%F$eCvoU
zjQ`AwM^^b7b@(Ln>=laL3pue%itth$k>yIiJuHDmZ5<GKKATTuLDa6!_CYl`5~jT%
znit$;o1F}&g31v(unf4D`;Fg~bmBO>>SUg(Xg;&QW8lR20TVO0_ctqti1OoGbIx@9
z73<c|UbUhqJJl9NhpTZtf;u=KvIuqhov!Zaob?Zw;;@FTrc@U>gq$?pra1&YeNGZM
zOhorQJ_p~OcC(;TlLriRWaS0=ILCg`y6rL;#O|p(Nem2|&b}KG{A-lDwBQ6CGfP5E
zwU`O#cSoMmVPa+WKV?aKs6oeb0fu{$tW=ZW#E6&?Kg6CddFhOIf1%Q5?EQ>uC-tML
z)w>W%Z6^Ed+d)zP@b8(0>exY3Vx6!Qu1(>VWIh^hl>?R*M~VKnje>$~%($!`(!0c%
zdT|Ts)Hx5+x&cL)-bxI$N{<_L(l}zmw%}G$Ul+uX{xEY$u>L*u`%y+SILfEC<{ATS
zI=U6^kZke78>*lD(CcYP#jk=F;1vj|<|_O*W}P6YIvc67z6kU=-V@*I=}qV~OI>-^
zn9M@E^JSfO?gB|#@kN_?UPDTBON<hwV4ZoCzFC2mjmQgxVDC|Krj${KuLUuNGgn@X
zC%y4~mpXmB@N5NHy4!plRI!oyL^F*ZP{005aQHxQP4j}h<<SHT(^))rWJY=wwJ)6@
z`K3emnqsM>v`K{VJkL94fft-iA$Wxpp^0QiN*l4I|M_WMlWv5ikt;@(@6<7LeDVYh
z4sr2@<sYu#YlKpX@7Y!6IiXSdiyXQoMTX7!?&D)h(`*vcgNAhl<(02xsd9OC=o*7_
zN{Y9{Y_-_P{pI;p#~I^m@zVLA^>}Uu$Y0%veHx~TBN_CssT(4bDCM4h=lc!tv9_Iw
zsjw8#=!}fe;`1bCZl0g5kw4(~s-#6liOGu$;4q)ow0bOV6^L<d#C<n`lB6cq3EGFR
z&4rF~N+WGS>x)kpp_z(qp|06As`e=_YwAox%hMdbh$i02@~BBE^DI=;L4Mc}79Q4&
zs{VwI7XOB(eo5`0gItIJh<?u8y<vo$7_uG|CmFkVv_$xaj~P{8Cy!;DG_)FV&9`Nr
zB)IS7m=OUBg@GLvGbAKJtj0rXA74jIxHO<1j9-yc-D|zVDHBVET_U18>~>k9)Pyg-
zA<ce+t;H)*_nJ&VT0HGOe9_v_)g(TpvMyFoY~e<eTAW>6nvT0_<f|^fi_jnSnCy+q
zuPH3V%{P)z+At^bh9!!;r-mT79YbEv@%m!G0ts%T5kAQ!^8+$1QDp?IiWItIm&5Z<
z^V}HM2mMUpPrMj7nY1{9Od;8{MmpVb2%fZ5BA2f<&|iT^IAk$0as9=q(4}Mc1Nu$J
zV)h5bddEW&_9Ne4jku?MZr$P;IZL)rt>RnWJ9Fi`Xc=kNyt?9jda_TsYbe`ulNCc;
zpCb%jf2=^+dlrnl$?Lp`zf3vQNfptb{h^d&Xnd%-<^8GaK8oJVQ$6vt6BB-`uA8($
zWbQei__)mHF{cmve6OLl5up+Ib)O;V>I^Nf=SjNNkrHBZA^%BxzKxdJ;F++Tk-Hz=
z;?<NiPIy;XMqsE7{&6o{a^mmE=$TN7CGtnl)Zt55%p4!>Y8g@3dEZ0{JQO|dqJ!;b
zw=h8&;gnR22R1I(t&6?@Zqad`=n8_>BxCEOp4GW1e62kw{{u2lF1EKC{>LU+De)yW
zAuK!_<IlZCQ@mNJSKWH2XN~&N5ct#Kq4C>U)5o5{p!x6*z~wsV?wIPfX8-K|)-_xi
zt+8&hW#dNUluwoQ#FTA%>(Q<Uw!B>INQWD&AkFn`Oo{H$enN;nr`6&)c;dN>AvdX8
zqgQ%wzy-|*3XTY{(3ew|#xhK<diRG;osyR+ywwP+yNxZmJ*xX1_qU0avb%N~wK@v7
z20C<&80UddaJgbDp;6k{Z;VZTw6@O2@cHk*+v`Ex%n2zi>}dS5SmD0EPD|DT_g+>T
zw<^KVDw)iBAS(JTfuw=a&@$%UMBL6{B~Gc0<>4JULH8!wqZGZCi&CJi&b?>p^;P7Z
z91C=uYnUml?-Jq)+M(wQIViC0HZI7vf0TByv$3PF%X^RgNo^GzFN!|#ygLh~8&+}N
zF5vVhh&|Z0<Q6zeSy(C_$lLRh-f2~H`E@Ul=@DmFwRgct2uB13jZiEJbys*@V2dQI
zBY$>Pry$5><v_0R86mujckoC~;Zj_u6*cjH(RMyuvdl889|5T824}yi&M#)+{rxUE
z_S>xshl%S)*t1#qn~dxvaV~l|jBA)tVothAn5B1S>tc(6^t+gRvI>@WX_ikMcfG_X
z>U_8iBR3&b(y`6vD672J?%whyEehWAY}Z4Xp=<WQvb110{9UObt9%*GKMN~~SJm<=
zQFu9*roz{}<F=z>IzR`_qjx6PrPPE1<C?phi-W7}^gz>dna#nqG25iemm${SEa9{~
zv_1~UUIIn0wUe{3w;%-{`Z3a|?R>P(?BQX7lX>a%Vg0oQs-%Gg0zVM07_faTK9n+~
z0vsKj3E`tS3udgqW1xIY?}<zCnbwzy)4=xk2n>1u+J5S*<oqKs%!QovZky=a<@d=|
z_wR8=BP(qzbiedSa(x=#$zVI`Fu*Ak?s(+jil}mO!Zd!>9ejI8w(~7Jk{}3=j)TRn
z!BSM0oApYItlrC-x@Z&aFwwi4tI-fVJftGtLpx{73(Rbq%tt684+f(BV}ux<^6Jee
zqCQ7u=8BA6gjv~6)1m!kE6Uh{#m1M&c&D;r@VzsAJY*awgjIuZWVfj_J8vr%_XKx4
zU?tCYvif51+e=>^yrDVroW14tWK3f<nYg_RICbhX4Et$ULJS9f3l!WfnU7};{geCG
zqv9t7wm)4_ni%wiW=#J`!yz!SR<_}B$3oqEzo^tX;)V#y_Z>#>jPHf>PX@C(GN)-T
zT9m_L-4>Up0Wu2vTb))4jia8;;WA_7gNCkFR1@t2zBSepeGMGPRLtSguo2b;QaHBj
z@iE#yVts;pTSb8^B|C(xUwlGd%cfPv-cN=uUT>9+C(K}h%}PTBGRndM`}JLYm2anO
z2HU&iMjI$*7c`eKY0V=aWpQo%$FY7%Oyf^d65IO2;^iLpkDIevat*r$Dh~gY)ZKFI
zNUPz%?)lnQjVNiA#rbi*P{C7m526Mgm0<n1f9)Va9O};8>itY`V7W}ab6SMgNfV5n
zf-ORLAMg3=YNIrVi=qs=hl;X>Ie|@ID7XNbw%L3y;y$xvI{Kj+0f(5{9Cu~DnKkxL
zty5d?P$+E+P18&`^MA$Hy%y&sYCq5#nQ`<S=pByYO|Wpe`;xz0{GBAD`O@_la?v_O
z{|!nvlox#BcDoK~5AQ&rdj@=grY(~Svgt60{ylt1mzB@yctoF4M<czA@^0kC)S4Z~
zuXlclyIal<v(D8UhY`fQ&f`6o9?R%YAZYhmN=`L-iqJld<7^9KJS~~83Pj?4Y^pAJ
zlKis~^3qqwlEC*X!~=ZzTj9#frZ>}!!d=y_tv|SQPfPuJ_u=&&+MW61(ewQxFK=&V
zZa5-Fe3<aCoL|hLbMy-9M-(G^feQ@!aa=RDB_z%W7tU7BKa<rqM=v>?%;!&bqfAwX
zaeh-J9r#G+NZjs<3U67@c`J)Ba0iW`*8E_IcgTytI;g~PD~S^NDfuY;lOQEEZqR<c
zp^Aj~|K2@k`8jw1gX~6mAuNh_BGTF@??lqiW><@4N0(yzO+SiUMaova*m!PK3(3wf
z+1`j^a&E<@fdfKP$sQ)BQg~L7aUa%d*G?p?2YKW8vSW;_#LBgaLr0vACHti=Ga5w3
zh!|}xw|kq$ub555=A2{>nku;cdvpn%jMAzvvKC_>f2&v>5UmM9!5EON1Rt51(WX7)
z$?g*7P_k2IaH+GUx?g17oTK>2%EywdXH}72mg3GUdCct)xxnz7&SaA}UtV&WY>+o*
z@2J>ahA+AQmMNtM7XNL-ilsp;e!JF5+C{?8kEsk;hIVo;$|(6KAI6`-&;YYPmayRq
z2GIasLU+tJ2YIJX!Y*-1v{NHkNTYwz&st}Y%BbUDkB-Wmymaf-L>!gcMcmYEZmuJ2
z?A?7`lr;fIWB2gEA7QvE?J}P)He*Yl#>34q%v%gpZkJ1l4ssbNJ#ucyn27(T21O#^
z|M1gvQAecSd|J$btG@}_4a!j)D`lzg^A*kKAVP?({n`y8l0Txy`&3vX$#bLio|<ay
zr?4jx+Mb$_wb|N0k`T}D+rCjAeLarff;)H8Qs5iJlF5$F7oLZ)J@WTmBq_9%r0m>4
zy@>a8tH@^Wd>Y2{`bPv^+(lc-p4M9}d$J_|mkkVZmwPBl1>QGD#5uc*FCU2I6;6EM
zo%R>M<7_@gEkaSuY_{m|WSK_&e1OA(+YmDLPP6m8wqj|7{u$w0ik$-3<!@}~byfEo
z^^SL6uhxC5_<101uR!7BNp|zF9GDu0R9g~PmKE;}-@T9aHp?^N#HNFH=X9$P8RGN{
z0-Ile(@V9XsOPZ^cfM*2Td)$+ek0G(syXi6W2YO>_P&o*f0iX}d7Ypm3}uPh*lR#m
zC8qNFJ63;QebdxQy+8`|LGk*s$IfEyc)Y<*9v{8x88xSW;|d>Y-M~7}JF}H<dU<Ce
zz!Z_-Y!Os^gcTs`BX~v0RbIWi_MT@XVtuZuG*&OmBmcD67WVvrbHf_bV)%W@*&XTZ
zJF~1s89Px#RIS`UXu}+La<eG9dCL8r3^HNlPAM4~lF_$!)Ao;lI<zau$45ESAy~kd
z3Yfe)#=)Qb_$(pA<3lnw_d%3Zrn$fyI<s+Js*1%>b~AYp?7Qm%q2EFIMxtMvh13pB
z@)0-LA1$`4@5fxsMteS&NxH9py?KliN#f-Bi7r+xvOX!WD$QnVPFdW*YJN+r{?UnY
zuEMllU@+58NZiS5lfmuHJ5{nk+xh!9Jo-<GjrS`J!|d9V-$%gjr~#N~^E(8WF@Au#
zftAc_v?suNs%VlL|AjT>CHXDWkvfHKqa#XFr@PYIH_Yj^_G~%KEV8U9!m?<T0#>*{
z?j{=B8PAL4)KW*!U2L{&frp3FZHL2x>#fy@NLzmCzbYpy-@T08TS>uVptHglXL`)-
z6bYYt_d)rt+*A_8LAhTo)F-f#7$Dt~A!xoDRxgb$KEGfJs_X0GR;rftsec(W;-Z;a
zL|31h4XB7hOBC+RBYDOQg4&xGTO*-lQ~ldpij#qxxY|173~Q~koCnq8O4CgeD66$M
z409bF9clw-Q6i6OKQA+7JW&3R?AA-Dno70v_&rgjE0HO!F#VQ^iA?q@eQZ){Lbgqx
z{EHmF_XlWB(toPR9_VvV>wi{uKR7023SHZfdeX(W^fPFdLcfPMlkjf+@WflUQjyI}
z*uk4Y0?~E@obqDJt?D47LcGo=KG7Y^v2`Eh5LRQb>l^7=3gq+>){hXBJJl{r0k*CW
zmu$}I-PeK~XzS#)UQB%F*fxr@oIFc{p`%`v^;0al_LjWwd0E8yTol(^Ojz2=%~o)j
zyC2~B(^VfO6l=X%)7<K?cZtVUwd5CVrn#9RLDf)u9k1rP6z5DhkE0U5BZUWk4Kl#?
z9}pqvBS4hMX8k8hkwpa89CP$jtb?=o8)VssR#OLE#zF1q3A$$2`r<j67xrP<p=9;l
z1J4Ffet&+V;_?q=B*b~_|FV^CFd3U`A^4OTf6m0&O#_|91ljhhSE`P8yXO&yC(y`8
zGo$$J26d<=R<anE;vE_~W<SZ#ds+(plmCfnKf4dz`fiu-i8ZgxY?~RP)?<d~5ihF4
zlC8pAoW!dKIro@#cW@^*HV6{Kw1=6e=-Q9NR0HTNwpM}%+1zv`%_{OX(X4}?GMmq~
zZrY+<-#qUR5ye9&CIy?MsXw5_g+asS@Xf?^&g+cfF~jVhAzRcKFMIy;ZEHjmRo=`H
z*+Vw8RtoxNRaElfXidy~zR`qFqJ3aOp^(c!gnr+M5xLBkz2Q6~9)2t0L-07|!MnZ-
zYj8pWIea_3t#DpN!5KmJ7jN>##F)S5I2g;D^aml^^N`412nt4sc;&nsj~uC)CAsS7
zpen|xsyJcH`AJ0g4O7&<$Du@}!%*r7Spv8pPYfT~ga7oGC|P}{FwRYN_CZtt{ocBy
z<ZJwPBZSiL-PV5IKW4R%7)s(FvTTPd&3=Sc13>gB0Rd^S5Sgz+g4PG^@q<hS4%Wv5
z%B6}djU*+p4TZ;_HdBi4h0i#-R)of0?a$FaJ~8zx614M%I3gWM-CH))o~vdfKCnlh
z`z?GSSoJ<tB}%7&{KW6*K#TpgJ;fbUY8qa3np%Q+DVM+O$y;Ksk6>N2bM*;_1!uvY
zx7b)S_%4;wxO*2smWn{&;O^P{E_j4Y<(;<R^Cc|i!9V+qj3+z&r97;{AVK@^Y<%Zy
z9h5BujS<rn*@J!OBaK+a;etq;=;|7Kjw*xy(cYE+L)m|QA&omNw`8fN6z*_~O17C$
zWSKDCvXpf!*|KFV#-MDWhDKu&qNouX`;ukI5?N*}*~3iMVGst{pU?O{zdX<DdH#a$
zcYe5D^TYMJu5+Dp-tY51=lt+-6B{timd1WSHu*-@TyY+&I*Q*K%ML5;4<2~g>Aome
zG@b#_OhVM>MfxPd@eEy%(zHB4-^*9nK@mRv*z7=JFYCqG%e_b%3v^rZaD|2V21ahp
zE2Czf>O-3qKL<sdZU*8qhb5{j=dW>1E15*)ckUQ=DM+ZaCm1R1*l|?lWaa1XSTvfq
zFj5{uZOxaZ+nf)wn|3}R+OijLVjgNZ-%TL|+T_fKp3_E!N2VT|_o})09lOa#&IRF@
z5bXx?{w^;k_9^B@;cZmysut6sL8z7~T&=9#Voh$dQP_mdT*=wb)a?*z6K-;{C4?Wm
zPq{{jrb1;cF6O!NqpeC$${-ErE|Ic7diKt#hkY7f+m^17QJJ_sOz?xOeH-nZg`dwU
zd%ltN-nm1B^KV_CTmJBX=|uwFa?57q@q2vP@|wvvX%beuGydFBXd@HWlvLpEhsl~I
z5MVzS{_aD2%?t}g4qlEj5xy6e)f9i*^;XZ>Dg;jOhfDPtOWU-_j$+>J1qlZ8-X%4T
zl~&?zEZe`K*FxAnC^}Q2`RM*CJr{bvPVFOkvwg)`1Jtd_)vy;Jb-a!#8+Vbv@iXID
z5nB~MA$kP5_v^_`EghGE0&vpcnzec9;uC+;{*?D*a)`3t@2!+oIXr7)+=p1^Piwdu
z@Q;jYVo8D3v{xeD#0Qdm2ek$LLdF!@stI9M3Qy{WKypt2c;}Rk<qCm_b3N8Nkhn8E
zXOYe@C?CC95to_A=lobG@+IXVk`+MCtaqKBS|J;B6={rS^Q4KHP~%xJ1ky)YAPIoH
zEYoyeQ{uBW^%Vd?ns8SJ-2Kj9LgOBManT1Vfb=~2ihmz7XQoo+Ueqsvxq37B_i)T@
z%v$nnCmZMOa|gt(b8wFRWi#bu4r>)!^t|hX@aKVF?srII^6l70c)5w45}r9UTBMO?
zW&qWFV5q+xWU8!FzVPIdQcQ*8#CPns_x!Rm^KF5>ecoCrt%h~2Ez+>?&7ZrecVlFS
z<kO-*B)KIH>uqR)!bm%69qsP;0-&rJl38MuTj3giieM3T2t~Z-Z$;O)gg35S-Ek6~
z^?RLGeavd|{dUrt9WD7CmX8z|=3|6dh(R(ebT^E?i0=xZPPugq+A=rfY8FCAxyCO1
zaLZoP^B$ha?jr1H1zPLjT+7Q%i;dQ=k{j&4l0rK9Qzu&(q{||9f$jVjnxIZ|a3+X_
zVoWf4v#{`?o#3@Eivn|+%$xzL<f_R^8Y&Rn&@KKz458kN|FiPCew3v{qby^B^~E1s
z5u6V#bZ8)l6Lka8%J6|(U4J^jE;uJxo$@xl;1vG*cJ!q+g6{*jsmmtFU1o_uwBL^D
zZS;WI8dKCmV@5d~YPKEo$ZJby@sxD?<=$}XqOZ!T^AA_o1?e&^ejjsg_HFgW2?_Pa
z##G!$l8@(`*ea4%AJj}&0?i#-liI+pdyf41TrSjcBVv1i({<OA9*SzI{3;1Pnm2Nd
z=)Uytmc<e4FRz-+qWe3R4XEdvt~A8n=h=j}YrjjaOm2GWq64Wh>r&g_qNdYj;j=qG
zlr<D7pd50yxLiVg^m>=eH(`^3a@XXI<mzsYb%{mS&VqR%yxGq%vjseguSSY7@_1cN
z=;DdWouWiSp6eK4R-O=KJq=U|@L4O+huM^TtY&%p!oxh9w$-z%J$9fe%-*0%sRCs6
zh|y%6kvS>RuKh516EiR4yzT{S6i$vP=gqUZISZq2jW5`-NOGenk(R*W+;sm1EAeXO
zEiXYhfzQVuPEbjf7;0FXn2lt0Q?WwimfU(L)x)@7Nf8qPIBZI1r%+E7GFE;dVA}xi
zn>}-M751s#o!<&tMLW3SGX7A6$8Ru2i1N--zGA*8VP*F9uIZwibn>VR1>+wDtUnI4
zBnk3tlI>%dC~Yvu|AXVtK}or^OL^TFhv-QyM2*Zz<XcjkC#=J7M8KbaFnZboowzXZ
zY$O0P*N;J2HWjx1I*8~zWCVw~8&5VWDL^ASJ}~i>h}mXyqHFd!_n9>Hwvw<P3Mo*l
zm9Z2Ymh6Ai^UR5~W4p5(nz8qo8&vbOwWY(0n(DjB7ar}iZeVL%;MsH$&i*?+D!pEi
zvh{5>|2>b&zghv#refa!K(Qd>HMe34TiVS_itwq@j6glRMd3Kgb6fTLTN<o<F&lX=
zGx@%Nk|KFOzRI}-@%6elsqK_M9=d6zGL2V68on0r6hf;5rb>%uKA%1_->T2SaZnO*
z<GS(U^D(nXxjfWuuQvhhIk51DSdpG3duv%nA}+Wm-DCZ2+Ygt*_H)P5pl>XFD6;Do
z)C7K2r~Q=gmVXS3=EFc;%cEEq-3GPiH+PD6pZ0U3zlk+zsho{v>aktr<rF<b*4yVE
zqa>#ET$@Y<X*d~Hgvt2Mcs?2JslVZ1Tgg+(oQ?L8RsW$RK1{a3E=<nguB3n6JwnH<
z=*48{&gmL7{`nbMHlAGUkZG_T`wpF(;7NkT3_c5@*BZ_Qzh%XydX5by&2MNr0PhNY
z>g?Pg(Z`1h6GN~r#Vx<m4*{vL4^pfNCY)-0Frc@|qePoCcBme-U_suDSB4PiE37!N
z%o3yS(dUVU4l&GH)k~S?rS8SKS7oQtmmg^zrn{Z)JFlkRyW?l7lqU8=TDz4j%B`h5
z^BJqG(f^_uYpQrGZbCG=jm|9YnsjKI!(MWJOSxLKVeAKi^Y^3w5vO3+M*hO<eZA~M
zY@s+&i-sqc9Mm*(#jF+|raz;$$siBS3(%3rvHvSW%|&TL&yWlDP7Im)ABW5I?BQo9
zW+MV!%gS9>eAJGAbmaQ>(KzT}0XXTdW8wU)bf8P~>;y~0KU3i>$wl5(rbhBqqW;e;
z)4s6+WzI&a_}93(G50$)PutMzOKNB;@~KqZWc%oc9VD;Afjl`$<t}t$(D`0#MV%U&
z$%}$nRB><A{;1uiu>;7V`IANJpEx5**}xI)5C#=z!jPS-E8A-O*||C*AB{1IJ6R1F
zz~$Hj(Jv!j(aW-RM1i37AD!i`F&So<UL)iCtqP%-H?~d-GK&)4@X)w8_o??UWiw_C
zG^9#2Gwhd7EY<~1F8|srr-lcS=?CWx^h~0DMP6Dd==QK+{_s_`Txh+1y@~6DX$QrN
z_|!j@5n!iUm4{7V6|p|fcv2(w1!`%VWFkn4p%h2dw(!@Uttzyj*0JH`t6dwp<}>C-
z;;OQ6l9zkaTz1>avq`(E8!{l3qT-&MEmd?kcH_ce?<j-3twH;)g{53Prt@es&Pc-)
zW7wSM%iNgi^Lg~MImG_yyOFY;-mYVN(^1ij1dde`^pWQNxrBn*I84t-QF}8$t1qPd
zN@tmd8PT;#Vqo89*kc(ga-gz_--?_*RRd4x1!s&E&GrkbBoItSr-Wo{92HORwl1a+
zzqRhP&P?wpy&SjUh1aE$)}=1d?5#hS|2653epdP${^;w+W=sKv!0Q1uLX}mY{u)&)
z4k+!-cxj;|o1MeX(XxhiW0d%}`Dw;#WQ_8Sg5Vmg+)>T%o-dHoHBbLRr@?W9D|n32
zAT>TCOz6Fi=dF|4K$3yDeFV%t;}Hes8uqDayqnqTt8IK>=$;npx?JIw;9%`vOwYSl
zq7W4PEO1ygMGIOzDEY^o8YlhO`6EYor=mCOA)H6EZgE6C!1%Mm_nx@Ky$VrK8xcva
zEL}95sPyk$LN4;SfMIj0l&SYQmK<;Pdq-sJ{9uQm^|<+yw*0;1$`=I5wR#2uE+W+A
zeVf^+oi<Q<_>x02!l3)nL&DIifVLS0w@;n2w`vXRWV`8YZZA{J*VZ3k#^8}JX`_k7
z2IX6{B})ic<Row$roX05^X!!_Ja3A)3-Q%Vqnr$K<+8X}YO;>rVBurqW=!tE?ag$u
zBXY=S>TB^`Q1<mhvM<W-5l1dN*Zq}FZDw1Mm$jS7GjXc&pm7>IOXI)mgfK^Ssa@*w
zy*ik|Fzx)fz!5VQY7gavho5LBHf~U5ohH3Kff@PSKn&{DX8gVPMB{U`!73-c!E?Pj
z0fz5K<`jcpXWBn0+DJl(`&7y+!eJXqtwl4=xA4AhRron`L}m=>X8h`&Z~kFto0WI$
zrY-7%<9Ek{%p66=Wko<>5}cH}RYe3L>UA;2&FkAsK_z;Ln<PUY(TDSmyBm1FuJuz@
zv1?>HF7IZA6+|*1I#cuSxN8RhX+zoT6-hQlUQ5^GOl};?A&G50K%_Cfm!5p?jV*IV
zojlYg7T8OiVNIj(;5gH5eUvEUCSomtH9SeQxv|%1hSpkw>ea3$3NA~z@+VeJp!Zpz
z{WDDprCvE4&k8^s!TI(`*9(6cOjTHD$RcLgAdXkhe;C+Tm6xfc8@LEr6*zwO;vc{k
zodN^Nz4ha5ZnxjT=3Ux!#qrX!2Frv%^I;O5=R?LzOl<E*JY^OUSJC}0#LByUW%>CC
zwb5KXn6Wx%@~@?ZXvYB%HODM_ltR5%l3{*c;#(aQ_*gveDS`Wt8X3pDrL}>c96tMW
z*BZa9$CW4<qW?YJmF>V8HKF<M2@=rr3`qnwR0p6U5{Oz4h<H5!7icXcIFrN8tIt4`
z&UwnYRQ}_$Qg^dD*(InvGvr{I6V=(VoT77mm+~S{f&LYTd|vX}|Fp|6Bbb*xC<h+C
zVgR-Y0q^?nw8~pLax-%rraM7<5E{zjLr{VyaoT8psjKBWKVRU2qN$t9%U@iS_#!MX
z*I{i?9?EXQ(r@>3f6xS7l<z7I&o)Q+<YU)xLIRh>928}Y6dvO2c<8|U<4zaauEj@(
zuxsmp$bYaG9^n(f8*k?z8!y2!$0Si;j%`fa`TUYhd+}}kE?Jx`moT^XH5%;go24&r
z#rrZeq-1p<A-3GGjC0)DI^dPlrF;==9@WRzLdB~MyWn;W^W%cePyW)fIgdbdpZ}$Y
zj&Vy9&=&-Y8DQF{KWoYN4_)9Yy9TQ6{wzKa(A+EgP)E_hz9dzf_lW%81xFvKkh;ZH
z@QQ@_rb5?g6&O4AWe$>na<17Fax2EOhQ5)o5e5+)REDuX&X4`UcMov}d4Bq;7Kg!K
zCEAZ(XD?nOZ-$QMX%369T8`1oCXzz09RP~tAxDzbUP`lr#-^e@tNxF_tm}ZU&U{b$
sZ#Msb@B3Hu|MTeo>CS%-U(<FuhC<GA#Rk-PaDX2|3weX2Ve{m_00{RG)Bpeg

literal 0
HcmV?d00001

diff --git a/examples/mnist/example2/main.py b/examples/mnist/example2/main.py
new file mode 100644
index 00000000..519b6b93
--- /dev/null
+++ b/examples/mnist/example2/main.py
@@ -0,0 +1,117 @@
+import argparse
+import numpy as np
+from pathlib import Path
+import paibox as pb
+
+
+class Conv2d_Net(pb.Network):
+    def __init__(self, weight1, Vthr1, weight2, Vthr2, weight3, Vthr3):
+        super().__init__()
+
+        pe = pb.simulator.PoissonEncoder()
+        self.i1 = pb.InputProj(input=pe, shape_out=(1, 28, 28))
+        self.n1 = pb.IF((2, 26, 26), threshold=Vthr1, reset_v=0)
+        self.conv2d_1 = pb.Conv2d(self.i1, self.n1, kernel=weight1, stride=1)
+
+        self.n2 = pb.IF((4, 24, 24), threshold=Vthr2, reset_v=0, tick_wait_start=2)
+        self.conv2d_2 = pb.Conv2d(self.n1, self.n2, kernel=weight2, stride=1)
+
+        self.n3 = pb.IF(10, threshold=Vthr3, reset_v=0, tick_wait_start=3)
+        self.fc1 = pb.FullConn(
+            self.n2, self.n3, weights=weight3, conn_type=pb.SynConnType.All2All
+        )
+
+        self.probe1 = pb.Probe(self.n3, "spike")
+
+
+param_dict = {}
+
+
+def getNetParam():
+    timestep = 8
+    layer_num = 3
+    delay = layer_num - 1
+
+    weights_dir = Path("./weights")
+    w1 = np.load(weights_dir / "weight_conv1.npy").astype(np.int8)
+    vthr1 = int(np.load(weights_dir / "Vthr_conv1.npy") / 1.0)
+    w2 = np.load(weights_dir / "weight_conv2.npy").astype(np.int8)
+    vthr2 = int(np.load(weights_dir / "Vthr_conv2.npy") / 1.0)
+    w3 = np.load(weights_dir / "weight_fc1.npy").astype(np.int8).T
+    vthr3 = int(np.load(weights_dir / "Vthr_fc1.npy") / 1.0)
+
+    param_dict["timestep"] = timestep
+    param_dict["layer_num"] = layer_num
+    param_dict["delay"] = delay
+    param_dict["w1"] = w1
+    param_dict["vthr1"] = vthr1
+    param_dict["w2"] = w2
+    param_dict["vthr2"] = vthr2
+    param_dict["w3"] = w3
+    param_dict["vthr3"] = vthr3
+
+
+if __name__ == "__main__":
+    parser = argparse.ArgumentParser()
+    parser.add_argument(
+        "-v", "--verbose", help="visualize the input data", action="store_true"
+    )
+    args = parser.parse_args()
+
+    getNetParam()
+    pb_net = Conv2d_Net(
+        param_dict["w1"],
+        param_dict["vthr1"],
+        param_dict["w2"],
+        param_dict["vthr2"],
+        param_dict["w3"],
+        param_dict["vthr3"],
+    )
+
+    # Network simulation
+    raw_data = np.load(Path(__file__).parent.parent / "data" / "mnist_input_data7.npy")
+    input_data = raw_data.flatten()
+
+    # Visualize
+    if args.verbose:
+        pe = pb.simulator.PoissonEncoder()
+        data_to_see = pe(raw_data).astype(np.int8)
+        print(data_to_see)
+
+    # Input
+    pb_net.i1.input = input_data
+
+    # Simulation, duration=timestep + delay
+    sim = pb.Simulator(pb_net)
+    sim.run(param_dict["timestep"] + param_dict["delay"], reset=False)
+
+    # Decode the output
+    spike_out = sim.data[pb_net.probe1].astype(np.int8)
+    spike_out = spike_out[param_dict["delay"] :]
+    spike_sum = spike_out.sum(axis=0)
+    pred = np.argmax(spike_sum)
+
+    assert pred == 7, print("failed")  # Correct result is 7
+
+    out_dir = Path(__file__).parent
+
+    mapper = pb.Mapper()
+    mapper.build(pb_net)
+    graph_info = mapper.compile(
+        weight_bit_optimization=True, grouping_optim_target="both"
+    )
+
+    # #N of cores required
+    print("Core required:", graph_info["n_core_required"])
+
+    mapper.export(
+        write_to_file=True,
+        fp=out_dir / "debug",
+        format="npy",
+        split_by_coordinate=True,
+        local_chip_addr=(0, 0),
+        export_core_params=False,
+    )
+
+    # Clear all the results
+    mapper.clear()
diff --git a/examples/mnist/example2/weights/Vthr_conv1.npy b/examples/mnist/example2/weights/Vthr_conv1.npy
new file mode 100644
index 0000000000000000000000000000000000000000..2a18baee57ed0cb874f1056fa1f2dfe8424d7a37
GIT binary patch
literal 136
zcmbR27wQ`j$;eQ~P_3SlTAW;@Zl$1ZlWC!@qoAIaUsO_*m=~X4l#&V(cT3DEP6dh=
XXCxM+0{I%6ItsN46alWU3=jYSFjO2j

literal 0
HcmV?d00001

diff --git a/examples/mnist/example2/weights/Vthr_conv2.npy b/examples/mnist/example2/weights/Vthr_conv2.npy
new file mode 100644
index 0000000000000000000000000000000000000000..6172d3e59ba9d1e2c58951aba64b6a83fa613136
GIT binary patch
literal 136
zcmbR27wQ`j$;eQ~P_3SlTAW;@Zl$1ZlWC!@qoAIaUsO_*m=~X4l#&V(cT3DEP6dh=
XXCxM+0{I%6ItsN46alUq3=jYSFKiqd

literal 0
HcmV?d00001

diff --git a/examples/mnist/example2/weights/Vthr_fc1.npy b/examples/mnist/example2/weights/Vthr_fc1.npy
new file mode 100644
index 0000000000000000000000000000000000000000..3b1ce3f287586b3f0190e071d3772f3d6d024342
GIT binary patch
literal 136
zcmbR27wQ`j$;eQ~P_3SlTAW;@Zl$1ZlWC!@qoAIaUsO_*m=~X4l#&V(cT3DEP6dh=
YXCxM+0{I%6ItsN46alV2Mg}kd04*aM(EtDd

literal 0
HcmV?d00001

diff --git a/examples/mnist/example2/weights/weight_conv1.npy b/examples/mnist/example2/weights/weight_conv1.npy
new file mode 100644
index 0000000000000000000000000000000000000000..5086aa214d585e0bc9e90b747f97f1cd8722f940
GIT binary patch
literal 200
zcmbR27wQ`j$;eQ~P_3SlTAW;@Zl$1ZlV+l>qoAIaUsO_*m=~X4l#&V(cT3DEP6dh=
zXCxM+0{I$7Itqq53dTUBsiRP<KnCFY|NpNO0|SEt1H%Cz-LRj5p$SL}0I`J=BSQ_4
iUIWA@4l*z-1JaLx*aL{~0WnC;4o3!tibD(x35NjI^eu@1

literal 0
HcmV?d00001

diff --git a/examples/mnist/example2/weights/weight_conv2.npy b/examples/mnist/example2/weights/weight_conv2.npy
new file mode 100644
index 0000000000000000000000000000000000000000..d9c9743cf519f061341b164ec2f46156ad456cab
GIT binary patch
literal 416
zcmbV{u}Z^G6oyYX5r+<r4tKj1G8FAlq~JA(Q<W|bP7+LtL$M_(E=369&_Sf&3uF)x
z@c|suOb$-&LN?#R>v!lI81ixcd;b5PoIIYK9uLkMaxF6(C)q`6_l)fgJ2o(OI8LW&
zbag&X<3#&M(I`vkXP40=;oRy3W+yPayxW1fG5>hhMd|~Q!ils)k$hidL@kygt`do1
zffjlLaOBpgn(0G{r}bs&{SR~Q(Hrnqt!C)mU-TE$=q<cYm_yC1ocbJk|6PgPK?}NY
z8}iMZow#Grukg<NIcJ^OBcppy>9;HIXViY!kO|%)`T@G|1g>25Kgc)nT}h^5E;R9V
R=LMej3$$i7@$}zZ`3KQeWYPct

literal 0
HcmV?d00001

diff --git a/examples/mnist/example2/weights/weight_fc1.npy b/examples/mnist/example2/weights/weight_fc1.npy
new file mode 100644
index 0000000000000000000000000000000000000000..b5a8e71e06811964d177738f24e9f20f8b7c092c
GIT binary patch
literal 92288
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
Nz!&M6D<J*r{{t4kz-<5k

literal 0
HcmV?d00001


From 3bb381e2e49fd6e8175e23401396f22a97b342eb Mon Sep 17 00:00:00 2001
From: KafCoppelia <k740677208@gmail.com>
Date: Fri, 15 Mar 2024 16:31:43 +0800
Subject: [PATCH 21/68] =?UTF-8?q?=F0=9F=93=9D=20updated=20example1=20of=20?=
 =?UTF-8?q?MNIST?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

---
 .../{example1 => }/data/mnist_input_data7.npy | Bin
 examples/mnist/example1/README.md             |   4 +-
 .../example1/examples-mnist-ex1-network.png   | Bin 55501 -> 79037 bytes
 examples/mnist/example1/main.py               |  63 +++++++++++++++---
 examples/mnist/example1/model.py              |  46 -------------
 5 files changed, 57 insertions(+), 56 deletions(-)
 rename examples/mnist/{example1 => }/data/mnist_input_data7.npy (100%)
 delete mode 100644 examples/mnist/example1/model.py

diff --git a/examples/mnist/example1/data/mnist_input_data7.npy b/examples/mnist/data/mnist_input_data7.npy
similarity index 100%
rename from examples/mnist/example1/data/mnist_input_data7.npy
rename to examples/mnist/data/mnist_input_data7.npy
diff --git a/examples/mnist/example1/README.md b/examples/mnist/example1/README.md
index 80ad3aac..2a19f296 100644
--- a/examples/mnist/example1/README.md
+++ b/examples/mnist/example1/README.md
@@ -1,7 +1,7 @@
-该示例构建了双输入节点的两层全连接网络，进行仿真测试与后端部署，可实现MNIST手写字体识别。
+该示例构建了双输入节点的两层全连接网络。
 
 - 权重及阈值：`./weights`
-- 测试数据：`./data`，数字7
+- 测试数据：`../data`，数字7
 - 网络结构：
   <p align="center">
         <img src="examples-mnist-ex1-network.png" alt="MNIST-ex1 网络结构" style="zoom:50%">
diff --git a/examples/mnist/example1/examples-mnist-ex1-network.png b/examples/mnist/example1/examples-mnist-ex1-network.png
index 46009cb557d38d1c87015761747a99037d304765..4a164107c6e91bb8b48d6d8cae35a63c37bb05a5 100644
GIT binary patch
literal 79037
zcmeFZWl)@J&^9=@B)Gd<a0u?fU6SAu+#$F-!QBb&5Zql7+zIaPKEZ?SL(cnsTa|OZ
zt=d2PYpaH$U~2BWpO&k;ukM;qB?U<&M0`XL2!tdpC8h!bK^uWU5N+_Vz<*N697us*
z5DqGm??4q}ga^PM2%n`i96%s}z?UD0nX*bp5Qr2cEhh58RrfdpCMDq`PXDv0v`cb6
z`6LxBd3XXmc1}LL3{$x$q6~dIJOeFRwj;b$zz{k*qD&(x>EufD#b~P6+Cu6=s0;74
zPv)M-!*cUotBdE^eU`)cPd^DrO5y){t*b%uc3$_5N%=zm=Sx^5DDD67)`Og{e?*pF
zEgw25#DBc9NxKF9^GabzZ)#zYzVWUFB7_*wf4r1pHi-Z8NKyzPjBL^^)Ai%1|CW|^
z;4{j99vS1Cg`gAzX8-Ig`CnQPhQu^#g8NSeNOg@v(+=F?ako<Z*He;0AhIn({U3B|
z3LN|JI(;Sfzn(G%1cP__-$$aKvjfL^!;YQ)w@AMJuW$bQNQB!|;8-CjQ<wi12{5O}
z|M%v!^FpD7J0G~RD9iB!Em-*WkpC?mDk<dmhcWCC!`fzTOryH9&3uq1l-a9waikf<
zH#_$9#>}93*!7g47R~SkD5clJ#Go5cIxH&GdeST`VFLZ@Y((F5kWrR4bQMMy1aqBr
zWhfDd8tN8VxD4f9f9mhsgdrCZntltGwHu!$zHYveMr2#W?tJa50U86D6~U8STd0Cq
z(1o4&V4NZL&2K#e8Y(an;y8}rv*~?Jt?TSay551>A<|v)qPbo}jtGO;Otr32d~-mB
zP_D-k_fg*xAkQg$>BG)<WWoKzqNWaiUyqsut?fp_33m?X8-^b`5dDk9g2A#<eV|=Y
zCC08}a}$dltxLW8V?l=kKbH}d7Zhn~yvbEqG25Wq4K|fMC<Q7T*7pbmO9$Ea5j2kX
zG)pARUJ&HDirIx9=@sIkR!7clUQ&Z5jM3{LA?sFd%tq^g&P<7x*)gXXyYp{{YLn?o
zywSgiI%+y+dUMv_3qg4OV?gxKE6zV+3yY+}_3LX+c-F^sD`Yew6Z$z18{D24iZJ!q
zHBy#@4^K9$fmSVZujl+{EtVY*klu|@g9?yVDV`xiK%bW-binCoV5ws=-yo2x*}fsZ
zFUs2lc4m9jF4-{dZG(@&z3=JuR+F)8Gay#2(yjj;CEQf&L-$oqhMjb0VG4W@Rj<3!
zG!ZQrFxbxGF^!HZ_i@7DhR8*i6Z#aeJ7|4ZWR9^*ZlHYOOq{kIz=9>#Gf_S9XyZvV
z_?$`bTq=5j=@uZPfF*Xj8;d+o+Rc~{?jphj+Y0T$IC2_L$X--W?j4FSFK7p%PVINS
zjYLl-EPmga1=_)lV!!~^ao_=}8o?*Ge*;}3eA6#Ms}(<Plrpt<+GcKZURYh&jS}Xa
zDpGBLL95$+?LSIX&`Fc(hE9>^22o&Ci}~MloRW6Pp;I*s^Qj_*;)GDxiHC*ng}GLR
zJX(p)R}*Wgiu<A&D_PZ|PxYy0FJpq9IH4y;;e;`jz|iR9_*&Qq>y{w&iNWQbDaoT5
zTD1;S^k`FhP_x2S2f1UjN|v$ozk*zwV*L=%<q>&b2rY%s@$-)6oGv5L<%=fKD;l98
z<JLtL=|sNtEcL_=CT0|XhTe$y5G9Tppkh<fRunsZb5hwHn=hp?2y|`SRzVy{-qJ!^
znqHQb2<t45m}>df6f}5yPy5|HgTvaJN`|o&)YUrnrseLAHegSgnJPR1I?y0nk4vNm
z|8KnKCi^3o!!K_JWH@>x4fi8Bh?8vZtb9_#W>K-g*bf@$7vgMhu-Kq~d2JhEB!Wo&
z0_s}SM>(MB-N(!1O(DbKi7rNl)Hr)G?{vERuqzWkn(P>PezcyBKUOBc4oOQ<jc*uv
z@1w`&ifKHjxzKB$nrQjqhihkU&EmznU9~wj&A&ic3BKt<&<aV>MnOt=?G2~_4r1Yd
zNkr*-wl|cuou&8t6I6){c)BnHfg$drG$d@PDr%QB(iS>%x~1w|co^OHpwUuU!Zd7r
zapL;SdMQeuWai4sz&JFJpfYc=<7%90`oB~1x&UNm2g-0HY_s*R@bCILNjE_|cCsS(
zg3=<?-qy8rnYiYOLRhL#D_b*-7G2sgXslue(^A>G9@KM*l<(s$coOG1HT&v^KNCsY
z_m$3yAk3FOwU%|3(@TvlV%y?|RvOxLU>fzjGS8Y^kf)kB6E_Xm-uoM!gdxAeyKZ@@
z*HB6SzzHR&6$8hhF{dtll~`|m_dlZil!V$Zc_?jr7+&GgoBtrXc-SD*9oH^h!@a<c
z0L`FQxSjP4t2+L4QI!CFsh3|gK|9%Ew?JANn+^e<VRx8b_V6>+eY`7NsF(5j<ecoq
zC-%REh?z%l{Vm841=>XYWbJ}wXTs~N2L;bVyGBDd&~pOctVYdhs6t0z#Nc}>IL{E5
zv0oP#YhL&rswgpD&`4XYY)C5KOd77dmvYA0wAO#A%%IcEyjv9yEkrCvy3n&}as8|6
z_)6c~*?5Ncan>?&6$YVmO4*63k)o!oe@8gHCgiFs3ASWFkb((qwbV|K1SuOc%+5U}
zOllL+MXU&As#Sv<rAfFOsgA9e!&gv>t&~Xnchp*O|I<~M$*TPF4#SUyR3L<&(%vBa
z-?!6c+1j!060+hn#@mb2Jhg0NY~pS?vc)BH(+y(jsT+|&3$TC32&KV`U*M>rSDF39
zF@TVg!x{W_MC%ybm`nj^q#ks^8S=?WaWuXnN?t|%?E07RPD|u+R=o3CHCf&Kk%D&H
zhjAjh3l3jm{C;ZV*3`uI*TSc;?iRav>0&HHhPYEmiUdw7dh%I?*jkqB8gu<#HUGjn
zc$XIu=2-GuD$G$edvZt{(JkJw;mD>ddr-5QP&P-jo&E0i{{>`?*D+9C8nxVvxswGD
zpU1;n-%ZMgn?_hEG_SHxd?}Ndr7NWBj?3Sg&7~fyr(M|oHt1AR)Xq|g0P3Na7|{c3
zm$lmy)2ofzxakX8`Tt$!p;JKUwWG+k{e-8I3pP4PJSUoMm|xeJlG<u5FS5i)c!4ut
zE~M0uq_5=_@WdA9>WVlzxjf<YNmjxaU2WurA;n}OfmCLd6i2qVpM5_<3?6kTbg!2s
zjtQu0B)@$dn;lY|{zHoM@?-ZE9ReEztImV|W+cV8Qj5(J3b#}9zx`AgvI66L=e~*;
zA0dtGtaDS`&^oS6+<W^b7-j|V5WG*QAZhXPuUz(p!-=`hLELY9(~sYvVNf!rxO&Xj
zYJ;At?QeKN!WAERFdRlGq-F0*L2aiS3dz$8YqZvNtgg#abyhy9MxE%fvh~bJ$AUL%
zd&j|lE9FOoFY{{f3E3gir<9GpkY;2uwWP2&jjEoJocpUlz<}t>*`TEz%`QItJhcjI
z3xksu6a}pv%G8;M)*1{`w$Jw~@W#?BJOWXZu#a-m<PwS#3VnHEP`@C6#i9bqUF?eL
zCfa15c!EeTB7I6E!%zG#6p!&eg7yRp9-Cp#LIf6+(c7u$Wa)cGW_tiQjzPo1Z`$x}
z6HJy#viepU<*@^uuTL`t?JQ*vg3xIqN83fyq`OtTh69NcUdD&k<(CXZaV0zld1i{<
zS?umwLrdn)Az?6Xn|)8gvA_M*L0c)3tGYLn@6E^}>X-Msa{sQ&KWF#~tp=A%awyml
zD?NJ;#fUWe9*Md%OH90!SfR3O3}B@X1eMzoE^ba79|j;lL4ZQvS=;2j)<_n#QxW3v
z4Go*$EH3VG0%SZ^wU&u7xLdMD+N%2~CYGlY)-P`jVzp`5lCD21>tVAsj{IdLS0?*+
zTahEvm37wrhC(`*;+>K=yIEY5#5<?kN&nNA5c$0JMligx7PjEMir#S0d-=d9dwiGG
zVVO6U2*+uvB@_n3wn4XV>{l$3;&_i0OF4Z$kgHoB_vNOzE`{Jk<uk?Ovc)f(_q=i{
zOZ=e0cagBJyYDamcjF_ROSXP?qmO0f0x}$-RfDQp=${Ta^<t}j#b%#4z{^rm34^y_
zC=W5hx@5IkPyQ~ll$w~UCP=N!U~mA7L78w=zD?8HxgM(E;q}hY47@1s`E&C^5Z5<p
z5be>^4sUW2=KAV>mi51`Z9;{gzOOnTE)4vk#1Y!~I@Hqp7wbIW3UbH(5oL`%pIOI4
zPosU`#qnxxRv9UAYL{iS9iN^`B49Gm)qlKSi6L&ONsGK<bKM+B{FWL<iy;LTjnvOm
z=+z+`md7mnSK8DUCq)G`-9-T_2_qfKsQSv6G74PqPyDUJ`d*rp3W`f>oD4^jTFWxv
zaiqn&HW^*11aERsxSWj$*eqW~#lDt!1yRPSU5nm3sqAjUjI^fDZdkr~pAJEqT4wfN
zG5_*}5g+2F+j3tokgyv4W7SU;LxZ|0NZDVG?&o*#yOFAODN$PIiK#4Oha=~UStj2^
zHn=v_+2`rs8I(bgR-1{HCvbE4aY|o3`Yn*A7}HJA|9JYVaC?_3oV^<SWkD765%d5@
zT1i3*`v+ILc+Y;TPzlsk-gNKD3|SmVCh#IyY?nwQnxQFeGiA?fP@z^D>Du?c0o{HC
z*Ol1dE;*^axvwg7J$lP#>BHm8<vCB1M*Uae<M){wwfII~|C@<x7$j*9o2RwN4N!W(
zR$bFBAY|uOy7<SH6lY9EbCJswDPi{gl1X#Hx?xU@rl-!0%CAeZ{1Eq3+F-?uLz=`}
z*HWKrD6~JyC|SkYm#i2p%(bYG^>=0^_3LU!8TKe`D;<)LFok$H3hsq(dFjUNs+E&c
z7@s&msa|b(l<X6BAQ()v9V+I_o5;90&98Cl%x945#|EuHEo&MP!b9Gd?wsT81=7Ra
z9Bo^FN2C@`%%M$3Z=ovPX4oSe^e=~@T<7%@ZbKQS-O;(S-hp$z%UL18c6>=4AOwF8
zX=##j8-F>$j>4%v)QD?75K7{)WGnx&mjyMYxx}x5aNOFFUd~}!<?@1#o@li1QsINd
z76|KFR8&{41c^Nkg;^r}XjmU0!7{Uj)|&WS^c2Lx<d`LR)s*ZXnLs!?R>8f085!uw
zHeX7vrjQLUrPaIb_UkCvDxg?5f=WWg`-OZs@Z%Z)4Y}nSTWHd`pbr=u>&!?5(qReg
zRxOGNku*1Fl(3O`(-X!JR%{{Y=2+25()jn)Y9rbau}9+a3D-L2s%@G*Ui1{cZumX8
zXyPhR1IWT{9+Xo*DL~B-+6{;5yUj~6oUK(0YrO%IededB+g5Gk1e^WGT=bN4-z>OG
zd&d7QF(LZ-wpUZ?hK?fo-~c148&1M}aU5-bW<8e?Zj`Ebab+2qn1p)g3*IhK6CrK>
z5UVAk&<Hhp&%?e!<L4k={ocBA)0xU3pqYijI1MT#I|Ppe@^)1N4p|TfylpAEzH*bu
zc9dWxQ_<rY`z=>0j4RUZtCdR-m35nWUM}=T;=1%KwV!_$?C1A}rbrMBZ1nVC7fNxS
z$iK6rRF@azX$OjI^hF}c(x}HXjIR+Ec8;WXlh4rkGetsII|qan*Mk|eT0vb~YtYr7
zy3U$nGYA?D{YqX=EM5xfej$l8Pc{CQJ`ODPlq!NINNEz`8XjUnn>Iy+k<4ZXMjuZh
z46B(}LyIAF+nqm@g~q&t9K`8)Z)ru9QhX9h6LF~zq}e8ltLe5eHIU%@CsHPBH&D}8
zfuSj$8o|G-y+8s8m$l$80fECYTG$P8Jt<2=_YG})vY<7zpqufWAeUA+e6oK8z11Nt
zDQbQ5?A}GnlrYgG(lcsNfu235ixuic4mrXAB;p^TJ<ezxtexlqJK_cLYp;o^ryv-V
zI2-ylG%@4vz3i_B-ecI}fYEEN3S=s^IpQqk4af_n9&iqBWJN&+($D3+V&Wg6V8cz7
zP#6={gZ`~tx))&!^zBSgW5u05SDnh)Bo3f}(QT(^tYq{b|8y>;A?tSY>zau&ck!;Z
z>GmzwTZokJRg7iR<I9FRWgDoQMQ=!aiI`}8XLVFz&cC5gsPey~oUf=WqEe6R+qiE_
zF)Bw#!AHxb{MrBwk)(aGc}2b|FeYa(GmxxqFc;GFQ7X?Pt=9RD=Wk8M2&Y5&ww`tW
zV2(sjzQUs-45F-xb!ie9Lb<Hqrc$qzobPz)(6tZ!WH?Fhj-D}H-gxu0D`uymKNpsN
zzcBq8w97{~H;`YvEdKC8ln9&bFTjLApHLwEuo~RG`@)v&>|&nbDxZhFS!K;V4Xu&9
zV1fY0l~h7s2^8g+BP3{}ccFpe3S>@+C;x+lk^JB1$o&|lr>ktlub9eL+DwpYL;rdM
zKTywv)=nuJCwAd%QVFH5AHqRVQd5c>n4U5A=G@_5xC+q-4}E|CS^cHjscx6#!)3$u
zG8_n^{B9xJjOIE}o{<IrMq0Q~UPiS@CP+@XF@1!G$JZ-Jcwijgp#PF{S(Y#r9@j4H
z@5F~H1^NBAAffXg_Qm$%y9{jhs7z8Gjo*Vrpvam%lAOE`qb{>%#hXyjMKzh`4Xr5Z
zmf{azh@yYdz&XOC^MKl3+J%U%O8<Q0Q>b+hQMpu<1O}0u^BsgjRv8IOgqY=t7{51~
zgJt<tOp32S>=1I0q==0F5#T=1{u^H0WiQPk_u2>v-QA>kLade0WrE$<NShcGl~m1n
zYi_j#y?6*3t5rlFFT;PN1RY2}ZxZCAKV%@MB_4<!q|IjZ+Z=Jdron<?hum*E=$1_s
zq76cr->9KUJ?lR(yiNAShN3S8Uc`0e*Vn$=d^pwXSSK^;lQ59L15q_EUUq$PXOQ{3
zRHR(zgUmS>B(#4~toB-!`D+N1vnJh0j<=|!T1YYKfqzFGq!?+++Je8E6=!m|znrf#
zYb({iJQE<$rP=`InsT*%Z{*+b4Y(krm@n|*u3D{s`wu#)Uym&C?xv2%So+_$zj!aH
zFmN<9JpccH@jrtKK-G?x`0WLXZBu}@N!#G3b?OqxEpZtSvUg5y*Y;R66;0nC%za|(
z>>MKnzeKD&^zFk$Ae|K=_zsOz7S9>ufQ^aT_E>bqp@p(qJZBCIItGPz8`^OJ<V8&s
zql%IrsE|Cu?biNOjoefTX9Lw@>HCC!$&IqEw}1J(Zx~M~8~4t~%yTY;eFGA3il#Ek
zJrPI{?Lgoh=ei$n+w9bWm20-ML`YUV2*Hf1YcE(;WkWe?Jo;R{Unxtx=!w-l-e|hL
zZ0<;J`alWIJpn3aRPv$)n&@frs9LmW$~v;WVvXPKQ;#*t)y|X&-M}p-GXV|6GdeJj
z(Oc~}jfAt%!$7XMcFRVtxLP-pB27Rzze5`;-TOU%_wYFb&(bwm_=c6$ICJ0W>T+TZ
z_B_l*)2THvl6QZWYUV)AYlXs~ajE>anf!mI7wfXX?8H-g?%Dc6_{3+|?>H9jP<YaG
zjS^KCP#k>al_MvCpiny6=H4phgp-wA=)AfP#{N&#37i{~rBzE=7gXMd6v|NV?@cyn
z_w92PH(D~J10T*Vnr}Sx!vSCuB&*seCBr^Zi2)<*`f^x!W!tD%TXyyRh-z0{?<d+~
zz~Av(ypLEQN1#-N^z;tA8M?SbTRkEut3Bd(_aewpm>a@UOxXswW7)pxfpkF*wtV?e
zM{^Z&`EQs~8Eh~rg;HVLgYo1Vllc>L%9oe!>)?1A*UNo`Qz1|P)*F(|vG(95r#(TN
z<&Nl5uCvXdt5(;`+fe!x&cmzUB-EGRSVt3Op5Dlc^y%d<pdj4(0%IK#VWeDYK*71a
z=iilFv#%jOa7sf`exmH!lXSI(78Ls7;T2%+oFUP(Ef=Rfhv4o7#|ZvZV<Z*1yuePX
zHhVb`%fZN2AbS#jpxx?(gTu7e*F4N+cfE<E-E5~OE0ml)<wbBWC1huC29JPAh$$gL
zO`GHwKnigKuM}e!tyMg|>Bsv)b*SC$m+%QO*DN^%`ey~-ag@D?cg@gQBsp#FIjqix
z&iRu21+xA&6W#jQ1Ml2wvxQGb2D0cWCX1x;Vh~o_97u}Bb@~Tu)$BG$u=))rL<sHr
zsHMYxevc^+^_LTFc+E!zafS+b6;agpMMRY8?=5VrcsMB2s~ZEV0P>)tuU}BKxxi$R
zY_xayrDw#^m7rulPsgIh3z<q_GR7c@Ul@yrZQJ3M2J{jOx<?p3>-JU0Cx8C^;B?<T
zDS{#p)W6!5>^CwYCPJ<5jNC5*Y4dU!Y#r*iA5c#4j7bEdfZ>tM%HBazW`}~ZNWQXs
zu_6-`dgpxL@4g<Ze8dOQ0&!hIT_6|xy7$$d82HCRERWaM?96c9CcuvC>)>#1*9U&U
z%2u``$)HEy{Y(yOSOXPIBS?`9uQ=aiK$l?j0aEKAxI<DMTxO(jI16S!qZa}c0Un5$
z)ii$~CUy0E#w&*RQ-<7$f)-xQ(tmfA6-py02-}s2qeQl4zVq1sdLJG+V|Z3wJMXYv
z#>!nqv{XE`H3e=bZ?LqPe+5G~;0i&WM(QVwmQ9L5`|If-8P4MQGx7&!ekHgt{(CCF
zbD9^gsbu}5$ES3i?G&Vd>^UF((s9R<_qm>6e%dQJ8z1DsJ+Bi1cWfWx2b9LsMKlw~
zmhV3WzTI5h2`3-}Q_=9Z_hb+xFA9Vz7MZ3*nHH(T6~qOsCg?jv4J4h2msmZE{Bu>M
zkjb36oLnlUyBL(~V2h9rI?<ctfoR0>J+6Yh>;9C7g<!F(6}R=b4QE0~US+GQb6N&Y
zA?fn~FjV%7i}cL}E(jvrzD!L?ejxc50&(Cke!hVU!~vN$r#xh6I$*4gc8He?udc3+
zc_qtji>3}b>apr>79bat3ofT1hLg6Bnzb647g8Hec)n23FjF6E*03I25m8^3u`VQU
z<&tj6wpgV>d%jGzqaom$+=z>z+CYM*nQ#^)P$n0YF(EIgwi-VEqPt3FQye@jc4Fat
zClY&s5{qU?+OI-s%&jPk4bd4Lfoo5^=4bft9UaF*m^$$JVes@~jaw<#;a+CKARb?x
zb73OkTkrj^a27(sCODKaQh$zqHNG{u$^XB00sgthWX|S;+$<*Vh(EGZ*^*DiC*(Gj
z92ONy#l!Fl(ZbQ-=*&-BW1V*UBm}E$?qy!ZlHr3SlG@kTfwTjzX~j5;1Y91-5(-&<
zM$+*HpN&lG%#_w%mDhxRrW6*TCRF3_R^V3(zWM!2m}vEAcp+Ap^hFS<-yLUZ<0xzF
z$VJ30QIT|L_hLdM6IhLzYLPPH%DGZwpTAc0J1jikxRpI`r9?Vk!o^e0wDVPH^>|0~
zv09QE!K8+rarV}yaoIinGUoUG)k7DLIT%l29ELfN&I)C3IvlkZj@cJ(ER#1T%S`4F
z^jhKQzO*aq@g8hnI$L-umax$1$cnf-xK&A3m4!+Uh#H7J9GL?^&;O29>|hy4G6~=D
zXjCm0oZ#WT;P5VVJ1~=SXIq(MjkvF1D^Cyuo=Tp{j%f^qY>Sv&|I;+HcJmj#29n-H
z0+({c1E$0Crk}T&99$l+v<DE`-uR}uoPOG_JCKM*_ef%rx1f}d!<@5Skx|+%!K9mL
zdpg3MZpNrF8QNy7uxVuX=#{BEnOn<!3Pbo=tWi+2WL;x$3*<wL4oiCWEg<L4CBq#8
zp*$7^4Ji#sDLi@OwdU!4n`y^=IpH?VT<<6y_XJIvc;|_@GwQ$iF;o6hEg`+UT3cVU
z@dREWz1cwLGE?w+FbzYn;;y!qv(A(FmwyEBpxTmmAY-eu#)#W$F`8?^I~XIGtkv5a
zEtgY+?kJ)Z7MDzL)-JWdi2qLtut6%DX475SNa`ybr9yqf<qm?PzQLwzW}S$LgJRv^
zuifFf<N(d$D0WY{WzT}>0>c5f{1M)t6E7Tt0U+%F&OrAD_-=!&OH4@z%}^Cm%0_S{
zPTYYk*C19*xXa^x!~&S>nuyPIWu3z7IDW33Y$!02^y01wjLWg*@k*)4TQ{6gqh?+^
z5^bt5?>R6uZg}X@?J$9^+GLWe_(M(pjp{^X(i5*E{FdpsNF1f~`5;`ma@i*lE=~Q!
z9$}yab**GWnFg@_kB{0rQvywhr#Ez5$JzbvMfXjFXmfCrrHu5PrbpigS3x0NhDS$Q
zMaEBtYb|@2&cxi-E6)N%nbY9Q-zxL)Z0PWfH~X}s{t=kRoL1b_jOu2}G>TEj^YvzA
zKzhQcf-&u<%uWOlrab>$Eg{NuPP2`s<S10VstN<JHnRQ(LQqJX3R`pM?g761>ersx
z7Ub=rcYPGz`-17IVs-LPp<r}puakKn{H5#6ny<;H266en)dUbO2{`>nw!ef=IPJ3}
zL*q67xU_nNZF1iV5^wJ~5&VHev>3cXy&3o;8U&MiuJ!%`5Bw(-p`2U+h>?W!dr9!5
z2lpMef<m6-+?XCLg$)Y1Yi1epp#~8*s#6WLc|x}=syAV+bk*GwF{w5Cl8$#4#j?O-
zp1$3dmD6hL$<1^fB-Cpk@}TcelIoItS!jW`ig`N><rKpZ7#;K-sy@1_MgyoyVZWeU
z2msfmFju8bg%c9h!tzeDR*qT9*!*x*8r{935}1{^2`fHQunpCX(Wth=z`xp0^<DXy
zI2<da#^jPxgN$$+2`I2L2U$uI$a(%Nwi!Uka!ntHK%)}@`upKA2x#x@%E{C@R+)7R
zLhS3DF-Xrv%A(YeX2SLlST1UYFemQAq_#^&=T3TzqJLiEHpJJZ{W$b7lR**En+n(+
zs%&~(#Y36)mOPz9cFVq|w{ez$3=R8}0G3~hwcjngtz*hZO9$C$M!JeBT62}E%QJ=Q
zt1yuCoJ4Xl=vpXV_Xq-(a?Uw;l<p$C%LTHu>U$iBY!%1&Nl5qrLi?N0d9tAr7kl}0
zm;sd_uUV2m6q#QY1)!RF#**H^KUv1f*g2!GCqWwW0Y<>lqWuMH>`vIEV);wx<*UoW
zp@I6t|I3l{)=*?Cn8RtJA99EKI%K}QzFCZUfKb2<v0&9a#dj`eM=0l0CjVD%Vt#MP
zR%D_d&BMvD4CX4^LrF;DS!2;Py<s9n>|R`N>#4pF3%U6xrg7>Y=Jxjac59hDW|y4K
z5O7r=jAwA)t!ePP-lC>X7D@W?H!E}N32u+ZLh+#xb|oHholA&06`e>EXgQz!SddMQ
zIB2Xj83}pkc9HwJqirCLl_Ke(g?Jq6P2l9X;8q=Dz3+(S-V@aP^UYe5{Uh&Wk$iZ%
zMs2QKwJAq!!|CyHZ@7Aub4GRKAr`%+r{~G8{6mcw-xJS8mfgcn7!Fs`E1En~429Cv
z&rJW1sU?w^JkP)z>OAhwb*=n8EKg1Tt3<lMOYRqxzO%$IW7f*`koYjeTMZ~Iq-x?a
zeigfo%~UFyz4OTcll*w0TQZu(YfvR3iyg-&OCctHSzX>As<BLuB&+TYWUf+R-$MPI
zDP;Sah2QHyk=y64rrPtGA=U2po)hxXs>eA<FCsb!niHFh+G!|3>h1$#h_InGBmQ*%
zv>()Q1C3#f)yGn<VHbjd6s8Pi(iX2dxx4okig*(wjB94=j=IT}I^8KGCI)?q!x8Ty
z7%}vVraaDaW(bhd!_?i|iG^&JOw!N3$)|xSIkB@EtOFo2`0&y?Je~!E<i1AO?v4gm
zu{MUtB(hka3+I_(BLn3&q3X{kLf35Mvn#;mfb>yI;V1l3@5Wqut#M_MbeIw%3W!B5
zu)w=N;_MohE0@s9U=HFTcB7=Ro<866&pz9Y*bDNmtnU-g+?%Hw<>D9#;<KQ#Co?vF
znyFj0Oc6Ay((w*fNEaSfyvG#~us0o#I%U+#ULF1znMpx2p4s~_W67d_%FplqFh3vU
zS|sJcoXl)mJ4$qavsFs>zS?<MwWqI7Gr^8}Ammo5NXO%N-Uo#At<(Rz4msG$4^l!|
zG%$vzRMqgjaqXRoXE+bKQB*pAD898|pli~ldnZ;4r)`i`Dm%du5uei{caiifoOjS@
ztc?C6H7Q8@EM`?dr;2`D^!_Y2e$}Sl@;Xx{mhe7`s5>7fyvp&>eJY(knd!?ycMx7L
zgJrAZ)i>qoI~%Y;9!^YiiGM^yt$s8y>Nt&uYOWNTRfYftT^!BaFCv6PHXxea-S~+C
zJSV1jeFzKa_i$%pU5YgSrOufg-g7+n^yU`FyoPCsh$<<Y(@(n-%c4&qs{a-^XYH$`
zF_6_r)SKhOr2bm1NHX!I!sbg8&BZo~dcJ2K;<SJSJ1fh#89b$M!Tp-F8NMdu37g|}
zWO2_5QS1LIy@p>2tFbf&1qXKTS7@@kZvf|gP!#wgZkT&+v4ex2@OU&qmbV^DA#38v
z<A%uje3x7j!7d`vra{fDZPZp#dzgm6+3t?~;6=!>SjQ37n@LKcOP#oCiAZ<vcJJKx
zyimhKua+~4V`q>Bd@QiyIsleHyinD)&CmAU%f`X;y^pq)oJIwrfc;0Sl?3U5<SCUE
zuTDihe!ct<yY?XY$Fcq9ysz+VXVc$80kMCqc-)+uM8YR{Uu)#c++ljJJn<#j&YQ7j
zptZZ>!xSlTA+qIk_(%1R|4B}N5_38c0(2Yzy?*&;_Z@c+=K@=w&dAu_m_YfeP1_a9
zW}uJiG50sILTGY_(y)8%=ruXrblkynO58XS(^LLLWaBzp7RiWSG@RS$#vZ=5JGx=b
zFFmpPxVZy<H?<pMDS%GDJO1S&a+UU4uHvz6rM&gP5Y5;-iw|xb({<4%W9{a&m%e<-
z4Bbc!b4af?NjU}g{@{6{L)x(QBy1n;Zb!`-2Jhl>treS*r7yVJv|RAWFk)#_DrTX>
zl-a^-dTgJHlGW--lbb}bKuW)Hbi9MuvTZj1>t(0)7(;&Ddr2`ewBQexDn*<I&c|Y-
zLy4@v<8=qp$pXan9%<xy&d&-{pQw)-Ou@MzFXQ$(Mi{)a>eqcqfS2`s1h1w5?Fq4L
zgBZ}Jzm$OIt7w1H6K|T1(e!TxUmJh7=DBa!qCX!t(Bi%?JOo@_7#1<>U)d%tLS~;4
zuGIF4Ng667_($ZoJXNiM282e-&D-5?Z6-ji)rP#t#0C)r6thjv)+2=1iBpdg4?bC&
z{aHS&iSd?vX+F2BHtCqnCJ8q)nuWij_>D%yF)wi6G{92j%Kvn~iX`T3Fc`QbCi-Gm
zyN6p^@!N#lqD^V=beS^5uDMVC7?F+qhtwOp=0z&bj&al5V&xxQgS$inGo@@u1Y4KQ
z4uwKDW;5ubtuD1ZQN?FI!dcZ@a#^9KQ*+Npk<O6>3k=MV+N<~+jBPn%*6OxXt%C=-
zu*$$z>;K&$;)}@xJ%?EM_na8v6f^+lMzE(Xc>mGQSDk+tDc?4u)ahi?S4NT<IBp;5
zaGiS>%OyW=Z;M~#Xot1?y~BW$=+Q~5*4Jkokovs3hls`LZe}!`@Dq3aBfmk9hiE%7
zg<MZsu3rE3{zQK0ic`XoJk^?wSs3_N_e3SBF5Z~jX8s4y#uD-BFUon5U|p+J=$%oe
zJMk&WDCktYp!H7lEO7?QLb>_YTgid+6OFa%t<M{WAJhCt;IeMImp|GO(~$R-rE`DR
z|Gbi{)gJ8}iNEmr@cvP8c*1*~bc#jcu??H2#>g%R@u$P?=9Y4v{7w(w?*0%~UsvC3
zq5DIz&)MZ_YsleaXt$uz2)d;tNAp+JL%b7>+;jy}5DdVvf?7ygxBV8QtDq*ZP^KY#
z$C#u^V^Lp75S*`nm;%Y#@Q5%x#P#>}5lo@TXI#a;m*y(ey0jv1FMxJt>wbqXCpt2`
z+2U=6jhSQgq1Q1Idl^isUk2aC$d^}r>#e3^dR>uPjS+aRlLgWNWvOgH_rDoa#us@s
z&1phyZ$yq6@+o_<gDO0-q`ZDUd{pb*W=}D-f3R!Ld~L$cn-oEN$^j|uggya})S)B>
zP0ZRLlzNZI!|?#PNWXx4&r5y(3L!kKFJOmFexsfqC^OHs@d%A1K+&_K8H{|o9z6OI
z%-|^H_GrrTt3fBrx=(DdPmD^f6<=_|jTF$&NG#)T-=fE8aF`OmQyE*-I+!~vTra3G
z=7?lef2ACQFq;S-YXYJSx&M>(7r4VuI(Sjx(C@MUK+5S1iZc0!dT3v8!o!JIdxkE`
z307eIr(A!x#Am*lzx%9l_NQR~N|o|cq*6BQVXIXly_(}|6}C~Gy9u`zHMo%OVeyFD
zgLU<Bf3bnFPq<xkgx5Q?N2R&SJYeOPwq!`{t=l;_fInR?MWo?3%Na@sr6rfuzW#Ep
zrI8Otwr#UuoBVXw6)8EQW}AE}>&EF=%yp_&_x@@5Ui5K-N;C8NLy|gHca{>>dTpKu
zHYa=k!&<d6u_f<Ed7nA*0d>=9&Bqh5JW`w?ph!qi8^4=(%XS{4O^^kewV~4f>UiPL
zFU?xhT>sQhpjo5)K2f&jCO3kcL0kwbKp$wlO2f)wA7szrsr*b(Pf3{xo<a@>b-D|5
zWKPiM!olEisonRaveQ2GX%#NUsr+8e;(OajZJx1q-_$66$5`vl;=Vs$^A_ukNDXl)
z&v4CKqe-KI=Q2jO8l#vL?sm;adt6uba+=)t8P`Nr=6hKPi*c4p8LJ*B_KX9(>J?7<
z7nUD>Ezo1pe>%yx<)}U6F`%R#OS65${B9zVF%4rn`RJqls0;_Ae}wi~9JpkcK{aYu
z1g?q{CKdGKMs$u}=^nx!)C#cJzUK=Z2!T9*+6cctZA3jss{)0AJ+*XH?d~e;3_Yeq
ziK#t}ATAlpR=ec5LHF1em|{kR<Q~46<~oYoR>0GJz)W39Yn7t$X&xC(pl*J{=ZO`z
zjH9t&t1s7PCfQ2WMLY(LOx%Czt0^s;?Favr4m@R|M?NR9YJV6aWVJ~HuE%_?+2^O=
z6T1Q#<JVvBfqwM_k$rX{?hR0!AWd!667XzM(X~+}Ha6?5{MPcPH^wyDgjbHSYsh<d
z??7BE>hYK!3Ghj#fw#cC(zg|0$UY})n@w+BP`sTTOv{TPtkp-o{LMVg$qq2eH*3ZF
zqfGNj$q1gER&X}UoU#GsQ%F&#$^xr-!Uxg*5wPbDYUO=!S!vgu)qM*oSIAKNU%5O0
z%EizM(;-dBopLoIq>9nAX`L*OlayTMW~1BgGJnB~qjr``{^ohHL1fLDWMPz?s@Kra
zkk$BSG%gF6K)cm#YWKEB*5t>Y7x=oA1KramGgL;9K{+4ZnJJ~n&t5zB&T@A1QP7KV
zXlW=2U{aCMVDLt@=qX<TfF3to=r+NxWGT_>50IKnK>gY+{)tRA{SQsU{F;mHjf8<|
z3LE`LdOdjK%+akcNeh9M@W+C`NH`zylAYA6Wq%4#)M(vEib!-LK44-5xOixooZoq!
z5+-=7Y6TGwo+gxp6>vr5`PNjp4y2&ysc6YsB~}*7^_J9{T93*3UwJ>zpa$ngd}#AN
z!tNVO|FYlgV0SdO0&P85&p2o?4b~YR`Oq#A^&_wu3>g6pBiP9*0kzXaj_!Cn%A_N|
z)BEb6@46hJPxk-CbD;z;xn2I|<jpwct4~d!i`(dS0am}zVWYvQ<%*^KeTS@0VCQ9@
z+xh8e-AY@&95tlyBMMBTw+!899ygnbvq`Dmg(!GN5kGT#ZPwbu%RZKBU^;E<Z&i@y
zIiK%?4W+PizsFN=0gWm`5O<lRi=*wryWt7Dt3LUNyA3$QAUd?95k~Vk%6S$;Udqpv
z78Hf@lAZeq*gH{`x&=I4=if%tzzU7Gu99&)7X1&m$Ep_HfLlr_#r&*`6m397nI>y>
z{0ch;RZlI)02C|hut1D0`(nTQ2sFAmy}y1aQREqLN|`Ctm)MW*h|knSi7LD1XmM`9
zKz5$|hVvn+k*cU;Z7~&dx+tU@Favo#Z-{OetFDlzDW?HI*fY*pIXiE8xS3cwpjX;(
zU<fWlLm}`e{1~&~bX&z*8td9V&n68PxLuOQ<+E%6zlpQZU^D4C(3=&3#+unJ*A3YG
z@+xPVy`kNk(#v%_Sx<k|R*Rt}&Qi_(QKlY=&pF%XJ__3ysG*_H+D+VyhgX+zDzt)=
zvige5&nC<8B)pf|MeKmRA}QJdvs=jE&uBm#x`N-n&VaM{XTI9S2(U^`Ul@(v0OL3|
z*&VQO>mSk+`hJAKLb;QWtw?dpZpo_a2D)OkEkJ|*sb-&6S|x#Sj?tj=w<IDP{#=gt
zp43B)b!&-Z6obb3_~ML0<&)GGqI;C}9o4h6L*(P-LEQ1)Omi%wq+YA8rUeJ9!Y`b*
z9(O^JeV^Lx3#2(hkI2C~AMRbJ&5Wedu=O0xY+ba`g>NtHwpf4PlgJrULdCn@7gKM}
zOmSF>LPD3$R;kL55ZmAt&*{=k0;|4TawM|CpAcSKSp$|00W5n9gZ$F~=)d=Wm=kiM
zOyi4G;{t#)`~o<58d4vDgpr>#ocCQ5?qW2HonrNy@?;*T#zH4_QpH;E)Lv!3iv`v)
zmlZUg)`FWtg;oGS0Jwj-4U0^hC=M<t>PtuK1}luJWi;4kBJu*PE_Z_kOpWoFRbwW-
ze*`?^r0(f4!X}hPoo$AK`vnTSQneVudptBF@6{G04{T<8ZW1(OU9&|(k7#0!r1(4S
zwT_uwg|nZ^5;;=!08hL%5N14(IEooOWJ3}+q}hXA&DNXQd(Bg8om4=I5&XqJVyaS4
z3J1su`N`u4>p(gT3xNT~L(2eH7M!;JE+0ROgsetM7uUpSIta?QqiJ!vG%<Yh?j2A2
z1Y6oUjvo}w*w)-h|47ReQN*dn3g!g`@T6!UF?bd(G>FWxlZ@qK`yI*6f#Z4GUrcPU
zS1Y_8Nxd^9TCeEeMZxnLkTiOeh_*P}H9eKke_+#LMc>$6)0+i~USc+RcdrQIa!muX
z8yn;$%rj!}FXfZzaZ55?!Ed3Y6m|wl5s&zl?b<W?TIduK2E8EyTG_&oXp%KDiQYxA
zUy>uBpNTFySCN;nP%<AlEVm9L3Ht1ZbNh3y!<iS$*e&l6J?DLV57@!n=;IWUv-%UC
zLbwYThe9!48p?+&ol9vUU~uYR&+jYbHCYoL348DNdq2leoqtdAp<@T-!R5CQzxyrx
zf`hT-PBML-+tRM<ZgVcv*t|#YT%|_zJWX}+oxA)Q$Kejp!(6i|aRSWeCvrfm4WsAl
z-=U5dn&JARiTlgb8e^G6dAEnNaIkdCLK5h*CTFEUGC=i#u`lBA^xkyN3z+rvyC1V<
zSqJxhj3IYp%K}NsMe4S?<MB0E_chl(Z$7oR4kYl<BjR`=8xM8*<`1?F-)!Xd-#Tw_
zzG@qEq`h~F4q5rtUxjAWflCq@J7uaaH@*0(XG-4r{1%~Yz71wuGs@zT*I76#TCi^E
zvcs@nsoC6tKQxjf3<u!GeCtZyFEQF?#L~%s`_NQlTs!*f8!1I<2&cCY(N3nvm`yAC
z{Z4s>UGC_s0vY|S*Wv49N-(JaCuVSToEmd1bzL?-Zx^Cc!FXkJ0Rb!Ste|vxpOuvJ
z*d<cfNh2KxZAs%5o;;jfyL8(43OoD03axLP>QfE0LW3#B-e|DvW6D#&ObraBdNqaR
zQe`LWt3-=e645^hl2{Y@SIE696-D}J2B-=awStnw!S@R^0%lfk)lsHzPFK4p#)A#O
z%T%-va{Ak2X#~M2gnhjiaj~pp+k9)^yy!0<+GygaBcs&{><(>kmfF18`%nm?p*&D>
zy}N(o3W_W_NjLIcW|ISiN0;G8fYl9tiTO4WVgdI+I>Vw*v(pPrb^@ot!VVa$g&Jul
z`xCWLlle#;>O{bFVp|CGkNv1DL`eiL^}app(%NEASDM%-RU>Sywzrz0Dq}a=uJp{%
zBgD6=tI1?gGu9Z5MoGwP<r&@x-j>}5&o{UUFllp#(?oC8Lb(OFwp`+!@BO4-H5)qN
zj3QhPt_;5E{_R9h$|Y1L-#1_8B<VTdjKgL$u<a}~i=}488-iiFxmOWTadw+I(-~*4
zPcblUc0tx~${8j{O|V)E*HUkG$`La;aX8wE*RDbtADhzV7;*53u*hYeo}E>T!<?&d
zkIe0SSO-3wZW)X}m-8zkijsu9QZ+Y8g&5RLBL5f@3tMYC7-78CPf&R`&(^$Hw>@_y
zVVik1RfsQ+=kOi|?=G#!>dsCMlk&E*Ub?T?K60)1z+o>!EykHq^OIT|>rH;FGn?sv
zZ?9f-H6Dh^)R++1x$(5g;fz@Kjn?cw5rsj5z!Cp8y=S9q^?_kCFSXhLp@vvm!+e8B
zbjd*SN=xqCeR*4p(8CHY3|<y$a-<8s@3Kq6y(<KUi9cA_>v7Sk&ia8Yijdo1L^<GG
zVX84Q{CpdX@%o61(4kNRmLVC+daZI3%IV&y7i6{8Mzj?i-G7<^UIWrxNA9RIFnsmT
z0Ggm{wf)5zOS82)DCA?Fbw|7`uO|&T9Tu$ATGzAQ5%VH^L?Bau2Cv9pj2>*0p;IDJ
zkV~s9cJEX$MH6j!90H-<!L8q?35LgG_2$)$DmG-NK3w5zto}UqHiGa0k65s7r0#yi
zfhvMLigBvHZ}aKVqsjG&aO{bu|G*VvJYLlFw6%jx_ZzFvF6QgQDWquPUOu&XOJ228
z&lDCfG?@hKe!6k%=e51+CzK0ISr%h0L^qM$-{o4kZ00rKmdN_h<o<1lNAPd@nRH!x
zdzjjM6C18is7!jTCf~4?OV9;f?-?<@c!f^ae0=qMo>#c3@$|mzg&Xcx<<O?kM0eZR
ztTqQw3kU@ny<y`5Z>F$)_GR6#Xij~__RA%7Z?eFRz0PZo2y+0#<)dsM2AKG3r%5^Z
z;y@4i`%>ks6brJ0h=d>}M2T%{^hB{U<IAY6m~_agoVZ(Z6KHW`xg?RxQg9;;V2Fye
z33#vgJUQILq`S~<iNW5ntlNXJL~(u=;L6U;`vM`n_K>gbx+q)sp1VpBv3Ao(^9YTn
z%N(N=z>Y|tm13n@tsFBG%y!EH%5ais1w(3D&kEW`KYvp-{XHq}5U{AS@aAFsJdw?%
zJm%7XeB@!Xme~3&p%t9P9aFveG&WzuX%~IH?)RS5B)Zd`PK*pq$G$?ntqQX+D%s4}
zog^z!2_-7Op;z=epTF33_v!aHWFRaSk#1pZTO|MsUC_YxfxbuVcEoC~$ScA{7kJ(b
z<hxh9k{ytD=eIu%3FkdPjW)|NO4ZA+c32F-uRGm6c$W+?jndKV?=P~sp9lB(uA-&W
zD4`fQjgGkJ$-VIB#@^d=TB0h$N}^~X#!&Rh_iM>(^1^V~YzvD;H+Tl)b2$kf&f4zR
zoqln6-bkw!WxctVrnXH8cwQB)*&fW8y>j*|cx967GKZpV!TIs<ZOX+IEWch&ne3Gn
zR)^c3pvi;LT@;B2)B!beL=#bszg(|N+UDYDT8t~z?m~bSL=64A1vcY%E8m!TA`NpB
z8+v%~E=MUD)LUWIY?tdaPVUIRkeR1xy)8yTdwsm{QiwlxWNmf6!jb>+#Yv-tnS2l+
zaI>YJ9{Qro0S=M(Fp&Z+aNF-fbLLwgy}&iUV;KxyJtG)|u9&*yaw=T$zQFyEuFm^N
z{`LMcou9Cgt@r)&69E*BcYu>tqeeb5*IAx>FJjD*;taiN-LUjxO2;M5*4HI=v}mKY
z`(!50FnwlD+fdoL3e6C%Stlw5#W}_~LaG0?3$Q!-G8?UD@|j4;Bi*Vkh|!ZCgRFAK
zxF}`8u!1`juf@)J?zgK>gN-<j?qkGohaF;$M$)qme6`1fJ6s@>fvAOID-woD*VdsP
z@Wch*`ZWI~j9JzHveiObTln(~uq!~sLqG|E4vz+u!t=VcZb5^!Wv2vA5p%I&*x}Jm
z)R~##drW=jPZXqT4x`rlw>hqPb^+NMUWjahT4669a7^BB<%;Cqe())tO4Q=5&x(L;
z<hanOFHCKrrZ9$WWZNCla}^Vo_tH80V%yDEah-Di2u<_8?dscaddyp$r~LMK2kew>
zUp8v7V9w7<FkDY|;v^JFn&YO6H3-C}%Yq+ZUWxL%N0IRPW6ACsEJQoV*=f&!jmA?6
zEIH347ab1-h&PWDeKv<8U4tR_9j|gdKIj2{5z#N!Htnme6KBa%G?v+WN3Rx<$?ayp
zEqu2*o*Ib3>}1@C2WH@LIf(m7u)B7F6OqYhUr%d3nLiLO!1pbY+4fT6rvVDFU{B}X
zI6!?~a64@9SFE*Iw@FaGi+~rId6OXd`|asULE?vbEtiu%9~|b*Usp#`@o%Vr{e^HG
znWWDtPBOzy7?yZ|s&wwgLAYnmi&bl{eK3qS)%2oB=aHwcbUlfR6w=ug+<q-fyV7k^
zrA-Oh9YYJAJkT-eHU*9cdq;h}N;l1O2+mu+ACF-TC^>xQ^$Eigs$hBKgTZqt1_rM&
z!rU*s;KrNN)oKF9HLEYWdY58HQP)0!OBZ{@p63b#QeAp8l<JQzuNd{rpqdqdDR6>!
z*SHTGFe_yZaO&DSl#|6C{Sp!;zWnuepZVTk(sg(O`CehA@4X_=O~XRx4RhQ3);RIb
z3Pd)Qy8xFXgW*2C^QF@%)Y$H<*>*4Xvft(q-)4#f^bL#1EE@<pTi5RHZTF{J$SU+|
zBOIofYPbZSmRIThu2XxCZwc<BGT1*(K#5XcM%?=QM>q#DNJEN90-HCA$zrGQnb4?N
zQ4IPnf><X02f~aZ_G!~L2IMR*GlU6mO!2~pib`{Gz$AMN5}lckKv(yvmmFXlHsk@4
zJ@AMgJT8;O7<%eOXiA;<)i5}!cf0z%T%^(1SG=^Fe!YIA%hMdvttl+{+dD-Q93E;D
zq|4&Gu{!5OQ{}Sk29o*mg9s81_+LT}eD<fYVC*mK@udn^rO6GnyHTVR1`#1_LbiMn
zMXy?D7<dRu%g3qGCS?mQHVP~_z$Z7d=_X2xjUF^#JHUV*)2$X93@%QmI1Nvl*b2L!
zwR>8uB{xg=t2kRE#dLsyvyzbpIy~FUu44zO7m~hGklDU?VCoZS){?fgS&D_I*e8V_
zqx-)1xuu5EL|S-CbIHF+e+Aaj21{B*;sV)F1X$Jm{IbruGbBS8Np+F5IZAD75e9QH
z4vsH=R`GgIp;2S}z0ivwz@!z}JiAkYzI-snG|DxgbTa02Dr6)`kSuh(X20SkH;|3t
zao5#?rLsj}Q_ST59!_<!e*fi2>DcZ0F}v~ewF@p!K8p9MGdv!f$!winZjiU1Z9j57
zZL7tUE~Z<bT@bx#q#m$W$e#Rcu6wKktUVnA*&%joj}o=#W#PcnZd)zR$GRu3daioA
zIJs0#7wwN_!J4~1on3FwusRtfzmt!h5#M`$8R5NsY+Q>J3I4d1NaZtWst4HiyBM%*
zIIb!Roj!Rtgv$;e_OV<UD}LAWNFz_TOkSifoW+_8YvMvL*^briDmrpcF^@_y36m(T
zZT~tyKqMyi`!KhzPbmT-7TxZ(ws!e^qnZc5P8G}cVytSbBbfhN(wJ#1w#V-W4%dUk
zubOF9TBm6+T41TWvoOp_Dp5g1Hey3#C`wfBm;J3Dx~FHFLCG$w<*p;IFW=I?2MpC(
ze-Nan+8aEgQSU^R$#hxgfbPvu?QpNq_N?lu4FbN;BXGO|Xi@!N_7pN1gN?8l?j3my
zuc@jxFoHxf>AnNW^q~eFg74XhxIQO|DbzcIcQ{>RDo6T+%|?+|9U8BZW?iJW;FW2P
z`{-N@YkVF&Gy-1?X;*(V5t|o_^{T~(a^2y8*q)C%RW@8>dQpm*1<^Azg```os+_`*
zeiXpo1oN@ZV`7h|lKqA@zlp&zo;e^l-`k^*(W71n+A&pIEn_(xd^u{mDymO;7Qo!p
z+=&|-=pTGuNIdq%IJzo{g(lz2aZDfBaBtoGgKzPs?G}~tA`*P`C^E3e4>)-B9T?eZ
z*-`DTIfTU;cX*9OaVY>g<&=no%=}($s-d)gta+qG&I}nA!#DjshH12{Lp4j`M@kCF
zW*bf#YtXyZtK%S>f=~$M)LM8_O(jv|-JeS1KeE7XTD>>k-sHG}PQ2V1Etkr^(Hu9P
zqaM1)&wCDhYle$Q4KV<KO~4qbyA~^h%TN&3hZna*rRYa`qJuw^2|f(o`0U)5MF^f}
z@u(;~1R_DzevLm{J3k&tzS9mgRc*@rR7J8hxKBdr^O23`ByuM1*nUe|m89!@EEH+&
zvBj2zFCVQ8d^bsqAs#xs%8M5?u>7JA-7bmuaW_CmQ{p$-e0p`(1L>Asq1*t=lpgPD
zzgVvNsCnyth}()a%cN&HqG{*)te<9VzcctHy2U$?x*Xp!?7?;g9tQ8kvN!I3@C)T;
z?q)Dv{jFy`*%QwbN}u-)$G5qPQ*T4TZ_*-tlAka*31Tkvw)a!qCN^}OxHFB^<2WIy
z2Be$|rP+PnWqQIqG<;e;EFO~`-^$vu!;3v^|B0)on0b^~h+(8TX($MTSD9^0L5Yg{
z@(4pZ{6?D&Z#-t}sr9L2;0__OUiVyC&dJweR&Naz&=>k7gMxnz=QJnM>EW02_4R*N
z7K(Rv_ngP@vATmIZ}FVp5&htO2a_+Kj9v816It?eO@C_~yg<Kw&gcHiEMM*}K{kPI
zpeZo?3(%1KNC7;*LO^Jw@yEVM9;@jhVZ_(Bh-gma{`ScLHXYU6J_0U;MIp4@o;&vI
z1fMFF*;JyDh6r9{w=dGN_`#Fuq2}cC00P_p#nm^(=k*3#r?G9jO=H_?Y&&^l+iq;5
zVPmUl>@;R$H@59>=YP(*`7Uyq-@Bi|vuD;?GaG0>#frALfx47}!g&}`ZFd*n?wYga
z;r#Jfv)(WFF_#0Vmf^KIM8E^dKGZ_1yHa1!&iQW>nMr;@zP};{ys!pBT?yIp<GR<-
z4c}4@``nxl`zzJkNXce!;vKRSHdyG_YqFKE;Yy+qv%hu-7d+u&^N$rl0m+2UfDOz|
z!kT>Gg?BIURSxfO5QyiTgb03`0nq??Cby3=)o$xtD4W7^;06yUp%@}ICjAqX2#~?N
zRAP7cZbv9&B<_{<5z2&MS&|AQ4QJy8!j~@Hfn!yqF^V+Bt+U$IJ7HBAu3tUiM&_Kg
z(=MDF-+jHFU1$x)1o0J(JW-;4tSfp!HmIkUn)S8+@q&I8(#V8y1atI!e^%fbj6Far
zP2NivqZO3Z;=ByHA3v~1<^PM>HKA#?RGh2$kkOl|r4m0K9SQZ}lMmVKaxMu9i9mm1
ziwv{ti|SAu>|QFTKQUr17r5!yWaM%pQQ?8}(anWx1CVO8O~39D-Abn#oTYLbpi^NK
z1|*t;59ebvmAX76(*<GwfIl*tAs4GxWIwHjv2g$S#M@HUqRa)3)$BHui?zRkV=KIp
z!UNVGOQ>)UxgT0F*84v-lzU0FsAeLsLj3LTurEx9FxxLYzN>KAf@dK29?IY(kP}N&
zDNTV=i7?T4l&r7>>sRcLTGbhF1DC&FmY_HBs~~ZJp8rX2_KN$-S$Ii~7d(cUM1geU
zSK$V0;PvB6^Wyb(jE?23f|9-(!OK=11i*|f{Fe3zEY*mVvwR@RIoA%WqP&IUOZB8w
zTxPpg+8I~vyZ^<bRJe&8qJpATZ0LX&kxX|eDMown?vO57?K-M^$2&0NLFYqBpnh^B
zO`uPIe3U{poTpl%tjFhZ(ajZ`>s~E-*4}a&E9IAOqg|6h^UuEZ#`1Dzz;q~qwr$T7
zXu$u^7eZeUSl+z+hOQ6C%2)@Y{oe@%BMdZNBL#oIAj2J5+ivYX&V&{L|0bz;LP!uK
zs~8;>e32e-`Cr<+%U1u!e$-c^l=|u1<_MgtOu0y+ey4adV}L4yl|&$#_r46<DoA!R
zmcG__m=83b3XyokV^U0K=iH>m%%L84;EA08PplMw`PG<10{rbmXxG*Ly0-FhyjDai
zVF}%?L7&G)#~1XW`!qp+w@3x#!4*zhPH2qk7bmQ=eq2jFM97SvU~g{lksn~}w{EyV
zMQjlG<%^<Y4v*uAhp*dQq8c1**L3rz&{z_DOz$}02z0@d&}evACev<d#cFFK0%aUq
zw!&tsvyY`ZUHRjW1}#2lGB{&mvr~*BXCr^-<+^^lCh>erq=YM;G}vww>fFogzczc(
z1>`R!Gb%untPz2f6mb5r?Tdd~=ni!xC>rwW^`n}2_^MhRaGo}C!9Bu+3Q8q#DdO}&
zjwC9D+}ZDF#)N0H#~{_Q$8fFd_@8I49cVLK()L+?RN+&uuN>MRPWn7J;7brsW&(|)
z0aRpw#6H)OsSy|Wff2{~UvRjyB|1a>@h$%E#77#8!2o(vpmYA|V08wEjKZiLUR;<u
zz0;Nu0nXzaP~wJx1vfoOgF(R1+nb}^(kAnP^uK810rwgQx?hnQyKENw^!~3tp?EZj
z1TeY+g6AyVpU0#$V8fH^*xgZfWBTMOT_}d|0Tp($P1WQH6;xayzi0&xaXy_uI&>r0
z%3!c;)PqUmCEA9cH{OtOpWK5j+QO>7Ey}#6b2dP9gTOXEee-zlgCVMy!U!B2xfXrX
zF=he8ts7*{=3{;F3SpY6(Qke}iiN$vjrZgg`VDFOkrB}J$S@gbIqi@YIHgv|VC4))
z&i%L#5lb!V>{vG0JULf<KfP!2+LDdqOC&sH*VlqiuqO|b0@sFPDy>mh)~DS+&a>O1
zSTpd%6D@t~rMWa5*<&;h(!cx@nO?WpCOmCZWswfc;`G=GS;OFY%4@x*h$oc^_74%P
z1;b-GB&Qzyfh1r8O!?ErO=O0LC=w*8NxkViSo|~E)vlu?TS7p52WEo8cU&|Hv6BRU
zX;MTqE3tI6Mi<BcE~q(P>aEE*>1T2uPZ`~-iG$t-tcVAigc%sHA<S~()Icx4#bxxm
zx;l^RlqQF*MYx&4+?#jYD&EK(0!<S|gRblQ<44BD;3q3I5GZ8bqmi&PqmB#EsFLiD
zcbl&Xiap}!_ueBckcq?Jvubm%WFQ_LN23aU4n+N^y3P@(85LfArjD(O^d8k#LHS>Y
zbX#1Y=A=7~GbICip=zB*;Ykb|Y*=I=@iH)L7#_`<hIEp{QB06DQl47>wIoQPakPH=
zX3fFo4u#h;fl&o3qHWd+Ecg<aomSQ#!Gx)W>}CxGsIeoQNFgUtOQF3><NzaSt2q;B
z`-~>USHjulz)&Zr8c{L4OOZrOs}1YYKJqiPQWV2zVH>)i>L_Z$)QXcR-izbgOW!hv
z6nF|u7)PT6&ge7D8v$5gU@~UekN-WyYT4SlngZH4l7q+_7h(sx;<eF)K%2cX0z4$j
z`0g(*Xoxh<X9I6W|2dXkhdMCeV=P4Dr1QZQ6m#_xMAn~9RC>F|iinkV?d^V^FOnZw
zoPX@XV<Xs#WI2=3HR|Pm+WRe@Ip^8ab-2PC#1*g(T@&BK5MI7z^cRqx+d#!QXvAkg
z|AW9W|12^r6MCt;pm=TxmZ-vt6Ces!&Wq}N1r}eCkO+R-?&Nw@7%K1!TM9|&jrYEO
z3yE@_fbAUZOL4e&jW#D<d5~;g4#{2W&cpP!N5S%s;<#tOIhgTfw(E8H)+Ka657E=2
zF@C<^HB^cO1J(h1EMcu*!&eVVe$Q$(e*;{*4hx}jJS*s5Fnp|*z$2$UX3z<@<h(oy
zeN=^}-{ObUpz&%spLIqW{NxqIutF9H_Ma&ZfUO%kj2PA_zkl;)3YU5f4Q1_&BsS+%
za9ph<l-|!<Gte(?zJ@7Pes8z8XkfwsL9So7w-(x-W+$Vc#|wv67)Bv#nB!a9C?WTf
zQ+@+kweZXi{o7QUDzD}Zl6Br4NoJ$EC#A;grIX@`c?SyzQzaJi2Ai{qR#_dxx4?a8
z1lxhqgVbw5Zd{PccK<Y{GV%hSR~#y!OGAF0I8$<w*jS4=vMDV?SAibS#av&q`;;Yz
z@V}u!cn-j;S5Q0Fc;?&1aepdmsHVDJI$41+K&+Pk${S_^O2}NE(I)F;vCgcY2rWR5
ziSE?qvPrmZtB7=ezV>I;l;F}uI4L;aJDz?1>Hfu)POEFO{YC=dPB#H!5|ZL$<Dm|g
z<LLuVz_UVMbAGjoaX%NP@vK%zJ?TudItJk?j{kH1)o9A)T5nk<&dH5n$@FU<vF1y~
zs>hU>5$Vvk7u@Tp(GQCq5~U=zK{?4Cf(Mv?D%EhyYNWeV`wP}whKb3%S*k{*0hNIn
z*_}Fx8Z5!*w)14tZe_XD?D0)%-2*SIC8C^0B!R!e3e|*zmPFccO?ra5{Dk|mU8*b@
z3r!OI&1>c>*kU<kS#rRTphv@{*lcQl1R9!zJ}S}ETv$CRM)-bM0lzAb0Un><&0;$I
zeN*s{VD`~O$m3$qTp^(e|AYb)K;42i8l&De((px{scog9fYc=7?5UB~;&P&b>wcpv
zz0rd|hgNCX_II^9-^-+U<%%0+XD0DAP)SQC>`IY_e+-eW7!O4yt&+Gc_^Io6vcWN1
zea@#FLVPyHHIq+REW6}z?ZH$nqaFrj>7>o;CDaHB+z?+xT=z;x0588CDqZ8Kbb=ZN
z%k@ui@Y04_EwL2j3t`d&B=<T|7^c^m?Ee6&?4CFkUo2ffx>n!Z<gmQIjhV5j+W~3V
z<y+Hq0OY<}7u(;3l?fgt0l`XG^{X0mTJx*{uWC$!BHi~^7@;#ZmZ=)r8!$L<e&q;+
zonK}^X%pz-w+P{N*h{6#NM!W#5K_))xJ)iZi0x4j7QHb~N(yA$G&4nh-{28lMY0z@
zmduX3_g{d`o?dJ9ggECc57{0>Hd$_;8xZQ$J{`EN7&w+2P8vO@JzI)>Evd6TFMAmA
ziUx+bh-K!<1M@zbO2*ND!!;C6u0pyudgwqbK{b#zSRG6A>3tJXTl~God!Og&+melD
z?|HS`)6RY!&mFZLU>Rlh9{$$xWHS8p$D_EppK|Uax`r6DMk}j}!eK%{dWm@zY^RW7
z-_cMK5~U@IL_&o+<9=y0X(?B)^_QSH^N%KeNk(7zlk$w5_%zGMeoqxV7*~)hh4UkV
zsjYJ0*y3p~C^~#{y*0;jy+pSm!CD*G-q+>CKbjL3A0~sPK6g40;m9^>hz$z5d^C#N
z-D;7!5J&NhhEUm4=!vSacvk9J;EfN8u7M+1L0JS|%vQdig*b(?O)o{b6&vdBuH)IW
z9VuYQy?%XHjA|;_Z=^cs^|BB=lGLPzn9VdDW~|r|`OImrI|y?=|0f~%`Qj8sMyb(@
ze!Ouq`xPhVNWG_g{Fx8_<$3h3fXhQ9%S~;@y_mGX6HhZ9G6)z_!Rx9V-j^m-)Zj_t
zLc9{W{z02kISQRbdM(_?@n90gMbN+W7fD9(S2`E$V$&Xyw&8v38a7l8qZ*+}CjkVS
zd8J&<0zrqB1QKBcj(&AC%{6t~cl*J4B8yjfpGwsTEs8qppt%#mQmArWhP^qeNo;xf
zoU1jgB!9m{E$4ydAIblIS*cWe4TYD^i$us2xN_}X>do@hbDqHAp_}iy7UlKFCt$p6
z;PbSZrV2}Uim|fII+ldDz{EjnA+Ix*@-|%C5uw$J5gr?cw^3-M=++yegG4qTjS#B)
zg}p1DR=8ZZFpt<ugMofSPaDDj8>oR~T8n=}xV;_oS&7o?p?Byyb81gi9!?ehF8Z<s
zAD9p<*q02K`rg9-aL!LD!yxrexYD`CJ6&sM8YN=VnH{sR;j~kESgH2z@3%d`?lV=$
zfK0L)b#RXTQ^HnCzGU3({gKzp%_eY*Y83a_%NSw)bl`FHYAA-)x3Zc83Qr-to&gRr
z9k6^ZV?ae$Y^BE8oi}BFX#+g9@ZM>7ljDtIds1kBa6&Uv?8#6dg@twv9x-41)R#-@
zrPOt=dpT9_MtrB8iBH4jb@mGaz|x#q&!e)ET1vAzQ4~U*SGyNe44%dV&{L_`=~4Pc
z@GTN)?m6B#5f_)DOf;;%-d|Z3;U1gF&!L&~6}4CAXHB>oDxDjS?l`~*FCbRWwb2uH
z;-J0^WqzlT8{tI<fi}`%ys+XjLgjhTPzW#k(UKS|`kT=d2n~R>XJylfR045K?FUh@
zBF%E+j>d%J%;}IBh8})=p6F3D+r|Gb0{aF?F!0&!!wFkXO15HRV#GJ>eCupBoiM*@
z!#b-^2)EvJj$<B-<P?!^!_zm7K;OJ9nCi;vznW~bYyB_mm(DBG%2D#}Y8y<2Kqu;M
zyW|bMRKM@CtT;AFJKbsOQ_Nh(WT?rO*@#`m#ddO(B4e>uh>T3K7*&t;wZLf(9~p*W
z<2?-JZ2PIPg3HCQsV--+A1_L&p?a0rb)!?O7AuZekeNMCCe#N&vG#{EDN!AOuH2^+
z68%_sl<_!`O8gAZTRdFJ9E&b!Y&R<H(&{mDATP9B-0v?Qk+)R4>fmosPP6xYut%2#
zGh8N@&z3_PD~r^MbMbgjnr|nI>-8A0B!|*0BGnE;d0;p&QzLEF0P7L24d^TN->6cf
zIc3N73xDrMl5R`AlP8wq%xCLqDR0lF-+vaF@_>OzFY`G2h8A)Cliwl9yCKn9#%kc}
zWAB}7O-5}c)w*20KNVP`BsN`;Y%QPQ-gtUkPws%h(zgV1DEuay=-&yp2^49&^xXh?
zWN3IUy!db}k<4I#k6|t+G$5NZaC2|LjiCzUg<cMaHp0Q9!T<(<+ZZ>#bQ}IkMH-<{
z;aN~I7=5gmkon_y^?i4IA8rOaU%jI#D~Ryb)Ib)W(eYrrYSX)l`NsM*0zb=bs}FpC
zGF$j~z}0cfz9r+h({wBuO6NXjdPfaZlV;s?X1wQgoxISDxyDKk&>i;+A?#A5|2|M<
z7r32;grrcM3_4`5gbJxG<!Uqb%cFoG;dpN6BSeAID?GPXvdu4B^m5B=xO`@)Rvr4I
z>7Km_RS%9KO3BO$!L}7XM{H%x9%F{Hz6G%|guAtM_ca{{mqrRh!po~(H>a_Cwm&G;
zj#L>M594~}k!Ramch<>=*yC73=_HPV;-IG1I*QR};lGno7%-rLW@%|FkOCu*xzpnw
za%DJ5!OcvKQw&=Z8;6%E4{AK7!-uoQq#C?7WZF;IS&;&~nlA9cB2+zB27RHuukHQ-
z_kNinDk$ji5m2<3o+MJsMAl=Cko))e#G6k=biMb)((~rc98Oi*vbr1+MI@KaLV|i4
zVm=H(5AOGtv?LxIp#{M&3q$VCLazt3&IO@2J#p9Q>muV>R0N$5SJtzhuS7q{`wApc
zE@yr&;a+ro<MXjNJfz$2j9q)qGhLa8cMF=6Cl-vHmpj@z@h{;gHoivT$$wXz+*<oQ
zR9o1$d_aum3N*j%d^X+0fzK!;#+#Xq4`y%RFRllu)%F{a$uz5R(sF;{K3ed@>W8t5
z3YYe_5L1mUIEq~FIf?-<jzCP1z%k$%o3)5*^GV(tJG6X?lC3*_|5KlEMU&AT<hSro
z6m^daa;OWA&Pg!d+0c#Crww)kW768TGGo|2^NlEWYt6fgCker>q0xAX=cir=&nYhl
zScJu!LcrS9YQ{N9u(4nib||LFTQi$^Sim`NJNsi26z*4@jw~cnF&!fkcv2`7w{s7y
ziQ2|hiR(Jb%A+A(Xy1Hnt-d-nk{AqBUf$~R*&0Ch3x~4Xoy%w8N@l|-$HNWmhw-_0
zp0Gk9m@@?FO4gb~!Q%)uY8XgV+*QTX#`XV0mY=zJft?5p8z==Ff+3q-U<`e{Ws;u{
zn$`_3)$FI~@xDL%DJ%vI>p765F=RP6Zxq#G(&UKTWwlH<FTqG8>^7W{eBjW{PKV%U
z8)=0ecXAW<S`GVRu~{vb+xSga8eG|NpP>Y-*1-t;Q#P3Sn#3!b@>R8@P!Br){Ku>P
z5&V1G9S_G((FwF*0xI*rME}h$HKeyYpcON|!U5zrQwmTez0w1?-m`29_U^)M16ZYR
zGF7R$KNx|}e1ldW;2|IOu8Oppt$TX^e?dwIpPY8bLvYH~MT*B_Ss5R#_yTP-wgaC&
z_ZPLP#b~7wGG@AFrPYJcQOLA)9R#9+#{Q)6hKezwBk{iVSot&Dt)7aD`N4EMhtf%o
zekx4cVV3qGFz_BIEx;lh(jCKADy@DVMNee!K>s{2Jq7{v6;|TymoM>b^WJV}JplUe
zcz?!EsgSUm{>bQ@I`&1mGJHJXx-&EG^Qo1OpT}Qu<0=BoeZfEyZnHk?sbje<uT;dc
z>6hE92v@yc<MjrOw+LF!vw=zRk_w!)f+s6@7NffM9_9#>68Y^JW&@L3`>rKb6CkSn
zvw@B`x9soMI~XFXwO%!41S&<H@r&6ekYY&sur7s{LiB=RQjvycdQP3i==mz&Rd12A
zAsNuq=m!Nax$QOR(O`uo{^pb?l<UPbkzdx>w0s{<VQ7h@S@>RfD!vR1Y!@~z#6gyz
zD<nMp!q7jYwjj9F&Pwm69)diLgf=t;go~eWwT9gBfaByZmifyrQ{vIRw=F(tNZG#p
zpB7*|@>?$TL-kb1OZl@AI50sq7@g~;d4u`CS_ps*LqUkwY~}L4B>#Q36l@HIV7%4-
znErc_C7l`=P&$W%XIVEd@6U-JE!Ijga1;+uFj#xF13=~2)f%E!hrHjeu4Pd%va)_e
z{-|zdL{sX<LS;QB9n8A^2*6m-Frip?GrUkgw?+-7RDgcOz!$BY%BrILajkW*Z3%*{
zQxoEBWxl}q=4tsaYL{MFxG+gwf)<{<QBA)?v8aBt((A%D138jL^K3%AMT7wy)U_TM
z2Hr}buj`0bFHlxW{<6i#nkZ;khq3^B^50;i5t^o_2|y_x{RJTP1<m?j65v1>i{;?g
zX!qyjkrtrkAp8MX955MgCC|VF99}eIN(=k$=pfndspldSV0{R1Yx}5CVh`e&{Sgx?
z+ilO>Lw~~tQI?eAGZrHS9A-*dY1J}=4HtsWOsS|S<3l~BG>a!48ZdAwr0!^?0;@7T
zu6@po3G$V7+Y><c<vH?ixc522qbn&K=ix!og0;^zC^)$!Zv>ha_n2(^f><VLrAWRv
zQ$Ol`u}6MD-Bw_s*p5WF+yLXp{SmAhvJDHu3+_IXM+2HEK%;zEd@=azdbTuzcA@4+
zE0CJLN0^}YNz8!$tXf%`og}*~PHEu*?gB-I&8?3@AdB%%x&l$m2}`mc);>cJ3h&Ym
zSkn67K@N}^^uv&!%ZkJUq^ux93pXsxzg!RL<gxu~01wbzQ<BrQqWUezmC+v&!RBxd
z)4d^FpNgctKEZc~32X|QnFrSe#;+E3d^vyQale<ToCr`CkC}ArX8aP}{`xIJSFU}Z
z7uROV`(v^>+8)QQ!Gb9R*|h5n%_!Otfb_j9mlCl8jgi*7hu?R2{IdWg`3)N&+I@?A
zX33#447HKY<Nm}zu-7nf>qDb4QEFCMZ7GrGP_480!?TEDqKRKMr+so*kC7^bs6}Ne
zmcv4!eZ0Mw?0c79wveetkb<}Ihq}u~_{ZPi7(OUV!@2k1e>VZCU;OmCo$E{=Ap&cg
zoJa>ZovU8()8NbLbFs2xLWQq_x1(*^oj5Q(uUsvyL`h~URg_2tuT{T#ojbY8>OPUh
z`<%TywmNz3b(@%Re&w^V!8&ozx39Ij95N8U38vX8fWhLm$omSt@;OzQ8e=8Cl^dhk
zzfc}8CQBLoF+`;kW{jmNy?~cf^4JVsN1En_66NhRarXh#%C9?|ZlF5V*yxXs2TDZL
z?Sq2-#s7#&_p-ZCj{=I9dYdB)mc7bowG_hxt^OhyUZ4Wz@I}&k?V+rtmKDlOs*Z$*
zm)l+NKpx);(ul7+T@;uyxSS1@3_`19>!r0DL>A=L*KtElc|sb6y}kQ7e}6{M{O+h3
zv|>m1jL=<ena)Y1;xLJ8H;*aQfI9c|H@`35==_F&CRmn7(cCN+@|+|?NxeZmT<C3x
zrq3|bbhB9we?dIgF8|~RD^ns{<=emUVdpv*Pf{z$P)Et>`0AUSn+QY}n(qcnVRr5#
zmJgTvxuZ-&q)9KdBG4H-tgbWREJMwfoQX9uK`>S!3?UovUha$6h5b4yUzVv$`bhf}
zi)!c@u?1!Y3FXRAHyY|OY5S&M{fNLiwO;$?V~u3l)I&xrufPJV(bHMi8BD;Km>Uh6
z-DOKNqLc?&#+Z6;*41${U*AuMW0D%*lG?dJL0@TyM5(nb)|lmk?or&oFw$?4Gg-Je
z{zyE{!!gRpTB(3In%fh+MQ_5;Y_NmK@pV^^&-7Gt_?O;8tUmQ|8oP}@bn`WRmL(={
z3Nj<=q<}{_RsO%zKq1e<>wWDaLM(OP6B?EXM!as({Z}RA($%EPIa)(aF8j~BdhYTo
z7)38)Z~tx+cV~gStRz@x^Bv|$2id%&D4I-)28X2u>+F=FXbt|`up+x(TKF%LJNd3W
zT?>{W%An~E->(ku4(C4$wKTyetYnC^&m#I(J~xCLdTqX6&4}DwU1SR%6?#u5DLxn$
z!^1((v)``dG9QO+oFdRyRPVeiLTAkC!KC<s@IcD`aDYp^1~RgQp)+LvD!i^@@hQ@}
zl)YfvI#X5=K^cBScW0R+W)ZDwr(i3c`jQmx7__UTMV%r-+y<eE6&NU}5z_&8-IkRt
zW|tr8H1S-s;LxANnWzlz^LJ}yMy$i!?Q$<3?rQ==u&kY)Hded;4tBJ3ZRRHm>U(y?
z;QSncGNq2M4BRcOS68@8nZEU)%Q&tx2k-ojotk{fnk44Cy0j!g2SSR}<aCdd+r!27
zkfv>AX1VJvN6|KZBNFO;L>8SU+rD2*8%D$DT_(Gk?2B~+$cqI=6om7gMEG;&yFH7A
zg@uq9T@UCRW4Unz3>}c3o<5Ek@fjPFgBs3zhNJUUi{5ek4mN2Mi)Cg%@8t{+bN#m}
zTAb@%YPxDIul+3)n;4LJ@}QQ99Kg!C_F`?Jx?7P5e0W&mM!N_&fA%oA)~!^x{TvmB
zF-lu*G$Eq4X_I?@4P!L(joL_M94zm8msrboALyyl$rl|>WkQ6&Vjp_xG=?gk%n07C
zc<UV)|Dn`nM?|>T&du}7Dx_RZ1S=A@>g%nK@87}Bj@E-h0n?bF{nOz;0&Bd#?P4g9
z&lHWQ4~d1KGh8qf&V5*h3e((M%`5%|YUj)Ba@x>?J&&I%Rd^}Z|K>=6##6^N2G`$n
z+>H6^;1#9d9a{Ea?~>~k!>VU;@WvK!ZF6ctSeCX`E>l4C==<>GP=o7IMJIRie8AhM
z!yRI*)y4QCb04RvXlnlheqFHMeKSS#`lWX(<xW>el6V#IRQp6JBBI&<umR^KaIzCl
zEb0PEN-3};Yu{u77o=XL70gTGiOJZ0-#LkjCLMeB;@^B5IqEnRxQRhFO?tKS!+tYj
zVdDZ1|I7QtL-`mOlj}U4F1rt;*?Tjo1w1}i=q^fkQArN^!rbL@VVvVThQhx#K-PD+
zQsHQ#J9AI2>ohVfKp{!j%as32>`!Pf$1t!*KemZO$7V)2S4LrX;!cBXD;c-=@IBg&
z20xBd;1Tzj)8@vtc-q1nj@Ami>V5^Mpr#Ew_^gF9KfcJl*e9|Lc;Jn<2a|7qj^@gO
zKbdDo<m2cE;LlZrslA0!$y_X2*KD`AZ}bTsFBGW!;COhk^a}1Xw>kE{rWZDCVdQ;f
z%UxfhWEld@*!`)gK%Tv19W5r7;sUaY#-q>EWPRgq+WGfXHb@u0jAdx5B1A2=^OHj*
zXR^6U(8$#|T8y&ns!T-V2&QvWtq4{hpdPYP%eU`^`?`NH&=icbBrw|eRR$}+e^nTT
z2fBHE<P<~Z@q}A;uku+^{CD@OZxV1dyptChp?)%V+Th`x>xTO5f=-2lk$!Q9Soyl3
z-aeHuwov0Gj|*CVe{t6J=#wkeZiIiz_WIiTy78WGcbe@>m1gjCA=>_S`Pl{KswyKi
zm=^}AKmHnmG5A66a)I^YprR&dAi#Dd7y<DCiN#&u1@_GEhIz`HI!m_snIX%OkXBYA
zmEC$_tJ1pqPYJ78kVIMqV=HQoD6;Trw$*0IhF{;s=g$GhS2B|nas3VVYr#bBwfnS)
zIl;%x#|e^-=O%H_^A00*gAX3REIUaKsIGPax{%9AB!f8uItM|X?~_S&7xG+%T2yiU
zxp)1E|6sNN#Nemrli-!>=j}xXJ)c+0Lj1>@nY@Gu2@*evN$f7MQ8H1+90a>&xO3k-
zJm92cT<_m8e4K4o+u>$9e*}l=d$o*x8(==9zg{jCVOz3os^@-NsfV)nVZn>*e8TU1
z;P~RxI!1ckv#;W)-81F%JSJ?`amAv2I(l(>f{F*KH_1hxQ-(Pb8#a~fq9iKCYQ<bU
zyKjecjB7f5`=L&=57I*|V;W*I82!ACN@dnv!WmVCD7tDjQ(@XzwZIQ%7w(wsLpxp5
z^+*P0*1yP^V0Ht|GdF)pbWWdM^pm!YN%hcMGHCn0!+Uy0I%o_uG`(YMpHhwC`W_xi
z)7GW%_m!fJOqJ#IdBb3ps|G){=LQ(rl3Iv;{(1TqEt}FD)14JE%4E8y@Tn0ool2+f
z`N5j6h?s<9*ee*ZgXC$=jhE-QWw3?>qGaC_UmPR?5`j5l2R@?tmCSSu=R>>vmt5I*
z_{sL`SjOc2$9utxkjF*S*M%9!-H!Y1%LRjb{>uBaWh`$FtM7suRlOMY?S}}gR|xwC
z59@7c{G7NsE~};*5546)jg~R)16Yr}z9%BV(rFEoe^$i<Gk492{P}X)oi!JaPwQ90
zjCyt2Q6Nw@yrL!-w=iQz-FEiU-iaK!^nL#MouKxte77~oW`o1g^)Hyj2wj(`!Hg9e
z$ESluqoc_6gI<XH$>~%p2Bg-^-l7cSpVg2krnkKxB1iI*CC=3?$VtU=v;@t6*1fkI
zN^(WAv!xAS*9G2$Wph~<%uzF6<}^(8d0%3QSrj&$age#M>DcW5Vp`8v-Qt~|Ts_WU
z_;@GMlLyQGK2bIHIugppZL&E`DTHt>ohov#y85#eM6TskFM^u1_+(1`eyA}2PaW^D
zz;>Jc-s>M-b@zj9RpLC`Pr^@z;)Eu3?M>H;gPgSQOCmZR6rC&s%v!`NIYVjdEL{Wt
z`5(5vtHao7a|HwM%it52Xv#xqd>DF{4hKre%eW-^M(6Qcf{8|`3Aa?M{|-kXq3&7$
z+8+ueii`8733ls$y%@Y?1Ei6Jlv@*2(<nP-O=gC#0|6#MmWH#<WI6Gkr}fLEqH)m$
z4DCbaW9hHUv}o5qSDzm+nr&Af>h&rbw`0@a?|$rFjl8@Jl2|M~_vftvn>FzSCgbZk
zb>r6c4z&nT@lB8gUdQsL(#+2~2ufVfiLc=E2gCP&c6Opt9r0i9;`k0^D~i~s@e;#V
zdpw?2Fcz3LToDtxQG8?TLqhth$9NKjcRf;W`-n)&w)H&;@4EB;P%e0aI0oN%Pli!q
zXU%-d(1+_bDsPh<4>Zwn=at(NW@Lak4gdLO%yMQQ^m6M?s<D=`pB?2LmMrKT>$Rt)
z%bCbcBohLifzPXY@3}Tb8xGz2oa=#(!uN=Ipym8?Fc>FngT&b)o!|{FUU&ehEuM$S
zB~PA6hch~>|D&Lm=1gu;IVtk<Eco)CN_{!5P#lIB!+aBMw8|L6EVHdxffMkf<I(Jm
zQH&(??SYkwg(POp<jY@7zVHVmzL%s3xZXC1!F-$a;^>)T0NV8l7Gum9q01LZf%dL3
zYSTazT^5K0kAQho0=#xtl-&O;X%{?FH-|*1(q7U+By+0IqPNT;Ucw>gWK*=%k%f1i
zYP?Li!ixk^tOO-DfP4j+qH|TlQh~&BLu!<R7D}q;N``>`Jxwt*Rj0anHLZ4m<`$Ws
z@5^lQ>D%-6nxi;bhyCLHUY&Snm{%85*Kl~nDdQnHt1jzLRFfR<_4^*VwA<@f9QpM9
zo&Lb!piaNDPH*4*Z*H5*%ehY4TAjG~B^EB>l+M@;{rUS@IGDe$pAHhZ-e7YOf<rtl
zcye8l{a!MN=Qca+PdWsCJR-H;x6xVTIY8rue#v$+4V)CZ9W9JN>xkkab?)MOC+7E%
z3DM^nEtX|iuwUQ$bKvomVR~AwRuy?iuVZ|L5eG#DrT={1rFpqv#b&=uSrN^wn~unW
z#&})%4qUF48@=HO->yCi9Wd7WhM)2LoA}Ols+5RBone*wAb(otfN^KCoT!xH6^qr)
z3f5TjYs*+J#DzZ|$6=L;(<Y+7%*feNlZ%<S8GV-)2J>`rzznocCBVPH&V=P~`*=Gu
zff3V%dGqUm+f^{jLIw<PScG4h@0V<b)eXvOYH3j^mnJ4fu(C})@~?GmOubSxF&0s7
z2s#m{$5t`;?<BVwWscGAVo*$WLv`@}bgQ~jLg4;=Q>i)8iu8kdGdqJxCJ3HtT}SmF
z%?j(jNc}u1>tjWY;|tcS@A2cm{L8#)%0#AfnVGXes9k>}5gman-lD@g{#s*KQbcd9
zOVDfuM(5Xr83(7J5?X!Y9#-kvsULd*`k#~WfG?We%PYQNn0tHK5_<N8n8NwvrHZ0t
ztPwzeHvdiV<!+;mX0QECTNdZ!P_(9Z<<HwudbcqB-Jk|zGJe#F@qK5RUIn(_>q9|!
zi_K!1J{J-)Z*N-L0OKYiOHL=w^H&q1nIcx|)j!hd2}KUQGq}uw;$+~x)&bleC%uJZ
z<8k{@{mMpfc{K(;J!vjn8e-5Hx=X`T$5VkkP4}F`Fjk?=Q@p)?<Q38RGL>{Lg{LF=
zn}+I%)s%axMiV$)lq?(_+PKv!INedqxF#0A4B;f#A5a>;qS-bg(g%7R2FN#7LUz0@
z6mfoPrVYJqAjjHJtg1t&SaF_yXk+C_H<G*i@x`P^!QF#e{6{Pq*C!mkJY1nBi)^PC
zZ}U?0mcKJJ%|T)`kZ<!D4&1seQmN4|>i2Q0oyLhi??bkl+`n7jny}B4HDKu08Y=uP
z>F?~qiNk&m)uov2J5l?!fFbz7d3Dv6gXlA3y4L#AD9Na-kyz5!-FS06+l<$%5V5ph
zgh|sPbEn?;y`M)Epa1Ba(qM|KUt9WrounxG+o<x{=b@HWSinc0?WQ=NDdGI*y{CFC
z-Hp5vLo)k&<t<gKE53=QUip&aVA}4Wk%$pBcC2{1&i+nMPrl6`1-@8@Q(S5NuZYLo
zdG~M+CgO)7;stOWA;xGdWCUH`S%%_SJvCHCcE|FSVg}f|Tx{0hRdV4tc2r%~W$)93
zsb_fOmmgj8<moqL<8p!^*f*4;ohz+L0~X(=C)nb5#{5GTJkY`wpeOF}QFEkvr-0{*
zO{<5fT>u-XkE|JF=196@nbvXm+sp-BoB5RZTjD^XU=lPMFS?D?mwJ$ZA)l^$PgOB{
z=cum#L(z6AcGx3Z1f{T8zb4a_nIU9Vzp=5Xf(c0^Ma>va&8gmqkE1U`1g`JqZT=&H
zN-$S}1kwZ&sLR30zZ<r7<Nf>sVyZpj6+6WwY9eTtPP-MJMAjAi3mXh3mP<pf%t#d_
zVE(b|UPU5!j5Ut(4bn4P<E;e>-YY1L+9@z2g**Il(rvb{->=(^$Tw(MrK7M3*YhC+
z{7w>@UESOaJ<s0Up%Ixx8M#Q@k&uy{;W^<tG~D=KhVp8uQhPfeuY^hyW}d_HjS$hI
z#CfvZyk_ec5cz+Gp@c*Ph3TVm-_WhLBXa&s7-e8nKXsKQO^fR|aix1Q7bO77K%+GD
z1tplH{v}h<Nlc<rTJHmNeg(gV6u-T|6s+%G$z8!#kLYPmWd{b8r_DdXRzsqCQR6FG
z+`t-qWp+bSaK>d5xh+%*wXgEv*)R@aX6_$8Q|oh}4yAU~d&#oSC;OarF^;i-Dm`(#
z_uVMtQgg@7{>rH9n4|A^dQE5!cZyOvX8gJc9se1Qzgp2ZK8snCAaHX$o2#3cBH&G9
zAW!pAEc_zW(euk^9LuMRPKEQEJY4!TR}tczGs+CcpfizLwQ{-Y-4KNS2>$S^w7V~j
z8I6h-iKX)Q%tg2m?tOHc{zZzAeCjWr{J0wMM1!ArpacH;^LKF1>jNVZ1&k6!^CNj9
z(*jNj7<51j^DNG}7KF2ovZIpE93qjT8N#ieZvBT*z9StoZP@YEX)+}^SUOZP^D}mE
zG=B+l(orW{kT^>sMaBCgjJFHI&PswXHMcIi^b_oXP`1E)Mmml72U_&0l4aYUwFkZT
zjk4*|jy0)-MQr$S>X<MLrRN6Sh&a`tSGM<uplICJuUTRCB;c3bo05ekkVqsrI@X4N
zh}93ZtnsWY5dXbjpQ3J87VJ70op8j!cx$ORt&P3+x?YZ>_7xZ>9RB{^&j%Y)$%8g3
z#63lwqe!*yB<k7k3lqQ{35p*MjH399uI%zY<Y?8>*d9m`$@@dX0l6minXR`@kG$k^
zh#vk-YrN1B;i7M{r%9<#EUiwIzkOdkxsq*&3*$!K=YfoHZkTwU$aX2AOCdx!^wIFh
zMc|i>vDco@%{K?ABC%frC#%<&<362*v?<n%XHhFK$$Rq=;xBVCFSgl6{Db<-D7pR^
zuw6}Q2yq;KbkKO-Z$ChuNRPLP!qm&ihu%#XK#6n8tIGVU?2%V}k}orsE0Sx}wIEzB
z!=-T|^3B)2lfg8Roto_KxnYJPbfDb6Qn5(0F)tyEm}g9V$bp_3kKu;;sAyp{h8eL}
zmus~0<+JRGOo1ZbZl_5)xpgKbdijnnAxZ$fEy-We*tr3~Dw(6C%;G8@@84v}Zbx7P
zUlLS8d)TyGYh+uA{u0{WA;jVjg*&BK{Pm1VGr3yu*)YQBYc8<(ws1ieeJUr&*QlTf
z|F4>}|0#&VIay090xR{!>3s?uk!Sy;kR};Ecx+_OdTM7;=mAmGX0H=X;lT4?w^87d
z^5ur0qd_KwsuiK8g~tpV;;fw@u8VjoI7i}!>q@3gMV_{zx_|PF7B{G8KL=yxp$-?M
zsTZM^`bAc|{bgpWP>lz$S+T7$1<r@f{`^RSoKyD6a|>l)PJ>M<<B>;{(hTPfYhEjd
z7CY7SJn(Zb&$!iQj)UvaJqWoLL#(JHKsdiv&unD~6=+$coK~dzj6hv$MsD3zEB2eQ
zDf*10#bXI_K6wjB!oJbExm_G=g~r6rw5pS6;?t>8Kk=EAUEESkdh<U=w;q<{*K07t
zIO0$_eJ0r~wEUnfDHjEvRswwwQcv?LRa_8<&GPrBFeqthg3v&$T)9sb*lJ=t*^bzI
z4DeYs-tPSHKuZ+vIYb~C2Uo7SBm1p=<K1iP9xE_SW5K|Q+3s{QD`J`oJ9vzHK|gGP
z8p;XD@A^tcsv?LoSoVfr8NnT6DsXx2Sw-m-Fu_OI+{79^KyPPcSO*KNjunwhF?{Nr
zHsThgzC}_Mg%yOkJ|(nJL$Nw%Pqme<=Fwu+78gm$iUL)W`b$aeK^iYP0r%pb@;BLO
z%nd<w73mHZk-YbzEjQ0fYKtIXWw>&eyj<3NNA}flp@(ET=Uz&jnaQm-kB_!-H{B<m
zXp$`&^CGwsd3AhH);cwNxyE2(1WBGg(cW5=UV82CL8Cw>a{o!dDqI|*skp5>X(i_^
z1SR*d9^=3#THO(_pGH)kixvWWeE8^5Gv{q4`I+BOIZg0J76vjX%(}JAjr->`Qf}S%
z(&04z^3Hw-0t0&87lqiDU9s4E=y5;L(`pNi#d0-I0DrEAWL6G3!{bYN6#)R7ZV%{5
z<;YudDQetJQJI~-|0R%DSsPJNzU;RhUU}2SjUd)w^Qse3rn9&5@^ZeaZKsssVcnP*
z(+!C4#!o~m2j!*?XoNDTT~ntEEExpp-p4_@QAf2FZoVamvlSi%^bWrw;tIDgWu9u0
zbi~?FanVp-oS9$O?cC1^v!*jK5@<}(SC8;(S;o`Q(Dc~pwHcju1v;&B>dm9PFseUV
zO%O8an(vJ=rXDAL4Myy%#I@VSnIsGQ7aT^e-UI(PCSS^2&zHW_@A9#JGK~KL6##MS
z>bqvH_exOKX*Gy>32{n<zpu03)L)LmJqBM)r}0guN^e6WU0nC07{k*>{vl<3TH1H8
z%|ADdRRFNE7*G37v^2*Ui82{^Zam*sR|M^1M3%ZY{Mm^rNS8df;|WU18aAR*(GUja
z;nUuo%HG?82NJ&w#HK2>z~NhI^S~h4i%|~~^%!Hn%v&Xw;yOcy0Bo@8Px0-DZ(3lZ
z#m1$IMfWzu3=!3#o<8Y>Ex}EcPfdhk_i<uMW|CcOYl8I<p}%g>h8XG0s5<h>gJ3u|
zkaFaIElDTJ<#`MkkLjsSF#jqo?Z(jIHvS<3*e(C<GYWCgz2JMh4GjP%_05`7=bgUQ
znWnyN?7mLdFA0!cR~3$sI?r98een{A&kY&rdjIF)@+_ER`g7D0N>msHchB(>0ZB$u
zZ;`X~`rx?wk7)_(zP<~$<3G|VmGE9d20{NDGOPJgrTNR8LE^#FZ4yNM1E4G8Dwf$V
z4dz8+@t1o=<efugU;*%X5{CosF*w|Kl{kLv$#r*y*~_JWqe~5rCseN&qmm@X3tnUF
zxB%8<EK(}LK%EEC7{&P+uDs|_NN-6rty#rg6Dz>O;sVUDkxXg}5*K=p(O<46O;aSr
zA|U^nzJmKt&H;lX(b_U=M!xhN`_ri5`SCc}HD}k<YhP8GkkgIy%qs==h*k10v>_6u
z7c#_~T7|_rR}4Zg)B<U$Ve*Sz_b%hTdzs)cR^~d3(*0(!y&>)3F;@GoU>SRpiOztN
z=~6Ok{-^Ls3p6QW&s{ad)_r|h?>DVqf&t<%K~!qc8Hxi*#ck)Yj5!$r&~0MX<&QfA
z_FIv>XE#)<uBi`hUhBV>>;(;Yy+*|_ykl{xj~fZR7t=O{-rdz5dO_-<nKuW0N`vnB
zpttlF=A(rwf<p9;Z0+ntn68(ep9r5?iqFMyQw2$XKGBiMo5)9X+z(h6JUD&P1jR@E
zetud%{RqNmWHs3?Hsb#ZGtNlU40|x9o*ycE<Q3A2e>iHdZj0SvFer1u^M=YRF=h0L
z)r~x$!PX8B>r}NujP&H2ECwuC(d=2i+wYH{(*ghtV&NGPMa(_Qy-2*-F6<3~{%T&U
zkso{?FmHPF_csksqtPc3DRH>5^d`)iJtp>Sy|G6f>F5IDmXSXAP)C`0e9&*Zl~4$;
z+yFs!$c1M+%`W0dyXH@0fTnPUjrlAD$Cr#n()}#DDN1AmLg$9(Qx^jQF6_KNKha#d
zIub$}&&hMw_Gst1kD`vOCyPs6U^UL|pPTda83s}!?ce<fD625|=J;G?NdKn=5INMn
z=|yO+cEIF&cZWU5-bzL(@e33P4!W*p8fH!+l1y9@WDweKkfEh!Zn?O(?@*c;{k}2%
zqx9jpCOEX!c}hsvbrTA0&|Tdk^M3Dmu}13AACcJa5eu<1?GJX)?$|rg{<R@|3PE_$
z<Ydbpj{)pri2{G1C^9Iv+t3jol<vJ>fdjs&@A$5*yJ$4B<_>M?x>{i`(bU`GK%`8=
z_KB#}`FZ5qbzp0K7{jG;>+Fx?c!o8$k*RM~3K<W6#vN6Z!#g;HY$SeJ*Yu)@F-Cz8
zI}dx~A@gPMYVe~H_i?(-HoY}u<3M{Cnqg8wz}DI<H|(~J(QRX4kQvQ_wQ(>tfNNr^
zk9B>(9L#@>o=pby61o>{0CE_5IW@I~>D76|-AZt`<gBo>i}&C-Jn3;;Ak~RJfjGPw
z%q^o3mbk{hR%>?JT3;g)vb^{_-4;AR*2QEqlC%G3-EE>bgzM@Bp>8R4HEm;t)M*{A
z!*O*p%qT82rn_90wd<W20Fp?k8O%C=C_*FModcYK$6Lq!Xz@=YtNBqz@tbz;=S=I%
zr@`EZCq9?a@#fme2r|#_Gmq6h!HN!Vp1XXe2e(cu4=^802y_hRTQR}({Z7)zxbXJ!
zG>$=J%|1&zpQc;28isGI0Dkrg@qy0h5ugJz-|z|M6v#M{iT9b7^1b*so)3H=_WhXg
zWR3qH_rMD$qU{J3P-v&QHN0rM<V~Eu%3TL$<|FdaK^iN|U{qd_wXsO?f+>8`+^xEC
zPUTz|$Zyh0fzu4KHuYgKiSy+888(Ik7n?-8ri@jNnHmRFJ5Gn+^(8aUNm`ItVKg{v
zFSaRURWo1%uwX{THf190-G-Q`43h#+`3JBGF@_2fyD_zF<2SvsrEE=%P|I2quE}z?
z$Gvt<e=Vmma*B-Z)N~G9YFwD=lud<S>?a$mRw+|~!T=(HAZ^W0@|&n~DYB=hr^it>
zFNHejXJE->cTYNtiNq4>DY8Xi(?BeZhHp3${Aa!x0*N#)*bsO%rz7UgswT(B+AAKC
z<!U0$j53pB^-|>`_zzMp0VAj9@9wB@A7Y2<iLU&)W7c^Cz`FfA-p5Iu7q|+Fs<kn#
z9aJfN-Fb@4^#SKS>&^<=-Ho#Ey2bN4NgS(RuG6(Hv!e)>Er&CA^C2o_9Tl8wF#ji1
zHC6Oiu4t5YP1=$U7F4Hj8>&%#8C4Z2?Q;BD<3!)FYNbL{j)`6an9q04^xs>;ijcE|
zD@3TjPi2Beh*V#OYKLs{0q5H|a#FW@g;ssXese`^2IhNs4}bkSY2R+G@+4A$gh|^1
zD@CH}@MvFf)9UwY1z3-U#TEOfbHUo9sfP25A|s*L)4zYxK&evp*&-0VA9&E%xt1dn
zDHKjtoK8(MA+M@=<M`E8?=#5*BH<m&V*WBS+?i<8IwEyz4DhL;mYeyNk#_yX9JQ!w
zu5HBJPoT7A*IJK5WxmS+f(Ou(h9Nm<&$8u;ud_XpVW*dm<HjO_^7*VWjgc^VUFO<f
z8+|s}>xTDK)j*um92Zx#3)hR?efnqV$Q0O(+w@}XT)LlTeg9x@3*%VL_0VZkkdbi<
zDa+7KFGHw7F!F3mM;9K?2bt!eHFrgwz81ftp*5iX`FGL53~~9+hU1zbi`!|5=@#Oe
z;NN-<xkNtjRHe}SS5gJM)c&*eBB*i=gj2qFKBRi@LVBI1?E*`Lk(A$ednzlSR2xBN
zya8PF5x8JP92Waa<5e~@I%;2T`a+}796}UbwSZuql$ya#r(1lFC;eza^~x_e(mP$z
z2LNYL-4+y@N;|=|reXCotzpm?IalGELz@5HNCN42Ven)@AFf<?$6jW8s4=AAVso}^
z*QHovjAoGVgRzp7Q$ERhKHZ|heVc_GOXp-P#F4Kea_^TKB#b#`I3wVI{JJ_B2AygR
zkKhYUWL}CZ+M~G^u{+2eCRoOZq-B23w{9M8xkT4qg0{a}?@BuWP~8&z*K`L}JD8zv
zNCM}&h#eQ;2DoV|xLdB<>CD1p=K1sWGN;SUPd^cSpEJe*K7-?2-(}4;FLvU~4;|3K
zN2J<xS`>Q!M*HSnnuy4<<Q73$Y#(|?5<yd;k4L45->G`5W-g!c<Z88*KJi?j<cn>Y
z#06KW*+ERAU=TiM&B@crqK?1lW+mR2d=k7D4a|m?cD=n3<odEA_*d!%zW=uQV~2$Q
zulDY=?w)uTW3P4huTG;GQt?>Up^Ty|#h`v0duWMDi4#`D)|@*)$UpIkSu7fg|I~9^
z$AdX(K;a=;q%I8nl5<%`>)b-8(+JP2S`q4dw+aEUjBxmA!(P@WwGi^BewC9#7;*6s
z&OmhiIy&!C@-ER{w6CG&s^9Jrm?V~>`Gf~@dX|nCrUr1zV3;Gte3{_N?@cX8dKDOf
zH)ya}<;lM{GR{a2R}N&yl6#&dsZ%SsX}{&MP1ii4qw4xb^ttgCaxb4OGzYQnsNerj
zQ=3oDG4|-G7R~xKv6~aKEQ@t$XMQ(tE?fu%4#e>t)=vmmyL0<clv#W5T7aa5&qE3b
zX_5Q*#b2mHnx%>UuC4xsrn#&fQlaN0csfngzz%*(DH}cn2>z^sU#lf#u}94YMJPtb
z;eSh5{d-XaYrdc?_xICNPssiH<yx4XBussItj#Y@x(x|5<PX?|s=!-SC6aSH*!<zc
zwb2Hjlu5(jKy<27&>4iC<u)>-7q10QLKD+!dpOu}x9YfK?hN+(nd}Z8VI9-$!`0la
zS3{%Pzg)12C!U~=Iqi_=YJoDEl}XJI5GG-1#n6IVk^)*7d{T1<csvjbtRRv~+ke*`
z+et%lsS6|vemT%u?l!OMI=q(><~h5hK)`>#XGPp5OJ~ZGv8i(xb>S|hv05lkD5yZu
zpZ`G1PumRY{-vR&_#v5LFf)>9Or0jE_5yB7abf=rTbLdID2t%8HaAV<hcBQDJ-pHg
z0me0X%Xj`FB~oZWGzAo2M!4`p=8Pl-!Y#JC{=asUIueX<Pxohnd7kqR>Vw5rxM(Np
zAFE)-ncZXOX~s|OMNBedicwEL`-R>f$a0p-^y?5=%BU+Z#YsZ|J4%u1;vmuoM<Z~M
zg?w$^`LHAASzTzg3uG4bgsr+=G1MV-{<CCjM2WjV+N$8+HjD98bnr)t62xH3bwVqL
zP-dc4E0kYr8y$Zf(F0k`H(7jG-{TxMr2>prmDmc8=_8`Ezmed9(DRE0$p4`Ok<tvJ
zP%aEbo}~dlPBhYU$x}Z_l&OX*OPGVyMJwO=T>31jZXlzS;y(RKQC@BJ&kr0z64RXn
zX%*pLsp9hdQW-R|RUPj##|Dw7=h7jIin6is#81-)yB?OxS58n4F2k!zU%#tKm{)O$
z^8#?b&$i=K;8N6p9}@#xZMcX^^?s8{sSlcdz-?5X{_MI%<o_}isqjEw2VM8;pCxw#
z^x@Pq47geZ4OgK_L1r6(MB?XMXUw$KMrf%<o4Pux79gV9d;f(F-1)KNItRaSmDNA(
z*@{E04VW7%0RoAj);-KXN;JT$Qlxr3(TFSzYw46_yY>IksrO(v(tn-UqhWVg0u}S6
zt5~%p^nvQGa}_LY4FHVYsC4w+b)wuyDuM}&{w*s?`M+{yvQ<azd7nq_d9w@MTB+%Y
zTaM1#YTm3EXx@x|rPF&;@K{4k4{)>}7TjCgw!eS*Q6>(EpJ=W!H6Rm(067h%kjo`1
zk7ApLb7Ed50tz7GlJ4!a3YV7bR?C<6d-@>kTn~By1P7w#dj$bkvBzZMDXtY*Fa@4j
zc=1xsZQcFZ?G&h~6|Z8V-%3j6{RO6rPA8bEt0uPHq%ub}Xxej*$@qkH@;qZ*A4ro9
zh)e^>uOB}Q|NqGP3ZN?AVDCeSGzcOkE!{^DkQ9*a?k;KR4v|jj?(UK<N$KtokVd4t
zzV`tB@BQY^FgiHS6Z>rMZ})BM|56IT?0!%v@_mdW1Xx+Yn_F=j*w{Wp4E$3e%xom*
zJiHI8HL|4g{<bUhxDfYNH!;p1$*_{FKs%4Z!Aj+MBWr%B5Q;-P1Lw2^LPhJeRcBD^
zU00fCNk?UjS%u49x5|d<vks?xgCY)(8`jkI3Of;DAYncBLDe>ZF9;qW1Zg<~t`Zz>
zoVj4og!MM0$VNS9g#u*4G|bv2ZpkRiYAZk1p8#IT$oKciIL!5Bx;UHu;&=Fnvfm38
zWm+vICyF#NB~Y7eOYri)>)THh%Mt+Dnh)Pi6=lAQ#Z(^6(Fr$OTmvxv27;to^PcWO
z^>W?uSH-`|XX8Q~2OC0FZij`;7i+jv2`(pC2J?DQ_Ra*kQpP50l0Q&rVww@YK=)q5
zWdA$KR`vGO`ABxHGhhhDUW!gE7+!oib}77W{d~6%Jw&6$&aHGsJtS60OVl>Ln+J6E
z#k<?9f>!6R9*8r64+Tf)Q+mrM%eP*G6bFntHz@H%I$x}=J$!WU%wyN+`-&{@mf@8D
zyk25czLx@WyDPMeonsny_xT#jwA-f7Lm4aqK}tr&%mW$GI_fcPbhMc{J8$&s!?|wM
z%lF8Y7({$N{wu=vA|MJ-QJ<l0ooxX@YWX0lGz<vRbjzhQ_^cXjQ#@W}n!TN6Pyhuc
zMJH2$&T<)nrU4PoD1pKV$M4V(V9?D3361z=yoH&;(^P{7&$`1((G)3$M$c@^47^!;
z*wWXk3zm(aUR$;QAq?M?2zqr?0QEbI#_#ejA5dM?iDcUyeZ*0A*?2OrU}1p61}dbx
z2Hwl$eJOP9v77atJ4H+WyV!e_xZRd0*@zWYTFR!fbN6DLXG4MvB3^z)uP}(9nymxE
z<66HXg9AUyGrq7U2W+KAJv{<#4vc;KR%K-tAR?uxz1G(h{W<e{oYCbTs)vn0QFP^Y
zurG|E$<u&bm^#G`8nHKYXoCK5XOvYD=><B}!;iNergbwVUxT+`lC&sV){DNK{dJDm
z$$854k9@F#ZSH`+{roFcgzV}6TO&d7cnv)(&yvgl)PhYg@V!U@!w-w)NS{VO!1Yz@
zOuZo`h9;G92Dn(>`Am%#>uDE3c!Q4tLZnDVCPZnpXG+MdM@%>rq^SjvjGF7d7Mi3(
zQSjV%Qw6)7uUBRB<+%S_WV!sHl!ypYl%J6)l=S+GwfcN5eQ%HPuyBAN9~`bG5oFJY
zpHX;rZkQS<6BHfY>ahBY=9szzxV9#SNRnL9-wh@$=cOhs$}kFLN@^8z^p%FY@93`f
z80oGIv0@qSDVx;bB;xDJ4CwzBc48&+`_eQcrPr#T$-4x2!2>@AlmO8yZGUBdhx`Wo
zWJmG61s%U^fL+6u`iq8B>r1PsndPEbJy*-Dwl|M{YC0{pNl4B$ooJ8Gbe|U!e?M+x
zzQnJtE~5G@z7`A14nOTcaCTlcLu|IuaZCeNkPlWv61a`BRd_V!Bh{d$(eo!r@c)-F
z;gmDZ!(-3y`fD=p=D4<QxOrHZ-PxJ^vHxK4i=oQ({)RR7Ql4MnZa3<wgyUdLg4#!#
zQ~NZvYCKKI`hvuq(#Ugc|2@3~Iy_dx1YFw}396`4j$>gdT)6QjjtMu;>0)mm^*!&J
z>-|&)`!Vn^09ZO0yx}eP(8uWj;1>@@@{=ruZ4{LPwe26)DhN3g5CKD}5M(h$3Sk_`
zX4J4Wid%B`-@5jWBwj+X4~P!`d^=Jvi3wCiVTHm{bK@r+fg~2Q`;uHdxlumSRxk$4
z<!^r{Bg*w1n_t90WcZKoeo{koxP1Ltz&)l1Ss3_flZ2)D2;cLNnC)<)QW#r$<;o@)
z=aXnutR~mM2&ZJ6c(z!ka?sy*BwvLW^+}7TG<}|Idy2N}`1E`O0dF&2AKj~hI#szN
z_~9)TNFj&M9GsH-cX&})oA-9qt>y7(i<eSL$kOkdI+je945r`c4wUM?qSy2-sPaI-
z?p9DxSjLUlq(v+$;g7K~Ap4FCp{_M2z$*(a0%Ot-r{#lP5GJM+h`T~zw3JzFt701I
z2y9yC3AI+}ahGjY!#dv+!egDQwCChWsmI~HdEKtw{oq5ouh9%^e^Q{vlBWj#P+-k{
z;5<GK;H+DjPx1@(LgXu-lrIAcp5{WXLE|NcPPI+@mV=0G^=#Q^(h!@P;ij&B=F8oW
zBvZyi!$o?@%tqz@hGSK-FAJkX8!1vC_azpGK#z0qDZfA6zU>*T4XNEHos}Np`1~sx
zop;r5O90~*w%x>wH~DM!S^i>Pd(h<W;o*s|O0z?j0Ed2#w?$qUJ^P03`6mKdGG7|Q
zSwB%t2q}I#0H-y$MiujXV!NNOy^GN_@tAIY>xVYcSV7H<hE)I-d$d_RSd1w1<=&Vc
z{J8M=E1ll`q7+HC1oC<5*N&6SQJJADnfq9UYng))G!H5U7ouWt9aPO;KB<@qAVz3l
z!D)-1kW5JaMz25M3M!lx<|@CmJg}Q%<cLy;lnpYb>t6Wi`Chqkl5TeCt#}9+Km)~R
z#~TilKdF!ih`W~!TLkw{afy9gMgh5-(=NdQvB5LT92vY^1;fnox4HVe6znJIxt5Ca
zlP>O;i)Hbbw{m%5Nyz5=D@O<9zBKh$eUUbhRU;Z9zW-wLWZx6>5^KU%(%2QSc$Xap
zzBQJJtC1Wnkc_fp?(cOr8c+}VWb0vHJgAbO+{HE573cxPJyFV8ugD=9?k^>=PssJT
z2wu<w*9P#tLl?2%8uJCE7E-}$f7<0bmN#Z4$JM71dpE*cE!&;kn$yYN=SyAzEYegm
zE%JED&lrH8C#7S`@T4?J(PQ}v`QubJ0xYplIxq7`Z;pjudcwnS|Iw$CC?FLSI7h*4
zG0@W+l^Oorn?}F#0$7ddz5OHIMc@EdkNhC3|ELs!KO-QE34y3UBTGp|Mh=<z$4J3F
z&_8R>m7#wLeiGWprWm!7mG$=TwOND+c?W~Ya|mnXcLHQ8=u9fhc@)V2K1BF8oOXfh
zVH@f(5mL}?{#$j1d@E}na3TJC1gdil)89%~3B?KYC?Tbo{+P~px?1lbQeF`r85xVH
zD2AYfLi2D#bTr_Is~I^pPj5^NU4brQv^B;Fa#4*!g<_(4_3V$uRXCkx-1C7ift9w>
zx9?d$tDQUKYn6yKbriV2hOIGQ3{&Pw3<aWTI2T+daW7OrPhp%n1PS=cNPb#NLQ41B
z>vx1YDP6AH`A5~y5O116!<6nnD#HNYv-m#D7OsG{YZMujo9VSqHJkrH%;zv~0LNVb
zLajRI%o65gDIA_)iB!N;sc_-eN>mv-JNhW=y?LN8Oki|V3rg0xwxso%0=+U6A(Eth
zSX)LE5MOywHm&|wPonS=v+i}9PZ$Rr3=U>b6SAV|C$r(_+dQ97gdbZ**ygY89)o4}
zRNaZ1FR&Z*T4BA~oPP)&8%AmsthbyRX%(oo^h_Ba_J{yO<N~<_?%x(-(&?lb;xM3>
z9Pl2SgCye&N`;ShN}{UPs$N>)^?c69Vu5^33<Qb98g$;9CQ=i@$GZD?6uV@02B3Z@
zMiPY{EyX)v@y>41k|zP-gI%SJFxiT19XMqOqh^E3$1TFU^zD)dy<WF!wH?G`&oh3$
z9vX<H6FJYEHekCy*nSn7v`6Ntrm(!7xK_}PvWct+e1|KPKW0o&d;F0xqsai#VL*IR
zLg?NK7$R@%0_*kQd}V`#5<N4ilON)zkgD42Un|ekouf3f>?hBu-;|qd)3`C63ilvy
zcx8UE{4LK;?+>IWgP_cu9@g@{0Emyt`}XudeH;+Z$CV+DOuK^VT6ZLjtg5#qr?Ty7
zb|~d+Uk=NcaGKM#gfjYD#+Rn6)}r7O_hJ7tz)p!>FBgeTWzJsAbKmD02?2KXqYi8F
zqrUHgXgX$(9s2(`DFw0v5fuBo_6Uic{*kEiNNp82G_Tzoln^c$?32F%bKn0chGo%~
zyec3mx9l*Ia5APCz<A5#t-Bx(1h^;#38Rk9GetCjS^1d$ZyPs2{sP0})Skr83;vA|
zaqLLWZ;%_hp_3mt6lL0IIewLUa8Csh)6h7X!6GSBK8YgmQ;8Ne36uVkoJ7)b(I7F*
zc>Wg({pZde(nntbAq2~yP(Csc7x2b!!gGWk9XEhl0TOMv4b=pEW+0?u%i`dHgGdoD
z2H%G|I2fT<;Vcpw+xMw~Zj4+Nn8+zk8uk{66bBRPZ@*yNBvJ^4;_u)_3Vw8^AA~9Q
zu^0d(Piplwp4gMI#h^(4E!w^{A^Y^ZAh8tmHRyt{Ev&`^5I+PRCNEj$kn>zX_Cz!0
zPFq{+K5MbkRRQk!ULE7y-&R-TjzZA}gaOq$WO<{zm+@0xs+Cxc;jP_OT%rxY%ZL&K
zu`q<I_)H<e8eS=$;(t4_KxBLxM&}MawlR#Ns+q%J&fhee*QSpteq-=%f9H<^40iGe
z^_<fcj}I(G6E}?6{r8w3??O0({Op>^5g;#ufX@2$X?ciQR%>~3-T*_L&IM(>g;CYm
z?Lwj3YZlwWKnaKi-J-mb>h@2cqzuhq?#^Fbuttm*Flp``UsMb$3-jB?%fHb0BPzP|
ze4DBLBA?&*ur%PVCG!>grv(jXzxYq+1k<BI0&(&4Sw>&@Okq^4_BnMr*IN8^x&Gc4
z3!N6$t*s6H>>rn<{LuYrTS-oDwPHF?|2Wpd@HipY`LHfyF*V-{8d0$j#AW|zJVl70
zQsl;Z)ZPX@Su4Xgd{+L=^km2=%s1hlR?mrLr2}d}8*{oqu1gxqI{Ll}mHxbQWsf7K
za}PGx<NB@9ExLln_IM_=^fc@#At?RlsH0B6Fve@G#eb&M8DLsbLh;ZyPqGp7jgJ5{
z_*w|N5sE^VF<yjDmE3>Q#tr<~TlNDk(bm<TuX*k}&2JBb#l-32c`xH%DOlN#T3D~y
z0mn#7;V^(d=6`GjE?{sax@-9mpR607(hGJt5N7Tbx8{x!pR1Aq-tV;Ogn?Qhy4V`u
zYeUY@p~fUX*jTGqX-MAorW2*BFXNBFSOlFudh|cx0ZRn_q8atiek)<>B<%2mu8mEw
zl3h&_KIB^WoqNsp-Jd`9C5FDuPRy13+IB7;`#Wko*jzL8^5Zj2^&aL};E-N9xsL|z
zFOcyI;XM1G_V182FY-;D`xbUil?vjF)>U)14ThZ80hq_Ugqv9!(3jSb?!sC~DN5me
ze>We(rsab7yk`IF)N{XLuG9lN^%~0#fielC9qmcJYgqv<I$J`?mxV7wBU-Q@tjoXP
zQ|_O*Rr-NKnL9uu0wkJ8p=|yV!cy<bt@}_Y1{!ZL+2*TwTnJP*=rHBdB$M7{*5+~F
zX||%8DU}5k+77C5W_bAcv7Z(reeQ~3TfU-Y{82qjsoxc3IMYHeLqN5|$ILQQ??B*I
zWo?g4KR#`+J4NqwS>JQGobOt0a|vExUDZu?80r#LUS1sD(C^*%{*KRN`C5JC^e+yD
zT)rG~#Dw63Wd5Hp_NNf^bCnqLFe#rS&+BHJ<jI&vOjIzp#;0vYUfq-1+Le@PZK}L8
zhEu%dy9()5cxkk?_4Sx*kKcZthkeJ=%if%&J+bun&)i!*``_`9Nl`J2i<LVcQxt35
zQO4d@u;h!z6e=Ee>?e(TF<rf6dDnb*G>)U~gnf5$J6(wiG#m}6H@%K(t?{QPi8U2R
zR19i~F(rB6;$=BNRo2<*XU9ItssXk4JroX9x?#|1+3fw)Dh*&smUxDJDINIt)L2&&
z=U609&Z;}wiCWQi9Pi^PM>kK7Gs9Rnyys<ER>RUA^a))NdQRVyoBqP`yz_o8{L2TM
zf(v=)L&E($g+hrEz3DFnRw@9vGGE5Mua1eLBqbX2!D!KM&}pXx_rrKhan}$eM~81z
z0x0y!kLjNuql7VjAe-?o;s^X(nF4r)ilhF8*!COn^Y!rL%I6Zt?!2>*!bEcFb4u8&
z+#-ga{$ZY16LCv;uJ3f23x0y_``(;zM>*tsb(%&To;&S)8?C#J9pmbHi+$reXAhQb
zLY%3wr<LOQdoSY{cV)6z17qa*mf)A$>Bo^dIm3vRH^a^6C`x6EIPt?wVT^cVr#?)a
z=`uMc*m?iBl@*XUjb?5+sV5a(naD>#+lt(8K*`zvHxLFfm=m{6(u4mIpkkL8pe?ju
zPew@Ssx8w~-+C8J;1KZF;;q#XUGl<h1dvgmxy*bU)`6Yo5mHbUm#O=E@wc{Mq)YLw
zG0M&a{ouF+%wUCoO(#+7t=u~o8WeEX+gJL3GkN<rz}}oaSWcFx71cln^%B%gj^JaF
za)td53*h(S$#aVaFmDv=0j%Et)U*rqAXEsnwHt;g@(_`#8<)h%LHKO5IMVBK>8&RE
z(G3DlH=K(!%~v<|Sbi^V^E+kov^3EQ%Rl&a<KP)mNM65?JQp1(e`%2t=;mpE_snT`
za&t^C;_`4a=E7v|i&r8X#VeG<*PA2i8DfFv*;kJ$q%Mr_MBZ;#A(sC?mswTJ3&ArO
z!~|vi(a^v{_pn|oJV5gnCT03s=TD{W;MZ;x!wA(nt{OzKUhq%zUo8awgmup;nvPze
znk>G{u+PpM=dRTZr6j^j0MKr~cG*@F990C1B$TkQoRXE^`O@U*W&Mk9=OAX!VJ%VS
z>B(qVp*G^`q1*PbdKs(4JDPdeHyiT$F=`cx)Sf9PdziHAEb2sL98F{yr;U%Aw;Ie8
zV|2fm_@<cOjkN^qhD_;vu+CUvKYvzv8B#c721)x)JqK8MsK)f=qd$m^4j>JmB@tsi
znU!=53>^<#Ji`kw0!NPoBa1K<Hvk@K_?bHt|4+zxW34z&mO3&RfsxpkK-D5JCi^C`
z?=?92_c{QVyVUkxRW%A6bze}_q;$5u1D{whcoCTQyFYJ3pw?*d`{zGLL&5_?6V~#l
zhYsLFhQ;V(v>o}DXU?7}?LmKkQIg2o&YW@{uG=soX%K-BZh7;wk!hzzecUMG(&>tS
zK)bR%H-aNQKYiW_WCgQjajl2s^$zrkyy<X<>d749z5(nP+=`j$e||3*da<Olm0n-h
zMrFT$bjemob^OVbtFS|v6@tS($1!+{LQ$v;^qfXz(E7QU?;|u76scEewFn+%e*wsq
z<FftvV)vidOAL9V1w_L_A_UR!W6KZ6XQ^JSdC*v~>>>d4ta#|;;H{Nzc=MUV9#(`U
z8m@6p&LI9&>;23iB@;<Ce~gA}j0p3iLoEn#s^D2qpF{#kaFBa9fN;oc4eLau@R$%?
z|KL-xy35tVR4D5^h)aNVBUBsDtn4hC@p)3uvXH?w7S|S+yiWRH`L5_b?S2on+tmZ{
zKXC8;XuiXhvsWxCF+LH)`Z=H*7Anxj`2V?YfPb|Sr`x=qI#f2)az;I2Hc|cOw`~|N
z&gm|N(ov$1K|ArW$mlJO$0iC@YK00M?mS%CoiSOeE3eFz%V3c9;f*`?93zx3&9?Sq
zg4H`2QjL=`&wBN!+KHh#B$sh$Jw=f2X&4*!6ekJ^tP|_%hDq`j#|cL<h{A!X0X0_h
ze!L#{So_VF7(qe{fhFp-0K##m5C#9f<F}QE=GnHNebM2XMc&nYX`$Gm=A7wcV6dzQ
zF&j>{*@^$L6fWdZklUEb1jKLq|2m^hI>0-1YIvw&E0n!*JpEJoBg!Ho(D>IH38sV@
zP@r+ziuq(nWO-{vM%c2n`Q|iDQBgEQ>`+6;^fAy}R)g%|V3r;K-wyE5_DyMvQ}^DY
z${UIZI66neT(6y-1BuKcEh2y(io|@i5;cy~`}rnZ^_r1VbO18<g*hfVp33F3>8wBb
ze68-yWY5t)qT(1Y!lSC;_(*&hB`&2q@-NlL2U{5knRGzTG+1dn&{l=&ulvTMShVJY
z(SSbVN}X2TSHXs>vKXi1bz>Q);Xy=I#1B7NBtzUubRu-4GNFeJK*iN>{;Ahwl8B35
za%1$)X7rZ7b9j!7_5r?LGu`~67LSr2F$jlyf5v^?$&TEpTW<4{z0?@j-~{Hu^HIjM
zK7N~&WRFx281GJxlD7^i)OU<<)+We{XBBgMmftm@yr4#d^|tWMqEJDopz`NllAu^<
zD!6i<DJatFd2BvxP$<;FdsPG-3a|YrCWkr_Bajnp+i#GV9DDeaV)&^AecE)MGk?v?
zMEz@!MEo0<!Oa$K!^G!%xQpfE`oc<sMnbI0=w@E2Pe7s}VjOnWop1;?q}Vkz`U6Ex
ze>MRyIP(TIJ<ad}e!7ax>p92{Wqes3^lWKAuk)RKz0yJzEeIJ}M#-Xm%Ji+5GDrhP
z#~Io-xy^?GRLT*3gS<=#l7^m%ZM*o^Q2p!x&ucPvg*K);?M+eX$|Hs3B)kyxuUt3l
zP}&$QrFZayKln9Cu{XdFy6xEG8kl2;M_%P##AUBM<P|-j54q6hg^hcgq?o08;*R1v
zXWnU4Js$QdY@F7p>HL6g4!_V&|K%`>79SdPfYQc~>JS<<;WVE7k7S@>m@T+vqM|Wa
z6dW^9^@)cAxmQ&Q;msW#h^U+W`C?-bosT@7CeJhLhII~1@oSZNCRMU&LB=<DsT7@a
zvU`swwu$9q1d%l}3ZEU9F{$@!aXN0@=}u?tV+oAtC@-xpQvViS@|8VbRLfn^BqQwp
zv^k>7&YD>{U9eIp`*4d754XtMdeKuwl@_iJb;10BU~jQ<$5{?8;U}j@+WIFO|7mnv
z@#tWm?(ogxgVgU@`ahxjRYp6_bl69(7I<J88}6MuzEE^KjZU87>G8l=M@+k}v4IFd
zyuMrF!?<|iRO%q6tmQ`LfkRlYU_BFKD=<-;ZtQ2Oq0$#gRbkX9qQWXm@7?fe9{D)m
z4HhT1KknIjWPPgpo_zjv{wLgTk7^38Pp2oCCPmc!_ay!J-nd1CDp1PfI=^Ex?ANMV
zRp#;}N_*ZXI2j9emo@PK%6NVJ#HpLQl$b`wn^k&rNAJ8a^*`b0ClxzG_~|BW$=o@;
zX=gCWMlCwj3RR~jrqTB{6;7w@Q}4cW`k%iz{+9+@vz6R_NWp&iXL%%>BA_4Z&%ZoR
zZ&cRaCBySK>AYlZf4!+fqH10V3*vT+58glnal)|Uv>8q{4e6Tv*(UJ0JAAj&#1;CD
zAYlo2AM`KX^c^;y(g?>3YDLL<%u9AgUwdguY(3lZxn5bfJ*HMUGI(V)XP)?Y{>by7
zd#&CO@%H<lyh%pX*6bEZffj316rIoQ_@!ZwDrFSD^O)<;>);`n;;^2V*cDv6M_v8c
zqc4MwuZx`^_dF>DEBNV(Np$ve(X*HeV&I9#H`N+{y#YHbS;j>Xz>FfjiTvz4xLwbW
z_Np%%-H#y85`_*X<X&-QQ%NdGCeWrx{dr<DXarhJnwZdzAK{lsD0JIbDTj<a>EaC8
z!<(@9@J(?La$Z9l*sg0_+v3rNRtAFvJU)HZbsJ##rm+8ciQZ%>b+cJ+8$d>(&gAK~
z7sY&_;A*hLH}JS|Cg({M68<eW+oXGY9lq!Wjke1<Q|;zY?S!#p{gj9e5F}pO)ZJ8J
z={}$s#J;Wq2h5!gM}dDvx4s9|b+5nExUm$DOOhZ)gKjfIdUMPPo1A*fqOP2V+U`v|
ztnUCPrj$uYx?{hk63iVtVbDrujcafDrD$yGP^leC)*YKluS*t+1zO-ytvhZT?&y1p
zi(Bim%~6@6pqH5Z)T35kh$kf>c2q;k3vF5=sMV9sg>dTHrurP#lKZibHUvXT0`Oyo
z=@;P=9-C>C^veQQJ_>NRsw{Ood<0-4GwY>VkViug<ZBx47^=8%lkoRBZ&GwgfMFP4
z-Psfc><1$no~{Z_Fo(8^Y(WCsxBV$9Wf^>{OyHxxL6coO&#Wpl-&*Jky)8eezRWCf
zH@5nlP^MQ`xc&X8rG(&=lS`0SDLk_x4>B-`gFUwS<ea8VSa!9HoQ%=Wau+#^^tW?t
z3~TapX=Igu!J{E;`$k}(lN#4ec8PE*R{$fu+gPD0+3Rr*3U#TUx;<RhoIyfNh8ldY
z7{W{9m)nUpGU6!f*ma8)V>N29NhU>WKWzNoMq>6vNQu7HL#3kG5*jw#z$y0^J?3h&
z#Sv(GDn4LQM*KW3w^b67V#=_>2948}%J~XgpB`r;gMVE2N6ko13Ev!-B3gM~Lfuq2
z-C1Sgs;DRiBKX`^qJdh-gD6hgFXvxqbqZLuJ+HHaCDa=V9sT(`ZT!=l)y<p3+&&o_
zUaz8(URB@=-ZD=+&PsYc&z^_UAQZ4~x1n9k8(a~0IcxS|lyV!Z`!U4c>{>4ShL8(w
z;WIZO0k)g#Q@m(&jKI0DF#Gm%-{+>3=LTy6!x_eD3LN3xRh2=t_AY2Bjh<XXT&>z&
z&r#pD_Y)0vAGJ=!xtqn}EcR$l#*oYp(Dtl>0YnF`I|`5-m+3`NIB|}DffDlWa%Q*O
zx;R*+;S8c$+Y~E{)&nb|PDfj&enq(x%%Xr<{FsDMFi-t3ul~%rm*cC~Tj-7Ms#~!~
z-rDsElr>MhJLgq^m#ePWM$z}Q?>Z}B`FXGx$J_Yp{Vrb(I5F}{>%q}$i-FY}!o(E4
zZa_ItwEJr>9Y=5mG(LZ!m8#{m>aIOAdw$x5&-j+oldmQInA5@H=e(r>b?ONr11Do0
zd#A<utCc@U&hvvF^;R?Ao!o8$Dt$FP=V9u$j!3B0XM7kv154(iIfz3aLJc(TIO+lB
zPJRRj*)6#~2LTu$y9yK=dz}c+T)|+g0sL5h<Yt4rK_=m89_c<}%sQ~s7*+XQpTB4K
zP!2!gacoJ;3|{<Xl1dkKGSdqtf!vEc?K33#zwak-2KMyI(7UV)s-mi?l)mZl>xj_^
z#NO<H%>$P{L^n2TSW1k&XL(9gUcob6a_`r=;mXS5Mro@^pve&uyW42(`&9G~9mci1
zlf>jkHS^Vug%xfIaa~n>?dq16?-EwGE5yYW>wE}f)0cp~nkw70ZrqC8v}Pyac79sv
zo9y_R$Fe1u<1UKPv+P%Z@e)FG(*|x<ejD&bR;4Yuqfs+Kh@+jqb<9KnwS~SM9UA+2
zLll%|fL=wLMrjy9-AuamZjg<UQw<yV^0ad9vYxJeW{%RwT;nD}_D$ggAD0q`YTewe
z^eC~f%olLIT41|GvUBlF@oet^INX-?Y`0~5Nlu>8A9{a!Xyl9Eebl9T)$9kh_!KH@
z&kD)6c?0S=gNs=<A8Rd~?l06hcHZA8K^pp!J2P^>U(PUEu7?FS<C8_LMZ*UpS)08i
z0&z8#i(hKB+)-;alfvoMoz#&<w6q9I>yF@(9S=d)$>uLh_kC)$yT1Ee>s{CI@uVbv
zci>;~8D7n|?8y*Qyq6{BptVy{`Qjb;QGlz5Lr8f`&c@p8A;vtw6zK-&fFc$6CAwY&
zH{)AipLnSoV0>~<g6b#C-Z*zU93F%waeuR{^eD`Oaq3n7;u6GWj1=|PG7QY5eQaS}
z&4C8OJnSYtciOBQnu;j9!x(nL!3nsV_nhkvRidVOrJ42pFiz{ZHtTcl%{Ipz)f2Z9
zr@%V3;cqk>Ys8AA##05Qa;2Bo`Mmgf>j#sx4<}9eK2j+5Uuy2!>a9}A1tvK;`3p{k
zvKAP;cS{6$Dem8ff7;x}#OYjN%a^-MBAPEXQR`{r8R4;*hX{o__Lvbhkksn3ya(BK
zb6s~j6{}yf)mWi@MdffE!;!DG<X&(RCUHqIC{spv53{C!tigJd`5`QDl(uzPTjf#N
zQGXuTp@xL4QqWlLgqDU_I)Pm+ZAlEa4ds1S*%Ji4OXSKt(%sN>v&0MRsjX5C+HA4q
zsVN2@aV<NdaC*2ozGjdw*x4N(x&AFjasR51vS2j-qsIHbve7|V$NdaZiUntHW%857
zv+m%WqE@%W);&Q+=}r79m2O%5$DnfpQ$!4)j;X^>B90tpiK^mE9Y_^WYS>4<_5C1F
z{d!C^t&jF#bg;LWh$y?P`bE|@S*fZrEHV~0L|3MawgKnokV?-S?pSQfDGfiwQ`?d$
zZ;Ubh5)-^9I+FsQpzqgZXnwzy7hU<l|4?{PDn|X|{Ir_%pl{mFU5+K?3oP9FPM?ot
zeiUL<M3-*R4PlHImv;ics9@s0>Iz<9M2<7XOWPq)4~O9^!x3vZs%LMu+2R~zEAs{e
zZISVQkKuSeleYn2v9cwafo6KE!6HmIqPl}lseH{MAz$nas4;1sf5|<}xX0w)S0ve7
z&Iv9>O|g5ePeOp`B$GxIZt8B}pQ?O%ui_A~&6(T|Yna!4VXiK_^}x4qI;vmUEE<6x
zBwlCpk8CNk$=g9)NF%B7aosQRSmOobMP12yOO_a|Y*}=gZiJbsHmmJCHuD=^cA&2(
zj`WENHKk8Gb>unW=t;%d!8d>YGmE!f(DD8p<MBNPFhxG5##<NZ{VW@HWdUFqx^2Rj
z_>Tx*>}Igs#%EC&O7BOI?}xw`UV54XyHI`_g{`qR^q6?q2RMx&F^jhX58Ab{!5lKr
z{aA1}HQiKu+|4%nG&i7X<?-e%!zHDJ2JQS_o*r*xtgNs^j>M1P^AXEyT~0MZUCbVy
zZMuSxi-L>>DvTpHe%kGBB=rZun>q2Apo~oKe(o@z-NsOA1-j1}9i3+vqf2{P!yn>e
zJ`w2C5-w(s;a)o(8rL6857}^uB{a7&^Wm#4`!@o!<g-HmGS+Hva3T0Tuk1qCBT50N
z_q_Qw5Nj_}Ko>X>qSm&UffjZ{aVq9Xa4I_u_CnM|zt{Z*Y$NV6x3Dj<k$+8Gkkne{
z%=i)UY=2T)oRveoMWVA3KSF=7CYB+FAN%5}NeA6%+}F?hnb-)JS4Sw{+{0;2+tSf4
z-1>c}aQ%v$W?OcdsF?o(38e?%7BTcTWg8ds<<#w`I2P&Q${x2Ye_G*Jwev=BakEV~
z)eQMs^!1aTV@)k$Y>Pm9`oRb-(CZvg2samww;D(ejPZ%1S;WeE23WZ_-}q=!{mBY8
zC5Q)V4%b9WevWCLa{)sP3%oOOER?qoKMaQ(AWHjUtJLc!`{BCuRKt}swSPr+TwNL8
zUgT%n<7|S<DJzL@ssYOMet3A&e^$6(-@OrbQfe}58sCi(h^xd>+8RG{dY-RyjSZUV
zXCG<rWfgyn`NqV(0u}t#t*Xa3ZMV&{J_R321NGf?*ETxaV2%b`+iJ_)@*D|siA-CM
zRs#;61WPn!@CG)P-TEb!5@4u{vnL+%#a|Gze>>0gx`nKBE#KcLTRmHB9xrDug#_EV
z)oxX{6Yr)9LsNrxy)73RVRT-ZHXg{h+D9W4LE%{8s*|!BYGJ$du-Jw4zUjK5)6i=&
z*<H^7+JJuNHnM58va9*Obi1$XP>C%rl%<wY6oAx(_=Yf+xxH43Brt~G9NWJwm-B-=
zwn&sddVprpA@N#{)iGSz>3@DMT7&Lnd!zw@((-9Ov~4TrIa*h*1G*HC#QmXWzmAZ7
z>^#HE8N4-uKGB(rI{Z>%@|)P_MTkEM!i1UY|D4lcIx?iRZKh@Ik&%%l5Td;FLW$ap
z;%u>ZM?k+{!O8>6Po3K=2KBm|dBaQzZWkvH!Bof!-(}^%u3zAyBM>?AE02`8sj6Jh
zn~)NcN6KT6$v{RvlJNYpJe0n^=WJ%hOd_vSj_BD;AMLUbtMSo_GPJQQL(NxC+T;$L
zM<`aUg&J<*q!k%#qG7il&_Sc6>LNqb4Dyeidmsq4w;eCqb^Z9beYOQ=80>*_5L=i1
za8%49FqM+jSZ_fA-@qv}<=L|He3wue7M|%Umdk=QS_0It7F-gEN;UhOuN4br7pM2+
z9X0LRj)xV;ff?p&GTg;@P#*_xN4*|3RBFg2tKXyG-oS39Y_m-qNVh~Rr|r=V4_*k<
zNtzQyt9Pne6bSTle|EYyz><^@><T))T+j2}T3-RnQ!cuuer<n#Nk~}*{x{rFtW!>t
zI(ZCHv+s|CsRN)+|Byx$Z0gF*O^W%h)QX-QzADYg)2I1&kwGI=Y*)z>yEiX0g;9^o
z4@yXL-biSk2{H;%AR38Uw7RX+qb+j$_~EDK44qmL0#0D@xUikMh>Of8q5bf3hvFgG
z8}SCZI(p=qM0OvS;zdnYEeJ+P;;$JFoaQ%oIRKWZVPj(q0Sw9-_pTBFop5LEUqnf*
z@N*v~J2DH&8B2+YNpPKA*_kh4P_chX-01r4=b(T1Met*WcwnSFFK~%I5n{~Y4v!(E
zrZ7ahKuL~QAf%pbIgN9!gp|DKHOo;o(02;~9@Cg&slRmV!oLxIY7YhyGN44VkTe_N
zxEi0=iB53(VTEWx9eAHhzM+r()@Ms8dK=Ke6!@E19jQf1pPV-E@f{pq=)`a>Dc|tx
zdlnl<mah~7Wp3IMHp`aJ;aqjNbKl{W*O(f;)(dMMXC12QX)hIKLZdYo(vTu*7Q%C%
z0tM)Nb6D^xm&6dAoNe?oE&>h%;Gnp>E0l4JVvUMnyKbm$^`BG@+?O;Mi#wz)hin$5
zx~tLH`%K2G)^A|pHqd?xfCfGan2{e(7^q#;{2@)kD6EX$CK$bWh);Q;Hb`AZM)zEH
zQ*j_u|3IjStR-*jtx{4<m%m`X?<&i1$qsG%T5GJc*IHen8mR*QC38h%M{UuV9|#Ca
zWinrGs(;{~I7kz81En*}Vr};zmtIwWuacCUw-mI|*i^}jIHYARhY%$OFh*F?nO;Ry
z4v2O3_lX~h2!qm8Qr~H&Sgsr*N3YeKOmR%U+u#JLxG0i7@&W-YPT>i+7lFl23tD=f
z;$39#S!VD2QlTfMpXtQ?-D<b<WI3`?+kCEBkNc>@{bE*V!Twu5ouPKac<^yv+W_1^
zWXX&>1e`7^C!8TJ3SFQJoZ2Q4a%zN0?Ue#_ki22G8bDHNALQi|sssdLg0gXyg8Vf5
zE^@LgJNy22r*hT}q5j+8-9TZJ30+Y$KiP^*Oxwjy8akrXVgZGGj_rz$9XXHs!QE94
z*W$i{l*gy<MgZok)wl}itGh-m0^<w}ztyS{cSw?ocE;hr2)ztvK`yuPk#;Cmg~3jp
zLGY8}!u{pe2%U?-bvlJy{0rwGj2R^akFB#Ka-%mA0=II});g7%g2fYtgnl+&kPBQc
z^cgD(=~aUc)bUgr0DIaKHHPCrh<<y-=H)`&f}?^PQ1(^D@QbCIKe;YXgXcI(a=Qkj
zG02H~=<}zL3}fU_4wi1Z&@4|z5S#1q;Encc_f?CA5q!C+g{i<L=99>8PgS%uKA=th
z$C7L5BCQ`uCDBJ!M537lFWzkA|1)81K{_Af6Z<2G1{jM1Cy|Ai7(%dyKvNqH`vwS=
zp#@QZ0s@fk1s`%rq`N6`_qzNT!rpswWnh>P{?Z78f7ndoN4nXcoKj>Nk_XT$on~3l
zvbVHiVEC^TQQ+xsjS+;G-%wSlRq-D8%(w-Rp>~*Uae>fO$qRb?OeBXB)SJ37)jl|n
z;Qc+dOL!G-1KNTT6!_Lk`ifS556%nW^;6Q|F9kZaLT^F+xc%HEH|Eg1c6PM7GmxNn
z>|jZV>!uV+^+s}W6a)&>3z7wqCbj?IN0I66q35r#ochk_dZ}JEL>r{z0XCL65B|+>
z=Xk<Ew~gPndww`u7is>gDDl)_^WIMWv!Pi?#z*Y@TK<)Oxdk`M^D4c%h?#7k^UTJ%
zh6ASn1Jp#3oQ!#xivhFfncgE4-7UF~ot7cGPNUmX7l$FDWv?2nCZ8SXAp^zGk1B=H
zis)O59b&@jP)s8Cj6Izio93YFIi9@dXs01g=?)<RaSpK}r$`-z4P8|t-ycCNKXIUd
zxmEix#oK?-6f0@F1s22K!8FN#T5=?7`MLE7>uMY0ZoJ~GooOU-c`X)hBASaJabpAZ
z>IUP4$563XjRoJcar4*9?QXLmU(lad9KH-W@W4QI02?a?jpa<pGk;y&!w(LDUa2DP
z@KdFtOxD;aVbU;Y&fkA65EPQ^@en0~>)XvVaI6~jRAK_K6<J7lDTZ>oh8T<Q+L|c1
z+~!c;n!ARbTeA;=jWnQj_^S~}-K2jbXx1>6&y92?x%5OG`)YprmdzI0Ea5<E>MLIP
z^G%aP>RPlXh~-&1LwB##A>oqt_wR;x1hG_cPwbn-N0%WsgmrM&ZJjIAUasedEgXFV
zjKYBOIbQ%@KBDBn_>$EmC+>*wkF%k2ng<ykaB^q1Du_lxp1a6KM6T(lG7&+SEDz{q
z159thH2?bUxZ=3Ivs3WV7e(JsTPwlW1Wot*6&UA)FggwAIotv{dd?1m+YgV=h>yn>
zFBmYzhKOc;$$ayLAJ^b!G2YV`EBwNkp#R`UGV{r+jL8UWV^aP&aD&t6+uU!4s!gL{
z;*UoI2&~ve3J1?Si9|lGv-tn$<R#?RWf!K>bv_iCl6Or5oP5oM?XjBYUQR{Aiguwp
zk61@^B5$KuNB#Ulv2Q}F;?NX0pJRV)wBDapkeULy6Rs}Aj??e@Uw+xTH~_s(cU#jJ
zud=4F$jS|O9k|Yyiqi#KxX^&AHZbmhAaf+gPG;&gU@>Mzh(|YdOJladIEF98OhPiw
z$$B=c-eO)X?YrMK^?=XtmHuG?uFcQ2L(*-o9&=!Ag(yD7t(9*mH4F4#G^jS~kZ++(
zr`AiGcsWm*;)kz%t=BY>G<e7FCr4l^37*{5J$mC6SAxX(N;Aa*=U2~2RuE#d<`((O
z9bv`!_aSeK1KT@Tj$5sl8k-OTRPQ)nWnfLFF~wU+MXCCd#9mH50WyKY%~u)@VYKzp
zgA_KF`17uKgXMtLq1+eARmBkCx_R8K{!W=tFFDhvIp~`MTk9RRr=dzcc>;iNqxK~V
z0K%<~@aBqZ;B+j(Tj*7*k53d-me>Vp>ZQ={lHBNVNOBsM0Sk|7OJLXYSjg&?`qh0v
zYf+(6f%yi<Cy<wC9w#d>85zVxhKiJKo7n;N+Jd|~M;Jb8&!$NwlDvMM2&N%!+{e$4
z%4pmOLuV>6ZyKrDH4_1t5h6UGoXBE%7-~lM*J8AL@*HBaiJ=R~B1G~d<&!S882e*u
z(6(3jus7q$fnkBVOp;1abWxW6EW$~*e@45R(enHdFyd>SI4C>^3pd^|Kfv=0$L{Td
z_~XVz)olSl8^FjxTxhl_-;0}y-F81nE59mVdHY&BmkHa1OA0~ClH(c@>l`S(JrBOu
zu`XGcijm~aG#`y|hT2-UshB?A48)19AxgywcG5(4f66oy+rna?DB73~e7!zH*N**(
z8mCV2#}t51Zz}>g8ABVPa0e5G*39j3@N@PgBdrH~@Xvrf;>%3Pa4@L^bO0QvxpOHu
zsLR~<)ihBaV)DRZ#OkU3wi^&`THZ}rVy<3ht!>gbS<Et&j?{oYiQG0MKfQhHmytkq
z$ybE;yhwrhOy<#xSk{8Z0>;FZ?hx#z{uoATa-J3HZv1mc7CgUR;gY!>tbH!}gp}^1
z#AF;`pMPsLKntXMcfQ+MfA92Cg|@@t?UWx9!`wUwd<W#hGS?=6ehA`e1cUx#>me>k
z41P!1#YL~}(($QK-C1m_mqe5hs>M5VG#D!~evmWq1h#D~n(o_Nmn&5oZi&wmq~|A<
zx4~DMS?o4{V_;+tjCG}A7t`Nos8q=d!(NBw&H7c`yIKDqHvC~s4}nB{Tqy0<naH24
z?Cc!=IJqy1K0tu627;>PMcbT!1VtI1%y%7cq9$u3i4SE^Z&2kcVJQr*1`2oV0&3+Z
zuBfUG4!Eb2;Ol+a90ypJ>N=mxWyU=935dLcbVlyaa%o_s_&fK+4>ZGgSz!{q0TLIz
zus(%UgfnhzPVYxI$VA_Hui^$XJIZnh&tw8FYrkaU2Yz3Miu?|KHY!R2;K2lmeP9=^
zxRPxl^6|B`Z@-)d<Zh|RF_-#-NRUBdkcr9j(#)l~6QfWNW<YVte6gchG^A|k8N8Yg
z#DiL6_crjOnU%c+hRT?c4@%?c-vz9q>8AU;dxe!GEsyvlQgG$IkEQ%?hD<Bd!weaA
z>_fS&$l!MZg}@?pVP5k9(;PvV=I1nbKlm3&=L=ijz(=eB<h=%MmBg2;^Kuj-JYDME
zg^%M|Qf;BQV7&gWSC5E6?f`VWNP6k!|0bXTZxdo3QV3ji$HViiYTWu^v*laHr?oSE
z(Ti!Qwg{54P|@L+lZAe}LElx)F~lFUaYIkuEgP<}uKP@kEs#GB_`t&0N1)-y0(Rkm
zEBQfb2)3><e&5L%r|L+m;WEs8TUEPdK`u(sx=eg@@H^QGSI-1FnA2I`ZKvR|Rf`V;
zKAQ%>)fUDO>5Xiyz9XLxl?GL1+^XXm(u8qVGj~7qTDSnQXMbvg?8}C=Zq08}fWELK
ziP+v;d9c4gX}yWSD-TqBq;$p6kMH@nrk1m!r2V$U)aAH;0cIH%bP{pdeoG@R@Q5v;
z9knFFN1)I%W(Wg%Mu1w>zo8rCeUPCW`zrry=tc*+buFU6iV0nzu6)F^XBX(ik5yh!
z<+?NbZYq!|54_z}oW!q{nl{5j3JYpZQtSSZK2w<AIg)$7x|R2Y0!<)`*pbPJE-`OA
z2oGmHDrDMbiuxHBh;iE;&Lsi;tHh}HEcJKkdn36UvfO5WK#zrKU;+YQfa`7UL^#v{
zv9+uBSQC&z4(Oh2rvcsoE&?Pf33<)7k3hqU0`*I_eyWa$nEy4up=gzK;jg@5|I{7?
zOlFf)(tP>*9i(Mv07E~7s2F%X$3Rg?>)`o|f7l6tsq6Nk<AfenGHC=otem1Eb;&Lx
zigw{u;oCe3h)R*zydBNw3FZ<_hE*!o3J=d??A-Z|PoRxUi(<|>xvndg@lGK_ykX$6
zkUAy?0V1wW8T?!GEiBNzhf;~LV!TKyj(MBN2=!w!t}fzHzvCG%Cdw5Y{OgL!W!l_S
zWFE5q4E@VQ1&~C;J$nL+ihsHDDoE=No#)`crVhZ2?+V25e_*5!3^fLX>i8O%G1w_f
za9(smB7rP>Ww#-Hv9gJ^{vt8HuB)@2fzE<p-|CMfh;r_|#rH@B#t=v1?~gEAbZ-%0
z?a|YJxFAw=M(<>JMa0@IpckZKDJbZ2Xx|Zta{L`<@CTFr;4zjZo3sMG2ofo$NK;k|
zuT8l>0#oU{IVxoMGQ>G5zo|W>FzQl(URTRsB-@Xmd!S>8G(tW@Y-Qv@Ju-#(>trsd
z7C;&h*3)zIHT$*5XEl?eB`l^aW<oywx(#~PT1>}V3^mR&*x!R?=lUkWwn2x^m!Vz<
zGyBVfc6kp#rfl5(zw<ou`3n(3?_^{}ME|`1>FYPwU&Gy6$VGTxV+l<rEG?glFmU5R
zoja_KSk;N_yB&=2`+l|&@qnU|!9`93>7{?y;w$ZCWADnk>-JSti;7iL-!ApymzoQU
z?(?g13l<e!&Fn7|J@=!tMH5+~>>>xU&pn8KF{GUTZQNf#*gsuEY=XY3ON;u86%|7v
zr5PE+IfEnQ^+E?W84ZfEnV&r^%Sku{MAin+1RdgqjLvlP>~ubS4sY5}CuvaPAQA5m
z%y*Z%if2@z1%loZRFRZfgHw)QSCQBVS59L5bH}1UF{UA&X<}rrb(09D*Cxn0zYK~q
zLjx<K<G;}1r+DX*ay|fA8?uE;7+<l7BKVm&+OKr5DHa7N-^4t`Z0zd=hn3LF-jo*%
z48XV+U;m=dD;s3Vt#|Ml`=L{T86`wA1<WQ!+ULJxTls^Me-wxZ+2P|4J{%Z~F0&E(
z0e7Y{=D#~s5u+E$#bnwh#%ZTNPse-KW@7m3>*4QAzM&JUh`01|<kFe&_pL71P|A1C
zezf;oKQ_x=o){>k!tBW2EycjRtf2lB3f$w<p@GHIn!M;b{C?Wc9;k)`1^mV2?^U6Y
z^97`5h_4g=?SrVM2J=fAWEQ0pWf-H_6Y2;~b-cAZYSz`BU^7(xMxJ}TGZeOackd*}
zwBL78Y`N1)A5iiszP8GSBjN1bEtLxO88hn_h;xD_zJ&*xBRstY20%WcKrQ_wT*#I>
zusBfHB<Mx*F_}K~Jt64>E5AmSpPdAS#gh<lfE!8FyA^&$lK6Hsyp^rZz7GGj{5MOv
z?snPm#0uSB8nMSN&gmd!cKp`+R*P-6w6j3G(jEoB`+<ZukbUY~^!xwYN1d##K#Uaq
zEdFKm5_xJLjHx}Fe1SxR>4F9(nZBB`fk?{hZ8^%1eFlLai}fxeruTVPw}a1}ZdU0D
zxskg1N5b`@x%|agDY+yF(3#q91LF}YOpx;!x=4+Wl^!-Je-172a|Xsx%je-<!1ZJ(
zpl^`!eLap(Q2wOL70kuc+?h#eHr0JzjwNLVo(!1=HJMJ7|BdKNqCm`U;r5Hq=!{yg
zJ3}#r=e3gNWIeC%2y}IS9bWD_y4~Dh5%IWpHKL{Y>NS-ud35%(5xqFuYb2i{k|~-L
zH$E+C8i^FGFsB1f1ol66csvm+bm5{TUcLqJRcvDjsflIuZ;dEa_h7zjDjm*F`QE$N
zAdMZV7zi#p+g#t+6v`oMg{F@CAOhT)_#w30tAP($Vb;2E2T@^Wc{NjuGb`?z9G_uL
zq7dt_e)+f~L5t(q^&9Xl)+H0d7qsZ;a;~j~M@1U#wgM%6sLPc35ri^1P!rUOd~&Q2
z=roFg8LZ#0k`OP7;g(<ur@gK?Celp?Ju~Ef$@(`g*aeog>_`+;OZ@B%3Wv4=*ATaT
z4Y74jWSkgUm$q&EHtU;61~tGj@MW_(4-V_LRB2L9KyxtiCoWQKxxp3`mV)c={0Yvy
z)6cxdy@G^AANkI{>AQJ!mewj7Z3_Q^PICnQiOMOB|FlT0gdtBZ<K+Yu14Zbx7<`(5
z?^{z=eg&Gz(F3*}0Wo^6;jbYvRv>A8*tGx<CfMdA==9y8@0`n@Xm)ucY}48M_5wko
zs6jVf#lp>#Ke61py_^2>O~#pQBvr=()r(v*m+%MJsLbaim|*6f2v#QO$`4)$xU+Tq
z7y=jk^avqAvZPr^-$~`bFMq4N@Us!Ag^yTc6P!xJ<l$XAZ=V?>#Z4iqS)kaBMSxC@
zq%9%KL<h(CAxAkpn}V?RI{{*+1r_c^fYp#q{i)tH$*?g@j*~bXWY&Dp5%`JB-36|f
z>Ay?zoOkm14u)1DA)Xfj10Q`p%G0ChJ-LxV_At-4hqoSe*|mPl7L0&v3x8-U#0RWQ
zLZ-hdqJyWMPY#mprZI5Ih}~n12Ro1_y>fj)41G-MCHNlw4@jnGG~(cL#RP4}!95|B
zsAiGH%n=@%FzU-#W2d|`U&&vJT*8nfGd%-|-5}(GC^F5RY>@=I3duhnw|~h}Tb#ms
z7?)N@t7MvxZ>fw@Hf0JnzWNuyK*QC^XXvQHV}dKKVeo&ztM~(ipIXU{R&~oz3d$?4
zlJ~<lRn5~;@dpp<!J3D8(ebjmdCV;AqiXW`ZTbrwE_dY!^NHl32x!M3xqJvUY2@4Z
z`Nz*3SDr-N@1;oUn~an0fRT%{4&w#S8#qUz=Jvhkj9F<JU(`?}90OsrIqb~z_=Udu
zIKz_>E5pV|d@C}}t_WtF7+a=NrUy65;EOBHp{AE=9O^gXK;e?;;HaLV@O=QWy*4CE
zBMReR;@R!{b5lN?>x|V%e2{f;gU-iI^`4YM{OaY;6nYe!`)Itw-yiLYV}spLuKkkk
zTiOO2hd<x<;*T2@r2FAvb_g8ik#VvxlaR%+`S0n#7V`lNL(3;W^0GyS_NS^+JWUl6
zYaWg2ia=^R{0$%Rb1!ilG0oNEj{0Ac2`NNFC=PUUDUXK1kcO37_ofc83EYTl62S_+
zQB=?g%2vF~eZ0fg>uHo1H!*cKSx2vB!jH~NUoQtpGL!s<pKz8G;v<FJ8(t)#a0ThR
z1OeGMRd9n$KX{#=G+q^jOotKH;FJT{QOnYC;63;~?`s%P84Wcwx0_F2zG6HmJ(Ibs
zR1|Y{vk6!BjiXRqonTV)n*vQa8YDF3-|d6K?4GwT_<wo6%enFr3;po+x`8Op#=^EC
zK7!dFo!1!FAOv`CutOMZ?xC+5G`e9iKLxg_lw#x|XL~L+DimNwd_fwu=Ta9p<!q~G
zn$i@T{_bppMYFI_Wd%QYWQzRp<x}ZC^G8!fAbdPBsP3H$lXF?=CQEKPLf_{}BsNkg
zWWIB!2`!Iv2gC;Hla~LBawv$h1}WectRa05N!EptH?YarP$0*@h*j)XgEfe1=-l+T
zZS?_j@FwFMQ2t8knMluMFuj1eNLx`-WT1(rj($dtWaKTD0L5(7EUf4*t=SU(JMOOl
zLFv19cOrF&T2Sr_!wHJ7I-mfJhR&Bd1ka8EMPcwduw`$01L^x7v%?x9xK76PCXSM)
zALNq?GJ21Jt(Ejbh8?<61bAD46{~N!$A;D(>}+jPEu7M=Z45LqrePJC&CXRhA7|65
z-WRJ!HfQAhmFOAz)p6Q5oXH@$7(cONS=B^4T$Q5<+zvx?Y7l+~2iVmdx!h;+*mv#+
zYWd+2YKx3*VPxoS|BgN@G^+F?AMrj<1Nf*kYJaGoF`&in5WGN<Lm9)Eic(*d{n-XK
z#A<)zc9Y$0qqKm9!qe00oUjJk4*^%5q~8S>iW8!$3HThAG2Aj7h%X#e=6*n4uhJ*n
zIZ!3ot3y8S;>P-~<M0oFqCUIXjk{oSDtkAqSOMQ1KlOn$ZUUOvfxwHyRrc+_T^74$
zGmfv>?U9uCaROsy^@o*N)dqJr@A#A79cINxya<n36dF>gz=*=87g}Kd%+%eFS+X-#
zF+bN7Q3*ISLaKL_6KX9o>Ot|9-JA#fg9T!JE{Zd1hNR0Q6XZO+(U)TZ-{-tH{Z%lX
zlS9zAIJom=E*wws_!Qeliu-bGvt&w7z?D;nxf%_pu-=qbc+7(CUF2aq=eW%ajG~`%
z^biu{T5H>OYpo8~x{%zi?-uDO4u5wEv|k*4qw%E$=ZXe@skh107)_JC^}H9LQC6-x
z-eV<R8zaA&%T00MAT?yLTnhM;0G{oK)e`;yXx%JgV^v)m?fepu<OliJb`TzX)=Xwz
zxcb6cWd|dTD9F<>bJ5FZ2yGK?Qq*y}!|J}wv{Mr;e|*PsbdZ&~FuK>r&ayYzZj*U_
zYCLYg{Qd$3(5)uvBBv6*R+2_8${a7Nut<$*V<Se*SN8nTfbYtFLzmSPizNSlRDESw
zlwb5MDc#)+-7(TgNDSTG-6$a4A>Am_-QC>^!U#%tcc+x}efj<GeeS(q=JAWnob&Fp
z_u6Z(bzZqx0S=e*-IY!zN!)>igcNuC{-G)Oa*dK?RGrG}s`(yx3YpmH%wGQ#v5I7N
zi)Q7V{Vw1KZ*}z)X9M-H{pl$0H7g0;I{fVXN(6_g@EWzooFUV*0{f4NK4ev6gUDXW
z3np4SxHf1(QXL9AKuWf^x*WX6r*}QqK%H8(m~(mfuF#*KJH4@XG<K+Cl`BYLp2M00
z{M5g#@!2lh$9ml&wK-rE0)-T*;q6~xxxEkPINw2_v}XI}a}y&F*t+`6GMQCh6a6C}
z+2#6y2L6X-{4+5~or~ohU^PjiA!$tIgE#sfot~&xcPW)NN@R~i&FmEk&oMoy{;f=w
zqPg4B3;;$;)TV6i<wQXwEqWXhthrPzQgas_6u{XFm~sr3Mt-EW@PLUd6|Q$aMR(@>
zHbP@m@9(S%WjE})o5v34a{qU`sGbN`2C8o+H=YI|=LG!WYLAHQ-mdi(MMje|4rCNH
z&sckLFA9%g;IzF_t;5+YqQ}#w#`x!N0@jVq&5-AlC6LL@F=lfFQ7R{pn4oj~>biqO
z_ROluwV1*tWrA9AJ+*KKyN}3@aO2`OnQJikaLy~*278zN+E73QnLUQ(?U+%G9Vaf8
zp`IlYp2Q90ruXf+jnT9H@U%DrKF^fOMm<i*zZeO6bQ0|Dzf56+HIY4oYIAKR!r$Cv
zaN)Sl)l6l6Wj4~!0-Tz^zS3=YCgLQDy#AC`X>M>L=QMYS%FWjkzt{L&=*4l&!=p95
zeLYcG|31K(0>7jEyIaGGH2%5P(+AzRC5}l|Oj=AaUr%OxmQdQ=sD?O}-|A{!|E7<>
zZ%xC$cPEvwUhTNv7YqoI4n;5K+Nstcs+Ewu-o-eXB<b&TZ?28-=7sd30wt*)jt5Z*
zC`ln%R$=8HU9YK&;CX{NHfR8OUdTO4NWvD4<?kJ+{?@W&G=4AQx5wzNR7BAD;-a*F
zUtK2dSMJGf{y{mC>u<Fi716UT10KLvKi^~QbARjtz8d3(_<@n|W0CBnY(7(ZpvOt_
zsB2XeP94r`bwJilFWUi%A-Ngt+vERECfQxW41lSqO)IDAS$JekmelD+$r@tDuvoha
z^O!w^#PCCrGv$%J?%te)qt3Wbtn<(xtYH)$DA*rgoE;hWXUv$3fEu6r-t!!6Q6P4b
z3AX_F1bx<Y*p(Qz69i<@l{^oq1dv6Mk39^gmH*44nKIrWNFN(qi@ecaMDf%G^Ou<l
z!J*JtJu#+$pzKkspIi8ueCs<zJYNM!RzzH3O_sW08Bm|@AACDC8WCdXX7Rv8AD6`s
zb_1ngPx>~){uRsO#Pn@{j}7VudZfYC$R$q^2Fv4^)^44~{;&*<Z^tK^#tArF2|?54
z3ey}r!wJeP7_itVBRJsQr@Va}4*@a!I2FgYt5ckHF{l;o9S<e5v+gYTksnm&-Fug?
zjH4!T4KUp2^j5#^>6yz`F<MfJ1;!uGIDkPGzYO{<tUd#^zQH9-3EfO$kfClEQXa=S
zeWkD{4TIv&*F^zbrVY~<&IMOb1k0?E+5%g42|p|fQv$%0N6wVEF|0kL@hFddZr-vo
zH0L+=WjsrtT$N%=W};~Vx&)M)H10m^00pFK$rqDTQVc>`8X`o_L^(cW6se6*Tc4BI
z?s7{R&0|lFSXsH$LhW0kXwEh8E%4*k@k}Mq=^<_oMtw%No22%fWn)U=q|#(Lv5`#X
zAiX+y@H`gq!Ui}Pd{j&-y&lc!Wu1H{m-8#;W&eN3COrYtKz2%E*MMw49xz%er(%|J
zm<*2a=a=mn|Edz5d`)EUe4Y($d$Wb4QMaL4B!Yp%=&kt7bq8nS+ha-aVtaoqv{S8N
zPL8IFN7~$u2#tHZKX1!@rSU(UX3F5KwXMP+^1V7HnLS-#-7nLuNM7BVb6PWhx!7vE
zT+cTRynsUtbs42ogbIA+FFXxHA=$gB1$NZ{W_s#97y2tw%_h@YrJ&72Mu;uuP`miC
zNT_cD+XtI1IQ3Eqn#z10-HQm5WpQi+HaILFr}NMCUo;`~^}r6MN8@g$$#yk6W<mqn
z^Q#@<ss+3-U%}0@6Jz7!MPNfg=K0buus&YJpOoT}0?&vdkv0DEvZ2TDeHi@xt<w1@
zAUS9I2M-J8a)&a-)!8_u94<Zh=xbo^I~-JW&c!Z772_`K!BTgHu!n~mi16)HDkrh%
z6qV+DT4dS)3LcGF$Uo|kK~?>k>d%OUGU?MYe5$P#MiKjs7)7!viqw&-fzxKs0l#y^
z?CJF9-o98J#mv=myB~nrRvWaa&0|q;gem`I7AkdjSj(|B>&N*I#iKl|c%NhUL_}Dq
z4q+1S$W7e!4UOe;dz`-eZQT7PG_IyCl_M_90)keQ{uby*M%SgMeAm&MT_5Iv7DQR=
z)2U8`=N>t-8$8#NDQh>(?>bZ8<ceeyn|C<%82e{_0lGm2a1o2=kE+z9^>dd08=fA~
zsJ6R(#2@}9dK0o4lx^}KxWMQ+Q!gL<cU#UQ5i1C6<-t39o|F&8wqvq(YLyIxaTFG~
zy_Ky_h1Yo?i6WW7CcBAFch>3q<}Pf(Pq!1aRSV5zjoQ_a`BtY8%xGnhe{TxYM@<`O
zu>vuFAnXmfVD$O9b2s-cG6@Y;h37$ZqC%=#tGaaT!A4luLIX<C8ypa;=jo3$L0571
z9=QTq%bK<Bm|+T`U>b${mJgqE*k8mmG|NN1`Oj8}Zg@Obgs?#pG~tO0r1-HPMJ+;Q
zbH5;><>?%0Gu^tX(M3{W5jm|6EH@w33v#J;?t#UKzDJ|rA%I6zb9#N~6NLglEHg>L
z9z=&Hf`rL#58$Ky!1Q6Cc799{j9`lyzvIru(MvFsfXtpo)w}rR$8(1^Xqy(k!i!&v
zM~>vQc@g4@>Z$Kw|B<bGKlhS?r4MZU0t9X|tqXz5^WL>#<@y|hrBHh#?X=~ujY>>~
zRW>V`IP=FP&*L{WtKJnhHS%!{uU!X!YlN;6^zrhnmua?$glSQl7N5ZN)3y9K=gHvq
z<26~?LUks#zl0h^=iVre`e*c==^fUxl@<8>vo*8?Tzc7{YmKLKgLIRESP|Fj3URL@
zSA{U(@DAlq*)&=F#sTC10XwbufQ)SRj`bjgJ{)WJNZ*9r@Ey6Op{mJp2fOUz77^|z
zG>_a2te(eG5gRy`xq=emku^1<76@O;mAZY>-kPVWJrFw1Gc~czVT&ZQw0J%nJ|-LI
zu6z)-WJ28?rvK;gBcwMJN)d+*nkus=m_FVOPRJF_53url%;M+7rB@8<O~~zQF<pr?
zHdQxq3U*fS08pkI76iE3zbt#Hm#;&Wtc1lMQ8iNITh@aSV1*-ub<jxV`B0-ldi;nN
zG;sA+R1E(?ITE}K*^4M^_D+0<ef}2>^^K~Ug;K)+%0z>QOAXl;^{uK%I)U)$`pVE)
z2O;_SEuRT1-7GHHNz70Ddeq3}W|3E<_1a;M(88DWOj}xwvbV_=MgAyXpSyIf8mB-_
z5vBNv=a|0eFRDb*?<g(SBt`@6udd35Z9&l|LbkawGEi*h<YIZP;IuSRTj~xz2YYqS
zBueAJ__uP<{gxNe&VXuFs=?$Yl6O*NOSlvu*T+Xh&68#6NZbNaKAYL<_aXl-ln%+?
zedtJ>EyB@%nIGPfwKc~~l90l*E7H5RM@AI{E-V}FYYj9h`s6-i;ILf<qxk5Me`B-V
zdPz1Xyid!z(x3>HjVLDP1)9=$<D^jrGQ(FSCUjfJ0O>PE*8SQc)okvQ!IdbR@ybSw
z_{ZxFz1fSf;QLXj9~SgqKb}!6+-`m62hIK|C=b>}j7Dcz>3SjW#5{6E3tF67>-;3{
zw)<0FB3!?S4c71fXaS5oNx4z4OpJguK=}NZ#HztV@s`^ntb?0Q33y3H1IpI#j-H*q
z_w#j5y&mMnC*=Aa1D4tN@^6P94YW@F?IV*I;YzoLM{^fOHvKZHjK|Kms0#lLV<Prj
zw_ZK1!_@<Z<wbpQd$lam<)Y+|A}(0!hbpU!{0U9Epe2_Of0Vv}o+qq)H_Kuh^Ql-s
z)sssuUp03Rf3b!PK`*@mx22C|2Cp=q5}5#uQ3fBkP!4h%km>gULl-6{59x~KY&n<|
zKr;XJ)c+(tz^hsnsc-&wlA*1RsI;aaxRfG}37hPXk0pzxs>74sqGD`UK|jJ3`~sL9
zZ|j!~|A%{i-)m{NklM8{S>PiGFaiCU^?Up7hP@ApbIE%f`A{6LMG=}0gOLKfAjzNJ
zmwQlVDcd5sbP1+&c^q#1?tHlfkRnrtxzugV{%lpcoS3?g#zuHtGp}(<JQY&(Fc+gH
zWAXGE`&D@L<t4#kH!&W|@R5E=){UB5=<m&!=ofW=!Y|Xz8k;``G4ez*zX0cZ{h(3@
zf|7pI4>6q?jf}*jvG73n9o^D)TKi$KK;bI`B<7xDp@G0i=E3$)TdNb+WP5x1XVhm_
zo%}U?lM{jH`1X2>PSyE&RURC%j9g!y7m5J*dzsER3yRGiJQC%0(tjh*aIHMxF^PfQ
zgBNez`r?=0LOYMCEC1i_3HC*F(a}=lyzZV_X#~{iw18Ax+Q0Su4wPhLSpflhuaZv7
z##qoR6r}8<{`2-*4C;rY6sf;-C?s4Y)aL;C#kSyqdUzh0Q5jOEx%Kp*Noqd)u9U$N
z;_I{ieX3OAVg*ShhvsTUI3Hf6fle+_$O<)?Nfl<=z0~g7Uc#neKQt1K2A$`V%M>KP
zxtW-Gu7S5qITjLmp2vi*@ukj7?xYY1zKWR1>CRdY$BpIodcRGtuXdWHwT3vTNLUBU
z%)^sUrT@%!ha-_maHC-|1l{V!t$wAcnytjzO&09dstNn3xy3TvM=t8Gt#lfoD@tsv
zInLPcOV_LJ(M3OV<5#FiBBt}2b4WxEl0aCWp62`>YjwHRT7J1>14Qk0ERP3pR7uHq
zDx`n>7jZMc9EoVDDPg(G6?kEe!G&Mc)2)GKfzpdUJ{c&{n>QBKe?+Vith57%{LAtu
zgH&5&wUb%sPCX}e(Xz7nDL);E#v6^>aTSK>6CmkX-?#;u{>BG(Yye`Nc8McBwOyr0
zmXISIPSq{yAytM#3qe0hRb~HHiu4(<?a65tB=dzZ-jjm!p~l@M<A?gR(}HCdh2i^i
zHQ5u&(j~{dRi2VtOo!q2hpHV(X#kfRp&vwKKQ7y;ST2DWhR<HFUha<s3X!ATi6I(#
zM!YOgG^zJT5{f4-e`+U|7_2Lttr3KU1C?3=mGjr?TPL7X{9{qHje~1c#_Yd=3$p@m
zCmhrvKN$YO2Em*eE*!w~-FehOM`GuBJr#qU%2IHA1VQ`&@$>XX&J7@%WR=^5$I9Pp
zXxZDMC98whJgybq7Z=-PIZvT3<MPrOchO7L_SNdg*)`sG+;X>2Fjz_n+}(UeVp2_@
z5vL8+mk$)8pfR@|z_veH?plNCzK}`bB%pDNmHYCg_`Okr>~D8HQejWZ{e=917&0PF
zyi%u5z6nCg+26F2<vw#C1-uU3@Qsq+>`ZhCGO<JJbZa(DS9n-_wCgqHj?;x@c(hl)
zGSHe{lb(3dgcwr_;#-Lp>!@XXgA8DUlUJp0>;??0$tNJf&eV8dOoTN|1%UCwq!xBY
ziQ<^fs@N8%`aAjBHd?-L%BFv+#5>q8_WQdCQ&zUhgL9---yiN55GgMIU6KxH<6^~+
z->z7wtNNsRc@>dSXp~zj<Nx}~eG{A?L}Ai)f&9JnIjTt$(cOy}{07}Q(A-uO4@^UD
z&*rne@@tEFQZm-C(^ZB^w~{r}Mo}j2@5@`E6<nas<FkCMT*{Z#VJ7ITJ~Kw473rWg
z@etZmLTmo{aUu`~P9=-yqfUX8#Kbbd2&B_lqj%DOyK6@dA(Hms2S*S!pO<K_cKkiu
z-(X_4QiMuT4}`|H^UE)c-APnCzN9xAhrC98I(&NWTexA#KHbAfQy9&_J}=7lXUefB
z9mx{nT&iK$E_y-*XW$(V<O$zk;fyst`{!w6&82N-@PHO)S?S?N<`FcI*%nAc#&3l_
z)M@?4oJvFRAJd?rv5}s(GowbfVu}yXXm2SI5g`WRIyxs`i8w<SnK~K<J;8^aon(xn
zY>|l*Ow_o=w*ygaE;@`RN;1OD2bA;m@ZlZ@jtw#R7+6?XLjc<10xlUf?)7(=7LERr
z&g;lT`m8ND?7E_?c~z%cV<^z<(Tto-8(y{0jr1V`eTK}biVPPIjDrpE<o7e`+u{H@
zKKY>_E`B3yQMY1}59V5mtPdU-e2Lc}6PIwPxy#nep*X=5ZC^^()O;JPA<m(iB>t{{
z91WCa?3vMV5A6z78l>pmKbAUVUfd(t0-jGG%$)drp-0Iapm{Fko&FITi)`46fVgqn
zb5G%?T%{kCdl`K+F1eDeo-&gV9#xZ9MUMmS*wt`wsHg^ie1=>0y@KwKmg$~-aj__*
zx3b;L^gQG8U-<N|RzJ*>N)$37ZD%k&Q}%FnpIv^hoD-r~NrOVng8H~Ep7^>_)rpOJ
zkupl7P*r^O{fk1iV=D;;I4a<j_3B5HLy7FAJCvFxxc}ooY>T|9Y4ZdSn2OTvCFxrx
z|89#eb?p0B&bDc8uMEp)zf*!B51c<HPAJdgb0d4*zwuBl*9^29WQe6A$|n659229P
zqy3xZ9mF2tNB@j&-GzW?;8TfKwRWZO=%Ilgr++942@W*3%^8+p>A>?|k7rh<Y=Q=|
z8u%CqK;nIjIF28K`Vx>vaiIOk<B+o09qr%R8!Jo`$X9W?`nVz=d*DTIPpFZ~K_H}v
zQ(wgDVrYon<%Lt`Tnk}fHw?vjZoC?NYIG>whwB%{qL3&wPP&dSbJc`qKu@(vf4;`{
z_t4m~Io<ltX^Co8M^Yq|pV6B40^R4HFbEIKwrvWI*WUw!>~&Ry{iR7qn8?tH$NXNR
zV)YPheeD4ogH$Lc3JgFV;mV~e$9%s7O;ObAO}v&ye8plxUW@3xvDm*q3pk~}M-IaW
z_uHJU|JLf>l}CE)USU1Z2gns<6aVLXf&&)K$s_COd^Je~^eL5U?&8CR5gn*{bH)v~
z^sH)V95aprG^^V~Y2RK-jdL(m-!CEkEzwkJEw*|R&t?h@;wjKI&}i~B0J#kxnhr1h
zmpI`*|7HUKvHhq0GFK@DO|0_0ld{gT$o6h0HT>2WxfT;$B>}@J<=wSQokZ10(k*sp
z7eiEO%VWaB&J2Lm1xWM*NV?x8flYbkGe7RU5;jt%Ba*LUsdZH92-t%Hg+5&}M7$Nk
zqkG3A3FcUR;Qv6JLJ>-Iy#r+Hz?F6Ua3ZBh1gJ0ZF&#%O6&mE_Ul{9KnY(fbkh=i=
zz({NEMCJi5Qkc!vr&1=__W<XP;z*&wc`W8(C@hqnNp^a?V8wSG!4PWL5o@y4G&4$Z
zasZlk<)#O?@#^>A)9THOCtAikI$9B_u%oZl<-bD8YS3mpCuDn>dz_Ur@Bw;{*N%t)
zo089h!7r6<CO#ii5&xtRho-hcyZj9cc2&}#R;B4rsV9l<5<<|5Wa-$rXh}$)Ch@##
zT4Izq5SK|*reT;C5|I3OJiC@}uU$EA6epGi0(q!70gR?|W={{pCVd$E@%~O@^$74<
zmGnfHAR@=MqHlW<80_XVEfRfoX-<HmVLb1XnF0Hd&xfGC-M*N%m(XF~C+yFgJphqQ
zd^GCndG@hLC0id?x0OmDlEMFqmRDOjBNCz&@V3&VmB0<4{9Ro4Jc{JL4R60w0J>~_
zS(Cx037KZnman2sZrt(&EJe-1$m#wv2^)`t*Au4^vgs!JO#@+M{Gl#Qx%@*3hkr=c
zj~KC~Nu#JZDQle8qS5V|+{+Ye-d9&eIf9roI632M4b9xxfSgyy1+uu=D%}T$Nlc6W
z)^V+yucHlXwH?^lAU5ngzL@}+0Rpn*Rm<KNd+5HAetKdOrKOC0)8?adQG1sM`fCT*
zgI<PatNEzSz>m5sO9dbIZe|tPu;&ROkgB)5vFb3o*OUIkAFNW4Wh4wWjkr!E0yIM{
zWA!-sucW)B1czN=OlU!mj1JqJ!V~wdDb1(IanQkB4g26tk!Il3mo`hg579U{{4b|#
z4sKl1P@bbDEdRx(!GEjW1v7FJBKSLnNxly^K?Qz15~1ibQ42i&r1sDHqWVUfwBhzY
z6Sx1Qu%kvv8Wjh8oR;F0508FPrVyak@5cZBwOF3F3l)Q4@WXX(u>H<3Np_>(l7}0q
zp!`EDO+3?ICZU7fw{N84?JQ;b*dDcaiF^YY=#3IkNaQxAnOI@ho0NDA$}~?yf5%nw
z*SqYz$rAX4i*+U@H9yBy^e2(fDuDfS3WWiU%JVYe>3qjVu2|srbUYj9mr?&N41eG)
zn!ggcT_MSA8gO!7hWU%;{sWeJw?5}=kUll!fhQd1x41zEP8*IED-5|Gj7SeFQpkWg
z?j^0zKa*~+Fs&F`QZ0NAZDfLgsahmEvbm@!`;9x0GIPS0KTj%K(W@GtqXRUys%jiM
zc-dqAUF_!)rKC|~-|rGg#8VA^e(*fsxnwL-{6^~imk5$%UMywRr`vEdSLc-0c$&7F
z+{S{RIXm=3{xoifoWAk)iQ9X^ygQB*608fCRbQ|3+#dId-5_}K6A!q+mmmFL`B%|l
z48K!>Vob_EN=lAIA^@OCPY#q!g<%MT>E)7<ITOgi6(*8URmK8%1;Tu<=SPN<yhTn7
zA4no!FFtb!e9U#Uu%smPmBR#L0p48(OfOk77POYoR18b8*gq80(=?MxZ_rY3WJ`5|
zWn^erXLCyas9(?~*X=r6BYlSQHFQstD;<?F^Gnc-gSeU)X+F(Q%_;$*0|E1*@i2K>
z2mjK%oB*Zbv>qCdTtJDTL|vL<kMTUE7`rB#Sw*d0ZiteuLM3MQSa&hsW{>x2_ZM>_
z)f|UOe<R~`61T+u+qDu0GB2!4NR~j-b%oSNqiL=Vwy|tJqNCJWq$F@SF2Av%W~C7U
z<&#K~2%{AyRDtckg4(q_G|L5NjzbL&=ipJ}R50h&6+OKQ<h9&SRj7uBB_@sBf!?Sm
zXj2N*iEX0I5S|#A&U?8u)BfC#KOjaMOGx7&GT0s2eJ+LViZD6H=A90-f6k$8Bs<g`
ze=|aSJyNPdr8d`1yxQv<qr+Lq=gFOwEFh=eR;(Puz`mI8dj=w2?!=3yKpmJWO*nrt
zu=J#6HV(1;W#n={sKBhLSH1P~vNVmy8oR|wKhDX_Ozo;jE|XH^AwjB9J6qf+toX|b
zQtkT9XJ~h29;wh&=cK^o8BeI<4raFVRhBr|&Z@wZ>dJmborN4xq!W{Zut2@+D-O!j
zB)7YGpxcL8o?)Sc91+Runic2ERezAX{aIH#^eekV(~WBWYD3_@r#N_~SXL66_@n7#
zd7b;NBIwUhnyUR&NiTeuZBAbp8iG1RhbI*MDb~KlG3^iu5IQkUb60pxt+~8hSbz`@
zj_;cpevz%nl1_ddo*^JBRpQmh+g&f8vYoHw7xlXjeIa0FkQ%}!v66o`6yI+`#&1uh
zaY$U8D9w0EA+$N)ez^z=yg7{O`LHB=A24q~f(Pb%pJm+j@Zw&T?<X@n<Vws<D<iS{
z=ZJrQz6r0!qz98qjEct|=YszD)@hB~Y(T2Yu*{_HF#$8sbiWNMv7+vMyj*^{zf#Yi
zBgPxJAe%@H3sI&FzW;Nm(A-7m!`AjXX`+j4#D(<bBX2)Up#1Tx@%{bB@5uxsJ-Nev
zTO11AdBlc4tB|hb@~FGHH3hoDppr-KhV~b`Jf7nk&Ho5rdQqc;=aoP%|4AmtCE{ia
zcIi;XjCSPS4jq0{oWB?SzEuY8*k6ax2j^<<O?-BKnaEPR#6}6dBL~vZk4DCXi+zw$
zDJ{M7a$DQ|dSm};vcjH9;S`m-6pj`~M$3<Xc7Y(}EP*fcz6Y~-2szVA1|cm=Up7(F
z`Oj9(j+eb9I^yzGlZU$0Xw^E+5gYBKQ>c}y(>r7Teg}B+=BZ_cRLDa(Mxw9-;YQ|S
zuSyoSBh7<6AzP3Y-XJY79GT#_yy-{cxjaQW)GT7f|H&PA#gxBaQ?ri?zH+VDn=IU+
z+Mh4OX|RfxouSzbEr^&sUZs6!as}K+^jQ4~U)T+W#77oka-1W3qDWt>NHK?8Q#gFG
z`Cc(Ac1ov)+O@-No^n0GZ=uksoiE_K2{FG@PfA~bEoF27hzwk;fOaU}d~w!WZ+S@w
zir!CHZ02%>uG{`1ZYb3D#OiuDSL;k@bJ;{*$+6doBvqC_uvTdO2w%*0fI71R+LUQ+
ztEWE;CLaXGPH#EUAJ1ru4Wcp@V{o_|*Q{Ad)!6tY!bKG*GTfw~6WE$n`Z%y7R|d;d
zy?B(>?_AE$BAxK%nB;c`;<jYdnDQ;hSGqg^p+U>wgJ;su{+~=#yxw#fE%EX>G3gF5
z+%za8fZPG`U)5I}XL2}R*ne<b6tir>A6_B3oeR%vIgmteYIRzLOjRgd({Kt(K+r!a
zb3+Jk#Uv&zELGKsbh@Ubn~k2-Wpf4^9`ING9Ci@>jB`l6Cg-smq~WohU96h2R;0uT
zG<jOfw`SA*OzKXWnf-8eA^AH;l(I7AH$gxuUHjiN#(_AZv17w>q~*Ikp^Ry^2u~+T
z98P0D%du}r>0legVh*Eso}^}GNhDku&7C*op*@m=^5(-!Sh@9HG0$iJHu7Z&xfY+g
z|F6v9{k6PXClZNdta|8Vkzy3-&WlY;e3b4$`DoPGal3A(4Zm?%53f+QX-!sM%O60B
z0gLmdWP2bC%~sfrm{Qcggq{O^Xwr{H&SNY)&QPxbIROKOWJNF|nU*G$X}QAs?yrP=
zLOC*pqy(feh9-zfefKE>E6=S$3I#XM=<_}C&H+vsHMqGKc(i72eU8T>K8m&OZKtH)
z<i8;li)pa{9vS5#i-}$KkTE5cBpJ&yVC;_wt}+~%^?JVlM(J%Kka~D^<#>m5-|ECT
z`_w=Jfcrm&@7KP(15Z-)*9^oiBa_HukS=f*czk94v~^uMXZvV?_s;)OlQ@;hg@(M_
z1L0z8D0M&&KWeJ48?^sJv0QcLNL%LGhc~fRoN_=V5hej>?9NwBLF#+`4_H19lmB*>
zQVL}+0Ir>mdsKq{e}V&BhjJ8|2?n+UUwuRP9%+W*+G-mDg>F1zUmAyoh2=|Ei#cC!
zYIScYLL=XgF%LpFpJilylrU;gnuQ9cP+<7y25j{VIPuhY*8A_>`xkf6t_C%lAiHc6
zf%VFGm`G=m5xWDlGSRvckhc~WT?fSc1-0jM8gnMp?UnwSV>k<wdGd10?f!V#A`gX1
zjGW!bxvlw5Tq90wgnzP20-a*Xh<p<azpDUmqZ$<I2xj%j8XOsi2EmnSHa|XSE*1lS
z7gv)`Ria!W`Hkz@1noQTJN3wcU&$O4^7znNdSyCY27Lm2y}$qNTtTF}Ym6#kPzrhW
z0_;jfyQu<+C|n7iXyUuS*R0R}e-Un}#J+znRRN?YzM#0sNMf20mSnczZMiDeFLKp&
zKpl#R7|YrCnaMBvg$dMPGaPGzN)+94luX=daYPJ=nGWy1!-Os?(|-Ebn>!(W?_{7)
z%`Z`+-M-l7`H)k$<6XJC8F>2gw!@!B;f*)ukH*q5ZpTM1&2oC9(B}+#hmE)6Na>B%
zgH4DUNxgL!oawou0dL0ma@06xqz0=N%X77@6sRDj1_&SvHm#_N#-j)ZL3{Wv4nV;?
zfDb!Ib!`=ymDD6(3Pg@z7L|Dx?@t?4LPR#g(KMu6O50LENcl#jlw|AtfeLhRK*R$<
zM4!sj7w~-3mRgXfH}dm#EI&<HqqnL5r|(%3b?}{SrUKDuo?7#yPmI1ibbR}!cdjo9
z{=wznvVV~hrxMV)%KpyghP|{=3Vty;QZ4D~{AJfMkYufT7F@V7A(L^h_8!#ge6eeB
za&K>X%;t3a8ba4}2^I(dkO#`7JL(SdYB48$f!@!Of!HkM^bw+(JiTUXeWu81XQ?8&
zEfyv0dm(%WkJ@m9jD17+{4Mn<`#)D4GflxCB3fu<KHBx1ME)YP4Nu(AEKUm=aV3GZ
z0*SL9>{l-6tEaOwN<cXFA_N^(C<U2|c5q3iTvb)B&LF(Tv_Plkx-U568nO0*tW;b6
zzB3=<j?pkPyer*vyxC*Qe>M1<Su{_q<I|H%T3JDJ@}Xww<d~0ZHPC>>g4C_o>K&jN
zD?;YKGFp%OA3Wibc&%pDHOs2Priv<d-2;E7Cqm<8n-6(^HhHTl6zW=xGz*W_-OgV_
z%UJ-i#g_4B6cUH=ZNb<eML-uexEoI`Z>ac}3FqzfB9E$k%(fJiExQ#RPev-Bvw_+6
z>&l|O16Og&Ebqwdk4>c*wF*Z$HB~ARXY}mAvnqa%`A{?4iJJDZyB2cG*Nvbz2pQ`j
zf%T>l-w1t%DT8s2l~N9kB_G9dHN_2H%Tt%^@_L42ZDB`pzqqueSRnpSXe+eh8nOC<
zATh`psjpKqLA})R5v54cx<kXsjgkujUG}1>`TRvQ^!M%Anp%xB1Djqe(H-g{r+b$D
z0J$(ZUBxbjS)0$nyI5lJ_c1u?l>u)RGg*}^ua7*b>K&KtjC4e9Z#`5-LSv_%9=?-B
zD*;+93s<M9R=O9`a(WAUvqLqNa>Xy$Z$HskGATt)hVe8!o%30aS&822%42<4tD{)r
za~xX!=E|mSQ0iy2-0m(TT&hqzy3gB|DlO#5EkG&}uJO$gR^Z4IAvqXkCiURigmHR;
zyPT62hyhF>2IhP{Ph&)uZjf!@vvH7aD1dDzw;g?2&cE%Yd>aC;>_xd%dB6EH?(^xN
zVZFFEa%2*4&T-jF9?7TeXzo2nUcz0593dCt!0Fl|idm<50k;cM(~lYZdyR9H((|on
zix(Ab|DsSxCeAO!A>skA%OlEFeXa@c_P!iZA3!%Mv6%iQryQzSi`iWlXk+;+D_h2s
z+9AGbH!0D1pnR(|Q9#ZdpUJR~rrP37-1ozu4o$8?x5u%ol9mck)x#fv0L6{39Yb6s
zhVRekR~qpES=FCJNG39`xvd8{IIpLDq8mMP&T(+uxL>tFQI2h~P1P3mcWCUSnCO@J
zv$}`ez2x-@7NTq8KOB>#%Hh^C(fZxY?bu*#r@nYRcN7x)sqU9~UdwytOiRM56<<sh
zV=2Bd^@z#}fYK!Cs*1#^6MGdNA-XE`(ogV4--~GsC?@iz3`Zp%+{k#6qZYyBAuqT)
zGB#Ky?Eho%Oy~C(ElJ3&;nmn>Rxp5_p81}9&qWC5tZ^#P=nt@Crg#Wd75_b+(LE%B
z(+^h$7HtDA-*@wrWOKQ@*QJ15`j>-Msl5L*&^RENGDzN_uU9<YtxTOEVdfw3lPEjb
zk96{SbqvfTMs6sH1p~tW{i1;YLqT|*k1}pFaoEj_0PP*L1&R$aeAN<t%ptkh%9M8?
zYKl%v!UIheOY4xM6x6KY;NnT_PJ9Mb!1r)DV*c@*xni_d70D8<MSfv_(W<M8Qx<v}
zH^c-RxF-&cDplKb&B{~jb#s%F=@0Xyu4&!EI$88$*;D{`4{or%80rhD6T3~Fl^_oI
zlZaSPAeKz#eYMN!wD-T!OX)bDBt$WQ@EIOU<jwp9eHt6#w*_nNmvXoLCrN|ebAAUH
zt+V@8BYo4oS$Al<uo&O5X!w9!Wa?LC367PadNdpg1w=IqR6OwH#z+RB%c6bNWl@&~
z#+9oWDZXflp6C9==f-0j{3L@5{uZP4ra8Vvs$#aBrKy0AJ~>xqf@O}w=&cZ)WC?nn
zTY>e5jOdC-&e@g;c)vOiJE^D4X*&(teZxHLFQ>NL5>P)Nm&o{r%>f$dxYsjvvxOF7
zyYyS|OQPEF9k+u#3|t99p4nwMv9OZZ+jJBXy+F)kyDUlIf%Uwv%>Qwg5jR-Wk9**Z
z50YF--{n}Mu^Ucc&wlwg(OdRc!MMmxAx_I6<U&LHK=>2nps8q(6nN$bTK|tOxW{LB
zr_@Ql2wQC+mKG&l?MY?}XrdOoa|B)9aOU<-KX?1>{FO}>NTMW^R(Oo{SXq+(9&vSb
zu#I8QEMKHhN|~*?J7<!}qo=OASA_T+h_bOkTCQ3B<@|%ykI)V)&8moQ?>~fXUMa&3
zFe~?N(h0#LRXPkCinO7zH6HR>EXeCAp$ZKwfLq2H6G8oP|9Ea`+JjsU%Czwagv&eq
zIfpn!J+MXp^R<LO*a(n}35qh|p8Pny731uszTd1V7<>-@hPG9DbyeT0O#U7k8r}m*
z4<Vte{ccVHw`=2n_m|`(bEa=g2CL5Y4~ON*`-OtZkzSQmQw`IB?5hZJKr`%<rAJF^
z%Ks`hB%5x+&JNYQ5G_#ycR(~Q*1p5+_o@vfg~sM{&xU7d_^3xPP+Xj?1cveC-&O8`
z(jCAe*K580GGFbLT(*WWPR5S-%0Ht#<C!0u+8gQTJ4=_%*we{nAoxn&P)o}naq@EW
z$;t$iyr$A3giLpCxX~z>r$KSEsAi1TJy{9J>E2L8B|NzK|7ZbjsX{xr0fad?e8Q?)
z#`NuAl8C`F>k{5#r{*}|<?=sPubBc}f0hNd6@Rw5t3*UNBr$zY3`JuQ^F1I@U66sQ
zS}Nv#WOv!!R@)xdfHC%uKsl-T0ODNp8;H*CsIJx00oIK;3G^;?c(2I^WglwARFYnC
zs=$7w1a+1)ha80d-c!k)X!ytql8%xkUI~c`hasKy&fhb@`uKkIouEbN^`!R*m&<_E
z`v{#t6}K~m70Vsa1U7hCOOBGmoRt{1m|As5=Bd1k^z%1m==|SD;z?JgmZ}vRx1~ZJ
zJquvWqHgTpxnMW<keg~UP76cA(|I(X$Mc1*Mbv)Y7$}HNYv<?RMULmY-aPkM;1J$u
z&4&ISAsVamI(1_+!4JYZqZOvYIkkG$LFs8srBzytlvq>$6_H?aKDYa|<B;+#h?bzE
zDgwtD=5>J-ZU%k|1)V4&|E+8w>1&<ask&Jp<<q<Mg|Ysk{<6<_?wjKTy>~rj#{3P?
zg5uR@!W)d4!17?mgdA#vQO9}WHdqu~-N5{MH-FbHB|u6m6W&v^qe<@y^Vby!<Z<bs
z!x1;c^~*J)&5!bomX7WL$16QLvia;<Ep&t*BW+#&grWx~N>Q86J(yti=C#_3lPND(
z+vyD?5b1=b4@Sr;L3Pa|$!RU)$>$RezCt!P@2046e<fQEXAxAkQb={6r?V}5YO?4J
z_wUbgA8NAD>=S0Nr2CvozzugJ(}xVQ2&DCrHlW6qy@vH`agREFi;?G2p3|bMkgTkr
zky7?q{d$u3d<X3Ut*=MJHwoZ3zdHCo-4n3eKjpLk%VhIbcNDB6H~<$BSmoBgKT4^F
zp8@Bg-4?{5sR325(tW|a0Ofzc03QGb%(38VUOu=dkF{|4TwDEngvk*Nh<@{p6xHcR
zNnYF{;oP7x1|kGHki);+?#Z(J()Ad!-+RGhaBXi)$-%)=>B+$h`pTqcJ`h*RtKvZ9
zKKgjiySZA5BZv#mcQW3%=tuIp-v-qfzKbzhn%x3AAIJr}VH4f#$vYOkw~^=0ypK9Z
zKpwG>7(CR;WCX*-%K+|~p@+T{LZ&;iQN*`IriZyx2wr80XU|g)za^x%|6F_?3N!x!
zFu!E9;Bfn)X=W3md?$%Nki9hC-w^m%Y;abEC2f@+J1zDSw(6(QV)jw23fkFvJH{*l
zKRELO&h*5n54ptNCvzj5vSWFa?88H44@J|Vzhe;{R11|Y3iH%R$9J1Y*7*b4jx|!;
z_?;h}u}dBW5r{^^r55Je$}cC1q<!U#aqnAgcUdSTAjRrHgrYQ6h2l7)0}(3l#?!aD
z!crm}^=|TKYAB6Hileb3=X|L9y(d*rcBV&xV^~94t51#Pnxkwx3T-Gl!Tz=;J@b2O
zqgZh^Y4Km7vFxJ>VX!glM_Vxvc2e`-noq9}0f)iT`~XRYVM!YdDhzhM`=NJEGN~}j
zYl*({^z`7VNGVK=X7g|$!gA$`;<$|GQW{sz1;W!n@D`<|e*0<;N|!8pYl9Rt@k(oG
zJ*lfh?>O5>)}K0W;b;gdHO2e>!W@iq7ur39pAhd0A`5=n!xpk7_Hb{=1X&Y;C7`-g
z32doK^%MXwp+-YU2DDZF0jg$qySxU}lDp^-14CdFVsujCBE`kqUcB!RDUw`=)!lHw
zq%!J<>c8HV*B^~bFL>&K{qB6+KXMdt+esCxgSHo4={)1SQ<atVHWP$s*DaBq)l52t
zr)Q;CJk(FQf;5`m78{q9Q!3W8{cIj()~dlLbTYIgvU%lm0;fMlg+}3;&x~q8v!pvD
z9MzqG$SKFMdc{t8?}Nq?pq{~~gBlxN%=Es%u@A89OlD!9{J9q)?JUPVUvn$gPIOHm
z3B}&O4q%O6h~a06PxQVz7Y%rzPcZ(z7U!!{pqd2jtZwEcAi8cQ6wDbyhT;Qmoa589
z2^h${>5P%s6{=M1B<D0xXr;n_5HvsJVaf;}JG=N_|K-)6wh!j7T}77mL&N7Vh1ZcQ
z{Q?-$%zgoo1R_oaTZ{{C5fEGCb&N=~@ELN5H38~^IePvi{`~cG>2%9nxN`RPTV#rk
z+xLe&2g$omZjNeb5g|ABC&u-H$i>5tq+9;ZOGm_#P*h@A?^o%$(UVz>lZ*#EaZOYt
z_i~&%=QPk4OZ*})Zd%G$9oyoM2iY|g@wv|LjhT$+yC4~Mdl9(m{CR)y@~s7E1evWR
zAS`rxSU{6}erI+MVE=G2DsHL1|LXMmNRa+RwfcxYJz#vTpINH2Q8THGOI{cth_SJ_
z%A?e;Y(dJE$?-$9aNGfWt@Y-6b`&BNtcKJ4gLMsXkUp1Jtgmy-{LMC5iuLp^|H#Yj
zJ{jnhbC|56)KhuD-lLY&_Nr4f|Cr9iO!ED#_xxUNC`1;4w~F;io@a^?XxTqmd&HB!
z0a|k;&N__PAXl2cJ(=x0m)!x9u7K-B8W|JOKoZx|KU1US=LU#8b_5Gr404lnOqUKM
zF>dmLX=7N-6Fik8|1BoZl;wMAeU;hHkAKYF*VhVwhwW&K2_Ey!DWp{F5Lv90lTgLj
z_l?e6atbRr?c(e!|2)2z+HENkFumlisseBh`D+!z@I^iOM-+5jY8G0K{~(Lx+awih
zts~!~%3r;RuESwGAr#3`6Ig9Py=ZoOwk&g|>|b|rhA}aU0!Swkb0q8h`!QqF4?l<h
zA&WNdpMbxUII+b#zmE;N1eO+Y2aKQ2SnEb`iNad{3@v~Fu(Xypqq^bwC#B-spBTS|
zDgACq21~Yx)2k?2TQ#u|yb+x`<d$du!B6xMYs1b<bl(J{1iyk;xJVbA@{J2F{?)_U
zxuNWC!4x>Jzi?X!iDjZ0BtcF`>1Q-uc--;vV%HTmv6W<p_%t0w<u*Kp!WQ0Vk}Frk
z%UqL%U9<9;uJ6OzPBq67&-@^kucQG-^z67L18yRwZEqt;-yM!Bz|$sN_AiqGp(q$?
z{>L=}s1$ym86?93NRvkhe?_Z@HRxgp;ek^mTm7f(y*!=h6_0sM@!xev=+z8BV-po_
zU5<ZrLmBNAfq^%!tsV;PI`J!{Lp$ZZ^RRqLAmt{+;g+Yi^q^b`t`cm>aO-Q=*qdlj
zR_NYK4;T)e>C~b9W^e_{m8y$97RJql<EK#xeg~PO1`pb-6IU5^5as{?VPZ`3YUG^#
zm~4^HF{Z}9Bjm?81wD|lQN4{*ahwAXwt;`&KVonB1Ji)K?JEm%k5`O#1*6%>gG>ZX
z!qgfj?!}6__!0Z7aN|rE;<O*fxHh2pGp;gKb*Q^+Rkz+KMT(tz>OH(qQ~$2}ND?q2
zA{X!{t6^4`Ge3CV;&<M;(V#H0SNZ=R%er!M+cUFuz(Vf}nZ&g<W+s)rPiPj$^a+_~
z-!EFm=E0ActD(zxpJY0_Q``+U455PE+=wywebc=qAy5)Y(3h|R`;yq4SQB6tdRIw%
zdFwu;ZaK35To?vTQx*}*9~)mSFbnv*j}q>i(04sDhvUYF?Xo$DBcgK{45aZmrXvf$
zM1=w87eFi~HqZkC2q@{{@*%<F=RHCCwu)it>JJxRMcu(Xl_e_Cx*?C-+@HAvXDz##
zb)KI>+b%ZKwOlWjnR#mRO*riivk1yo#52{bv?C_pywceAIxNw^z>8SWj6uKUh+~0p
z_EaQ-k#p7Vy1ZX&1}IDD#@c`vi0akm7~fvJ7LV{;hJ!~-1BoX(3_rzi**a8WU)RJM
zG<+{fBceZj4{y@rH{pu!ZeV}z>kks5HyU)4xF7%7NQ4*?wo50Q2$LDYM;h06_bfs#
z>5K8b<$5WJ&tIR%ag};8HApt6u8ynA_kr^Exjm+_bTpX8a?#B$E?5-)!!w+8E5Ns5
zhUF63AY_rkzP6`=Vr(t~K*;9pBwJAUyc}`UGBw_3s&=X-dbw=n`8Iyih8L-`L2}gZ
z)O31ILc>aA_~6qh^!esQd~WvodN3|yJwa^I{jIPLCcJUCUwryke{9lwQhNDR$->=}
zM5d&JcrBh9t0(z3mlN<IpFQkakkyxu7B`E9$PYJ0l^O&@Vn7$qJWv&jQ}=2sn<qa5
zy<~q5jMk;!mx&{mizIHx0dwYb_c_s5AWMZqy6$}od`&Lbh#mF2QTiWZVQ^^82Y&uU
z#DixbJ%LIM$iJMz*EtD)+m1@FT5H9;L)%M8|3W-!Ex`~D^VbbPzFbj3hR7uCSyU-K
zEQ(Ow=(MRg&;6%_@vFaRK5wYw-Ym?zD^Od3M+{7+o+|HOP}fgSpqw+ZdsSgaYR%eL
zCiW8oYhn@Rr@y0oFh4GLQ4Ff!t(ARGa*{dYV6SsM5~@ZipDL2H84IvoZE?Ui-(5by
zBc86L{kYZ<zWbpgD3Y-wRi3_f&3~ZbLkD~9#q!#c2s<8F9rW9W7#8W(rK<G4)Jf(P
z&N;@KKwhc9yf?zpEQ*|C8tYV~FOTxG%gwf4H@iBw;i0`|vxin=#LNxG5~4b!6{Cf_
z3ztzYmRn;e57K?8Mj7~cjw7;k`=kEzkU6@0O;>x}PTwx^QB*k`P=%wZ$6jw+&;TkS
zPNU~%l=QTX((?t(-WQb6-_v<3s*=8-hLWjCpn>7CI>vU??G}huP;W2(elAv;?{fly
zXr%u5(PKVxPe9B&j%Lz(C?kX?H_?5I-E_K-GD&O0O=ro|!k};(ZB9S3UdkqjU4w~K
zY;7bINGdh2inF$6;F;oQpeDptUN_X6;EMsIiiivXd+dLY*Q~QAtDhGfW;cHWb|=?I
zCfvb<F&Md5mKZmLL~F(rW=pY3Jc;Yda59p(znR=SpK{rPOCml8ZpJW*qk~>;Q%W`$
zlx=#SA>yFu!QSEdK*<o75i1!;g-}d!fJ$);3`Qhtzjud@$`4wa_0jyh|0loce73Q=
zzrXMv*N9u~N2sFW_*OfBuCOV9WHE631l*-!{g2tNrT;82G`G}boR}c*!->X!Wcjca
z;i5{eXhDrHw;#~NkL8LI3dutlFSZ!P7q3Vrt`ctGeu3LO8Og<PV^ha+H!t^8CPs@N
z3=W$Pk~sV!j`JV1UQin!q7H(H#&QdE_I8m4Ki+pv3Ak+LjgQf*R(nV`*`EbVMSYkG
ze#^8?$g%2Iwep3OSa@W~A2_ny*Wj^)kiKr21TMhP!3H>$0Dofh7@(_pwgT#lk7A&$
zBEmXO5dIrh@<%mVhIwn&BPNgSutn_$-|I~RWpcr&Qn(3tOK28sZ!%|Ga(Tg7mnEw&
zd3h=diA=$m!&|t~I2b^AdtxFg=D2I3xBO!331~4LB&t`-7s`PP6q>4xepr)vdi-qt
zX!!kG%-;F&0j=NNBZ=G>2FYQ~@{JTBc2pu(6dj$VHA$Ugfw<IsD%yPQa{Ig6@+N?7
zwh4SVZtKmwJ+&C0wwrhVSEt68f<khT4XEm_(w@g<XN(#5Z5j3b>0l}dEcjgp(VAEK
zH2MJRp?1*Mc`1l^J`lY5szXscnPXT<;(DTrz^oFy^gpvosg|uf&V-)-#+7vWJDr;(
zm@?}p5o5Z5K6ottT$S$i0+<{Wl8DYBZ*(ufwicfw226PyU!}Wj%WZN_u0YW^b6~J6
z8p4P17yd*gen`bECpDmYOV^2JQg(vbZbSsQ@{Klje-a1lhW)oqAAxP!G+9`F;pqel
zYC+_2bVjcZM>bj5r}VQ}OFTDSyI5?%IEMnKa!8;px(@i$qLRTNJX%}t24)0cL@8Y|
z+<P#S1F${!w}3zHfE#g~3g-HjmL@#<Mo96W#0l5_Ndp(~<#2B~e;^OYBLJ55kFA$?
zW_T~dfT&}^2&;D;WM9_2BI;`CA(@Se=-A+`ZEt|kLe&)lcpmME)ZX*Dm3Y$UYt!R_
zTYidaJB(?zqXIU*!k++eIxs={Z?)p}FUTZMDH42ogI(%9s+mKwzi9tSR9l|apTq`r
z;jCXuu0BVVy8}l9|9#=5mFvrt?wqf^>V%X1ldxTDi4~5Rv0)}mpZtf<eg8>-lzSCy
z4GE%^j<y2gQAn0dNA&}#6KjE&FZj#4tGy0j4oraaUo@ntOnN85&gdlT1nh6|P%<wV
zE>;`?ID&wM3V@5Q4?3Qn#sS|`VVn8bc3Z*iYFtRA?92xkZGI0Z&!RP%HANkpXGZ0D
z)>!1ALOLgw-?KDvq+5e4zCcYGcLF}J4N1y?TMf{&OeOIE(}$$99xpBS2(Y03b`u!D
zB)rt?1LQtas<N4WUa^rcqKKrL9OS+*&LP<!F}orkRA?F@dFpW&XBu`0cwpsq!*-{9
z+pUr|k3CFag5`z}d?4t&sQ}gh&p1Dh(4)G9ZK(YRdEnFQV>%@Y0&Jl-wWp^(%2+J;
z&lE)NfwL9LE=BS=bT>hH>)Ad3Th_P~tU!*RGcoc6sEAQLs?-%ZSDQ#`9$hn0NXUd@
zfsYVY_!+<alwdqZTR4-l56B#q)(GZ;|7{c6f7>+Y>>0k2@;~a)23Eq*&X;9z3Qv{=
z3*mC@PSB$@XX^?a4KJ0bFOp4-=r~37Ne!UTmc{l?yMFCpL_ExGz#v*eW~=xuv}W)V
z!>oOeYK(OB5OA|pQ1NTu#B4rHI<^<l@JOKHAmR@%3|KvTd3=C09itpK-1k$OKw}0o
zJ@8?ccbdrrTH>HnJB9p~sH*vZbT>I7qO#s}%f;{cUP%~uy{l)|OzU5Xm3CzvNrvMk
zesVx|-%9nauTiHqk;x3sQa%&&g;g8>V0roXMu|TqC1t#bO#J56H&)`wc05Bv!>iq#
z4nIUj4nrW$xGYDKQM5)<-cJrhNgwf(djX1`tTrzkz`EI2I%bjxSXv*mI60$tM<N8?
zIK&uj1Gfx>#Ay!gJPjqtW`hyIMRK1T#9m^Pe|?S7viP)I%4y=f{af$xVH+i<Hy{rG
z*Oz>$?{G{xVq%&s1m^P4cV74SL!5?vU-vlAFD`A`ik+naFNs>0IPB}qNKH?cdxQQD
zh$hWW^Wwq@=L@97bo0gyrte=xX13X%NC26-;X5-jVIU0240j5?aZZ1_Kv?>YEI{@8
zAahmRJzsD3c$k|%1&F8|SlL2v?R+Ur{6Cq@H?aA66uF(x*hnfe)-f<%r)MWQv(9LM
z9Q0k_HL3+*^Q)i`e&1_L_H}LeF(hfFGvCc@Dl9P)Td&C*jqu|#9X1BtnWVBUN>IPe
zXddAD$?EhlazddI@auXv(Jp5ZWBe84;l^U}M;LG&O8A7gSg}e1Aet-G*n+_Q0zsIR
zY&T5;%@j<r0Vy`A6>1U*fx@=|Ks=*XW2?r^ay^I*p?!o0EW=M;w;P4$v9g6{8yi1f
zh<<;=n?k~n8oR)&lGj@#^n=;j1$sV*x!A=NKx&o4o>A!3*&<6U)+6^&yV?_nNXBRW
z^M=Cf@{|IQsD?@^5TR{FIUaHOg&G^2*8Isp^<b3)<i%fF*;;|UOR*>^A_1zxm)3c0
zh`8QsRbUI$vuDqxN}(xvyfA+A)8FVTgVd5wadIy=<LdV>)gWa57r{>vZ+`mmVr7LS
zE_m-_FJh2{w*i0`a7mRt0-RaWyY%r--hWP4=G$JJ0D_#|g{#E|>&k9Q9}QCkO^77q
z?r82aG{|YK_o$l`@aqFgrdLlZlh0r>8_6wWK&{%!apg4&4?g=F^nu_+4eH6_zy}X!
zP9xG^Um3oOy*$S-$D{<^6elebu$bNrT*xL<2g|KACA>N{LlFZ}d~FSzql0Afm)phF
zXk^B+Bi6pq>w}|^b6T#C%m&xrM^bU-=w;f$m>qCiSBX1skK|AkcE3|?cGNQyP0|EJ
z?TAT=QupIyObybsyNkve_$o`F{<^L8_nObeJd4wnj8zvGmyG1Xfv~Q#RWn~Ki@p|E
z@hM(Prl6BFIr!b(6J$PP4gmfK=l?Fa0F;|X5txPLo@-12CEo$-qI7VUpp+RX;yrNt
z!gsWm#$e9rmVRx_3?TjeU-}}#^<Jxy^}p0Q=&{Gm%+#&$?p+A!qSHR>x8G4T-rzw|
zF8sPJ;7U8tziF|gl!`n|EXlzj*i#%FDxm@|iSPodj#$#TFJY)=*=P7g?g|7yrKKDn
zS6juHvgK%>B_oj480iA3#DcAsT2RX00ajt$Nk6w8z}~ViVut&?*rxW+s{3QHJT!}g
z;?>|EmdW?OiaN`<sNP_Y)6xxsG)M~w(n~JgAPv$fjihu+r_$XG3M}2--67o)BAxdv
z_kTZkU!0eF_L(y?&ogu8_g%Ell5cV@?f)#0+ioKj(9iBK=}DI{sTWh$jh?@r@^%hJ
zPN?>+?dna76CBo^DGin|@s@8300eV}gNYSg{~BqekWC|UV)frhHGIzBtpa$n=WpMJ
z(k%t`Rj$=z*}lRepf+MyvdqY0!=;xeGK(saOENmEJy7u>C!-RJ<5mZ`_4ShQ;Jo)r
zR#|2|FWK=EU2yx8tl{?CX3@dnz_@`<f$6~p7$PEVcTk}W0>m~GlE)Jts7({2pYaOP
z>P1f8Y5zU6Ef!fi7|JP-L&#!~0O9~jpZd-=^Zzia1w~1buh2LU$kH}u2jU=mN5DkT
zJFu`+ZNFks1*(v(^kEE@&vhWDG;PBRhu3bQMK~3bM4|&gN!(>Io)jj9%&D<Cp^@Ro
zOK7HjjTlF{6%ia8Rl!7D%pwt@@#0|)W=FdWE@meJUZD>zM@L3GlMilG9HzUmoyEE(
zxxYV9o5*rnS0>$6+jQ}AR%ndwmw|C;PL4syjIyTJC6F@2FTikS?Jywiz9i4kYbU&Q
z5|3J+pcNg#;Sn!ZvzmvcN~&G0Lx2mCCRN4#a!_r^gTtRPRnS|)RhHM=EIO{g;C&OC
z*|d+Gq5=O3EeNZ?TO~Y^F=rqhjPYip_h^2Js#UkXD@bU`H?3AUtImcGNg<=~5ro5m
zg4gpp*N%ZH6uC(T?X}T)Zg2KL>fOnSmY`Yu{>*#62VI~BBW*DRkpS5lWV4f<0%Yei
zxaAIHUV3PDE;8V11|U<7kJeUh|EJ4aWk{)(sLoZ(dG`wsJLQCbd&--%*@10}pJ1kx
zcYvd&s9C?6b`(Yej{{#6>>|m4SYpszH`&xfGzpz~&M~aY$!F5kXPYgQ&J<V>8eX%!
zz!)VHnl`v8(5F#b>#6q@&bvZCyX=l6U=FtEZgRzWO2#d9`q(a|)Y{KXrwC{{oP)14
z${kg0TZyQPLY+euSyvkTfwAhNf@7O>Ap(fcBi9gTshDb^gd9}$<!;V&C+W7?sam8`
zA*U&*R|pK4saUNn>rxh<oGjznI^!_rFR=mg@0r6wh774rf0bRmCKoi?G_LvRh}S%<
z;XC6oz(DOqI9y1ZF91Q+rv_*g;nXIUCO|s4Ffa}q*+hegiwvn@7!;cw5^+c1IKV-V
zL2&evHHa_yVDfm(+UktAcs7vBM2(fHwn7(o@Voe^PG~CwpWPlH(C&-3Ey~7>VMsa`
zqr35Jw)Qr+%m7CII`HUK%9=xdX6ZS>iR8;TgIx@&HOg`{pMz1Crr7qr#Y3!I1iWuQ
z-fu~X`b+OvH8ICgIer{(#htrT49iW*{d_)KQben0_h+F{^SQ?XPQq5ra#>OLENSWs
z1DMVP_)F%ICIpF08*N9UEhH6tqnftIpIi)DpsT%>uMWoQ2-^9~O_MwTe5SMY(KD~Y
zOw5T9mHzVChrnvyvIn1P>vvAx1aX<{B8S%bo>ooWJ&QK#8m-)A-y}$c%iTFRoMW$2
zUFx2ONx<vNB~#A+&l)JdVN+)7{)OL=1ds%e4FCwnx-`^WZ|~|1fZAr+<lQ`hfFu&F
ziz6cBWYYE1P#OzMY0@yW=690>J<n+U{>$bWY&qufZm~ET!`gdKRS|~7|4<F9gfy>I
zOD8Jy;vj0AL+3M<Xr=#haaLL7`UvywgnCmsr-e$@O7VfoM=~=8iAiNn3>1R%)<&mh
z?R!T4V5^)K4?HIPCa$+8#m#EbZy>doj>XyU2?z;k)O3qf*dEpDvV(ndY$mfH(~K4L
z2CE+KH=LWj)KfvZ!9B=E;04PbA}TRnyx;5uCMqEDQk=%ZH~`78e#YTVO<#D#?*T{>
zqp$pI=l9Scwtrn}UE7pFOYkj1H0v!u_S$%%INffnJaN^7*xE&~M7ZSKK8>E=#)2Xe
z^Vo|5vX)`|)2_2j=8d{pJFS#_Plw`MR3ppFw7}mETa-&NQ3#q8_7azjwMx#cgX3v)
zM`+-{^$TTu;J#S3_XJ<Xg1rL8z(JQoui2s>(RQ_MYBmt8#*f*#<NXen>oA`F6lCq1
zTH%E2%c!;m=r7?yy2yXCaLf+8zYF=;%^)EkiEqC&VzX>5E0~K+fy;!yQg3@vVo^9(
z;7mi^=o~yynpG-3cRp$B$<pUT8wph8DEigEB?0hPOa`v`d9V(OzA*_fs0M9@zZ|rM
zgnOuWTDDpqf;eB<I;t|AEdv+>;C*ZVS00wF3~!A4Xn<v~PjHUt(6P4M8qZflATyv`
zpHbT`NjQ(8T_bDh|1JT)cwS`RFCWJ#2wfrukp9YnGO6Vmrh1eI%&Rkk_(^P2$+aEk
zbe5N~Nc`17G)E=aDd7BYt(-T^YSt1o-&|ExJ~2g?#r<vdJb<9b*paaZMcOHlF_kv=
zxm9aTk4Agm?qYDLN0--k19YDOcfS$rb+nd`+P*L_cvmvwqH2&4QtDrPK!HM}tkDmk
zAa!1<pCtd6>L>X>1O`?0<vYKJ#pxWY#r<LT(8*DgcT$FHzm6I_q}bF^n7D?<{v7$N
zq;pH)a(qMdxE{#}3@?yPT`t?-tD`h6CXcjE`JzL@z+rJJ@Q5j!i!nod)2?Cba5qG7
ztc2wH$8Rzd2jbEbTG$+CUT&nL1gJqB_AiJlm{wgkb}u5ROr4L`qzSkHcp@<TN4~lD
zMamDz@Yl*Cf40zEM$Wbtp;Jk3V1YDse+(@SADLaDZI2fTDw)B{$b3N-7o`S8Obw>L
zTzw|x*|x&tAk!?-vrvM3{rfrM3Tf~+erA;r+9>(MqbLAU@)J{(rp88eK)~}BRl8KO
za9lZjv{!+|#Kx)f4&(1Qpoh9tj<9QoeUv!5Bn4sm+D6s}Qb#dtO4CS?@XWeu=4L5e
zoCNAu=!8$PeT&UGk)1IM3koL`=EHugT|@(DFB`*N4HCh&DGx93;U)u2E))?{0_ZC6
zUslokvI^@#Xfc5azyVLv*UDZ?@YkCr7H|C0p#EQEj?<XK6%GK+J2zHmijQS~m%Dsc
zKcvO=HGV-bjm!cKyxU!*<Zy3bD)%`-HW(0(i|R!fQy2Ky`$zE55H~g@Fd1iLRaquL
zrEo`DrdqMQnxjkZXBQ<JYwL<+>{EHo43EahDT(l}jJn$%b-at_E91)1fFd_{r6&+T
zD+2q(A5s)~pyouNtVRXev_RL5univQGJuQH7OG#!h8@I!{vF-%e_2Xj1c^!7>C|}4
zSARRX6W_6ap(U8v5c%sTbfTj5Ms=3~SVJVY43V&q-RWYmT4g0+ry`<t*)tnQl=O#1
z!XWg6!XLD<dQ$^af43&eJxpgJiMGZK+F`AfD&qJv^%s2Kad5Fn?T$25yVMY=cM)~J
zVF#*|ZeS-q_UeA~p-{(zL{}M|YT9JQeZ+ubv9MVwZ7!RiD-qc!UI;=0a1{;|fS3Ka
z_+QIOfu%^kpgG!<<w9t!je)kS_e)gp1iVB=LG!;0v_H84vQ>nV(Ia-nsyTiIrS2_=
z$Tq_6i1idLGif>BnvUL`4iUPXsJx}Z0}5gE1SXmbZ&T2zkzTXkQ)mL-YgWH07sU!a
zGPCdsU@x!9b!Lu&LW1<1a*qQFEJzCIAp64D^qN&OPb(Hzq>*XuBKL0LEw>i)(G17G
z6gG^dLzSH|Bo;06Gc}cf0d}?f>x&ZAt+7nK+^KLtx(*0NJ4D(`bRJ7SeczheRUnMB
z7MFFgT0zEO(liH~Kbo_ESg&e2wzeaHC%JP(!uSq&lK2eOn9zp%H)wb4Q6EU?D^Cz}
zpot^;0oMIsj3pfezaqC&ElD=c9w_o3s?Om@dwYFzgKH1}2Ozt}K1O+5c8-aK)apX@
zhnQ@-0n}f6)DtTgN8xXsOnG$ddo_aO0nz4}0kL*gaO4^v2qwXok>#+!{&4j*KCGC_
zCr)tB$6i;mi(MrOPHeq2E`ov@pP0;SX)4^(jV~6bc5fAvl|gO~0qyVk4eK&1k82)O
z3T%jL?l4eNUWZ^&f8Olz_&4^cH5_`FdMuZjE!7foY|(z?T;FeWDqbo<J2_d6;w<@i
zFuH+Etb%<`Nler6+KLz?1vd?VbYVlw0|3x+Bs9f4wG#oS$9mt2)r=(j3A<utJvX1h
z0Bz-yz4E!z?XQy9{}J%2p2edCpS)MCwcwM11CN<*ea^q)Ne|DlAFM1_qgnK^gp-3U
zE=QA24+x~XjikNjI}sc+8bOil=Wnh1B6+KAP(BvP6IYA^cq>ULk|m(|8%rAojXmnl
z5N%|hC9zYkF3q>_%fom<&ZH@SpU*i4?^Bwnj?;wa%YDSayGH9i4F%FU7Pt~1g5ot8
zKoLH5f9r>Nys@=ITyZ-CP9I1I&`d_%ob3!IDY5K(-af2u2*6U^uzE*?+LZgzg)^am
z@WPkA+8XA|VQ=oFa`;E~%wP3Gc;%9dF9}2cy(%qB+&iGeegRlCSonqA4b3~K_kMj`
zG0=if1eX5Oehu0v6!0otI|WtfGTmSi!<D)iGgv|108lBykETA%sz|zz7DT=8>@z$X
zt{LJf-QCW4f$3dqT!U&Vi&34WJu@HHfOQG9sOYMhHu&hQ_U!9&Krjg8HR{lGcJrF&
zQgxzj9*mRrA4n2KL_>h$`Rw^>On|@iE_`ck4IPDw3Km^_4j)0BhGFPS2LwJ;Ehc;x
z9Frg+pc5*>seHjumfNp`5o?%#MT&np6V3ph)j&ilN2?Aa%EcCW!(~c^VjYU|q20qE
z_5E;KtoH8~vy=PjukH8E*G>j4NuECKp8aDNC(U4m=#oW8r}2~1E2D)~47~5fjc31I
ztREFqChVP42O4eDl8SpjSQuVy%Zv_PXH2M_oq+bgpF9f(wpaR~X^%fFD$Skxevstr
z%%39(mCSlJ8p|6Z_{maL-ZKFU|1ft?Xj*(dmSmsad_pip5ji<$<KyuwN!H|MD1P!2
zexgvia!By_Sp;7WcT0qpD4n4W9I3GUQ4=BK*xx*fWaIOKl;QNpRn}iPv7a+x8W`}N
z_OkUOadx<yNmJ5x7?53FO%s|9tY6o8!8P@X1rx4?D7HnC@xiq=xrL0<ovr4a{@Trp
zNx&I%rVV*AQp_uw&8&>ZDdzXdJ)nn_ac3UwJHH|bc|*~}y|cL2`)^h7{(9>!?7Pa*
z<VuoHQNTdZvR!Yob(Ls+Et;rmitC?Mp#LIfUF^ty*{s5BIdRAMZ+GkT)OVtmfS}N|
z!l!2OJCED=SA<iWh2nB;c3*P3m{z?6Dawqjq13QHVR#RULlY%Q!MALiiwSI=gTq<(
zyoC=}nC*ha4czB#_rH$Q>>qsO6lHrB;%M0aoWq8*B+T}o4UT1KH9LNvqP+bL>f7x7
z>ZE?jD(HbPD3t}`lYF$_xB8wy&N`qqnD$iX0JgP#{sO&JyU2?u0mi(@uX_AVDqL$}
zvrA^aZPTFG^+e^zo#}dZSuoLB>Y;$bOS9g@$mTiID8xi%V{{mRzIe1eQ%8%Qnr63s
zALAZhe^fC$u<xxRGMU!4@-3~%jQdehB8Vm}!_ut2tn#bNqsN2e<oD9xw-7|`G>j?%
zNW)^7yxKZ3hz2dK-rgRU{Vd)`D=F!S$2(MiK>L!3TzAd^EPY%WUqxOvSJ6L1|KQT*
zu`V)UTG*Ln)?rs~a+E2kRei{XpOhGY`oUSY;4c;Hmff4Yhx#KVy@GOUFU#7i%kL)=
zGL6?^MY|6&S9}KgVcZqEWo=iBng)!)<m2@5CJ^28iqDUjuT5*|%B#E-i!XPoE>F^x
ztre1YKKL)tcKq#LYTLUpvVE59YI>Em?2z|!aqSiM9%Bs2Ba#x22>hDIf$Qpd*B=#%
zS8S7>!3Ss@rkDzcUu_OJ8hrRtCRa@A7tb~y8k60Z8>io8o@U+NT1?F3%s<~|CMA=E
zU}>g~e4N%@3qeKRG9T@WZVlEKHd9IsMVv0ob@6H`m9_UeV=L&`;6u_qmaqzFHtrNq
z&RhN`=v=z{gou`=*gA2~39($d`6~;XFD45jWnk?af>{4@JW9%z9GEHE$w9eJSE@Y+
zIpzp)JLeWO7P-Zc54pVOZ&h<Yi=8ja?}u-1mP-lU_QZ&+^qHJ3vkwm+E5jo2n`0YC
z<Bd9477M{AZ1c%^;%8&gfoY;M4-P@&&^R+TB;n1etMlc9UKaW3vgu)?DLkg;ee9zt
zmOj*VVLr1BmH!iD6r=eig>@Qo!+Y5cuklk5mwRTm`E2s_{ez?~JTJ{^<uZ**B$XhG
zN-UKaDkf>i%8G#3!|m(RU}FBkze$UWL_ao!V_I9PQKK2JH;Sq`+RMbF#`33G_4r-j
z2y_agD2gIepO#bWRW!6q(h*cV_fu7Lte9Ne9~0-dbNk#%c+aKBK0e$}D?K_Fs<OL9
zzX_I@{xH6rzu<OyIX3EklAykzubl0HN?)Qtvchilmb}$owu4#OU&xs0=g8oo3Mzk_
zX74@|k%C+9->q6H6IBBy(^c=`QCX_psR+0%&RoHx!=t$87@l7jka^Lf1TTuFr39`G
z@{v>lnZ~}I`w4=oekZ5a%Jh=ODJoh--zK-}O{EXQpJLf-uE(lC^fP-Frn@}6IovhZ
zT5fcPHb4wU9%nf~wr+4(I~TOq9K1_r->hYFlpN!-TP^f9yyxO`HAFD_ti2;+v(QA5
z&~NRf5%$Hu#x2-WVNkW$43#5FlB}Y#j~?W<QFPAn@JTa<l?=3*%3LKrZuf-Y6nGX^
zSf!z+ZuBpjOg7M%>C46b6mc|_*aICdVww2gIGQ08944Cy@m$Qo!G?TIHgw_%1BeKI
zq}Nn}N8=AQwQQG9q#iD(Nc|Hz`d>=4?ZHQL4b~S?vi@|*A-u{;#7r>iYML|!wzzi}
z(*2i#uNdh)Z$49YAQD^qqNFS9F1Np2Y{>8?zQgom2_9It^YmjK6YG8s`6k(ZuF&Cm
zhr7sYY-w<DI=v{n`^{Fa)BmH*QlYDf7~#?%V=rC|uh}0ppG4_wuzteO8B)UmhK#EL
zD<|L`VrQpVqR`LKeIYCxLXemA+X@*ZCCqOk6%Ih?tI9Ka%dH>Mq0q+5dYtf$1nD~L
zmRa6e;`4BH;LX)N$1|JcW;cJBCz#B3b%lNak@yMT433Tt_}O@%D#TJJ@G6`%olh{H
z6&@%?-2x7Y9!Lr6n5e3P(G*5-ksCYHPU&A^3h$|<73Di1nwR2h7mDmMMa2zpSttCF
z-?<=GS8N8E$H_SaM63gr5{Ww;{tVdb0rL2iM-7PdGyGjKU32NmQm`EMoe0K10J~U&
zGPgn?k7W=StX&%q5#(QRxLs~lK7!NlAHof&fbmpoE_ABro&z1Pzn8whPJa&N8;Guo
zZ_m80mTJi_sQwf?8P7Uw4)+FcJs`5r&xLRt1u}*?;qIwe%!M?vnIeLYw+^JUJ*S7C
zb-sB<db_xLB56HeVCHX5=xyM-?}|*$%nq=9Xwxh$iyp~8!hx;`O{_)P^L0yYZ&Gv(
zJ)XLwS9Pqr5s52MYP{&OsbGOsA<x6)0{gNb9;cc=o)yMMwIv<)76Px2);&D*UeA)#
zO$Tz^!mx~cCC4)J$w+3--8-*I+;|lk%CG*gb&hpq!RaZ%1-XB@?QYMc2>+uz=O9Xl
zZ`JY*g(wK-wJG{0a@5RvkPgjHB%EOsh$v~N)q7YpT;Quki#(EhfDHW<Rp;^{(+%@G
z+&D~wsO_n%EuMo!du2n5z2<_=t^miDtK1((rq20$S%-%oR#`+G-Vw3xoc4(()|}oQ
zh$)s+yRFFp5e2wwmk0)3G@ex;-`lQ32QZmY_Pc15_x^N1XqG>+J3wuAS#9SrRwys>
z4k3GKk%y{{fWyO0Qu37ZQ*3;GQmW{&uFEDTDpq3NnIWUq(HN4BF6=<?aE;XVD_Q|C
zo0BLVm{J=ZZz2#_7cjBeD#(`;O>Qmdx*4Q{b=X3W7m5MB)v-l1#oSd@=A0R;LmdRt
zy@l;AUU6WbXLpdXoM%6-xWAl7v$>^nP*T12+vU<i<)T{!pR7{E@!(fS6N<Emz?KkQ
z)|kOIZ$T0c;13Z3r^5);B7SHbIDVFfIO)nH3w$`rQFw>QBBnU<ekjFIQyyalLfy_9
z;mCZOzqwg2nbxm-7xhE_k;JO%WX%zx^y!p-{ee6uOUcauJ1J{PR}KYpnw0eP_Z2Pk
zi0*%1KadF@j;5h;czF6<TfiAXU7YAl{^t)MZg?5d3HWj_;mO&|;N-KlUu^0BV#_E~
zz1^Czu{z#36viT?rlIW;d#h$~X9epJRx(uwqyD=6*!1EszFB%}W!DS*Xi`D{`17q|
z0sZNCZzjqfRJYcV@vJQd+ra?KmTurND(?y=`$-}+Q0C!i1%~bfEm1~KNMitw4>xR_
z0)qz)E?)$wc@6S(uGjyi6(Up7Az3|@6}o+527O$n-wgO6uI#kFosaMq5+-E~7Qo#+
z4vnbEOIZEQsh`%TlI7B<Y;X#;%|PRVxbS)xV$v(kGmW~JDb8e{YhfIYHwARoO32<G
zqSZ*2qnoSL{=Q@$5Vtn@9Rj$}03K1zuAWn!P>cYoob-i4F^dsC2~KRsgRa45yTOxC
zG7MfQGO&%}bXvZl0#3GDOmYnTPAN6*%Pf7On~EalMAHl^$o}=V+>QJ^!zzaIWF)nl
z0g-X7-A(NNlu*}|HbnBx09+Tu&~@nepX>I#2fp&xju-S|PosT50YrNeK9AhMWM_K%
z<iIx;xJ{boSc-Sv3%_*p1gTjQ0UwbXf=lu9fm)Hmlf`v6NC&O7FJTY`;^^I-$_`tD
z12_wJOmGoff6Up<-@^fHWjapC>v<W*Dnd9hN=J3MyRo1KPecS)nXqGU==f^?w(mvy
z5Byw=Ar97oAhDQv4%k2(AUAcA;ui7)hkBF=(_tWaq;zZP(HR;7&Vl}i6hm$6CI?oH
zkQfJUsJ4*bvE*mtJvdw+#zQ3g10_Ffbs)@=EF~<Mb7U;>yd1`g)&UiJ*00<TfouH{
s7VN{eT1Tzh@-T-y9Y+nf|C;I<{#APd<kY4%0tWcVNGOU|f(--y2Vqtm(EtDd

literal 55501
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

diff --git a/examples/mnist/example1/main.py b/examples/mnist/example1/main.py
index 734b6030..86b518f0 100644
--- a/examples/mnist/example1/main.py
+++ b/examples/mnist/example1/main.py
@@ -1,14 +1,59 @@
 import argparse
-from pathlib import Path
-
 import numpy as np
-from model import fcnet_2layer_dual_port
+from pathlib import Path
 
 import paibox as pb
 
 
+class fcnet_2layer_dual_port(pb.Network):
+    def __init__(self, weight1, Vthr1, weight2, Vthr2):
+        super().__init__()
+
+        pe = pb.simulator.PoissonEncoder()
+        self.i1 = pb.InputProj(input=pe, shape_out=(392,))
+        self.i2 = pb.InputProj(input=pe, shape_out=(392,))
+        self.n1 = pb.IF(128, threshold=Vthr1, reset_v=0)
+        self.s1 = pb.FullConn(
+            self.i1,
+            self.n1,
+            weights=weight1[:392],
+            conn_type=pb.SynConnType.All2All,
+        )
+        self.s2 = pb.FullConn(
+            self.i2,
+            self.n1,
+            weights=weight1[392:],
+            conn_type=pb.SynConnType.All2All,
+        )
+
+        # tick_wait_start = 2 for second layer
+        self.n2 = pb.IF(
+            5, threshold=Vthr2, reset_v=0, tick_wait_start=2, name="batch_dual_port_o1"
+        )
+        self.n3 = pb.IF(
+            5, threshold=Vthr2, reset_v=0, tick_wait_start=2, name="batch_dual_port_o2"
+        )
+        self.s3 = pb.FullConn(
+            self.n1,
+            self.n2,
+            weights=weight2[:, :5],
+            conn_type=pb.SynConnType.All2All,
+        )
+        self.s4 = pb.FullConn(
+            self.n1,
+            self.n3,
+            weights=weight2[:, 5:],
+            conn_type=pb.SynConnType.All2All,
+        )
+
+        self.probe1 = pb.Probe(target=self.n2, attr="spike")
+        self.probe2 = pb.Probe(target=self.n3, attr="spike")
+
+
+param_dict = {}
+
+
 def getNetParam():
-    param_dict = {}
     timestep = 4
     layer_num = 2
     delay = layer_num - 1
@@ -27,8 +72,6 @@ def getNetParam():
     param_dict["w2"] = w2
     param_dict["vthr2"] = vthr2
 
-    return param_dict
-
 
 if __name__ == "__main__":
     parser = argparse.ArgumentParser()
@@ -37,7 +80,7 @@ def getNetParam():
     )
     args = parser.parse_args()
 
-    param_dict = getNetParam()
+    getNetParam()
     pb_net = fcnet_2layer_dual_port(
         param_dict["w1"],
         param_dict["vthr1"],
@@ -46,7 +89,7 @@ def getNetParam():
     )
 
     # Network simulation
-    raw_data = np.load("./data/mnist_input_data7.npy")
+    raw_data = np.load(Path(__file__).parent.parent / "data" / "mnist_input_data7.npy")
     input_data = raw_data.flatten()
 
     # Visualize
@@ -79,6 +122,10 @@ def getNetParam():
     graph_info = mapper.compile(
         weight_bit_optimization=True, grouping_optim_target="both"
     )
+
+    # #N of cores required
+    print("Core required:", graph_info["n_core_required"])
+
     mapper.export(
         write_to_file=True,
         fp=out_dir / "debug",
diff --git a/examples/mnist/example1/model.py b/examples/mnist/example1/model.py
deleted file mode 100644
index ab711ddb..00000000
--- a/examples/mnist/example1/model.py
+++ /dev/null
@@ -1,46 +0,0 @@
-import paibox as pb
-
-
-class fcnet_2layer_dual_port(pb.Network):
-    def __init__(self, weight1, Vthr1, weight2, Vthr2):
-        super().__init__()
-
-        pe = pb.simulator.PoissonEncoder()
-        self.i1 = pb.InputProj(input=pe, shape_out=(392,))
-        self.i2 = pb.InputProj(input=pe, shape_out=(392,))
-        self.n1 = pb.neuron.IF(128, threshold=Vthr1, reset_v=0)
-        self.s1 = pb.synapses.NoDecay(
-            self.i1,
-            self.n1,
-            weights=weight1[:392],
-            conn_type=pb.SynConnType.All2All,
-        )
-        self.s2 = pb.synapses.NoDecay(
-            self.i2,
-            self.n1,
-            weights=weight1[392:],
-            conn_type=pb.SynConnType.All2All,
-        )
-
-        # tick_wait_start = 2 for second layer
-        self.n2 = pb.neuron.IF(
-            5, threshold=Vthr2, reset_v=0, tick_wait_start=2, name="batch_dual_port_o1"
-        )
-        self.n3 = pb.neuron.IF(
-            5, threshold=Vthr2, reset_v=0, tick_wait_start=2, name="batch_dual_port_o2"
-        )
-        self.s3 = pb.synapses.NoDecay(
-            self.n1,
-            self.n2,
-            weights=weight2[:, :5],
-            conn_type=pb.SynConnType.All2All,
-        )
-        self.s4 = pb.synapses.NoDecay(
-            self.n1,
-            self.n3,
-            weights=weight2[:, 5:],
-            conn_type=pb.SynConnType.All2All,
-        )
-
-        self.probe1 = pb.simulator.Probe(target=self.n2, attr="spike")
-        self.probe2 = pb.simulator.Probe(target=self.n3, attr="spike")

From e7bc7b1b13397ea255e6720d4edf053dd8fa7c97 Mon Sep 17 00:00:00 2001
From: KafCoppelia <k740677208@gmail.com>
Date: Fri, 15 Mar 2024 16:32:12 +0800
Subject: [PATCH 22/68] =?UTF-8?q?=F0=9F=99=88=20updated=20.gitignore?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

---
 .gitignore             | 1 +
 docs/images/.gitignore | 1 -
 2 files changed, 1 insertion(+), 1 deletion(-)
 delete mode 100644 docs/images/.gitignore

diff --git a/.gitignore b/.gitignore
index e29fd08f..6ebc37e6 100644
--- a/.gitignore
+++ b/.gitignore
@@ -154,3 +154,4 @@ cython_debug/
 
 .vscode
 debug
+*.drawio
\ No newline at end of file
diff --git a/docs/images/.gitignore b/docs/images/.gitignore
deleted file mode 100644
index 8e062ad3..00000000
--- a/docs/images/.gitignore
+++ /dev/null
@@ -1 +0,0 @@
-*.drawio

From bf38fe946be2d530075411e10c8af08f7a045b72 Mon Sep 17 00:00:00 2001
From: KafCoppelia <k740677208@gmail.com>
Date: Fri, 15 Mar 2024 16:40:29 +0800
Subject: [PATCH 23/68] =?UTF-8?q?=F0=9F=93=9D=20updated=20TODO=20list?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

---
 TODO.md | 31 +++++++++++++++++++------------
 1 file changed, 19 insertions(+), 12 deletions(-)

diff --git a/TODO.md b/TODO.md
index ce7e69a6..a212b9b6 100644
--- a/TODO.md
+++ b/TODO.md
@@ -1,18 +1,25 @@
 ## TODO
 
-- [x] 帧导出与优化
-- [x] 神经元目的地突触寻找对齐地址算法（待验证）
+- [X] 帧导出与优化
+- [X] 神经元目的地突触寻找对齐地址算法（待验证）
   - 聚焦 `aligned_coords` 前后所涉及的寻找神经元的目的地突触地址算法
-- [x] 多精度权重支持（待验证）
+- [X] 多精度权重支持（待验证）
   - 聚集 `CorePlcement` 内 `_fold_raw_weights` 前后所涉及的权重拆分算法，需要经过充分验证
-- [x] 运行时交换文件格式约定与导出
-- [x] `tick_wait_start` 与 `tick_wait_end` 前/后端支持
-- [x] 网络节点间自定义延迟( `tick_relative` )前后端支持
-- [x] 神经元密集分配策略（待验证）
-- [ ] 半折叠卷积算子前后端支持
+- [X] 运行时交换文件格式约定与导出
+- [X] `tick_wait_start` 与 `tick_wait_end` 前/后端支持
+- [X] 网络节点间自定义延迟( `tick_relative` )前后端支持
+- [X] 神经元密集分配策略（待验证）
 
+- 功能模块支持
+
+  - [X] 全展开2D卷积算子
+  - [ ] 半折叠2D卷积算子
+  - [ ] 残差结构
+  - [ ] 逻辑算子：与、或、非
+  - [ ] 二维矩阵转置
 - 多层次结构网络组件的发现、数据流验证与后端解析
-  - [x] 对有层次结构（子网络例化复用等情形）的网络模型，实现在所有层次上网络组件的发现、数据流与后端解析实现
+
+  - [X] 对有层次结构（子网络例化复用等情形）的网络模型，实现在所有层次上网络组件的发现、数据流与后端解析实现
   - [ ] 局部连接包装成单个算子，实现在所有层次上网络组件的发现、数据流与后端解析实现。考虑用户调用接口
 - 带有约束的路由坐标分配
 
@@ -23,9 +30,9 @@
 
 - 神经元分配策略（资源优先、延迟/吞吐率优先、资源+延时/吞吐率兼顾）的后端支持
 
-  - [x] 资源优先：直接对该节点所有神经元进行密集分配，使用最少的物理核资源
-  - [x] 延时/吞吐率优先（负载均衡）：由于节点的计算时间取决于该节点神经元全部计算完成的耗时，因此该节点神经元被分配至多个物理核上时，采取负载均衡策略，可提高节点吞吐率，优化计算延时
-  - [x] 资源+延时/吞吐率兼顾：在资源优先的基础上，可**叠加使用密集分配策略**，对未分配满的物理核尝试分配同一节点的其他神经元段。相较于单纯使用资源优先策略，使用更少的物理核
+  - [X] 资源优先：直接对该节点所有神经元进行密集分配，使用最少的物理核资源
+  - [X] 延时/吞吐率优先（负载均衡）：由于节点的计算时间取决于该节点神经元全部计算完成的耗时，因此该节点神经元被分配至多个物理核上时，采取负载均衡策略，可提高节点吞吐率，优化计算延时
+  - [X] 资源+延时/吞吐率兼顾：在资源优先的基础上，可**叠加使用密集分配策略**，对未分配满的物理核尝试分配同一节点的其他神经元段。相较于单纯使用资源优先策略，使用更少的物理核
   - [ ] 自适应策略：根据网络结构，对各层 `unrolling factor` 做全局最优化设置，且预留接口以手动约束某些节点
 
 - [ ] 混合精度权重支持（已添加权重精度优化的**编译选项**）

From 8cb0305bc7861733b35a23eb5316ed535a06b5c9 Mon Sep 17 00:00:00 2001
From: KafCoppelia <k740677208@gmail.com>
Date: Fri, 15 Mar 2024 17:15:31 +0800
Subject: [PATCH 24/68] =?UTF-8?q?=F0=9F=97=91=EF=B8=8F=20removed=20useless?=
 =?UTF-8?q?=20code?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

---
 paibox/backend/experimental/coreblock.py |  96 -----
 paibox/backend/experimental/routing.py   | 469 -----------------------
 2 files changed, 565 deletions(-)
 delete mode 100644 paibox/backend/experimental/coreblock.py
 delete mode 100644 paibox/backend/experimental/routing.py

diff --git a/paibox/backend/experimental/coreblock.py b/paibox/backend/experimental/coreblock.py
deleted file mode 100644
index 1687880c..00000000
--- a/paibox/backend/experimental/coreblock.py
+++ /dev/null
@@ -1,96 +0,0 @@
-from typing import List, NamedTuple, NewType, Sequence
-
-from paibox.base import NeuDyn
-
-
-class NeuronSegment(NamedTuple):
-    parent: NeuDyn
-    """指示这个对象是描述的哪个神经元组"""
-    index: slice
-    """指示这段神经元对应的下标范围（一定连续分配）"""
-    addr_ram: slice
-    """分配到在物理核内的RAM坐标范围（一定连续分配）"""
-
-
-NeuronSegments = NewType("NeuronSegments", List[NeuronSegment])  # one_core
-
-
-def get_neuron_segments_1(
-    neurons: Sequence[NeuDyn], capacity: int
-) -> List[NeuronSegments]:
-    result = []
-
-    for n in neurons:
-        num = n.num_out
-        i = 0
-
-        while i < (num - 1) // capacity:
-            segment = NeuronSegment(
-                n, slice(i * capacity, capacity * (i + 1), 1), slice(0, capacity, 1)
-            )
-
-            result.append([segment])
-            i += 1
-
-        segment = NeuronSegment(
-            n, slice(i * capacity, num, 1), slice(0, num - (i * capacity), 1)
-        )
-        result.append([segment])
-
-    return result
-
-
-def get_neuron_segments_2(
-    neurons: Sequence[NeuDyn], capacity: int
-) -> List[NeuronSegments]:
-    result = []
-    segments_of_neurons = get_neuron_segments_1(neurons, capacity)
-    temp = []
-
-    sum = 0
-    for segs in segments_of_neurons:
-        if segs[0].addr_ram.stop < capacity:
-            temp.append(segs[0])
-            sum += segs[0].addr_ram.stop
-        else:
-            result.append(segs)
-
-    temp.sort(key=lambda seg: seg.addr_ram.stop)
-
-    i = 0  # 剩余部分可组成的物理核个数
-    j = 0  # 有剩余的的物理核
-    while i < (sum - 1) // capacity + 1:
-        segments = NeuronSegments([])
-        full = 0
-        empty = capacity - full
-
-        while empty > 0 and j < len(temp):
-            if empty >= temp[j].addr_ram.stop:
-                segment = NeuronSegment(
-                    temp[j].parent,
-                    temp[j].index,
-                    slice(full, full + temp[j].addr_ram.stop, 1),
-                )
-                segments.append(segment)
-                full += temp[j].addr_ram.stop
-                empty = capacity - full
-                j += 1
-            else:
-                segment = NeuronSegment(
-                    temp[j].parent,
-                    slice(temp[j].index.start, temp[j].index.start + empty, 1),
-                    slice(full, capacity, 1),
-                )
-                segments.append(segment)
-                temp[j] = NeuronSegment(
-                    temp[j].parent,
-                    slice(temp[j].index.start + empty, temp[j].index.stop, 1),
-                    slice(0, temp[j].addr_ram.stop - empty, 1),
-                )
-                full += capacity
-                empty = 0
-
-        i += 1
-        result.append(segments)
-
-    return result
diff --git a/paibox/backend/experimental/routing.py b/paibox/backend/experimental/routing.py
deleted file mode 100644
index 8d40e70c..00000000
--- a/paibox/backend/experimental/routing.py
+++ /dev/null
@@ -1,469 +0,0 @@
-from typing import Any, List, Optional, Sequence, final
-
-from paicorelib.v2.routing_defs import RoutingDirection as Direction
-from paicorelib.v2.routing_defs import RoutingDirectionIdx as DirectionIdx
-from paicorelib.v2.routing_defs import RoutingNodeLevel as Level
-from paicorelib.v2.routing_defs import RoutingNodeStatus as NodeStatus
-from paicorelib.v2.routing_defs import get_node_consumption
-
-from ...exceptions import NotSupportedError
-from ..placement import CorePlacement
-
-"""
-    This is an alternative to the routing tree that \
-    does the same thing as the development version \
-    but is more complex.
-
-    Some functions are still not implemented and \
-    will not be developed until the solution is \
-    reconsidered later.
-"""
-
-
-class RoutingNode:
-    def __init__(
-        self,
-        level: Level,
-        data: Optional[Any] = None,
-        *,
-        tag: Optional[str] = None,
-    ) -> None:
-        """Instance a tree node with `level`. \
-            For a node with level Lx > 0, after created, \
-                the length of children is `node_capacity`.
-
-            For a node with level L0, it is a leaf node.
-
-        Args:
-            - level: the node level.
-            - data: the data hanging on the node. Optional.
-            - tag: a tag for user to identify. Optional.
-        """
-        self._level = level
-        self._children: List["RoutingNode"] = []
-        self.item = data
-        self.tag = tag
-
-        self._status = NodeStatus.ALL_EMPTY
-
-    def add_item(self, data: Any) -> None:
-        """Add data to its item. Only used for L0-level node."""
-        self.item = data
-        self._status = NodeStatus.OCCUPIED
-
-    def add_child(self, child: "RoutingNode") -> bool:
-        if self.level == Level.L0:
-            # L0-level node cannot add child.
-            raise AttributeError(f"L0-level node cannot add child")
-
-        if self.level - child.level != 1:
-            raise AttributeError(
-                f"The node with level {child.level} can not be a child"
-            )
-
-        if self.is_full():
-            return False
-
-        self._children.append(child)
-
-        return True
-
-    def get_avail_child(self, method: str = "nearest") -> Optional["RoutingNode"]:
-        if self.is_children_all_status(NodeStatus.OCCUPIED):
-            return None
-
-        for child in self.children:
-            if child.status != NodeStatus.OCCUPIED:
-                return child
-
-    def find_node_by_path(self, path: Sequence[Direction]) -> "RoutingNode":
-        """Find node by the path of `Direction`.
-
-        Description:
-            Find by starting at this level based on the path provided. \
-            Take `path[0]` each time and then do a recursive search.
-
-        NOTE: The length of path <= the level of this node.
-        """
-        if len(path) == 0:
-            return self
-
-        if len(path) > self.level:
-            raise ValueError(
-                f"The length of path {len(path)} > level of node {self.level}"
-            )
-
-        idx = path[0].to_index()
-        if idx > len(self.children) - 1:
-            raise IndexError(f"Index out of range: {idx} > {len(self.children) - 1}")
-
-        sub_node = self.children[idx]
-
-        if len(path) > 1:
-            return sub_node.find_node_by_path(path[1:])
-        else:
-            return sub_node
-
-    def find_node_by_tag(self, tag: str) -> Optional["RoutingNode"]:
-        """Searches for nodes by tag using DFS.
-
-        Args:
-            - tag: the tag string.
-
-        Returns:
-            - the node if found. Otherwise return `None`.
-        """
-
-        def dfs_preorder(root: RoutingNode, tag: str) -> Optional[RoutingNode]:
-            if root.tag == tag:
-                return root
-            elif root.level == Level.L0:
-                return None
-            else:
-                for child in root.children:
-                    node = dfs_preorder(child, tag)
-                    if node:
-                        return node
-
-        return dfs_preorder(self, tag)
-
-    def get_node_path(self, node: "RoutingNode") -> List[Direction]:
-        """Return a direction path from L4 to the level of `node`.
-
-        Args:
-            - node: the node with level <= `self.level`.
-
-        Return:
-            - A list of `Direction` from L4 to L0.
-        """
-        if node.level > self.level:
-            raise ValueError(f"The node with level {node.level} is not in self")
-
-        if node.level == self.level:
-            if node != self:
-                raise ValueError(f"The node with level {node.level} is not in self")
-
-            return []
-
-        path = []
-
-        def dfs_preorder(root: RoutingNode) -> bool:
-            i = 0
-            for child in root.children:
-                path.append(DirectionIdx[i])
-                if child is node:
-                    return True
-                else:
-                    if dfs_preorder(child):
-                        return True
-                    else:
-                        path.pop(-1)
-
-                i += 1
-
-            return False
-
-        if dfs_preorder(self):
-            return path
-        else:
-            raise ValueError(f"The node with level {node.level} is not in self")
-
-    def get_lx_nodes(self, lx: Level, method: str = "nearest") -> List["RoutingNode"]:
-        if lx > self.level:
-            raise ValueError(f"The node with level {lx} is not in self")
-
-        if lx == self.level:
-            return [self]
-
-        nodes = []
-
-        def dfs_preorder(root: RoutingNode, lx: Level, method: str = "nearest") -> None:
-            if root.level == lx + 1:
-                nodes.extend(root.children)
-                return
-
-            for child in root.children:
-                dfs_preorder(child, lx, method)
-
-        dfs_preorder(self, lx, method)
-
-        return nodes
-
-    def _find_lx_node_with_n_child_avail(
-        self, lx: Level, n_child_avail: int, method: str = "nearest"
-    ) -> Optional["RoutingNode"]:
-        """Find the child of level `lx` with at least \
-            `n_child_avail` children available.
-        """
-        if lx > self.level:
-            raise ValueError(f"The node with level {lx} is not in self")
-
-        if lx == self.level:
-            if self.n_child_not_occpuied() >= n_child_avail:
-                return self
-            else:
-                return None
-
-        if lx < self.level:
-            for child in self.children:
-                node = child._find_lx_node_with_n_child_avail(lx, n_child_avail, method)
-                if node is not None:
-                    return node
-
-            return None
-
-    def _find_lx_node_all_empty(
-        self, lx: Level, method: str = "nearest"
-    ) -> Optional["RoutingNode"]:
-        if lx > self.level:
-            raise ValueError(f"The node with level {lx} is not in self")
-
-        if lx == self.level:
-            if self.status == NodeStatus.ALL_EMPTY:
-                return self
-            else:
-                return None
-
-        if lx < self.level:
-            for child in self.children:
-                node = child._find_lx_node_all_empty(lx, method)
-                if node is not None:
-                    return node
-
-            return None
-
-    def find_lx_node_for_routing(
-        self,
-        lx: Level,
-        n_child_avail: int = 1,
-        method: str = "nearest",
-    ) -> List["RoutingNode"]:
-        """Find lx-level node for placing.
-
-        Args:
-            - lx: the level of node to be found(lx > L0).
-            - n_child_avail: find the node with at least `N` free child left.
-            - method: nearest or by the path. The paremeter is reserved.
-        """
-
-        def _get_child_nodes(
-            routing_node: RoutingNode,
-        ) -> List["RoutingNode"]:
-            if n_child_avail == 4:
-                return routing_node.children
-            elif n_child_avail == 2:
-                not_empty = routing_node.n_child_not_empty()
-                if not_empty > 0:
-                    return routing_node.children[2:]
-                else:
-                    return routing_node.children[:2]
-            elif n_child_avail == 1:
-                avail_child = routing_node.get_avail_child(method)
-                if avail_child:
-                    return [avail_child]
-            else:
-                # TODO Hard to describe
-                raise NotSupportedError
-
-            return []
-
-        if lx > self.level:
-            raise ValueError(f"The node with level {lx} is not in self")
-
-        if lx == self.level:
-            node = self._find_lx_node_with_n_child_avail(lx, n_child_avail, method)
-            if node is not None:
-                return _get_child_nodes(node)
-        else:
-            for child in self.children:
-                # Find the Lx-level node with `n_child_avail` Lx-1-level children.
-                lx_node = child._find_lx_node_with_n_child_avail(
-                    lx, n_child_avail, method
-                )
-                if lx_node is not None:
-                    return _get_child_nodes(lx_node)
-
-        return []
-
-    def add_item_to_L0_node(self, data: Any, method: str = "nearest") -> bool:
-        """Add item to the nearest available L0-level node."""
-        if self.level == Level.L0:
-            self.add_item(data)
-            return True
-
-        # Find the nearest available L1-level node.
-        L1_node = self._find_lx_node_with_n_child_avail(Level.L1, 1)
-
-        if L1_node is None:
-            # No available L1-level node found.
-            return False
-
-        # Find the nearest available L0-level node.
-        L0_node = L1_node.get_avail_child(method)
-        if L0_node is None:
-            return False
-
-        L0_node.add_item(data)
-        return True
-
-    def n_child_occupied(self) -> int:
-        """Get #N of occpuied children."""
-        return sum(child.status == NodeStatus.OCCUPIED for child in self.children)
-
-    def n_child_not_occpuied(self) -> int:
-        return self.node_capacity - self.n_child_occupied()
-
-    def n_child_empty(self) -> int:
-        """Get #N of empty children."""
-        return sum(child.status == NodeStatus.ALL_EMPTY for child in self.children)
-
-    def n_child_not_empty(self) -> int:
-        return self.node_capacity - self.n_child_empty()
-
-    def is_full(self) -> bool:
-        return len(self.children) == self.node_capacity
-
-    def is_empty(self) -> bool:
-        return len(self.children) == 0
-
-    def is_children_all_status(self, status: NodeStatus) -> bool:
-        return all(child.status == status for child in self.children)
-
-    def is_sub_node_all_status(self, status: NodeStatus) -> bool:
-        if self.level == Level.L1:
-            return self.is_children_all_status(status)
-
-        for child in self.children:
-            if not child.is_sub_node_all_status(status):
-                return False
-
-        return True
-
-    def __getitem__(self, index: int) -> "RoutingNode":
-        return self.children[index]
-
-    def __contains__(self, item: "RoutingNode") -> bool:
-        return item in self.children
-
-    @property
-    def level(self) -> Level:
-        return self._level
-
-    @property
-    def node_capacity(self) -> int:
-        return 4 if self.level > Level.L0 else 0
-
-    @property
-    def children(self) -> List["RoutingNode"]:
-        return self._children
-
-    @property
-    def status(self) -> NodeStatus:
-        return self._status
-
-    @status.setter
-    def status(self, new_status: NodeStatus) -> None:
-        self._status = new_status
-
-    def node_status_update(self, method: str = "nearest") -> None:
-        """Update the status of the node and its children \
-            of all levels(from `self.level` to L1).
-        """
-
-        def dfs_preorder(root: RoutingNode, method: str) -> None:
-            if root.level > Level.L1:
-                for child in root.children:
-                    dfs_preorder(child, method)
-
-            root._status_update()
-
-        if self.level > Level.L0:
-            dfs_preorder(self, method)
-
-    def _status_update(self) -> None:
-        """Update the status of the node."""
-        if self.is_sub_node_all_status(NodeStatus.OCCUPIED):
-            self._status = NodeStatus.OCCUPIED
-        elif self.is_sub_node_all_status(NodeStatus.ALL_EMPTY):
-            self._status = NodeStatus.ALL_EMPTY
-        else:
-            self._status = NodeStatus.AVAILABLE
-
-
-@final
-class RoutingRoot(RoutingNode):
-    def __init__(self, empty_root: bool = False, **kwargs) -> None:
-        """Initialize a routing quadtree root. \
-            The level of the root is L5.
-
-        Args:
-            empty_root: whether to create a empty root. Default is false.
-        """
-        super().__init__(Level.L5, **kwargs)
-
-        if not empty_root:
-            for i in range(self.node_capacity):
-                L4_child = create_lx_full_tree(Level.L4, f"L4_{i}")
-                self.add_child(L4_child)
-
-    def insert_gsyn_on_core(self, *cb_on_core: CorePlacement) -> None:
-        """Insert the grouped synapse on core into the tree.
-
-        Steps:
-            - 1. Get the routing node consumption.
-            - 2. Based on the routing level, find the available node of the routing level.
-        """
-        n_core_total = len(cb_on_core)
-
-        cost = get_node_consumption(n_core_total)
-        level, next_n = cost.get_routing_level()
-
-        # Find L2-level node with at least 2 L1 children available.
-        routing_node = self.find_lx_node_for_routing(level, next_n)
-        if routing_node is None:
-            raise ValueError
-
-        for gsyn_on_core in cb_on_core:
-            leaf = RoutingNode(
-                Level.L0, gsyn_on_core, tag=f"leaf of {gsyn_on_core.name}"
-            )
-
-
-def create_lx_full_tree(lx: Level, root_tag: Optional[str] = None) -> RoutingNode:
-    """Create a full Lx-level routing tree.
-
-    If creating a L4 routing tree, it will return:
-    L4 with #N children
-        -> L3 with #N children
-            -> L2 with #N children
-                -> L1 with #N children
-                    -> L0 with no child
-
-    where #N is `node_capacity`.
-    """
-    root = RoutingNode(lx, tag=root_tag)
-
-    if lx > Level.L0:
-        for i in range(root.node_capacity):
-            child = create_lx_full_tree(Level(lx - 1), f"L{lx-1}_{i}")
-            root.add_child(child)
-
-    return root
-
-
-def get_parent(tree: RoutingNode, node: RoutingNode) -> Optional[RoutingNode]:
-    """Get the parent node of the given node. \
-        If not found, return None.
-    """
-
-    def dfs_preorder(tree, node) -> Optional[RoutingNode]:
-        if tree is node:
-            return None
-
-        for child in tree.children:
-            if child is node:
-                return tree
-            else:
-                return dfs_preorder(child, node)
-
-    return dfs_preorder(tree, node)

From b5cef776941a280365259f8be5926a72e7038f77 Mon Sep 17 00:00:00 2001
From: KafCoppelia <k740677208@gmail.com>
Date: Fri, 15 Mar 2024 17:39:09 +0800
Subject: [PATCH 25/68] =?UTF-8?q?=F0=9F=93=9D=20updated=20the=20guide?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

---
 docs/Guide-of-PAIBox.md | 109 +++++++++++++++++++++++++---------------
 1 file changed, 69 insertions(+), 40 deletions(-)

diff --git a/docs/Guide-of-PAIBox.md b/docs/Guide-of-PAIBox.md
index 7bbc06be..54fe0850 100644
--- a/docs/Guide-of-PAIBox.md
+++ b/docs/Guide-of-PAIBox.md
@@ -53,7 +53,7 @@ PAIBox提供**神经元**与**突触**作为基本组件，用于搭建神经网
 
 PAIBox提供了多种类型的神经元模型，能够实现各种特殊的功能。
 
-⚠️ 请注意，神经元初始膜电位为0。
+⚠️ 神经元初始膜电位为0。
 
 #### IF神经元
 
@@ -62,7 +62,7 @@ IF神经元实现了经典的“积分发射”模型，其调用方式及参数
 ```python
 import paibox as pb
 
-n1 = pb.neuron.IF(shape=10, threshold=127, reset_v=0, keep_shape=False, delay=1, tick_wait_start=1, tick_wait_end=0, name='n1')
+n1 = pb.IF(shape=10, threshold=127, reset_v=0, keep_shape=False, delay=1, tick_wait_start=1, tick_wait_end=0, name='n1')
 ```
 
 其中：
@@ -74,7 +74,7 @@ n1 = pb.neuron.IF(shape=10, threshold=127, reset_v=0, keep_shape=False, delay=1,
 - `delay`：设定该神经元组输出的延迟。默认为1，即本时间步的计算结果，**下一时间步**传递至后继神经元。
 - `tick_wait_start`：设定该神经元组在第 `N` 个时间步时启动，0表示不启动。默认为1。
 - `tick_wait_end`：设定该神经元组持续工作 `M` 个时间步，0表示**永远持续工作**。默认为0。
-- `unrolling_factor`：该参数与后端相关。展开因子表示神经元将被展开，部署至更多的物理核上，以降低延迟，并提高吞吐率。
+- `unrolling_factor`：该参数与后端流程相关。展开因子表示神经元将被展开，部署至更多的物理核上，以降低延迟，并提高吞吐率。
 - `name`：可选，为该对象命名。
 
 #### LIF神经元
@@ -82,7 +82,7 @@ n1 = pb.neuron.IF(shape=10, threshold=127, reset_v=0, keep_shape=False, delay=1,
 LIF神经元实现了“泄露-积分-发射”神经元模型，其调用方式及参数如下：
 
 ```python
-n1 = pb.neuron.LIF(shape=128, threshold=127, reset_v=0, leak_v=-1, keep_shape=False, name='n1')
+n1 = pb.LIF(shape=128, threshold=127, reset_v=0, leak_v=-1, keep_shape=False, name='n1')
 ```
 
 - `leak_v`：LIF神经元的泄露值（有符号）。其他参数含义与IF神经元相同。
@@ -92,7 +92,7 @@ n1 = pb.neuron.LIF(shape=128, threshold=127, reset_v=0, leak_v=-1, keep_shape=Fa
 Tonic Spiking神经元可以实现对持续脉冲刺激的周期性反应。
 
 ```python
-n1 = pb.neuron.TonicSpiking(shape=128, fire_step=3, keep_shape=False, name='n1')
+n1 = pb.TonicSpiking(shape=128, fire_step=3, keep_shape=False, name='n1')
 ```
 
 - `fire_step`：发放周期，每接收到 `N` 次刺激后发放脉冲。
@@ -103,7 +103,7 @@ n1 = pb.neuron.TonicSpiking(shape=128, fire_step=3, keep_shape=False, name='n1')
 import paibox as pb
 import numpy as np
 
-n1 = pb.neuron.TonicSpiking(shape=1, fire_step=3)
+n1 = pb.TonicSpiking(shape=1, fire_step=3)
 inp_data = np.ones((10,), dtype=np.bool_)
 output = np.full((10,), 0, dtype=np.bool_)
 voltage = np.full((10,), 0, dtype=np.int32)
@@ -133,7 +133,7 @@ print(output)
 Phasic Spiking神经元可以实现，在接受一定数量脉冲后发放，然后保持静息状态，不再发放。
 
 ```python
-n1 = pb.neuron.PhasicSpiking(shape=128, time_to_fire=3, neg_floor=10, keep_shape=False, name='n1')
+n1 = pb.PhasicSpiking(shape=128, time_to_fire=3, neg_floor=10, keep_shape=False, name='n1')
 ```
 
 - `time_to_fire`：发放时间。
@@ -145,7 +145,7 @@ n1 = pb.neuron.PhasicSpiking(shape=128, time_to_fire=3, neg_floor=10, keep_shape
 import paibox as pb
 import numpy as np
 
-n1 = pb.neuron.PhasicSpiking(shape=1, time_to_fire=3)
+n1 = pb.PhasicSpiking(shape=1, time_to_fire=3)
 # [0, 0, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1]
 inp_data = np.concatenate((np.zeros((2,), np.bool_), np.ones((10,), np.bool_)))
 output = np.full((12,), 0, dtype=np.bool_)
@@ -176,10 +176,12 @@ print(output)
 
 ### 突触
 
+#### 全连接
+
 PAIBox中，突触用于连接不同神经元组，并包含了连接关系以及权重信息。以全连接类型的突触为实例：
 
 ```python
-s1= pb.synapses.NoDecay(source=n1, dest=n2, weights=weight1, conn_type=pb.SynConnType.All2All, name='s1')
+s1= pb.FullConn(source=n1, dest=n2, weights=weight1, conn_type=pb.SynConnType.All2All, name='s1')
 ```
 
 其中：
@@ -187,18 +189,19 @@ s1= pb.synapses.NoDecay(source=n1, dest=n2, weights=weight1, conn_type=pb.SynCon
 - `source`：前向神经元组，可以是**神经元或者输入节点**类型。
 - `dest`：后向神经元组，只能为**神经元**类型。
 - `weights`：突触的权重。
-- `conn_type`：连接形式，默认为 `MatConn` 矩阵连接。当设置为 `All2All` 或 `One2One` 时，`weights` 有更简洁的表达。
+- `conn_type`：连接形式，默认为 `MatConn` 矩阵连接。当设置为 `All2All`、`One2One` 或 `Identity` 时，`weights` 有更简洁的表达。
 - `name`：可选，为该对象命名。
 
 突触表达的是两个神经元组之间的连接关系。PAIBox提供了三种主要的连接关系表达：
 
 - `All2All`：全连接
 - `One2One`：单对单连接
+- `Identity`：恒等映射，同单对单连接，权重为缩放因子标量
 - `MatConn`：普通的矩阵连接
 
 通常情况下，`MatConn` 适合所有的连接关系，而 `All2All`、`One2One` 则提供了对于特殊连接更为方便的表达。
 
-#### All2All 全连接
+##### All2All 全连接
 
 对于全连接，其权重 `weights` 有两种输入类型：
 
@@ -207,30 +210,29 @@ s1= pb.synapses.NoDecay(source=n1, dest=n2, weights=weight1, conn_type=pb.SynCon
 
 其中，`N1` 为前向神经元组数目，`N2` 为后向神经元组数目。
 
-#### One2One 单对单连接
+##### One2One 单对单连接
 
 两组神经元之间依次单对单连接，这要求**前向与后向神经元数目相同**。其权重 `weights` 主要有以下几种输入类型：
 
 - 标量：默认为1。这表示前层的各个神经元输出线性地输入到后层神经元，即 $\lambda\cdot\mathbf{I}$
 
   ```python
-  n1 = pb.neuron.IF(shape=5,threshold=1)
-  n2 = pb.neuron.IF(shape=5,threshold=1)
-  s1 = pb.synapses.NoDecay(source=n1, dest=n2, conn_type=pb.ConnType.One2One, weights=2, name='s1')
+  n1 = pb.IF(shape=5, threshold=1)
+  n2 = pb.IF(shape=5, threshold=1)
+  s1 = pb.FullConn(source=n1, dest=n2, conn_type=pb.SynConnType.One2One, weights=2, name='s1')
 
   print(s1.weights)
   >>>
   2
   ```
 
-  其权重以标量的形式储存。由于在运算时标量会随着矩阵进行广播，因此计算正确且节省了存储开销。
-
+  其权重以标量的形式储存。
 - 数组：尺寸要求为 `(N2,)`，可以自定义每组对应神经元之间的连接权重。如下例所示，设置 `weights` 为 `[1, 2, 3, 4, 5]`，
 
   ```python
-  n1 = pb.neuron.IF(shape=5,threshold=1)
-  n2 = pb.neuron.IF(shape=5,threshold=1)
-  s1 = pb.synapses.NoDecay(source=n1, dest=n2, conn_type=pb.ConnType.One2One, weights=np.arange(1, 6, dtype=np.int8), name='s1')
+  n1 = pb.IF(shape=5, threshold=1)
+  n2 = pb.IF(shape=5, threshold=1)
+  s1 = pb.FullConn(source=n1, dest=n2, conn_type=pb.SynConnType.One2One, weights=np.arange(1, 6, dtype=np.int8), name='s1')
 
   print(s1.weights)
   >>>
@@ -243,14 +245,33 @@ s1= pb.synapses.NoDecay(source=n1, dest=n2, weights=weight1, conn_type=pb.SynCon
 
   其权重实际上为 `N*N` 矩阵，其中 `N` 为前向/后向神经元组数目。
 
-#### Identity 恒等映射
+##### Identity 恒等映射
 
 具有缩放因子的单对单连接，即 `One2One` 中权重项为标量的特殊情况。
 
-#### MatConn 一般连接
+##### MatConn 一般连接
 
 普通的神经元连接类型，仅可以通过矩阵设置其权重 `weights`。
 
+#### 2D卷积
+
+全展开形式2D卷积可用突触进行表示。对于一个卷积连接，需要严格指定前后神经元的尺寸、神经元维度顺序、卷积核全权重、卷积核维度顺序与步长信息。
+
+- `kernel`：卷积核权重。
+- `stride`：步长，可以为标量或元组。当为标量时，对应为 `(x, x)`；当为元组时，则对应为 `(x, y)`。
+- `fm_order` 指定神经元维度顺序为 `CHW` 或 `HWC` 排列。
+- `kernel_order`：指定卷积核维度顺序为 `OIHW` 或 `HWIO` 排列。
+
+```python
+n1 = pb.IF(shape=(8, 28, 28), threshold=1)      # Input feature map: (8, 28, 28)
+n2 = pb.IF(shape=(16, 26, 26), threshold=1)     # Output feature map: (16, 26, 26)
+kernel = np.random.randint(-128, 128, size=(16, 8, 3, 3), dtype=np.int8) # OIHW
+
+conv2d = pb.Conv2d(n1, n2, kernel=kernel, stride=1, fm_order="CHW", kernel_order="OIHW", name="conv_1")
+```
+
+⚠️ `padding` 不支持，默认为0。
+
 ### 编码器
 
 对于非脉冲数据，我们需要将其进行脉冲编码，然后输入网络中进行计算。
@@ -349,7 +370,7 @@ print(output)
 
 当启用 `keep_shape` 时，特征图数据将保持其维度信息。
 
-输入节点的参数也可以是 `np.ndarray` 。以下为一个简单实例：
+输入节点的参数也可以是数组。以下为一个简单实例：
 
 ```python
 x = np.random.randint(0, 5, size=(4, 4))
@@ -371,7 +392,7 @@ print(output)
 
 #### 函数类型输入
 
-输入节点支持使用自定义函数作为输入。以下为一个简单实例：
+输入节点支持使用函数作为输入。以下为一个简单实例：
 
 ```python
 def fakeout(*args, **kwargs):
@@ -393,7 +414,7 @@ print(output)
  [3 3 3 3]]
 ```
 
-当函数需要时间步信息，则可在函数参数中声明 `t` ，输入节点将在前端环境变量 `FRONTEND_ENV` 中获取时间步信息。当需要传入额外的参数时，通过 `FRONTEND_ENV.save()` 保存相关参数至前端环境变量。当函数与时间步或其他参数无关时，可使用 `**kwargs` 代替。以下为一个简单实例：
+当函数需要时间步信息，则可在函数中声明传入参数 `t` ，输入节点则在前端环境变量 `FRONTEND_ENV` 中获取时间步信息。当需要传入额外的参数时，通过 `FRONTEND_ENV.save()` 保存相关参数至前端环境变量。当函数与时间步或其他参数无关时，可使用 `**kwargs` 代替。以下为一个简单实例：
 
 ```python
 from paibox import FRONTEND_ENV
@@ -431,7 +452,7 @@ print(output)
 
 PAIBox提供了一些常用编码器，编码器内部实现了 `__call__` 方法，因此可作为输入节点的输入使用。在作为输入节点的输入使用时，它与一般函数做为输入节点的输入使用存在差别。
 
-在例化 `InputProj` 时，输入节点的输入为编码器。在运行时，还需要通过设置 `inp.input`，向输入节点输入待编码数据，输入节点内部将自动完成泊松编码并输出。以泊松编码器为例：
+在例化 `InputProj` 时，输入节点的输入为编码器。在运行时，还需要通过设置 `inp.input`，**向输入节点输入待编码数据**，节点内部将完成泊松编码并输出。以泊松编码器为例：
 
 ```python
 pe = pb.simulator.PoissonEncoder()                          # 例化泊松编码器
@@ -457,7 +478,7 @@ print(output)
 
 ### 网络模型
 
-在PAIBox中，神经网络搭建可以通过继承 `DynSysGroup`（或 `Network`，`DynSysGroup` 别名）来实现，并在其中例化神经元与突触组件，完成网络模型的搭建。以一个简单的全连接网络为例：
+在PAIBox中，可以通过继承 `DynSysGroup`（或 `Network`）来实现，并在其中例化神经元与突触组件，完成网络模型的构建。以一个简单的两层全连接网络为例：
 
 <p align="center">
     <img src="images/Guide-基础网络搭建-全连接网络示例.png" alt="基础网络搭建-全连接网络示例" style="zoom:50%">
@@ -476,10 +497,10 @@ class fcnet(pb.Network):
         pe = pb.simulator.PoissonEncoder()
 
         self.i1 = pb.InputProj(input=pe, shape_out=(784,))
-        self.n1 = pb.neuron.IF(128, threshold=128, reset_v=0, tick_wait_start=1)
-        self.n2 = pb.neuron.IF(10, threshold=128, reset_v=0, tick_wait_start=2)
-        self.s1 = pb.synapses.NoDecay(self.i1, self.n1, weights=weight1, conn_type=pb.SynConnType.All2All)
-        self.s2 = pb.synapses.NoDecay(self.n1, self.n2, weights=weight2, conn_type=pb.SynConnType.All2All)
+        self.n1 = pb.IF(128, threshold=128, reset_v=0, tick_wait_start=1)
+        self.n2 = pb.IF(10, threshold=128, reset_v=0, tick_wait_start=2)
+        self.fc1 = pb.FullConn(self.i1, self.n1, weights=weight1, conn_type=pb.SynConnType.All2All)
+        self.fc2 = pb.FullConn(self.n1, self.n2, weights=weight2, conn_type=pb.SynConnType.All2All)
 ```
 
 #### 容器类型
@@ -491,15 +512,15 @@ import paibox as pb
 l1 = pb.NodeList()
 
 for i in range(5):
-    l1.append(pb.neuron.IF(10, threshold=5, reset_v=0))
+    l1.append(pb.IF(10, threshold=5, reset_v=0))
 
 for i in range(5):
-    l1.append(pb.neuron.LIF(10, threshold=5, reset_v=0))
+    l1.append(pb.LIF(10, threshold=5, reset_v=0))
 ```
 
 如此，我们共例化了10个神经元，包括5个IF神经元、5个LIF神经元。在容器内的基本组件可通过下标进行访问、与其他基本组件连接。这与一般容器类型的用法相同。
 
-#### 构建子网络
+#### 嵌套网络
 
 有时网络中会重复出现类似的结构，这时先构建子网络，再多次例化复用是个不错的选择。
 
@@ -513,7 +534,7 @@ class ReusedStructure(pb.Network):
 
         self.pre_n = pb.LIF((10,), 10, tick_wait_start=tws)
         self.post_n = pb.LIF((10,), 10, tick_wait_start=tws+1)
-        self.syn = pb.NoDecay(
+        self.fc = pb.FullConn(
             self.pre_n, self.post_n, conn_type=pb.SynConnType.All2All, weights=weight
         )
 
@@ -522,12 +543,12 @@ class Net(pb.Network):
         self.inp1 = pb.InputProj(1, shape_out=(10,))
         subnet1 = ReusedStructure(w1, tws=1, name="Reused_Struct_0")
         subnet2 = ReusedStructure(w2, tws=3, name="Reused_Struct_1")
-        self.s1 = pb.NoDecay(
+        self.fc1 = pb.FullConn(
             self.inp1,
             subnet1.pre_n,
             conn_type=pb.SynConnType.One2One,
         )
-        self.s2 = pb.NoDecay(
+        self.fc2 = pb.FullConn(
             subnet1.post_n,
             subnet2.pre_n,
             conn_type=pb.SynConnType.One2One,
@@ -540,7 +561,7 @@ w2 = ...
 net = Net(w1, w2)
 ```
 
-上述示例代码中，我们先创建需复用的子网络 `ReusedStructure`，其结构为 `pre_n` -> `syn` -> `post_n`。而后，在父网络 `Net` 中实例化两个子网络 `subnet1`、 `subnet2`，并与父网络其他部分连接，此时网络结构为：`inp1` -> `s1` -> `subnet1` -> `s2` -> `subnet2`。最后，在为 `pb.Network` 初始化时，传入子网络 `subnet1`、 `subnet2`。由此，父网络 `Net` 才能发现子网络组件。如果想取到 `Net` 内的 `subnet1` 对象，可通过索引其名字 `Net["Reused_Struct_0"]` 取到。
+上述示例代码中，我们先创建需复用的子网络 `ReusedStructure`，其结构为 `pre_n` -> `fc` -> `post_n`。而后，在父网络 `Net` 中实例化两个子网络 `subnet1`、 `subnet2`，并与父网络其他部分连接，此时网络结构为：`inp1` -> `fc1` -> `subnet1` -> `fc22` -> `subnet2`。最后，在为 `pb.Network` 初始化时，传入子网络 `subnet1`、 `subnet2`。由此，父网络 `Net` 才能发现子网络组件。如果想取到 `Net` 内的 `subnet1` 对象，可通过索引其名字 `Net["Reused_Struct_0"]` 取到。
 
 上述示例为一个二级嵌套网络，对于三级嵌套网络或更高（不推荐使用），可参考上述方式构建。
 
@@ -596,7 +617,7 @@ sim.add_probe(probe2)
 可监测的对象包括网络内部所有的属性。例如，神经元及突触的各类属性，常用的监测对象包括：
 
 - 输入节点的 `feature_map`。
-- 神经元：脉冲输出 `spike` （本层神经元产生的脉冲，但不一定传递至后继神经元）、基于硬件寄存器的**输出** `output`（大小为 `256*N` ）、特征图形式的脉冲输出 `feature_map `、膜电位 `voltage`。
+- 神经元：脉冲输出 `spike` 、基于硬件寄存器的**输出** `output`（大小为 `256*N` ）、特征图形式的脉冲输出 `feature_map `、膜电位 `voltage`。
 - 突触：输出 `output`。
 
 ### 仿真机理
@@ -658,7 +679,15 @@ mapper.clear()
 - `split_by_coordinate`：是否将配置帧以每个核坐标进行分割，由此生成的配置帧文件命名为"config_core1"、"config_core2"等。默认为 `False`。
 - `local_chip_addr`：本地芯片地址，元组格式表示。默认为后端配置项 `local_chip_addr` 所设置的默认值。
 - `export_core_params`: 是否导出实际使用核参数至json文件，以直观显示实际使用核的配置信息。默认为 `False`。
-- 同时，该方法将返回模型的配置项字典。
+
+同时，该方法将返回模型的配置项字典 `GraphInfo`，包括：
+
+- `input`：输入节点信息字典。
+- `output`：输出目的地信息字典。
+- `memebers`：中间层所在物理核的配置项字典。
+- `inherent_timestep`：网络模型的最长时间步。
+- `n_core_required`：网络模型需要的物理核数目。
+- `extras`：其他额外的网络信息字典，例如，编译后网络名称。
 
 ### 后端配置项
 

From cdfaaff8ee255fed7722dd43aa4105bfc32b22d8 Mon Sep 17 00:00:00 2001
From: KafCoppelia <k740677208@gmail.com>
Date: Fri, 15 Mar 2024 18:45:22 +0800
Subject: [PATCH 26/68] =?UTF-8?q?=F0=9F=93=9D=20updated=20toml=20&=20chang?=
 =?UTF-8?q?elog?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

---
 CHANGELOG.md   |  10 ++
 README.md      |   2 +-
 poetry.lock    | 271 +++++++++++++++++++++++++++++++++++++++++++++++--
 pyproject.toml |   8 +-
 4 files changed, 281 insertions(+), 10 deletions(-)

diff --git a/CHANGELOG.md b/CHANGELOG.md
index c14c1141..1065e964 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -4,3 +4,13 @@
 - 修复工作流版本错误
 - 修复神经元膜电位溢出处理错误
 - 修复神经元分组的计数错误
+
+## v1.0.0a4
+
+- 重命名突触连接类型 `ConnType` 为 `SynConnType` ，现在通过 `pb.SynCnnType.x` 调用。例如，`pb.SynCnnType.All2All`
+
+## v1.0.0a5
+
+- 支持无限嵌套深度的网络
+- 支持全展开2D卷积算子构建与部署（`padding` 不支持）
+- 修复当 `keep_shape=True` 时，，神经元状态变量在运行时尺寸错误
diff --git a/README.md b/README.md
index c9dd7e93..91c7f215 100644
--- a/README.md
+++ b/README.md
@@ -8,7 +8,7 @@
     <a href="https://github.com/PAICookers/PAIBox/blob/master/pyproject.toml">
         <img src="https://img.shields.io/pypi/pyversions/paibox">
     </a>
-    <a href="https://github.com/PAICookers/PAIBox/releases/tag/v1.0.0a4">
+    <a href="https://github.com/PAICookers/PAIBox/releases/tag/v1.0.0a5">
         <img src="https://img.shields.io/github/v/release/PAICookers/PAIBox?include_prereleases&color=orange">
     </a>
     <a href="https://www.codefactor.io/repository/github/PAICookers/PAIBox">
diff --git a/poetry.lock b/poetry.lock
index 0e708efa..af10a356 100644
--- a/poetry.lock
+++ b/poetry.lock
@@ -54,6 +54,67 @@ type = "legacy"
 url = "https://pypi.tuna.tsinghua.edu.cn/simple"
 reference = "tsinghua"
 
+[[package]]
+name = "filelock"
+version = "3.13.1"
+description = "A platform independent file lock."
+optional = true
+python-versions = ">=3.8"
+files = [
+    {file = "filelock-3.13.1-py3-none-any.whl", hash = "sha256:57dbda9b35157b05fb3e58ee91448612eb674172fab98ee235ccb0b5bee19a1c"},
+    {file = "filelock-3.13.1.tar.gz", hash = "sha256:521f5f56c50f8426f5e03ad3b281b490a87ef15bc6c526f168290f0c7148d44e"},
+]
+
+[package.extras]
+docs = ["furo (>=2023.9.10)", "sphinx (>=7.2.6)", "sphinx-autodoc-typehints (>=1.24)"]
+testing = ["covdefaults (>=2.3)", "coverage (>=7.3.2)", "diff-cover (>=8)", "pytest (>=7.4.3)", "pytest-cov (>=4.1)", "pytest-mock (>=3.12)", "pytest-timeout (>=2.2)"]
+typing = ["typing-extensions (>=4.8)"]
+
+[package.source]
+type = "legacy"
+url = "https://pypi.tuna.tsinghua.edu.cn/simple"
+reference = "tsinghua"
+
+[[package]]
+name = "fsspec"
+version = "2024.2.0"
+description = "File-system specification"
+optional = true
+python-versions = ">=3.8"
+files = [
+    {file = "fsspec-2024.2.0-py3-none-any.whl", hash = "sha256:817f969556fa5916bc682e02ca2045f96ff7f586d45110fcb76022063ad2c7d8"},
+    {file = "fsspec-2024.2.0.tar.gz", hash = "sha256:b6ad1a679f760dda52b1168c859d01b7b80648ea6f7f7c7f5a8a91dc3f3ecb84"},
+]
+
+[package.extras]
+abfs = ["adlfs"]
+adl = ["adlfs"]
+arrow = ["pyarrow (>=1)"]
+dask = ["dask", "distributed"]
+devel = ["pytest", "pytest-cov"]
+dropbox = ["dropbox", "dropboxdrivefs", "requests"]
+full = ["adlfs", "aiohttp (!=4.0.0a0,!=4.0.0a1)", "dask", "distributed", "dropbox", "dropboxdrivefs", "fusepy", "gcsfs", "libarchive-c", "ocifs", "panel", "paramiko", "pyarrow (>=1)", "pygit2", "requests", "s3fs", "smbprotocol", "tqdm"]
+fuse = ["fusepy"]
+gcs = ["gcsfs"]
+git = ["pygit2"]
+github = ["requests"]
+gs = ["gcsfs"]
+gui = ["panel"]
+hdfs = ["pyarrow (>=1)"]
+http = ["aiohttp (!=4.0.0a0,!=4.0.0a1)"]
+libarchive = ["libarchive-c"]
+oci = ["ocifs"]
+s3 = ["s3fs"]
+sftp = ["paramiko"]
+smb = ["smbprotocol"]
+ssh = ["paramiko"]
+tqdm = ["tqdm"]
+
+[package.source]
+type = "legacy"
+url = "https://pypi.tuna.tsinghua.edu.cn/simple"
+reference = "tsinghua"
+
 [[package]]
 name = "iniconfig"
 version = "2.0.0"
@@ -70,6 +131,147 @@ type = "legacy"
 url = "https://pypi.tuna.tsinghua.edu.cn/simple"
 reference = "tsinghua"
 
+[[package]]
+name = "jinja2"
+version = "3.1.3"
+description = "A very fast and expressive template engine."
+optional = true
+python-versions = ">=3.7"
+files = [
+    {file = "Jinja2-3.1.3-py3-none-any.whl", hash = "sha256:7d6d50dd97d52cbc355597bd845fabfbac3f551e1f99619e39a35ce8c370b5fa"},
+    {file = "Jinja2-3.1.3.tar.gz", hash = "sha256:ac8bd6544d4bb2c9792bf3a159e80bba8fda7f07e81bc3aed565432d5925ba90"},
+]
+
+[package.dependencies]
+MarkupSafe = ">=2.0"
+
+[package.extras]
+i18n = ["Babel (>=2.7)"]
+
+[package.source]
+type = "legacy"
+url = "https://pypi.tuna.tsinghua.edu.cn/simple"
+reference = "tsinghua"
+
+[[package]]
+name = "markupsafe"
+version = "2.1.5"
+description = "Safely add untrusted strings to HTML/XML markup."
+optional = true
+python-versions = ">=3.7"
+files = [
+    {file = "MarkupSafe-2.1.5-cp310-cp310-macosx_10_9_universal2.whl", hash = "sha256:a17a92de5231666cfbe003f0e4b9b3a7ae3afb1ec2845aadc2bacc93ff85febc"},
+    {file = "MarkupSafe-2.1.5-cp310-cp310-macosx_10_9_x86_64.whl", hash = "sha256:72b6be590cc35924b02c78ef34b467da4ba07e4e0f0454a2c5907f473fc50ce5"},
+    {file = "MarkupSafe-2.1.5-cp310-cp310-manylinux_2_17_aarch64.manylinux2014_aarch64.whl", hash = "sha256:e61659ba32cf2cf1481e575d0462554625196a1f2fc06a1c777d3f48e8865d46"},
+    {file = "MarkupSafe-2.1.5-cp310-cp310-manylinux_2_17_x86_64.manylinux2014_x86_64.whl", hash = "sha256:2174c595a0d73a3080ca3257b40096db99799265e1c27cc5a610743acd86d62f"},
+    {file = "MarkupSafe-2.1.5-cp310-cp310-manylinux_2_5_i686.manylinux1_i686.manylinux_2_17_i686.manylinux2014_i686.whl", hash = "sha256:ae2ad8ae6ebee9d2d94b17fb62763125f3f374c25618198f40cbb8b525411900"},
+    {file = "MarkupSafe-2.1.5-cp310-cp310-musllinux_1_1_aarch64.whl", hash = "sha256:075202fa5b72c86ad32dc7d0b56024ebdbcf2048c0ba09f1cde31bfdd57bcfff"},
+    {file = "MarkupSafe-2.1.5-cp310-cp310-musllinux_1_1_i686.whl", hash = "sha256:598e3276b64aff0e7b3451b72e94fa3c238d452e7ddcd893c3ab324717456bad"},
+    {file = "MarkupSafe-2.1.5-cp310-cp310-musllinux_1_1_x86_64.whl", hash = "sha256:fce659a462a1be54d2ffcacea5e3ba2d74daa74f30f5f143fe0c58636e355fdd"},
+    {file = "MarkupSafe-2.1.5-cp310-cp310-win32.whl", hash = "sha256:d9fad5155d72433c921b782e58892377c44bd6252b5af2f67f16b194987338a4"},
+    {file = "MarkupSafe-2.1.5-cp310-cp310-win_amd64.whl", hash = "sha256:bf50cd79a75d181c9181df03572cdce0fbb75cc353bc350712073108cba98de5"},
+    {file = "MarkupSafe-2.1.5-cp311-cp311-macosx_10_9_universal2.whl", hash = "sha256:629ddd2ca402ae6dbedfceeba9c46d5f7b2a61d9749597d4307f943ef198fc1f"},
+    {file = "MarkupSafe-2.1.5-cp311-cp311-macosx_10_9_x86_64.whl", hash = "sha256:5b7b716f97b52c5a14bffdf688f971b2d5ef4029127f1ad7a513973cfd818df2"},
+    {file = "MarkupSafe-2.1.5-cp311-cp311-manylinux_2_17_aarch64.manylinux2014_aarch64.whl", hash = "sha256:6ec585f69cec0aa07d945b20805be741395e28ac1627333b1c5b0105962ffced"},
+    {file = "MarkupSafe-2.1.5-cp311-cp311-manylinux_2_17_x86_64.manylinux2014_x86_64.whl", hash = "sha256:b91c037585eba9095565a3556f611e3cbfaa42ca1e865f7b8015fe5c7336d5a5"},
+    {file = "MarkupSafe-2.1.5-cp311-cp311-manylinux_2_5_i686.manylinux1_i686.manylinux_2_17_i686.manylinux2014_i686.whl", hash = "sha256:7502934a33b54030eaf1194c21c692a534196063db72176b0c4028e140f8f32c"},
+    {file = "MarkupSafe-2.1.5-cp311-cp311-musllinux_1_1_aarch64.whl", hash = "sha256:0e397ac966fdf721b2c528cf028494e86172b4feba51d65f81ffd65c63798f3f"},
+    {file = "MarkupSafe-2.1.5-cp311-cp311-musllinux_1_1_i686.whl", hash = "sha256:c061bb86a71b42465156a3ee7bd58c8c2ceacdbeb95d05a99893e08b8467359a"},
+    {file = "MarkupSafe-2.1.5-cp311-cp311-musllinux_1_1_x86_64.whl", hash = "sha256:3a57fdd7ce31c7ff06cdfbf31dafa96cc533c21e443d57f5b1ecc6cdc668ec7f"},
+    {file = "MarkupSafe-2.1.5-cp311-cp311-win32.whl", hash = "sha256:397081c1a0bfb5124355710fe79478cdbeb39626492b15d399526ae53422b906"},
+    {file = "MarkupSafe-2.1.5-cp311-cp311-win_amd64.whl", hash = "sha256:2b7c57a4dfc4f16f7142221afe5ba4e093e09e728ca65c51f5620c9aaeb9a617"},
+    {file = "MarkupSafe-2.1.5-cp312-cp312-macosx_10_9_universal2.whl", hash = "sha256:8dec4936e9c3100156f8a2dc89c4b88d5c435175ff03413b443469c7c8c5f4d1"},
+    {file = "MarkupSafe-2.1.5-cp312-cp312-macosx_10_9_x86_64.whl", hash = "sha256:3c6b973f22eb18a789b1460b4b91bf04ae3f0c4234a0a6aa6b0a92f6f7b951d4"},
+    {file = "MarkupSafe-2.1.5-cp312-cp312-manylinux_2_17_aarch64.manylinux2014_aarch64.whl", hash = "sha256:ac07bad82163452a6884fe8fa0963fb98c2346ba78d779ec06bd7a6262132aee"},
+    {file = "MarkupSafe-2.1.5-cp312-cp312-manylinux_2_17_x86_64.manylinux2014_x86_64.whl", hash = "sha256:f5dfb42c4604dddc8e4305050aa6deb084540643ed5804d7455b5df8fe16f5e5"},
+    {file = "MarkupSafe-2.1.5-cp312-cp312-manylinux_2_5_i686.manylinux1_i686.manylinux_2_17_i686.manylinux2014_i686.whl", hash = "sha256:ea3d8a3d18833cf4304cd2fc9cbb1efe188ca9b5efef2bdac7adc20594a0e46b"},
+    {file = "MarkupSafe-2.1.5-cp312-cp312-musllinux_1_1_aarch64.whl", hash = "sha256:d050b3361367a06d752db6ead6e7edeb0009be66bc3bae0ee9d97fb326badc2a"},
+    {file = "MarkupSafe-2.1.5-cp312-cp312-musllinux_1_1_i686.whl", hash = "sha256:bec0a414d016ac1a18862a519e54b2fd0fc8bbfd6890376898a6c0891dd82e9f"},
+    {file = "MarkupSafe-2.1.5-cp312-cp312-musllinux_1_1_x86_64.whl", hash = "sha256:58c98fee265677f63a4385256a6d7683ab1832f3ddd1e66fe948d5880c21a169"},
+    {file = "MarkupSafe-2.1.5-cp312-cp312-win32.whl", hash = "sha256:8590b4ae07a35970728874632fed7bd57b26b0102df2d2b233b6d9d82f6c62ad"},
+    {file = "MarkupSafe-2.1.5-cp312-cp312-win_amd64.whl", hash = "sha256:823b65d8706e32ad2df51ed89496147a42a2a6e01c13cfb6ffb8b1e92bc910bb"},
+    {file = "MarkupSafe-2.1.5-cp37-cp37m-macosx_10_9_x86_64.whl", hash = "sha256:c8b29db45f8fe46ad280a7294f5c3ec36dbac9491f2d1c17345be8e69cc5928f"},
+    {file = "MarkupSafe-2.1.5-cp37-cp37m-manylinux_2_17_aarch64.manylinux2014_aarch64.whl", hash = "sha256:ec6a563cff360b50eed26f13adc43e61bc0c04d94b8be985e6fb24b81f6dcfdf"},
+    {file = "MarkupSafe-2.1.5-cp37-cp37m-manylinux_2_17_x86_64.manylinux2014_x86_64.whl", hash = "sha256:a549b9c31bec33820e885335b451286e2969a2d9e24879f83fe904a5ce59d70a"},
+    {file = "MarkupSafe-2.1.5-cp37-cp37m-manylinux_2_5_i686.manylinux1_i686.manylinux_2_17_i686.manylinux2014_i686.whl", hash = "sha256:4f11aa001c540f62c6166c7726f71f7573b52c68c31f014c25cc7901deea0b52"},
+    {file = "MarkupSafe-2.1.5-cp37-cp37m-musllinux_1_1_aarch64.whl", hash = "sha256:7b2e5a267c855eea6b4283940daa6e88a285f5f2a67f2220203786dfa59b37e9"},
+    {file = "MarkupSafe-2.1.5-cp37-cp37m-musllinux_1_1_i686.whl", hash = "sha256:2d2d793e36e230fd32babe143b04cec8a8b3eb8a3122d2aceb4a371e6b09b8df"},
+    {file = "MarkupSafe-2.1.5-cp37-cp37m-musllinux_1_1_x86_64.whl", hash = "sha256:ce409136744f6521e39fd8e2a24c53fa18ad67aa5bc7c2cf83645cce5b5c4e50"},
+    {file = "MarkupSafe-2.1.5-cp37-cp37m-win32.whl", hash = "sha256:4096e9de5c6fdf43fb4f04c26fb114f61ef0bf2e5604b6ee3019d51b69e8c371"},
+    {file = "MarkupSafe-2.1.5-cp37-cp37m-win_amd64.whl", hash = "sha256:4275d846e41ecefa46e2015117a9f491e57a71ddd59bbead77e904dc02b1bed2"},
+    {file = "MarkupSafe-2.1.5-cp38-cp38-macosx_10_9_universal2.whl", hash = "sha256:656f7526c69fac7f600bd1f400991cc282b417d17539a1b228617081106feb4a"},
+    {file = "MarkupSafe-2.1.5-cp38-cp38-macosx_10_9_x86_64.whl", hash = "sha256:97cafb1f3cbcd3fd2b6fbfb99ae11cdb14deea0736fc2b0952ee177f2b813a46"},
+    {file = "MarkupSafe-2.1.5-cp38-cp38-manylinux_2_17_aarch64.manylinux2014_aarch64.whl", hash = "sha256:1f3fbcb7ef1f16e48246f704ab79d79da8a46891e2da03f8783a5b6fa41a9532"},
+    {file = "MarkupSafe-2.1.5-cp38-cp38-manylinux_2_17_x86_64.manylinux2014_x86_64.whl", hash = "sha256:fa9db3f79de01457b03d4f01b34cf91bc0048eb2c3846ff26f66687c2f6d16ab"},
+    {file = "MarkupSafe-2.1.5-cp38-cp38-manylinux_2_5_i686.manylinux1_i686.manylinux_2_17_i686.manylinux2014_i686.whl", hash = "sha256:ffee1f21e5ef0d712f9033568f8344d5da8cc2869dbd08d87c84656e6a2d2f68"},
+    {file = "MarkupSafe-2.1.5-cp38-cp38-musllinux_1_1_aarch64.whl", hash = "sha256:5dedb4db619ba5a2787a94d877bc8ffc0566f92a01c0ef214865e54ecc9ee5e0"},
+    {file = "MarkupSafe-2.1.5-cp38-cp38-musllinux_1_1_i686.whl", hash = "sha256:30b600cf0a7ac9234b2638fbc0fb6158ba5bdcdf46aeb631ead21248b9affbc4"},
+    {file = "MarkupSafe-2.1.5-cp38-cp38-musllinux_1_1_x86_64.whl", hash = "sha256:8dd717634f5a044f860435c1d8c16a270ddf0ef8588d4887037c5028b859b0c3"},
+    {file = "MarkupSafe-2.1.5-cp38-cp38-win32.whl", hash = "sha256:daa4ee5a243f0f20d528d939d06670a298dd39b1ad5f8a72a4275124a7819eff"},
+    {file = "MarkupSafe-2.1.5-cp38-cp38-win_amd64.whl", hash = "sha256:619bc166c4f2de5caa5a633b8b7326fbe98e0ccbfacabd87268a2b15ff73a029"},
+    {file = "MarkupSafe-2.1.5-cp39-cp39-macosx_10_9_universal2.whl", hash = "sha256:7a68b554d356a91cce1236aa7682dc01df0edba8d043fd1ce607c49dd3c1edcf"},
+    {file = "MarkupSafe-2.1.5-cp39-cp39-macosx_10_9_x86_64.whl", hash = "sha256:db0b55e0f3cc0be60c1f19efdde9a637c32740486004f20d1cff53c3c0ece4d2"},
+    {file = "MarkupSafe-2.1.5-cp39-cp39-manylinux_2_17_aarch64.manylinux2014_aarch64.whl", hash = "sha256:3e53af139f8579a6d5f7b76549125f0d94d7e630761a2111bc431fd820e163b8"},
+    {file = "MarkupSafe-2.1.5-cp39-cp39-manylinux_2_17_x86_64.manylinux2014_x86_64.whl", hash = "sha256:17b950fccb810b3293638215058e432159d2b71005c74371d784862b7e4683f3"},
+    {file = "MarkupSafe-2.1.5-cp39-cp39-manylinux_2_5_i686.manylinux1_i686.manylinux_2_17_i686.manylinux2014_i686.whl", hash = "sha256:4c31f53cdae6ecfa91a77820e8b151dba54ab528ba65dfd235c80b086d68a465"},
+    {file = "MarkupSafe-2.1.5-cp39-cp39-musllinux_1_1_aarch64.whl", hash = "sha256:bff1b4290a66b490a2f4719358c0cdcd9bafb6b8f061e45c7a2460866bf50c2e"},
+    {file = "MarkupSafe-2.1.5-cp39-cp39-musllinux_1_1_i686.whl", hash = "sha256:bc1667f8b83f48511b94671e0e441401371dfd0f0a795c7daa4a3cd1dde55bea"},
+    {file = "MarkupSafe-2.1.5-cp39-cp39-musllinux_1_1_x86_64.whl", hash = "sha256:5049256f536511ee3f7e1b3f87d1d1209d327e818e6ae1365e8653d7e3abb6a6"},
+    {file = "MarkupSafe-2.1.5-cp39-cp39-win32.whl", hash = "sha256:00e046b6dd71aa03a41079792f8473dc494d564611a8f89bbbd7cb93295ebdcf"},
+    {file = "MarkupSafe-2.1.5-cp39-cp39-win_amd64.whl", hash = "sha256:fa173ec60341d6bb97a89f5ea19c85c5643c1e7dedebc22f5181eb73573142c5"},
+    {file = "MarkupSafe-2.1.5.tar.gz", hash = "sha256:d283d37a890ba4c1ae73ffadf8046435c76e7bc2247bbb63c00bd1a709c6544b"},
+]
+
+[package.source]
+type = "legacy"
+url = "https://pypi.tuna.tsinghua.edu.cn/simple"
+reference = "tsinghua"
+
+[[package]]
+name = "mpmath"
+version = "1.3.0"
+description = "Python library for arbitrary-precision floating-point arithmetic"
+optional = true
+python-versions = "*"
+files = [
+    {file = "mpmath-1.3.0-py3-none-any.whl", hash = "sha256:a0b2b9fe80bbcd81a6647ff13108738cfb482d481d826cc0e02f5b35e5c88d2c"},
+    {file = "mpmath-1.3.0.tar.gz", hash = "sha256:7a28eb2a9774d00c7bc92411c19a89209d5da7c4c9a9e227be8330a23a25b91f"},
+]
+
+[package.extras]
+develop = ["codecov", "pycodestyle", "pytest (>=4.6)", "pytest-cov", "wheel"]
+docs = ["sphinx"]
+gmpy = ["gmpy2 (>=2.1.0a4)"]
+tests = ["pytest (>=4.6)"]
+
+[package.source]
+type = "legacy"
+url = "https://pypi.tuna.tsinghua.edu.cn/simple"
+reference = "tsinghua"
+
+[[package]]
+name = "networkx"
+version = "3.1"
+description = "Python package for creating and manipulating graphs and networks"
+optional = true
+python-versions = ">=3.8"
+files = [
+    {file = "networkx-3.1-py3-none-any.whl", hash = "sha256:4f33f68cb2afcf86f28a45f43efc27a9386b535d567d2127f8f61d51dec58d36"},
+    {file = "networkx-3.1.tar.gz", hash = "sha256:de346335408f84de0eada6ff9fafafff9bcda11f0a0dfaa931133debb146ab61"},
+]
+
+[package.extras]
+default = ["matplotlib (>=3.4)", "numpy (>=1.20)", "pandas (>=1.3)", "scipy (>=1.8)"]
+developer = ["mypy (>=1.1)", "pre-commit (>=3.2)"]
+doc = ["nb2plots (>=0.6)", "numpydoc (>=1.5)", "pillow (>=9.4)", "pydata-sphinx-theme (>=0.13)", "sphinx (>=6.1)", "sphinx-gallery (>=0.12)", "texext (>=0.6.7)"]
+extra = ["lxml (>=4.6)", "pydot (>=1.4.2)", "pygraphviz (>=1.10)", "sympy (>=1.10)"]
+test = ["codecov (>=2.1)", "pytest (>=7.2)", "pytest-cov (>=4.0)"]
+
+[package.source]
+type = "legacy"
+url = "https://pypi.tuna.tsinghua.edu.cn/simple"
+reference = "tsinghua"
+
 [[package]]
 name = "numpy"
 version = "1.24.4"
@@ -114,13 +316,13 @@ reference = "tsinghua"
 
 [[package]]
 name = "packaging"
-version = "23.2"
+version = "24.0"
 description = "Core utilities for Python packages"
 optional = false
 python-versions = ">=3.7"
 files = [
-    {file = "packaging-23.2-py3-none-any.whl", hash = "sha256:8c491190033a9af7e1d931d0b5dacc2ef47509b34dd0de67ed209b5203fc88c7"},
-    {file = "packaging-23.2.tar.gz", hash = "sha256:048fb0e9405036518eaaf48a55953c750c11e1a1b68e0dd1a9d62ed0c092cfc5"},
+    {file = "packaging-24.0-py3-none-any.whl", hash = "sha256:2ddfb553fdf02fb784c234c7ba6ccc288296ceabec964ad2eae3777778130bc5"},
+    {file = "packaging-24.0.tar.gz", hash = "sha256:eb82c5e3e56209074766e6885bb04b8c38a0c015d0a30036ebe7ece34c9989e9"},
 ]
 
 [package.source]
@@ -170,13 +372,13 @@ reference = "tsinghua"
 
 [[package]]
 name = "pydantic"
-version = "2.6.3"
+version = "2.6.4"
 description = "Data validation using Python type hints"
 optional = false
 python-versions = ">=3.8"
 files = [
-    {file = "pydantic-2.6.3-py3-none-any.whl", hash = "sha256:72c6034df47f46ccdf81869fddb81aade68056003900a8724a4f160700016a2a"},
-    {file = "pydantic-2.6.3.tar.gz", hash = "sha256:e07805c4c7f5c6826e33a1d4c9d47950d7eaf34868e2690f8594d2e30241f11f"},
+    {file = "pydantic-2.6.4-py3-none-any.whl", hash = "sha256:cc46fce86607580867bdc3361ad462bab9c222ef042d3da86f2fb333e1d916c5"},
+    {file = "pydantic-2.6.4.tar.gz", hash = "sha256:b1704e0847db01817624a6b86766967f552dd9dbf3afba4004409f908dcc84e6"},
 ]
 
 [package.dependencies]
@@ -315,6 +517,25 @@ type = "legacy"
 url = "https://pypi.tuna.tsinghua.edu.cn/simple"
 reference = "tsinghua"
 
+[[package]]
+name = "sympy"
+version = "1.12"
+description = "Computer algebra system (CAS) in Python"
+optional = true
+python-versions = ">=3.8"
+files = [
+    {file = "sympy-1.12-py3-none-any.whl", hash = "sha256:c3588cd4295d0c0f603d0f2ae780587e64e2efeedb3521e46b9bb1d08d184fa5"},
+    {file = "sympy-1.12.tar.gz", hash = "sha256:ebf595c8dac3e0fdc4152c51878b498396ec7f30e7a914d6071e674d49420fb8"},
+]
+
+[package.dependencies]
+mpmath = ">=0.19"
+
+[package.source]
+type = "legacy"
+url = "https://pypi.tuna.tsinghua.edu.cn/simple"
+reference = "tsinghua"
+
 [[package]]
 name = "tomli"
 version = "2.0.1"
@@ -331,6 +552,42 @@ type = "legacy"
 url = "https://pypi.tuna.tsinghua.edu.cn/simple"
 reference = "tsinghua"
 
+[[package]]
+name = "torch"
+version = "2.2.1+cpu"
+description = "Tensors and Dynamic neural networks in Python with strong GPU acceleration"
+optional = true
+python-versions = ">=3.8.0"
+files = [
+    {file = "torch-2.2.1+cpu-cp310-cp310-linux_x86_64.whl", hash = "sha256:5d82422cf04797f1b2a8574b64a916070ec83eef58ad4900615ee0218d7b8b8e"},
+    {file = "torch-2.2.1+cpu-cp310-cp310-win_amd64.whl", hash = "sha256:f8914dd0f5f0e5c66fdecd9559403eea9feac82d1ea639b672fde0073c6addbd"},
+    {file = "torch-2.2.1+cpu-cp311-cp311-linux_x86_64.whl", hash = "sha256:6bc973d5632374b92b4b293817b4d2ff8c8ce1c784c748b471dba1fffcd9c333"},
+    {file = "torch-2.2.1+cpu-cp311-cp311-win_amd64.whl", hash = "sha256:abdec34b0ade8fca0520055e72c3094425ae0ef210718e9c0278121cd3608c32"},
+    {file = "torch-2.2.1+cpu-cp312-cp312-linux_x86_64.whl", hash = "sha256:d7339580135da4105c1244a8621faa076990409afeab5a7b642c3c1ee70a5622"},
+    {file = "torch-2.2.1+cpu-cp312-cp312-win_amd64.whl", hash = "sha256:039128fcb5548122465b15f679b8831c47d14f0d6c28c1f1b631f8019c104720"},
+    {file = "torch-2.2.1+cpu-cp38-cp38-linux_x86_64.whl", hash = "sha256:2b447f7bb50b393b4544b4036d587e39ab524d4353e77c197f6a2727f22b0d47"},
+    {file = "torch-2.2.1+cpu-cp38-cp38-win_amd64.whl", hash = "sha256:2ccdf3e5f71e6426ea9e34d21c3cc333b29d4f48299b981d28aeb5112b5495e1"},
+    {file = "torch-2.2.1+cpu-cp39-cp39-linux_x86_64.whl", hash = "sha256:2fb340b289760040a16a77a6d70b8a48961abba1822e6f58705c97c80befa03e"},
+    {file = "torch-2.2.1+cpu-cp39-cp39-win_amd64.whl", hash = "sha256:e03dc4654ecceeb5b03f0a6f60b342c0e0d267b3ebc61e4f672cace1df8cd930"},
+]
+
+[package.dependencies]
+filelock = "*"
+fsspec = "*"
+jinja2 = "*"
+networkx = "*"
+sympy = "*"
+typing-extensions = ">=4.8.0"
+
+[package.extras]
+opt-einsum = ["opt-einsum (>=3.3)"]
+optree = ["optree (>=0.9.1)"]
+
+[package.source]
+type = "legacy"
+url = "https://download.pytorch.org/whl/cpu"
+reference = "torch-cpu"
+
 [[package]]
 name = "typing-extensions"
 version = "4.10.0"
@@ -350,4 +607,4 @@ reference = "tsinghua"
 [metadata]
 lock-version = "2.0"
 python-versions = "^3.8"
-content-hash = "295f008b50237c89eb3f089a3ee5300773b140e93e4d879f87ba469b20e6ac36"
+content-hash = "6b533f29e8de8c75ca36a4885b25f8dca69422b7701d6271cdcdc572781bbd4d"
diff --git a/pyproject.toml b/pyproject.toml
index cf43b98f..b1bef1e7 100644
--- a/pyproject.toml
+++ b/pyproject.toml
@@ -1,6 +1,6 @@
 [tool.poetry]
 name = "paibox"
-version = "1.0.0a4"
+version = "1.0.0a5"
 description = "New toolbox of PAICORE 2.0."
 authors = ["Ziru Pan <zrpan@stu.pku.edu.cn>"]
 maintainers = ["Ziru Pan <zrpan@stu.pku.edu.cn>"]
@@ -15,7 +15,7 @@ packages = [{ include = "paibox" }]
 # Includes the document
 include = ["docs", "CHANGELOG.md"]
 # Excludes the experimental code
-exclude = ["paibox/backend/experimental"]
+exclude = ["paibox/experimental"]
 
 [tool.poetry.dependencies]
 python = "^3.8"
@@ -23,9 +23,13 @@ pydantic = "^2.0"
 numpy = "^1.23.0"
 paicorelib = "0.0.13"
 
+[tool.poetry.group.test]
+optional = true
+
 
 [tool.poetry.group.test.dependencies]
 pytest = { version = "^7.4.0", python = "^3.8" }
+torch = { version = "^2.2.1+cpu", optional = true, source = "torch-cpu" }
 
 
 [tool.pytest.ini_options]

From 6736dc2ea4aa8e926597420d63cb429f6a3f8087 Mon Sep 17 00:00:00 2001
From: "pre-commit-ci[bot]"
 <66853113+pre-commit-ci[bot]@users.noreply.github.com>
Date: Fri, 15 Mar 2024 11:08:14 +0000
Subject: [PATCH 27/68] :rotating_light: auto fix by pre-commit hooks

---
 .gitignore                        |  2 +-
 TODO.md                           | 26 ++++++++++++++------------
 docs/Guide-of-PAIBox.md           |  1 +
 examples/mnist/example1/main.py   |  3 ++-
 examples/mnist/example2/main.py   |  4 +++-
 paibox/__init__.py                |  6 +++---
 paibox/backend/conf_template.py   |  1 -
 paibox/base.py                    |  4 ++--
 paibox/synapses/__init__.py       |  5 ++---
 paibox/synapses/base.py           | 19 +++++++------------
 paibox/synapses/conv_utils.py     |  4 ++--
 paibox/synapses/synapses.py       |  4 ++--
 paibox/synapses/transforms.py     |  5 +++--
 tests/backend/conftest.py         |  8 ++------
 tests/conftest.py                 |  3 ++-
 tests/synapses/test_transforms.py |  4 ++--
 16 files changed, 48 insertions(+), 51 deletions(-)

diff --git a/.gitignore b/.gitignore
index 6ebc37e6..d53852fe 100644
--- a/.gitignore
+++ b/.gitignore
@@ -154,4 +154,4 @@ cython_debug/
 
 .vscode
 debug
-*.drawio
\ No newline at end of file
+*.drawio
diff --git a/TODO.md b/TODO.md
index a212b9b6..66e86fc6 100644
--- a/TODO.md
+++ b/TODO.md
@@ -1,26 +1,28 @@
 ## TODO
 
-- [X] 帧导出与优化
-- [X] 神经元目的地突触寻找对齐地址算法（待验证）
+- [x] 帧导出与优化
+- [x] 神经元目的地突触寻找对齐地址算法（待验证）
   - 聚焦 `aligned_coords` 前后所涉及的寻找神经元的目的地突触地址算法
-- [X] 多精度权重支持（待验证）
+- [x] 多精度权重支持（待验证）
   - 聚集 `CorePlcement` 内 `_fold_raw_weights` 前后所涉及的权重拆分算法，需要经过充分验证
-- [X] 运行时交换文件格式约定与导出
-- [X] `tick_wait_start` 与 `tick_wait_end` 前/后端支持
-- [X] 网络节点间自定义延迟( `tick_relative` )前后端支持
-- [X] 神经元密集分配策略（待验证）
+- [x] 运行时交换文件格式约定与导出
+- [x] `tick_wait_start` 与 `tick_wait_end` 前/后端支持
+- [x] 网络节点间自定义延迟( `tick_relative` )前后端支持
+- [x] 神经元密集分配策略（待验证）
 
 - 功能模块支持
 
-  - [X] 全展开2D卷积算子
+  - [x] 全展开2D卷积算子
   - [ ] 半折叠2D卷积算子
   - [ ] 残差结构
   - [ ] 逻辑算子：与、或、非
   - [ ] 二维矩阵转置
+
 - 多层次结构网络组件的发现、数据流验证与后端解析
 
-  - [X] 对有层次结构（子网络例化复用等情形）的网络模型，实现在所有层次上网络组件的发现、数据流与后端解析实现
+  - [x] 对有层次结构（子网络例化复用等情形）的网络模型，实现在所有层次上网络组件的发现、数据流与后端解析实现
   - [ ] 局部连接包装成单个算子，实现在所有层次上网络组件的发现、数据流与后端解析实现。考虑用户调用接口
+
 - 带有约束的路由坐标分配
 
   - [ ] 支持芯片阵列部署
@@ -30,9 +32,9 @@
 
 - 神经元分配策略（资源优先、延迟/吞吐率优先、资源+延时/吞吐率兼顾）的后端支持
 
-  - [X] 资源优先：直接对该节点所有神经元进行密集分配，使用最少的物理核资源
-  - [X] 延时/吞吐率优先（负载均衡）：由于节点的计算时间取决于该节点神经元全部计算完成的耗时，因此该节点神经元被分配至多个物理核上时，采取负载均衡策略，可提高节点吞吐率，优化计算延时
-  - [X] 资源+延时/吞吐率兼顾：在资源优先的基础上，可**叠加使用密集分配策略**，对未分配满的物理核尝试分配同一节点的其他神经元段。相较于单纯使用资源优先策略，使用更少的物理核
+  - [x] 资源优先：直接对该节点所有神经元进行密集分配，使用最少的物理核资源
+  - [x] 延时/吞吐率优先（负载均衡）：由于节点的计算时间取决于该节点神经元全部计算完成的耗时，因此该节点神经元被分配至多个物理核上时，采取负载均衡策略，可提高节点吞吐率，优化计算延时
+  - [x] 资源+延时/吞吐率兼顾：在资源优先的基础上，可**叠加使用密集分配策略**，对未分配满的物理核尝试分配同一节点的其他神经元段。相较于单纯使用资源优先策略，使用更少的物理核
   - [ ] 自适应策略：根据网络结构，对各层 `unrolling factor` 做全局最优化设置，且预留接口以手动约束某些节点
 
 - [ ] 混合精度权重支持（已添加权重精度优化的**编译选项**）
diff --git a/docs/Guide-of-PAIBox.md b/docs/Guide-of-PAIBox.md
index 54fe0850..5ccaf761 100644
--- a/docs/Guide-of-PAIBox.md
+++ b/docs/Guide-of-PAIBox.md
@@ -227,6 +227,7 @@ s1= pb.FullConn(source=n1, dest=n2, weights=weight1, conn_type=pb.SynConnType.Al
   ```
 
   其权重以标量的形式储存。
+
 - 数组：尺寸要求为 `(N2,)`，可以自定义每组对应神经元之间的连接权重。如下例所示，设置 `weights` 为 `[1, 2, 3, 4, 5]`，
 
   ```python
diff --git a/examples/mnist/example1/main.py b/examples/mnist/example1/main.py
index 86b518f0..e92a6ae2 100644
--- a/examples/mnist/example1/main.py
+++ b/examples/mnist/example1/main.py
@@ -1,7 +1,8 @@
 import argparse
-import numpy as np
 from pathlib import Path
 
+import numpy as np
+
 import paibox as pb
 
 
diff --git a/examples/mnist/example2/main.py b/examples/mnist/example2/main.py
index 519b6b93..3c985886 100644
--- a/examples/mnist/example2/main.py
+++ b/examples/mnist/example2/main.py
@@ -1,6 +1,8 @@
 import argparse
-import numpy as np
 from pathlib import Path
+
+import numpy as np
+
 import paibox as pb
 
 
diff --git a/paibox/__init__.py b/paibox/__init__.py
index ffe52dc7..184d573f 100644
--- a/paibox/__init__.py
+++ b/paibox/__init__.py
@@ -1,3 +1,5 @@
+from importlib.metadata import version
+
 from .backend import BACKEND_CONFIG as BACKEND_CONFIG
 from .backend import Mapper as Mapper
 from .base import *
@@ -12,10 +14,8 @@
 from .simulator import Simulator as Simulator
 from .synapses import Conv2d as Conv2d
 from .synapses import FullConn as FullConn
-from .synapses import NoDecay as NoDecay
 from .synapses import GeneralConnType as SynConnType
-
-from importlib.metadata import version
+from .synapses import NoDecay as NoDecay
 
 try:
     __version__ = version("paibox")
diff --git a/paibox/backend/conf_template.py b/paibox/backend/conf_template.py
index 7b6e3709..203bb735 100644
--- a/paibox/backend/conf_template.py
+++ b/paibox/backend/conf_template.py
@@ -23,7 +23,6 @@
     WeightPrecision,
     get_replication_id,
 )
-
 from paicorelib.framelib import types
 from paicorelib.framelib.frame_gen import OfflineFrameGen
 from paicorelib.framelib.utils import np2bin, np2npy, np2txt
diff --git a/paibox/base.py b/paibox/base.py
index 52dcecf5..7631a146 100644
--- a/paibox/base.py
+++ b/paibox/base.py
@@ -1,6 +1,7 @@
 import sys
-import numpy as np
 from typing import Any, ClassVar, Dict, List, Literal, Optional, Set, Tuple, Union
+
+import numpy as np
 from numpy.typing import NDArray
 
 if sys.version_info >= (3, 10):
@@ -14,7 +15,6 @@
 from .node import NodeDict, NodeList
 from .types import WeightType
 
-
 __all__ = []
 
 
diff --git a/paibox/synapses/__init__.py b/paibox/synapses/__init__.py
index 9b94bd66..4a249c18 100644
--- a/paibox/synapses/__init__.py
+++ b/paibox/synapses/__init__.py
@@ -1,8 +1,7 @@
-from .base import RIGISTER_MASTER_KEY_FORMAT
-from .base import SynSys
+from .base import RIGISTER_MASTER_KEY_FORMAT, SynSys
+from .synapses import Conv2d as Conv2d
 from .synapses import FullConn as FullConn
 from .synapses import NoDecay as NoDecay
-from .synapses import Conv2d as Conv2d
 from .transforms import GeneralConnType as GeneralConnType
 
 __all__ = ["Conv2d", "FullConn", "NoDecay", "GeneralConnType"]
diff --git a/paibox/synapses/base.py b/paibox/synapses/base.py
index 81bff250..28cb7bb1 100644
--- a/paibox/synapses/base.py
+++ b/paibox/synapses/base.py
@@ -1,7 +1,8 @@
-import numpy as np
-
 from typing import ClassVar, Literal, Optional, Tuple, Union
-from paicorelib import HwConfig, WeightPrecision as WP
+
+import numpy as np
+from paicorelib import HwConfig
+from paicorelib import WeightPrecision as WP
 
 from paibox.base import NeuDyn, SynSys
 from paibox.exceptions import ShapeError
@@ -10,15 +11,9 @@
 from paibox.types import DataArrayType, SynOutType, WeightType
 
 from .conv_utils import _fm_ndim2_check
-from .transforms import (
-    Conv2dForward,
-    GeneralConnType as GConnType,
-    OneToOne,
-    AllToAll,
-    Identity,
-    MaskedLinear,
-    Transform,
-)
+from .transforms import AllToAll, Conv2dForward
+from .transforms import GeneralConnType as GConnType
+from .transforms import Identity, MaskedLinear, OneToOne, Transform
 
 RIGISTER_MASTER_KEY_FORMAT = "{0}.output"
 
diff --git a/paibox/synapses/conv_utils.py b/paibox/synapses/conv_utils.py
index 1f2f9668..d104f872 100644
--- a/paibox/synapses/conv_utils.py
+++ b/paibox/synapses/conv_utils.py
@@ -1,13 +1,13 @@
-from itertools import repeat
 from functools import partial
+from itertools import repeat
 from typing import Any, Iterable, Literal, Tuple, TypeVar, Union
 
 import numpy as np
 from numpy.typing import NDArray
+
 from paibox.exceptions import ShapeError
 from paibox.types import SynOutType, WeightType
 
-
 T = TypeVar("T")
 
 _TupleAnyType = Union[T, Tuple[T, ...]]
diff --git a/paibox/synapses/synapses.py b/paibox/synapses/synapses.py
index 67718c5e..21d641f2 100644
--- a/paibox/synapses/synapses.py
+++ b/paibox/synapses/synapses.py
@@ -1,8 +1,8 @@
 import warnings
-import numpy as np
-
 from typing import Literal, Optional, Union
 
+import numpy as np
+
 from paibox.base import NeuDyn
 from paibox.neuron import Neuron
 from paibox.projection import InputProj
diff --git a/paibox/synapses/transforms.py b/paibox/synapses/transforms.py
index 94d22c7c..8696912c 100644
--- a/paibox/synapses/transforms.py
+++ b/paibox/synapses/transforms.py
@@ -5,11 +5,12 @@
 from numpy.typing import NDArray
 from paicorelib import WeightPrecision as WP
 
-from .conv_utils import _conv2d_faster, _conv2d_unroll, Size2Type
 from paibox.exceptions import ShapeError
 from paibox.types import DataArrayType, IntScalarType, SynOutType, WeightType
 from paibox.utils import is_shape
 
+from .conv_utils import Size2Type, _conv2d_faster, _conv2d_unroll
+
 __all__ = [
     "GeneralConnType",
     "OneToOne",
@@ -185,7 +186,7 @@ def __init__(self, conn_size: Size2Type, weights: DataArrayType) -> None:
 
     def __call__(self, x: np.ndarray, *args, **kwargs) -> SynOutType:
         """
-        NOTE: 
+        NOTE:
             - When weights is a scalar, the output is a scalar (sum * w) & repeated     \
                 `conn_size[1]` times.
             - When weights is a matrix, the output is the dot product of `x` & weights.
diff --git a/tests/backend/conftest.py b/tests/backend/conftest.py
index e1b64fe2..c973b930 100644
--- a/tests/backend/conftest.py
+++ b/tests/backend/conftest.py
@@ -426,12 +426,8 @@ def __init__(self):
         n_list.append(n3)
         self.n_list = n_list
 
-        self.s1 = pb.FullConn(
-            n_list[0], n_list[1], conn_type=pb.SynConnType.All2All
-        )
-        self.s2 = pb.FullConn(
-            n_list[1], n_list[2], conn_type=pb.SynConnType.All2All
-        )
+        self.s1 = pb.FullConn(n_list[0], n_list[1], conn_type=pb.SynConnType.All2All)
+        self.s2 = pb.FullConn(n_list[1], n_list[2], conn_type=pb.SynConnType.All2All)
 
         self.probe1 = pb.Probe(self.n_list[1], "output", name="n2_out")
 
diff --git a/tests/conftest.py b/tests/conftest.py
index 609e9d2b..67a47ae4 100644
--- a/tests/conftest.py
+++ b/tests/conftest.py
@@ -1,7 +1,8 @@
 from typing import Any, List, Optional, TypedDict
-from typing_extensions import NotRequired
+
 import numpy as np
 import pytest
+from typing_extensions import NotRequired
 
 import paibox as pb
 
diff --git a/tests/synapses/test_transforms.py b/tests/synapses/test_transforms.py
index a2451328..3e78fc6f 100644
--- a/tests/synapses/test_transforms.py
+++ b/tests/synapses/test_transforms.py
@@ -1,8 +1,8 @@
+from typing import Tuple
+
 import numpy as np
 import pytest
 
-from typing import Tuple
-
 from paibox.synapses.transforms import *
 from paibox.utils import shape2num
 

From 2809451ff8abd0e90ad682fa0b3fad81bf3650dd Mon Sep 17 00:00:00 2001
From: KafCoppelia <k740677208@gmail.com>
Date: Tue, 19 Mar 2024 16:45:26 +0800
Subject: [PATCH 28/68] =?UTF-8?q?=E2=9C=A8=20added=20Always1Neuron?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

---
 paibox/neuron/__init__.py |  8 ++------
 paibox/neuron/base.py     |  6 ++----
 paibox/neuron/neurons.py  | 29 +++++++++++++++++++++++++++++
 3 files changed, 33 insertions(+), 10 deletions(-)

diff --git a/paibox/neuron/__init__.py b/paibox/neuron/__init__.py
index 59b21939..dd441cd0 100644
--- a/paibox/neuron/__init__.py
+++ b/paibox/neuron/__init__.py
@@ -3,10 +3,6 @@
 from .neurons import LIF as LIF
 from .neurons import PhasicSpiking as PhasicSpiking
 from .neurons import TonicSpiking as TonicSpiking
+from .neurons import Always1Neuron as Always1Neuron
 
-__all__ = [
-    "IF",
-    "LIF",
-    "TonicSpiking",
-    "PhasicSpiking",
-]
+__all__ = ["IF", "LIF", "TonicSpiking", "PhasicSpiking", "Always1Neuron"]
diff --git a/paibox/neuron/base.py b/paibox/neuron/base.py
index f41315f3..8f3f65a3 100644
--- a/paibox/neuron/base.py
+++ b/paibox/neuron/base.py
@@ -357,7 +357,6 @@ def bias(self) -> int:
 class Neuron(MetaNeuron, NeuDyn):
     _excluded_vars = (
         "_vjt_init",
-        "vjt_pre",
         "vjt",
         "vj",
         "y",
@@ -445,7 +444,6 @@ def __init__(
 
         """Stateful attributes. Vector."""
         self.set_memory("_vjt", self.init_param(self._vjt_init).astype(np.int32))
-        self.set_memory("vjt_pre", self.init_param(self._vjt_init).astype(np.int32))
         self.set_memory("_inner_spike", self.init_param(0).astype(np.bool_))
 
         # Not supported for attributes in ANN mode
@@ -548,11 +546,11 @@ def copy(self) -> "Neuron":
 
     @property
     def shape_in(self) -> Tuple[int, ...]:
-        return self.varshape
+        return self._shape
 
     @property
     def shape_out(self) -> Tuple[int, ...]:
-        return self.varshape
+        return self._shape
 
     @property
     def num_in(self) -> int:
diff --git a/paibox/neuron/neurons.py b/paibox/neuron/neurons.py
index 2a1cfb73..7ee3cd51 100644
--- a/paibox/neuron/neurons.py
+++ b/paibox/neuron/neurons.py
@@ -153,3 +153,32 @@ def __init__(
             name=name,
             **kwargs,
         )
+
+
+class Always1Neuron(Neuron):
+    """This neuron will always output 1 as long as it starts working.
+    
+    FIXME There must be a forward synapse connected to it, otherwise    \
+        the backend will go wrong.
+    """
+
+    def __init__(
+        self,
+        shape: Shape,
+        *,
+        keep_shape: bool = False,
+        name: Optional[str] = None,
+        **kwargs,
+    ) -> None:
+        super().__init__(
+            shape,
+            reset_v=1,
+            leak_comparison=LCM.LEAK_BEFORE_COMP,
+            neg_thres_mode=NTM.MODE_SATURATION,
+            neg_threshold=0,
+            pos_threshold=0,
+            leak_v=(1 << 29) - 1,
+            keep_shape=keep_shape,
+            name=name,
+            **kwargs,
+        )

From 3a25fa5a9f4659a9ad382b853b0223bbe011caaf Mon Sep 17 00:00:00 2001
From: KafCoppelia <k740677208@gmail.com>
Date: Tue, 19 Mar 2024 16:50:23 +0800
Subject: [PATCH 29/68] =?UTF-8?q?=F0=9F=8E=A8=20updated=20typing=20&=20com?=
 =?UTF-8?q?ments?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

---
 paibox/base.py                |  2 ++
 paibox/mixin.py               |  4 ++--
 paibox/synapses/base.py       | 36 +++++++++++++++++++++--------------
 paibox/synapses/conv_utils.py | 26 ++++++++++++-------------
 paibox/synapses/synapses.py   | 18 +++++++++---------
 paibox/synapses/transforms.py |  6 +++---
 6 files changed, 51 insertions(+), 41 deletions(-)

diff --git a/paibox/base.py b/paibox/base.py
index 7631a146..1ee9f17d 100644
--- a/paibox/base.py
+++ b/paibox/base.py
@@ -233,10 +233,12 @@ def reset_state(self, *args, **kwargs):
 
     @property
     def shape_in(self) -> Tuple[int, ...]:
+        """Actual shape of input."""
         raise NotImplementedError
 
     @property
     def shape_out(self) -> Tuple[int, ...]:
+        """Actual shape of output."""
         raise NotImplementedError
 
     @property
diff --git a/paibox/mixin.py b/paibox/mixin.py
index 4759a70d..742ae763 100644
--- a/paibox/mixin.py
+++ b/paibox/mixin.py
@@ -209,8 +209,8 @@ def set_reset_value(self, name: str, init_value: Any) -> None:
 
     def __getattr__(self, name: str) -> Any:
         if "_memories" in self.__dict__:
-            _memories = self.__dict__.get("_memories")
-            if _memories is not None and name in _memories:
+            _memories = self.__dict__["_memories"]
+            if name in _memories:
                 return _memories[name]
 
         raise AttributeError(f"Attribute '{name}' not found!")
diff --git a/paibox/synapses/base.py b/paibox/synapses/base.py
index 28cb7bb1..3c3868c6 100644
--- a/paibox/synapses/base.py
+++ b/paibox/synapses/base.py
@@ -1,4 +1,4 @@
-from typing import ClassVar, Literal, Optional, Tuple, Union
+from typing import ClassVar, Optional, Tuple, Union
 
 import numpy as np
 from paicorelib import HwConfig
@@ -10,7 +10,7 @@
 from paibox.projection import InputProj
 from paibox.types import DataArrayType, SynOutType, WeightType
 
-from .conv_utils import _fm_ndim2_check
+from .conv_utils import _fm_ndim2_check, _Order3d, _KOrder4d
 from .transforms import AllToAll, Conv2dForward
 from .transforms import GeneralConnType as GConnType
 from .transforms import Identity, MaskedLinear, OneToOne, Transform
@@ -34,24 +34,32 @@ def __init__(
         source: Union[NeuDyn, InputProj],
         dest: NeuDyn,
     ) -> None:
-        self.source = source
-        self.dest = dest
+        self._source = source
+        self._dest = dest
+
+    @property
+    def source(self) -> Union[NeuDyn, InputProj]:
+        return self._source
+
+    @property
+    def dest(self) -> NeuDyn:
+        return self._dest
 
     @property
     def shape_in(self) -> Tuple[int, ...]:
-        return self.source.shape_out
+        return self._source.shape_out
 
     @property
     def shape_out(self) -> Tuple[int, ...]:
-        return self.dest.shape_in
+        return self._dest.shape_in
 
     @property
     def num_in(self) -> int:
-        return self.source.num_out
+        return self._source.num_out
 
     @property
     def num_out(self) -> int:
-        return self.dest.num_in
+        return self._dest.num_in
 
 
 class FullConnectedSyn(Synapses, SynSys):
@@ -61,8 +69,8 @@ def __init__(
         dest: NeuDyn,
         name: Optional[str] = None,
     ) -> None:
-        super().__init__(source, dest)
         super(Synapses, self).__init__(name)
+        super().__init__(source, dest)
 
         self.set_memory("_synout", np.zeros((self.num_out,), dtype=np.int32))
 
@@ -148,13 +156,13 @@ class Conv2dSyn(FullConnectedSyn):
 
     def __init__(
         self,
-        source: Union[Neuron, InputProj],
+        source: Union[NeuDyn, InputProj],
         dest: Neuron,
         kernel: np.ndarray,
         stride: Tuple[int, int],
         # padding: Tuple[int, int],
-        fm_order: Literal["CHW", "HWC"],
-        order: Literal["OIHW", "IOHW"],
+        fm_order: _Order3d,
+        order: _KOrder4d,
         name: Optional[str] = None,
     ) -> None:
         super().__init__(source, dest, name)
@@ -173,8 +181,8 @@ def __init__(
         out_channels, in_channels, kernel_h, kernel_w = _kernel.shape
 
         # C,H,W
-        in_ch, in_h, in_w = _fm_ndim2_check(source._shape, fm_order)
-        out_ch, out_h, out_w = _fm_ndim2_check(dest._shape, fm_order)
+        in_ch, in_h, in_w = _fm_ndim2_check(source.shape_out, fm_order)
+        out_ch, out_h, out_w = _fm_ndim2_check(dest.shape_out, fm_order)
 
         if in_ch != in_channels:
             raise ShapeError(f"Input channels mismatch: {in_ch} != {in_channels}")
diff --git a/paibox/synapses/conv_utils.py b/paibox/synapses/conv_utils.py
index d104f872..ff6fdb3d 100644
--- a/paibox/synapses/conv_utils.py
+++ b/paibox/synapses/conv_utils.py
@@ -14,15 +14,19 @@
 _Tuple1Type = Union[T, Tuple[T]]
 _Tuple2Type = Union[T, Tuple[T, T]]
 _Tuple3Type = Union[T, Tuple[T, T, T]]
-_Tuple4Type = Union[T, Tuple[T, T, T, T]]
 
 _SizeAnyType = _TupleAnyType[int]
 _Size1Type = _Tuple1Type[int]
 _Size2Type = _Tuple2Type[int]
 _Size3Type = _Tuple3Type[int]
-_Size4Type = _Tuple4Type[int]
 
+SizeAnyType = Tuple[int, ...]
 Size2Type = Tuple[int, int]
+Size3Type = Tuple[int, int, int]
+
+_Order2d = Literal["HW", "HW"]  # Feature map order in 2d
+_Order3d = Literal["CHW", "HWC"]  # Feature map order in 3d
+_KOrder4d = Literal["OIHW", "IOHW"]  # Kernel order
 
 
 def _ntuple(x, n: int) -> Tuple[Any, ...]:
@@ -38,16 +42,14 @@ def _ntuple(x, n: int) -> Tuple[Any, ...]:
 _quadruple = partial(_ntuple, n=4)
 
 
-def _fm_ndim1_check(
-    fm_shape: _TupleAnyType, fm_order: Literal["CHW", "HWC"]
-) -> Size2Type:
+def _fm_ndim1_check(fm_shape: SizeAnyType, fm_order: _Order2d) -> Size2Type:
     if len(fm_shape) < 1 or len(fm_shape) > 2:
-        raise ShapeError()
+        raise ShapeError(f"Expected shape of 1 or 2, but got {len(fm_shape)}")
 
     if len(fm_shape) == 1:
-        channels, l = (1, *fm_shape)
+        channels, l = (1,) + fm_shape
     else:
-        if fm_order is "CHW":
+        if fm_order is "HW":
             channels, l = fm_shape
         else:
             l, channels = fm_shape
@@ -55,14 +57,12 @@ def _fm_ndim1_check(
     return channels, l
 
 
-def _fm_ndim2_check(
-    fm_shape: _TupleAnyType, fm_order: Literal["CHW", "HWC"]
-) -> Tuple[int, int, int]:
+def _fm_ndim2_check(fm_shape: SizeAnyType, fm_order: _Order3d) -> Size3Type:
     if len(fm_shape) < 2 or len(fm_shape) > 3:
-        raise ShapeError()
+        raise ShapeError(f"Expected shape of 2 or 3, but got {len(fm_shape)}")
 
     if len(fm_shape) == 2:
-        channels, h, w = (1, *fm_shape)
+        channels, h, w = (1,) + fm_shape
     else:
         if fm_order is "CHW":
             channels, h, w = fm_shape
diff --git a/paibox/synapses/synapses.py b/paibox/synapses/synapses.py
index 21d641f2..cae80e32 100644
--- a/paibox/synapses/synapses.py
+++ b/paibox/synapses/synapses.py
@@ -1,5 +1,5 @@
 import warnings
-from typing import Literal, Optional, Union
+from typing import Optional, Union
 
 import numpy as np
 
@@ -9,7 +9,7 @@
 from paibox.types import DataArrayType
 
 from .base import Conv2dSyn, FullConnSyn
-from .conv_utils import _pair, _Size2Type
+from .conv_utils import _pair, _Size2Type, _Order3d, _KOrder4d
 from .transforms import GeneralConnType as GConnType
 
 __all__ = ["FullConn", "Conv2d"]
@@ -64,23 +64,23 @@ def __init__(
         *,
         stride: _Size2Type = 1,
         # padding: _Size2Type = 0,
-        fm_order: Literal["CHW", "HWC"] = "CHW",
-        kernel_order: Literal["OIHW", "IOHW"] = "OIHW",
+        fm_order: _Order3d = "CHW",
+        kernel_order: _KOrder4d = "OIHW",
         name: Optional[str] = None,
     ) -> None:
         """2d convolution synapses in fully-unrolled format.
 
         Arguments:
-            - source: source neuron(s). The dimensions need to be expressed explicitly as (C, H, W) or  \
-                (H, W, C). The feature map dimension order is specified by `fm_order`.
+            - source: source neuron(s). The dimensions need to be expressed explicitly as (C,H,W) or    \
+                (H,W,C). The feature map dimension order is specified by `fm_order`.
             - dest: destination neuron(s).
             - kernel: convolution kernel. Its dimension order must be (O,I,H,W) or (I,O,H,W), depending \
                 on the argument `kernel_order`.
             - stride: the step size of the kernel sliding. It can be a scalar or a tuple of 2 integers.
             - fm_order: dimension order of feature map. The order of input & output feature maps must be\
-                consistent, (C, H, W) or (H, W, C).
-            - kernel_order: dimension order of kernel, (O, I, H, W) or (I, O, H, W). (O, I, H, W) stands\
-                for (output channels, input channels, height, width).
+                consistent, (C,H,W) or (H,W,C).
+            - kernel_order: dimension order of kernel, (O,I,H,W) or (I,O,H,W). (O,I,H,W) stands for     \
+                (output channels, input channels, height, width).
             - name: name of the 2d convolution. Optional.
         """
         if fm_order not in ("CHW", "HWC"):
diff --git a/paibox/synapses/transforms.py b/paibox/synapses/transforms.py
index 8696912c..1c0b88ae 100644
--- a/paibox/synapses/transforms.py
+++ b/paibox/synapses/transforms.py
@@ -1,5 +1,5 @@
 from enum import Enum, auto, unique
-from typing import Literal, Type, Union
+from typing import Type, Union
 
 import numpy as np
 from numpy.typing import NDArray
@@ -9,7 +9,7 @@
 from paibox.types import DataArrayType, IntScalarType, SynOutType, WeightType
 from paibox.utils import is_shape
 
-from .conv_utils import Size2Type, _conv2d_faster, _conv2d_unroll
+from .conv_utils import Size2Type, _conv2d_faster, _conv2d_unroll, _Order3d
 
 __all__ = [
     "GeneralConnType",
@@ -245,7 +245,7 @@ def __init__(
         kernel: np.ndarray,
         stride: Size2Type,
         padding: Size2Type,
-        fm_order: Literal["CHW", "HWC"],
+        fm_order: _Order3d,
     ) -> None:
         self.in_shape = in_shape
         self.out_shape = out_shape

From 1499678e307e52ecd2812dd2b9d0a59b601b345f Mon Sep 17 00:00:00 2001
From: KafCoppelia <k740677208@gmail.com>
Date: Tue, 19 Mar 2024 17:06:02 +0800
Subject: [PATCH 30/68] =?UTF-8?q?=F0=9F=94=A8=20only=20supports=20deletion?=
 =?UTF-8?q?=20of=20synapses=20between=20two=20specified=20neurons?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

---
 paibox/network.py | 253 +++++++++++++++++++++++++++-------------------
 1 file changed, 147 insertions(+), 106 deletions(-)

diff --git a/paibox/network.py b/paibox/network.py
index ab314151..8892e3af 100644
--- a/paibox/network.py
+++ b/paibox/network.py
@@ -8,13 +8,14 @@
 from .collector import Collector
 from .exceptions import PAIBoxWarning, RegisterError
 from .mixin import Container
+from .neuron import Neuron
 from .node import NodeDict
 from .projection import InputProj, Projection
 from .synapses import RIGISTER_MASTER_KEY_FORMAT, SynSys
 
 __all__ = ["DynSysGroup", "Network"]
 
-ComponentsType: TypeAlias = Union[InputProj, NeuDyn, SynSys]
+ComponentsType: TypeAlias = Union[InputProj, Neuron, SynSys]
 
 
 class DynSysGroup(DynamicSys, Container):
@@ -32,16 +33,7 @@ def __init__(
         )
 
     def update(self, **kwargs) -> None:
-        """For a network, the operating nodes within it will be distributed according to the network level  \
-            where they are located. For I, S & N, if the network is a two-level nested network, it can be   \
-            divided into Ix, Sx, Nx and Iy, Sy, Ny, where x & y are two parts containing many operations.   \
-
-        TODO Prove that the operation sequence I->S->N can be divided into Ix->Sx->Nx->Iy->Sy->Ny & it has  \
-            nothing to do with the network topology.
-
-            The above expression cannot be completely established, and the condition needs to be met: the   \
-            dependent synapses of the neuron are in the same subgraph.
-        """
+        """Find nodes of the network recursively."""
         nodes = (
             self.nodes(include_self=False, find_recursive=True)
             .subset(DynamicSys)
@@ -77,11 +69,11 @@ def __call__(self, **kwargs) -> None:
         return self.update(**kwargs)
 
     def add_components(self, *implicit: DynamicSys, **explicit: DynamicSys) -> None:
-        """Add new components. When a component is passed in explicitly, its tag name \
-            can be specified. Otherwise `.name` will be used.
+        """Add new components. When a component is passed in explicitly, its tag name can   \
+            be specified. Otherwise `.name` will be used.
 
-        NOTE: After instantiated the components outside the `DynSysGroup`, you should \
-            call `add_components()` to actually add the new components to itself.
+        NOTE: After instantiated the components outside the `DynSysGroup`, you should call  \
+            `add_components()` to actually add the new components to itself.
         """
         for comp in implicit:
             setattr(self, comp.name, comp)
@@ -89,124 +81,165 @@ def add_components(self, *implicit: DynamicSys, **explicit: DynamicSys) -> None:
         for tag, comp in explicit.items():
             setattr(self, tag, comp)
 
-    def _remove_component(self, remove: DynamicSys) -> None:
-        """Remove a component in the network."""
-        for tag, obj in self.__dict__.items():
-            if obj is remove:
-                delattr(self, tag)
-                break
-
-        return None
+    def disconnect_syn(
+        self, target_syn: SynSys, exclude_source: bool = False
+    ) -> SynSys:
+        """Disconnect a synapse in the nwtwork.
 
-    def _disconnect_neudyn(
-        self,
-        neudyn_a: NeuDyn,
-        condition: Callable[[SynSys], bool],
-        neudyn_b: Optional[NeuDyn] = None,
-        remove_syn: bool = True,
-    ) -> List[SynSys]:
-        nodes = self.nodes(level=1, include_self=False).subset(DynamicSys).unique()
-
-        if neudyn_b is None:
-            self._assert_neudyn(nodes, neudyn_a)
-        else:
-            self._assert_neudyn(nodes, neudyn_a, neudyn_b)
-
-        target_syns = self._find_syn_to_unregi(nodes, condition)
-
-        if target_syns:
-            for syn in target_syns:
-                self._disconnect_syn(syn)
+        Args:
+            - target_syn: target synapse.
+            - exclude_source: whether to disconnect the source. If so, remove the synapse   \
+                from the network
+            
+        Returns: the disconnected synapse.
+        """
+        ret = target_syn.dest.unregister_master(
+            RIGISTER_MASTER_KEY_FORMAT.format(target_syn.name)
+        )
+        if ret is not target_syn:
+            raise RegisterError("unregister failed!")
 
-                # FIXME The disconnected synapses will not effect the simulation.
-                # However, it will effect the placement in the backend.
-                if remove_syn:
-                    self._remove_component(syn)
+        if not exclude_source:
+            self._remove_component(target_syn)
 
-            return target_syns
-        else:
-            warnings.warn("There is no synapse to unregister.", PAIBoxWarning)
-            return []
+        return target_syn
 
-    def disconnect_neudyn_from(
-        self, neudyn_a: NeuDyn, neudyn_b: NeuDyn, remove: bool = True
+    def disconnect_neuron_from(
+        self, neuron_a: Neuron, neuron_b: Neuron
     ) -> List[SynSys]:
-        """Disconnect synapses between `NeuDyn` A & B.
+        """Disconnect synapses between `Neuron` A & B and remove the synapses from the network.
 
         Args:
-            - neudyn_a: target `NeuDyn` A.
-            - neudyn_b: target `NeuDyn` B.
-            - remove: whether to remove the original synapses from the network.
+            - neuron_a: target neuron A.
+            - neuron_b: target neuron B.
 
-        Returns: the disconnected synapses.
+        Returns: the disconnected synapses in list.
         """
-        return self._disconnect_neudyn(
-            neudyn_a,
-            lambda syn: syn.source is neudyn_a and syn.dest is neudyn_b,
-            neudyn_b,
-            remove,
+        return self._disconn_neuron(
+            neuron_a,
+            lambda syn: syn.source is neuron_a and syn.dest is neuron_b,
+            neuron_b,
+            remove_syn=True,
         )
 
-    def diconnect_neudyn_succ(
-        self, neudyn: NeuDyn, remove: bool = True
-    ) -> List[SynSys]:
-        """Disconnect successor synapses of `neudyn`.
+    # Not sure about specific needs
+    # def diconnect_neuron_succ(self, neuron: Neuron) -> List[SynSys]:
+    #     """Disconnect successor synapses of `neuron`.
 
-        Args:
-            - neudyn: target `NeuDyn`.
-            - remove: whether to remove the original synapses from the network.
+    #     Args:
+    #         - neuron: target neuron.
+    #         - remove: whether to remove the original synapses from the network.
+    #         - new_source: only valid when `remove` is false.
 
-        Returns: the disconnected synapses.
-        """
-        return self._disconnect_neudyn(
-            neudyn, lambda syn: syn.source is neudyn, remove_syn=remove
-        )
+    #     Returns: the disconnected synapses.
+    #     """
+    #     return self._disconn_neuron(
+    #         neuron, lambda syn: syn.source is neuron, remove_syn=True
+    #     )
 
-    def diconnect_neudyn_pred(
-        self, neudyn: NeuDyn, remove: bool = True
-    ) -> List[SynSys]:
-        """Disconnect predecessor synapses of `neudyn`.
+    # def replace_neuron_succ(self, neuron: Neuron, new_source: Neuron) -> List[SynSys]:
+    #     """Replace the source of successor synapses of `neuron` with new one."""
+    #     disconn_syns = self._disconn_neuron(
+    #         neuron, lambda syn: syn.source is neuron, remove_syn=False
+    #     )
 
-        Args:
-            - neudyn: target `NeuDyn`.
-            - remove: whether to remove the original synapses from the network.
+    #     for syn in disconn_syns:
+    #         syn.source = new_source
 
-        Returns: the disconnected synapses.
-        """
-        return self._disconnect_neudyn(
-            neudyn, lambda syn: syn.dest is neudyn, remove_syn=remove
-        )
+    #     return disconn_syns
+
+    # def replace_neuron_pred(self, neuron: Neuron, new_source: Neuron) -> List[SynSys]:
+    #     """Replace the destination of predecessor synapses of `neuron` with new one.
+
+    #     Args:
+    #         - neuron: target neuron.
+    #         - remove: whether to remove the original synapses from the network.
 
-    def insert_neudyn(
+    #     Returns: the disconnected synapses.
+    #     """
+    #     disconn_syns = self._disconn_neuron(
+    #         neuron, lambda syn: syn.dest is neuron, remove_syn=False
+    #     )
+
+    #     for syn in disconn_syns:
+    #         syn.dest = new_source
+
+    #     return disconn_syns
+
+    def insert_between_neuron(
         self,
-        neudyn_a: NeuDyn,
-        neudyn_b: NeuDyn,
-        components_to_insert: Tuple[ComponentsType, ...],
+        neuron_a: Neuron,
+        neuron_b: Neuron,
+        cpn_to_insert: Tuple[ComponentsType, ...],
         replace: bool = True,
-        remove: bool = True,
     ) -> List[SynSys]:
-        """Insert new components between `NeuDyn` A & B.
+        """Insert new components between `Neuron` A & B.
 
         Args:
-            - neudyn_a: target `NeuDyn` A.
-            - neudyn_b: target `NeuDyn` B.
-            - components_to_insert: new components to insert between `neudyn_a` & `neudyn_b`.
+            - neuron_a: target neuron A.
+            - neuron_b: target neuron B.
+            - cpn_to_insert: components to insert between `neuron_a` & `neuron_b`.
             - replace: whether to disconnect the original synapses. Default is `True`.
-            - remove: whether to remove the original synapses from the network. Valid only when `replace` is `True`.
 
-        Returns: the disconnected synapses.
+        Returns: the disconnected synapses in list.
         """
         if replace:
-            removed_syn = self.disconnect_neudyn_from(neudyn_a, neudyn_b, remove=remove)
+            removed_syn = self.disconnect_neuron_from(neuron_a, neuron_b)
         else:
             removed_syn = []
 
-        self.add_components(*components_to_insert)
+        self.add_components(*cpn_to_insert)
 
         return removed_syn
 
+    def _remove_component(self, remove: DynamicSys) -> None:
+        """Remove a component in the network."""
+        for tag, obj in self.__dict__.items():
+            if obj is remove:
+                delattr(self, tag)
+                break
+
+        return None
+
+    def _disconn_neuron(
+        self,
+        neuron_a: Neuron,
+        condition: Callable[[SynSys], bool],
+        neuron_b: Optional[Neuron] = None,
+        remove_syn: bool = True,
+    ) -> List[SynSys]:
+        nodes = (
+            self.nodes(include_self=False, find_recursive=True)
+            .subset(DynamicSys)
+            .unique()
+        )
+
+        if neuron_b is None:
+            self._assert_neuron(nodes, neuron_a)
+        else:
+            self._assert_neuron(nodes, neuron_a, neuron_b)
+
+        target_syns = self._find_syn_to_disconn(nodes, condition)
+
+        if target_syns:
+            for syn in target_syns:
+                self._disconn_syn(syn)
+
+                # The disconnected synapses will not effect the simulation, but will
+                # effect the placement in the backend.
+                # If the disconnected synapses aren't removed from the network, do cleaning
+                # before the compilation in the backend.
+                # TODO Add a pre-processing step before the compilation.
+                if remove_syn:
+                    self._remove_component(syn)
+
+            return target_syns
+        else:
+            warnings.warn("there is no synapses to disconnect.", PAIBoxWarning)
+            return []
+
     @staticmethod
-    def _find_syn_to_unregi(
+    def _find_syn_to_disconn(
         nodes: Collector, condition: Callable[[SynSys], bool]
     ) -> List[SynSys]:
         syns = []
@@ -218,19 +251,27 @@ def _find_syn_to_unregi(
         return syns
 
     @staticmethod
-    def _disconnect_syn(target_syn: SynSys) -> None:
+    def _disconn_syn(target_syn: SynSys) -> None:
+        ret = target_syn.dest.unregister_master(
+            RIGISTER_MASTER_KEY_FORMAT.format(target_syn.name)
+        )
+        if ret is not target_syn:
+            raise RegisterError("unregister failed!")
+
+    @staticmethod
+    def _disconn_succ_syn(target_syn: SynSys) -> None:
         ret = target_syn.dest.unregister_master(
             RIGISTER_MASTER_KEY_FORMAT.format(target_syn.name)
         )
         if ret is not target_syn:
-            raise RegisterError("Unregister failed!")
+            raise RegisterError("unregister failed!")
 
     @staticmethod
-    def _assert_neudyn(nodes: Collector, *neudyns: NeuDyn) -> None:
-        neu_dyns = nodes.subset(NeuDyn)
+    def _assert_neuron(nodes: Collector, *neurons: Neuron) -> None:
+        neu_dyns = nodes.subset(Neuron)
 
-        if any(neudyn not in neu_dyns.values() for neudyn in neudyns):
-            raise ValueError("Not all NeuDyn found in the network.")
+        if any(neuron not in neu_dyns.values() for neuron in neurons):
+            raise ValueError("not all neurons found in the network.")
 
 
 Network: TypeAlias = DynSysGroup

From 4b4060dd3990f638d332573887b406cf06616bd8 Mon Sep 17 00:00:00 2001
From: KafCoppelia <k740677208@gmail.com>
Date: Tue, 19 Mar 2024 17:06:33 +0800
Subject: [PATCH 31/68] =?UTF-8?q?=E2=9C=85=20added=20tests=20&=20sync=20ch?=
 =?UTF-8?q?anges?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

---
 tests/neuron/test_neurons.py    | 28 +++++++++++++-
 tests/synapses/test_synapses.py | 25 +++++++++++++
 tests/test_network.py           | 66 +++++++++------------------------
 tests/test_projection.py        |  2 -
 4 files changed, 68 insertions(+), 53 deletions(-)

diff --git a/tests/neuron/test_neurons.py b/tests/neuron/test_neurons.py
index 7942c274..002e4cc1 100644
--- a/tests/neuron/test_neurons.py
+++ b/tests/neuron/test_neurons.py
@@ -254,8 +254,8 @@ def test_neuron_instance(shape):
     # keep_shape = False
     n2 = pb.TonicSpiking(shape, 5)
 
-    assert n2.shape_in == as_shape(shape2num(shape))
-    assert n2.shape_out == as_shape(shape2num(shape))
+    assert n2.shape_in == as_shape(shape)
+    assert n2.shape_out == as_shape(shape)
     assert len(n2) == shape2num(shape)
 
 
@@ -412,3 +412,27 @@ def test_tick_attr_behavior(self, monkeypatch, build_Net3):
         sim.reset()
 
         # TODO can add new test items here
+
+    def test_Always1Neuron_behavior(self):
+        class Net(pb.Network):
+            def __init__(self):
+                super().__init__()
+                self.inp1 = pb.InputProj(input=None, shape_out=(1,))
+
+                self.n1 = pb.Always1Neuron(shape=(1,), tick_wait_start=1)
+                self.s1 = pb.FullConn(
+                    self.inp1, self.n1, weights=0, conn_type=pb.SynConnType.One2One
+                )
+
+                self.probe1 = pb.Probe(self.n1, "spike")
+
+        net = Net()
+        sim = pb.Simulator(net)
+
+        for i in range(20):
+            net.inp1.input = np.random.randint(0, 2, size=(1,), dtype=np.bool_)
+            sim.run(1)
+
+        assert np.array_equal(
+            sim.data[net.probe1], 20 * [np.ones((1,), dtype=np.bool_)]
+        )
diff --git a/tests/synapses/test_synapses.py b/tests/synapses/test_synapses.py
index c851dd3c..44294871 100644
--- a/tests/synapses/test_synapses.py
+++ b/tests/synapses/test_synapses.py
@@ -284,3 +284,28 @@ def test_Conv2d_instance(self):
             in_channels * shape2num(in_shape),
             out_channels * shape2num(out_shape),
         )
+
+    def test_Conv2d_inchannel_omitted(self):
+        in_shape = (32, 32)
+        kernel_size = (5, 5)
+        stride = 2
+        out_shape = ((32 - 5) // 2 + 1, (32 - 5) // 2 + 1)
+        in_channels = 1  # omit it
+        out_channels = 4
+        korder = "IOHW"
+
+        n1 = pb.IF(in_shape, 3)  # HW, (in_channels=1)
+        n2 = pb.IF((out_channels,) + out_shape, 3)
+
+        weight = np.random.randint(
+            -128, 128, size=(in_channels, out_channels) + kernel_size, dtype=np.int8
+        )
+        s1 = pb.Conv2d(
+            n1, n2, weight, stride=stride, fm_order="CHW", kernel_order=korder
+        )
+
+        assert s1.num_in == in_channels * shape2num(in_shape)
+        assert s1.connectivity.shape == (
+            in_channels * shape2num(in_shape),
+            out_channels * shape2num(out_shape),
+        )
diff --git a/tests/test_network.py b/tests/test_network.py
index c760886b..c7d646da 100644
--- a/tests/test_network.py
+++ b/tests/test_network.py
@@ -133,7 +133,7 @@ class TestNetwork_Components_Oprations:
     def test_Collector_operations(self):
         s1 = pb.base.DynamicSys(name="s1")
         s2 = pb.InputProj(1, shape_out=1, name="s2")
-        s3 = pb.network.NeuDyn(name="s3")
+        s3 = pb.base.NeuDyn(name="s3")
         s4 = pb.DynSysGroup(s1, s2, name="s4")
 
         g1 = pb.DynSysGroup(s1, s2, s3, name="g1")
@@ -159,8 +159,8 @@ def test_Collector_operations(self):
         assert len(g4_nodes.unique()) == 2
 
         assert len(g3_nodes.exclude(pb.projection.Projection)) == 1
-        assert len(g1_nodes.not_subset(pb.network.NeuDyn)) == 2
-        assert len(g1_nodes.include(pb.network.NeuDyn, pb.projection.Projection)) == 2
+        assert len(g1_nodes.not_subset(NeuDyn)) == 2
+        assert len(g1_nodes.include(NeuDyn, pb.projection.Projection)) == 2
 
     def test_add_components(self, build_NotNested_Net_Exp):
         net: pb.Network = build_NotNested_Net_Exp
@@ -168,9 +168,6 @@ def test_add_components(self, build_NotNested_Net_Exp):
         s1 = pb.FullConn(net.n1, n3, conn_type=pb.SynConnType.All2All)
         s2 = pb.FullConn(net.n2, n3, conn_type=pb.SynConnType.All2All)
 
-        with pytest.raises(ValueError):
-            net.diconnect_neudyn_succ(n3)
-
         # Add extra components into the network after initialization
         setattr(net, n3.name, n3)  # key is 'LIF_0'
         # Or added by user
@@ -184,29 +181,28 @@ def test_add_components(self, build_NotNested_Net_Exp):
         net.add_components(s2)
         assert getattr(net, s2.name, False)
 
-    def test_disconnect_neudyn_from(self, build_Network_with_container):
+    def test_disconnect_neuron_from(self, build_Network_with_container):
         net: pb.Network = build_Network_with_container
 
         # Disconnet the n_list[0] -> s1 -> n_list[1]
         # Nothing to disconnect so a warning is raised
         with pytest.warns(PAIBoxWarning):
-            removed = net.disconnect_neudyn_from(
-                net.n_list[0], net.n_list[2], remove=False
-            )
+            removed = net.disconnect_neuron_from(net.n_list[0], net.n_list[2])
             assert removed == []
 
         nodes = net.nodes(level=1, include_self=False).subset(DynamicSys).unique()
         assert net.n_list[0].name in nodes
 
         # Remove the target synapse
-        removed = net.disconnect_neudyn_from(net.n_list[0], net.n_list[1], remove=True)
+        removed = net.disconnect_neuron_from(net.n_list[0], net.n_list[1])
         assert len(removed) == 1
         assert not getattr(net, "s1", False)
 
-    def test_disconnect_neudyn_succ(self, build_multi_inodes_onodes):
+    @pytest.mark.skip("Not implemented")
+    def test_disconnect_neuron_succ(self, build_multi_inodes_onodes):
         net: pb.Network = build_multi_inodes_onodes
 
-        removed = net.diconnect_neudyn_succ(net.n1, remove=True)
+        removed = net.diconnect_neuron_succ(net.n1)
 
         assert len(removed) == 2
         assert not getattr(net, "s2", False)
@@ -214,10 +210,11 @@ def test_disconnect_neudyn_succ(self, build_multi_inodes_onodes):
         assert getattr(net, "s1", False)
         assert getattr(net, "s3", False)
 
-    def test_disconnect_neudyn_pred(self, build_multi_inodes_onodes):
+    @pytest.mark.skip("Not implemented")
+    def test_replace_neuron_pred(self, build_multi_inodes_onodes):
         net: pb.Network = build_multi_inodes_onodes
 
-        removed = net.diconnect_neudyn_pred(net.n1, remove=True)
+        removed = net.replace_neuron_pred(net.n1)
 
         assert len(removed) == 2
         assert not getattr(net, "s1", False)
@@ -225,7 +222,7 @@ def test_disconnect_neudyn_pred(self, build_multi_inodes_onodes):
         assert getattr(net, "s2", False)
         assert getattr(net, "s4", False)
 
-    def test_insert_neudyn(self, build_Network_with_container):
+    def test_insert_between_neuron(self, build_Network_with_container):
         net: pb.Network = build_Network_with_container
 
         # Insert n3 between n_list[0] & n_list[1]
@@ -238,12 +235,11 @@ def test_insert_neudyn(self, build_Network_with_container):
         )
 
         # Replace s1 with s_insert1->n_insert->s_insert2
-        net.insert_neudyn(
+        net.insert_between_neuron(
             net.n_list[0],
             net.n_list[1],
             (n_insert, s_insert1, s_insert2),
             replace=True,
-            remove=False,
         )
 
         nodes = net.nodes(level=1, include_self=False).subset(DynamicSys).unique()
@@ -252,42 +248,14 @@ def test_insert_neudyn(self, build_Network_with_container):
         assert s_insert2.name in nodes
         assert getattr(net, f"{s_insert1.name}", False)
 
-        assert getattr(net, "s1", False)  # s1 is still in the network
-        assert net.s1.name in nodes
+        assert not getattr(net, "s1", False)  # s1 ie removed from the network
 
         assert getattr(net, f"{s_insert2.name}", False) in list(
             net.n_list[1].master_nodes.values()
         )
 
-    @pytest.mark.skip(reason="Not implemented")
-    def test_Subnets(self, build_Network_with_subnet):
-        net = build_Network_with_subnet
-
-        # 1. Relative + include_self == True, level 1
-        nodes1 = (
-            net.nodes(method="absolute", level=1, include_self=False)
-            .subset(DynamicSys)
-            .unique()
-        )
-        nodes1_sub = nodes1.subset(NeuDyn)
-
-        # 2. Relative + include_self == True, level 2
-        nodes2 = (
-            net.nodes(method="absolute", level=2, include_self=False)
-            .subset(DynamicSys)
-            .unique()
-        )
-
-        nodes3 = (
-            net.nodes(method="absolute", level=7, include_self=False)
-            .subset(DynamicSys)
-            .unique()
-        )
-
-        print()
-
 
-@pytest.mark.skip(reason="'Sequential is not used'")
+@pytest.mark.skip(reason="'Sequential' is not used")
 def test_Sequential_build():
     n1 = pb.TonicSpiking(10, fire_step=3)
     n2 = pb.TonicSpiking(10, fire_step=5)
@@ -311,7 +279,7 @@ def __init__(self):
     assert len(nodes2) == 3
 
 
-@pytest.mark.skip(reason="'Sequential is not used'")
+@pytest.mark.skip(reason="'Sequential' is not used")
 def test_Sequential_getitem():
     n1 = pb.TonicSpiking(10, fire_step=3, name="n1")
     n2 = pb.TonicSpiking(10, fire_step=5, name="n2")
diff --git a/tests/test_projection.py b/tests/test_projection.py
index 9fca4a27..fc8c47d4 100644
--- a/tests/test_projection.py
+++ b/tests/test_projection.py
@@ -101,8 +101,6 @@ def test_passing_args_through_run(self):
         def fakeout_with_args(t, bias, *args, **kwargs):
             return np.ones((10, 10), dtype=np.int8) * bias
 
-        FRONTEND_ENV.clear_ctx("bias")
-
         inp = pb.InputProj(
             input=fakeout_with_args, shape_out=(10, 10), keep_shape=False
         )

From ac6fc32bdaf1c0e626cd501128565baf1695a944 Mon Sep 17 00:00:00 2001
From: KafCoppelia <k740677208@gmail.com>
Date: Tue, 19 Mar 2024 17:27:10 +0800
Subject: [PATCH 32/68] =?UTF-8?q?=F0=9F=93=9D=20updated=20toml,=20todo=20&?=
 =?UTF-8?q?=20changelog?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

---
 CHANGELOG.md   |  6 +++++-
 README.md      |  2 +-
 TODO.md        |  2 --
 poetry.lock    |  6 +++---
 pyproject.toml | 16 +++++++++++++++-
 5 files changed, 24 insertions(+), 8 deletions(-)

diff --git a/CHANGELOG.md b/CHANGELOG.md
index 1065e964..f948a9eb 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -13,4 +13,8 @@
 
 - 支持无限嵌套深度的网络
 - 支持全展开2D卷积算子构建与部署（`padding` 不支持）
-- 修复当 `keep_shape=True` 时，，神经元状态变量在运行时尺寸错误
+- 修复当 `keep_shape=True` 时，神经元状态变量在运行时尺寸错误
+
+## v1.0.0a6
+
+- 新增 `Always1Neuron` 神经元，该神经元将在工作期间持续输出1，不得单独存在，需存在前向突触与其连接。
diff --git a/README.md b/README.md
index 91c7f215..a5ce6bf5 100644
--- a/README.md
+++ b/README.md
@@ -8,7 +8,7 @@
     <a href="https://github.com/PAICookers/PAIBox/blob/master/pyproject.toml">
         <img src="https://img.shields.io/pypi/pyversions/paibox">
     </a>
-    <a href="https://github.com/PAICookers/PAIBox/releases/tag/v1.0.0a5">
+    <a href="https://github.com/PAICookers/PAIBox/releases/tag/v1.0.0a6">
         <img src="https://img.shields.io/github/v/release/PAICookers/PAIBox?include_prereleases&color=orange">
     </a>
     <a href="https://www.codefactor.io/repository/github/PAICookers/PAIBox">
diff --git a/TODO.md b/TODO.md
index 66e86fc6..f21de321 100644
--- a/TODO.md
+++ b/TODO.md
@@ -45,5 +45,3 @@
   - 目前仅支持芯片的SNN模式。要想支持ANN模式，前端上需要支持ANN模式的算理。同时，ANN/SNN模式是物理核的行为，因此当网络拓扑中同时存在两种模式的神经元时，需要以此为约束条件，从而影响分组结果（类似第6点。例如，同为ANN模式下的不同神经元可被分在同一组）
 - [ ] 神经元计算模型随机性仿真
   - 基于硬件神经元计算机制，实现带有部分随机数的计算机制。并考虑与硬件的实现相接近的程度（能否接近实现与硬件一致的随机数发生行为）
-- [ ] 网络节点间自定义延迟( `tick_relative` )尝试ringbuffer结构优化
-  - 目前使用的delay_register方案，将在每个神经元组后方申请较大内存，用于存放delay至后继节点的数据。可尝试使用ringbuffer的思路对此结构进行优化。
diff --git a/poetry.lock b/poetry.lock
index af10a356..d21a7d00 100644
--- a/poetry.lock
+++ b/poetry.lock
@@ -77,13 +77,13 @@ reference = "tsinghua"
 
 [[package]]
 name = "fsspec"
-version = "2024.2.0"
+version = "2024.3.1"
 description = "File-system specification"
 optional = true
 python-versions = ">=3.8"
 files = [
-    {file = "fsspec-2024.2.0-py3-none-any.whl", hash = "sha256:817f969556fa5916bc682e02ca2045f96ff7f586d45110fcb76022063ad2c7d8"},
-    {file = "fsspec-2024.2.0.tar.gz", hash = "sha256:b6ad1a679f760dda52b1168c859d01b7b80648ea6f7f7c7f5a8a91dc3f3ecb84"},
+    {file = "fsspec-2024.3.1-py3-none-any.whl", hash = "sha256:918d18d41bf73f0e2b261824baeb1b124bcf771767e3a26425cd7dec3332f512"},
+    {file = "fsspec-2024.3.1.tar.gz", hash = "sha256:f39780e282d7d117ffb42bb96992f8a90795e4d0fb0f661a70ca39fe9c43ded9"},
 ]
 
 [package.extras]
diff --git a/pyproject.toml b/pyproject.toml
index b1bef1e7..5c3fae22 100644
--- a/pyproject.toml
+++ b/pyproject.toml
@@ -1,6 +1,6 @@
 [tool.poetry]
 name = "paibox"
-version = "1.0.0a5"
+version = "1.0.0a6"
 description = "New toolbox of PAICORE 2.0."
 authors = ["Ziru Pan <zrpan@stu.pku.edu.cn>"]
 maintainers = ["Ziru Pan <zrpan@stu.pku.edu.cn>"]
@@ -10,6 +10,20 @@ repository = "https://github.com/PAICookers/PAIBox"
 homepage = "https://github.com/PAICookers/PAIBox"
 documentation = "https://github.com/PAICookers/PAIBox#readme"
 keywords = ["PAICORE 2.0", "PAIBox", "Toolbox"]
+classifiers = [
+    "Intended Audience :: Science/Research",
+    "License :: OSI Approved :: GNU General Public License v3 or later (GPLv3+)",
+    "Operating System :: OS Independent",
+    "Programming Language :: Python :: 3 :: Only",
+    "Programming Language :: Python :: 3.8",
+    "Programming Language :: Python :: 3.9",
+    "Programming Language :: Python :: 3.10",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+    "Topic :: Scientific/Engineering :: Artificial Intelligence",
+    "Topic :: Software Development :: Build Tools",
+    "Topic :: Software Development :: Libraries",
+]
 packages = [{ include = "paibox" }]
 
 # Includes the document

From 3358b509dd962158182cdc0269435fd2bb110f6a Mon Sep 17 00:00:00 2001
From: "pre-commit-ci[bot]"
 <66853113+pre-commit-ci[bot]@users.noreply.github.com>
Date: Tue, 19 Mar 2024 09:35:09 +0000
Subject: [PATCH 33/68] :rotating_light: auto fix by pre-commit hooks

---
 paibox/network.py           | 2 +-
 paibox/neuron/__init__.py   | 2 +-
 paibox/neuron/neurons.py    | 2 +-
 paibox/synapses/base.py     | 2 +-
 paibox/synapses/synapses.py | 2 +-
 5 files changed, 5 insertions(+), 5 deletions(-)

diff --git a/paibox/network.py b/paibox/network.py
index 8892e3af..c12b9761 100644
--- a/paibox/network.py
+++ b/paibox/network.py
@@ -90,7 +90,7 @@ def disconnect_syn(
             - target_syn: target synapse.
             - exclude_source: whether to disconnect the source. If so, remove the synapse   \
                 from the network
-            
+
         Returns: the disconnected synapse.
         """
         ret = target_syn.dest.unregister_master(
diff --git a/paibox/neuron/__init__.py b/paibox/neuron/__init__.py
index dd441cd0..9fe79ea0 100644
--- a/paibox/neuron/__init__.py
+++ b/paibox/neuron/__init__.py
@@ -1,8 +1,8 @@
 from .base import Neuron
 from .neurons import IF as IF
 from .neurons import LIF as LIF
+from .neurons import Always1Neuron as Always1Neuron
 from .neurons import PhasicSpiking as PhasicSpiking
 from .neurons import TonicSpiking as TonicSpiking
-from .neurons import Always1Neuron as Always1Neuron
 
 __all__ = ["IF", "LIF", "TonicSpiking", "PhasicSpiking", "Always1Neuron"]
diff --git a/paibox/neuron/neurons.py b/paibox/neuron/neurons.py
index 7ee3cd51..96eaad0e 100644
--- a/paibox/neuron/neurons.py
+++ b/paibox/neuron/neurons.py
@@ -157,7 +157,7 @@ def __init__(
 
 class Always1Neuron(Neuron):
     """This neuron will always output 1 as long as it starts working.
-    
+
     FIXME There must be a forward synapse connected to it, otherwise    \
         the backend will go wrong.
     """
diff --git a/paibox/synapses/base.py b/paibox/synapses/base.py
index 3c3868c6..3fcf8712 100644
--- a/paibox/synapses/base.py
+++ b/paibox/synapses/base.py
@@ -10,7 +10,7 @@
 from paibox.projection import InputProj
 from paibox.types import DataArrayType, SynOutType, WeightType
 
-from .conv_utils import _fm_ndim2_check, _Order3d, _KOrder4d
+from .conv_utils import _fm_ndim2_check, _KOrder4d, _Order3d
 from .transforms import AllToAll, Conv2dForward
 from .transforms import GeneralConnType as GConnType
 from .transforms import Identity, MaskedLinear, OneToOne, Transform
diff --git a/paibox/synapses/synapses.py b/paibox/synapses/synapses.py
index cae80e32..5f2f6912 100644
--- a/paibox/synapses/synapses.py
+++ b/paibox/synapses/synapses.py
@@ -9,7 +9,7 @@
 from paibox.types import DataArrayType
 
 from .base import Conv2dSyn, FullConnSyn
-from .conv_utils import _pair, _Size2Type, _Order3d, _KOrder4d
+from .conv_utils import _KOrder4d, _Order3d, _pair, _Size2Type
 from .transforms import GeneralConnType as GConnType
 
 __all__ = ["FullConn", "Conv2d"]

From 79afc93a30b2d28954e3f7b7c1d02d916fab2698 Mon Sep 17 00:00:00 2001
From: KafCoppelia <k740677208@gmail.com>
Date: Wed, 20 Mar 2024 11:39:47 +0800
Subject: [PATCH 34/68] =?UTF-8?q?=E2=9C=A8=20added=20latency=20encoder=20&?=
 =?UTF-8?q?=20simplified=20encoder=20classes?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

---
 paibox/simulator/__init__.py |   3 +-
 paibox/simulator/encoder.py  | 108 +++++++++++++++++++----------------
 2 files changed, 61 insertions(+), 50 deletions(-)

diff --git a/paibox/simulator/__init__.py b/paibox/simulator/__init__.py
index 2c8834a9..04dc9b2b 100644
--- a/paibox/simulator/__init__.py
+++ b/paibox/simulator/__init__.py
@@ -1,6 +1,5 @@
+from .encoder import LatencyEncoder as LatencyEncoder
 from .encoder import PeriodicEncoder as PeriodicEncoder
 from .encoder import PoissonEncoder as PoissonEncoder
 from .probe import Probe as Probe
 from .simulator import Simulator as Simulator
-
-__all__ = ["PeriodicEncoder", "PoissonEncoder", "Probe", "Simulator"]
diff --git a/paibox/simulator/encoder.py b/paibox/simulator/encoder.py
index 669bdd85..a2c82257 100644
--- a/paibox/simulator/encoder.py
+++ b/paibox/simulator/encoder.py
@@ -1,69 +1,51 @@
-from abc import abstractmethod
-from typing import Optional, Tuple
+import math
+from typing import Literal, Optional
 
 import numpy as np
+from paibox.mixin import StatusMemory
+from paibox.types import SpikeType
 
-from paibox.base import DynamicSys
-from paibox.types import Shape
-from paibox.utils import as_shape, shape2num
-
-__all__ = ["PeriodicEncoder", "PoissonEncoder"]
+__all__ = ["LatencyEncoder", "PeriodicEncoder", "PoissonEncoder"]
 
 MAXSEED = np.iinfo(np.uint32).max
 MAXINT = np.iinfo(np.int32).max
 
 
-class Encoder(DynamicSys):
-    def __init__(
-        self,
-        shape_out: Shape = (0,),
-        *,
-        seed: Optional[int] = None,
-        name: Optional[str] = None,
-    ) -> None:
-        self._shape = as_shape(shape_out)
-
-        super().__init__(name)
+class Encoder:
+    def __init__(self, seed: Optional[int] = None) -> None:
         self.rng = self._get_rng(seed)
 
     def _get_rng(self, seed: Optional[int] = None) -> np.random.RandomState:
         _seed = np.random.randint(MAXINT) if seed is None else seed
         return np.random.RandomState(_seed)
 
-    @property
-    def num_out(self) -> int:
-        return shape2num(self._shape)
-
-    @property
-    def shape_in(self) -> Tuple[int, ...]:
-        return (0,)
-
-    @property
-    def shape_out(self) -> Tuple[int, ...]:
-        return self._shape
+    def __call__(self, x: np.ndarray, *args, **kwargs) -> SpikeType:
+        raise NotImplementedError
 
 
 class StatelessEncoder(Encoder):
     pass
 
 
-class StatefulEncoder(Encoder):
-    def __init__(self, T: int, shape_out: Shape, **kwargs) -> None:
-        super().__init__(shape_out, **kwargs)
+class StatefulEncoder(Encoder, StatusMemory):
+    def __init__(self, T: int, seed: Optional[int] = None) -> None:
+        super().__init__(seed)
+        super(Encoder, self).__init__()
 
         if T < 1:
-            raise ValueError(f"T must be positive, but got {T}")
+            raise ValueError(f"'T' must be positive, but got {T}")
 
         self.T = T
         self.set_memory("spike", None)
         self.set_memory("t", 0)
 
-    def __call__(self, x: Optional[np.ndarray] = None, *args, **kwargs) -> np.ndarray:
+    def __call__(self, x: Optional[np.ndarray] = None, *args, **kwargs) -> SpikeType:
+        # If there is no encoded spike but there is an input, encode the input
         if self.spike is None:
             if x is None:
-                raise ValueError("Input must be given if spike is None")
+                raise ValueError("input must be given if spike is None")
 
-            self.single_step_encode(x)
+            self.encode(x)
 
         t = self.t
         self.t += 1
@@ -73,8 +55,8 @@ def __call__(self, x: Optional[np.ndarray] = None, *args, **kwargs) -> np.ndarra
 
         return self.spike[t]
 
-    @abstractmethod
-    def single_step_encode(self, x: np.ndarray):
+    def encode(self, x: np.ndarray) -> None:
+        """Encoding function. Called only if there is no encoded spike."""
         raise NotImplementedError
 
 
@@ -83,24 +65,54 @@ def __init__(self, spike: np.ndarray, **kwargs) -> None:
         """Periodic encoder.
 
         Args:
-            - spike: the input spike. Encode when instantiate itself. \
-                T = `.shape[0]` & shape_out = `.shape[1]`.
+            - spike: the spike to be encoded. Encode at instantiation, where `T=shape[0]` & `shape_out=shape[1]`.
         """
-        super().__init__(spike.shape[0], spike.shape[1], **kwargs)
+        super().__init__(spike.shape[0], **kwargs)
         self.spike = spike
 
+    def encode(self, x: np.ndarray) -> None:
+        self.spike = x
+        self.T = x.shape[0]
+
+
+class LatencyEncoder(StatefulEncoder):
+    def __init__(self, T: int, encoding_func: Literal["linear", "log"]) -> None:
+        """Latency encoder.
+
+        Args:
+            - T: encoding timestep.
+            - encoding_func: encoding function. It can be 'log' or 'linear'.
+
+        NOTE: See details at https://spikingjelly.readthedocs.io/zh-cn/latest/activation_based/2_encoding.html#id5
+        """
+        super().__init__(T)
+
+        if encoding_func == "log":
+            self.alpha = math.exp(T - 1) - 1
+        elif encoding_func != "linear":  # `alpha` is not used in method 'linear'.
+            raise ValueError("encoding function must be 'log' or 'linear'")
+
+        self.enc_func = encoding_func
+
+    def encode(self, x: np.ndarray) -> None:
+        if self.enc_func == "log":
+            t_f = (self.T - 1 - np.log(self.alpha * x + 1)).round().astype(np.int64)
+        else:
+            t_f = ((self.T - 1.0) * (1.0 - x)).round().astype(np.int64)
+
+        indices = t_f.flatten()
+        spike = np.eye(self.T, dtype=np.bool_)[indices]
+        # [*, T] -> [T, *]
+        self.spike = np.moveaxis(spike, -1, 0)
+
 
 class PoissonEncoder(StatelessEncoder):
     def __init__(self, seed: Optional[int] = None, **kwargs) -> None:
         """Poisson encoder.
 
-        Args:
-            - seed: the random seed.
-
-        NOTE: The output size of the poisson encoder depends on the \
-            actual input size.
+        NOTE: The output shape of the poisson encoder depends on the input shape.
         """
-        super().__init__(seed=seed, **kwargs)
+        super().__init__(seed, **kwargs)
 
-    def __call__(self, x: np.ndarray, *args, **kwargs) -> np.ndarray:
+    def __call__(self, x: np.ndarray, *args, **kwargs) -> SpikeType:
         return np.less_equal(self.rng.random(x.shape), x).astype(np.bool_)

From f2c8e13c9cf337de223ee61bf562c7ef9509c72c Mon Sep 17 00:00:00 2001
From: KafCoppelia <k740677208@gmail.com>
Date: Wed, 20 Mar 2024 11:40:12 +0800
Subject: [PATCH 35/68] =?UTF-8?q?=E2=9C=85=20added=20tests=20for=20latency?=
 =?UTF-8?q?=20encoder?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

---
 tests/simulator/test_encoder.py | 20 +++++++++++++++++---
 tests/test_projection.py        | 19 +++++++++++++++++++
 2 files changed, 36 insertions(+), 3 deletions(-)

diff --git a/tests/simulator/test_encoder.py b/tests/simulator/test_encoder.py
index 8548fde9..971051f0 100644
--- a/tests/simulator/test_encoder.py
+++ b/tests/simulator/test_encoder.py
@@ -14,7 +14,6 @@ def test_PeriodicEncoder(self):
         pe = pb.simulator.PeriodicEncoder(spike)
 
         out_spike = np.full((20, 3), 0)
-
         for t in range(20):
             out_spike[t] = pe()
 
@@ -23,16 +22,31 @@ def test_PeriodicEncoder(self):
         assert np.array_equal(spike, out_spike[10:15])
         assert np.array_equal(spike, out_spike[15:20])
 
+    def test_LatencyEncoder(self):
+        N = 6
+        x = np.random.rand(N)
+        T = 20
+
+        le1 = pb.simulator.LatencyEncoder(T, "linear")
+        le2 = pb.simulator.LatencyEncoder(T, "log")
+
+        out_spike1 = np.zeros((T, N), dtype=np.bool_)
+        out_spike2 = np.zeros((T, N), dtype=np.bool_)
+        for t in range(T):
+            out_spike1[t] = le1(x)
+            out_spike2[t] = le2(x)
+
+        assert 1
+
     def test_PoissonEncoder(self):
         seed = 1
         rng = np.random.RandomState(seed=seed)
         x = rng.rand(10, 10).astype(np.float32)
+
         pe = pb.simulator.PoissonEncoder(seed=seed)
 
         out_spike = np.full((20, 10, 10), 0)
-
         for t in range(20):
             out_spike[t] = pe(x=x)
-
         for t in range(1, 20):
             assert not np.array_equal(out_spike[0], out_spike[t])
diff --git a/tests/test_projection.py b/tests/test_projection.py
index fc8c47d4..5311a39d 100644
--- a/tests/test_projection.py
+++ b/tests/test_projection.py
@@ -160,6 +160,25 @@ def test_input_PeriodicEncoder(self):
 
         sim.run(10)
         assert len(sim.data[prob]) == 10
+        assert sim.data[prob][-1].size == 3
+
+    @pytest.mark.parametrize("encoding_func", ["linear", "log"])
+    def test_input_LatencyEncoder(self, encoding_func):
+        N = 6
+        x = np.random.rand(N)
+        T = 20
+
+        le = pb.simulator.LatencyEncoder(T, encoding_func)
+        inp = pb.InputProj(le, shape_out=(N,), keep_shape=False)
+
+        sim = pb.Simulator(inp)
+        prob = pb.simulator.Probe(inp, "output")
+        sim.add_probe(prob)
+
+        inp.input = x
+        sim.run(T)
+        assert len(sim.data[prob]) == T
+        assert sim.data[prob][-1].size == N
 
     def test_illegal_input(self):
         def fakeout_with_t(t, **kwargs):

From a0218945c5f6dd719201e0cc824853b5b7ef58a6 Mon Sep 17 00:00:00 2001
From: KafCoppelia <k740677208@gmail.com>
Date: Wed, 20 Mar 2024 15:41:38 +0800
Subject: [PATCH 36/68] =?UTF-8?q?=F0=9F=8E=A8=20updated=20exceptions=20tex?=
 =?UTF-8?q?t?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

---
 paibox/__init__.py              |  2 +-
 paibox/backend/graphs.py        | 11 +++++------
 paibox/backend/mapper.py        | 10 +++++-----
 paibox/backend/placement.py     | 10 +++++-----
 paibox/backend/routing.py       | 31 ++++++++++++++++---------------
 paibox/backend/segment_utils.py | 14 +++++++-------
 paibox/base.py                  |  2 +-
 paibox/collector.py             | 13 +++++++------
 paibox/context.py               |  4 ++--
 paibox/generic.py               |  6 +++---
 paibox/mixin.py                 | 30 ++++++++++++------------------
 paibox/network.py               | 12 ++++++------
 paibox/neuron/base.py           | 10 +++++-----
 paibox/node.py                  |  2 +-
 paibox/projection.py            | 14 +++++++-------
 paibox/simulator/encoder.py     |  6 +++---
 paibox/simulator/probe.py       |  2 +-
 paibox/simulator/simulator.py   | 12 ++++++------
 paibox/synapses/base.py         | 13 ++++++-------
 paibox/synapses/conv_utils.py   |  4 ++--
 paibox/synapses/synapses.py     |  7 +++----
 paibox/synapses/transforms.py   | 18 ++++++------------
 paibox/types.py                 |  2 +-
 paibox/utils.py                 |  8 ++++----
 24 files changed, 115 insertions(+), 128 deletions(-)

diff --git a/paibox/__init__.py b/paibox/__init__.py
index 184d573f..f66423e8 100644
--- a/paibox/__init__.py
+++ b/paibox/__init__.py
@@ -33,7 +33,7 @@
     if hasattr(plib, "get_version"):  # For plib <= 0.0.12
         raise ImportError(
             tools.PLIB_UPDATE_INTRO.format(
-                __plib_minimum_version__, ".".join(map(str, plib.get_version()))
+                __plib_minimum_version__, ".".join(map(str, plib.get_version()))  # type: ignore
             )
         ) from None
 
diff --git a/paibox/backend/graphs.py b/paibox/backend/graphs.py
index 0b663997..df9925f8 100644
--- a/paibox/backend/graphs.py
+++ b/paibox/backend/graphs.py
@@ -176,7 +176,7 @@ def _graph_supported_check(self) -> None:
             for onode in self.onodes.values()
         ):
             raise NotSupportedError(
-                f"Only output nodes with no more than {HwConfig.N_FANIN_PER_DENDRITE_MAX} "
+                f"only output nodes with no more than {HwConfig.N_FANIN_PER_DENDRITE_MAX} "
                 f"neurons are supported."
             )
 
@@ -190,7 +190,7 @@ def _node_pos(self, node: NodeName) -> NodePosition:
 
     def build_check(self) -> None:
         if not self.has_built:
-            raise BuildError(f"The graph hasn't been built yet.")
+            raise BuildError(f"the graph hasn't been built yet.")
 
     def group_edges(self) -> List[FrozenSet[EdgeType]]:
         """Group all edges according to a certain rule.
@@ -274,7 +274,7 @@ def inherent_timestep(self) -> int:
 
     @property
     def graph_name_repr(self) -> str:
-        _str = f"Graph_of_{self.networks[0].name}"
+        _str = f"graph_of_{self.networks[0].name}"
 
         for network in self.networks[1:]:
             _str += f"_and_{network.name}"
@@ -289,8 +289,7 @@ def _degree_check(
     for node in filter(lambda node: degree_of_nodes[node].out_degree > 1, succ_dg):
         if any(degree_of_nodes[succ_node].in_degree > 1 for succ_node in succ_dg[node]):
             raise NotSupportedError(
-                "If out-degree of a node is greater than 1, "
-                "the in-degree of its sucessors must be 1."
+                "If out-degree of a node is greater than 1, the in-degree of its sucessors must be 1."
             )
 
 
@@ -373,7 +372,7 @@ def toposort(directed_edges: Mapping[_NT, Iterable[_NT]]) -> List[_NT]:
                 vertices.add(m)
 
     if any(incoming_edges.get(v, None) for v in directed_edges):
-        raise NotSupportedError("The graph with cycles is not supported yet.")
+        raise NotSupportedError("the graph with cycles is not supported.")
 
     return ordered
 
diff --git a/paibox/backend/mapper.py b/paibox/backend/mapper.py
index 6700801d..75b009c6 100644
--- a/paibox/backend/mapper.py
+++ b/paibox/backend/mapper.py
@@ -225,7 +225,7 @@ def coord_assign(self) -> None:
             n_core_required := sum(cb.n_core_required for cb in self.core_blocks)
         ) > HwConfig.N_CORE_OFFLINE:
             raise ResourceError(
-                f"#N of total cores required out of {HwConfig.N_CORE_OFFLINE} ({n_core_required})."
+                f"the number of required cores is out of range {HwConfig.N_CORE_OFFLINE} ({n_core_required})."
             )
 
         self.n_core_required = n_core_required
@@ -237,7 +237,7 @@ def coord_assign(self) -> None:
         for rg in routing_groups:
             if not self.routing_tree.insert_routing_group(rg):
                 raise RuntimeError(
-                    f"Insert routing group {rg} into the routing tree failed."
+                    f"insert routing group {rg} into the routing tree failed."
                 )
 
         self.routing_groups = routing_groups
@@ -423,7 +423,7 @@ def export(
         Return: a dictionary of configurations.
         """
         if format not in ("bin", "npy", "txt"):
-            raise ValueError(f"Format {format} is not supported.")
+            raise ValueError(f"format {format} is not supported.")
 
         _fp = _fp_check(fp)
 
@@ -459,7 +459,7 @@ def find_neuron(self, neuron: NeuDyn, *, verbose: int = 0) -> None:
             # Find neuron in one or more core blocks.
             if neuron in cb.dest:
                 print(
-                    f"Neurons {neuron.name} placed in {cb.name}, LCN_{1 << cb.lcn_ex}X"
+                    f"neurons {neuron.name} placed in {cb.name}, LCN_{1 << cb.lcn_ex}X"
                 )
                 for core_plm in cb.core_placements.values():
                     for neu_seg in core_plm.neu_segs_of_cplm:
@@ -476,7 +476,7 @@ def find_axon(self, neuron: NeuDyn, *, verbose: int = 0) -> None:
         for cb in self.core_blocks:
             # Find neuron in one or more core blocks.
             if neuron in cb.source:
-                print(f"Axons {neuron.name} placed in {cb.name}, LCN_{1 << cb.lcn_ex}X")
+                print(f"axons {neuron.name} placed in {cb.name}, LCN_{1 << cb.lcn_ex}X")
                 axon_segment = cb.axon_segments[neuron]
                 print(
                     f"{neuron.name} placed in {cb.core_coords}\n"
diff --git a/paibox/backend/placement.py b/paibox/backend/placement.py
index 85ca673a..7bd7d564 100644
--- a/paibox/backend/placement.py
+++ b/paibox/backend/placement.py
@@ -277,7 +277,7 @@ def n_neuron_of_plm(self) -> List[int]:
         FIXME Different in SNN/ANN RUNTIME_MODE.
         """
         if len(self.core_coords) == 0:
-            raise BuildError(f"Do this after coordinates assignment.")
+            raise BuildError(f"do this after coordinates assignment.")
 
         # Get #N of neurons on each `CorePlacement` according to the
         # maximum address required of neuron segments on each `CorePlacement`.
@@ -345,7 +345,7 @@ def build(cls, *synapses: SynSys, seed: int = 0, enable_wp_opt: bool):
         wp0 = synapses[0].weight_precision
         # Check wether weight precision of all synapses equal.
         if not all(wp0 == s.weight_precision for s in synapses):
-            raise NotSupportedError("Mixed weight precision is not supported yet")
+            raise NotSupportedError("mixed weight precision is not supported yet.")
 
         if wp0 > max(cls.SUPPORTED_WP):
             raise NotSupportedError(f"{wp0.name} is not supported yet.")
@@ -357,7 +357,7 @@ def build(cls, *synapses: SynSys, seed: int = 0, enable_wp_opt: bool):
         # FIXME where does the parameter check do?
         if seed > (1 << 64) - 1:
             warnings.warn(
-                f"Random seed {seed} is too large, truncated into 64 bits!", UserWarning
+                f"random seed {seed} is too large, truncated into 64 bits.", UserWarning
             )
 
         return cls(*synapses, weight_precision=wp0, seed=seed)
@@ -721,11 +721,11 @@ def n_axon2lcn_ex(n_axon: int, fan_in_max: int) -> LCN_EX:
         LCN_EX = log2[ceil(#N/fan-in per dendrite)], where LCN_EX = 0 is `LCN_1X`.
     """
     if n_axon < 1:
-        raise ValueError(f"The #N of axons must be positive, but got {n_axon}")
+        raise ValueError(f"the number of axons must be positive, but got {n_axon}.")
 
     if (lcn_bit := ((n_axon - 1) // fan_in_max).bit_length()) > LCN_EX.LCN_64X:
         raise ResourceError(
-            f"LCN extension required out of {LCN_EX.LCN_64X}: {lcn_bit}"
+            f"LCN extension required out of range {LCN_EX.LCN_64X} ({lcn_bit})."
         )
 
     return LCN_EX(lcn_bit)
diff --git a/paibox/backend/routing.py b/paibox/backend/routing.py
index 78510189..763704c2 100644
--- a/paibox/backend/routing.py
+++ b/paibox/backend/routing.py
@@ -84,7 +84,7 @@ def add_child(
     ) -> bool:
         if self.level == Level.L0:
             # L0-level cluster cannot add child.
-            raise AttributeError(f"L0-level cluster cannot add child")
+            raise AttributeError(f"L0-level cluster cannot add child.")
 
         if self.is_full():
             return False
@@ -101,7 +101,7 @@ def add_child_to(
     ) -> bool:
         """Add a child cluster to a certain `direction`."""
         if self.level - child.level != 1:
-            raise ValueError
+            raise ValueError(f"Cannot skip more than 1 level.")
 
         if not force and d in self.children:
             return False
@@ -127,7 +127,7 @@ def find_cluster_by_path(
 
         if len(path) > self.level:
             raise ValueError(
-                f"The length of the {path} should be less than or equal to level, but yours is greater than"
+                f"the length of the {path} should be less than or equal to level."
             )
 
         if path[0] not in self.children:
@@ -150,7 +150,9 @@ def get_routing_path(self, cluster: "RoutingCluster") -> Optional[List[Direction
             - A list of `Direction` from L4 to L0.
         """
         if cluster.level > self.level:
-            raise ValueError
+            raise ValueError(
+                f"Cannot get routing path because the level cluster is higher."
+            )
 
         if cluster.level == self.level:
             if cluster != self:
@@ -188,7 +190,7 @@ def n_child_avail(self) -> int:
     def _find_lx_cluster_with_n_child_avail(
         self, lx: Level, n_child_avail: int, method: str = "nearest"
     ) -> Optional["RoutingCluster"]:
-        """Find the child of level `lx` with at least `n_child_avail` children available."""
+        """Find the child of level `lx` with at least `n_child_avail` child available."""
         if lx > self.level:
             raise ValueError
 
@@ -218,8 +220,7 @@ def add_subtree(
         subtree: "RoutingCluster",
         method: str = "nearest",
     ) -> bool:
-        """Add the subtree's children to itself. \
-            If successful, return the added parent cluster."""
+        """Add the subtree's children to itself. If successful, return the added parent cluster."""
         if subtree.level > self.level:
             raise ValueError
 
@@ -268,7 +269,7 @@ def add_subtree(
             else:
                 # Only support 1, 2, & 4.
                 raise NotSupportedError(
-                    f"#N of {sub_n_child} children not supported yet."
+                    f"the number of {sub_n_child} child is not supported."
                 )
 
             return True
@@ -307,10 +308,10 @@ def create_lx_full_tree(
 
     @classmethod
     def create_routing_tree(cls, lx: Level, n_branch: int) -> "RoutingCluster":
-        """Create a routing tree with `n_branch` children.
+        """Create a routing tree with `n_branch` child.
 
-        NOTE: When lx == L1, do not create the L0-level children. \
-            WHen lx > L1, create the lx-1 level children.
+        NOTE: When lx == L1, do not create the L0-level child. \
+            WHen lx > L1, create the lx-1 level child.
         """
         if lx == Level.L0 or n_branch < 0:
             raise ValueError
@@ -339,10 +340,10 @@ def add_L0_for_placing(self, data: Any = None, **kwargs) -> "RoutingCluster":
 
         L1_cluster = self._find_lx_cluster_with_n_child_avail(Level.L1, 1)
         if not L1_cluster:
-            raise RuntimeError("Available L1 cluster not found!")
+            raise RuntimeError("available L1 cluster not found.")
 
         if not L1_cluster.add_child(cluster):
-            raise RuntimeError(f"Add child into L1 cluster failed!")
+            raise RuntimeError(f"add child to L1 cluster failed.")
 
         return cluster
 
@@ -436,7 +437,7 @@ def assign(self, assigned: List[Coord], wasted: List[Coord]) -> None:
 
     def __getitem__(self, idx: int) -> CoreBlock:
         if idx >= len(self.cb) or idx < 0:
-            raise IndexError(f"Index out of range [0, {len(self.cb)}), {idx}.")
+            raise IndexError(f"index out of range [0, {len(self.cb)}) ({idx}).")
 
         return self.cb[idx]
 
@@ -474,7 +475,7 @@ def get_leaf_coord(self, cluster: "RoutingCluster") -> RoutingCoord:
         if path:
             return RoutingCoord(*path)
 
-        raise RuntimeError(f"Get leaf cluster {cluster.tag} coordinate failed.")
+        raise RuntimeError(f"get leaf cluster {cluster.tag} coordinate failed.")
 
     def insert_routing_group(self, routing_group: RoutingGroup) -> bool:
         """Insert a `RoutingGroup` in the routing tree. Assign each core blocks with \
diff --git a/paibox/backend/segment_utils.py b/paibox/backend/segment_utils.py
index 6249c904..bea80f37 100644
--- a/paibox/backend/segment_utils.py
+++ b/paibox/backend/segment_utils.py
@@ -110,8 +110,8 @@ def _get_nsg_opt_core(
 
     if raise_warning:
         warnings.warn(
-            "When grouping neurons with 'core' optimization, unrolling "
-            "factor greater than 1 will be invalid. Modified to 1.",
+            "when grouping neurons with 'core' optimization, unrolling "
+            "factor greater than 1 is invalid. Modified to 1.",
             ParameterInvalidWarning,
         )
 
@@ -198,8 +198,8 @@ def _get_neu_slices(
 def _dense_reorganized(
     seg_slices_dict: Dict[NeuDyn, List[NeuSlice]], capacity: int, repl_prop: int
 ) -> NeuSegOfCoreBlock:
-    """Reorganize densely. Based on the result of 'latency' method, use greedy \
-        algorithm to reorganize the incomplete neuron segments for saving cores.
+    """Reorganize densely. Based on the result of 'latency' method, use greedy algorithm to \
+        reorganize the incomplete neuron segments for saving cores.
     """
 
     def _find_neu_in_segs_of_cplm(neu: NeuDyn, seg_of_cplm: NeuSegOfCorePlm) -> bool:
@@ -260,8 +260,8 @@ def get_neu_segments(
     """Get the neuron segments by given a optimization strategy.
 
     Args:
-        - optim_target: Target of optimization. 'catagory' strategy intends to optimize the throughput of nodes. \
-            The 'dense' strategy intends to optimize the consumption of cores.
+        - optim_target: Target of optimization. 'catagory' strategy intends to optimize the throughput  \
+            of nodes. The 'dense' strategy intends to optimize the consumption of cores.
     """
     if optim_target == "core":
         seg_slices_dict = _get_neu_slices_opt_core(neu_groups, capacity)
@@ -303,7 +303,7 @@ def _seg_alloc(axon: SourceNodeType) -> AxonSegment:
 
         if offset + addr_width > fan_in_max:
             raise ResourceError(
-                f"Axons address out of range [0, {fan_in_max}), {offset + addr_width}."
+                f"axons address out of range [0, {fan_in_max}) ({offset + addr_width})."
             )
 
         cur_offset = offset
diff --git a/paibox/base.py b/paibox/base.py
index 1ee9f17d..e793ce7e 100644
--- a/paibox/base.py
+++ b/paibox/base.py
@@ -30,7 +30,7 @@ def __init__(self, name: Optional[str] = None) -> None:
     def __eq__(self, other: "PAIBoxObject") -> bool:
         if not isinstance(other, PAIBoxObject):
             raise TypeError(
-                f"Cannot compare {type(self).__name__} with {type(other).__name__}."
+                f"cannot compare {type(self).__name__} with {type(other).__name__}."
             )
 
         if self is other:
diff --git a/paibox/collector.py b/paibox/collector.py
index b8f41359..fd70e4bb 100644
--- a/paibox/collector.py
+++ b/paibox/collector.py
@@ -10,7 +10,7 @@ def __setitem__(self, key: _KT, value: _VT) -> None:
         if key in self:
             if id(self[key]) != id(value):
                 raise ValueError(
-                    f"Name '{key}' conflicts: same name for {value} and {self[key]}."
+                    f"mame '{key}' conflicts: same name for {value} & {self[key]}."
                 )
 
         super().__setitem__(key, value)
@@ -30,7 +30,7 @@ def update(
     ) -> Union["Collector[_KT, _VT]", "Collector[_KT, _T]"]:
         if not isinstance(other, (dict, list, tuple)):
             raise TypeError(
-                f"Expected a dict, list or sequence, but we got {other}, type {type(other)}"
+                f"expected a dict, list or sequence, but got {other}, type {type(other)}."
             )
 
         if isinstance(other, dict):
@@ -56,6 +56,7 @@ def __add__(
 
         Arguments:
             - other: the other dictionary.
+
         Returns:
             - gather: the new collector.
         """
@@ -75,7 +76,7 @@ def __sub__(
     ) -> Union["Collector[_KT, _VT]", "Collector[str, _T]"]:
         if not isinstance(other, (dict, list, tuple)):
             raise TypeError(
-                f"Expected a dict, list or sequence, but we got {other}, type {type(other)}"
+                f"expected a dict, list or sequence, but got {other}, type {type(other)}."
             )
 
         gather = type(self)(self)
@@ -83,11 +84,11 @@ def __sub__(
         if isinstance(other, dict):
             for k, v in other.items():
                 if k not in gather.keys():
-                    raise ValueError(f"Cannot find '{k}' in {self.keys()}.")
+                    raise ValueError(f"cannot find '{k}' in {self.keys()}.")
 
                 if id(v) != id(gather[k]):
                     raise ValueError(
-                        f"Cannot remove '{k}', since there's two different values:"
+                        f"cannot remove '{k}', since there are two different values: "
                         f"{v} != {gather[k]}"
                     )
                 gather.pop(k)
@@ -109,7 +110,7 @@ def __sub__(
 
             for k in set(keys_to_remove):
                 if k not in gather:
-                    raise KeyError(f"Key '{k}' not found. Removed failed.")
+                    raise KeyError(f"key '{k}' not found. Removed failed.")
 
                 gather.pop(k)
 
diff --git a/paibox/context.py b/paibox/context.py
index b5587baf..9884124d 100644
--- a/paibox/context.py
+++ b/paibox/context.py
@@ -19,7 +19,7 @@ def load(self, key: Any, default: Any = None) -> Any:
             return super().__getitem__(key)
 
         if default is None:
-            raise KeyError(f"The context of '{key}' not found.")
+            raise KeyError(f"the context of '{key}' not found.")
 
         return default
 
@@ -27,7 +27,7 @@ def save(self, *args, **kwargs) -> None:
         """Save the context by the key-value pairs."""
         if len(args) % 2 > 0:
             raise TypeError(
-                f"Expected even positional arguments but odd given ({len(args)})"
+                f"expected even positional arguments, but odd given ({len(args)})."
             )
 
         for i in range(0, len(args), 2):
diff --git a/paibox/generic.py b/paibox/generic.py
index 276983e0..de43c242 100644
--- a/paibox/generic.py
+++ b/paibox/generic.py
@@ -12,12 +12,12 @@ def is_name_unique(name: str, obj: object) -> None:
     Otherwise raise an error.
     """
     if not name.isidentifier():
-        raise ValueError(f"{name} is not a valid identifier")
+        raise ValueError(f"'{name}' is not a valid identifier.")
 
     if name in _id_dict:
         if _id_dict[name] != id(obj):
             raise RegisterError(
-                f"Name of {obj}({name}) is already used by {_id_dict[name]}"
+                f"name of {obj}({name}) is already used by {_id_dict[name]}."
             )
 
     else:
@@ -41,4 +41,4 @@ def clear_name_cache(ignore_warn: bool = False) -> None:
     _type_names.clear()
 
     if not ignore_warn:
-        warnings.warn(f"All named models & ids are cleared.", PAIBoxWarning)
+        warnings.warn(f"all named models & ids are cleared.", PAIBoxWarning)
diff --git a/paibox/mixin.py b/paibox/mixin.py
index 742ae763..391e3a99 100644
--- a/paibox/mixin.py
+++ b/paibox/mixin.py
@@ -28,10 +28,7 @@ def wrapper(*args, **kwargs):
 
 
 def prevent(func):
-    """
-    Decorate func with this to prevent raising an Exception when \
-    an error is encountered.
-    """
+    """Decorate function with this to prevent raising an Exception when an error is encountered."""
 
     @wraps(func)
     def wrapper(*args, **kwargs):
@@ -44,11 +41,8 @@ def wrapper(*args, **kwargs):
 
 
 def check(attr):
+    """Decorate function with this to check whether the object has an attribute with the given name."""
     def decorator(method):
-        """
-        Decorate method with this to check whether the object \
-        has an attribute with the given name.
-        """
 
         @wraps(method)
         def wrapper(self, *args, **kwargs):
@@ -75,7 +69,7 @@ def __getitem__(self, item: str) -> Any:
         if item in self.children:
             return self.children[item]
 
-        raise KeyError(f"Key '{item}' not found.")
+        raise KeyError(f"key '{item}' not found.")
 
     def _get_elem_name(self, elem: object) -> str:
         if isinstance(elem, pb.base.PAIBoxObject):
@@ -99,7 +93,7 @@ def elem_format(
                 for c in child:
                     if not isinstance(c, child_type):
                         raise ValueError(
-                            f"Expect type {child_type.__name__}, but got {type(c)}."
+                            f"expect type {child_type.__name__}, but got {type(c)}."
                         )
                     elems[self._get_elem_name((c))] = c
 
@@ -107,18 +101,18 @@ def elem_format(
                 for k, v in child.items():
                     if not isinstance(v, child_type):
                         raise ValueError(
-                            f"Expect type {child_type.__name__}, but got {type(c)}."
+                            f"expect type {child_type.__name__}, but got {type(c)}."
                         )
                     elems[k] = v
             else:
                 raise TypeError(
-                    f"Expect elements in dict, list or tuple, but got {type(child)}."
+                    f"expect elements in dict, list or tuple, but got {type(child)}."
                 )
 
         for k, v in children_as_dict.items():
             if not isinstance(v, child_type):
                 raise ValueError(
-                    f"Expect type {child_type.__name__}, but got {type(v)}."
+                    f"expect type {child_type.__name__}, but got {type(v)}."
                 )
             elems[k] = v
 
@@ -134,7 +128,7 @@ class ReceiveInputProj(MixIn):
 
     def register_master(self, key: str, master_target) -> None:
         if key in self.master_nodes:
-            raise RegisterError(f"Master node with key '{key}' already exists.")
+            raise RegisterError(f"master node with key '{key}' already exists.")
 
         self.master_nodes[key] = master_target
 
@@ -142,7 +136,7 @@ def unregister_master(self, key: str, strict: bool = True) -> Optional[Any]:
         if key in self.master_nodes:
             return self.master_nodes.pop(key, None)
         elif strict:
-            raise KeyError(f"Key '{key}' not found in master nodes.")
+            raise KeyError(f"key '{key}' not found in master nodes.")
 
     def get_master_node(self, key: str) -> Optional[Any]:
         return self.master_nodes.get(key, None)
@@ -189,7 +183,7 @@ def __init__(self) -> None:
 
     def set_memory(self, name: str, value: Any) -> None:
         if hasattr(self, name):
-            raise AttributeError(f"'{name}' has been set as a member variable!")
+            raise AttributeError(f"'{name}' has been set as a member variable.")
 
         self._memories[name] = value
         self.set_reset_value(name, value)
@@ -199,7 +193,7 @@ def reset_memory(self, name: Optional[str] = None) -> None:
             if name in self._memories:
                 self._memories[name] = deepcopy(self._memories_rv[name])
             else:
-                raise KeyError(f"Key '{name}' not found!")
+                raise KeyError(f"key '{name}' not found.")
         else:
             for k in self._memories.keys():
                 self._memories[k] = deepcopy(self._memories_rv[k])
@@ -213,7 +207,7 @@ def __getattr__(self, name: str) -> Any:
             if name in _memories:
                 return _memories[name]
 
-        raise AttributeError(f"Attribute '{name}' not found!")
+        raise AttributeError(f"attribute '{name}' not found.")
 
     def __setattr__(self, name: str, value: Any) -> None:
         _memories = self.__dict__.get("_memories")
diff --git a/paibox/network.py b/paibox/network.py
index c12b9761..98c1772d 100644
--- a/paibox/network.py
+++ b/paibox/network.py
@@ -97,7 +97,7 @@ def disconnect_syn(
             RIGISTER_MASTER_KEY_FORMAT.format(target_syn.name)
         )
         if ret is not target_syn:
-            raise RegisterError("unregister failed!")
+            raise RegisterError("unregister failed.")
 
         if not exclude_source:
             self._remove_component(target_syn)
@@ -256,7 +256,7 @@ def _disconn_syn(target_syn: SynSys) -> None:
             RIGISTER_MASTER_KEY_FORMAT.format(target_syn.name)
         )
         if ret is not target_syn:
-            raise RegisterError("unregister failed!")
+            raise RegisterError("unregister failed.")
 
     @staticmethod
     def _disconn_succ_syn(target_syn: SynSys) -> None:
@@ -264,7 +264,7 @@ def _disconn_succ_syn(target_syn: SynSys) -> None:
             RIGISTER_MASTER_KEY_FORMAT.format(target_syn.name)
         )
         if ret is not target_syn:
-            raise RegisterError("unregister failed!")
+            raise RegisterError("unregister failed.")
 
     @staticmethod
     def _assert_neuron(nodes: Collector, *neurons: Neuron) -> None:
@@ -302,11 +302,11 @@ def __getitem__(self, item: Union[str, int, slice]):
             if item in self.children:
                 return self.children[item]
             else:
-                raise KeyError(f"Key {item} not found.")
+                raise KeyError(f"key '{item}' not found.")
 
         if isinstance(item, int):
             if item > len(self):
-                raise IndexError(f"Index out of range: {item}")
+                raise IndexError(f"index out of range {item}.")
 
             return tuple(self.children.values())[item]
 
@@ -314,7 +314,7 @@ def __getitem__(self, item: Union[str, int, slice]):
             return Sequential(**dict(tuple(self.children.items())[item]))
 
         raise TypeError(
-            f"Expected type str, int or slice, but got {item}, type {type(item)}"
+            f"expected type str, int or slice, but got {item}, type {type(item)}."
         )
 
     def __len__(self) -> int:
diff --git a/paibox/neuron/base.py b/paibox/neuron/base.py
index 8f3f65a3..32e7acec 100644
--- a/paibox/neuron/base.py
+++ b/paibox/neuron/base.py
@@ -94,7 +94,7 @@ def _neuronal_charge(
 
         if self.synaptic_integration_mode is SIM.MODE_STOCHASTIC:
             raise NotImplementedError(
-                f"Mode {SIM.MODE_STOCHASTIC.name} is not implemented."
+                f"mode {SIM.MODE_STOCHASTIC.name} is not implemented."
             )
         else:
             if incoming_v.ndim == 2:
@@ -134,7 +134,7 @@ def _neuronal_leak(self, vjt: VoltageType) -> VoltageType:
             v_leaked = np.add(vjt, _ld * self.leak_v).astype(np.int32)
         else:
             raise NotImplementedError(
-                f"Mode {LIM.MODE_STOCHASTIC.name} is not implemented."
+                f"mode {LIM.MODE_STOCHASTIC.name} is not implemented."
             )
             # _F = 1 if abs(self.leak_v) >= _rho_j_lambda else 0
             # sgn_leak_v = fn_sgn(self.leak_v, 0)
@@ -393,17 +393,17 @@ def __init__(
     ) -> None:
         if neg_threshold > 0:
             raise ValueError(
-                f"Negative threshold must be non-positive, but got {neg_threshold}."
+                f"negative threshold must be non-positive, but got {neg_threshold}."
             )
 
         if pos_threshold < 0:
             raise ValueError(
-                f"Positive threshold must be non-negative, but got {pos_threshold}."
+                f"positive threshold must be non-negative, but got {pos_threshold}."
             )
 
         if bit_truncation < 0:
             raise ValueError(
-                f"Bit of tuncation must be non-negative, but got {bit_truncation}."
+                f"bit of tuncation must be non-negative, but got {bit_truncation}."
             )
 
         if delay < 1:
diff --git a/paibox/node.py b/paibox/node.py
index 2b6c3e9e..f8bed49e 100644
--- a/paibox/node.py
+++ b/paibox/node.py
@@ -33,4 +33,4 @@ def __getitem__(self, key: _KT) -> _VT:
         if key in self:
             return super().__getitem__(key)
 
-        raise KeyError(f"Key '{key}' not found.")
+        raise KeyError(f"key '{key}' not found.")
diff --git a/paibox/projection.py b/paibox/projection.py
index ca0d4b1f..99b62b38 100644
--- a/paibox/projection.py
+++ b/paibox/projection.py
@@ -42,8 +42,8 @@ def __init__(
         """The input node of network.
 
         Arguments:
-            - input: the input value of the projection node. It can be numeric value \
-                or callable function(function or `Encoder`).
+            - input: the input value of the projection node. It can be numeric value or callable\
+                function(function or `Encoder`).
             - shape_out: the shape of the output.
             - keep_shape: wether to keep the shape when retieving the feature map.
             - name: the name of the node. Optional.
@@ -73,13 +73,13 @@ def update(self, **kwargs) -> SpikeType:
         elif isinstance(_spike, np.ndarray):
             if shape2num(_spike.shape) != self.num_out:
                 raise ShapeError(
-                    f"Cannot reshape output value from {_spike.shape} to ({self.num_out},)."
+                    f"cannot reshape output value from {_spike.shape} to ({self.num_out},)."
                 )
             self._inner_spike = _spike.flatten().astype(np.bool_)
         else:
             # should never be reached
             raise TypeError(
-                f"Expected type int, np.bool_, np.integer or np.ndarray, "
+                f"expected type int, np.bool_, np.integer or np.ndarray, "
                 f"but got {_spike}, type {type(_spike)}."
             )
 
@@ -93,7 +93,7 @@ def _get_neumeric_input(self, **kwargs):
         # Otherwise, use the output of `_func_input`.
         if self._num_input is None:
             if self._func_input is None:
-                raise SimulationError(f"Both numeric & functional input are not set.")
+                raise SimulationError(f"both numeric & functional input are not set.")
             else:
                 return _call_with_ctx(self._func_input, **kwargs)
 
@@ -131,8 +131,8 @@ def input(self, value: DataType) -> None:
         """Set the input at the beginning of running the simulation."""
         if not isinstance(value, (int, np.bool_, np.integer, np.ndarray)):
             raise TypeError(
-                f"Expected type int, np.bool_, np.integer or np.ndarray, "
-                f"but got {value}, type {type(value)}"
+                f"expected type int, np.bool_, np.integer or np.ndarray, "
+                f"but got {value}, type {type(value)}."
             )
 
         self._num_input = value
diff --git a/paibox/simulator/encoder.py b/paibox/simulator/encoder.py
index a2c82257..87ebb3bf 100644
--- a/paibox/simulator/encoder.py
+++ b/paibox/simulator/encoder.py
@@ -33,7 +33,7 @@ def __init__(self, T: int, seed: Optional[int] = None) -> None:
         super(Encoder, self).__init__()
 
         if T < 1:
-            raise ValueError(f"'T' must be positive, but got {T}")
+            raise ValueError(f"'T' must be positive, but got {T}.")
 
         self.T = T
         self.set_memory("spike", None)
@@ -43,7 +43,7 @@ def __call__(self, x: Optional[np.ndarray] = None, *args, **kwargs) -> SpikeType
         # If there is no encoded spike but there is an input, encode the input
         if self.spike is None:
             if x is None:
-                raise ValueError("input must be given if spike is None")
+                raise ValueError("input must be given if 'spike' is None.")
 
             self.encode(x)
 
@@ -90,7 +90,7 @@ def __init__(self, T: int, encoding_func: Literal["linear", "log"]) -> None:
         if encoding_func == "log":
             self.alpha = math.exp(T - 1) - 1
         elif encoding_func != "linear":  # `alpha` is not used in method 'linear'.
-            raise ValueError("encoding function must be 'log' or 'linear'")
+            raise ValueError("encoding function must be 'linear' or 'log'.")
 
         self.enc_func = encoding_func
 
diff --git a/paibox/simulator/probe.py b/paibox/simulator/probe.py
index 8a1b9253..e2404e12 100644
--- a/paibox/simulator/probe.py
+++ b/paibox/simulator/probe.py
@@ -26,7 +26,7 @@ def __init__(
     def _check_attr(self, target: PAIBoxObject) -> None:
         if not hasattr(target, self.attr):
             raise AttributeError(
-                f"Attribute '{self.attr}' not found in target {self.target}."
+                f"attribute '{self.attr}' not found in target {self.target}."
             )
 
         self.target = target
diff --git a/paibox/simulator/simulator.py b/paibox/simulator/simulator.py
index 65238eb9..a2228463 100644
--- a/paibox/simulator/simulator.py
+++ b/paibox/simulator/simulator.py
@@ -29,7 +29,7 @@ def __init__(
         """
         if not isinstance(target, DynamicSys):
             raise SimulationError(
-                f"Target must be an instance of {DynamicSys.__name__}, but we got {target}: {type(target)}"
+                f"target must be an instance of {DynamicSys.__name__}, but got {target}, {type(target)}."
             )
 
         super().__init__(name)
@@ -60,18 +60,18 @@ def run(self, duration: int, reset: bool = False, **kwargs) -> None:
         """
         if kwargs:
             warnings.warn(
-                "Passing extra arguments through 'run()' will be deprecated."
+                "passing extra arguments through 'run()' will be deprecated. "
                 "Use 'FRONTEND_ENV.save()' instead.",
                 DeprecationWarning,
             )
 
         if duration < 1:
-            raise SimulationError(f"Duration must be positive, but got {duration}")
+            raise SimulationError(f"duration must be positive, but got {duration}.")
 
         n_steps = self._get_nstep(duration)
         if n_steps < 1:
             raise SimulationError(
-                f"Steps of simulation must be positive, but got {n_steps}"
+                f"the number of simulation steps must be positive, but got {n_steps}."
             )
 
         indices = np.arange(self._ts, self._ts + n_steps, dtype=np.uint16)
@@ -105,7 +105,7 @@ def remove_probe(self, probe: Probe) -> None:
             self.probes.remove(probe)
             self._sim_data.pop(probe)
         else:
-            raise KeyError(f"Probe '{probe.name}' does not exist.")
+            raise KeyError(f"probe '{probe.name}' does not exist.")
 
     def _run_step(self, indices: NDArray[np.uint16], **kwargs) -> None:
         for i in range(indices.shape[0]):
@@ -142,7 +142,7 @@ def get_raw_at_t(self, probe: Probe, t: int) -> Any:
         t_index = t if self._start_time_zero else t - 1
 
         if not t_start <= t < self.timestamp:  # [t_start, timestamp)
-            raise IndexError(f"Time {t} is out of range [{t_start}, {self.timestamp}).")
+            raise IndexError(f"time {t} is out of range [{t_start}, {self.timestamp}).")
 
         return self._sim_data[probe][t_index]
 
diff --git a/paibox/synapses/base.py b/paibox/synapses/base.py
index 3fcf8712..309f92ec 100644
--- a/paibox/synapses/base.py
+++ b/paibox/synapses/base.py
@@ -21,8 +21,7 @@
 def _check_equal(num_in: int, num_out: int) -> int:
     if num_in != num_out:
         raise ShapeError(
-            f"The number of source & destination neurons must "
-            f"be equal, but {num_in} != {num_out}."
+            f"the number of source & destination neurons must be equal: {num_in} != {num_out}."
         )
 
     return num_in
@@ -136,7 +135,7 @@ def __init__(
         elif conn_type is GConnType.Identity:
             if not isinstance(weights, (int, np.bool_, np.integer)):
                 raise TypeError(
-                    f"Expected type int, np.bool_, np.integer, but got type {type(weights)}"
+                    f"expected type int, np.bool_, np.integer, but got type {type(weights)}."
                 )
             comm = Identity(_check_equal(self.num_in, self.num_out), weights)
         elif conn_type is GConnType.All2All:
@@ -144,7 +143,7 @@ def __init__(
         else:  # MatConn
             if not isinstance(weights, np.ndarray):
                 raise TypeError(
-                    f"Expected type np.ndarray, but got type {type(weights)}"
+                    f"expected type np.ndarray, but got type {type(weights)}."
                 )
             comm = MaskedLinear((self.num_in, self.num_out), weights)
 
@@ -169,7 +168,7 @@ def __init__(
 
         if kernel.ndim != self._spatial_ndim + 2:
             raise ShapeError(
-                f"The convolution kernel dimension must be {self._spatial_ndim + 2}, but got {kernel.ndim}."
+                f"convolution kernel dimension must be {self._spatial_ndim + 2}, but got {kernel.ndim}."
             )
 
         if order == "IOHW":
@@ -185,10 +184,10 @@ def __init__(
         out_ch, out_h, out_w = _fm_ndim2_check(dest.shape_out, fm_order)
 
         if in_ch != in_channels:
-            raise ShapeError(f"Input channels mismatch: {in_ch} != {in_channels}")
+            raise ShapeError(f"input channels mismatch: {in_ch} != {in_channels}.")
 
         if out_ch != out_channels:
-            raise ShapeError(f"Output channels mismatch: {out_ch} != {out_channels}")
+            raise ShapeError(f"output channels mismatch: {out_ch} != {out_channels}.")
 
         # If padding is considered, the implementation of convolution unrolling
         # is extremely complex, so fix it.
diff --git a/paibox/synapses/conv_utils.py b/paibox/synapses/conv_utils.py
index ff6fdb3d..322d0867 100644
--- a/paibox/synapses/conv_utils.py
+++ b/paibox/synapses/conv_utils.py
@@ -44,7 +44,7 @@ def _ntuple(x, n: int) -> Tuple[Any, ...]:
 
 def _fm_ndim1_check(fm_shape: SizeAnyType, fm_order: _Order2d) -> Size2Type:
     if len(fm_shape) < 1 or len(fm_shape) > 2:
-        raise ShapeError(f"Expected shape of 1 or 2, but got {len(fm_shape)}")
+        raise ShapeError(f"expected shape of 1 or 2, but got {len(fm_shape)}.")
 
     if len(fm_shape) == 1:
         channels, l = (1,) + fm_shape
@@ -59,7 +59,7 @@ def _fm_ndim1_check(fm_shape: SizeAnyType, fm_order: _Order2d) -> Size2Type:
 
 def _fm_ndim2_check(fm_shape: SizeAnyType, fm_order: _Order3d) -> Size3Type:
     if len(fm_shape) < 2 or len(fm_shape) > 3:
-        raise ShapeError(f"Expected shape of 2 or 3, but got {len(fm_shape)}")
+        raise ShapeError(f"expected shape of 2 or 3, but got {len(fm_shape)}.")
 
     if len(fm_shape) == 2:
         channels, h, w = (1,) + fm_shape
diff --git a/paibox/synapses/synapses.py b/paibox/synapses/synapses.py
index 5f2f6912..edb0436f 100644
--- a/paibox/synapses/synapses.py
+++ b/paibox/synapses/synapses.py
@@ -47,8 +47,7 @@ def __init__(
         name: Optional[str] = None,
     ) -> None:
         warnings.warn(
-            "The `NoDecay` class will be deprecated in future versions, "
-            "use `FullConn` instead.",
+            "'NoDecay' class will be deprecated in future versions. Use 'FullConn' instead.",
             DeprecationWarning,
         )
 
@@ -84,10 +83,10 @@ def __init__(
             - name: name of the 2d convolution. Optional.
         """
         if fm_order not in ("CHW", "HWC"):
-            raise ValueError(f"Unknown feature map order '{fm_order}'.")
+            raise ValueError(f"feature map order must be 'CHW or 'HWC'.")
 
         if kernel_order not in ("OIHW", "IOHW"):
-            raise ValueError(f"Unknown kernel order '{kernel_order}'.")
+            raise ValueError(f"kernel order must be 'OIHW' or 'IOHW'.")
 
         super().__init__(
             source,
diff --git a/paibox/synapses/transforms.py b/paibox/synapses/transforms.py
index 1c0b88ae..ce75e60d 100644
--- a/paibox/synapses/transforms.py
+++ b/paibox/synapses/transforms.py
@@ -58,7 +58,7 @@ def _get_weight_precision(weight: np.ndarray, enable_wp_opt: bool) -> WP:
     _min = np.min(weight, axis=None).astype(np.int32)
 
     if _max > MAX_INT8 or _min < MIN_INT8:
-        raise ValueError(f"Weight precision out of range, [{_min}, {_max}]")
+        raise ValueError(f"weight precision out of range [{_min}, {_max}].")
 
     if _max <= MAX_INT1 and _min >= MIN_INT1:
         return WP.WEIGHT_WIDTH_1BIT
@@ -120,15 +120,13 @@ def __init__(self, num: int, weights: DataArrayType) -> None:
         self.num = num
 
         if isinstance(weights, np.ndarray) and not is_shape(weights, (num,)):
-            raise ShapeError(
-                f"Expected shape is ({num},), but we got shape {weights.shape}"
-            )
+            raise ShapeError(f"expected shape is ({num},), but got {weights.shape}.")
 
         # The ndim of weights = 0 or 1.
         _w = np.asarray(weights, dtype=np.int8)
 
         if _w.ndim not in (0, 1):
-            raise ShapeError(f"The ndim of weights must be 0 or 1, but got {_w.ndim}.")
+            raise ShapeError(f"the ndim of weights must be 0 or 1, but got {_w.ndim}.")
 
         super().__init__(_w)
 
@@ -173,14 +171,12 @@ def __init__(self, conn_size: Size2Type, weights: DataArrayType) -> None:
         self.conn_size = conn_size
 
         if isinstance(weights, np.ndarray) and not is_shape(weights, conn_size):
-            raise ShapeError(
-                f"Expected shape is {conn_size}, but we got shape {weights.shape}"
-            )
+            raise ShapeError(f"expected shape is {conn_size}, but got {weights.shape}.")
 
         _w = np.asarray(weights, dtype=np.int8)
 
         if _w.ndim not in (0, 2):
-            raise ShapeError(f"The ndim of weights must be 0 or 2, but got {_w.ndim}.")
+            raise ShapeError(f"the ndim of weights must be 0 or 2, but got {_w.ndim}.")
 
         super().__init__(_w)
 
@@ -219,9 +215,7 @@ def __init__(
         weights: np.ndarray,
     ) -> None:
         if not is_shape(weights, conn_size):
-            raise ShapeError(
-                f"Expected shape is {conn_size}, but we got {weights.shape}"
-            )
+            raise ShapeError(f"expected shape is {conn_size}, but got {weights.shape}.")
 
         _w = np.asarray(weights, dtype=np.int8)
         super().__init__(_w)
diff --git a/paibox/types.py b/paibox/types.py
index c3fdd844..da6b2af0 100644
--- a/paibox/types.py
+++ b/paibox/types.py
@@ -75,4 +75,4 @@ def __ior__(self, other: Iterable[Any]) -> "OrderedSet[_T]":
         return self
 
     def __hash__(self) -> NoReturn:
-        raise TypeError("'OrderedSet' is not hashable (use 'FrozenOrderedSet' instead)")
+        raise TypeError("'OrderedSet' is not hashable (use 'FrozenOrderedSet' instead).")
diff --git a/paibox/utils.py b/paibox/utils.py
index 8bb86b91..eb15cde5 100644
--- a/paibox/utils.py
+++ b/paibox/utils.py
@@ -24,7 +24,7 @@ def check_elem_unique(obj: Any) -> bool:
 
         return True
 
-    raise TypeError(f"Unsupported type: {type(obj)}")
+    raise TypeError(f"unsupported type: {type(obj)}.")
 
 
 def count_unique_elem(obj: Iterable[Any]) -> int:
@@ -46,7 +46,7 @@ def check_elem_same(obj: Any) -> bool:
     if isinstance(obj, dict):
         return len(set(obj.values())) == 1
 
-    raise TypeError(f"Unsupported type: {type(obj)}")
+    raise TypeError(f"unsupported type: {type(obj)}.")
 
 
 def is_nested_obj(obj_on_top: Any) -> bool:
@@ -75,7 +75,7 @@ def as_shape(shape, min_dim: int = 0) -> Tuple[int, ...]:
     elif is_iterable(shape):
         _shape = tuple(shape)
     else:
-        raise ValueError(f"Cannot make a shape for {shape}")
+        raise ValueError(f"cannot make a shape for {shape}.")
 
     if len(_shape) < min_dim:
         _shape = tuple([1] * (min_dim - len(_shape))) + _shape
@@ -85,7 +85,7 @@ def as_shape(shape, min_dim: int = 0) -> Tuple[int, ...]:
 
 def is_shape(x, shape: Shape) -> bool:
     if not is_array_like(x):
-        raise TypeError(f"Only support an array-like type: {x}")
+        raise TypeError(f"only support an array-like type: {x}.")
 
     _x = np.asarray(x)
     return _x.shape == as_shape(shape)

From fcef26e1a0a5e9e953f600d1ba11febac3972eff Mon Sep 17 00:00:00 2001
From: KafCoppelia <k740677208@gmail.com>
Date: Wed, 20 Mar 2024 15:45:34 +0800
Subject: [PATCH 37/68] =?UTF-8?q?=F0=9F=93=9D=20updated=20docs?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

---
 docs/Guide-of-PAIBox.md | 51 +++++++++++++++++++++++++++++++++++------
 1 file changed, 44 insertions(+), 7 deletions(-)

diff --git a/docs/Guide-of-PAIBox.md b/docs/Guide-of-PAIBox.md
index 5ccaf761..bd78f9f8 100644
--- a/docs/Guide-of-PAIBox.md
+++ b/docs/Guide-of-PAIBox.md
@@ -254,21 +254,38 @@ s1= pb.FullConn(source=n1, dest=n2, weights=weight1, conn_type=pb.SynConnType.Al
 
 普通的神经元连接类型，仅可以通过矩阵设置其权重 `weights`。
 
+#### 1D卷积
+
+全展开形式1D卷积为全连接突触的一种特殊表达。对于卷积形式的突触，需**严格指定**前后神经元的尺寸、神经元维度顺序、卷积核权重、卷积核维度顺序与步长。
+
+- `kernel`：卷积核权重。
+- `stride`：步长，标量。
+- `fm_order` 指定神经元维度顺序为 `CL` 或 `LC` 排列。
+- `kernel_order`：指定卷积核维度顺序为 `OIL` 或 `IOL` 排列。
+
+```python
+n1 = pb.IF(shape=(8, 28), threshold=1)      # Input feature map: (8, 28)
+n2 = pb.IF(shape=(16, 26), threshold=1)     # Output feature map: (16, 26)
+kernel = np.random.randint(-128, 128, size=(16, 8, 3), dtype=np.int8) # OIl
+
+conv2d = pb.Conv1d(n1, n2, kernel=kernel, stride=1, fm_order="CL", kernel_order="OIL", name="conv1d_1")
+```
+
 #### 2D卷积
 
-全展开形式2D卷积可用突触进行表示。对于一个卷积连接，需要严格指定前后神经元的尺寸、神经元维度顺序、卷积核全权重、卷积核维度顺序与步长信息。
+全展开形式2D卷积为全连接突触的一种特殊表达。对于卷积形式的突触，需**严格指定**前后神经元的尺寸、神经元维度顺序、卷积核权重、卷积核维度顺序与步长。
 
 - `kernel`：卷积核权重。
 - `stride`：步长，可以为标量或元组。当为标量时，对应为 `(x, x)`；当为元组时，则对应为 `(x, y)`。
 - `fm_order` 指定神经元维度顺序为 `CHW` 或 `HWC` 排列。
-- `kernel_order`：指定卷积核维度顺序为 `OIHW` 或 `HWIO` 排列。
+- `kernel_order`：指定卷积核维度顺序为 `OIHW` 或 `IOHW` 排列。
 
 ```python
 n1 = pb.IF(shape=(8, 28, 28), threshold=1)      # Input feature map: (8, 28, 28)
 n2 = pb.IF(shape=(16, 26, 26), threshold=1)     # Output feature map: (16, 26, 26)
 kernel = np.random.randint(-128, 128, size=(16, 8, 3, 3), dtype=np.int8) # OIHW
 
-conv2d = pb.Conv2d(n1, n2, kernel=kernel, stride=1, fm_order="CHW", kernel_order="OIHW", name="conv_1")
+conv2d = pb.Conv2d(n1, n2, kernel=kernel, stride=1, fm_order="CHW", kernel_order="OIHW", name="conv2d_1")
 ```
 
 ⚠️ `padding` 不支持，默认为0。
@@ -277,7 +294,7 @@ conv2d = pb.Conv2d(n1, n2, kernel=kernel, stride=1, fm_order="CHW", kernel_order
 
 对于非脉冲数据，我们需要将其进行脉冲编码，然后输入网络中进行计算。
 
-PAIBox提供了有状态与无状态编码器。其中，有状态编码器是指编码过程与时间有关，将输入数据编码到一段时间窗口内。而无状态编码器是指编码过程与时间无关。每个时间步，都可以根据输入直接进行编码。
+PAIBox提供了有状态与无状态编码器。其中，有状态编码器是指编码过程与时间有关，将输入数据编码到一段时间窗口内。而无状态编码器是指编码过程与时间无关，每个时间步，都可以根据输入数据进行编码。
 
 #### 无状态编码器
 
@@ -298,9 +315,11 @@ for t in range(20):
 
 #### 有状态编码器
 
-有状态编码器类别较多。但目前来看，使用传统思路进行训练的SNN网络不能使用与时间有关的有状态编码器进行训练。
+有状态编码器类别较多。PAIBox提供了几种有状态编码器：周期编码器 `PeriodicEncoder`、延迟编码器 `LatencyEncoder` 。
+
+##### 周期编码器
 
-PAIBox提供了一种有状态编码器，周期性编码器 `PeriodicEncoder`。它以一段脉冲序列为输入，将其循环地在每一个时间步输出。以下为一个简单实例：
+它以一段脉冲序列为输入，将其循环地在每一个时间步输出。以下为一个简单实例：
 
 ```python
 # 定义一段脉冲序列
@@ -319,6 +338,24 @@ for t in range(20):
 
 这将仿真20个时间步，周期性地获取输入的脉冲序列并将其输出。
 
+##### 延迟编码器
+
+根据输入数据 `x` 延迟发放脉冲的编码器。当刺激强度越大，发放时间越早，且存在最大脉冲发放时间 `T`。因此对于每一个输入数据，都能得到一段时间步长为 `T` 的脉冲序列，每段序列有且仅有一个脉冲发放。编码类型可为：`linear` 或 `log`。以下为一个简单实例：
+
+```python
+N = 6
+x = np.random.rand(N)
+T = 20
+
+le = pb.simulator.LatencyEncoder(T, "linear")
+
+out_spike = np.zeros((T, N), dtype=np.bool_)
+for t in range(T):
+    out_spike[t] = le(x)
+```
+
+具体编码原理参见：[SpikingJelly/延迟编码器](https://spikingjelly.readthedocs.io/zh-cn/latest/activation_based/2_encoding.html#id5)
+
 ### 输入节点
 
 为了支持多样的数据输入形式，同时标明网络模型的输入节点，PAIBox设计了输入节点这一组件。
@@ -453,7 +490,7 @@ print(output)
 
 PAIBox提供了一些常用编码器，编码器内部实现了 `__call__` 方法，因此可作为输入节点的输入使用。在作为输入节点的输入使用时，它与一般函数做为输入节点的输入使用存在差别。
 
-在例化 `InputProj` 时，输入节点的输入为编码器。在运行时，还需要通过设置 `inp.input`，**向输入节点输入待编码数据**，节点内部将完成泊松编码并输出。以泊松编码器为例：
+在例化 `InputProj` 时，输入节点的输入为编码器。在运行时，还需要通过设置 `inp.input`，**向输入节点输入待编码数据**，节点内部将完成编码并输出。以泊松编码器为例：
 
 ```python
 pe = pb.simulator.PoissonEncoder()                          # 例化泊松编码器

From d87e3f1662ed384e743496e200c7b580ca5a092e Mon Sep 17 00:00:00 2001
From: KafCoppelia <k740677208@gmail.com>
Date: Sun, 24 Mar 2024 14:49:39 +0800
Subject: [PATCH 38/68] =?UTF-8?q?=E2=9C=A8=20supported=201d=20convolution?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

---
 paibox/__init__.py            |  1 +
 paibox/synapses/__init__.py   |  3 +-
 paibox/synapses/base.py       | 54 ++++++++++++++++++++-
 paibox/synapses/conv_utils.py | 91 +++++++++++++++++++++++++++++++++--
 paibox/synapses/synapses.py   | 46 ++++++++++++++++--
 paibox/synapses/transforms.py | 60 +++++++++++++++++++++--
 6 files changed, 241 insertions(+), 14 deletions(-)

diff --git a/paibox/__init__.py b/paibox/__init__.py
index f66423e8..08c35d8f 100644
--- a/paibox/__init__.py
+++ b/paibox/__init__.py
@@ -12,6 +12,7 @@
 from .projection import InputProj as InputProj
 from .simulator import Probe as Probe
 from .simulator import Simulator as Simulator
+from .synapses import Conv1d as Conv1d
 from .synapses import Conv2d as Conv2d
 from .synapses import FullConn as FullConn
 from .synapses import GeneralConnType as SynConnType
diff --git a/paibox/synapses/__init__.py b/paibox/synapses/__init__.py
index 4a249c18..19470873 100644
--- a/paibox/synapses/__init__.py
+++ b/paibox/synapses/__init__.py
@@ -1,7 +1,8 @@
 from .base import RIGISTER_MASTER_KEY_FORMAT, SynSys
+from .synapses import Conv1d as Conv1d
 from .synapses import Conv2d as Conv2d
 from .synapses import FullConn as FullConn
 from .synapses import NoDecay as NoDecay
 from .transforms import GeneralConnType as GeneralConnType
 
-__all__ = ["Conv2d", "FullConn", "NoDecay", "GeneralConnType"]
+__all__ = ["Conv1d", "Conv2d", "FullConn", "NoDecay", "GeneralConnType"]
diff --git a/paibox/synapses/base.py b/paibox/synapses/base.py
index 309f92ec..0e9436ce 100644
--- a/paibox/synapses/base.py
+++ b/paibox/synapses/base.py
@@ -10,8 +10,8 @@
 from paibox.projection import InputProj
 from paibox.types import DataArrayType, SynOutType, WeightType
 
-from .conv_utils import _fm_ndim2_check, _KOrder4d, _Order3d
-from .transforms import AllToAll, Conv2dForward
+from .conv_utils import _fm_ndim1_check, _fm_ndim2_check, _KOrder3d, _KOrder4d, _Order2d, _Order3d
+from .transforms import AllToAll, Conv1dForward, Conv2dForward
 from .transforms import GeneralConnType as GConnType
 from .transforms import Identity, MaskedLinear, OneToOne, Transform
 
@@ -150,6 +150,56 @@ def __init__(
         self._set_comm(comm)
 
 
+class Conv1dSyn(FullConnectedSyn):
+    _spatial_ndim: ClassVar[int] = 1
+
+    def __init__(
+        self,
+        source: Union[NeuDyn, InputProj],
+        dest: Neuron,
+        kernel: np.ndarray,
+        stride: Tuple[int],
+        # padding: Tuple[int],
+        fm_order: _Order2d,
+        order: _KOrder3d,
+        name: Optional[str] = None,
+    ) -> None:
+        super().__init__(source, dest, name)
+
+        if kernel.ndim != self._spatial_ndim + 2:
+            raise ShapeError(
+                f"convolution kernel dimension must be {self._spatial_ndim + 2}, but got {kernel.ndim}."
+            )
+
+        if order == "IOL":
+            _kernel = kernel.transpose(1, 0, 2)
+        else:
+            _kernel = kernel.copy()
+
+        # O,I,L
+        out_channels, in_channels, kernel_l = _kernel.shape
+
+        # C,L
+        in_ch, in_l = _fm_ndim1_check(source.shape_out, fm_order)
+        out_ch, out_l = _fm_ndim1_check(dest.shape_out, fm_order)
+
+        if in_ch != in_channels:
+            raise ShapeError(f"input channels mismatch: {in_ch} != {in_channels}.")
+
+        if out_ch != out_channels:
+            raise ShapeError(f"output channels mismatch: {out_ch} != {out_channels}.")
+
+        # If padding is considered, the implementation of convolution unrolling
+        # is extremely complex, so fix it.
+        padding = (0,)
+
+        assert (in_l + 2 * padding[0] - kernel_l) // stride[0] + 1 == out_l
+
+        comm = Conv1dForward((in_l,), (out_l,), _kernel, stride, padding, fm_order)
+
+        self.comm = comm
+
+
 class Conv2dSyn(FullConnectedSyn):
     _spatial_ndim: ClassVar[int] = 2
 
diff --git a/paibox/synapses/conv_utils.py b/paibox/synapses/conv_utils.py
index 322d0867..87adef87 100644
--- a/paibox/synapses/conv_utils.py
+++ b/paibox/synapses/conv_utils.py
@@ -21,12 +21,14 @@
 _Size3Type = _Tuple3Type[int]
 
 SizeAnyType = Tuple[int, ...]
+Size1Type = Tuple[int]
 Size2Type = Tuple[int, int]
 Size3Type = Tuple[int, int, int]
 
-_Order2d = Literal["HW", "HW"]  # Feature map order in 2d
+_Order2d = Literal["CL", "LC"]  # Feature map order in 2d
 _Order3d = Literal["CHW", "HWC"]  # Feature map order in 3d
-_KOrder4d = Literal["OIHW", "IOHW"]  # Kernel order
+_KOrder3d = Literal["OIL", "IOL"]  # Kernel order in 3d
+_KOrder4d = Literal["OIHW", "IOHW"]  # Kernel order in 4d
 
 
 def _ntuple(x, n: int) -> Tuple[Any, ...]:
@@ -49,7 +51,7 @@ def _fm_ndim1_check(fm_shape: SizeAnyType, fm_order: _Order2d) -> Size2Type:
     if len(fm_shape) == 1:
         channels, l = (1,) + fm_shape
     else:
-        if fm_order is "HW":
+        if fm_order == "CL":
             channels, l = fm_shape
         else:
             l, channels = fm_shape
@@ -72,6 +74,37 @@ def _fm_ndim2_check(fm_shape: SizeAnyType, fm_order: _Order3d) -> Size3Type:
     return channels, h, w
 
 
+def _conv1d_unroll(
+    in_shape: Size1Type,
+    out_shape: Size1Type,
+    kernel: WeightType,
+    stride: Size1Type,
+    # padding: Size1Type,
+):
+    """Unroll the convolution kernel of 1d convolution into a matrix."""
+    cout, cin, kl = kernel.shape
+    il = in_shape[0]
+    ol = out_shape[0]
+
+    w_unrolled = np.zeros((cin * il, cout * ol), dtype=kernel.dtype)
+    zeros_image = np.zeros((cin * il, cout, ol), dtype=kernel.dtype)
+
+    for i in range(ol):
+        for ch_idx in np.ndindex(kernel.shape[:2]):
+            # [0] -> o_ch, [1] -> i_ch
+            zeros_image[
+                i * stride[0] + ch_idx[1] * il : i * stride[0] + ch_idx[1] * il + kl,
+                ch_idx[0],
+                i,
+            ] = kernel[ch_idx[0], ch_idx[1], :]
+
+        t = zeros_image[:, :, i].T
+        for o_ch in range(cout):
+            w_unrolled[:, i + o_ch * ol] = t[o_ch].flatten()
+
+    return w_unrolled
+
+
 def _conv2d_unroll(
     in_shape: Size2Type,
     out_shape: Size2Type,
@@ -117,6 +150,39 @@ def _conv2d_unroll(
     return w_unrolled
 
 
+def _conv1d_faster(
+    x_cl: np.ndarray,
+    out_shape: Size1Type,
+    kernel: WeightType,
+    stride: Size1Type,
+    padding: Size1Type,
+) -> SynOutType:
+    xc, xl = x_cl.shape
+
+    # (O, I, L)
+    cout, cin, kl = kernel.shape
+    assert xc == cin
+
+    x_padded = np.pad(x_cl, ((0, 0), (padding[0], padding[0])), mode="constant")
+
+    assert (xl + padding[0] * 2 - kl) // stride[0] + 1 == out_shape[0]
+
+    # kernel: (cout, cin, kl) -> (cin*kl, cout)
+    col_kernel = kernel.transpose(1, 2, 0).reshape(-1, cout)
+
+    # padded: (cin, xl+2*p[0]-kl) -> (ol, cin*kl)
+    col_fm = _1d_im2col(x_padded, out_shape[0], kl, stride)
+
+    # out = np.zeros((cout,) + out_shape, dtype=np.int64)
+    # (ol, cin*kl) * (cin*kl, cout) = (ol, cout)
+    out = col_fm @ col_kernel  # + self.bias
+
+    # (ol, cout) -> (ol, cout) -> (cout, ol)
+    out = out.reshape(out_shape + (cout,)).T
+
+    return out.astype(np.int32)
+
+
 def _conv2d_faster(
     x_chw: np.ndarray,
     out_shape: Size2Type,
@@ -143,7 +209,7 @@ def _conv2d_faster(
     col_kernel = kernel.transpose(1, 2, 3, 0).reshape(-1, cout)
 
     # padded: (cin, xh+2*p[0]-kh, xw+2*p[1]-kw) -> (oh*ow, cin*kh*kw)
-    col_fm = _im2col(x_padded, out_shape[0], out_shape[1], kh, kw, stride)
+    col_fm = _2d_im2col(x_padded, out_shape[0], out_shape[1], kh, kw, stride)
 
     # out = np.zeros((cout,) + out_shape, dtype=np.int64)
     # (oh*ow, cin*kh*kw) * (cin*kh*kw, cout) = (oh*ow, cout)
@@ -155,7 +221,22 @@ def _conv2d_faster(
     return out.astype(np.int32)
 
 
-def _im2col(
+def _1d_im2col(
+    x_padded: np.ndarray, ol: int, kl: int, stride: Size1Type
+) -> NDArray[np.int64]:
+    cols = np.zeros((ol, x_padded.shape[0] * kl), dtype=np.int64)
+
+    _, pl = x_padded.shape
+
+    idx = 0
+    for i in range(0, pl - kl + 1, stride[0]):
+        cols[idx] = x_padded[:, i : i + kl].reshape(-1)
+        idx += 1
+
+    return cols
+
+
+def _2d_im2col(
     x_padded: np.ndarray, oh: int, ow: int, kh: int, kw: int, stride: Size2Type
 ) -> NDArray[np.int64]:
     cols = np.zeros((oh * ow, x_padded.shape[0] * kh * kw), dtype=np.int64)
diff --git a/paibox/synapses/synapses.py b/paibox/synapses/synapses.py
index edb0436f..ac666bea 100644
--- a/paibox/synapses/synapses.py
+++ b/paibox/synapses/synapses.py
@@ -8,11 +8,20 @@
 from paibox.projection import InputProj
 from paibox.types import DataArrayType
 
-from .base import Conv2dSyn, FullConnSyn
-from .conv_utils import _KOrder4d, _Order3d, _pair, _Size2Type
+from .base import Conv1dSyn, Conv2dSyn, FullConnSyn
+from .conv_utils import (
+    _KOrder3d,
+    _KOrder4d,
+    _Order2d,
+    _Order3d,
+    _pair,
+    _single,
+    _Size1Type,
+    _Size2Type,
+)
 from .transforms import GeneralConnType as GConnType
 
-__all__ = ["FullConn", "Conv2d"]
+__all__ = ["FullConn", "Conv1d", "Conv2d"]
 
 
 class FullConn(FullConnSyn):
@@ -54,6 +63,37 @@ def __init__(
         super().__init__(source, dest, weights, conn_type=conn_type, name=name)
 
 
+class Conv1d(Conv1dSyn):
+    def __init__(
+        self,
+        source: Union[Neuron, InputProj],
+        dest: Neuron,
+        kernel: np.ndarray,
+        *,
+        stride: _Size1Type = 1,
+        # padding: _Size1Type = 0,
+        fm_order: _Order2d = "CL",
+        kernel_order: _KOrder3d = "OIL",
+        name: Optional[str] = None,
+    ) -> None:
+        if fm_order not in ("CL", "LC"):
+            raise ValueError(f"feature map order must be 'CL' or 'LC'.")
+
+        if kernel_order not in ("OIL", "IOL"):
+            raise ValueError(f"kernel order must be 'OIL' or 'IOL'.")
+
+        super().__init__(
+            source,
+            dest,
+            kernel,
+            _single(stride),
+            # _single(padding),
+            fm_order,
+            kernel_order,
+            name=name,
+        )
+
+
 class Conv2d(Conv2dSyn):
     def __init__(
         self,
diff --git a/paibox/synapses/transforms.py b/paibox/synapses/transforms.py
index ce75e60d..3cd2bd5e 100644
--- a/paibox/synapses/transforms.py
+++ b/paibox/synapses/transforms.py
@@ -9,7 +9,16 @@
 from paibox.types import DataArrayType, IntScalarType, SynOutType, WeightType
 from paibox.utils import is_shape
 
-from .conv_utils import Size2Type, _conv2d_faster, _conv2d_unroll, _Order3d
+from .conv_utils import (
+    _conv1d_faster,
+    _conv1d_unroll,
+    _conv2d_faster,
+    _conv2d_unroll,
+    _Order2d,
+    _Order3d,
+    Size1Type,
+    Size2Type,
+)
 
 __all__ = [
     "GeneralConnType",
@@ -17,6 +26,7 @@
     "AllToAll",
     "Identity",
     "MaskedLinear",
+    "Conv1dForward",
     "Conv2dForward",
 ]
 
@@ -231,6 +241,51 @@ def connectivity(self):
         return self.weights.astype(self.conn_dtype)
 
 
+class Conv1dForward(Transform):
+    def __init__(
+        self,
+        in_shape: Size1Type,
+        out_shape: Size1Type,
+        kernel: np.ndarray,
+        stride: Size1Type,
+        padding: Size1Type,
+        fm_order: _Order2d,
+    ) -> None:
+        self.in_shape = in_shape
+        self.out_shape = out_shape
+        self.stride = stride
+        self.padding = padding
+        self.fm_order = fm_order
+
+        _w = kernel.astype(np.int8)
+        super().__init__(_w)
+
+    def __call__(self, x: np.ndarray, *args, **kwargs) -> SynOutType:
+        cin = self.weights.shape[1]
+
+        if self.fm_order == "LC":
+            # (N,) -> (L, C) -> (C, L)
+            _x = x.reshape(self.in_shape + (cin,)).T
+        else:
+            _x = x.reshape((cin,) + self.in_shape)
+
+        o_conv1d = _conv1d_faster(
+            _x,
+            self.out_shape,
+            self.weights,
+            self.stride,
+            self.padding,
+        )
+
+        return o_conv1d.flatten()
+
+    @property
+    def connectivity(self):
+        return _conv1d_unroll(
+            self.in_shape, self.out_shape, self.weights, self.stride
+        ).astype(self.conn_dtype)
+
+
 class Conv2dForward(Transform):
     def __init__(
         self,
@@ -255,8 +310,7 @@ def __call__(self, x: np.ndarray, *args, **kwargs) -> SynOutType:
 
         if self.fm_order == "HWC":
             # (N,) -> (H, W, C) -> (C, H, W)
-            _x = x.reshape(self.in_shape + (cin,))
-            _x = _x.transpose(2, 0, 1)
+            _x = x.reshape(self.in_shape + (cin,)).transpose(2, 0, 1)
         else:
             _x = x.reshape((cin,) + self.in_shape)
 

From 44349c110027d02e463419447d1eff280dd2d140 Mon Sep 17 00:00:00 2001
From: KafCoppelia <k740677208@gmail.com>
Date: Sun, 24 Mar 2024 14:49:56 +0800
Subject: [PATCH 39/68] =?UTF-8?q?=E2=9C=85=20added=20tests=20for=201d=20co?=
 =?UTF-8?q?nv?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

---
 tests/synapses/test_synapses.py   | 50 +++++++++++++++++
 tests/synapses/test_transforms.py | 92 +++++++++++++++++++++++++++++++
 2 files changed, 142 insertions(+)

diff --git a/tests/synapses/test_synapses.py b/tests/synapses/test_synapses.py
index 44294871..3c60f41d 100644
--- a/tests/synapses/test_synapses.py
+++ b/tests/synapses/test_synapses.py
@@ -260,6 +260,31 @@ def test_FullConn_MatConn(self, n1, n2):
 
 
 class TestConv2d:
+    def test_Conv1d_instance(self):
+        in_shape = (32,)
+        kernel_size = (5,)
+        stride = 2
+        out_shape = ((32 - 5) // 2 + 1,)
+        in_channels = 8
+        out_channels = 16
+        korder = "IOL"
+
+        n1 = pb.IF((in_channels,) + in_shape, 3)  # CL
+        n2 = pb.IF((out_channels,) + out_shape, 3)
+
+        weight = np.random.randint(
+            -128, 128, size=(in_channels, out_channels) + kernel_size, dtype=np.int8
+        )
+        s1 = pb.Conv1d(
+            n1, n2, weight, stride=stride, fm_order="CL", kernel_order=korder
+        )
+
+        assert s1.num_in == in_channels * shape2num(in_shape)
+        assert s1.connectivity.shape == (
+            in_channels * shape2num(in_shape),
+            out_channels * shape2num(out_shape),
+        )
+
     def test_Conv2d_instance(self):
         in_shape = (32, 32)
         kernel_size = (5, 5)
@@ -285,6 +310,31 @@ def test_Conv2d_instance(self):
             out_channels * shape2num(out_shape),
         )
 
+    def test_Conv1d_inchannel_omitted(self):
+        in_shape = (32,)
+        kernel_size = (5,)
+        stride = 2
+        out_shape = ((32 - 5) // 2 + 1,)
+        in_channels = 1  # omit it
+        out_channels = 4
+        korder = "IOL"
+
+        n1 = pb.IF(in_shape, 3)  # L, (in_channels=1)
+        n2 = pb.IF((out_channels,) + out_shape, 3)
+
+        weight = np.random.randint(
+            -128, 128, size=(in_channels, out_channels) + kernel_size, dtype=np.int8
+        )
+        s1 = pb.Conv1d(
+            n1, n2, weight, stride=stride, fm_order="CL", kernel_order=korder
+        )
+
+        assert s1.num_in == in_channels * shape2num(in_shape)
+        assert s1.connectivity.shape == (
+            in_channels * shape2num(in_shape),
+            out_channels * shape2num(out_shape),
+        )
+
     def test_Conv2d_inchannel_omitted(self):
         in_shape = (32, 32)
         kernel_size = (5, 5)
diff --git a/tests/synapses/test_transforms.py b/tests/synapses/test_transforms.py
index 3e78fc6f..86664862 100644
--- a/tests/synapses/test_transforms.py
+++ b/tests/synapses/test_transforms.py
@@ -186,6 +186,98 @@ def test_MaskedLinear_conn(self, shape, x, weights, expected_dtype):
         assert np.array_equal(y, expected)
         assert f.connectivity.shape == shape
 
+    @staticmethod
+    def _conv1d_golden(
+        x: np.ndarray,
+        out_shape: Tuple[int],
+        kernel: np.ndarray,
+        stride: Tuple[int],
+        padding: Tuple[int],
+        fm_order: str,
+    ):
+        cout, cin, kl = kernel.shape
+
+        if fm_order == "LC":
+            _x = x.T
+        else:
+            _x = x.copy()
+
+        xcin, il = _x.shape
+
+        assert cin == xcin
+
+        ol = (il - kl + 2 * padding[0]) // stride[0] + 1
+
+        assert ol == out_shape[0]
+
+        out = np.zeros((cout,) + out_shape, dtype=np.int64)
+
+        x_padded = np.pad(_x, (0, padding[0]), mode="constant")
+
+        for o in range(cout):
+            for i in range(cin):
+                conv_result = np.zeros((ol,), dtype=np.int64)
+                for l in range(ol):
+                    window = x_padded[i, l * stride[0] : l * stride[0] + kl]
+                    conv_result[l] = np.sum(window * kernel[o, i, :])
+
+                out[o] += conv_result
+
+        return out
+
+    @pytest.mark.parametrize(
+        "in_shape, in_channels, out_channels, kernel_size, stride, padding, fm_order",
+        # Padding is fixed at (0, 0)
+        [
+            ((28,), 16, 8, (3,), (1,), (0,), "CL"),
+            ((28,), 24, 12, (3,), (2,), (0,), "CL"),
+            ((28,), 24, 12, (5,), (2,), (0,), "CL"),
+            ((16,), 8, 16, (3,), (2,), (0,), "CL"),
+            ((28,), 16, 8, (3,), (1,), (0,), "LC"),
+            ((24,), 8, 8, (3,), (2,), (0,), "LC"),
+            ((24,), 8, 16, (7,), (2,), (0,), "LC"),
+            ((32,), 4, 12, (5,), (1,), (0,), "LC"),
+        ],
+    )
+    def test_Conv1dForward(
+        self,
+        in_shape,
+        in_channels,
+        out_channels,
+        kernel_size,
+        stride,
+        padding,
+        fm_order,
+    ):
+        kernel = np.random.randint(
+            -128, 127, size=(out_channels, in_channels) + kernel_size, dtype=np.int8
+        )
+
+        out_shape = ((in_shape[0] + 2 * padding[0] - kernel_size[0]) // stride[0] + 1,)
+
+        f = Conv1dForward(in_shape, out_shape, kernel, stride, padding, fm_order)
+
+        if fm_order == "CL":
+            fm_shape = (in_channels,) + in_shape
+        else:
+            fm_shape = in_shape + (in_channels,)
+
+        x = np.random.randint(0, 2, size=fm_shape, dtype=np.bool_)
+        xf = x.copy().flatten()
+
+        y = f(xf)
+        expected = self._conv1d_golden(x, out_shape, kernel, stride, padding, fm_order)
+
+        # Flattened output
+        y = y.reshape((out_channels,) + out_shape)
+
+        assert y.shape == expected.shape
+        assert np.array_equal(y, expected)
+        assert f.connectivity.shape == (
+            shape2num((kernel.shape[1],) + in_shape),
+            shape2num((kernel.shape[0],) + out_shape),
+        )
+
     @staticmethod
     def _conv2d_golden(
         x: np.ndarray,

From 231629c01b69ae7a5cbe04874080f9c7f6d91c53 Mon Sep 17 00:00:00 2001
From: KafCoppelia <k740677208@gmail.com>
Date: Sun, 24 Mar 2024 16:29:56 +0800
Subject: [PATCH 40/68] =?UTF-8?q?=F0=9F=9A=9A=20renamed=20files?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

---
 paibox/base.py                   | 2 +-
 paibox/mixin.py                  | 2 +-
 paibox/{generic.py => naming.py} | 0
 tests/backend/conftest.py        | 2 +-
 4 files changed, 3 insertions(+), 3 deletions(-)
 rename paibox/{generic.py => naming.py} (100%)

diff --git a/paibox/base.py b/paibox/base.py
index e793ce7e..2a75e2b4 100644
--- a/paibox/base.py
+++ b/paibox/base.py
@@ -10,7 +10,7 @@
     from typing_extensions import TypeAlias
 
 from .collector import Collector
-from .generic import get_unique_name, is_name_unique
+from .naming import get_unique_name, is_name_unique
 from .mixin import ReceiveInputProj, StatusMemory, TimeRelatedNode
 from .node import NodeDict, NodeList
 from .types import WeightType
diff --git a/paibox/mixin.py b/paibox/mixin.py
index 391e3a99..824373fa 100644
--- a/paibox/mixin.py
+++ b/paibox/mixin.py
@@ -9,7 +9,7 @@
 
 from .context import _FRONTEND_CONTEXT
 from .exceptions import RegisterError
-from .generic import get_unique_name
+from .naming import get_unique_name
 from .node import NodeDict
 
 _T = TypeVar("_T")
diff --git a/paibox/generic.py b/paibox/naming.py
similarity index 100%
rename from paibox/generic.py
rename to paibox/naming.py
diff --git a/tests/backend/conftest.py b/tests/backend/conftest.py
index c973b930..bf1bcf66 100644
--- a/tests/backend/conftest.py
+++ b/tests/backend/conftest.py
@@ -24,7 +24,7 @@
 import paibox as pb
 from paibox.backend.conf_template import CoreConfig, CorePlacementConfig, NeuronConfig
 from paibox.backend.routing import RoutingCluster
-from paibox.generic import clear_name_cache
+from paibox.naming import clear_name_cache
 from paibox.node import NodeList
 from tests.conftest import ParametrizedTestData
 

From 1a090e8a19ab139f7934416ad1edccb3496f2bd1 Mon Sep 17 00:00:00 2001
From: KafCoppelia <k740677208@gmail.com>
Date: Sun, 24 Mar 2024 16:47:22 +0800
Subject: [PATCH 41/68] =?UTF-8?q?=F0=9F=93=9D=20updated=20todo=20&=20chang?=
 =?UTF-8?q?elog?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

---
 CHANGELOG.md   | 10 +++++++++-
 README.md      |  4 +++-
 TODO.md        | 11 ++++++-----
 pyproject.toml |  2 +-
 4 files changed, 19 insertions(+), 8 deletions(-)

diff --git a/CHANGELOG.md b/CHANGELOG.md
index f948a9eb..f36e1625 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -1,6 +1,10 @@
+## v1.0.0a2
+
+- 修复 `paicorelib` 错误的导入与版本约依赖
+
 ## v1.0.0a3
 
-- 添加了示例程序，MNIST双输入端口两层全连接网络
+- 添加示例
 - 修复工作流版本错误
 - 修复神经元膜电位溢出处理错误
 - 修复神经元分组的计数错误
@@ -18,3 +22,7 @@
 ## v1.0.0a6
 
 - 新增 `Always1Neuron` 神经元，该神经元将在工作期间持续输出1，不得单独存在，需存在前向突触与其连接。
+
+## v1.0.0a7
+
+- 支持全展开1D卷积算子构建与部署（`padding` 不支持）
diff --git a/README.md b/README.md
index a5ce6bf5..b759f506 100644
--- a/README.md
+++ b/README.md
@@ -8,7 +8,7 @@
     <a href="https://github.com/PAICookers/PAIBox/blob/master/pyproject.toml">
         <img src="https://img.shields.io/pypi/pyversions/paibox">
     </a>
-    <a href="https://github.com/PAICookers/PAIBox/releases/tag/v1.0.0a6">
+    <a href="https://github.com/PAICookers/PAIBox/releases/tag/v1.0.0a7">
         <img src="https://img.shields.io/github/v/release/PAICookers/PAIBox?include_prereleases&color=orange">
     </a>
     <a href="https://www.codefactor.io/repository/github/PAICookers/PAIBox">
@@ -24,3 +24,5 @@ PAIBox使用指南：[Guide-of-PAIBox](docs/Guide-of-PAIBox.md)
 高效编写测试项目指南：[Guide-of-Test](docs/Guide-of-Test.md)
 
 TODO：[TODO List](./TODO.md)
+
+[Changelog](./CHANGELOG.md)
diff --git a/TODO.md b/TODO.md
index f21de321..b372fd09 100644
--- a/TODO.md
+++ b/TODO.md
@@ -12,17 +12,18 @@
 
 - 功能模块支持
 
-  - [x] 全展开2D卷积算子
-  - [ ] 半折叠2D卷积算子
+  - [x] 全展开1D卷积
+  - [x] 全展开2D卷积
+  - [ ] 半折叠2D卷积
   - [ ] 残差结构
-  - [ ] 逻辑算子：与、或、非
+  - [ ] 逻辑与、或、非
+  - [ ] 加、减
   - [ ] 二维矩阵转置
-
+  - [ ] 三维矩阵转置
 - 多层次结构网络组件的发现、数据流验证与后端解析
 
   - [x] 对有层次结构（子网络例化复用等情形）的网络模型，实现在所有层次上网络组件的发现、数据流与后端解析实现
   - [ ] 局部连接包装成单个算子，实现在所有层次上网络组件的发现、数据流与后端解析实现。考虑用户调用接口
-
 - 带有约束的路由坐标分配
 
   - [ ] 支持芯片阵列部署
diff --git a/pyproject.toml b/pyproject.toml
index 5c3fae22..5c45b150 100644
--- a/pyproject.toml
+++ b/pyproject.toml
@@ -1,6 +1,6 @@
 [tool.poetry]
 name = "paibox"
-version = "1.0.0a6"
+version = "1.0.0a7"
 description = "New toolbox of PAICORE 2.0."
 authors = ["Ziru Pan <zrpan@stu.pku.edu.cn>"]
 maintainers = ["Ziru Pan <zrpan@stu.pku.edu.cn>"]

From 83f91ee524f60cc08c80924595b0605dbe4fce99 Mon Sep 17 00:00:00 2001
From: "pre-commit-ci[bot]"
 <66853113+pre-commit-ci[bot]@users.noreply.github.com>
Date: Sun, 24 Mar 2024 08:47:55 +0000
Subject: [PATCH 42/68] :rotating_light: auto fix by pre-commit hooks

---
 TODO.md                       | 2 ++
 paibox/base.py                | 2 +-
 paibox/mixin.py               | 1 +
 paibox/simulator/encoder.py   | 1 +
 paibox/synapses/base.py       | 9 ++++++++-
 paibox/synapses/transforms.py | 4 ++--
 paibox/types.py               | 4 +++-
 7 files changed, 18 insertions(+), 5 deletions(-)

diff --git a/TODO.md b/TODO.md
index b372fd09..930a88f3 100644
--- a/TODO.md
+++ b/TODO.md
@@ -20,10 +20,12 @@
   - [ ] 加、减
   - [ ] 二维矩阵转置
   - [ ] 三维矩阵转置
+
 - 多层次结构网络组件的发现、数据流验证与后端解析
 
   - [x] 对有层次结构（子网络例化复用等情形）的网络模型，实现在所有层次上网络组件的发现、数据流与后端解析实现
   - [ ] 局部连接包装成单个算子，实现在所有层次上网络组件的发现、数据流与后端解析实现。考虑用户调用接口
+
 - 带有约束的路由坐标分配
 
   - [ ] 支持芯片阵列部署
diff --git a/paibox/base.py b/paibox/base.py
index 2a75e2b4..e3250d00 100644
--- a/paibox/base.py
+++ b/paibox/base.py
@@ -10,8 +10,8 @@
     from typing_extensions import TypeAlias
 
 from .collector import Collector
-from .naming import get_unique_name, is_name_unique
 from .mixin import ReceiveInputProj, StatusMemory, TimeRelatedNode
+from .naming import get_unique_name, is_name_unique
 from .node import NodeDict, NodeList
 from .types import WeightType
 
diff --git a/paibox/mixin.py b/paibox/mixin.py
index 824373fa..7af5f923 100644
--- a/paibox/mixin.py
+++ b/paibox/mixin.py
@@ -42,6 +42,7 @@ def wrapper(*args, **kwargs):
 
 def check(attr):
     """Decorate function with this to check whether the object has an attribute with the given name."""
+
     def decorator(method):
 
         @wraps(method)
diff --git a/paibox/simulator/encoder.py b/paibox/simulator/encoder.py
index 87ebb3bf..ff3f6254 100644
--- a/paibox/simulator/encoder.py
+++ b/paibox/simulator/encoder.py
@@ -2,6 +2,7 @@
 from typing import Literal, Optional
 
 import numpy as np
+
 from paibox.mixin import StatusMemory
 from paibox.types import SpikeType
 
diff --git a/paibox/synapses/base.py b/paibox/synapses/base.py
index 0e9436ce..fc35ecdf 100644
--- a/paibox/synapses/base.py
+++ b/paibox/synapses/base.py
@@ -10,7 +10,14 @@
 from paibox.projection import InputProj
 from paibox.types import DataArrayType, SynOutType, WeightType
 
-from .conv_utils import _fm_ndim1_check, _fm_ndim2_check, _KOrder3d, _KOrder4d, _Order2d, _Order3d
+from .conv_utils import (
+    _fm_ndim1_check,
+    _fm_ndim2_check,
+    _KOrder3d,
+    _KOrder4d,
+    _Order2d,
+    _Order3d,
+)
 from .transforms import AllToAll, Conv1dForward, Conv2dForward
 from .transforms import GeneralConnType as GConnType
 from .transforms import Identity, MaskedLinear, OneToOne, Transform
diff --git a/paibox/synapses/transforms.py b/paibox/synapses/transforms.py
index 3cd2bd5e..2aaa7329 100644
--- a/paibox/synapses/transforms.py
+++ b/paibox/synapses/transforms.py
@@ -10,14 +10,14 @@
 from paibox.utils import is_shape
 
 from .conv_utils import (
+    Size1Type,
+    Size2Type,
     _conv1d_faster,
     _conv1d_unroll,
     _conv2d_faster,
     _conv2d_unroll,
     _Order2d,
     _Order3d,
-    Size1Type,
-    Size2Type,
 )
 
 __all__ = [
diff --git a/paibox/types.py b/paibox/types.py
index da6b2af0..25b2e8e0 100644
--- a/paibox/types.py
+++ b/paibox/types.py
@@ -75,4 +75,6 @@ def __ior__(self, other: Iterable[Any]) -> "OrderedSet[_T]":
         return self
 
     def __hash__(self) -> NoReturn:
-        raise TypeError("'OrderedSet' is not hashable (use 'FrozenOrderedSet' instead).")
+        raise TypeError(
+            "'OrderedSet' is not hashable (use 'FrozenOrderedSet' instead)."
+        )

From 23b07ad70726ac5342d252ebe3040c219ff658be Mon Sep 17 00:00:00 2001
From: KafCoppelia <k740677208@gmail.com>
Date: Mon, 25 Mar 2024 20:19:24 +0800
Subject: [PATCH 43/68] =?UTF-8?q?=E2=AC=86=EF=B8=8F=20=20bump=20numpy=20>?=
 =?UTF-8?q?=3D=201.24?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

---
 docs/Guide-of-PAIBox.md | 3 +--
 poetry.lock             | 2 +-
 pyproject.toml          | 2 +-
 3 files changed, 3 insertions(+), 4 deletions(-)

diff --git a/docs/Guide-of-PAIBox.md b/docs/Guide-of-PAIBox.md
index bd78f9f8..005126eb 100644
--- a/docs/Guide-of-PAIBox.md
+++ b/docs/Guide-of-PAIBox.md
@@ -17,7 +17,7 @@ poetry install
 ```toml
 python = "^3.8"
 pydantic = "^2.0"
-numpy = "^1.23.0"
+numpy = "^1.24.0"
 paicorelib = "0.0.13"
 ```
 
@@ -227,7 +227,6 @@ s1= pb.FullConn(source=n1, dest=n2, weights=weight1, conn_type=pb.SynConnType.Al
   ```
 
   其权重以标量的形式储存。
-
 - 数组：尺寸要求为 `(N2,)`，可以自定义每组对应神经元之间的连接权重。如下例所示，设置 `weights` 为 `[1, 2, 3, 4, 5]`，
 
   ```python
diff --git a/poetry.lock b/poetry.lock
index d21a7d00..103cbcd7 100644
--- a/poetry.lock
+++ b/poetry.lock
@@ -607,4 +607,4 @@ reference = "tsinghua"
 [metadata]
 lock-version = "2.0"
 python-versions = "^3.8"
-content-hash = "6b533f29e8de8c75ca36a4885b25f8dca69422b7701d6271cdcdc572781bbd4d"
+content-hash = "e9d4e900216862445287836ea2d3790f942e612c2c95a9429b135fc40e802969"
diff --git a/pyproject.toml b/pyproject.toml
index 5c45b150..4fde8d11 100644
--- a/pyproject.toml
+++ b/pyproject.toml
@@ -34,7 +34,7 @@ exclude = ["paibox/experimental"]
 [tool.poetry.dependencies]
 python = "^3.8"
 pydantic = "^2.0"
-numpy = "^1.23.0"
+numpy = "^1.24.0"
 paicorelib = "0.0.13"
 
 [tool.poetry.group.test]

From 15cdb83b7bc9d95ddf2b9265d7c8f3a896f96f07 Mon Sep 17 00:00:00 2001
From: KafCoppelia <k740677208@gmail.com>
Date: Mon, 25 Mar 2024 20:19:32 +0800
Subject: [PATCH 44/68] =?UTF-8?q?=F0=9F=93=9D=20updated=20TODO?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

---
 TODO.md | 14 +++++++-------
 1 file changed, 7 insertions(+), 7 deletions(-)

diff --git a/TODO.md b/TODO.md
index 930a88f3..a60d3a7b 100644
--- a/TODO.md
+++ b/TODO.md
@@ -14,18 +14,18 @@
 
   - [x] 全展开1D卷积
   - [x] 全展开2D卷积
-  - [ ] 半折叠2D卷积
-  - [ ] 残差结构
-  - [ ] 逻辑与、或、非
-  - [ ] 加、减
+  - [ ] 逻辑算子：与、或、非
   - [ ] 二维矩阵转置
   - [ ] 三维矩阵转置
-
+  - [ ] 全展开1D转置卷积
+  - [ ] 全展开2D转置卷积
+  - [ ] 脉冲加、减法
+  - [ ] 残差结构
+  - [ ] 半折叠2D卷积
 - 多层次结构网络组件的发现、数据流验证与后端解析
 
   - [x] 对有层次结构（子网络例化复用等情形）的网络模型，实现在所有层次上网络组件的发现、数据流与后端解析实现
-  - [ ] 局部连接包装成单个算子，实现在所有层次上网络组件的发现、数据流与后端解析实现。考虑用户调用接口
-
+  - [ ] 局部连接包装成单个算子，实现在所有层次上网络组件的发现、数据流与后端解析实现
 - 带有约束的路由坐标分配
 
   - [ ] 支持芯片阵列部署

From ec0cb1c0069b0fe701cb6f2a3a443184c2fb1150 Mon Sep 17 00:00:00 2001
From: KafCoppelia <k740677208@gmail.com>
Date: Tue, 26 Mar 2024 23:22:38 +0800
Subject: [PATCH 45/68] =?UTF-8?q?=F0=9F=90=9B=20bugfix:=20wrong=20sum=20in?=
 =?UTF-8?q?puts=20of=20neuron?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

---
 paibox/neuron/base.py  | 44 ++++++++----------------------------------
 paibox/neuron/utils.py | 28 +++++++++++++++++++++++++++
 paibox/types.py        |  1 +
 3 files changed, 37 insertions(+), 36 deletions(-)
 create mode 100644 paibox/neuron/utils.py

diff --git a/paibox/neuron/base.py b/paibox/neuron/base.py
index 32e7acec..f2346fc9 100644
--- a/paibox/neuron/base.py
+++ b/paibox/neuron/base.py
@@ -14,15 +14,14 @@
     MaxPoolingEnable,
     SpikeWidthFormat,
 )
-from typing_extensions import TypeAlias
 
 from paibox.base import NeuDyn
-from paibox.types import Shape, SpikeType
+from paibox.types import Shape, SpikeType, VoltageType
 from paibox.utils import as_shape, shape2num
 
-__all__ = ["Neuron"]
+from .utils import _vjt_overflow
 
-VoltageType: TypeAlias = NDArray[np.int32]
+__all__ = ["Neuron"]
 
 
 class MetaNeuron:
@@ -65,7 +64,6 @@ def __init__(
         self.leak_v: int = leak_v  # Signed 30-bit
         self.synaptic_integration_mode: SIM = synaptic_integration_mode
         self.bit_truncation: int = bit_truncation  # Unsigned 5-bit
-        self._vjt_init = 0  # Signed 30-bit. Fixed.
 
         # TODO These two config below are parameters of CORE.
         self._spike_width_format: SpikeWidthFormat
@@ -90,7 +88,6 @@ def _neuronal_charge(
                 `vjt` = `vjt_pre` + `_rho_w_ij` * \sum^{N-1}_{i=0} * x_i(t) * w_{i,j}
         """
         _rho_w_ij = 1  # Random synaptic integration enable, 0/1
-        xt = self.init_param(0).astype(np.int32)
 
         if self.synaptic_integration_mode is SIM.MODE_STOCHASTIC:
             raise NotImplementedError(
@@ -104,7 +101,7 @@ def _neuronal_charge(
 
         v_charged = np.add(vjt_pre, _v).astype(np.int32)
 
-        return v_charged
+        return _vjt_overflow(v_charged)  # Handle with overflow here
 
     def _neuronal_leak(self, vjt: VoltageType) -> VoltageType:
         r"""2. Leak integration.
@@ -356,7 +353,6 @@ def bias(self) -> int:
 
 class Neuron(MetaNeuron, NeuDyn):
     _excluded_vars = (
-        "_vjt_init",
         "vjt",
         "vj",
         "y",
@@ -443,11 +439,12 @@ def __init__(
         super(MetaNeuron, self).__init__(name)
 
         """Stateful attributes. Vector."""
-        self.set_memory("_vjt", self.init_param(self._vjt_init).astype(np.int32))
+        # Initial vjt is fixed at 0.
+        self.set_memory("_vjt", self.init_param(0).astype(np.int32))
         self.set_memory("_inner_spike", self.init_param(0).astype(np.bool_))
 
         # Not supported for attributes in ANN mode
-        self.set_memory("vj", self.init_param(self._vjt_init).astype(np.int32))
+        self.set_memory("vj", self.init_param(0).astype(np.int32))
         self.set_memory("y", self.init_param(0).astype(np.int32))
 
         """Auxiliary internal stateful attributes for debugging"""
@@ -493,10 +490,8 @@ def update(
         if x is None:
             x = self.sum_inputs()
 
-        incoming_v = _vjt_overflow(x)
-
         self._inner_spike, self._vjt, self._debug_thres_mode = super().update(
-            incoming_v, self._vjt
+            x, self._vjt
         )
 
         idx = (self.timestamp + self.delay_relative - 1) % HwConfig.N_TIMESLOT_MAX
@@ -575,26 +570,3 @@ def feature_map(self) -> SpikeType:
     @property
     def voltage(self) -> VoltageType:
         return self._vjt.reshape(self.varshape)
-
-
-VJT_MAX_LIMIT: int = 2**29 - 1
-VJT_MIN_LIMIT: int = -(2**29)
-VJT_LIMIT: int = 2**30
-
-
-def _vjt_overflow(x: np.ndarray) -> VoltageType:
-    """Handle the overflow of the membrane potential.
-
-    NOTE: If the incoming membrane potential (30-bit signed) overflows, the chip\
-        will automatically handle it. This behavior needs to be implemented in  \
-        simulation.
-    """
-    return np.where(
-        x > VJT_MAX_LIMIT,
-        x - VJT_LIMIT,
-        np.where(
-            x < VJT_MIN_LIMIT,
-            x + VJT_LIMIT,
-            x,
-        ),
-    ).astype(np.int32)
diff --git a/paibox/neuron/utils.py b/paibox/neuron/utils.py
new file mode 100644
index 00000000..880d15c5
--- /dev/null
+++ b/paibox/neuron/utils.py
@@ -0,0 +1,28 @@
+import numpy as np
+from paibox.types import VoltageType
+
+VJT_MAX_LIMIT: int = 2**29 - 1
+VJT_MIN_LIMIT: int = -(2**29)
+VJT_LIMIT: int = 2**30
+
+
+def _is_vjt_overflow(vjt: VoltageType) -> bool:
+    return bool(np.any(vjt > VJT_MAX_LIMIT) or np.any(vjt < VJT_MIN_LIMIT))
+
+
+def _vjt_overflow(vjt: VoltageType) -> VoltageType:
+    """Handle the overflow of the membrane potential.
+
+    NOTE: If the incoming membrane potential (30-bit signed) overflows, the chip\
+        will automatically handle it. This behavior needs to be implemented in  \
+        simulation.
+    """
+    return np.where(
+        vjt > VJT_MAX_LIMIT,
+        vjt - VJT_LIMIT,
+        np.where(
+            vjt < VJT_MIN_LIMIT,
+            vjt + VJT_LIMIT,
+            vjt,
+        ),
+    ).astype(np.int32)
diff --git a/paibox/types.py b/paibox/types.py
index 25b2e8e0..e2fd56af 100644
--- a/paibox/types.py
+++ b/paibox/types.py
@@ -25,6 +25,7 @@
 )
 SpikeType = NDArray[np.bool_]
 SynOutType = NDArray[np.int32]
+VoltageType = NDArray[np.int32]
 WeightType = NDArray[np.int8]  # raw int8 weights
 
 _T = TypeVar("_T")

From 2a80a769cc53bf8d2ab05193ecb751159611a979 Mon Sep 17 00:00:00 2001
From: "pre-commit-ci[bot]"
 <66853113+pre-commit-ci[bot]@users.noreply.github.com>
Date: Mon, 1 Apr 2024 16:58:20 +0000
Subject: [PATCH 46/68] :arrow_up: auto update by pre-commit hooks
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

updates:
- [github.com/psf/black: 24.2.0 → 24.3.0](https://github.com/psf/black/compare/24.2.0...24.3.0)
- [github.com/python-poetry/poetry: 1.7.1 → 1.8.0](https://github.com/python-poetry/poetry/compare/1.7.1...1.8.0)
---
 .pre-commit-config.yaml | 4 ++--
 1 file changed, 2 insertions(+), 2 deletions(-)

diff --git a/.pre-commit-config.yaml b/.pre-commit-config.yaml
index 67f8991b..8256c9c3 100644
--- a/.pre-commit-config.yaml
+++ b/.pre-commit-config.yaml
@@ -13,7 +13,7 @@ repos:
         stages: [commit]
 
   - repo: https://github.com/psf/black
-    rev: 24.2.0
+    rev: 24.3.0
     hooks:
       - id: black
         stages: [commit]
@@ -40,7 +40,7 @@ repos:
         args: [--pytest-test-first]
 
   - repo: https://github.com/python-poetry/poetry
-    rev: 1.7.1
+    rev: 1.8.0
     hooks:
       - id: poetry-check
       - id: poetry-lock

From 48e78d543cda339aef587b4ebf76ca2f44105009 Mon Sep 17 00:00:00 2001
From: KafCoppelia <k740677208@gmail.com>
Date: Tue, 2 Apr 2024 00:17:28 +0800
Subject: [PATCH 47/68] =?UTF-8?q?=F0=9F=90=9B=20bugfix:=20treat=20weights?=
 =?UTF-8?q?=20as=208=20bit=20if=20weight=5Fbit=5Fopt=20is=20diabled?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

---
 paibox/synapses/transforms.py | 17 +++++++++--------
 1 file changed, 9 insertions(+), 8 deletions(-)

diff --git a/paibox/synapses/transforms.py b/paibox/synapses/transforms.py
index 2aaa7329..2707d88c 100644
--- a/paibox/synapses/transforms.py
+++ b/paibox/synapses/transforms.py
@@ -70,15 +70,16 @@ def _get_weight_precision(weight: np.ndarray, enable_wp_opt: bool) -> WP:
     if _max > MAX_INT8 or _min < MIN_INT8:
         raise ValueError(f"weight precision out of range [{_min}, {_max}].")
 
+    # If weight precision opt is disabled, return WP8 directly.
+    if not enable_wp_opt:
+        return WP.WEIGHT_WIDTH_8BIT
+
     if _max <= MAX_INT1 and _min >= MIN_INT1:
         return WP.WEIGHT_WIDTH_1BIT
-    elif enable_wp_opt:
-        if _max <= MAX_INT2 and _min >= MIN_INT2:
-            return WP.WEIGHT_WIDTH_2BIT
-        elif _max <= MAX_INT4 and _min >= MIN_INT4:
-            return WP.WEIGHT_WIDTH_4BIT
-        else:
-            return WP.WEIGHT_WIDTH_8BIT
+    elif _max <= MAX_INT2 and _min >= MIN_INT2:
+        return WP.WEIGHT_WIDTH_2BIT
+    elif _max <= MAX_INT4 and _min >= MIN_INT4:
+        return WP.WEIGHT_WIDTH_4BIT
     else:
         return WP.WEIGHT_WIDTH_8BIT
 
@@ -328,4 +329,4 @@ def __call__(self, x: np.ndarray, *args, **kwargs) -> SynOutType:
     def connectivity(self):
         return _conv2d_unroll(
             self.in_shape, self.out_shape, self.weights, self.stride
-        ).astype(self.conn_dtype)
+        ).astype(self.conn_dtype)
\ No newline at end of file

From 1b1e1492a7d9b99121beed1452e6f6e9ad6bde81 Mon Sep 17 00:00:00 2001
From: KafCoppelia <k740677208@gmail.com>
Date: Tue, 2 Apr 2024 10:15:11 +0800
Subject: [PATCH 48/68] =?UTF-8?q?=F0=9F=9A=B8=20updated=20exception=20desc?=
 =?UTF-8?q?ription=20in=20axon2lcn=20check?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

---
 paibox/backend/placement.py  | 58 ++++++++++++++++++++++--------------
 tests/backend/test_mapper.py | 23 ++++++++++++++
 2 files changed, 59 insertions(+), 22 deletions(-)

diff --git a/paibox/backend/placement.py b/paibox/backend/placement.py
index 7bd7d564..fb115c6d 100644
--- a/paibox/backend/placement.py
+++ b/paibox/backend/placement.py
@@ -26,7 +26,12 @@
 from paicorelib import WeightPrecision as WP
 
 from paibox.base import NeuDyn, PAIBoxObject
-from paibox.exceptions import BuildError, NotSupportedError, ResourceError
+from paibox.exceptions import (
+    BuildError,
+    NotSupportedError,
+    ResourceError,
+    TruncationWarning,
+)
 from paibox.synapses import SynSys
 from paibox.types import WeightType
 from paibox.utils import check_attr_same, count_unique_elem
@@ -78,10 +83,9 @@ def __init__(
             - seed: the random seed.
             - name: the name of the core block. Optional.
         """
-
         super().__init__(name)
         self._parents = parents
-        self._lcn_ex = n_axon2lcn_ex(self.n_axon, self.n_fanin_max)
+        self._lcn_ex = self._n_axon2lcn_ex()
         self.weight_precision = weight_precision
 
         self.seed = seed
@@ -142,6 +146,28 @@ def _get_syn_of(self, src: SourceNodeType, dest: DestNodeType) -> Optional[SynSy
 
         return None
 
+    def _n_axon2lcn_ex(self) -> LCN_EX:
+        """Convert #N(of axons) to `LCN_EX` & check.
+
+        NOTE: LCN_EX = log2[ceil(#N/fan-in per dendrite)], where `LCN_1X` = 0.
+        """
+        if self.n_axon < 1:
+            raise ValueError(
+                f"the number of axons must be positive, but got {self.n_axon}."
+            )
+
+        if (
+            lcn := ((self.n_axon - 1) // self.n_fanin_max).bit_length()
+        ) > LCN_EX.LCN_64X:
+            _max_n_axons = self.n_fanin_max * (1 << LCN_EX.LCN_64X)
+            raise ResourceError(
+                f"required LCN extension out of range {LCN_EX.LCN_64X} ({lcn}). "
+                f"The number of axons must be <= {_max_n_axons}. "
+                f"But synapses {self._obj_repr()} have a total of {self.n_axon} axons."
+            )
+
+        return LCN_EX(lcn)
+
     def copy(self):
         raise NotImplementedError
 
@@ -220,7 +246,7 @@ def lcn_ex(self, lcn_ex: LCN_EX) -> None:
         """Set or adjust the `lcn_ex` & lock."""
         if lcn_ex > LCN_EX.LCN_64X:
             raise ResourceError(
-                f"LCN extension required out of {LCN_EX.LCN_64X}: {lcn_ex}"
+                f"required LCN extension out of range {LCN_EX.LCN_64X} ({lcn_ex})."
             )
 
         self._lcn_ex = lcn_ex
@@ -337,6 +363,10 @@ def __repr__(self) -> str:
     def __str__(self) -> str:
         return f"<{self.name} of target '{self.obj}'>"
 
+    def _obj_repr(self) -> str:
+        """The representation of the names of target objects."""
+        return ", ".join(n.name for n in self.obj)
+
     @classmethod
     def build(cls, *synapses: SynSys, seed: int = 0, enable_wp_opt: bool):
         """Combine the SAME weight precision synapses and build the `CoreBlock`."""
@@ -357,7 +387,8 @@ def build(cls, *synapses: SynSys, seed: int = 0, enable_wp_opt: bool):
         # FIXME where does the parameter check do?
         if seed > (1 << 64) - 1:
             warnings.warn(
-                f"random seed {seed} is too large, truncated into 64 bits.", UserWarning
+                f"random seed {seed} is too large, truncated into 64 bits.",
+                TruncationWarning,
             )
 
         return cls(*synapses, weight_precision=wp0, seed=seed)
@@ -714,23 +745,6 @@ def __len__(self) -> int:
         return self.n_core_required
 
 
-def n_axon2lcn_ex(n_axon: int, fan_in_max: int) -> LCN_EX:
-    """Convert #N(of axons) to `LCN_EX`.
-
-    Description:
-        LCN_EX = log2[ceil(#N/fan-in per dendrite)], where LCN_EX = 0 is `LCN_1X`.
-    """
-    if n_axon < 1:
-        raise ValueError(f"the number of axons must be positive, but got {n_axon}.")
-
-    if (lcn_bit := ((n_axon - 1) // fan_in_max).bit_length()) > LCN_EX.LCN_64X:
-        raise ResourceError(
-            f"LCN extension required out of range {LCN_EX.LCN_64X} ({lcn_bit})."
-        )
-
-    return LCN_EX(lcn_bit)
-
-
 def max_lcn_of_cb(cb: List[CoreBlock]) -> LCN_EX:
     """Find the max LCN extenion of previous grouped synapses"""
     return max(cb, key=lambda cb: cb.lcn_ex).lcn_ex
diff --git a/tests/backend/test_mapper.py b/tests/backend/test_mapper.py
index 0f276527..e4267a2b 100644
--- a/tests/backend/test_mapper.py
+++ b/tests/backend/test_mapper.py
@@ -10,6 +10,7 @@
 
 import paibox as pb
 from paibox.backend.conf_template import CoreConfig, NeuronDest, NeuronDestInfo
+from paibox.exceptions import ResourceError
 from paibox.synapses import SynSys
 
 
@@ -198,6 +199,28 @@ def test_network_with_container(self, get_mapper, build_Network_with_container):
         assert len(mapper.graph_info["input"]) == 0
         assert len(mapper.graph_info["output"]) == 1
 
+    def test_network_axons_outrange(self):
+        class Net(pb.Network):
+            def __init__(self):
+                super().__init__()
+                self.inp = pb.InputProj(1, shape_out=(300, 300))
+                self.n1 = pb.IF((300, 300), 1, name="n1")
+                self.n2 = pb.IF((300,), 1, name="n2")
+
+                self.s1 = pb.FullConn(
+                    self.inp, self.n1, conn_type=pb.SynConnType.All2All
+                )
+                self.s2 = pb.FullConn(
+                    self.n1, self.n2, conn_type=pb.SynConnType.All2All
+                )
+
+        net = Net()
+        mapper = pb.Mapper()
+        mapper.build(net)
+
+        with pytest.raises(ResourceError):
+            mapper.compile()  # 300*300 > 1152*64
+
 
 class TestMapper_Export:
     def test_export_multi_nodes_more_than_32(

From de536bd200570c4783765d4b62d7303719e3e864 Mon Sep 17 00:00:00 2001
From: KafCoppelia <k740677208@gmail.com>
Date: Tue, 2 Apr 2024 19:29:13 +0800
Subject: [PATCH 49/68] =?UTF-8?q?=E2=9C=A8=20added=20property=20weight=5Fp?=
 =?UTF-8?q?recision=20for=20CoreBlock=20to=20determine=20the=20wp=20of=20i?=
 =?UTF-8?q?tself?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

---
 paibox/backend/mapper.py    | 33 ++++++++++----------
 paibox/backend/placement.py | 62 +++++++++++--------------------------
 2 files changed, 34 insertions(+), 61 deletions(-)

diff --git a/paibox/backend/mapper.py b/paibox/backend/mapper.py
index 75b009c6..7fa5ac95 100644
--- a/paibox/backend/mapper.py
+++ b/paibox/backend/mapper.py
@@ -12,7 +12,7 @@
     to_coord,
 )
 
-from paibox.base import NeuDyn
+from paibox.base import NeuDyn, SynSys
 from paibox.exceptions import ResourceError
 from paibox.network import DynSysGroup
 
@@ -140,22 +140,25 @@ def compile(
         if grouping_optim_target is not None:
             set_cflag(grouping_optim_target=grouping_optim_target)
 
-        """Backend compilation."""
+        """1. Check whether the PAIGraph has built."""
         self._build_check()
 
-        """1. Build core blocks."""
+        """2. Set global compilation flags."""
+        self._set_global_cflags()
+
+        """3. Build core blocks."""
         self.build_core_blocks()
 
-        """2. Adjust the LCN extension of each core block."""
+        """4. Adjust the LCN extension of each core block."""
         self.lcn_ex_adjustment()
 
-        """3. Core coordinate assignment."""
+        """5. Core coordinate assignment."""
         self.coord_assign()
 
-        """4. Allocate the core blocks to the `CorePlacement`."""
+        """6. Allocate the core blocks to the `CorePlacement`."""
         self.core_allocation()
 
-        """5. Export parameters."""
+        """7. Export parameters."""
         return self.config_export()
 
     def build_core_blocks(self) -> None:
@@ -166,13 +169,7 @@ def build_core_blocks(self) -> None:
         grouped_edges = self.graph.group_edges()
 
         for syns in grouped_edges:
-            self.core_blocks.append(
-                CoreBlock.build(
-                    *syns,
-                    seed=0,
-                    enable_wp_opt=_BACKEND_CONTEXT.cflags["enable_wp_opt"],
-                )
-            )
+            self.core_blocks.append(CoreBlock.build(*syns, seed=0))
 
         for cb in self.core_blocks:
             succ_cbs = list(
@@ -210,9 +207,8 @@ def lcn_ex_adjustment(self) -> None:
     def coord_assign(self) -> None:
         """Assign the coordinate of each `CorePlacement`.
 
-        NOTE: The neurons in each core block must be grouped first  \
-            to determine the #N of cores required, and then the     \
-            routing coordinates can be assigned.
+        NOTE: The neurons in each core block must be grouped first to determine the #N of cores required,   \
+            and then the routing coordinates can be assigned.
         """
         for cb in self.core_blocks:
             # Group the neurons, get the #N of cores required.
@@ -274,6 +270,9 @@ def config_export(self) -> GraphInfo:
 
         return _graph_info
 
+    def _set_global_cflags(self) -> None:
+        SynSys.CFLAG_ENABLE_WP_OPTIMIZATION = _BACKEND_CONTEXT.cflags["enable_wp_opt"]
+
     def _inpproj_config_export(self) -> InputNodeInfo:
         """Export the configuration of input projections.
 
diff --git a/paibox/backend/placement.py b/paibox/backend/placement.py
index fb115c6d..4b1fcde4 100644
--- a/paibox/backend/placement.py
+++ b/paibox/backend/placement.py
@@ -28,7 +28,6 @@
 from paibox.base import NeuDyn, PAIBoxObject
 from paibox.exceptions import (
     BuildError,
-    NotSupportedError,
     ResourceError,
     TruncationWarning,
 )
@@ -52,14 +51,6 @@
 
 
 class CoreAbstract(HwCore, PAIBoxObject):
-    SUPPORTED_WP: ClassVar[Tuple[WP, ...]] = (
-        WP.WEIGHT_WIDTH_1BIT,
-        WP.WEIGHT_WIDTH_2BIT,  # Not verified
-        WP.WEIGHT_WIDTH_4BIT,  # Not verified
-        WP.WEIGHT_WIDTH_8BIT,
-    )
-    """Supported weight precision."""
-
     SUPPORTED_MODE: ClassVar[Tuple[CoreMode, ...]] = (CoreMode.MODE_SNN,)
     """Supported core modes."""
 
@@ -69,24 +60,18 @@ class CoreBlock(CoreAbstract):
 
     RUNTIME_MODE: ClassVar[CoreMode] = CoreMode.MODE_SNN
 
-    def __init__(
-        self,
-        *parents: SynSys,
-        weight_precision: WP,
-        seed: int = 0,
-        name: Optional[str] = None,
-    ) -> None:
-        """
-        Arguments:
+    def __init__(self, *parents: SynSys, seed: int, name: Optional[str] = None) -> None:
+        """Core blocks in SNN mode.
+
+        Args:
             - parents: the parent synapses.
-            - weight_precision: the precision of weight matrix.
-            - seed: the random seed.
-            - name: the name of the core block. Optional.
+            - seed: random seed. Default value is 0.
+            - name: name of the core block. Optional.
         """
         super().__init__(name)
         self._parents = parents
         self._lcn_ex = self._n_axon2lcn_ex()
-        self.weight_precision = weight_precision
+        self._wp = WP.WEIGHT_WIDTH_8BIT  # Default value
 
         self.seed = seed
         """Random seed, legal integer, no more than uint64."""
@@ -222,14 +207,17 @@ def n_fanin_max(self) -> int:
     def n_core_required(self) -> int:
         return len(self.neuron_segs_of_cb)
 
+    @property
+    def weight_precision(self) -> WP:
+        # Optimized in `s.weight_precision`.
+        return max(s.weight_precision for s in self.obj)
+
     @property
     def n_dendrite_per_neuron(self) -> int:
-        """Multiple dendrites will be combined to achieve higher    \
-            precision weights.
+        """Multiple dendrites will be combined to achieve higher precision weights.
 
-        FIXME The limit on the number of dendrites in SNN/ANN modes \
-            is different, which affects the capacity of neurons in  \
-            physical core.
+        FIXME The limit on the number of dendrites in SNN/ANN modes is different, which affects \
+            the capacity of neurons in physical core.
         """
         return 1 << self.weight_precision
 
@@ -368,22 +356,8 @@ def _obj_repr(self) -> str:
         return ", ".join(n.name for n in self.obj)
 
     @classmethod
-    def build(cls, *synapses: SynSys, seed: int = 0, enable_wp_opt: bool):
-        """Combine the SAME weight precision synapses and build the `CoreBlock`."""
-        SynSys.CFLAG_ENABLE_WP_OPTIMIZATION = enable_wp_opt  # TODO OK but ugly
-
-        wp0 = synapses[0].weight_precision
-        # Check wether weight precision of all synapses equal.
-        if not all(wp0 == s.weight_precision for s in synapses):
-            raise NotSupportedError("mixed weight precision is not supported yet.")
-
-        if wp0 > max(cls.SUPPORTED_WP):
-            raise NotSupportedError(f"{wp0.name} is not supported yet.")
-
-        elif wp0 not in cls.SUPPORTED_WP:
-            # Treat lower bit weights as 8-bit weights.
-            wp0 = cls.SUPPORTED_WP[-1]
-
+    def build(cls, *synapses: SynSys, seed: int = 0):
+        """Group synapses & build `CoreBlock`."""
         # FIXME where does the parameter check do?
         if seed > (1 << 64) - 1:
             warnings.warn(
@@ -391,7 +365,7 @@ def build(cls, *synapses: SynSys, seed: int = 0, enable_wp_opt: bool):
                 TruncationWarning,
             )
 
-        return cls(*synapses, weight_precision=wp0, seed=seed)
+        return cls(*synapses, seed=seed)
 
     @classmethod
     def export_core_plm_config(cls, cb: "CoreBlock") -> Dict[Coord, CoreConfig]:

From 3c3edbb3a15a9cb1122161c34e903a1765830662 Mon Sep 17 00:00:00 2001
From: KafCoppelia <k740677208@gmail.com>
Date: Tue, 2 Apr 2024 19:30:08 +0800
Subject: [PATCH 50/68] =?UTF-8?q?=F0=9F=8E=A8=20updated=20typing?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

---
 paibox/backend/placement.py   |  6 +-----
 paibox/base.py                |  9 +++++----
 paibox/exceptions.py          |  6 ++++++
 paibox/neuron/utils.py        |  1 +
 paibox/synapses/base.py       | 17 ++++++++++++-----
 paibox/synapses/conv_utils.py |  2 +-
 paibox/types.py               |  3 ++-
 7 files changed, 28 insertions(+), 16 deletions(-)

diff --git a/paibox/backend/placement.py b/paibox/backend/placement.py
index 4b1fcde4..7c70a5cd 100644
--- a/paibox/backend/placement.py
+++ b/paibox/backend/placement.py
@@ -26,11 +26,7 @@
 from paicorelib import WeightPrecision as WP
 
 from paibox.base import NeuDyn, PAIBoxObject
-from paibox.exceptions import (
-    BuildError,
-    ResourceError,
-    TruncationWarning,
-)
+from paibox.exceptions import BuildError, ResourceError, TruncationWarning
 from paibox.synapses import SynSys
 from paibox.types import WeightType
 from paibox.utils import check_attr_same, count_unique_elem
diff --git a/paibox/base.py b/paibox/base.py
index e3250d00..e570a77b 100644
--- a/paibox/base.py
+++ b/paibox/base.py
@@ -1,14 +1,15 @@
 import sys
-from typing import Any, ClassVar, Dict, List, Literal, Optional, Set, Tuple, Union
+from typing import Any, ClassVar, Dict, List, Literal, Optional, Set, Tuple
 
 import numpy as np
-from numpy.typing import NDArray
 
 if sys.version_info >= (3, 10):
     from typing import TypeAlias
 else:
     from typing_extensions import TypeAlias
 
+from paicorelib import WeightPrecision as WP
+
 from .collector import Collector
 from .mixin import ReceiveInputProj, StatusMemory, TimeRelatedNode
 from .naming import get_unique_name, is_name_unique
@@ -323,11 +324,11 @@ def weights(self) -> WeightType:
         raise NotImplementedError
 
     @property
-    def weight_precision(self):
+    def weight_precision(self) -> WP:
         raise NotImplementedError
 
     @property
-    def connectivity(self) -> NDArray[Union[np.bool_, np.int8]]:
+    def connectivity(self) -> WeightType:
         raise NotImplementedError
 
     @property
diff --git a/paibox/exceptions.py b/paibox/exceptions.py
index bb593813..8cf17395 100644
--- a/paibox/exceptions.py
+++ b/paibox/exceptions.py
@@ -62,3 +62,9 @@ class TruncationWarning(PAIBoxWarning, UserWarning):
     """Value out of range & will be truncated."""
 
     pass
+
+
+class AutoOptimizationWarning(PAIBoxWarning):
+    """Parameters are optimized automatically by PAIBox."""
+
+    pass
diff --git a/paibox/neuron/utils.py b/paibox/neuron/utils.py
index 880d15c5..bffc545d 100644
--- a/paibox/neuron/utils.py
+++ b/paibox/neuron/utils.py
@@ -1,4 +1,5 @@
 import numpy as np
+
 from paibox.types import VoltageType
 
 VJT_MAX_LIMIT: int = 2**29 - 1
diff --git a/paibox/synapses/base.py b/paibox/synapses/base.py
index fc35ecdf..bbdc0d13 100644
--- a/paibox/synapses/base.py
+++ b/paibox/synapses/base.py
@@ -18,9 +18,16 @@
     _Order2d,
     _Order3d,
 )
-from .transforms import AllToAll, Conv1dForward, Conv2dForward
-from .transforms import GeneralConnType as GConnType
-from .transforms import Identity, MaskedLinear, OneToOne, Transform
+from .transforms import (
+    AllToAll,
+    Conv1dForward,
+    Conv2dForward,
+    GeneralConnType as GConnType,
+    Identity,
+    MaskedLinear,
+    OneToOne,
+    Transform,
+)
 
 RIGISTER_MASTER_KEY_FORMAT = "{0}.output"
 
@@ -121,8 +128,8 @@ def weight_precision(self) -> WP:
         return self.comm._get_wp(self.CFLAG_ENABLE_WP_OPTIMIZATION)
 
     @property
-    def connectivity(self):
-        """The connectivity matrix in `np.ndarray` format."""
+    def connectivity(self) -> WeightType:
+        """The connectivity matrix in `np.bool_` or `np.int8` format."""
         return self.comm.connectivity
 
 
diff --git a/paibox/synapses/conv_utils.py b/paibox/synapses/conv_utils.py
index 87adef87..35e69ea3 100644
--- a/paibox/synapses/conv_utils.py
+++ b/paibox/synapses/conv_utils.py
@@ -80,7 +80,7 @@ def _conv1d_unroll(
     kernel: WeightType,
     stride: Size1Type,
     # padding: Size1Type,
-):
+) -> WeightType:
     """Unroll the convolution kernel of 1d convolution into a matrix."""
     cout, cin, kl = kernel.shape
     il = in_shape[0]
diff --git a/paibox/types.py b/paibox/types.py
index e2fd56af..b7e709de 100644
--- a/paibox/types.py
+++ b/paibox/types.py
@@ -10,6 +10,7 @@
     Optional,
     Tuple,
     TypeVar,
+    Union,
 )
 
 import numpy as np
@@ -26,7 +27,7 @@
 SpikeType = NDArray[np.bool_]
 SynOutType = NDArray[np.int32]
 VoltageType = NDArray[np.int32]
-WeightType = NDArray[np.int8]  # raw int8 weights
+WeightType = NDArray[Union[np.bool_, np.int8]]
 
 _T = TypeVar("_T")
 

From 10b608d8a0ee381656511d447416321ee19522ad Mon Sep 17 00:00:00 2001
From: KafCoppelia <k740677208@gmail.com>
Date: Tue, 2 Apr 2024 19:32:14 +0800
Subject: [PATCH 51/68] =?UTF-8?q?=E2=9C=85=20added=20tests=20for=20setting?=
 =?UTF-8?q?=20coarse=20dtype=20of=20weights?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

---
 tests/synapses/test_synapses.py   | 20 ++++++++--
 tests/synapses/test_transforms.py | 66 ++++++++++++++++++++++++++++---
 2 files changed, 78 insertions(+), 8 deletions(-)

diff --git a/tests/synapses/test_synapses.py b/tests/synapses/test_synapses.py
index 3c60f41d..46f3cf6f 100644
--- a/tests/synapses/test_synapses.py
+++ b/tests/synapses/test_synapses.py
@@ -76,6 +76,11 @@ def test_FullConn_One2One_scalar(self, n1, n2, scalar_weight, expected_wp):
             s1.connectivity,
             scalar_weight * np.eye(n1.num_out, n2.num_in, dtype=np.int8),
         )
+        assert (
+            s1.connectivity.dtype == np.int8
+            if expected_wp > WP.WEIGHT_WIDTH_1BIT
+            else np.bool_
+        )
         assert s1.weight_precision is expected_wp
 
     @pytest.mark.parametrize(
@@ -117,6 +122,7 @@ def test_FullConn_One2One_matrix(self):
         assert np.array_equal(
             s1.connectivity, np.array([[2, 0, 0], [0, 3, 0], [0, 0, 4]], dtype=np.int8)
         )
+        assert s1.connectivity.dtype == np.int8
         assert s1.weight_precision is WP.WEIGHT_WIDTH_4BIT
 
         weight = np.array([1, 0, 1, 0], np.int8)
@@ -135,6 +141,7 @@ def test_FullConn_One2One_matrix(self):
                 [[1, 0, 0, 0], [0, 0, 0, 0], [0, 0, 1, 0], [0, 0, 0, 0]], dtype=np.bool_
             ),
         )
+        assert s2.connectivity.dtype == np.int8
         assert s2.weight_precision is WP.WEIGHT_WIDTH_1BIT
 
     @pytest.mark.parametrize(
@@ -163,6 +170,7 @@ def test_FullConn_All2All(self, n1, n2):
         s1 = pb.FullConn(n1, n2, conn_type=pb.SynConnType.All2All)
 
         assert (s1.num_in, s1.num_out) == (n1.num_out, n2.num_in)
+        assert s1.connectivity.dtype == np.bool_
         assert np.array_equal(s1.weights, 1)
         assert np.array_equal(s1.connectivity, np.ones((n1.num_out, n2.num_in)))
 
@@ -175,12 +183,14 @@ def test_FullConn_All2All_with_weights(self):
         s1 = pb.FullConn(n1, n2, weight, conn_type=pb.SynConnType.All2All)
 
         assert np.array_equal(s1.weights, weight)
+        assert s1.connectivity.dtype == np.int8
         assert s1.weight_precision is WP.WEIGHT_WIDTH_4BIT
 
         """2. Weights matrix."""
         weight = np.array([[1, 2, 3], [4, 5, 6], [7, 8, 9]])
         s2 = pb.FullConn(n1, n2, weight, conn_type=pb.SynConnType.All2All)
 
+        assert s2.connectivity.dtype == np.int8
         assert np.array_equal(s2.weights, weight)
         assert np.array_equal(s2.connectivity, weight)
 
@@ -235,8 +245,9 @@ def test_FullConn_MatConn(self, n1, n2):
 
         s = pb.FullConn(n1, n2, weight, conn_type=pb.SynConnType.MatConn)
 
-        assert np.array_equal(s.weights, weight)
         assert (s.num_in, s.num_out) == (n1.num_out, n2.num_in)
+        assert s.connectivity.dtype == np.int8
+        assert np.array_equal(s.weights, weight)
         assert np.array_equal(s.connectivity, weight)
 
         # Wrong weight type
@@ -280,6 +291,7 @@ def test_Conv1d_instance(self):
         )
 
         assert s1.num_in == in_channels * shape2num(in_shape)
+        assert s1.connectivity.dtype == np.int8
         assert s1.connectivity.shape == (
             in_channels * shape2num(in_shape),
             out_channels * shape2num(out_shape),
@@ -298,13 +310,14 @@ def test_Conv2d_instance(self):
         n2 = pb.IF((out_channels,) + out_shape, 3)
 
         weight = np.random.randint(
-            -128, 128, size=(in_channels, out_channels) + kernel_size, dtype=np.int8
+            -8, 8, size=(in_channels, out_channels) + kernel_size, dtype=np.int32
         )
         s1 = pb.Conv2d(
             n1, n2, weight, stride=stride, fm_order="CHW", kernel_order=korder
         )
 
         assert s1.num_in == in_channels * shape2num(in_shape)
+        assert s1.connectivity.dtype == np.int8
         assert s1.connectivity.shape == (
             in_channels * shape2num(in_shape),
             out_channels * shape2num(out_shape),
@@ -323,13 +336,14 @@ def test_Conv1d_inchannel_omitted(self):
         n2 = pb.IF((out_channels,) + out_shape, 3)
 
         weight = np.random.randint(
-            -128, 128, size=(in_channels, out_channels) + kernel_size, dtype=np.int8
+            -128, 128, size=(in_channels, out_channels) + kernel_size, dtype=np.int64
         )
         s1 = pb.Conv1d(
             n1, n2, weight, stride=stride, fm_order="CL", kernel_order=korder
         )
 
         assert s1.num_in == in_channels * shape2num(in_shape)
+        assert s1.connectivity.dtype == np.int8
         assert s1.connectivity.shape == (
             in_channels * shape2num(in_shape),
             out_channels * shape2num(out_shape),
diff --git a/tests/synapses/test_transforms.py b/tests/synapses/test_transforms.py
index 86664862..9cfc706b 100644
--- a/tests/synapses/test_transforms.py
+++ b/tests/synapses/test_transforms.py
@@ -3,11 +3,68 @@
 import numpy as np
 import pytest
 
+from paibox.exceptions import AutoOptimizationWarning
 from paibox.synapses.transforms import *
+from paibox.synapses.transforms import Transform
 from paibox.utils import shape2num
 
 
 class TestTransforms:
+    @pytest.mark.parametrize(
+        "weight, expected_dtype",
+        [
+            (np.array([1, 2, 3], dtype=np.int8), np.int8),
+            (np.array([1, 0, 1], dtype=np.bool_), np.bool_),
+            (np.array([True, False]), np.bool_),
+            (np.array([True, False], dtype=np.int8), np.int8),
+            (10, np.int8),
+            (1, np.bool_),
+            (True, np.bool_),
+            (np.int8(1), np.bool_),  # automatically optimizated
+            (np.uint8(99), np.int8),
+            (np.array([-128, 1, 127], dtype=np.int8), np.int8),
+            ([1, 2, 3], np.int8),
+            ((0, 1, 0, 1), np.int8),
+        ],
+    )
+    def test_weight_dtype_convert(self, weight, expected_dtype):
+        tfm = Transform(weight)
+        assert tfm.weights.dtype == expected_dtype
+
+    @pytest.mark.parametrize(
+        "weight, expected_dtype",
+        [
+            (np.array([1, 2, 3]), np.int8),
+            # Only automatically optimized to int8 unless specified as bool
+            (np.array([True, False], dtype=np.int16), np.int8),
+            (np.array([1, 0, 1], dtype=np.int16), np.int8),  # Same as above
+            (np.array([-128, 1, 127], dtype=np.int32), np.int8),
+            (np.array([-8, 4, 7]), np.int8),
+            ([-100, 0, 100], np.int8),
+        ],
+    )
+    def test_weight_dtype_convert_warning(self, weight, expected_dtype):
+        with pytest.warns(AutoOptimizationWarning):
+            tfm = Transform(weight)
+
+        assert tfm.weights.dtype == expected_dtype
+
+    @pytest.mark.parametrize(
+        "weight",
+        [
+            (np.array([1.0, 2.1, 3.2])),  # float is forbidden
+            (np.array([1, 2, 3], dtype=np.float32)),
+            (np.array([111, 222, -333], dtype=np.int16)),  # out of range int8
+            (999),
+            (3.14),
+            ([-100, 200, 0]),
+            ((1.1, 0.5)),
+        ],
+    )
+    def test_weight_dtype_convert_illegal(self, weight):
+        with pytest.raises((TypeError, ValueError)):
+            tfm = Transform(weight)
+
     @pytest.mark.parametrize(
         "weight",
         [
@@ -84,7 +141,7 @@ def test_AllToAll_weight_scalar(self, weight, expected_dtype):
         y = f(x)
         expected = np.full((num_out,), np.sum(x, axis=None), dtype=np.int32) * weight
 
-        assert f.conn_dtype == expected_dtype
+        assert f.connectivity.dtype == expected_dtype
         assert y.dtype == np.int32
         assert y.shape == (num_out,)
         assert y.ndim == 1
@@ -109,7 +166,7 @@ def test_AllToAll_weight_scalar(self, weight, expected_dtype):
             (
                 (20, 10),
                 np.random.randint(2, size=(20,), dtype=np.bool_),
-                np.random.randint(2, size=(20, 10), dtype=np.int8),
+                np.random.randint(2, size=(20, 10), dtype=np.bool_),
                 np.bool_,
             ),
             (
@@ -140,7 +197,7 @@ def test_AllToAll_array(self, shape, x, weights, expected_dtype):
         y = f(x)
         expected = x @ weights.copy().astype(np.int32)
 
-        assert f.conn_dtype == expected_dtype
+        assert f.connectivity.dtype == expected_dtype
         assert np.array_equal(y, expected)
         assert f.connectivity.shape == shape
 
@@ -162,7 +219,7 @@ def test_AllToAll_array(self, shape, x, weights, expected_dtype):
             (
                 (20, 10),
                 np.ones((20,), dtype=np.bool_),
-                np.random.randint(2, size=(20, 10), dtype=np.int8),
+                np.random.randint(2, size=(20, 10), dtype=np.bool_),
                 np.bool_,
             ),
             (
@@ -179,7 +236,6 @@ def test_MaskedLinear_conn(self, shape, x, weights, expected_dtype):
         y = f(x)
         expected = x @ weights.copy().astype(np.int32)
 
-        assert f.conn_dtype == expected_dtype
         assert f.connectivity.dtype == expected_dtype
         assert y.shape == (shape[1],)
         assert y.dtype == np.int32

From ba465bd1b2555c7663b81b556af354b477ba5260 Mon Sep 17 00:00:00 2001
From: KafCoppelia <k740677208@gmail.com>
Date: Tue, 2 Apr 2024 19:49:25 +0800
Subject: [PATCH 52/68] =?UTF-8?q?=E2=9C=85=20added=20tests=20for=20weight?=
 =?UTF-8?q?=5Fbit=5Foptim=20option?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

---
 tests/backend/conftest.py    | 76 ++++++++++++++++++++++++++++++++++++
 tests/backend/test_mapper.py | 56 +++++++++++++++++++++-----
 2 files changed, 122 insertions(+), 10 deletions(-)

diff --git a/tests/backend/conftest.py b/tests/backend/conftest.py
index bf1bcf66..9a0808f6 100644
--- a/tests/backend/conftest.py
+++ b/tests/backend/conftest.py
@@ -908,3 +908,79 @@ class TestData:
             "headless_neuron_2",
         ],
     )
+
+    cflags_weight_bit_opt_data = ParametrizedTestData(
+        args="range, scalar, dtype, expected_wp_noopt, expected_wp_opt",
+        data=[
+            (
+                ((0, 2), (0, 2)),
+                1,
+                (np.bool_, np.bool_),
+                WP.WEIGHT_WIDTH_1BIT,
+                WP.WEIGHT_WIDTH_1BIT,
+            ),
+            (
+                ((0, 2), (0, 2)),
+                -1,
+                (np.bool_, np.bool_),
+                WP.WEIGHT_WIDTH_8BIT,
+                WP.WEIGHT_WIDTH_2BIT,
+            ),
+            (
+                ((0, 2), (0, 2)),
+                1,
+                (np.bool_, np.int8),
+                WP.WEIGHT_WIDTH_8BIT,
+                WP.WEIGHT_WIDTH_1BIT,
+            ),
+            (
+                ((0, 2), (0, 2)),
+                -2,
+                (np.int8, np.bool_),
+                WP.WEIGHT_WIDTH_8BIT,
+                WP.WEIGHT_WIDTH_2BIT,
+            ),
+            (
+                ((0, 2), (0, 2)),
+                1,
+                (np.int8, np.int8),
+                WP.WEIGHT_WIDTH_8BIT,
+                WP.WEIGHT_WIDTH_1BIT,
+            ),
+            (
+                ((0, 2), (-2, 2)),
+                -8,
+                (np.bool_, np.int8),
+                WP.WEIGHT_WIDTH_8BIT,
+                WP.WEIGHT_WIDTH_4BIT,
+            ),
+            (
+                ((0, 2), (-2, 2)),
+                7,
+                (np.bool_, np.int8),
+                WP.WEIGHT_WIDTH_8BIT,
+                WP.WEIGHT_WIDTH_4BIT,
+            ),
+            (
+                ((0, 2), (-128, 128)),
+                127,
+                (np.bool_, np.int8),
+                WP.WEIGHT_WIDTH_8BIT,
+                WP.WEIGHT_WIDTH_8BIT,
+            ),
+            (
+                ((-2, 2), (-8, 8)),
+                7,
+                (np.int8, np.int8),
+                WP.WEIGHT_WIDTH_8BIT,
+                WP.WEIGHT_WIDTH_4BIT,
+            ),
+            (
+                ((-8, 8), (-8, 8)),
+                -100,
+                (np.int8, np.int8),
+                WP.WEIGHT_WIDTH_8BIT,
+                WP.WEIGHT_WIDTH_8BIT,
+            ),
+        ],
+    )
diff --git a/tests/backend/test_mapper.py b/tests/backend/test_mapper.py
index e4267a2b..895bcf7d 100644
--- a/tests/backend/test_mapper.py
+++ b/tests/backend/test_mapper.py
@@ -6,7 +6,7 @@
 
 import numpy as np
 import pytest
-from paicorelib import Coord, HwConfig, WeightPrecision
+from paicorelib import Coord, HwConfig
 
 import paibox as pb
 from paibox.backend.conf_template import CoreConfig, NeuronDest, NeuronDestInfo
@@ -402,18 +402,54 @@ def test_grouping_optim_both(self, monkeypatch, build_example_net4):
 
 
 class TestMapper_cflags:
-    def test_cflags_weight_bit_optimization(self, build_network_with_branches_4bit):
-        net = build_network_with_branches_4bit
+    from .conftest import TestData
+
+    @pytest.mark.parametrize(
+        TestData.cflags_weight_bit_opt_data["args"],
+        TestData.cflags_weight_bit_opt_data["data"],
+    )
+    def test_cflags_weight_bit_opt(
+        self, range, scalar, dtype, expected_wp_noopt, expected_wp_opt
+    ):
+        # s1, s2, s3 will be grouped in one core block.
+        class Net(pb.Network):
+            def __init__(self):
+                super().__init__()
+                self.n1 = pb.TonicSpiking(10, 3, name="n1", tick_wait_start=1)
+                self.n2 = pb.TonicSpiking(10, 4, name="n2", tick_wait_start=2)
+                self.n3 = pb.TonicSpiking(10, 4, name="n3", tick_wait_start=2)
+                self.n4 = pb.TonicSpiking(10, 4, name="n4", tick_wait_start=2)
+                self.s1 = pb.FullConn(
+                    self.n1,
+                    self.n2,
+                    weights=np.random.randint(*range[0], size=(10,), dtype=dtype[0]),
+                    conn_type=pb.SynConnType.One2One,
+                    name="s1",
+                )
+                self.s2 = pb.FullConn(
+                    self.n1,
+                    self.n3,
+                    weights=np.random.randint(*range[1], size=(10, 10), dtype=dtype[1]),
+                    name="s2",
+                )
+                self.s3 = pb.FullConn(
+                    self.n1,
+                    self.n4,
+                    weights=scalar,
+                    conn_type=pb.SynConnType.All2All,
+                    name="s3",
+                )
+
+        net = Net()
         mapper = pb.Mapper()
         mapper.build(net)
-        mapper.compile(weight_bit_optimization=True)
-        assert (
-            mapper.core_blocks[0].weight_precision == WeightPrecision.WEIGHT_WIDTH_4BIT
-        )
+        mapper.compile(weight_bit_optimization=False)
+        assert mapper.core_blocks[0].weight_precision == expected_wp_noopt
 
         mapper.clear()
         mapper.build(net)
-        mapper.compile(weight_bit_optimization=False)
-        assert (
-            mapper.core_blocks[0].weight_precision == WeightPrecision.WEIGHT_WIDTH_8BIT
+        mapper.compile(weight_bit_optimization=True)
+        assert mapper.core_blocks[0].weight_precision == max(
+            s.weight_precision for s in (net.s1, net.s2, net.s3)
         )
+        assert mapper.core_blocks[0].weight_precision == expected_wp_opt

From c62a18301c83b18b2859f509d6fad78597f4aa42 Mon Sep 17 00:00:00 2001
From: KafCoppelia <k740677208@gmail.com>
Date: Tue, 2 Apr 2024 22:20:55 +0800
Subject: [PATCH 53/68] =?UTF-8?q?=F0=9F=93=9D=20updated=20TODO=20&=20chang?=
 =?UTF-8?q?elog?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

---
 CHANGELOG.md            |  7 +++++++
 README.md               |  2 +-
 TODO.md                 | 10 ++++++----
 docs/Guide-of-PAIBox.md | 12 ++++++------
 poetry.lock             | 34 +++++++++++++++++-----------------
 pyproject.toml          |  2 +-
 6 files changed, 38 insertions(+), 29 deletions(-)

diff --git a/CHANGELOG.md b/CHANGELOG.md
index f36e1625..e8b40e7b 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -26,3 +26,10 @@
 ## v1.0.0a7
 
 - 支持全展开1D卷积算子构建与部署（`padding` 不支持）
+
+## v1.0.0a8
+
+- 提高 `numpy` 依赖版本至 `^1.24.0`
+- 修复神经元输入累加错误
+- 修复当权重为 `np.bool_` 且关闭权重精度优化选项( `weight_bit_optimization` )后，仍视为 `np.int8` 的错误
+- 支持混合精度权重的部署
diff --git a/README.md b/README.md
index b759f506..813c2896 100644
--- a/README.md
+++ b/README.md
@@ -8,7 +8,7 @@
     <a href="https://github.com/PAICookers/PAIBox/blob/master/pyproject.toml">
         <img src="https://img.shields.io/pypi/pyversions/paibox">
     </a>
-    <a href="https://github.com/PAICookers/PAIBox/releases/tag/v1.0.0a7">
+    <a href="https://github.com/PAICookers/PAIBox/releases/tag/v1.0.0b1">
         <img src="https://img.shields.io/github/v/release/PAICookers/PAIBox?include_prereleases&color=orange">
     </a>
     <a href="https://www.codefactor.io/repository/github/PAICookers/PAIBox">
diff --git a/TODO.md b/TODO.md
index a60d3a7b..82c7fcd7 100644
--- a/TODO.md
+++ b/TODO.md
@@ -40,11 +40,13 @@
   - [x] 资源+延时/吞吐率兼顾：在资源优先的基础上，可**叠加使用密集分配策略**，对未分配满的物理核尝试分配同一节点的其他神经元段。相较于单纯使用资源优先策略，使用更少的物理核
   - [ ] 自适应策略：根据网络结构，对各层 `unrolling factor` 做全局最优化设置，且预留接口以手动约束某些节点
 
-- [ ] 混合精度权重支持（已添加权重精度优化的**编译选项**）
-  - 对于网络中存在不同精度的突触情况，需要在后端实现对不同精度突触分组的处理。预期提供一个编译选项：
-    - 当开启时，当不同精度突触被分在同一组时，将按照最大精度权重进行，当分在不同组时，按各自权重处理
-    - 当关闭时，不同精度突触将**不被分在同一组**（即分割CB时存在约束）
+- [ ] 混合精度权重部署优化：对于网络中存在不同精度的突触情况，需要在后端实现对不同精度突触分组的处理。预期提供一个编译选项：
+
+  - [x] 当开启时，当不同精度突触被分在同一组时，将按照最大精度处理；当分在不同组时，按各自精度处理
+  - [ ] 当关闭时，不同精度突触将**不被分在同一组**（即对初次分配的CB进行分割，分割后得到的多个CB仍处于同一RG内）
 - [ ] ANN模式前后端支持
+
   - 目前仅支持芯片的SNN模式。要想支持ANN模式，前端上需要支持ANN模式的算理。同时，ANN/SNN模式是物理核的行为，因此当网络拓扑中同时存在两种模式的神经元时，需要以此为约束条件，从而影响分组结果（类似第6点。例如，同为ANN模式下的不同神经元可被分在同一组）
 - [ ] 神经元计算模型随机性仿真
+
   - 基于硬件神经元计算机制，实现带有部分随机数的计算机制。并考虑与硬件的实现相接近的程度（能否接近实现与硬件一致的随机数发生行为）
diff --git a/docs/Guide-of-PAIBox.md b/docs/Guide-of-PAIBox.md
index 005126eb..3b57a55b 100644
--- a/docs/Guide-of-PAIBox.md
+++ b/docs/Guide-of-PAIBox.md
@@ -704,7 +704,7 @@ mapper.clear()
 
 其中，编译时有如下参数可指定：
 
-- `weight_bit_optimization`: 是否对权重精度进行优化处理。例如，将声明时为 INT8 的权重根据实际值当作更小的精度处理（当权重的值均在 [-8, 7] 之间，则可当作 INT4 进行处理）。默认由后端配置项内对应**编译选项**指定（默认开启）。
+- `weight_bit_optimization`: 是否对权重精度进行优化处理。这将使得声明时为 INT8 的权重根据实际值当作更小的精度处理（当权重的值均在 [-8, 7] 之间，则可当作 INT4 进行处理）。默认由后端配置项内对应**编译选项**指定（默认开启）。
 - `grouping_optim_target`：指定神经元分组的优化目标，可以为 `"latency"`，`"core"` 或 `"both"`，分别代表以延时/吞吐率、占用核资源为优化目标、或二者兼顾。默认由后端配置项内对应**编译选项**指定（默认为 `both`）。
 - 同时，该方法将返回字典形式的编译后网络的信息。
 
@@ -713,8 +713,8 @@ mapper.clear()
 - `write_to_file`: 是否将配置帧导出为文件。默认为 `True`。
 - `fp`：导出目录。若未指定，则默认为后端配置选项 `build_directory` 所设置的目录（当前工作目录）。
 - `format`：导出交换文件格式，可以为 `bin`、`npy` 或 `txt`。默认为 `bin`。
-- `split_by_coordinate`：是否将配置帧以每个核坐标进行分割，由此生成的配置帧文件命名为"config_core1"、"config_core2"等。默认为 `False`。
-- `local_chip_addr`：本地芯片地址，元组格式表示。默认为后端配置项 `local_chip_addr` 所设置的默认值。
+- `split_by_coordinate`：是否将配置帧以每个核坐标进行分割，由此生成的配置帧文件命名为"config_core1"、"config_core2"等。默认为 `False`，即最终导出为一个文件。
+- `local_chip_addr`：本地芯片坐标，元组格式表示。默认为后端配置项 `local_chip_addr` 所设置的默认值。
 - `export_core_params`: 是否导出实际使用核参数至json文件，以直观显示实际使用核的配置信息。默认为 `False`。
 
 同时，该方法将返回模型的配置项字典 `GraphInfo`，包括：
@@ -724,17 +724,17 @@ mapper.clear()
 - `memebers`：中间层所在物理核的配置项字典。
 - `inherent_timestep`：网络模型的最长时间步。
 - `n_core_required`：网络模型需要的物理核数目。
-- `extras`：其他额外的网络信息字典，例如，编译后网络名称。
+- `extras`：其他额外的网络信息字典，例如，编译后的网络名称。
 
 ### 后端配置项
 
 与后端相关的配置项由 `BACKEND_CONFIG` 统一保存与访问，例如上述**编译选项**、`build_directory`、`local_chip_addr` 等。常用的配置项有如下：
 
 ```python
-BACKEND_CONFIG.local_chip_addr
+BACKEND_CONFIG.local_chip_addr # 本地芯片坐标
 >>> Coord(0, 0)
 
-BACKEND_CONFIG.test_chip_addr
+BACKEND_CONFIG.test_chip_addr # 测试芯片坐标（一般是FPGA）
 >>> Coord(1, 0)
 
 # Set output directory
diff --git a/poetry.lock b/poetry.lock
index 103cbcd7..685f01d2 100644
--- a/poetry.lock
+++ b/poetry.lock
@@ -1,4 +1,4 @@
-# This file is automatically @generated by Poetry 1.8.1 and should not be changed by hand.
+# This file is automatically @generated by Poetry 1.8.2 and should not be changed by hand.
 
 [[package]]
 name = "annotated-types"
@@ -56,18 +56,18 @@ reference = "tsinghua"
 
 [[package]]
 name = "filelock"
-version = "3.13.1"
+version = "3.13.3"
 description = "A platform independent file lock."
 optional = true
 python-versions = ">=3.8"
 files = [
-    {file = "filelock-3.13.1-py3-none-any.whl", hash = "sha256:57dbda9b35157b05fb3e58ee91448612eb674172fab98ee235ccb0b5bee19a1c"},
-    {file = "filelock-3.13.1.tar.gz", hash = "sha256:521f5f56c50f8426f5e03ad3b281b490a87ef15bc6c526f168290f0c7148d44e"},
+    {file = "filelock-3.13.3-py3-none-any.whl", hash = "sha256:5ffa845303983e7a0b7ae17636509bc97997d58afeafa72fb141a17b152284cb"},
+    {file = "filelock-3.13.3.tar.gz", hash = "sha256:a79895a25bbefdf55d1a2a0a80968f7dbb28edcd6d4234a0afb3f37ecde4b546"},
 ]
 
 [package.extras]
-docs = ["furo (>=2023.9.10)", "sphinx (>=7.2.6)", "sphinx-autodoc-typehints (>=1.24)"]
-testing = ["covdefaults (>=2.3)", "coverage (>=7.3.2)", "diff-cover (>=8)", "pytest (>=7.4.3)", "pytest-cov (>=4.1)", "pytest-mock (>=3.12)", "pytest-timeout (>=2.2)"]
+docs = ["furo (>=2023.9.10)", "sphinx (>=7.2.6)", "sphinx-autodoc-typehints (>=1.25.2)"]
+testing = ["covdefaults (>=2.3)", "coverage (>=7.3.2)", "diff-cover (>=8.0.1)", "pytest (>=7.4.3)", "pytest-cov (>=4.1)", "pytest-mock (>=3.12)", "pytest-timeout (>=2.2)"]
 typing = ["typing-extensions (>=4.8)"]
 
 [package.source]
@@ -554,21 +554,21 @@ reference = "tsinghua"
 
 [[package]]
 name = "torch"
-version = "2.2.1+cpu"
+version = "2.2.2+cpu"
 description = "Tensors and Dynamic neural networks in Python with strong GPU acceleration"
 optional = true
 python-versions = ">=3.8.0"
 files = [
-    {file = "torch-2.2.1+cpu-cp310-cp310-linux_x86_64.whl", hash = "sha256:5d82422cf04797f1b2a8574b64a916070ec83eef58ad4900615ee0218d7b8b8e"},
-    {file = "torch-2.2.1+cpu-cp310-cp310-win_amd64.whl", hash = "sha256:f8914dd0f5f0e5c66fdecd9559403eea9feac82d1ea639b672fde0073c6addbd"},
-    {file = "torch-2.2.1+cpu-cp311-cp311-linux_x86_64.whl", hash = "sha256:6bc973d5632374b92b4b293817b4d2ff8c8ce1c784c748b471dba1fffcd9c333"},
-    {file = "torch-2.2.1+cpu-cp311-cp311-win_amd64.whl", hash = "sha256:abdec34b0ade8fca0520055e72c3094425ae0ef210718e9c0278121cd3608c32"},
-    {file = "torch-2.2.1+cpu-cp312-cp312-linux_x86_64.whl", hash = "sha256:d7339580135da4105c1244a8621faa076990409afeab5a7b642c3c1ee70a5622"},
-    {file = "torch-2.2.1+cpu-cp312-cp312-win_amd64.whl", hash = "sha256:039128fcb5548122465b15f679b8831c47d14f0d6c28c1f1b631f8019c104720"},
-    {file = "torch-2.2.1+cpu-cp38-cp38-linux_x86_64.whl", hash = "sha256:2b447f7bb50b393b4544b4036d587e39ab524d4353e77c197f6a2727f22b0d47"},
-    {file = "torch-2.2.1+cpu-cp38-cp38-win_amd64.whl", hash = "sha256:2ccdf3e5f71e6426ea9e34d21c3cc333b29d4f48299b981d28aeb5112b5495e1"},
-    {file = "torch-2.2.1+cpu-cp39-cp39-linux_x86_64.whl", hash = "sha256:2fb340b289760040a16a77a6d70b8a48961abba1822e6f58705c97c80befa03e"},
-    {file = "torch-2.2.1+cpu-cp39-cp39-win_amd64.whl", hash = "sha256:e03dc4654ecceeb5b03f0a6f60b342c0e0d267b3ebc61e4f672cace1df8cd930"},
+    {file = "torch-2.2.2+cpu-cp310-cp310-linux_x86_64.whl", hash = "sha256:02c4fac3c964e73f5f49003e0060c697f73b67c10cc23f51c592facb29e1bd53"},
+    {file = "torch-2.2.2+cpu-cp310-cp310-win_amd64.whl", hash = "sha256:fc29dda2795dd7220d769c5926b1c50ddac9b4827897e30a10467063691cdf54"},
+    {file = "torch-2.2.2+cpu-cp311-cp311-linux_x86_64.whl", hash = "sha256:90089cae572672fb449c8ff1dc1b29daaffa117bf97ede7463dcd2fd1b991e4c"},
+    {file = "torch-2.2.2+cpu-cp311-cp311-win_amd64.whl", hash = "sha256:88e63c916e3275fa30a220ee736423a95573b96072ded85e5c0171fd8f37a755"},
+    {file = "torch-2.2.2+cpu-cp312-cp312-linux_x86_64.whl", hash = "sha256:431a747b5a880cf8e1fb6d58db6bfafa6768cbec76517d046854537c03323edf"},
+    {file = "torch-2.2.2+cpu-cp312-cp312-win_amd64.whl", hash = "sha256:2b0cf041f878607a361116945f82ce2dba4b7a747151da7619a63cb5fccb72df"},
+    {file = "torch-2.2.2+cpu-cp38-cp38-linux_x86_64.whl", hash = "sha256:8914ce932168e572a09b4a7e5b0806d279f771dfe58d7e1d8de2291fac4ce69b"},
+    {file = "torch-2.2.2+cpu-cp38-cp38-win_amd64.whl", hash = "sha256:4ef2911ffde6d86f643c23aa99f25f1a1df8bee93bf8d0c69cf1b9ba0ca521dc"},
+    {file = "torch-2.2.2+cpu-cp39-cp39-linux_x86_64.whl", hash = "sha256:6e3d323a21df22415770e88d39e13591079b9356dabb8b394d1ee29ac6c92481"},
+    {file = "torch-2.2.2+cpu-cp39-cp39-win_amd64.whl", hash = "sha256:c2c9e7d5e3c7d58e4b78d6aebfa8002af7cda16cde08d0e3ed00300dc21a8efc"},
 ]
 
 [package.dependencies]
diff --git a/pyproject.toml b/pyproject.toml
index 4fde8d11..943d1f11 100644
--- a/pyproject.toml
+++ b/pyproject.toml
@@ -1,6 +1,6 @@
 [tool.poetry]
 name = "paibox"
-version = "1.0.0a7"
+version = "1.0.0b1"
 description = "New toolbox of PAICORE 2.0."
 authors = ["Ziru Pan <zrpan@stu.pku.edu.cn>"]
 maintainers = ["Ziru Pan <zrpan@stu.pku.edu.cn>"]

From 8496e60a405ac04de7ebabec7cf036dc8cdb96a0 Mon Sep 17 00:00:00 2001
From: KafCoppelia <k740677208@gmail.com>
Date: Wed, 3 Apr 2024 10:11:00 +0800
Subject: [PATCH 54/68] =?UTF-8?q?=E2=9C=A8=20set=20coarse=20dtype=20for=20?=
 =?UTF-8?q?raw=20weights=20when=20instantiating=20Transform?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

---
 paibox/synapses/transforms.py | 170 ++++++++++++++++++++--------------
 1 file changed, 102 insertions(+), 68 deletions(-)

diff --git a/paibox/synapses/transforms.py b/paibox/synapses/transforms.py
index 2707d88c..0fee032b 100644
--- a/paibox/synapses/transforms.py
+++ b/paibox/synapses/transforms.py
@@ -1,11 +1,11 @@
 from enum import Enum, auto, unique
-from typing import Type, Union
+import warnings
 
 import numpy as np
-from numpy.typing import NDArray
+
 from paicorelib import WeightPrecision as WP
 
-from paibox.exceptions import ShapeError
+from paibox.exceptions import AutoOptimizationWarning, ShapeError
 from paibox.types import DataArrayType, IntScalarType, SynOutType, WeightType
 from paibox.utils import is_shape
 
@@ -62,32 +62,88 @@ class GeneralConnType(ConnType):
     """All-to-all connection."""
 
 
-def _get_weight_precision(weight: np.ndarray, enable_wp_opt: bool) -> WP:
-    """Get the actual weight_precision of the weight."""
-    _max = np.max(weight, axis=None).astype(np.int32)
-    _min = np.min(weight, axis=None).astype(np.int32)
+def _set_coarse_dtype(raw_w: DataArrayType) -> WeightType:
+    """Convert raw weights to `np.ndarray` coarsely (without optimization).
+
+    Description:
+        - For weights of type `bool` or `np.bool_`, set `np.bool_` as the dtype.
+        - For integer scalar weight, set the dtype according to its value.
+        - For array weights, set the dtype according to its minimum & maximum values. For weights in the\
+            range of int8, the dtype when declared will be followed (i.e. not optimized).
+    
+    NOTE: Only when the weight is input in integer scalar form, the weight precision will be optimized  \
+        automatically. 0/1 is treated as bool_ while others are treated as int8. The weights must not   \
+        exceed the range of int8.
+    """
+    if isinstance(raw_w, (bool, np.bool_, int, np.integer)):
+        if raw_w > MAX_INT8 or raw_w < MIN_INT8:
+            raise ValueError(f"weight out of range int8, got {raw_w}.")
+
+        if raw_w <= MAX_INT1 and raw_w >= MIN_INT1:
+            _dtype = np.bool_
+        else:
+            _dtype = np.int8
+
+        return np.asarray(raw_w, dtype=_dtype)
+
+    # Convert list or tuple to np.ndarray
+    _array = np.asarray(raw_w)
+    _max = np.max(_array, axis=None)
+    _min = np.min(_array, axis=None)
 
     if _max > MAX_INT8 or _min < MIN_INT8:
-        raise ValueError(f"weight precision out of range [{_min}, {_max}].")
-
-    # If weight precision opt is disabled, return WP8 directly.
-    if not enable_wp_opt:
-        return WP.WEIGHT_WIDTH_8BIT
-
-    if _max <= MAX_INT1 and _min >= MIN_INT1:
-        return WP.WEIGHT_WIDTH_1BIT
-    elif _max <= MAX_INT2 and _min >= MIN_INT2:
-        return WP.WEIGHT_WIDTH_2BIT
-    elif _max <= MAX_INT4 and _min >= MIN_INT4:
-        return WP.WEIGHT_WIDTH_4BIT
+        raise ValueError(f"weight out of range int8, got [{_min}, {_max}].")
+
+    if _array.dtype > np.int8:
+        # XXX If it is automatically optimized to int8, it cannot be converted using the 'same_kind' rule.
+        # if _max <= MAX_INT1 and _min >= MIN_INT1:
+        #     warnings.warn(
+        #         f"dtype of weight is optimized automatically, {_array.dtype} -> bool.",
+        #         AutoOptimizationWarning,
+        #     )
+        #     _dtype = np.bool_
+        # else:
+        warnings.warn(
+            f"dtype of weight is optimized automatically, {_array.dtype} -> int8.",
+            AutoOptimizationWarning,
+        )
+        _dtype = np.int8
+
+    elif _array.dtype == np.bool_ or _array.dtype == np.int8:
+        _dtype = _array.dtype
     else:
-        return WP.WEIGHT_WIDTH_8BIT
+        raise TypeError(f"weights must be bool or int8, but got {_array.dtype}.")
+
+    return _array.astype(_dtype, casting="same_kind")
+
+
+def _get_weight_precision(weight: WeightType, enable_wp_opt: bool) -> WP:
+    """Get the actual weight_precision of the weight."""
+    _max = np.max(weight, axis=None)
+    _min = np.min(weight, axis=None)
+
+    if enable_wp_opt:
+        if _max <= MAX_INT1 and _min >= MIN_INT1:
+            return WP.WEIGHT_WIDTH_1BIT
+        elif _max <= MAX_INT2 and _min >= MIN_INT2:
+            return WP.WEIGHT_WIDTH_2BIT
+        elif _max <= MAX_INT4 and _min >= MIN_INT4:
+            return WP.WEIGHT_WIDTH_4BIT
+        else:
+            return WP.WEIGHT_WIDTH_8BIT
+    else:
+        # If weight precision opt is disabled, return WP1 if dtype is np.bool_ else WP8.
+        if weight.dtype == np.bool_:
+            return WP.WEIGHT_WIDTH_1BIT
+        else:
+            return WP.WEIGHT_WIDTH_8BIT
 
 
 class Transform:
-    def __init__(self, weights: WeightType) -> None:
-        self.weights = weights
-        """The actual weights in synapse. Must stored in `np.int8` format."""
+    def __init__(self, weights: DataArrayType) -> None:
+        self.weights = _set_coarse_dtype(weights)
+
+        """The actual weights in synapses. Stored in `np.bool_` or `np.int8` format."""
         self.weights.setflags(write=False)
 
     def __call__(self, *args, **kwargs) -> SynOutType:
@@ -95,19 +151,10 @@ def __call__(self, *args, **kwargs) -> SynOutType:
         raise NotImplementedError
 
     def _get_wp(self, enable_wp_opt: bool) -> WP:
-        """Precision of weights."""
         return _get_weight_precision(self.weights, enable_wp_opt)
 
     @property
-    def conn_dtype(self) -> Union[Type[np.bool_], Type[np.int8]]:
-        # The value of `enable_wp_opt` dosen't effect the dtype of `connectivity`.
-        if self._get_wp(enable_wp_opt=False) is WP.WEIGHT_WIDTH_1BIT:
-            return np.bool_
-        else:
-            return np.int8
-
-    @property
-    def connectivity(self) -> NDArray[Union[np.bool_, np.int8]]:
+    def connectivity(self) -> WeightType:
         """The connectivity matrix in `np.ndarray` format."""
         raise NotImplementedError
 
@@ -133,13 +180,13 @@ def __init__(self, num: int, weights: DataArrayType) -> None:
         if isinstance(weights, np.ndarray) and not is_shape(weights, (num,)):
             raise ShapeError(f"expected shape is ({num},), but got {weights.shape}.")
 
-        # The ndim of weights = 0 or 1.
-        _w = np.asarray(weights, dtype=np.int8)
-
-        if _w.ndim not in (0, 1):
-            raise ShapeError(f"the ndim of weights must be 0 or 1, but got {_w.ndim}.")
+        super().__init__(weights)
 
-        super().__init__(_w)
+        # The ndim of weights = 0 or 1.
+        if self.weights.ndim not in (0, 1):
+            raise ShapeError(
+                f"the ndim of weights must be 0 or 1, but got {self.weights.ndim}."
+            )
 
     def __call__(self, x: np.ndarray, *args, **kwargs) -> SynOutType:
         # (N,) * (N,) -> (N,)
@@ -150,9 +197,9 @@ def __call__(self, x: np.ndarray, *args, **kwargs) -> SynOutType:
     @property
     def connectivity(self):
         return (
-            (self.weights * np.eye(self.num, dtype=np.bool_)).astype(self.conn_dtype)
+            (self.weights * np.eye(self.num, dtype=np.bool_))
             if self.weights.ndim == 0
-            else np.diag(self.weights).astype(self.conn_dtype)
+            else np.diag(self.weights)
         )
 
 
@@ -184,12 +231,12 @@ def __init__(self, conn_size: Size2Type, weights: DataArrayType) -> None:
         if isinstance(weights, np.ndarray) and not is_shape(weights, conn_size):
             raise ShapeError(f"expected shape is {conn_size}, but got {weights.shape}.")
 
-        _w = np.asarray(weights, dtype=np.int8)
-
-        if _w.ndim not in (0, 2):
-            raise ShapeError(f"the ndim of weights must be 0 or 2, but got {_w.ndim}.")
+        super().__init__(weights)
 
-        super().__init__(_w)
+        if self.weights.ndim not in (0, 2):
+            raise ShapeError(
+                f"the ndim of weights must be 0 or 2, but got {self.weights.ndim}."
+            )
 
     def __call__(self, x: np.ndarray, *args, **kwargs) -> SynOutType:
         """
@@ -211,25 +258,18 @@ def __call__(self, x: np.ndarray, *args, **kwargs) -> SynOutType:
     @property
     def connectivity(self):
         return (
-            self.weights.astype(self.conn_dtype)
+            self.weights
             if self.weights.ndim == 2
-            else (self.weights * np.ones(self.conn_size, dtype=np.bool_)).astype(
-                self.conn_dtype
-            )
+            else (self.weights * np.ones(self.conn_size, dtype=np.bool_))
         )
 
 
 class MaskedLinear(Transform):
-    def __init__(
-        self,
-        conn_size: Size2Type,
-        weights: np.ndarray,
-    ) -> None:
+    def __init__(self, conn_size: Size2Type, weights: np.ndarray) -> None:
         if not is_shape(weights, conn_size):
             raise ShapeError(f"expected shape is {conn_size}, but got {weights.shape}.")
 
-        _w = np.asarray(weights, dtype=np.int8)
-        super().__init__(_w)
+        super().__init__(weights)
 
     def __call__(self, x: np.ndarray, *args, **kwargs) -> SynOutType:
         # (N,) @ (N, M) -> (M,)
@@ -239,7 +279,7 @@ def __call__(self, x: np.ndarray, *args, **kwargs) -> SynOutType:
 
     @property
     def connectivity(self):
-        return self.weights.astype(self.conn_dtype)
+        return self.weights
 
 
 class Conv1dForward(Transform):
@@ -258,8 +298,7 @@ def __init__(
         self.padding = padding
         self.fm_order = fm_order
 
-        _w = kernel.astype(np.int8)
-        super().__init__(_w)
+        super().__init__(kernel)
 
     def __call__(self, x: np.ndarray, *args, **kwargs) -> SynOutType:
         cin = self.weights.shape[1]
@@ -282,9 +321,7 @@ def __call__(self, x: np.ndarray, *args, **kwargs) -> SynOutType:
 
     @property
     def connectivity(self):
-        return _conv1d_unroll(
-            self.in_shape, self.out_shape, self.weights, self.stride
-        ).astype(self.conn_dtype)
+        return _conv1d_unroll(self.in_shape, self.out_shape, self.weights, self.stride)
 
 
 class Conv2dForward(Transform):
@@ -303,8 +340,7 @@ def __init__(
         self.padding = padding
         self.fm_order = fm_order
 
-        _w = kernel.astype(np.int8)
-        super().__init__(_w)
+        super().__init__(kernel)
 
     def __call__(self, x: np.ndarray, *args, **kwargs) -> SynOutType:
         cin = self.weights.shape[1]
@@ -327,6 +363,4 @@ def __call__(self, x: np.ndarray, *args, **kwargs) -> SynOutType:
 
     @property
     def connectivity(self):
-        return _conv2d_unroll(
-            self.in_shape, self.out_shape, self.weights, self.stride
-        ).astype(self.conn_dtype)
\ No newline at end of file
+        return _conv2d_unroll(self.in_shape, self.out_shape, self.weights, self.stride)

From 09a3166c7e97c1cbd4bb21cbecee1c173db5862d Mon Sep 17 00:00:00 2001
From: "pre-commit-ci[bot]"
 <66853113+pre-commit-ci[bot]@users.noreply.github.com>
Date: Wed, 3 Apr 2024 02:15:40 +0000
Subject: [PATCH 55/68] :rotating_light: auto fix by pre-commit hooks

---
 TODO.md                       |  4 ++++
 docs/Guide-of-PAIBox.md       |  1 +
 paibox/synapses/base.py       | 13 +++----------
 paibox/synapses/transforms.py |  5 ++---
 4 files changed, 10 insertions(+), 13 deletions(-)

diff --git a/TODO.md b/TODO.md
index 82c7fcd7..fb288d8f 100644
--- a/TODO.md
+++ b/TODO.md
@@ -22,10 +22,12 @@
   - [ ] 脉冲加、减法
   - [ ] 残差结构
   - [ ] 半折叠2D卷积
+
 - 多层次结构网络组件的发现、数据流验证与后端解析
 
   - [x] 对有层次结构（子网络例化复用等情形）的网络模型，实现在所有层次上网络组件的发现、数据流与后端解析实现
   - [ ] 局部连接包装成单个算子，实现在所有层次上网络组件的发现、数据流与后端解析实现
+
 - 带有约束的路由坐标分配
 
   - [ ] 支持芯片阵列部署
@@ -44,9 +46,11 @@
 
   - [x] 当开启时，当不同精度突触被分在同一组时，将按照最大精度处理；当分在不同组时，按各自精度处理
   - [ ] 当关闭时，不同精度突触将**不被分在同一组**（即对初次分配的CB进行分割，分割后得到的多个CB仍处于同一RG内）
+
 - [ ] ANN模式前后端支持
 
   - 目前仅支持芯片的SNN模式。要想支持ANN模式，前端上需要支持ANN模式的算理。同时，ANN/SNN模式是物理核的行为，因此当网络拓扑中同时存在两种模式的神经元时，需要以此为约束条件，从而影响分组结果（类似第6点。例如，同为ANN模式下的不同神经元可被分在同一组）
+
 - [ ] 神经元计算模型随机性仿真
 
   - 基于硬件神经元计算机制，实现带有部分随机数的计算机制。并考虑与硬件的实现相接近的程度（能否接近实现与硬件一致的随机数发生行为）
diff --git a/docs/Guide-of-PAIBox.md b/docs/Guide-of-PAIBox.md
index 3b57a55b..93780276 100644
--- a/docs/Guide-of-PAIBox.md
+++ b/docs/Guide-of-PAIBox.md
@@ -227,6 +227,7 @@ s1= pb.FullConn(source=n1, dest=n2, weights=weight1, conn_type=pb.SynConnType.Al
   ```
 
   其权重以标量的形式储存。
+
 - 数组：尺寸要求为 `(N2,)`，可以自定义每组对应神经元之间的连接权重。如下例所示，设置 `weights` 为 `[1, 2, 3, 4, 5]`，
 
   ```python
diff --git a/paibox/synapses/base.py b/paibox/synapses/base.py
index bbdc0d13..0de0334c 100644
--- a/paibox/synapses/base.py
+++ b/paibox/synapses/base.py
@@ -18,16 +18,9 @@
     _Order2d,
     _Order3d,
 )
-from .transforms import (
-    AllToAll,
-    Conv1dForward,
-    Conv2dForward,
-    GeneralConnType as GConnType,
-    Identity,
-    MaskedLinear,
-    OneToOne,
-    Transform,
-)
+from .transforms import AllToAll, Conv1dForward, Conv2dForward
+from .transforms import GeneralConnType as GConnType
+from .transforms import Identity, MaskedLinear, OneToOne, Transform
 
 RIGISTER_MASTER_KEY_FORMAT = "{0}.output"
 
diff --git a/paibox/synapses/transforms.py b/paibox/synapses/transforms.py
index 0fee032b..e6f6397e 100644
--- a/paibox/synapses/transforms.py
+++ b/paibox/synapses/transforms.py
@@ -1,8 +1,7 @@
-from enum import Enum, auto, unique
 import warnings
+from enum import Enum, auto, unique
 
 import numpy as np
-
 from paicorelib import WeightPrecision as WP
 
 from paibox.exceptions import AutoOptimizationWarning, ShapeError
@@ -70,7 +69,7 @@ def _set_coarse_dtype(raw_w: DataArrayType) -> WeightType:
         - For integer scalar weight, set the dtype according to its value.
         - For array weights, set the dtype according to its minimum & maximum values. For weights in the\
             range of int8, the dtype when declared will be followed (i.e. not optimized).
-    
+
     NOTE: Only when the weight is input in integer scalar form, the weight precision will be optimized  \
         automatically. 0/1 is treated as bool_ while others are treated as int8. The weights must not   \
         exceed the range of int8.

From b6ae4e0595db58dd6a5517e853dc01904408151d Mon Sep 17 00:00:00 2001
From: KafCoppelia <k740677208@gmail.com>
Date: Wed, 3 Apr 2024 23:08:32 +0800
Subject: [PATCH 56/68] =?UTF-8?q?=F0=9F=94=A5=20removed=20fm=5Forder=20of?=
 =?UTF-8?q?=20conv1d,=20conv2d?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

---
 paibox/synapses/base.py       | 29 ++++++++-------------
 paibox/synapses/synapses.py   | 48 +++++++++++++++++------------------
 paibox/synapses/transforms.py | 48 ++++++++++++++---------------------
 3 files changed, 53 insertions(+), 72 deletions(-)

diff --git a/paibox/synapses/base.py b/paibox/synapses/base.py
index 0de0334c..0a76007b 100644
--- a/paibox/synapses/base.py
+++ b/paibox/synapses/base.py
@@ -10,14 +10,7 @@
 from paibox.projection import InputProj
 from paibox.types import DataArrayType, SynOutType, WeightType
 
-from .conv_utils import (
-    _fm_ndim1_check,
-    _fm_ndim2_check,
-    _KOrder3d,
-    _KOrder4d,
-    _Order2d,
-    _Order3d,
-)
+from .conv_utils import _fm_ndim1_check, _fm_ndim2_check, _KOrder3d, _KOrder4d
 from .transforms import AllToAll, Conv1dForward, Conv2dForward
 from .transforms import GeneralConnType as GConnType
 from .transforms import Identity, MaskedLinear, OneToOne, Transform
@@ -98,7 +91,7 @@ def update(self, spike: Optional[np.ndarray] = None, *args, **kwargs) -> SynOutT
             # Retrieve 0 to the dest neurons if it is not working
             synin = np.zeros_like(self.source.spike, dtype=np.bool_)
 
-        self._synout = self.comm(synin).astype(np.int32)
+        self._synout = self.comm(synin).ravel().astype(np.int32)
         return self._synout
 
     def reset_state(self, *args, **kwargs) -> None:
@@ -167,7 +160,7 @@ def __init__(
         kernel: np.ndarray,
         stride: Tuple[int],
         # padding: Tuple[int],
-        fm_order: _Order2d,
+        # fm_order: _Order2d,
         order: _KOrder3d,
         name: Optional[str] = None,
     ) -> None:
@@ -187,8 +180,8 @@ def __init__(
         out_channels, in_channels, kernel_l = _kernel.shape
 
         # C,L
-        in_ch, in_l = _fm_ndim1_check(source.shape_out, fm_order)
-        out_ch, out_l = _fm_ndim1_check(dest.shape_out, fm_order)
+        in_ch, in_l = _fm_ndim1_check(source.shape_out, "CL")
+        out_ch, out_l = _fm_ndim1_check(dest.shape_out, "CL")
 
         if in_ch != in_channels:
             raise ShapeError(f"input channels mismatch: {in_ch} != {in_channels}.")
@@ -202,7 +195,7 @@ def __init__(
 
         assert (in_l + 2 * padding[0] - kernel_l) // stride[0] + 1 == out_l
 
-        comm = Conv1dForward((in_l,), (out_l,), _kernel, stride, padding, fm_order)
+        comm = Conv1dForward((in_l,), (out_l,), _kernel, stride, padding)
 
         self.comm = comm
 
@@ -217,7 +210,7 @@ def __init__(
         kernel: np.ndarray,
         stride: Tuple[int, int],
         # padding: Tuple[int, int],
-        fm_order: _Order3d,
+        # fm_order: _Order3d,
         order: _KOrder4d,
         name: Optional[str] = None,
     ) -> None:
@@ -237,8 +230,8 @@ def __init__(
         out_channels, in_channels, kernel_h, kernel_w = _kernel.shape
 
         # C,H,W
-        in_ch, in_h, in_w = _fm_ndim2_check(source.shape_out, fm_order)
-        out_ch, out_h, out_w = _fm_ndim2_check(dest.shape_out, fm_order)
+        in_ch, in_h, in_w = _fm_ndim2_check(source.shape_out, "CHW")
+        out_ch, out_h, out_w = _fm_ndim2_check(dest.shape_out, "CHW")
 
         if in_ch != in_channels:
             raise ShapeError(f"input channels mismatch: {in_ch} != {in_channels}.")
@@ -253,8 +246,6 @@ def __init__(
         assert (in_h + 2 * padding[0] - kernel_h) // stride[0] + 1 == out_h
         assert (in_w + 2 * padding[1] - kernel_w) // stride[1] + 1 == out_w
 
-        comm = Conv2dForward(
-            (in_h, in_w), (out_h, out_w), _kernel, stride, padding, fm_order
-        )
+        comm = Conv2dForward((in_h, in_w), (out_h, out_w), _kernel, stride, padding)
 
         self._set_comm(comm)
diff --git a/paibox/synapses/synapses.py b/paibox/synapses/synapses.py
index ac666bea..4eda3998 100644
--- a/paibox/synapses/synapses.py
+++ b/paibox/synapses/synapses.py
@@ -9,16 +9,7 @@
 from paibox.types import DataArrayType
 
 from .base import Conv1dSyn, Conv2dSyn, FullConnSyn
-from .conv_utils import (
-    _KOrder3d,
-    _KOrder4d,
-    _Order2d,
-    _Order3d,
-    _pair,
-    _single,
-    _Size1Type,
-    _Size2Type,
-)
+from .conv_utils import _KOrder3d, _KOrder4d, _pair, _single, _Size1Type, _Size2Type
 from .transforms import GeneralConnType as GConnType
 
 __all__ = ["FullConn", "Conv1d", "Conv2d"]
@@ -72,12 +63,24 @@ def __init__(
         *,
         stride: _Size1Type = 1,
         # padding: _Size1Type = 0,
-        fm_order: _Order2d = "CL",
+        # fm_order: _Order2d = "CL",
         kernel_order: _KOrder3d = "OIL",
         name: Optional[str] = None,
     ) -> None:
-        if fm_order not in ("CL", "LC"):
-            raise ValueError(f"feature map order must be 'CL' or 'LC'.")
+        """1d convolution synapses in fully-unrolled format.
+
+        Arguments:
+            - source: source neuron(s). The dimensions need to be expressed explicitly as (C,L).
+            - dest: destination neuron(s).
+            - kernel: convolution kernel. Its dimension order is either (O,I,L) or (I,O,L), depending on \
+                the argument `kernel_order`.
+            - stride: the step size of the kernel sliding. It can be a scalar or a tuple of 2 integers.
+            - kernel_order: dimension order of kernel, (O,I,L) or (I,O,L). (O,I,L) stands for (output   \
+                channels, input channels, length).
+            - name: name of the 1d convolution. Optional.
+        """
+        # if fm_order not in ("CL", "LC"):
+        #     raise ValueError(f"feature map order must be 'CL' or 'LC'.")
 
         if kernel_order not in ("OIL", "IOL"):
             raise ValueError(f"kernel order must be 'OIL' or 'IOL'.")
@@ -88,7 +91,7 @@ def __init__(
             kernel,
             _single(stride),
             # _single(padding),
-            fm_order,
+            # fm_order,
             kernel_order,
             name=name,
         )
@@ -103,27 +106,24 @@ def __init__(
         *,
         stride: _Size2Type = 1,
         # padding: _Size2Type = 0,
-        fm_order: _Order3d = "CHW",
+        # fm_order: _Order3d = "CHW",
         kernel_order: _KOrder4d = "OIHW",
         name: Optional[str] = None,
     ) -> None:
         """2d convolution synapses in fully-unrolled format.
 
         Arguments:
-            - source: source neuron(s). The dimensions need to be expressed explicitly as (C,H,W) or    \
-                (H,W,C). The feature map dimension order is specified by `fm_order`.
+            - source: source neuron(s). The dimensions need to be expressed explicitly as (C,H,W).
             - dest: destination neuron(s).
-            - kernel: convolution kernel. Its dimension order must be (O,I,H,W) or (I,O,H,W), depending \
-                on the argument `kernel_order`.
+            - kernel: convolution kernel. Its dimension order is either (O,I,H,W) or (I,O,H,W),         \
+                depending on the argument `kernel_order`.
             - stride: the step size of the kernel sliding. It can be a scalar or a tuple of 2 integers.
-            - fm_order: dimension order of feature map. The order of input & output feature maps must be\
-                consistent, (C,H,W) or (H,W,C).
             - kernel_order: dimension order of kernel, (O,I,H,W) or (I,O,H,W). (O,I,H,W) stands for     \
                 (output channels, input channels, height, width).
             - name: name of the 2d convolution. Optional.
         """
-        if fm_order not in ("CHW", "HWC"):
-            raise ValueError(f"feature map order must be 'CHW or 'HWC'.")
+        # if fm_order not in ("CHW", "HWC"):
+        #     raise ValueError(f"feature map order must be 'CHW or 'HWC'.")
 
         if kernel_order not in ("OIHW", "IOHW"):
             raise ValueError(f"kernel order must be 'OIHW' or 'IOHW'.")
@@ -134,7 +134,7 @@ def __init__(
             kernel,
             _pair(stride),
             # _pair(padding),
-            fm_order,
+            # fm_order,
             kernel_order,
             name=name,
         )
diff --git a/paibox/synapses/transforms.py b/paibox/synapses/transforms.py
index e6f6397e..95ddd656 100644
--- a/paibox/synapses/transforms.py
+++ b/paibox/synapses/transforms.py
@@ -15,8 +15,6 @@
     _conv1d_unroll,
     _conv2d_faster,
     _conv2d_unroll,
-    _Order2d,
-    _Order3d,
 )
 
 __all__ = [
@@ -189,9 +187,7 @@ def __init__(self, num: int, weights: DataArrayType) -> None:
 
     def __call__(self, x: np.ndarray, *args, **kwargs) -> SynOutType:
         # (N,) * (N,) -> (N,)
-        output = x * self.weights.copy()
-
-        return output.astype(np.int32)
+        return x * self.weights.astype(np.int32)
 
     @property
     def connectivity(self):
@@ -250,7 +246,7 @@ def __call__(self, x: np.ndarray, *args, **kwargs) -> SynOutType:
             output = np.full((self.conn_size[1],), self.weights * sum_x, dtype=np.int32)
         else:
             # (N,) @ (N, M) -> (M,)
-            output = x @ self.weights.copy().astype(np.int32)
+            output = x @ self.weights.astype(np.int32)
 
         return output
 
@@ -272,9 +268,7 @@ def __init__(self, conn_size: Size2Type, weights: np.ndarray) -> None:
 
     def __call__(self, x: np.ndarray, *args, **kwargs) -> SynOutType:
         # (N,) @ (N, M) -> (M,)
-        output = x @ self.weights.copy().astype(np.int32)
-
-        return output.astype(np.int32)
+        return x @ self.weights.astype(np.int32)
 
     @property
     def connectivity(self):
@@ -289,26 +283,26 @@ def __init__(
         kernel: np.ndarray,
         stride: Size1Type,
         padding: Size1Type,
-        fm_order: _Order2d,
+        # fm_order: _Order2d,
     ) -> None:
         self.in_shape = in_shape
         self.out_shape = out_shape
         self.stride = stride
         self.padding = padding
-        self.fm_order = fm_order
+        # self.fm_order = fm_order
 
         super().__init__(kernel)
 
     def __call__(self, x: np.ndarray, *args, **kwargs) -> SynOutType:
         cin = self.weights.shape[1]
 
-        if self.fm_order == "LC":
-            # (N,) -> (L, C) -> (C, L)
-            _x = x.reshape(self.in_shape + (cin,)).T
-        else:
-            _x = x.reshape((cin,) + self.in_shape)
+        # if self.fm_order == "LC":
+        #     # (N,) -> (L, C) -> (C, L)
+        #     _x = x.reshape(self.in_shape + (cin,)).T
+        # else:
+        _x = x.reshape((cin,) + self.in_shape)
 
-        o_conv1d = _conv1d_faster(
+        return _conv1d_faster(
             _x,
             self.out_shape,
             self.weights,
@@ -316,8 +310,6 @@ def __call__(self, x: np.ndarray, *args, **kwargs) -> SynOutType:
             self.padding,
         )
 
-        return o_conv1d.flatten()
-
     @property
     def connectivity(self):
         return _conv1d_unroll(self.in_shape, self.out_shape, self.weights, self.stride)
@@ -331,26 +323,26 @@ def __init__(
         kernel: np.ndarray,
         stride: Size2Type,
         padding: Size2Type,
-        fm_order: _Order3d,
+        # fm_order: _Order3d,
     ) -> None:
         self.in_shape = in_shape
         self.out_shape = out_shape
         self.stride = stride
         self.padding = padding
-        self.fm_order = fm_order
+        # self.fm_order = fm_order
 
         super().__init__(kernel)
 
     def __call__(self, x: np.ndarray, *args, **kwargs) -> SynOutType:
         cin = self.weights.shape[1]
 
-        if self.fm_order == "HWC":
-            # (N,) -> (H, W, C) -> (C, H, W)
-            _x = x.reshape(self.in_shape + (cin,)).transpose(2, 0, 1)
-        else:
-            _x = x.reshape((cin,) + self.in_shape)
+        # if self.fm_order == "HWC":
+        #     # (N,) -> (H, W, C) -> (C, H, W)
+        #     _x = x.reshape(self.in_shape + (cin,)).transpose(2, 0, 1)
+        # else:
+        _x = x.reshape((cin,) + self.in_shape)
 
-        o_conv2d = _conv2d_faster(
+        return _conv2d_faster(
             _x,
             self.out_shape,
             self.weights,
@@ -358,8 +350,6 @@ def __call__(self, x: np.ndarray, *args, **kwargs) -> SynOutType:
             self.padding,
         )
 
-        return o_conv2d.flatten()
-
     @property
     def connectivity(self):
         return _conv2d_unroll(self.in_shape, self.out_shape, self.weights, self.stride)

From 6c2771765c4164570c87eff61bfe2d952e6f7d4c Mon Sep 17 00:00:00 2001
From: KafCoppelia <k740677208@gmail.com>
Date: Wed, 3 Apr 2024 23:09:24 +0800
Subject: [PATCH 57/68] =?UTF-8?q?=E2=9C=85=20added=20test=20cases=20&=20sy?=
 =?UTF-8?q?nc=20changes?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

---
 tests/synapses/test_synapses.py   |  16 +---
 tests/synapses/test_transforms.py | 120 +++++++++++++++++++-----------
 2 files changed, 81 insertions(+), 55 deletions(-)

diff --git a/tests/synapses/test_synapses.py b/tests/synapses/test_synapses.py
index 46f3cf6f..34644bd3 100644
--- a/tests/synapses/test_synapses.py
+++ b/tests/synapses/test_synapses.py
@@ -286,9 +286,7 @@ def test_Conv1d_instance(self):
         weight = np.random.randint(
             -128, 128, size=(in_channels, out_channels) + kernel_size, dtype=np.int8
         )
-        s1 = pb.Conv1d(
-            n1, n2, weight, stride=stride, fm_order="CL", kernel_order=korder
-        )
+        s1 = pb.Conv1d(n1, n2, weight, stride=stride, kernel_order=korder)
 
         assert s1.num_in == in_channels * shape2num(in_shape)
         assert s1.connectivity.dtype == np.int8
@@ -312,9 +310,7 @@ def test_Conv2d_instance(self):
         weight = np.random.randint(
             -8, 8, size=(in_channels, out_channels) + kernel_size, dtype=np.int32
         )
-        s1 = pb.Conv2d(
-            n1, n2, weight, stride=stride, fm_order="CHW", kernel_order=korder
-        )
+        s1 = pb.Conv2d(n1, n2, weight, stride=stride, kernel_order=korder)
 
         assert s1.num_in == in_channels * shape2num(in_shape)
         assert s1.connectivity.dtype == np.int8
@@ -338,9 +334,7 @@ def test_Conv1d_inchannel_omitted(self):
         weight = np.random.randint(
             -128, 128, size=(in_channels, out_channels) + kernel_size, dtype=np.int64
         )
-        s1 = pb.Conv1d(
-            n1, n2, weight, stride=stride, fm_order="CL", kernel_order=korder
-        )
+        s1 = pb.Conv1d(n1, n2, weight, stride=stride, kernel_order=korder)
 
         assert s1.num_in == in_channels * shape2num(in_shape)
         assert s1.connectivity.dtype == np.int8
@@ -364,9 +358,7 @@ def test_Conv2d_inchannel_omitted(self):
         weight = np.random.randint(
             -128, 128, size=(in_channels, out_channels) + kernel_size, dtype=np.int8
         )
-        s1 = pb.Conv2d(
-            n1, n2, weight, stride=stride, fm_order="CHW", kernel_order=korder
-        )
+        s1 = pb.Conv2d(n1, n2, weight, stride=stride, kernel_order=korder)
 
         assert s1.num_in == in_channels * shape2num(in_shape)
         assert s1.connectivity.shape == (
diff --git a/tests/synapses/test_transforms.py b/tests/synapses/test_transforms.py
index 9cfc706b..3bfab957 100644
--- a/tests/synapses/test_transforms.py
+++ b/tests/synapses/test_transforms.py
@@ -279,20 +279,27 @@ def _conv1d_golden(
 
                 out[o] += conv_result
 
-        return out
+        if fm_order == "LC":
+            return out.T
+        else:
+            return out
 
     @pytest.mark.parametrize(
-        "in_shape, in_channels, out_channels, kernel_size, stride, padding, fm_order",
+        "in_shape, in_channels, out_channels, kernel_size, stride, padding, fm_order, kdtype",
         # Padding is fixed at (0, 0)
         [
-            ((28,), 16, 8, (3,), (1,), (0,), "CL"),
-            ((28,), 24, 12, (3,), (2,), (0,), "CL"),
-            ((28,), 24, 12, (5,), (2,), (0,), "CL"),
-            ((16,), 8, 16, (3,), (2,), (0,), "CL"),
-            ((28,), 16, 8, (3,), (1,), (0,), "LC"),
-            ((24,), 8, 8, (3,), (2,), (0,), "LC"),
-            ((24,), 8, 16, (7,), (2,), (0,), "LC"),
-            ((32,), 4, 12, (5,), (1,), (0,), "LC"),
+            ((28,), 16, 8, (3,), (1,), (0,), "CL", np.bool_),
+            ((28,), 24, 12, (3,), (2,), (0,), "CL", np.bool_),
+            ((28,), 24, 12, (5,), (2,), (0,), "CL", np.bool_),
+            ((16,), 8, 16, (3,), (2,), (0,), "CL", np.bool_),
+            ((28,), 16, 8, (3,), (1,), (0,), "CL", np.int8),
+            ((28,), 24, 12, (3,), (2,), (0,), "CL", np.int8),
+            ((28,), 24, 12, (5,), (2,), (0,), "CL", np.int8),
+            ((16,), 8, 16, (3,), (2,), (0,), "CL", np.int8),
+            # ((28,), 16, 8, (3,), (1,), (0,), "LC"),
+            # ((24,), 8, 8, (3,), (2,), (0,), "LC"),
+            # ((24,), 8, 16, (7,), (2,), (0,), "LC"),
+            # ((32,), 4, 12, (5,), (1,), (0,), "LC"),
         ],
     )
     def test_Conv1dForward(
@@ -304,14 +311,23 @@ def test_Conv1dForward(
         stride,
         padding,
         fm_order,
+        kdtype,
     ):
-        kernel = np.random.randint(
-            -128, 127, size=(out_channels, in_channels) + kernel_size, dtype=np.int8
-        )
+        if kdtype == np.bool_:
+            kernel = np.random.randint(
+                0, 2, size=(out_channels, in_channels) + kernel_size, dtype=np.bool_
+            )
+        else:
+            kernel = np.random.randint(
+                np.iinfo(kdtype).min,
+                np.iinfo(kdtype).max,
+                size=(out_channels, in_channels) + kernel_size,
+                dtype=kdtype,
+            )
 
         out_shape = ((in_shape[0] + 2 * padding[0] - kernel_size[0]) // stride[0] + 1,)
 
-        f = Conv1dForward(in_shape, out_shape, kernel, stride, padding, fm_order)
+        f = Conv1dForward(in_shape, out_shape, kernel, stride, padding)
 
         if fm_order == "CL":
             fm_shape = (in_channels,) + in_shape
@@ -319,16 +335,17 @@ def test_Conv1dForward(
             fm_shape = in_shape + (in_channels,)
 
         x = np.random.randint(0, 2, size=fm_shape, dtype=np.bool_)
-        xf = x.copy().flatten()
+        xf = x.ravel()
 
-        y = f(xf)
-        expected = self._conv1d_golden(x, out_shape, kernel, stride, padding, fm_order)
+        # The result of __call__ using traditional conv
+        y1 = f(xf)
+        # The result of matmul using the unrolled matrix
+        y2 = xf @ f.connectivity.astype(np.int32)
 
-        # Flattened output
-        y = y.reshape((out_channels,) + out_shape)
+        expected = self._conv1d_golden(x, out_shape, kernel, stride, padding, fm_order)
 
-        assert y.shape == expected.shape
-        assert np.array_equal(y, expected)
+        assert np.array_equal(y1, expected)
+        assert np.array_equal(y2, expected.ravel())
         assert f.connectivity.shape == (
             shape2num((kernel.shape[1],) + in_shape),
             shape2num((kernel.shape[0],) + out_shape),
@@ -348,7 +365,7 @@ def _conv2d_golden(
         if fm_order == "HWC":
             _x = x.transpose(2, 0, 1)
         else:
-            _x = x.copy()
+            _x = x
 
         xcin, ih, iw = _x.shape
 
@@ -381,20 +398,27 @@ def _conv2d_golden(
 
                 out[o] += conv_result
 
-        return out
+        if fm_order == "HWC":
+            return out.transpose(1, 2, 0)
+        else:
+            return out
 
     @pytest.mark.parametrize(
-        "in_shape, in_channels, out_channels, kernel_size, stride, padding, fm_order",
+        "in_shape, in_channels, out_channels, kernel_size, stride, padding, fm_order, kdtype",
         # Padding is fixed at (0, 0)
         [
-            ((28, 28), 16, 8, (3, 3), (1, 1), (0, 0), "CHW"),
-            ((28, 28), 24, 12, (3, 3), (2, 2), (0, 0), "CHW"),
-            ((28, 28), 24, 12, (5, 5), (2, 1), (0, 0), "CHW"),
-            ((16, 16), 8, 16, (3, 3), (2, 2), (0, 0), "CHW"),
-            ((28, 28), 16, 8, (3, 3), (1, 1), (0, 0), "HWC"),
-            ((24, 32), 8, 8, (3, 4), (2, 1), (0, 0), "HWC"),
-            ((24, 24), 8, 16, (7, 7), (2, 2), (0, 0), "HWC"),
-            ((32, 16), 4, 12, (5, 7), (1, 2), (0, 0), "HWC"),
+            ((28, 28), 16, 8, (3, 3), (1, 1), (0, 0), "CHW", np.bool_),
+            ((28, 28), 24, 12, (3, 3), (2, 2), (0, 0), "CHW", np.bool_),
+            ((28, 28), 16, 8, (3, 3), (1, 1), (0, 0), "CHW", np.bool_),
+            ((28, 28), 24, 12, (3, 3), (2, 2), (0, 0), "CHW", np.int8),
+            ((28, 28), 24, 12, (5, 5), (2, 1), (0, 0), "CHW", np.int8),
+            ((16, 16), 8, 16, (3, 3), (2, 2), (0, 0), "CHW", np.int8),
+            # ((28, 28), 16, 8, (3, 3), (1, 1), (0, 0), "HWC", np.bool_),
+            # ((24, 32), 8, 8, (3, 4), (2, 1), (0, 0), "HWC", np.bool_),
+            # ((24, 24), 8, 16, (7, 7), (2, 2), (0, 0), "HWC", np.bool_),
+            # ((32, 16), 4, 12, (5, 7), (1, 2), (0, 0), "HWC", np.int8),
+            # ((24, 24), 8, 16, (7, 7), (2, 2), (0, 0), "HWC", np.int8),
+            # ((32, 16), 4, 12, (5, 7), (1, 2), (0, 0), "HWC", np.int8),
         ],
     )
     def test_Conv2dForward(
@@ -406,17 +430,26 @@ def test_Conv2dForward(
         stride,
         padding,
         fm_order,
+        kdtype,
     ):
-        kernel = np.random.randint(
-            -128, 127, size=(out_channels, in_channels) + kernel_size, dtype=np.int8
-        )
+        if kdtype == np.bool_:
+            kernel = np.random.randint(
+                0, 2, size=(out_channels, in_channels) + kernel_size, dtype=np.bool_
+            )
+        else:
+            kernel = np.random.randint(
+                np.iinfo(kdtype).min,
+                np.iinfo(kdtype).max,
+                size=(out_channels, in_channels) + kernel_size,
+                dtype=kdtype,
+            )
 
         out_shape = (
             (in_shape[0] + 2 * padding[0] - kernel_size[0]) // stride[0] + 1,
             (in_shape[1] + 2 * padding[1] - kernel_size[1]) // stride[1] + 1,
         )
 
-        f = Conv2dForward(in_shape, out_shape, kernel, stride, padding, fm_order)
+        f = Conv2dForward(in_shape, out_shape, kernel, stride, padding)
 
         if fm_order == "CHW":
             fm_shape = (in_channels,) + in_shape
@@ -424,16 +457,17 @@ def test_Conv2dForward(
             fm_shape = in_shape + (in_channels,)
 
         x = np.random.randint(0, 2, size=fm_shape, dtype=np.bool_)
-        xf = x.copy().flatten()
+        xf = x.ravel()
 
-        y = f(xf)
-        expected = self._conv2d_golden(x, out_shape, kernel, stride, padding, fm_order)
+        # The result of __call__ using traditional conv
+        y1 = f(xf)
+        # The result of matmul using the unrolled matrix
+        y2 = xf @ f.connectivity.astype(np.int32)
 
-        # Flattened output
-        y = y.reshape((out_channels,) + out_shape)
+        expected = self._conv2d_golden(x, out_shape, kernel, stride, padding, fm_order)
 
-        assert y.shape == expected.shape
-        assert np.array_equal(y, expected)
+        assert np.array_equal(y1, expected)
+        assert np.array_equal(y2, expected.ravel())
         assert f.connectivity.shape == (
             shape2num((kernel.shape[1],) + in_shape),
             shape2num((kernel.shape[0],) + out_shape),

From 48437272295a5103ff1772aae6f18b9d72beee23 Mon Sep 17 00:00:00 2001
From: KafCoppelia <k740677208@gmail.com>
Date: Wed, 3 Apr 2024 23:10:49 +0800
Subject: [PATCH 58/68] =?UTF-8?q?=E2=9A=A1=EF=B8=8F=20use=20`np.ravel`=20f?=
 =?UTF-8?q?or=20faster=20speed?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

---
 examples/mnist/example1/main.py |  2 +-
 examples/mnist/example2/main.py |  2 +-
 paibox/projection.py            |  2 +-
 paibox/simulator/encoder.py     |  2 +-
 paibox/synapses/base.py         |  4 +--
 paibox/synapses/conv_utils.py   | 55 ++++++++++++++++++---------------
 6 files changed, 36 insertions(+), 31 deletions(-)

diff --git a/examples/mnist/example1/main.py b/examples/mnist/example1/main.py
index e92a6ae2..d5d713e8 100644
--- a/examples/mnist/example1/main.py
+++ b/examples/mnist/example1/main.py
@@ -91,7 +91,7 @@ def getNetParam():
 
     # Network simulation
     raw_data = np.load(Path(__file__).parent.parent / "data" / "mnist_input_data7.npy")
-    input_data = raw_data.flatten()
+    input_data = raw_data.ravel()
 
     # Visualize
     if args.verbose:
diff --git a/examples/mnist/example2/main.py b/examples/mnist/example2/main.py
index 3c985886..0b87a0bb 100644
--- a/examples/mnist/example2/main.py
+++ b/examples/mnist/example2/main.py
@@ -72,7 +72,7 @@ def getNetParam():
 
     # Network simulation
     raw_data = np.load(Path(__file__).parent.parent / "data" / "mnist_input_data7.npy")
-    input_data = raw_data.flatten()
+    input_data = raw_data.ravel()
 
     # Visualize
     if args.verbose:
diff --git a/paibox/projection.py b/paibox/projection.py
index 99b62b38..7d3dc45c 100644
--- a/paibox/projection.py
+++ b/paibox/projection.py
@@ -75,7 +75,7 @@ def update(self, **kwargs) -> SpikeType:
                 raise ShapeError(
                     f"cannot reshape output value from {_spike.shape} to ({self.num_out},)."
                 )
-            self._inner_spike = _spike.flatten().astype(np.bool_)
+            self._inner_spike = _spike.ravel().astype(np.bool_)
         else:
             # should never be reached
             raise TypeError(
diff --git a/paibox/simulator/encoder.py b/paibox/simulator/encoder.py
index ff3f6254..9ee624cb 100644
--- a/paibox/simulator/encoder.py
+++ b/paibox/simulator/encoder.py
@@ -101,7 +101,7 @@ def encode(self, x: np.ndarray) -> None:
         else:
             t_f = ((self.T - 1.0) * (1.0 - x)).round().astype(np.int64)
 
-        indices = t_f.flatten()
+        indices = t_f.ravel()
         spike = np.eye(self.T, dtype=np.bool_)[indices]
         # [*, T] -> [T, *]
         self.spike = np.moveaxis(spike, -1, 0)
diff --git a/paibox/synapses/base.py b/paibox/synapses/base.py
index 0a76007b..0928aa71 100644
--- a/paibox/synapses/base.py
+++ b/paibox/synapses/base.py
@@ -172,7 +172,7 @@ def __init__(
             )
 
         if order == "IOL":
-            _kernel = kernel.transpose(1, 0, 2)
+            _kernel = np.swapaxes(kernel, 0, 1)
         else:
             _kernel = kernel.copy()
 
@@ -222,7 +222,7 @@ def __init__(
             )
 
         if order == "IOHW":
-            _kernel = kernel.transpose(1, 0, 2, 3)
+            _kernel = np.swapaxes(kernel, 0, 1)
         else:
             _kernel = kernel.copy()
 
diff --git a/paibox/synapses/conv_utils.py b/paibox/synapses/conv_utils.py
index 35e69ea3..3e658fda 100644
--- a/paibox/synapses/conv_utils.py
+++ b/paibox/synapses/conv_utils.py
@@ -81,7 +81,10 @@ def _conv1d_unroll(
     stride: Size1Type,
     # padding: Size1Type,
 ) -> WeightType:
-    """Unroll the convolution kernel of 1d convolution into a matrix."""
+    """Unroll the convolution kernel of 1d convolution into a matrix.
+
+    XXX: The case where the input feature map is in 'LC' order is not considered for the time being.
+    """
     cout, cin, kl = kernel.shape
     il = in_shape[0]
     ol = out_shape[0]
@@ -100,7 +103,7 @@ def _conv1d_unroll(
 
         t = zeros_image[:, :, i].T
         for o_ch in range(cout):
-            w_unrolled[:, i + o_ch * ol] = t[o_ch].flatten()
+            w_unrolled[:, i + o_ch * ol] = t[o_ch].ravel()
 
     return w_unrolled
 
@@ -112,7 +115,10 @@ def _conv2d_unroll(
     stride: Size2Type,
     # padding: Size2Type,
 ) -> WeightType:
-    """Unroll the convolution kernel of 2d convolution into a matrix."""
+    """Unroll the convolution kernel of 2d convolution into a matrix.
+
+    XXX: The case where the input feature map is in 'HWC' order is not considered for the time being.
+    """
     cout, cin, kh, kw = kernel.shape
 
     ih, iw = in_shape
@@ -139,13 +145,14 @@ def _conv2d_unroll(
                     i * ow + j,
                 ] = kernel[ch_idx[0], ch_idx[1], :, :]
 
-            t = (
-                zeros_image[:, :, i * ow + j]
-                .reshape(cin * ih, cout, iw)
-                .transpose(1, 0, 2)
+            t = np.swapaxes(
+                zeros_image[:, :, i * ow + j].reshape(cin * ih, cout, iw),
+                0,
+                1,
+                # .transpose(1, 0, 2)
             )
             for o_ch in range(cout):
-                w_unrolled[:, i * ow + j + o_ch * out_size] = t[o_ch].flatten()
+                w_unrolled[:, i * ow + j + o_ch * out_size] = t[o_ch].ravel()
 
     return w_unrolled
 
@@ -167,20 +174,18 @@ def _conv1d_faster(
 
     assert (xl + padding[0] * 2 - kl) // stride[0] + 1 == out_shape[0]
 
-    # kernel: (cout, cin, kl) -> (cin*kl, cout)
-    col_kernel = kernel.transpose(1, 2, 0).reshape(-1, cout)
+    # kernel: (cout, cin, kl) -> (cout, cin*kl)
+    col_kernel = kernel.reshape(cout, -1)
 
     # padded: (cin, xl+2*p[0]-kl) -> (ol, cin*kl)
     col_fm = _1d_im2col(x_padded, out_shape[0], kl, stride)
 
     # out = np.zeros((cout,) + out_shape, dtype=np.int64)
-    # (ol, cin*kl) * (cin*kl, cout) = (ol, cout)
-    out = col_fm @ col_kernel  # + self.bias
-
-    # (ol, cout) -> (ol, cout) -> (cout, ol)
-    out = out.reshape(out_shape + (cout,)).T
+    # (ol, cin*kl) * (cout, cin*kl)^T = (ol, cout)
+    out = col_fm @ col_kernel.T  # + self.bias
 
-    return out.astype(np.int32)
+    # (ol, cout) -> (cout, ol)
+    return out.astype(np.int32).T
 
 
 def _conv2d_faster(
@@ -205,20 +210,20 @@ def _conv2d_faster(
     assert (xh + padding[0] * 2 - kh) // stride[0] + 1 == out_shape[0]
     assert (xw + padding[1] * 2 - kw) // stride[1] + 1 == out_shape[1]
 
-    # kernel: (cout, cin, kh, kw) -> (cin*kh*kw, cout)
-    col_kernel = kernel.transpose(1, 2, 3, 0).reshape(-1, cout)
+    # kernel: (cout, cin, kh, kw) -> (cout, cin*kh*kw)
+    col_kernel = kernel.reshape(cout, -1)
 
     # padded: (cin, xh+2*p[0]-kh, xw+2*p[1]-kw) -> (oh*ow, cin*kh*kw)
     col_fm = _2d_im2col(x_padded, out_shape[0], out_shape[1], kh, kw, stride)
 
     # out = np.zeros((cout,) + out_shape, dtype=np.int64)
-    # (oh*ow, cin*kh*kw) * (cin*kh*kw, cout) = (oh*ow, cout)
-    out = col_fm @ col_kernel  # + self.bias
+    # (oh*ow, cin*kh*kw) * (cout, cin*kh*kw)^T = (oh*ow, cout)
+    out = col_fm @ col_kernel.T  # + self.bias
 
-    # (oh*ow, cout) -> (oh, ow, cout) -> (cout, oh, ow)
-    out = out.reshape(out_shape + (cout,)).transpose(2, 0, 1)
+    # (oh*ow, cout) -> (cout, oh*ow) -> (cout, oh, ow)
+    out = out.astype(np.int32).T.reshape((cout,) + out_shape)
 
-    return out.astype(np.int32)
+    return out
 
 
 def _1d_im2col(
@@ -230,7 +235,7 @@ def _1d_im2col(
 
     idx = 0
     for i in range(0, pl - kl + 1, stride[0]):
-        cols[idx] = x_padded[:, i : i + kl].reshape(-1)
+        cols[idx] = x_padded[:, i : i + kl].ravel()
         idx += 1
 
     return cols
@@ -246,7 +251,7 @@ def _2d_im2col(
     idx = 0
     for i in range(0, ph - kh + 1, stride[0]):
         for j in range(0, pw - kw + 1, stride[1]):
-            cols[idx] = x_padded[:, i : i + kh, j : j + kw].reshape(-1)
+            cols[idx] = x_padded[:, i : i + kh, j : j + kw].ravel()
             idx += 1
 
     return cols

From 95327ed11eef581d19a64309c2e589ae630524dd Mon Sep 17 00:00:00 2001
From: KafCoppelia <k740677208@gmail.com>
Date: Wed, 3 Apr 2024 23:11:46 +0800
Subject: [PATCH 59/68] =?UTF-8?q?=F0=9F=93=9D=20updated=20docs?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

---
 CHANGELOG.md            |  2 +-
 docs/Guide-of-PAIBox.md | 15 +++++++--------
 2 files changed, 8 insertions(+), 9 deletions(-)

diff --git a/CHANGELOG.md b/CHANGELOG.md
index e8b40e7b..000cbf94 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -27,7 +27,7 @@
 
 - 支持全展开1D卷积算子构建与部署（`padding` 不支持）
 
-## v1.0.0a8
+## v1.0.0b1
 
 - 提高 `numpy` 依赖版本至 `^1.24.0`
 - 修复神经元输入累加错误
diff --git a/docs/Guide-of-PAIBox.md b/docs/Guide-of-PAIBox.md
index 93780276..d4db1a4e 100644
--- a/docs/Guide-of-PAIBox.md
+++ b/docs/Guide-of-PAIBox.md
@@ -227,7 +227,6 @@ s1= pb.FullConn(source=n1, dest=n2, weights=weight1, conn_type=pb.SynConnType.Al
   ```
 
   其权重以标量的形式储存。
-
 - 数组：尺寸要求为 `(N2,)`，可以自定义每组对应神经元之间的连接权重。如下例所示，设置 `weights` 为 `[1, 2, 3, 4, 5]`，
 
   ```python
@@ -256,36 +255,36 @@ s1= pb.FullConn(source=n1, dest=n2, weights=weight1, conn_type=pb.SynConnType.Al
 
 #### 1D卷积
 
-全展开形式1D卷积为全连接突触的一种特殊表达。对于卷积形式的突触，需**严格指定**前后神经元的尺寸、神经元维度顺序、卷积核权重、卷积核维度顺序与步长。
+全展开形式1D卷积为全连接突触的一种特殊表达。对于卷积形式的突触，需**严格指定**前后神经元的维度、卷积核权重、卷积核维度顺序与步长。
 
 - `kernel`：卷积核权重。
 - `stride`：步长，标量。
-- `fm_order` 指定神经元维度顺序为 `CL` 或 `LC` 排列。
 - `kernel_order`：指定卷积核维度顺序为 `OIL` 或 `IOL` 排列。
+- 神经元维度顺序仅支持 `CL`。
 
 ```python
 n1 = pb.IF(shape=(8, 28), threshold=1)      # Input feature map: (8, 28)
 n2 = pb.IF(shape=(16, 26), threshold=1)     # Output feature map: (16, 26)
 kernel = np.random.randint(-128, 128, size=(16, 8, 3), dtype=np.int8) # OIl
 
-conv2d = pb.Conv1d(n1, n2, kernel=kernel, stride=1, fm_order="CL", kernel_order="OIL", name="conv1d_1")
+conv2d = pb.Conv1d(n1, n2, kernel=kernel, stride=1, kernel_order="OIL", name="conv1d_1")
 ```
 
 #### 2D卷积
 
-全展开形式2D卷积为全连接突触的一种特殊表达。对于卷积形式的突触，需**严格指定**前后神经元的尺寸、神经元维度顺序、卷积核权重、卷积核维度顺序与步长。
+全展开形式2D卷积为全连接突触的一种特殊表达。对于卷积形式的突触，需**严格指定**前后神经元的维度、神经元维度顺序、卷积核权重、卷积核维度顺序与步长。
 
 - `kernel`：卷积核权重。
 - `stride`：步长，可以为标量或元组。当为标量时，对应为 `(x, x)`；当为元组时，则对应为 `(x, y)`。
-- `fm_order` 指定神经元维度顺序为 `CHW` 或 `HWC` 排列。
 - `kernel_order`：指定卷积核维度顺序为 `OIHW` 或 `IOHW` 排列。
+- 神经元维度顺序仅支持 `CHW`。
 
 ```python
 n1 = pb.IF(shape=(8, 28, 28), threshold=1)      # Input feature map: (8, 28, 28)
 n2 = pb.IF(shape=(16, 26, 26), threshold=1)     # Output feature map: (16, 26, 26)
 kernel = np.random.randint(-128, 128, size=(16, 8, 3, 3), dtype=np.int8) # OIHW
 
-conv2d = pb.Conv2d(n1, n2, kernel=kernel, stride=1, fm_order="CHW", kernel_order="OIHW", name="conv2d_1")
+conv2d = pb.Conv2d(n1, n2, kernel=kernel, stride=1, kernel_order="OIHW", name="conv2d_1")
 ```
 
 ⚠️ `padding` 不支持，默认为0。
@@ -697,7 +696,7 @@ sim.reset()
 mapper = pb.Mapper()
 mapper.build(fcnet)
 graph_info = mapper.compile(weight_bit_optimization=True, grouping_optim_target="both")
-mapper.export(write_to_file=True, fp="./debug/", format="npy", split_by_coordinate=False, local_chip_addr=(0, 0), export_core_params=False)
+mapper.export(write_to_file=True, fp="./debug/", format="bin", split_by_coordinate=False, local_chip_addr=(0, 0), export_core_params=False)
 
 # Clear all the results
 mapper.clear()

From d967fa60c8360b8c1a2e145a639240d081980abd Mon Sep 17 00:00:00 2001
From: KafCoppelia <k740677208@gmail.com>
Date: Mon, 8 Apr 2024 15:33:41 +0800
Subject: [PATCH 60/68] =?UTF-8?q?=E2=9A=A1=EF=B8=8F=20Wasted=20cores=20wil?=
 =?UTF-8?q?l=20be=20configured=20to=20a=20reset=20state?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

---
 paibox/backend/conf_template.py |  85 ++++++++++++++++-------
 paibox/backend/mapper.py        | 116 +++++++++++++++++---------------
 paibox/backend/placement.py     |  90 +++++++++++++++++++------
 paibox/backend/routing.py       |  45 +++++++++----
 4 files changed, 223 insertions(+), 113 deletions(-)

diff --git a/paibox/backend/conf_template.py b/paibox/backend/conf_template.py
index 203bb735..0000ebca 100644
--- a/paibox/backend/conf_template.py
+++ b/paibox/backend/conf_template.py
@@ -2,7 +2,7 @@
 from dataclasses import dataclass
 from enum import Enum
 from pathlib import Path
-from typing import Any, Dict, List, Literal, NamedTuple, TypedDict
+from typing import Any, ClassVar, Dict, List, Literal, NamedTuple, TypedDict
 
 import numpy as np
 from numpy.typing import NDArray
@@ -10,6 +10,7 @@
     LCN_EX,
     AxonCoord,
     Coord,
+    HwConfig,
     InputWidthFormat,
     MaxPoolingEnable,
     NeuronAttrs,
@@ -254,6 +255,22 @@ def __json__(self) -> Dict[str, Any]:
         return dict_
 
 
+class EmptyCorePlacementConfig(CorePlacementConfig):
+    _default_seed: ClassVar[int] = 0
+    _default_zero_wram: ClassVar[NDArray[np.uint64]] = np.zeros(
+        (HwConfig.ADDR_RAM_MAX, 18), dtype=np.uint64
+    )
+
+    @classmethod
+    def encapsulate(cls, core_config: CoreConfig):
+        return cls(
+            cls._default_seed,
+            cls._default_zero_wram,
+            ParamsReg.model_validate(core_config._asdict(), strict=True),
+            {},
+        )
+
+
 InputNodeInfo: TypeAlias = Dict[NodeName, NeuronDest]
 OutputDestInfo: TypeAlias = Dict[NodeName, Dict[int, NeuronDestInfo]]
 CorePlacementInfo: TypeAlias = Dict[Coord, CorePlacementConfig]
@@ -271,8 +288,8 @@ class GraphInfo(TypedDict):
     inherent_timestep: int
     n_core_required: int
     """The actual used cores."""
-    # n_core_occupied: int
-    # """The occupied cores, including used & wasted."""
+    n_core_occupied: int
+    """The occupied cores, including used & wasted."""
     extras: NotRequired[Dict[str, Any]]
 
 
@@ -292,7 +309,7 @@ def gen_config_frames_by_coreconf(
         - write_to_file: whether to write frames to file.
         - fp: If `write_to_file` is `True`, specify the path.
         - split_by_coord: whether to split the generated frames file by the core coordinates.
-        - format: `txt`, `bin`, or `npy`. `bin` & `npy` are recommended.
+        - format: `txt`, `bin`, or `npy`.
     """
 
     def _write_to_f(name: str, array: FrameArrayType) -> None:
@@ -327,7 +344,7 @@ def _write_to_f(name: str, array: FrameArrayType) -> None:
             v.params_reg,
         )
 
-        # 3. Iterate all the neuron segments in the function inside
+        # 3. Iterate all the neuron segments inside the physical core.
         config_frame_type3 = []
         for neu_conf in v.neuron_configs.values():
             config_frame_type3.append(
@@ -344,20 +361,26 @@ def _write_to_f(name: str, array: FrameArrayType) -> None:
                 )
             )
 
-        frame3 = np.concatenate(
-            [f.value for f in config_frame_type3], dtype=FRAME_DTYPE
-        )
+        if config_frame_type3:
+            frame3 = np.concatenate(
+                [f.value for f in config_frame_type3], dtype=FRAME_DTYPE, casting="no"
+            )
+        else:
+            frame3 = np.asarray([], dtype=FRAME_DTYPE)
 
         # 4. Only one config frame type IV for each physical core.
         n_addr_write = v.params_reg.num_dendrite  # The number of address to write
-        config_frame_type4 = OfflineFrameGen.gen_config_frame4(
-            target_chip_coord,
-            core_coord,
-            _default_rid,
-            0,
-            18 * n_addr_write,
-            v.weight_ram[:n_addr_write],
-        )
+        if n_addr_write > 0:
+            config_frame_type4 = OfflineFrameGen.gen_config_frame4(
+                target_chip_coord,
+                core_coord,
+                _default_rid,
+                0,
+                18 * n_addr_write,
+                v.weight_ram[:n_addr_write],
+            )
+        else:
+            config_frame_type4 = None
 
         _debug_dict[core_coord] = {
             "config1": config_frame_type1,
@@ -366,15 +389,23 @@ def _write_to_f(name: str, array: FrameArrayType) -> None:
             "config4": config_frame_type4,
         }
 
-        frame_arrays_on_core[core_coord] = np.concatenate(
-            [
-                config_frame_type1.value,
-                config_frame_type2.value,
-                frame3,
-                config_frame_type4.value,
-            ],
-            dtype=FRAME_DTYPE,
-        )
+        if config_frame_type4:
+            frame_arrays_on_core[core_coord] = np.concatenate(
+                [
+                    config_frame_type1.value,
+                    config_frame_type2.value,
+                    frame3,
+                    config_frame_type4.value,
+                ],
+                dtype=FRAME_DTYPE,
+                casting="no",
+            )
+        else:
+            frame_arrays_on_core[core_coord] = np.concatenate(
+                [config_frame_type1.value, config_frame_type2.value, frame3],
+                dtype=FRAME_DTYPE,
+                casting="no",
+            )
 
     if write_to_file:
         if split_by_coord:
@@ -382,7 +413,9 @@ def _write_to_f(name: str, array: FrameArrayType) -> None:
                 addr = core_coord.address
                 _write_to_f(f"config_core{addr}", f)
         else:
-            _f = np.concatenate(list(frame_arrays_on_core.values()), dtype=FRAME_DTYPE)
+            _f = np.concatenate(
+                list(frame_arrays_on_core.values()), dtype=FRAME_DTYPE, casting="no"
+            )
             _write_to_f(f"config_cores_all", _f)
 
     return frame_arrays_on_core
diff --git a/paibox/backend/mapper.py b/paibox/backend/mapper.py
index 7fa5ac95..d2cc1cd0 100644
--- a/paibox/backend/mapper.py
+++ b/paibox/backend/mapper.py
@@ -216,7 +216,7 @@ def coord_assign(self) -> None:
                 optim_target=_BACKEND_CONTEXT.cflags["grouping_optim_target"]
             )
 
-        # Calculate the consumption of physical cores required.
+        # Calculate the consumption of required physical cores.
         if (
             n_core_required := sum(cb.n_core_required for cb in self.core_blocks)
         ) > HwConfig.N_CORE_OFFLINE:
@@ -238,12 +238,20 @@ def coord_assign(self) -> None:
 
         self.routing_groups = routing_groups
 
+        # Calculate the consumption of occupied physical cores.
+        if (
+            n_core_occupied := sum(rg.get_n_core_occupied() for rg in routing_groups)
+        ) > HwConfig.N_CORE_OFFLINE:
+            raise ResourceError(
+                f"the number of occupied cores is out of range {HwConfig.N_CORE_OFFLINE} ({n_core_occupied})."
+            )
+
+        self.n_core_occupied = n_core_occupied
+
     def core_allocation(self) -> None:
-        """Allocate the core blocks to the physical cores. \
-            The order of `core_plms` is the same as `core_blocks`.
-        """
-        for cb in self.core_blocks:
-            cb.core_plm_alloc()
+        """Allocate the routing groups to core placements level."""
+        for rg in self.routing_groups:
+            rg.core_block_alloc()
 
     def config_export(self) -> GraphInfo:
         """Export parameters of cores & neurons inside.
@@ -262,7 +270,7 @@ def config_export(self) -> GraphInfo:
             members=self.core_plm_config,  # The configuration of physical cores is in `core_plm_config`
             inherent_timestep=self.graph.inherent_timestep,
             n_core_required=self.n_core_required,
-            # n_core_occupied=self.n_core_occupied,
+            n_core_occupied=self.n_core_occupied,
             extras={"name": self.graph.graph_name_repr},
         )
 
@@ -329,12 +337,7 @@ def _inpproj_config_export(self) -> InputNodeInfo:
         return input_nodes_info
 
     def _member_cb_and_onode_config_export(self) -> OutputDestInfo:
-        """Export the configuration of member core blocks & output destinations.
-
-        Description:
-            Traverse core placements in core blocks, find the following core    \
-            blocks where the axons at. Get the coordinate of the core placement \
-            & coordinates of axons(for broadcasting).
+        """Export configuration & output destinations inormation for core blocks.
 
         Json exchange file format for output nodes:
         {
@@ -358,42 +361,48 @@ def _member_cb_and_onode_config_export(self) -> OutputDestInfo:
         # Shallow copy
         ocoord = copy(_BACKEND_CONTEXT["output_core_addr_start"])
 
-        for member_cb in self.core_blocks:
-            self.core_params.update(
-                CoreBlock.export_core_plm_config(member_cb)
-            )  # compatible for py3.8
-
-            output_axon_offset = 0
-            for core_plm in member_cb.core_placements.values():
-                for neu_seg in core_plm.neu_segs_of_cplm:
-                    # Find the axon destinations
-                    dest_cb = [
-                        cb for cb in self.core_blocks if neu_seg.parent in cb.source
-                    ]
-
-                    # FIXME It is necessary to ensure that when there are both output nodes
-                    # & member nodes in the same `CoreBlock`, they need to be allocated on
-                    # different physical cores, otherwise routing problem will occur.
-                    if dest_cb:  # `neu_seg` is memeber neurons
-                        # Should not happen
-                        assert _cb_routable(self.routing_groups, dest_cb)
-                        core_plm.export_neu_config(neu_seg, dest_cb)
-                    else:
-                        # `neu_seg` is output neurons. Every neuron segment is a output node.
-                        # Update the offset of axon
-                        output_axon_offset = core_plm.export_neu_config(
-                            neu_seg,
-                            output_core_coord=ocoord,
-                            axon_addr_offset=output_axon_offset,
-                        )
-                        output_dest_info[neu_seg.parent.name][
-                            core_plm.coord.address
-                        ] = core_plm.neu_configs[neu_seg.parent].neuron_dest_info
-
-                        # Coord.x += 1 for the destination of the next output node
-                        ocoord += CoordOffset(1, 0)
-
-                self.core_plm_config[core_plm.coord] = core_plm.export_core_plm_config()
+        for rg in self.routing_groups:
+            for member_cb in rg:
+                self.core_params.update(
+                    CoreBlock.export_core_plm_config(member_cb)
+                )  # compatible for py3.8
+
+                output_axon_offset = 0
+                for core_plm in member_cb.core_placements.values():
+                    for neu_seg in core_plm.neu_segs_of_cplm:
+                        # Find the axon destinations
+                        dest_cb = [
+                            cb for cb in self.core_blocks if neu_seg.parent in cb.source
+                        ]
+                        # TODO When obtaining core blocks, we should determine which core block
+                        # is used as a pure member core block, which one is used as both a member
+                        # & an output core block. This constrains the grouping of neurons.
+                        if dest_cb:
+                            # `neu_seg` is member neurons
+                            # Should not happen
+                            assert _cb_routable(self.routing_groups, dest_cb)
+                            core_plm.export_neu_config(neu_seg, dest_cb)
+                        else:
+                            # `neu_seg` is output neurons. Every neuron segment is a output node.
+                            # Update the offset of axon
+                            output_axon_offset = core_plm.export_neu_config(
+                                neu_seg,
+                                output_core_coord=ocoord,
+                                axon_addr_offset=output_axon_offset,
+                            )
+                            output_dest_info[neu_seg.parent.name][
+                                core_plm.coord.address
+                            ] = core_plm.neu_configs[neu_seg.parent].neuron_dest_info
+
+                            # Coord.x += 1 for the destination of the next output node
+                            ocoord += CoordOffset(1, 0)
+
+                    self.core_plm_config[core_plm.coord] = (
+                        core_plm.export_core_plm_config()
+                    )
+
+            # Generate default configurations for wasted core placements
+            self.core_plm_config.update(rg.get_wasted_cplm_config())
 
         return output_dest_info
 
@@ -412,11 +421,10 @@ def export(
         Args:
             - write_to_file: whether to write frames into file.
             - fp: If `write_to_file` is `True`, specify the output path.
-            - format: `txt`, `bin`, or `npy`.`bin` & `npy` are recommended.
-            - split_by_coordinate: whether to split the generated frames file by the    \
-                core coordinates.
-            - local_chip_addr: the address of the local chip. If not specified, the     \
-                default value in `_BACKEND_CONTEXT` will be used.
+            - format: `txt`, `bin`, or `npy`. `bin` is recommended.
+            - split_by_coordinate: whether to split the generated frames file by the core coordinates.
+            - local_chip_addr: the address of the local chip. If not specified, the default value in    \
+                `_BACKEND_CONTEXT` will be used.
             - export_core_params: whether to export the parameters of occupied cores.
 
         Return: a dictionary of configurations.
diff --git a/paibox/backend/placement.py b/paibox/backend/placement.py
index 7c70a5cd..d048ce88 100644
--- a/paibox/backend/placement.py
+++ b/paibox/backend/placement.py
@@ -31,7 +31,12 @@
 from paibox.types import WeightType
 from paibox.utils import check_attr_same, count_unique_elem
 
-from .conf_template import CoreConfig, CorePlacementConfig, NeuronConfig
+from .conf_template import (
+    EmptyCorePlacementConfig,
+    CoreConfig,
+    CorePlacementConfig,
+    NeuronConfig,
+)
 from .context import _BACKEND_CONTEXT
 from .graphs_types import DestNodeType, SourceNodeType
 from .segment_utils import (
@@ -116,9 +121,7 @@ def core_plm_alloc(self) -> None:
 
         for i, coord in enumerate(self.core_coords):
             # assert self.get_raw_weight_of_coord(i)[0].shape[0] == self.n_axon
-            self.core_placements[coord] = CorePlacement.build(
-                self, i, self.get_raw_weight_of_coord(i)
-            )
+            self.core_placements[coord] = CorePlacement.build(self, i)
 
     def _get_syn_of(self, src: SourceNodeType, dest: DestNodeType) -> Optional[SynSys]:
         for syn in self.obj:
@@ -277,8 +280,8 @@ def n_neuron(self) -> int:
         return sum(d.num_in for d in self.dest)
 
     @property
-    def unroll_factor(self) -> List[int]:
-        return [d.unroll_factor for d in self.dest]
+    def unrolling_factor(self) -> List[int]:
+        return [d.unrolling_factor for d in self.dest]
 
     @property
     def n_neuron_of_plm(self) -> List[int]:
@@ -388,7 +391,6 @@ def __init__(
         parent: CoreBlock,
         routing_coord: Coord,
         n_neuron: int,
-        *,
         raw_weights: List[WeightType],
         neu_segs_of_cplm: NeuSegOfCorePlm,
         name: Optional[str] = None,
@@ -416,18 +418,13 @@ def __init__(
         self.neu_configs: Dict[NeuDyn, NeuronConfig] = dict()
 
     @classmethod
-    def build(cls, parent: CoreBlock, idx: int, raw_weights: List[WeightType]):
+    def build(cls, parent: CoreBlock, idx: int):
         coord = parent.core_coords[idx]
         n_neuron = parent.n_neuron_of_plm[idx]
         neu_segs_of_cplm = parent.neuron_segs_of_cb[idx]
+        raw_weights = parent.get_raw_weight_of_coord(idx)
 
-        return cls(
-            parent,
-            coord,
-            n_neuron,
-            raw_weights=raw_weights,
-            neu_segs_of_cplm=neu_segs_of_cplm,
-        )
+        return cls(parent, coord, n_neuron, raw_weights, neu_segs_of_cplm)
 
     def _fold_raw_weights(self, raw_weights: List[WeightType]) -> WeightType:
         """Fold the weights into LCN-sized blocks."""
@@ -472,7 +469,7 @@ def _weight_ram_mapping(self) -> WeightRamType:
         if self.n_weight_bits == 1:
             w_unpacked[:row, :col] = self._weights_folded
         else:
-            # [N*M] -> [M*N*1]
+            # (N, M) -> (M*N, 1)
             w_folded_3d = np.expand_dims(self._weights_folded.T, axis=2).astype(
                 np.uint8
             )
@@ -490,19 +487,20 @@ def _weight_ram_mapping(self) -> WeightRamType:
                     :row, self.n_weight_bits * i : self.n_weight_bits * (i + 1)
                 ] = unpacked
 
-        assert np.max(w_unpacked, axis=None) <= 1
-        assert np.min(w_unpacked, axis=None) >= 0
+        assert np.max(w_unpacked, axis=None) <= np.uint8(1)
+        assert np.min(w_unpacked, axis=None) >= np.uint8(0)
 
         # Convert the unpacked weights into a mapping format,
         # corresponding to the RAM address, each address contains 18 uint64.
-        # [512 * 1152] -> [(512*18) * 64](uint8). Reshape to 64 columns to avoid contiguous problem.
+        # (1152, 512) -> (512, 1152) -> (512*18, 64)(uint8).
+        # Reshape to 64 columns to avoid contiguous problem.
         w_unpacked_T_rehaped = w_unpacked.T.reshape(-1, 64)
 
-        # [(512*18) * 64](uint8) -> [(512*18) * 8](uint8)
+        # (512*18, 64)(uint8) -> (512*18, 8)(uint8)
         w_packed_u8 = np.packbits(
             w_unpacked_T_rehaped, axis=1, bitorder=HwConfig.WEIGHT_BITORDER
         )
-        # [(512*18) * 8](uint8) -> [(512*18) * 1](uint64) -> [512 * 18](uint64)
+        # (512*18, 8)(uint8) -> (512*18, 1)(uint64) -> (512, 18)(uint64)
         w_packed_u64 = w_packed_u8.view(np.uint64).reshape(-1, 18)
         w_packed_u64.setflags(write=False)
 
@@ -715,6 +713,56 @@ def __len__(self) -> int:
         return self.n_core_required
 
 
+class EmptyCorePlacement(CoreAbstract):
+    """Empty core placement."""
+    _default_wp: ClassVar[WP] = WP.WEIGHT_WIDTH_1BIT
+    _default_lcn_ex: ClassVar[LCN_EX] = LCN_EX.LCN_1X
+    _default_n_dendrite: ClassVar[int] = 0
+    _default_tws: ClassVar[int] = 0
+    _default_twe: ClassVar[int] = 0
+    _default_target_lcn: ClassVar[LCN_EX] = LCN_EX.LCN_1X
+
+    def __init__(self, coord: Coord, name: Optional[str] = None) -> None:
+        super().__init__(name)
+        self.coord = coord
+
+    def export_param_config(self) -> CoreConfig:
+        _mode_params = CoreModeDict[CoreMode.MODE_SNN]
+        # fmt: off
+        cb_config = CoreConfig(
+            self.name,                          # name of the core
+            self._default_wp,                   # weight_precision
+            self._default_lcn_ex,               # lcn_extension
+            _mode_params[0],                    # input_width_format
+            _mode_params[1],                    # spike_width_format
+            self._default_n_dendrite,           # num_dendrite
+            MaxPoolingEnable.DISABLE,           # max_pooling_en
+            self._default_tws,                  # tick_wait_start
+            self._default_twe,                  # tick_wait_end
+            _mode_params[2],                    # snn_mode_en
+            self._default_target_lcn,           # target_lcn
+            _BACKEND_CONTEXT.test_chip_addr,    # test_chip_addr
+        )
+        # fmt: on
+        return cb_config
+
+    def export_core_plm_config(self) -> EmptyCorePlacementConfig:
+        core_param = self.export_param_config()
+        return EmptyCorePlacementConfig.encapsulate(core_param)
+
+    @classmethod
+    def build(cls, coord: Coord):
+        return cls(coord)
+
+    @property
+    def n_core_required(self):
+        return 1
+
+    @property
+    def shape(self) -> Tuple[int, int]:
+        return (0, 0)
+
+
 def max_lcn_of_cb(cb: List[CoreBlock]) -> LCN_EX:
     """Find the max LCN extenion of previous grouped synapses"""
     return max(cb, key=lambda cb: cb.lcn_ex).lcn_ex
diff --git a/paibox/backend/routing.py b/paibox/backend/routing.py
index 763704c2..09da91da 100644
--- a/paibox/backend/routing.py
+++ b/paibox/backend/routing.py
@@ -8,8 +8,8 @@
 from paicorelib.routing_defs import get_routing_consumption
 
 from paibox.exceptions import NotSupportedError
-
-from .placement import CoreBlock, CorePlacement
+from .conf_template import CorePlacementInfo
+from .placement import EmptyCorePlacement, CoreBlock, CorePlacement
 
 __all__ = ["RoutingGroup", "RoutingRoot"]
 
@@ -417,12 +417,13 @@ class RoutingGroup(List[CoreBlock]):
     """
 
     def __init__(self, *cb: CoreBlock) -> None:
-        self.cb = list(cb)
-
+        self.core_blocks = list(cb)
         self.assigned_coords: List[Coord] = []
-        """Assigned core coordinates for the routing group."""
+        """Assigned core coordinates in the routing group"""
         self.wasted_coords: List[Coord] = []
-        """Wasted core coordinates for the routing group."""
+        """Wasted core coordinates in routing group"""
+        self.wasted_core_plm: Dict[Coord, EmptyCorePlacement] = {}
+        """Wasted core placements"""
 
     def assign(self, assigned: List[Coord], wasted: List[Coord]) -> None:
         self.assigned_coords = assigned
@@ -435,20 +436,40 @@ def assign(self, assigned: List[Coord], wasted: List[Coord]) -> None:
             cb.core_coords = assigned[cur_i : cur_i + n]
             cur_i += n
 
+    def core_block_alloc(self) -> None:
+        for cb in self:
+            cb.core_plm_alloc()
+
+        # Allocate blank core placements for the wasted coordinates.
+        for coord in self.wasted_coords:
+            self.wasted_core_plm[coord] = EmptyCorePlacement.build(coord)
+
+    def get_wasted_cplm_config(self) -> CorePlacementInfo:
+        return {
+            coord: core_plm.export_core_plm_config()
+            for coord, core_plm in self.wasted_core_plm.items()
+        }
+
+    def get_n_core_occupied(self) -> int:
+        """Get the #N of cores occupied by the routing group."""
+        return len(self.assigned_coords) + len(self.wasted_coords)
+
     def __getitem__(self, idx: int) -> CoreBlock:
-        if idx >= len(self.cb) or idx < 0:
-            raise IndexError(f"index out of range [0, {len(self.cb)}) ({idx}).")
+        if idx >= len(self.core_blocks) or idx < 0:
+            raise IndexError(
+                f"index out of range [0, {len(self.core_blocks)}), ({idx})."
+            )
 
-        return self.cb[idx]
+        return self.core_blocks[idx]
 
     def __len__(self) -> int:
-        return len(self.cb)
+        return len(self.core_blocks)
 
     def __iter__(self) -> Iterator[CoreBlock]:
-        return self.cb.__iter__()
+        return self.core_blocks.__iter__()
 
     def __contains__(self, key: CoreBlock) -> bool:
-        return key in self.cb
+        return key in self.core_blocks
 
     @property
     def n_core_required(self) -> int:

From 6d69f80459bcc79b8575dbdea4306105bc1b8d24 Mon Sep 17 00:00:00 2001
From: KafCoppelia <k740677208@gmail.com>
Date: Mon, 8 Apr 2024 15:35:09 +0800
Subject: [PATCH 61/68] =?UTF-8?q?=E2=9C=85=20added=20tests=20for=20exporti?=
 =?UTF-8?q?ng=20config=20frames=20for=20wasted=20core=20placements?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

---
 tests/backend/conftest.py           | 54 +++++++++++++++++++++++++----
 tests/backend/test_conf_template.py |  8 +++++
 tests/backend/test_mapper.py        |  9 +++++
 tests/backend/test_placement.py     | 10 +++---
 tests/backend/test_segment_utils.py | 10 ++++--
 5 files changed, 78 insertions(+), 13 deletions(-)

diff --git a/tests/backend/conftest.py b/tests/backend/conftest.py
index 9a0808f6..aec0d57e 100644
--- a/tests/backend/conftest.py
+++ b/tests/backend/conftest.py
@@ -22,8 +22,14 @@
 from paicorelib import WeightPrecision as WP
 
 import paibox as pb
-from paibox.backend.conf_template import CoreConfig, CorePlacementConfig, NeuronConfig
+from paibox.backend.conf_template import (
+    EmptyCorePlacementConfig,
+    CoreConfig,
+    CorePlacementConfig,
+    NeuronConfig,
+)
 from paibox.backend.routing import RoutingCluster
+from paibox.exceptions import ResourceError
 from paibox.naming import clear_name_cache
 from paibox.node import NodeList
 from tests.conftest import ParametrizedTestData
@@ -40,6 +46,9 @@ def ensure_dump_dir():
             f.unlink()
 
     yield p
+    # Clean up
+    # for f in p.iterdir():
+    #     f.unlink()
 
 
 @pytest.fixture
@@ -170,12 +179,19 @@ class NetForTest4(pb.Network):
                   N1 -> S3 -> N3 -> S5 -> N4
     """
 
-    def __init__(self):
+    def __init__(self, large_scale: bool = False):
         super().__init__()
+
         self.inp1 = pb.InputProj(input=1, shape_out=(400,), name="inp1")
         self.n1 = pb.TonicSpiking(800, 3, name="n1", tick_wait_start=1)
-        self.n2 = pb.TonicSpiking(400, 4, name="n2", tick_wait_start=2)
-        self.n3 = pb.TonicSpiking(400, 4, name="n3", tick_wait_start=2)
+
+        if large_scale:
+            self.n2 = pb.TonicSpiking(1500, 4, name="n2", tick_wait_start=2)
+            self.n3 = pb.TonicSpiking(1500, 4, name="n3", tick_wait_start=2)
+        else:
+            self.n2 = pb.TonicSpiking(400, 4, name="n2", tick_wait_start=2)
+            self.n3 = pb.TonicSpiking(400, 4, name="n3", tick_wait_start=2)
+
         self.n4 = pb.TonicSpiking(400, 4, name="n4", tick_wait_start=3)
         self.s1 = pb.FullConn(
             self.inp1, self.n1, conn_type=pb.SynConnType.All2All, name="s1"
@@ -187,10 +203,10 @@ def __init__(self):
             self.n1, self.n3, conn_type=pb.SynConnType.All2All, name="s3"
         )
         self.s4 = pb.FullConn(
-            self.n2, self.n4, conn_type=pb.SynConnType.One2One, name="s4"
+            self.n2, self.n4, conn_type=pb.SynConnType.All2All, name="s4"
         )
         self.s5 = pb.FullConn(
-            self.n3, self.n4, conn_type=pb.SynConnType.One2One, name="s5"
+            self.n3, self.n4, conn_type=pb.SynConnType.All2All, name="s5"
         )
 
 
@@ -515,6 +531,10 @@ def build_example_net4():
     return NetForTest4()
 
 
+@pytest.fixture(scope="class")
+def build_example_net4_large_scale():
+    return NetForTest4(large_scale=True)
+
 @pytest.fixture(scope="class")
 def build_multi_onodes_net():
     return Network_with_multi_onodes()
@@ -626,6 +646,11 @@ def MockCorePlacementConfig(MockCoreConfigDict, MockNeuronConfig):
     return cpc
 
 
+@pytest.fixture
+def MockEmptyCorePlacementConfig(MockCoreConfigDict):
+    return EmptyCorePlacementConfig.encapsulate(MockCoreConfigDict)
+
+
 def packbits_ref(bits: np.ndarray, count: int) -> int:
     """Pack unsigned bits into a signed integer.
 
@@ -659,6 +684,23 @@ def packbits1():
     return partial(packbits_ref, count=1)
 
 
+
+def n_axon2lcn_ex_proto(n_axon, n_fanin_max) -> LCN_EX:
+    """Convert #N(of axons) to `LCN_EX` & check.
+
+    NOTE: LCN_EX = log2[ceil(#N/fan-in per dendrite)], where `LCN_1X` = 0.
+    """
+    if n_axon < 1:
+        raise ValueError(f"the number of axons must be positive, but got {n_axon}.")
+
+    if (lcn := ((n_axon - 1) // n_fanin_max).bit_length()) > LCN_EX.LCN_64X:
+        raise ResourceError(
+            f"required LCN extension out of range {LCN_EX.LCN_64X} ({lcn}). "
+        )
+
+    return LCN_EX(lcn)
+
+
 class TestData:
 
     toposort_data = ParametrizedTestData(
diff --git a/tests/backend/test_conf_template.py b/tests/backend/test_conf_template.py
index f939adfb..15c956b6 100644
--- a/tests/backend/test_conf_template.py
+++ b/tests/backend/test_conf_template.py
@@ -23,3 +23,11 @@ def test_CorePlacementConfig_instance(
             json.dump(
                 MockCorePlacementConfig.__json__(), f, indent=4, ensure_ascii=True
             )
+
+    def test_EmptyCorePlacementConfig_instance(
+        self, ensure_dump_dir, MockEmptyCorePlacementConfig
+    ):
+        with open(ensure_dump_dir / "empty_core_placement.json", "w") as f:
+            json.dump(
+                MockEmptyCorePlacementConfig.__json__(), f, indent=4, ensure_ascii=True
+            )
diff --git a/tests/backend/test_mapper.py b/tests/backend/test_mapper.py
index 895bcf7d..676158e2 100644
--- a/tests/backend/test_mapper.py
+++ b/tests/backend/test_mapper.py
@@ -234,6 +234,15 @@ def test_export_multi_nodes_more_than_32(
 
         assert len(mapper.graph_info["output"].keys()) == net.n_onodes
 
+    def test_export_empty_cplm(self, build_example_net4_large_scale, ensure_dump_dir):
+        net = build_example_net4_large_scale
+        mapper = pb.Mapper()
+        mapper.build(net)
+        mapper.compile()
+        mapper.export(fp=ensure_dump_dir)
+
+        assert len(mapper.routing_groups[1].wasted_coords) == 2
+
 
 class TestMapper_Weight4:
     @pytest.mark.skipif(
diff --git a/tests/backend/test_placement.py b/tests/backend/test_placement.py
index 8a639044..e911b1ae 100644
--- a/tests/backend/test_placement.py
+++ b/tests/backend/test_placement.py
@@ -4,7 +4,7 @@
 from paicorelib import WeightPrecision as WP
 
 import paibox as pb
-from paibox.backend.placement import NeuSeg, n_axon2lcn_ex
+from paibox.backend.placement import NeuSeg
 from paibox.exceptions import ResourceError
 
 
@@ -238,7 +238,7 @@ def test_weight_ram_mapping(self, shape, wp, nfold):
         if nbit > 1:
             w_unpacked = self._weight_ram_mapping_ref(w_folded, nbit)
         else:
-            w_unpacked = w_folded.copy().astype(np.bool_)
+            w_unpacked = w_folded.astype(np.bool_)
 
         w_unpacked.setflags(write=False)
 
@@ -390,8 +390,10 @@ def test_weight_ram_mapping_2bits(self, packbits2):
 
 
 def test_n_axon2lcn_ex():
-    lcn_ex = n_axon2lcn_ex(1152 * 18 + 1, 1152)
+    from .conftest import n_axon2lcn_ex_proto
+    
+    lcn_ex = n_axon2lcn_ex_proto(1152 * 18 + 1, 1152)
     assert lcn_ex == LCN_EX.LCN_32X
 
     with pytest.raises(ResourceError):
-        lcn_ex = n_axon2lcn_ex(1152 * 64 + 1, 1152)
+        lcn_ex = n_axon2lcn_ex_proto(1152 * 64 + 1, 1152)
diff --git a/tests/backend/test_segment_utils.py b/tests/backend/test_segment_utils.py
index 2de467aa..2b3fc1f1 100644
--- a/tests/backend/test_segment_utils.py
+++ b/tests/backend/test_segment_utils.py
@@ -6,7 +6,7 @@
 from paicorelib import WeightPrecision as WP
 
 import paibox as pb
-from paibox.backend.placement import NeuSeg, n_axon2lcn_ex
+from paibox.backend.placement import NeuSeg
 from paibox.backend.segment_utils import (
     aligned_coords,
     get_axon_segments,
@@ -349,7 +349,9 @@ def test_get_neu_segments_both(self, neurons, capacity, wp, lcn_ex, expected):
     ],
 )
 def test_get_axon_segments(axons):
-    lcn_ex = n_axon2lcn_ex(sum(axon.num_out for axon in axons), 1152)
+    from .conftest import n_axon2lcn_ex_proto
+    
+    lcn_ex = n_axon2lcn_ex_proto(sum(axon.num_out for axon in axons), 1152)
 
     tr_max = 1 << lcn_ex
 
@@ -368,7 +370,9 @@ def test_get_axon_segments(axons):
 )
 def test_get_axon_segments_boundary(axons):
     """Illegal boundary cases."""
-    lcn_ex = n_axon2lcn_ex(sum(axon.num_out for axon in axons), 1152)
+    from .conftest import n_axon2lcn_ex_proto
+    
+    lcn_ex = n_axon2lcn_ex_proto(sum(axon.num_out for axon in axons), 1152)
     tr_max = 1 << lcn_ex
 
     with pytest.raises(ResourceError):

From c15deeb15c098dccd99965bd7711e21d84ea4834 Mon Sep 17 00:00:00 2001
From: KafCoppelia <k740677208@gmail.com>
Date: Wed, 10 Apr 2024 20:15:59 +0800
Subject: [PATCH 62/68] =?UTF-8?q?=F0=9F=90=9B=20bugfix:=20core=20blocks=20?=
 =?UTF-8?q?connected=20to=20the=20input=20nodes=20will=20be=20grouped=20in?=
 =?UTF-8?q?to=20routing=20group=20first?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

---
 paibox/backend/graphs.py | 10 +++++++++-
 1 file changed, 9 insertions(+), 1 deletion(-)

diff --git a/paibox/backend/graphs.py b/paibox/backend/graphs.py
index df9925f8..bfba6069 100644
--- a/paibox/backend/graphs.py
+++ b/paibox/backend/graphs.py
@@ -296,6 +296,7 @@ def _degree_check(
 def convert2routing_groups(
     succ_dg_of_cb: Dict[CoreBlock, List[CoreBlock]],
     degrees_of_cb: Dict[CoreBlock, NodeDegree],
+    input_core_blocks: Dict[SourceNodeType, List[CoreBlock]],
 ) -> List[RoutingGroup]:
     ordered_core_blocks = toposort(succ_dg_of_cb)
     seen_cb = set()
@@ -303,13 +304,20 @@ def convert2routing_groups(
 
     _degree_check(degrees_of_cb, succ_dg_of_cb)
 
+    # After that, all input core blocks have been traversed.
+    for input_cbs in input_core_blocks.values():
+        seen_cb.update(input_cbs)
+        routing_groups.append(RoutingGroup(*input_cbs))
+
     for cb in ordered_core_blocks:
-        # Check whether it has been traversed
+        # Check whether it has been traversed. This judgment condition is for core blocks
+        # with out-degree = 1 & output core blocks (out-degree = 0).
         if cb not in seen_cb:
             seen_cb.add(cb)
             routing_groups.append(RoutingGroup(cb))
 
         # If the out-degree > 1, treat the following core blocks as one routing group.
+        # FIXME
         if degrees_of_cb[cb].out_degree > 1:
             succ_cbs = succ_dg_of_cb[cb]
             seen_cb.update(succ_cbs)

From e43ff59cae3cb028f0591151f9db27c87be377bd Mon Sep 17 00:00:00 2001
From: KafCoppelia <k740677208@gmail.com>
Date: Wed, 10 Apr 2024 20:17:56 +0800
Subject: [PATCH 63/68] =?UTF-8?q?=E2=99=BB=EF=B8=8F=20Refactored=20the=20c?=
 =?UTF-8?q?ode=20for=20exporting=20network=20configuration?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

---
 paibox/backend/mapper.py | 243 ++++++++++++++++++++++++++-------------
 1 file changed, 161 insertions(+), 82 deletions(-)

diff --git a/paibox/backend/mapper.py b/paibox/backend/mapper.py
index d2cc1cd0..1f21a2a5 100644
--- a/paibox/backend/mapper.py
+++ b/paibox/backend/mapper.py
@@ -30,7 +30,7 @@
 )
 from .context import _BACKEND_CONTEXT, set_cflag
 from .graphs import PAIGraph, convert2routing_groups, get_node_degrees
-from .graphs_types import NodeDegree
+from .graphs_types import NodeDegree, SourceNodeType
 from .placement import CoreBlock, aligned_coords, max_lcn_of_cb
 from .routing import RoutingGroup, RoutingRoot
 
@@ -50,32 +50,23 @@ class Mapper:
 
     def __init__(self) -> None:
         self.core_blocks: List[CoreBlock] = []
-        """A list for core blocks in topological order."""
-
+        """List for core blocks in the network."""
         self.succ_core_blocks: Dict[CoreBlock, List[CoreBlock]] = defaultdict(list)
-        """Grouped post-synapses of nodes. Structure:
-        {
-            node1.name: {
-                post-node1.name: grouped post-syn1,
-                post-node2.name: grouped post-syn2
-            }
-        }
-        """
-        self.degrees_of_cb: Dict[CoreBlock, NodeDegree] = defaultdict(NodeDegree)
+        self.input_core_blocks: Dict[SourceNodeType, List[CoreBlock]] = defaultdict(
+            list
+        )
+        """List of input core blocks for each input node."""
 
-        self.core_params: Dict[Coord, CoreConfig] = dict()
-        """The dictionary of core parameters. Structure:
-        {
-            address of core: {
-                parameters...
-            }
-        }
-        """
+        self.degrees_of_cb: Dict[CoreBlock, NodeDegree] = defaultdict(NodeDegree)
         self.routing_groups: List[RoutingGroup] = []
 
         self.core_plm_config: CorePlacementInfo = dict()
+        self.core_params: Dict[Coord, CoreConfig] = dict()
+        """The dictionary of core parameters."""
+
         self.graph_info: GraphInfo
         self.n_core_required = 0
+        self.n_core_occupied = 0
 
         self.clear()
 
@@ -85,10 +76,14 @@ def clear(self) -> None:
 
         self.core_blocks.clear()
         self.succ_core_blocks.clear()
+        self.input_core_blocks.clear()
 
         self.core_params.clear()
         self.core_plm_config.clear()
 
+        self.n_core_required = 0
+        self.n_core_occupied = 0
+
         # Set default cflags
         _BACKEND_CONTEXT.cflags.clear()
         set_cflag(enable_wp_opt=True)
@@ -180,10 +175,28 @@ def build_core_blocks(self) -> None:
             )
             self.succ_core_blocks[cb].extend(succ_cbs)
 
+        for inode in self.graph.inodes.values():
+            # TODO How to prevent this situation: there is input node & predecessor nodes
+            # in a certain core blocks.
+
+            # Disconnected input nodes will not be recorded.
+            succ_cb = [cb for cb in self.core_blocks if inode in cb.source]
+            if len(succ_cb) > 0:
+                self.input_core_blocks[inode] = succ_cb
+
         self.degrees_of_cb = get_node_degrees(self.succ_core_blocks)
 
     def lcn_ex_adjustment(self) -> None:
         """Adjust the LCN extension of each core block."""
+        # In the absence of the above complex situations, the following judgment is useless.
+        # But it'd be better to add this lcn adjustment.
+        for input_cbs in self.input_core_blocks.values():
+            if len(input_cbs) > 1:
+                max_lcn_ex = max_lcn_of_cb(input_cbs)
+                # Adjust the `lcn_ex` of the input core blocks for each input node
+                for g in input_cbs:
+                    g.lcn_ex = max_lcn_ex
+
         for cb in self.core_blocks:
             succ_cb = self.succ_core_blocks[cb]
 
@@ -228,7 +241,7 @@ def coord_assign(self) -> None:
 
         # Generate routing groups by given the list of core blocks.
         routing_groups = convert2routing_groups(
-            self.succ_core_blocks, self.degrees_of_cb
+            self.succ_core_blocks, self.degrees_of_cb, self.input_core_blocks
         )
         for rg in routing_groups:
             if not self.routing_tree.insert_routing_group(rg):
@@ -301,38 +314,36 @@ def _inpproj_config_export(self) -> InputNodeInfo:
         """
         input_nodes_info = dict()
 
-        # Traverse input core blocks where input nodes are
-        for input_cb in filter(
-            lambda cb: any(s for s in cb.source if s in self.graph.inodes.values()),
-            self.core_blocks,
-        ):
-            dest_coords = input_cb.core_coords
+        # Traverse input core blocks
+        for inode, input_cbs in self.input_core_blocks.items():
+            dest_coords: List[Coord] = []
+            for cb in input_cbs:  # Do not use iterative generation.
+                dest_coords.extend(cb.core_coords)
+
             dest_rid = get_replication_id(dest_coords)
 
-            # Traverse input nodes in the input core block only, in case that
-            # "other source nodes" are grouped with the input nodes.
-            for inode in filter(
-                lambda s: s in self.graph.inodes.values(), input_cb.source
-            ):
-                axon_coords = aligned_coords(
-                    slice(0, input_cb.n_axon_of(input_cb.source.index(inode)), 1),
-                    input_cb.axon_segments[inode],
-                    1,
-                    input_cb.n_timeslot,
-                )
+            # The arrangement of axons is the same for the rest of `input_cbs`.
+            # LCN of `input_cbs` are the same.
+            input_cb = input_cbs[0]
+            axon_coords = aligned_coords(
+                slice(0, input_cb.n_axon_of(input_cb.source.index(inode)), 1),
+                input_cb.axon_segments[inode],
+                1,
+                input_cb.n_timeslot,
+            )
 
-                neuron_dest = NeuronDest(
-                    [coord.tick_relative for coord in axon_coords],
-                    [coord.addr_axon for coord in axon_coords],
-                    dest_coords[0].x,
-                    dest_coords[0].y,
-                    dest_rid.x,
-                    dest_rid.y,
-                    _BACKEND_CONTEXT["local_chip_addr"].x,
-                    _BACKEND_CONTEXT["local_chip_addr"].y,
-                )
+            neuron_dest = NeuronDest(
+                [coord.tick_relative for coord in axon_coords],
+                [coord.addr_axon for coord in axon_coords],
+                dest_coords[0].x,
+                dest_coords[0].y,
+                dest_rid.x,
+                dest_rid.y,
+                _BACKEND_CONTEXT["local_chip_addr"].x,
+                _BACKEND_CONTEXT["local_chip_addr"].y,
+            )
 
-                input_nodes_info[inode.name] = neuron_dest
+            input_nodes_info[inode.name] = neuron_dest
 
         return input_nodes_info
 
@@ -367,45 +378,113 @@ def _member_cb_and_onode_config_export(self) -> OutputDestInfo:
                     CoreBlock.export_core_plm_config(member_cb)
                 )  # compatible for py3.8
 
-                output_axon_offset = 0
-                for core_plm in member_cb.core_placements.values():
-                    for neu_seg in core_plm.neu_segs_of_cplm:
-                        # Find the axon destinations
-                        dest_cb = [
-                            cb for cb in self.core_blocks if neu_seg.parent in cb.source
-                        ]
-                        # TODO When obtaining core blocks, we should determine which core block
-                        # is used as a pure member core block, which one is used as both a member
-                        # & an output core block. This constrains the grouping of neurons.
-                        if dest_cb:
-                            # `neu_seg` is member neurons
-                            # Should not happen
-                            assert _cb_routable(self.routing_groups, dest_cb)
-                            core_plm.export_neu_config(neu_seg, dest_cb)
-                        else:
-                            # `neu_seg` is output neurons. Every neuron segment is a output node.
-                            # Update the offset of axon
-                            output_axon_offset = core_plm.export_neu_config(
-                                neu_seg,
-                                output_core_coord=ocoord,
-                                axon_addr_offset=output_axon_offset,
-                            )
-                            output_dest_info[neu_seg.parent.name][
-                                core_plm.coord.address
-                            ] = core_plm.neu_configs[neu_seg.parent].neuron_dest_info
-
-                            # Coord.x += 1 for the destination of the next output node
-                            ocoord += CoordOffset(1, 0)
-
-                    self.core_plm_config[core_plm.coord] = (
-                        core_plm.export_core_plm_config()
+                if self.degrees_of_cb[member_cb].out_degree == 0:
+                    # member_cb is a pure output core block. All neu_segs inside are output neurons.
+                    ocoord = self._onode_cb_config_export(
+                        member_cb, output_dest_info, ocoord
+                    )
+                elif any(d in self.graph.onodes.values() for d in member_cb.dest):
+                    # member_cb is both a member & output core block.
+                    ocoord = self._member_onode_cb_config_export(
+                        member_cb, output_dest_info, ocoord
                     )
+                else:
+                    # member_cb is a pure member.
+                    self._member_cb_config_export(member_cb)
 
-            # Generate default configurations for wasted core placements
+                for coord, core_plm in member_cb.core_placements.items():
+                    self.core_plm_config[coord] = core_plm.export_core_plm_config()
+
+            # Generate default configurations for wasted core placements of the routing group
             self.core_plm_config.update(rg.get_wasted_cplm_config())
 
         return output_dest_info
 
+    def _member_cb_config_export(self, member_cb: CoreBlock) -> None:
+        """Export configuration information for core blocks that are pure members."""
+        succ_cbs = self.succ_core_blocks[member_cb]
+
+        for core_plm in member_cb.core_placements.values():
+            for neu_seg in core_plm.neu_segs_of_cplm:
+                # Find the axon destinations of neu_seg, not the successor core blocks.
+                dest_cb_of_nseg = [cb for cb in succ_cbs if neu_seg.parent in cb.source]
+
+                assert _cb_routable(self.routing_groups, dest_cb_of_nseg)
+                core_plm.export_neu_config(neu_seg, dest_cb_of_nseg)
+
+    def _member_onode_cb_config_export(
+        self,
+        member_onode_cb: CoreBlock,
+        output_dest_info: OutputDestInfo,
+        ocoord: Coord,
+    ) -> Coord:
+        """Export configuration information for core blocks that are both members & output."""
+        cur_ocoord = ocoord
+        output_axon_offset = 0
+        o_nodes = [d for d in member_onode_cb.dest if d in self.graph.onodes.values()]
+        succ_cbs = self.succ_core_blocks[member_onode_cb]
+
+        for core_plm in member_onode_cb.core_placements.values():
+            for neu_seg in core_plm.neu_segs_of_cplm:
+                dest_cb_of_nseg = [cb for cb in succ_cbs if neu_seg.parent in cb.source]
+
+                if len(dest_cb_of_nseg) > 0:
+                    assert _cb_routable(self.routing_groups, dest_cb_of_nseg)
+                    core_plm.export_neu_config(neu_seg, dest_cb_of_nseg)
+                else:
+                    offset_idx = o_nodes.index(neu_seg.parent)
+
+                    if hasattr(CoordOffset, "from_offset"):
+                        # For paicorelib > 0.0.13
+                        raise NotImplementedError
+                    else:
+                        # For paicorelib <= 0.0.13
+                        cur_ocoord = ocoord + CoordOffset(
+                            offset_idx % 32, offset_idx // 32
+                        )
+
+                    output_axon_offset = core_plm.export_neu_config(
+                        neu_seg,
+                        output_core_coord=cur_ocoord,
+                        axon_addr_offset=output_axon_offset,
+                    )
+                    output_dest_info[neu_seg.parent.name][core_plm.coord.address] = (
+                        core_plm.neu_configs[neu_seg.parent].neuron_dest_info
+                    )
+
+        return cur_ocoord
+
+    def _onode_cb_config_export(
+        self, onode_cb: CoreBlock, output_dest_info: OutputDestInfo, ocoord: Coord
+    ) -> Coord:
+        """Export configuration information for core blocks that are pure output."""
+        cur_ocoord = ocoord
+        output_axon_offset = 0
+        o_nodes = [d for d in onode_cb.dest if d in self.graph.onodes.values()]
+
+        for core_plm in onode_cb.core_placements.values():
+            for neu_seg in core_plm.neu_segs_of_cplm:
+                # Get the output coordinate of this neu_seg
+                offset_idx = o_nodes.index(neu_seg.parent)
+
+                if hasattr(CoordOffset, "from_offset"):
+                    # For paicorelib > 0.0.13
+                    raise NotImplementedError
+                else:
+                    # For paicorelib <= 0.0.13
+                    cur_ocoord = ocoord + CoordOffset(offset_idx % 32, offset_idx // 32)
+
+                output_axon_offset = core_plm.export_neu_config(
+                    neu_seg,
+                    output_core_coord=cur_ocoord,
+                    axon_addr_offset=output_axon_offset,
+                )
+                output_dest_info[neu_seg.parent.name][core_plm.coord.address] = (
+                    core_plm.neu_configs[neu_seg.parent].neuron_dest_info
+                )
+
+        return cur_ocoord
+
     def export(
         self,
         write_to_file: bool = True,

From 09d48f750ea1a4eba22952522b52aa274a41b88a Mon Sep 17 00:00:00 2001
From: KafCoppelia <k740677208@gmail.com>
Date: Wed, 10 Apr 2024 20:18:50 +0800
Subject: [PATCH 64/68] =?UTF-8?q?=E2=9C=85=20added=20tests=20for=20network?=
 =?UTF-8?q?=20with=20more=20than=20one=20input=20nodes?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

---
 tests/backend/conftest.py    | 86 +++++++++++++++++++++++++++++++-----
 tests/backend/test_mapper.py | 22 +++++++--
 2 files changed, 94 insertions(+), 14 deletions(-)

diff --git a/tests/backend/conftest.py b/tests/backend/conftest.py
index aec0d57e..690c06fb 100644
--- a/tests/backend/conftest.py
+++ b/tests/backend/conftest.py
@@ -120,9 +120,12 @@ def __init__(self):
 
 
 class NetForTest2(pb.Network):
-    """
-    INP1 -> S1 -> N1 -> S3 -> N2
-    INP2 -> S2 -> N1
+    """Test the following situations with multiple input nodes:
+        1. Two input nodes assigned within one core block.
+
+    Structure:
+        INP1 -> S1 -> N1 -> S3 -> N2
+        INP2 -> S2 -> N1
     """
 
     def __init__(self):
@@ -210,10 +213,16 @@ def __init__(self, large_scale: bool = False):
         )
 
 
-class Network_with_multi_inodes(pb.Network):
-    """
-    INP1 -> S1 -> N1 -> S2 -> N2
-    INP2 -> S3 -> N2
+class Network_with_multi_inodes1(pb.Network):
+    """Test the following situations with multiple input nodes:
+        1. Two input nodes with their own core blocks.
+        2. An input node assigned within one core block.
+        TODO 3. The input node is input to the middle layer.
+
+    Structure:
+        INP1 -> S1 -> N1 -> S2 -> N2
+             -> S3 -> N3 -> S4 -> N4 -> S5 -> N5
+        INP2 -> S6 -> N6 -> S7 -> N7 -> S8 -> N5
     """
 
     def __init__(self):
@@ -222,6 +231,53 @@ def __init__(self):
         self.inp2 = pb.InputProj(input=1, shape_out=(50,), name="inp2")
         self.n1 = pb.TonicSpiking(80, 2, name="n1", tick_wait_start=1)
         self.n2 = pb.TonicSpiking(20, 3, name="n2", tick_wait_start=2)
+        self.n3 = pb.TonicSpiking(20, 3, name="n3", tick_wait_start=1)
+        self.n4 = pb.TonicSpiking(20, 3, name="n4", tick_wait_start=2)
+        self.n5 = pb.TonicSpiking(40, 3, name="n5", tick_wait_start=3)
+        self.n6 = pb.TonicSpiking(40, 3, name="n6", tick_wait_start=1)
+        self.n7 = pb.TonicSpiking(40, 3, name="n7", tick_wait_start=2)
+
+        self.s1 = pb.FullConn(
+            self.inp1, self.n1, conn_type=pb.SynConnType.All2All, name="s1"
+        )
+        self.s2 = pb.FullConn(
+            self.n1, self.n2, conn_type=pb.SynConnType.All2All, name="s2"
+        )
+        self.s3 = pb.FullConn(
+            self.inp1, self.n3, conn_type=pb.SynConnType.All2All, name="s3"
+        )
+        self.s4 = pb.FullConn(
+            self.n3, self.n4, conn_type=pb.SynConnType.All2All, name="s4"
+        )
+        self.s5 = pb.FullConn(
+            self.n4, self.n5, conn_type=pb.SynConnType.All2All, name="s5"
+        )
+        self.s6 = pb.FullConn(
+            self.inp2, self.n6, conn_type=pb.SynConnType.All2All, name="s6"
+        )
+        self.s7 = pb.FullConn(
+            self.n6, self.n7, conn_type=pb.SynConnType.All2All, name="s7"
+        )
+        self.s8 = pb.FullConn(
+            self.n7, self.n5, conn_type=pb.SynConnType.All2All, name="s8"
+        )
+
+
+class Network_with_multi_inodes2(pb.Network):
+    """Test the following situations with multiple input nodes:
+        1. One input node assigned within more than one core block.
+
+    Structure:
+        INP1 -> S1 -> N1(tws=1) -> S2 -> N2
+             -> S3 -> N3(tws=2) -> S4 -> N2
+    """
+
+    def __init__(self):
+        super().__init__()
+        self.inp1 = pb.InputProj(input=1, shape_out=(40,), name="inp1")
+        self.n1 = pb.TonicSpiking(80, 2, name="n1", tick_wait_start=1)
+        self.n2 = pb.TonicSpiking(20, 3, name="n2", tick_wait_start=3)
+        self.n3 = pb.TonicSpiking(20, 3, name="n3", tick_wait_start=2)
 
         self.s1 = pb.FullConn(
             self.inp1, self.n1, conn_type=pb.SynConnType.All2All, name="s1"
@@ -230,7 +286,10 @@ def __init__(self):
             self.n1, self.n2, conn_type=pb.SynConnType.All2All, name="s2"
         )
         self.s3 = pb.FullConn(
-            self.inp2, self.n2, conn_type=pb.SynConnType.All2All, name="s3"
+            self.inp1, self.n3, conn_type=pb.SynConnType.All2All, name="s3"
+        )
+        self.s4 = pb.FullConn(
+            self.n3, self.n2, conn_type=pb.SynConnType.All2All, name="s4"
         )
 
 
@@ -512,13 +571,18 @@ def build_example_net2():
 
 
 @pytest.fixture(scope="class")
-def build_multi_inputproj_net():
+def build_multi_inputproj_net1():
     return NetForTest2()
 
 
 @pytest.fixture(scope="class")
 def build_multi_inputproj_net2():
-    return Network_with_multi_inodes()
+    return Network_with_multi_inodes1()
+
+
+@pytest.fixture(scope="class")
+def build_multi_inputproj_net3():
+    return Network_with_multi_inodes2()
 
 
 @pytest.fixture(scope="class")
@@ -535,6 +599,7 @@ def build_example_net4():
 def build_example_net4_large_scale():
     return NetForTest4(large_scale=True)
 
+
 @pytest.fixture(scope="class")
 def build_multi_onodes_net():
     return Network_with_multi_onodes()
@@ -684,7 +749,6 @@ def packbits1():
     return partial(packbits_ref, count=1)
 
 
-
 def n_axon2lcn_ex_proto(n_axon, n_fanin_max) -> LCN_EX:
     """Convert #N(of axons) to `LCN_EX` & check.
 
diff --git a/tests/backend/test_mapper.py b/tests/backend/test_mapper.py
index 676158e2..4eb7d71e 100644
--- a/tests/backend/test_mapper.py
+++ b/tests/backend/test_mapper.py
@@ -33,10 +33,10 @@ def default(self, o: Any) -> Any:
 
 
 class TestGraphInfo:
-    def test_multi_inputproj(
-        self, get_mapper, ensure_dump_dir, build_multi_inputproj_net
+    def test_multi_inputproj1(
+        self, get_mapper, ensure_dump_dir, build_multi_inputproj_net1
     ):
-        net = build_multi_inputproj_net
+        net = build_multi_inputproj_net1
         mapper: pb.Mapper = get_mapper
         mapper.build(net)
         mapper.compile()
@@ -65,6 +65,22 @@ def test_multi_inputproj2(
 
         assert len(mapper.graph_info["input"]) == 2
 
+    def test_multi_inputproj3(
+        self, get_mapper, ensure_dump_dir, build_multi_inputproj_net3
+    ):
+        net = build_multi_inputproj_net3
+        mapper: pb.Mapper = get_mapper
+        mapper.build(net)
+        mapper.compile()
+        mapper.export(
+            fp=ensure_dump_dir,
+            format="txt",
+            split_by_coordinate=True,
+            export_core_params=True,
+        )
+
+        assert len(mapper.graph_info["input"]) == 1
+
     def test_multi_output_nodes(
         self, get_mapper, ensure_dump_dir, build_multi_onodes_net
     ):

From 72a3cdc2f0da0dd18907b5601f24baf683d6e5f8 Mon Sep 17 00:00:00 2001
From: KafCoppelia <k740677208@gmail.com>
Date: Wed, 10 Apr 2024 20:19:51 +0800
Subject: [PATCH 65/68] =?UTF-8?q?=F0=9F=A5=85=20updated=20repr=20in=20=5Fd?=
 =?UTF-8?q?egree=5Fcheck?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

---
 paibox/backend/graphs.py | 13 +++++++++----
 1 file changed, 9 insertions(+), 4 deletions(-)

diff --git a/paibox/backend/graphs.py b/paibox/backend/graphs.py
index bfba6069..acd094e2 100644
--- a/paibox/backend/graphs.py
+++ b/paibox/backend/graphs.py
@@ -287,10 +287,15 @@ def _degree_check(
 ) -> None:
     """Filter out such network structure, which is currently not supported."""
     for node in filter(lambda node: degree_of_nodes[node].out_degree > 1, succ_dg):
-        if any(degree_of_nodes[succ_node].in_degree > 1 for succ_node in succ_dg[node]):
-            raise NotSupportedError(
-                "If out-degree of a node is greater than 1, the in-degree of its sucessors must be 1."
-            )
+        for succ_node in succ_dg[node]:
+            if degree_of_nodes[succ_node].in_degree > 1:
+                _node_repr = (
+                    succ_node.name if isinstance(succ_node, CoreBlock) else succ_node
+                )
+                raise NotSupportedError(
+                    f"If out-degree of a node is greater than 1, the in-degree of its sucessors must be 1. "
+                    f"However, in-degree of {_node_repr} is {degree_of_nodes[succ_node].in_degree}."
+                )
 
 
 def convert2routing_groups(

From e5e3efcc7125178296c6c8f00230c597731dc9e8 Mon Sep 17 00:00:00 2001
From: birdswimming <birdswimming3.14@gmail.com>
Date: Wed, 10 Apr 2024 18:28:17 +0800
Subject: [PATCH 66/68] fix routing group

---
 paibox/backend/graphs.py    | 22 +++++++++++++++++++---
 paibox/backend/mapper.py    |  6 +++---
 paibox/backend/placement.py | 10 ++++++----
 3 files changed, 28 insertions(+), 10 deletions(-)

diff --git a/paibox/backend/graphs.py b/paibox/backend/graphs.py
index acd094e2..ffcd5451 100644
--- a/paibox/backend/graphs.py
+++ b/paibox/backend/graphs.py
@@ -198,8 +198,9 @@ def group_edges(self) -> List[FrozenSet[EdgeType]]:
         Return: a list of set of grouped edges.
         """
         self.build_check()
-
+        routing_group_id = 0
         gathered: List[FrozenSet[EdgeType]] = []
+        routing_groups_id: List[int] = []
         seen_edges: Set[EdgeType] = set()  # Check if all edges are traversed
 
         for node in self.ordered_nodes:
@@ -210,6 +211,8 @@ def group_edges(self) -> List[FrozenSet[EdgeType]]:
                 comming_edges = edge_group.difference(seen_edges)
 
                 seen_edges.update(comming_edges)
+                routing_groups_id.append(routing_group_id)
+                routing_group_id += 1
                 gathered.append(frozenset(comming_edges))
 
             if self.degree_of_nodes[node].out_degree > 1:
@@ -225,6 +228,7 @@ def group_edges(self) -> List[FrozenSet[EdgeType]]:
                         succ_edges_sg = frozenset([succ_edges[i] for i in idx])
                         if succ_edges_sg not in gathered:
                             seen_edges.update(succ_edges_sg)
+                            routing_groups_id.append(routing_group_id)
                             gathered.append(succ_edges_sg)
                         else:
                             # FIXME Will this happen?
@@ -233,16 +237,21 @@ def group_edges(self) -> List[FrozenSet[EdgeType]]:
                     succ_edges_sg = frozenset(succ_edges)
                     if succ_edges_sg not in gathered:
                         seen_edges.update(succ_edges_sg)
+                        routing_groups_id.append(routing_group_id)
                         gathered.append(succ_edges_sg)
                     else:
                         # FIXME Will this happen?
                         raise NotSupportedError
 
+                routing_group_id += 1
+
             elif self.degree_of_nodes[node].out_degree == 1:
                 succ_node = list(self.succ_dg[node].keys())[0]
                 # Check the in-degree of the only following node.
                 if self.degree_of_nodes[succ_node].in_degree == 1:
                     gathered.append(frozenset({self.succ_dg[node][succ_node].edge}))
+                    routing_groups_id.append(routing_group_id)
+                    routing_group_id += 1
                 else:
                     # This edge is waiting to be processed when
                     # traversing the following node `succ_node`.
@@ -251,7 +260,7 @@ def group_edges(self) -> List[FrozenSet[EdgeType]]:
                 # out-degree = 0, do nothing.
                 continue
 
-        return gathered
+        return gathered, routing_groups_id
 
     @staticmethod
     def _find_pred_edges(
@@ -326,7 +335,14 @@ def convert2routing_groups(
         if degrees_of_cb[cb].out_degree > 1:
             succ_cbs = succ_dg_of_cb[cb]
             seen_cb.update(succ_cbs)
-            routing_groups.append(RoutingGroup(*succ_cbs))
+            core_block_dict: Dict[int, List[CoreBlock]] = {}
+            for succ_cb in succ_cbs:
+                if succ_cb in core_block_dict.keys():
+                    core_block_dict[succ_cb._routing_id].append(succ_cb)
+                else:
+                    core_block_dict[succ_cb._routing_id] = [succ_cb]
+            for _, succ_cb in core_block_dict.items():
+                routing_groups.append(RoutingGroup(*succ_cb))
 
     return routing_groups
 
diff --git a/paibox/backend/mapper.py b/paibox/backend/mapper.py
index 1f21a2a5..b96e85b6 100644
--- a/paibox/backend/mapper.py
+++ b/paibox/backend/mapper.py
@@ -161,10 +161,10 @@ def build_core_blocks(self) -> None:
 
         Description: Group all edges & build `CoreBlock` based on the grouped edges.
         """
-        grouped_edges = self.graph.group_edges()
+        grouped_edges, routing_groups_id = self.graph.group_edges()
 
-        for syns in grouped_edges:
-            self.core_blocks.append(CoreBlock.build(*syns, seed=0))
+        for syns, routing_id in zip(grouped_edges, routing_groups_id):
+            self.core_blocks.append(CoreBlock.build(*syns, seed=0, routing_id=routing_id))
 
         for cb in self.core_blocks:
             succ_cbs = list(
diff --git a/paibox/backend/placement.py b/paibox/backend/placement.py
index d048ce88..10672789 100644
--- a/paibox/backend/placement.py
+++ b/paibox/backend/placement.py
@@ -61,19 +61,21 @@ class CoreBlock(CoreAbstract):
 
     RUNTIME_MODE: ClassVar[CoreMode] = CoreMode.MODE_SNN
 
-    def __init__(self, *parents: SynSys, seed: int, name: Optional[str] = None) -> None:
+    def __init__(self, *parents: SynSys, seed: int, routing_id: int, name: Optional[str] = None) -> None:
         """Core blocks in SNN mode.
 
         Args:
             - parents: the parent synapses.
             - seed: random seed. Default value is 0.
+            - routing_id: id of routing group.
             - name: name of the core block. Optional.
         """
         super().__init__(name)
         self._parents = parents
         self._lcn_ex = self._n_axon2lcn_ex()
         self._wp = WP.WEIGHT_WIDTH_8BIT  # Default value
-
+        self._routing_id = routing_id
+        
         self.seed = seed
         """Random seed, legal integer, no more than uint64."""
 
@@ -355,7 +357,7 @@ def _obj_repr(self) -> str:
         return ", ".join(n.name for n in self.obj)
 
     @classmethod
-    def build(cls, *synapses: SynSys, seed: int = 0):
+    def build(cls, *synapses: SynSys, seed: int = 0, routing_id: int = 0):
         """Group synapses & build `CoreBlock`."""
         # FIXME where does the parameter check do?
         if seed > (1 << 64) - 1:
@@ -364,7 +366,7 @@ def build(cls, *synapses: SynSys, seed: int = 0):
                 TruncationWarning,
             )
 
-        return cls(*synapses, seed=seed)
+        return cls(*synapses, seed=seed, routing_id=routing_id)
 
     @classmethod
     def export_core_plm_config(cls, cb: "CoreBlock") -> Dict[Coord, CoreConfig]:

From de8963cf89dbbdee2e1acec1239e60a75ad873c7 Mon Sep 17 00:00:00 2001
From: "pre-commit-ci[bot]"
 <66853113+pre-commit-ci[bot]@users.noreply.github.com>
Date: Wed, 10 Apr 2024 12:26:20 +0000
Subject: [PATCH 67/68] :rotating_light: auto fix by pre-commit hooks

---
 docs/Guide-of-PAIBox.md             | 1 +
 paibox/backend/mapper.py            | 4 +++-
 paibox/backend/placement.py         | 9 ++++++---
 paibox/backend/routing.py           | 3 ++-
 tests/backend/conftest.py           | 2 +-
 tests/backend/test_placement.py     | 2 +-
 tests/backend/test_segment_utils.py | 4 ++--
 7 files changed, 16 insertions(+), 9 deletions(-)

diff --git a/docs/Guide-of-PAIBox.md b/docs/Guide-of-PAIBox.md
index d4db1a4e..cbfcde3c 100644
--- a/docs/Guide-of-PAIBox.md
+++ b/docs/Guide-of-PAIBox.md
@@ -227,6 +227,7 @@ s1= pb.FullConn(source=n1, dest=n2, weights=weight1, conn_type=pb.SynConnType.Al
   ```
 
   其权重以标量的形式储存。
+
 - 数组：尺寸要求为 `(N2,)`，可以自定义每组对应神经元之间的连接权重。如下例所示，设置 `weights` 为 `[1, 2, 3, 4, 5]`，
 
   ```python
diff --git a/paibox/backend/mapper.py b/paibox/backend/mapper.py
index b96e85b6..019ea6cb 100644
--- a/paibox/backend/mapper.py
+++ b/paibox/backend/mapper.py
@@ -164,7 +164,9 @@ def build_core_blocks(self) -> None:
         grouped_edges, routing_groups_id = self.graph.group_edges()
 
         for syns, routing_id in zip(grouped_edges, routing_groups_id):
-            self.core_blocks.append(CoreBlock.build(*syns, seed=0, routing_id=routing_id))
+            self.core_blocks.append(
+                CoreBlock.build(*syns, seed=0, routing_id=routing_id)
+            )
 
         for cb in self.core_blocks:
             succ_cbs = list(
diff --git a/paibox/backend/placement.py b/paibox/backend/placement.py
index 10672789..28ceb0e0 100644
--- a/paibox/backend/placement.py
+++ b/paibox/backend/placement.py
@@ -32,9 +32,9 @@
 from paibox.utils import check_attr_same, count_unique_elem
 
 from .conf_template import (
-    EmptyCorePlacementConfig,
     CoreConfig,
     CorePlacementConfig,
+    EmptyCorePlacementConfig,
     NeuronConfig,
 )
 from .context import _BACKEND_CONTEXT
@@ -61,7 +61,9 @@ class CoreBlock(CoreAbstract):
 
     RUNTIME_MODE: ClassVar[CoreMode] = CoreMode.MODE_SNN
 
-    def __init__(self, *parents: SynSys, seed: int, routing_id: int, name: Optional[str] = None) -> None:
+    def __init__(
+        self, *parents: SynSys, seed: int, routing_id: int, name: Optional[str] = None
+    ) -> None:
         """Core blocks in SNN mode.
 
         Args:
@@ -75,7 +77,7 @@ def __init__(self, *parents: SynSys, seed: int, routing_id: int, name: Optional[
         self._lcn_ex = self._n_axon2lcn_ex()
         self._wp = WP.WEIGHT_WIDTH_8BIT  # Default value
         self._routing_id = routing_id
-        
+
         self.seed = seed
         """Random seed, legal integer, no more than uint64."""
 
@@ -717,6 +719,7 @@ def __len__(self) -> int:
 
 class EmptyCorePlacement(CoreAbstract):
     """Empty core placement."""
+
     _default_wp: ClassVar[WP] = WP.WEIGHT_WIDTH_1BIT
     _default_lcn_ex: ClassVar[LCN_EX] = LCN_EX.LCN_1X
     _default_n_dendrite: ClassVar[int] = 0
diff --git a/paibox/backend/routing.py b/paibox/backend/routing.py
index 09da91da..795d00e5 100644
--- a/paibox/backend/routing.py
+++ b/paibox/backend/routing.py
@@ -8,8 +8,9 @@
 from paicorelib.routing_defs import get_routing_consumption
 
 from paibox.exceptions import NotSupportedError
+
 from .conf_template import CorePlacementInfo
-from .placement import EmptyCorePlacement, CoreBlock, CorePlacement
+from .placement import CoreBlock, CorePlacement, EmptyCorePlacement
 
 __all__ = ["RoutingGroup", "RoutingRoot"]
 
diff --git a/tests/backend/conftest.py b/tests/backend/conftest.py
index 690c06fb..200e395b 100644
--- a/tests/backend/conftest.py
+++ b/tests/backend/conftest.py
@@ -23,9 +23,9 @@
 
 import paibox as pb
 from paibox.backend.conf_template import (
-    EmptyCorePlacementConfig,
     CoreConfig,
     CorePlacementConfig,
+    EmptyCorePlacementConfig,
     NeuronConfig,
 )
 from paibox.backend.routing import RoutingCluster
diff --git a/tests/backend/test_placement.py b/tests/backend/test_placement.py
index e911b1ae..93aef554 100644
--- a/tests/backend/test_placement.py
+++ b/tests/backend/test_placement.py
@@ -391,7 +391,7 @@ def test_weight_ram_mapping_2bits(self, packbits2):
 
 def test_n_axon2lcn_ex():
     from .conftest import n_axon2lcn_ex_proto
-    
+
     lcn_ex = n_axon2lcn_ex_proto(1152 * 18 + 1, 1152)
     assert lcn_ex == LCN_EX.LCN_32X
 
diff --git a/tests/backend/test_segment_utils.py b/tests/backend/test_segment_utils.py
index 2b3fc1f1..f4311615 100644
--- a/tests/backend/test_segment_utils.py
+++ b/tests/backend/test_segment_utils.py
@@ -350,7 +350,7 @@ def test_get_neu_segments_both(self, neurons, capacity, wp, lcn_ex, expected):
 )
 def test_get_axon_segments(axons):
     from .conftest import n_axon2lcn_ex_proto
-    
+
     lcn_ex = n_axon2lcn_ex_proto(sum(axon.num_out for axon in axons), 1152)
 
     tr_max = 1 << lcn_ex
@@ -371,7 +371,7 @@ def test_get_axon_segments(axons):
 def test_get_axon_segments_boundary(axons):
     """Illegal boundary cases."""
     from .conftest import n_axon2lcn_ex_proto
-    
+
     lcn_ex = n_axon2lcn_ex_proto(sum(axon.num_out for axon in axons), 1152)
     tr_max = 1 << lcn_ex
 

From da259efdb60ff2c1660248b7346ff5480a7c22ef Mon Sep 17 00:00:00 2001
From: KafCoppelia <k740677208@gmail.com>
Date: Thu, 11 Apr 2024 10:58:21 +0800
Subject: [PATCH 68/68] =?UTF-8?q?=F0=9F=A9=B9=20improved=20the=20bugfix=20?=
 =?UTF-8?q?of=20wrong=20routing=20groups?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

---
 paibox/backend/graphs.py     | 43 +++++++++++++++++++-----------------
 paibox/backend/mapper.py     | 24 ++++++++++++++++----
 paibox/backend/placement.py  |  8 +++----
 tests/backend/conftest.py    | 21 +++++++++++++++---
 tests/backend/test_graphs.py |  4 ++--
 tests/backend/test_mapper.py | 10 ++++++++-
 6 files changed, 76 insertions(+), 34 deletions(-)

diff --git a/paibox/backend/graphs.py b/paibox/backend/graphs.py
index ffcd5451..54a6da71 100644
--- a/paibox/backend/graphs.py
+++ b/paibox/backend/graphs.py
@@ -192,15 +192,16 @@ def build_check(self) -> None:
         if not self.has_built:
             raise BuildError(f"the graph hasn't been built yet.")
 
-    def group_edges(self) -> List[FrozenSet[EdgeType]]:
+    def group_edges(self) -> Tuple[List[FrozenSet[EdgeType]], List[int]]:
         """Group all edges according to a certain rule.
 
-        Return: a list of set of grouped edges.
+        Return: a list of set of grouped edges and a list of routing groups id.
         """
         self.build_check()
-        routing_group_id = 0
-        gathered: List[FrozenSet[EdgeType]] = []
+
+        rgid = 0  # routing group id
         routing_groups_id: List[int] = []
+        gathered: List[FrozenSet[EdgeType]] = []
         seen_edges: Set[EdgeType] = set()  # Check if all edges are traversed
 
         for node in self.ordered_nodes:
@@ -211,8 +212,8 @@ def group_edges(self) -> List[FrozenSet[EdgeType]]:
                 comming_edges = edge_group.difference(seen_edges)
 
                 seen_edges.update(comming_edges)
-                routing_groups_id.append(routing_group_id)
-                routing_group_id += 1
+                routing_groups_id.append(rgid)
+                rgid += 1
                 gathered.append(frozenset(comming_edges))
 
             if self.degree_of_nodes[node].out_degree > 1:
@@ -228,7 +229,7 @@ def group_edges(self) -> List[FrozenSet[EdgeType]]:
                         succ_edges_sg = frozenset([succ_edges[i] for i in idx])
                         if succ_edges_sg not in gathered:
                             seen_edges.update(succ_edges_sg)
-                            routing_groups_id.append(routing_group_id)
+                            routing_groups_id.append(rgid)
                             gathered.append(succ_edges_sg)
                         else:
                             # FIXME Will this happen?
@@ -237,21 +238,21 @@ def group_edges(self) -> List[FrozenSet[EdgeType]]:
                     succ_edges_sg = frozenset(succ_edges)
                     if succ_edges_sg not in gathered:
                         seen_edges.update(succ_edges_sg)
-                        routing_groups_id.append(routing_group_id)
+                        routing_groups_id.append(rgid)
                         gathered.append(succ_edges_sg)
                     else:
                         # FIXME Will this happen?
                         raise NotSupportedError
 
-                routing_group_id += 1
+                rgid += 1
 
             elif self.degree_of_nodes[node].out_degree == 1:
                 succ_node = list(self.succ_dg[node].keys())[0]
                 # Check the in-degree of the only following node.
                 if self.degree_of_nodes[succ_node].in_degree == 1:
                     gathered.append(frozenset({self.succ_dg[node][succ_node].edge}))
-                    routing_groups_id.append(routing_group_id)
-                    routing_group_id += 1
+                    routing_groups_id.append(rgid)
+                    rgid += 1
                 else:
                     # This edge is waiting to be processed when
                     # traversing the following node `succ_node`.
@@ -315,6 +316,7 @@ def convert2routing_groups(
     ordered_core_blocks = toposort(succ_dg_of_cb)
     seen_cb = set()
     routing_groups = []
+    succ_cb_gid_dict = defaultdict(list)
 
     _degree_check(degrees_of_cb, succ_dg_of_cb)
 
@@ -324,24 +326,25 @@ def convert2routing_groups(
         routing_groups.append(RoutingGroup(*input_cbs))
 
     for cb in ordered_core_blocks:
-        # Check whether it has been traversed. This judgment condition is for core blocks
-        # with out-degree = 1 & output core blocks (out-degree = 0).
+        # Check whether the core block has been traversed. This judgment condition is for
+        # core blocks with out-degree = 1 & output core blocks (out-degree = 0).
         if cb not in seen_cb:
             seen_cb.add(cb)
             routing_groups.append(RoutingGroup(cb))
 
-        # If the out-degree > 1, treat the following core blocks as one routing group.
-        # FIXME
+        # If out-degree > 1, group successor core blocks according to their routing id.
         if degrees_of_cb[cb].out_degree > 1:
             succ_cbs = succ_dg_of_cb[cb]
             seen_cb.update(succ_cbs)
-            core_block_dict: Dict[int, List[CoreBlock]] = {}
+
+            succ_cb_gid_dict.clear()
             for succ_cb in succ_cbs:
-                if succ_cb in core_block_dict.keys():
-                    core_block_dict[succ_cb._routing_id].append(succ_cb)
+                if succ_cb._routing_id in succ_cb_gid_dict:
+                    succ_cb_gid_dict[succ_cb._routing_id].append(succ_cb)
                 else:
-                    core_block_dict[succ_cb._routing_id] = [succ_cb]
-            for _, succ_cb in core_block_dict.items():
+                    succ_cb_gid_dict[succ_cb._routing_id] = [succ_cb]
+
+            for succ_cb in succ_cb_gid_dict.values():
                 routing_groups.append(RoutingGroup(*succ_cb))
 
     return routing_groups
diff --git a/paibox/backend/mapper.py b/paibox/backend/mapper.py
index 019ea6cb..d39798d8 100644
--- a/paibox/backend/mapper.py
+++ b/paibox/backend/mapper.py
@@ -1,3 +1,4 @@
+import sys
 from collections import defaultdict
 from copy import copy
 from pathlib import Path
@@ -163,10 +164,20 @@ def build_core_blocks(self) -> None:
         """
         grouped_edges, routing_groups_id = self.graph.group_edges()
 
-        for syns, routing_id in zip(grouped_edges, routing_groups_id):
-            self.core_blocks.append(
-                CoreBlock.build(*syns, seed=0, routing_id=routing_id)
-            )
+        if sys.version_info >= (3, 10):
+            for syns, routing_id in zip(grouped_edges, routing_groups_id, strict=True):
+                self.core_blocks.append(
+                    CoreBlock.build(*syns, seed=0, routing_id=routing_id)
+                )
+        else:
+            if len(grouped_edges) != len(routing_groups_id):
+                raise ValueError(
+                    f"the length of grouped edges & routing groups id are not equal, "
+                    f"{len(grouped_edges)} != {len(routing_groups_id)}"
+                )
+
+            for syns, routing_id in zip(grouped_edges, routing_groups_id):
+                self.core_blocks.append(CoreBlock.build(*syns, routing_id=routing_id))
 
         for cb in self.core_blocks:
             succ_cbs = list(
@@ -352,6 +363,11 @@ def _inpproj_config_export(self) -> InputNodeInfo:
     def _member_cb_and_onode_config_export(self) -> OutputDestInfo:
         """Export configuration & output destinations inormation for core blocks.
 
+        Description:
+            Traverse core placements in core blocks, find the following core    \
+            blocks where the axons at. Get the coordinate of the core placement \
+            & coordinates of axons(for multicasting).
+
         Json exchange file format for output nodes:
         {
             "n3": { # as output node #1 & required two physical cores
diff --git a/paibox/backend/placement.py b/paibox/backend/placement.py
index 28ceb0e0..5df29497 100644
--- a/paibox/backend/placement.py
+++ b/paibox/backend/placement.py
@@ -62,14 +62,14 @@ class CoreBlock(CoreAbstract):
     RUNTIME_MODE: ClassVar[CoreMode] = CoreMode.MODE_SNN
 
     def __init__(
-        self, *parents: SynSys, seed: int, routing_id: int, name: Optional[str] = None
+        self, *parents: SynSys, routing_id: int, seed: int, name: Optional[str] = None
     ) -> None:
         """Core blocks in SNN mode.
 
         Args:
             - parents: the parent synapses.
-            - seed: random seed. Default value is 0.
             - routing_id: id of routing group.
+            - seed: random seed. Default value is 0.
             - name: name of the core block. Optional.
         """
         super().__init__(name)
@@ -359,7 +359,7 @@ def _obj_repr(self) -> str:
         return ", ".join(n.name for n in self.obj)
 
     @classmethod
-    def build(cls, *synapses: SynSys, seed: int = 0, routing_id: int = 0):
+    def build(cls, *synapses: SynSys, routing_id: int, seed: int = 0):
         """Group synapses & build `CoreBlock`."""
         # FIXME where does the parameter check do?
         if seed > (1 << 64) - 1:
@@ -368,7 +368,7 @@ def build(cls, *synapses: SynSys, seed: int = 0, routing_id: int = 0):
                 TruncationWarning,
             )
 
-        return cls(*synapses, seed=seed, routing_id=routing_id)
+        return cls(*synapses, routing_id=routing_id, seed=seed)
 
     @classmethod
     def export_core_plm_config(cls, cb: "CoreBlock") -> Dict[Coord, CoreConfig]:
diff --git a/tests/backend/conftest.py b/tests/backend/conftest.py
index 200e395b..ac11f325 100644
--- a/tests/backend/conftest.py
+++ b/tests/backend/conftest.py
@@ -268,8 +268,10 @@ class Network_with_multi_inodes2(pb.Network):
         1. One input node assigned within more than one core block.
 
     Structure:
-        INP1 -> S1 -> N1(tws=1) -> S2 -> N2
-             -> S3 -> N3(tws=2) -> S4 -> N2
+        INP1 -> S1 -> N1(tws=1) -> S2 -> N2(tws=2)
+             -> S3 -> N3(tws=2) -> S4 -> N4(tws=3)
+             -> S5 -> N5(tws=2) -> S6 -> N6(tws=3)
+                                -> S7 -> N7(tws=2/3)
     """
 
     def __init__(self):
@@ -278,6 +280,10 @@ def __init__(self):
         self.n1 = pb.TonicSpiking(80, 2, name="n1", tick_wait_start=1)
         self.n2 = pb.TonicSpiking(20, 3, name="n2", tick_wait_start=3)
         self.n3 = pb.TonicSpiking(20, 3, name="n3", tick_wait_start=2)
+        self.n4 = pb.TonicSpiking(20, 3, name="n4", tick_wait_start=3)
+        self.n5 = pb.TonicSpiking(20, 3, name="n5", tick_wait_start=2)
+        self.n6 = pb.TonicSpiking(20, 3, name="n6", tick_wait_start=3)
+        self.n7 = pb.TonicSpiking(20, 3, name="n7", tick_wait_start=2)
 
         self.s1 = pb.FullConn(
             self.inp1, self.n1, conn_type=pb.SynConnType.All2All, name="s1"
@@ -289,7 +295,16 @@ def __init__(self):
             self.inp1, self.n3, conn_type=pb.SynConnType.All2All, name="s3"
         )
         self.s4 = pb.FullConn(
-            self.n3, self.n2, conn_type=pb.SynConnType.All2All, name="s4"
+            self.n3, self.n4, conn_type=pb.SynConnType.All2All, name="s4"
+        )
+        self.s5 = pb.FullConn(
+            self.inp1, self.n5, conn_type=pb.SynConnType.All2All, name="s5"
+        )
+        self.s6 = pb.FullConn(
+            self.n5, self.n6, conn_type=pb.SynConnType.All2All, name="s6"
+        )
+        self.s7 = pb.FullConn(
+            self.n5, self.n7, conn_type=pb.SynConnType.All2All, name="s7"
         )
 
 
diff --git a/tests/backend/test_graphs.py b/tests/backend/test_graphs.py
index e8ebdc2b..2b7fdcb7 100644
--- a/tests/backend/test_graphs.py
+++ b/tests/backend/test_graphs.py
@@ -388,7 +388,7 @@ def test_group_edges_with_constrs(
         mapper: pb.Mapper = get_mapper
         mapper.clear()
         mapper.build(net)
-        grouped_edges = mapper.graph.group_edges()
+        grouped_edges, _ = mapper.graph.group_edges()
 
         # In this case, N2 & N3 should be together.
         pos_n2 = pos_n3 = 0
@@ -408,7 +408,7 @@ def test_group_edges_with_constrs(
 
         mapper.clear()
         mapper.build(net)
-        grouped_edges = mapper.graph.group_edges()
+        grouped_edges, _ = mapper.graph.group_edges()
 
         pos_n2 = pos_n3 = 0
         for i, g in enumerate(grouped_edges):
diff --git a/tests/backend/test_mapper.py b/tests/backend/test_mapper.py
index 4eb7d71e..366e7748 100644
--- a/tests/backend/test_mapper.py
+++ b/tests/backend/test_mapper.py
@@ -66,7 +66,7 @@ def test_multi_inputproj2(
         assert len(mapper.graph_info["input"]) == 2
 
     def test_multi_inputproj3(
-        self, get_mapper, ensure_dump_dir, build_multi_inputproj_net3
+        self, monkeypatch, get_mapper, ensure_dump_dir, build_multi_inputproj_net3
     ):
         net = build_multi_inputproj_net3
         mapper: pb.Mapper = get_mapper
@@ -80,6 +80,14 @@ def test_multi_inputproj3(
         )
 
         assert len(mapper.graph_info["input"]) == 1
+        assert len(mapper.core_blocks) == 6
+
+        monkeypatch.setattr(net.n7, "_tws", 3)  # n7.tws: 2 -> 3
+        mapper.clear()
+        mapper.build(net)
+        mapper.compile()
+
+        assert len(mapper.core_blocks) == 5  # n6 & n7 grouped in one core block.
 
     def test_multi_output_nodes(
         self, get_mapper, ensure_dump_dir, build_multi_onodes_net