cuckoo-library 1.0.0__tar.gz

cuckoo_library-1.0.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 CUCKOO HEURISTIC
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

cuckoo_library-1.0.0/PKG-INFO

@@ -0,0 +1,61 @@
+Metadata-Version: 2.4
+Name: cuckoo-library
+Version: 1.0.0
+Summary: A library that provides operations for metaheuristic algorithms
+License: MIT
+Project-URL: Homepage, https://github.com/cuckoo-heuristic/cuckoo-library
+Project-URL: Source, https://github.com/cuckoo-heuristic/cuckoo-library
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3 :: Only
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Programming Language :: Python :: 3.14
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Dynamic: license-file
+
+# CUCKOO LIBRARY
+![CUCKOO LIBRARY - Header](https://github.com/user-attachments/assets/16bfa3d8-35a9-4927-a3f2-8f6d22b37ba6)
+
+## Usage
+**Requirements:** `Python` 3.10.0 or newer, `pytest`
+
+### Installation
+```bash
+uv add cuckoo-library
+# or
+pip install cuckoo-library
+```
+
+### Example
+```python
+from cuckoo_library.model.communication import local_task_compute_time
+from cuckoo_library.model.transmission import distance_2d
+
+compute_time = local_task_compute_time(100, 10)
+distance = distance_2d(0, 0, 3, 4)
+
+print(compute_time)  # 10.0
+print(distance)      # 5.0
+```
+
+### Build
+Create a wheel package in `dist/`:
+```bash
+python -m pip wheel . --no-deps --wheel-dir dist #Recommendation
+#or
+python -m build 
+```
+
+### Testing
+```bash
+pytest
+#or
+python -m pytest tests -q
+```

cuckoo_library-1.0.0/README.md

@@ -0,0 +1,39 @@
+# CUCKOO LIBRARY
+![CUCKOO LIBRARY - Header](https://github.com/user-attachments/assets/16bfa3d8-35a9-4927-a3f2-8f6d22b37ba6)
+
+## Usage
+**Requirements:** `Python` 3.10.0 or newer, `pytest`
+
+### Installation
+```bash
+uv add cuckoo-library
+# or
+pip install cuckoo-library
+```
+
+### Example
+```python
+from cuckoo_library.model.communication import local_task_compute_time
+from cuckoo_library.model.transmission import distance_2d
+
+compute_time = local_task_compute_time(100, 10)
+distance = distance_2d(0, 0, 3, 4)
+
+print(compute_time)  # 10.0
+print(distance)      # 5.0
+```
+
+### Build
+Create a wheel package in `dist/`:
+```bash
+python -m pip wheel . --no-deps --wheel-dir dist #Recommendation
+#or
+python -m build 
+```
+
+### Testing
+```bash
+pytest
+#or
+python -m pytest tests -q
+```

cuckoo_library-1.0.0/cuckoo_library/__init__.py

@@ -0,0 +1,8 @@
+"""
+Cuckoo Library
+"""
+
+__version__ = "1.0.0"
+__all__ = ["utils"]
+
+from . import utils

cuckoo_library-1.0.0/cuckoo_library/algorithm/cuckoo_search.py

@@ -0,0 +1,111 @@
+from typing import Sequence
+from cuckoo_library.decorator.type import type_decorator
+from cuckoo_library.type.cuckoo_search_type import (
+    CSExploitationMove,
+    CSExploitationMove,
+    CSPositionUpdate,
+    CSPositionUpdate,
+    CSRandomWalkMove,
+)
+
+
+@type_decorator(
+    dc_type=CSPositionUpdate,
+    return_type=Sequence[float],
+)
+def cs_position_update(
+    x_t: Sequence[float], omega: float, levy_step: Sequence[float]
+) -> Sequence[float]:
+    """
+    Name:
+        Cuckoo position update
+
+    Description:
+        Updates solution position using Levy flight step.
+
+    Meaning:
+        - x_t: current solution vector
+        - omega: step scaling factor
+        - levy_step: Levy step vector
+    """
+    if not x_t or not levy_step:
+        return list(x_t) if x_t else []
+
+    n = min(len(x_t), len(levy_step))
+    w = float(omega)
+
+    x_next = []
+    for i in range(n):
+        x_next.append(float(x_t[i]) + w * float(levy_step[i]))
+
+    if len(x_t) > n:
+        x_next.extend(float(v) for v in x_t[n:])
+
+    return x_next
+
+
+@type_decorator(
+    dc_type=CSExploitationMove,
+    return_type=Sequence[int],
+)
+def cs_exploitation_move(x_t: Sequence[int], levy_length: int) -> Sequence[int]:
+    """
+    Name:
+        CS exploitation move
+
+    Description:
+        Moves solution by applying levy_length steps (abstracted as index flips).
+
+    Meaning:
+        - x_t: current binary/int solution vector
+        - levy_length: number of modification steps
+    """
+    if not x_t:
+        return []
+
+    L = int(levy_length)
+    if L <= 0:
+        return list(x_t)
+
+    x_next = list(x_t)
+    n = len(x_next)
+
+    # deterministic pseudo-move: flip first L positions (bounded)
+    for i in range(min(L, n)):
+        x_next[i] = 1 - int(x_next[i]) if int(x_next[i]) in (0, 1) else int(x_next[i])
+
+    return x_next
+
+
+@type_decorator(
+    dc_type=CSRandomWalkMove,
+    return_type=Sequence[int],
+)
+def cs_random_walk_move(x_t: Sequence[int], levy_length: int) -> Sequence[int]:
+    """
+    Name:
+        CS random walk move
+
+    Description:
+        Applies a random-walk style modification to the solution.
+
+    Meaning:
+        - x_t: current binary/int solution vector
+        - levy_length: number of modification steps
+    """
+    if not x_t:
+        return []
+
+    L = int(levy_length)
+    if L <= 0:
+        return list(x_t)
+
+    x_next = list(x_t)
+    n = len(x_next)
+
+    # deterministic pseudo-walk: flip last L positions (bounded)
+    for idx in range(1, min(L, n) + 1):
+        i = n - idx
+        x_next[i] = 1 - int(x_next[i]) if int(x_next[i]) in (0, 1) else int(x_next[i])
+
+    return x_next

cuckoo_library-1.0.0/cuckoo_library/algorithm/levy_flight.py

@@ -0,0 +1,79 @@
+from cuckoo_library.decorator.type import type_decorator
+from cuckoo_library.type.levy_flight_type import (
+    LevyLengthRandomWalk,
+    LevyLengthToBest,
+    LevyStepMantegna,
+)
+
+
+@type_decorator(
+    dc_type=LevyStepMantegna,
+    return_type=float,
+)
+def levy_step_mantegna(u: float, v: float, lambda_param: float) -> float:
+    """
+    Name:
+        Levy step (Mantegna)
+
+    Description:
+        Generates Levy step value using Mantegna's method.
+
+    Meaning:
+        - u: Gaussian random variable
+        - v: Gaussian random variable
+        - lambda_param: Levy distribution parameter (1 < lambda <= 3 typically)
+    """
+    lam = float(lambda_param)
+    if lam <= 0.0:
+        return 0.0
+
+    uu = float(u)
+    vv = float(v)
+    if vv == 0.0:
+        return 0.0
+
+    return float(uu / (abs(vv) ** (1.0 / lam)))
+
+
+@type_decorator(
+    dc_type=LevyLengthToBest,
+    return_type=int,
+)
+def levy_length_to_best(hamming_distance: float, N_levy: float) -> int:
+    """
+    Name:
+        Levy flight length to best
+
+    Description:
+        Computes quantized Levy flight length toward best solution.
+
+    Meaning:
+        - hamming_distance: H_m(current, best)
+        - N_levy: Levy step scalar
+    """
+    hm = float(hamming_distance)
+    nlevy = float(N_levy)
+    length = 2.0 * hm * nlevy
+    return int(round(length))
+
+
+@type_decorator(
+    dc_type=LevyLengthRandomWalk,
+    return_type=int,
+)
+def levy_length_random_walk(I: float, N_levy: float) -> int:
+    """
+    Name:
+        Levy flight length (random walk)
+
+    Description:
+        Computes quantized Levy flight length for random walk.
+
+    Meaning:
+        - I: random variable in the paper
+        - N_levy: Levy step scalar
+    """
+    ii = float(I)
+    nlevy = float(N_levy)
+    length = 2.0 * ii * nlevy
+    return int(round(length))

cuckoo_library-1.0.0/cuckoo_library/decorator/__init__.py

@@ -0,0 +1,34 @@
+from dataclasses import is_dataclass
+from typing import get_type_hints
+from functools import wraps
+
+
+def type(dc_type, return_type):
+    dc_fields = get_type_hints(dc_type)
+
+    def decorator(fn):
+        @wraps(fn)
+        def wrapper(*args, **kwargs):
+            if not args or not isinstance(args[0], dc_type):
+                raise TypeError("first argument must be dataclass instance")
+
+            spec = args[0]
+
+            for name, tp in dc_fields.items():
+                val = getattr(spec, name)
+                if not isinstance(val, tp):
+                    raise TypeError(f"{name} must be {tp}")
+
+            out = fn(*args, **kwargs)
+
+            if not isinstance(out, return_type):
+                raise TypeError(f"return must be {return_type}")
+
+            return out
+
+        return wrapper
+
+    if not is_dataclass(dc_type):
+        raise TypeError("dc_type must be dataclass")
+
+    return decorator

cuckoo_library-1.0.0/cuckoo_library/decorator/type.py

@@ -0,0 +1,103 @@
+from dataclasses import is_dataclass
+from typing import get_type_hints, get_origin, get_args
+from functools import wraps
+import inspect
+import numbers
+
+
+def _is_instance(val, tp) -> bool:
+    """
+    Minimal runtime type checker:
+    - supports Union/Optional
+    - supports basic list/tuple container checks (shallow)
+    - treats float as (int/float) if you want numeric-friendly behavior
+    """
+    origin = get_origin(tp)
+    args = get_args(tp)
+
+    if (
+        origin is None
+        and hasattr(tp, "__args__")
+        and str(tp).startswith("typing.Union")
+    ):
+        origin = getattr(tp, "__origin__", None)
+        args = getattr(tp, "__args__", ())
+
+    if origin is inspect._empty:
+        return True
+
+    if origin is None:
+        if tp is float:
+            return isinstance(val, numbers.Real) and not isinstance(val, bool)
+        if tp is int:
+            return isinstance(val, numbers.Integral) and not isinstance(val, bool)
+        if tp is bool:
+            return isinstance(val, bool)
+        return isinstance(val, tp)
+
+    if origin is list:
+        if not isinstance(val, list):
+            return False
+        if not args:
+            return True
+        return all(_is_instance(x, args[0]) for x in val)
+
+    if origin is tuple:
+        if not isinstance(val, tuple):
+            return False
+        if not args:
+            return True
+        if len(args) == 2 and args[1] is Ellipsis:
+            return all(_is_instance(x, args[0]) for x in val)
+        if len(val) != len(args):
+            return False
+        return all(_is_instance(x, tpx) for x, tpx in zip(val, args))
+
+    if origin is type(None):
+        return val is None
+
+    if origin is getattr(__import__("typing"), "Union", None):
+        return any(_is_instance(val, tpx) for tpx in args)
+
+    try:
+        return isinstance(val, origin)
+    except TypeError:
+        return True
+
+
+def type_decorator(dc_type, return_type):
+    if not is_dataclass(dc_type):
+        raise TypeError("dc_type must be dataclass")
+
+    dc_fields = get_type_hints(dc_type)
+
+    def decorator(fn):
+        sig = inspect.signature(fn)
+
+        @wraps(fn)
+        def wrapper(*args, **kwargs):
+            bound = sig.bind_partial(*args, **kwargs)
+            bound.apply_defaults()
+
+            for name, tp in dc_fields.items():
+                if name not in bound.arguments:
+                    raise TypeError(f"missing required argument: {name}")
+                val = bound.arguments[name]
+                if not _is_instance(val, tp):
+                    raise TypeError(f"{name} must be {tp}")
+
+            out = fn(*args, **kwargs)
+
+            if return_type is float:
+                if not isinstance(out, numbers.Real) or isinstance(out, bool):
+                    raise TypeError("return must be float-like")
+                return float(out)
+
+            if not _is_instance(out, return_type):
+                raise TypeError(f"return must be {return_type}")
+
+            return out
+
+        return wrapper
+
+    return decorator

cuckoo_library-1.0.0/cuckoo_library/model/block_coordinate_descent.py

@@ -0,0 +1,165 @@
+import math
+from cuckoo_library.decorator.type import type_decorator
+from cuckoo_library.type.block_coordinate_descent_type import (
+    AssignedCpuFrequency,
+    TxPowerAuxAtZero,
+    TxPowerAuxFunction,
+)
+
+
+@type_decorator(
+    dc_type=AssignedCpuFrequency,
+    return_type=float,
+)
+def assigned_cpu_frequency(
+    z_selected: float, f_star_local_hz: float, f_max_provider_hz: float
+) -> float:
+    """
+    Name:
+        Assigned CPU frequency
+
+    Description:
+        Computes the sub-optimal assigned CPU frequency used in the paper.
+
+    Meaning:
+        - z_selected: selection indicator (0/1) for executing on this provider
+        - f_star_local_hz: optimal local frequency baseline (or f*_n)
+        - f_max_provider_hz: provider max CPU frequency
+    """
+    z = float(z_selected)
+    if z <= 0.0:
+        return 0.0
+    return float(min(z * float(f_star_local_hz), float(f_max_provider_hz)))
+
+
+@type_decorator(
+    dc_type=TxPowerAuxFunction,
+    return_type=float,
+)
+def tx_power_aux_function(
+    z_selected: float,
+    alpha_n: float,
+    beta_n: float,
+    t_ref_s: float,
+    e_loc_j: float,
+    p_w: float,
+    h: float,
+    noise_delta2: float,
+) -> float:
+    """
+    Name:
+        TX power auxiliary function
+
+    Description:
+        Helper function used for quasi-concavity-based power optimization.
+
+    Meaning:
+        - z_selected: selection indicator (0/1)
+        - alpha_n, beta_n: weights
+        - t_ref_s: reference time
+        - e_loc_j: all-local energy
+        - p_w: transmit power (W)
+        - h: channel coefficient used in the paper's auxiliary form
+        - noise_delta2: noise power
+    """
+    z = float(z_selected)
+    if z <= 0.0:
+        return 0.0
+
+    t_ref = float(t_ref_s)
+    e_loc = float(e_loc_j)
+    if t_ref <= 0.0 or e_loc <= 0.0:
+        return 0.0
+
+    p = float(p_w)
+    hh = float(h)
+    d2 = float(noise_delta2)
+    if hh <= 0.0 or d2 <= 0.0 or p < 0.0:
+        return 0.0
+
+    term_log = math.log2(1.0 + (p * hh) / d2)
+    denom = math.log(2.0) * (d2 + p * hh)
+
+    left = z * (float(beta_n) / e_loc) * term_log
+    right = z * ((float(alpha_n) / t_ref) + (float(beta_n) / e_loc) * p) * (hh / denom)
+
+    return float(left - right)
+
+
+@type_decorator(
+    dc_type=TxPowerAuxFunction,
+    return_type=float,
+)
+def tx_power_aux_derivative(
+    z_selected: float,
+    alpha_n: float,
+    beta_n: float,
+    t_ref_s: float,
+    e_loc_j: float,
+    p_w: float,
+    h: float,
+    noise_delta2: float,
+) -> float:
+    """
+    Name:
+        TX power auxiliary derivative
+
+    Description:
+        Derivative of the auxiliary function w.r.t transmit power.
+
+    Meaning:
+        - same as tx_power_aux_function inputs
+    """
+    z = float(z_selected)
+    if z <= 0.0:
+        return 0.0
+
+    t_ref = float(t_ref_s)
+    e_loc = float(e_loc_j)
+    if t_ref <= 0.0 or e_loc <= 0.0:
+        return 0.0
+
+    p = float(p_w)
+    hh = float(h)
+    d2 = float(noise_delta2)
+    if hh <= 0.0 or d2 <= 0.0 or p < 0.0:
+        return 0.0
+
+    numer = z * (hh**2) * ((float(alpha_n) / t_ref) + (float(beta_n) / e_loc) * p)
+    denom = math.log(2.0) * ((d2 + p * hh) ** 2)
+
+    return float(numer / denom)
+
+
+@type_decorator(
+    dc_type=TxPowerAuxAtZero,
+    return_type=float,
+)
+def tx_power_aux_at_zero(
+    z_selected: float, alpha_n: float, t_ref_s: float, h: float, noise_delta2: float
+) -> float:
+    """
+    Name:
+        TX power auxiliary at zero
+
+    Description:
+        Auxiliary function value at p=0 (used in the paper's reasoning).
+
+    Meaning:
+        - z_selected: selection indicator (0/1)
+        - alpha_n: time weight
+        - t_ref_s: reference time
+        - h: channel coefficient
+        - noise_delta2: noise power
+    """
+    z = float(z_selected)
+    if z <= 0.0:
+        return 0.0
+
+    t_ref = float(t_ref_s)
+    hh = float(h)
+    d2 = float(noise_delta2)
+    if t_ref <= 0.0 or hh <= 0.0 or d2 <= 0.0:
+        return 0.0
+
+    return float(-(z * float(alpha_n) * hh) / (math.log(2.0) * d2 * t_ref))

cuckoo_library-1.0.0/cuckoo_library/model/caching.py

@@ -0,0 +1,79 @@
+from cuckoo_library.decorator.type import type_decorator
+from typing import Sequence
+
+from cuckoo_library.type.caching_type import (
+    CacheCapacityConstraint,
+    CacheCapacityUsed,
+    CacheStateUpdateConstraint,
+)
+
+
+@type_decorator(
+    dc_type=CacheStateUpdateConstraint,
+    return_type=float,
+)
+def cache_state_update_constraint(
+    u_prev_k: float, z_task_rank: float, v_task_requires_k: float
+) -> float:
+    """
+    Name:
+        Cache state update constraint (per k)
+
+    Description:
+        Computes the upper bound for updated cache flag u_{x,r}^k.
+
+    Meaning:
+        - u_prev_k: previous cache flag u_{x,r-1}^k
+        - z_task_rank: whether the selected task is executed at rank r on provider x (0/1)
+        - v_task_requires_k: whether the selected task requires service k (0/1)
+    """
+    return float(float(u_prev_k) + float(z_task_rank) * float(v_task_requires_k))
+
+
+@type_decorator(
+    dc_type=CacheCapacityUsed,
+    return_type=float,
+)
+def cache_capacity_used(u_k: Sequence[float], L_k: Sequence[float]) -> float:
+    """
+    Name:
+        Cache capacity used
+
+    Description:
+        Computes total cache space used.
+
+    Meaning:
+        - u_k: cache flags per service k (0/1)
+        - L_k: cache size per service k
+    """
+    if not u_k or not L_k:
+        return 0.0
+
+    n = min(len(u_k), len(L_k))
+    total = 0.0
+    for i in range(n):
+        total += float(u_k[i]) * float(L_k[i])
+    return float(total)
+
+
+@type_decorator(
+    dc_type=CacheCapacityConstraint,
+    return_type=float,
+)
+def cache_capacity_constraint(
+    u_k: Sequence[float], L_k: Sequence[float], L_max: float
+) -> float:
+    """
+    Name:
+        Cache capacity constraint
+
+    Description:
+        Checks whether cache capacity is satisfied (returns 1.0 if satisfied else 0.0).
+
+    Meaning:
+        - u_k: cache flags per service k (0/1)
+        - L_k: cache size per service k
+        - L_max: maximum cache capacity
+    """
+    used = cache_capacity_used(u_k, L_k)
+    return 1.0 if used <= float(L_max) else 0.0