server-simulator 0.1.0__py3-none-any.whl

server_simulator-0.1.0.dist-info/METADATA

@@ -0,0 +1,115 @@
+Metadata-Version: 2.4
+Name: server-simulator
+Version: 0.1.0
+Summary: Add your description here
+License-File: LICENSE
+Requires-Python: >=3.10
+Requires-Dist: gymnasium>=1.2.1
+Requires-Dist: numpy>=2.2.6
+Requires-Dist: pygame>=2.6.1
+Requires-Dist: rust-enum>=1.1.5
+Description-Content-Type: text/markdown
+
+![Tests](https://github.com/dev0Guy/server-simulator/actions/workflows/tests.yml/badge.svg?branch=main)
+[![Coverage](https://codecov.io/gh/dev0Guy/server-simulator/branch/main/graph/badge.svg)](https://codecov.io/gh/dev0Guy/server-simulator)
+![Python](https://img.shields.io/badge/Python-3.10%2B-blue?logo=python)
+![License](https://img.shields.io/github/license/dev0Guy/server-simulator)
+[![PEP8](https://img.shields.io/badge/code%20style-pep8-orange.svg)](https://www.python.org/dev/peps/pep-0008/)
+
+Base Status
+-----------
+We've created 3 Environment for scheduling, which implement the `ClusterABC` with `JobCollection` and `MachineCollection` protocols: 
+
+
+### SingleSlot Environment
+
+| Component | Details |
+|----------|---------|
+| **Description** | Minimal scheduling environment with no temporal memory; each machine and job exposes only its current resource usage. |
+| **State: Machines** | Shape: **[resource_usage]** — a single-cell array indicating current resource utilization (value between 0–1). |
+| **State: Jobs** | Shape: **[resource_usage]** — a single-cell array indicating the current resource requirement (value between 0–1). |
+| **Actions** | Discrete integer: **0 … (num_machines × num_jobs) + 1**. |
+| **Action 0** | Interrupt / time tick (move to next timestamp). |
+| **Action 1+** | Scheduling decision mapping to a specific **(machine, job)** pair. |
+
+### DeepRM Environment
+
+| Component | Details |
+|----------|---------|
+| **Description** | Environment inspired by the DeepRM scheduling model, representing fine-grained resource units across time. |
+| **State: Machines** | Tensor shape: **[num_machines, num_resources, num_resource_cells, num_ticks]**. Each cell represents whether resource unit **r_unit** of resource **r** is occupied at time **t**. |
+| **State: Jobs** | Tensor shape: **[num_jobs, num_resources, num_resource_cells, num_ticks]**. Each cell represents whether the job requires resource unit **r_unit** of resource **r** at time **t**. |
+| **Actions** | Discrete integer: **0 … (num_machines × num_jobs) + 1**. |
+| **Action 0** | Interrupt / time tick (advance to next timestamp). |
+| **Action 1+** | Scheduling decision mapping to a specific **(machine, job)** pair. |
+
+### MetricBased Environment
+
+| Component | Details |
+|----------|---------|
+| **Description** | Scheduling environment that models resource usage of machines and jobs over time. |
+| **State: Machines** | Tensor shape: **[num_machines, n_resources, n_ticks]**. Each value ∈ **[0–1]** representing machine resource usage for resource **r** at time **t**. |
+| **State: Jobs** | Tensor shape: **[num_jobs, n_resources, n_ticks]**. Each value ∈ **[0–1]** representing job resource demand for resource **r** at time **t**. |
+| **Actions** | Discrete integer: **0 … (num_machines × num_jobs) + 1**. |
+| **Action 0** | Represents an interrupt or a time tick (advance to next timestamp). |
+| **Action 1+** | Represents assigning job **j** to machine **m** (encoded according to environment mapping). |
+
+<br>
+
+**Dilation Operations:** assuming kernel size (in each dimension) is bigger than 1. By padding the input according to max zoom in possible the service can work for varying kernel sizes. 
+In addition, assume that use (in our case the DRL agent) can execute 3 operation with zoomingIn (going up one level -1) or zoomingOut (going out one level +1) or skipping to next timestamp, 
+notice that without executing real scheduling (when in last level and select a machine) can't stop and skip.
+Our algorithm represent the state as ndarray of `shape` to `[kernel_x, kernel_y, *shape[1:]]`. <br>
+
+**Reward Functions:** for now the only reward function is +1 for scheduling job and changing the job status from pending into running.
+
+
+Change Log
+-----
+EMPTY
+
+Tasks:
+-----
+
+#### Important: 
+
+- [-] Create Dilation Gym Environment Wrapper `DilationWrapper`.
+- [ ] Test `DilationWrapper`.
+- [ ] Implement Render technics to represent and visualize cluster result
+- [ ] Implement different reward Wrapper:
+  -  [ ] Need to decide which one ?? 
+
+
+#### Side Note:
+
+- [ ] Create Dilation for DeepRM
+- [ ] Create Tests for DeepRM
+
+  
+Finished Tasks:
+-----
+- [X] Implement global machine Protocol (`Machine`,`MachineCollection`).
+- [X] Implement global job Protocol (`Job`,`JobCollection`).
+- [X] Implement abstract cluster using these protocols, for Cross-functional (`ClusterABC`), where each subclass implement the creation of jobs and machines.
+- [X] Test `ClusterABC` (property based).
+- [X] Implement Single slot cluster using the abstract class (`SingleSlotCluster`).
+- [X] Test `SingleSlotCluster` (property based).
+- [X] Implement DeepRM cluster using the abstract class (`DeepRMCluster`).
+- [X] Test `DeepRMCluster` (property based).
+- [X] Implement MetricBased cluster using the abstract class (`MetricCluster`).
+- [X] Test `MetricCluster` (property based).
+- [X] Implement Gym Environment that get cluster as dependency `BasicClusterEnv`.
+- [X] Test `BasicClusterEnv` (property based) using random scheduler (`RandomScheduler`).
+- [X] Implement Dilation Protocol `DilationProtocol`.
+- [X] Implement Dilation numpy functionality (`hierarchical_pooling`, `get_window_from_cell`, etc..) `array_operation.py`.
+- [X] Test Dilation numpy functionality.
+- [X] Implement Dilation Service for Metric based cluster `MetricBasedDilator`.
+- [X] Test Dilation `MetricBasedDilator`.
+
+## Assumption
+- Dilation assume that cluster state is bigger than dilation & the kernel has no 1 in each of its diminution
+- For each Step which is not real allocation reward is set to 0 
+- On each job has reward of 1 if change status to running 
+- Dilation is operating by taking [n_machine, n_resource, n_ticks] and
+  padding to perpetrate size of [max_x_kernl, max_y_kernel, n_resources, n_ticks]
+- Dilation implement both zoom in and zoom out when arriving to level 0 will cause real scheduling 

server_simulator-0.1.0.dist-info/RECORD

@@ -0,0 +1,49 @@
+src/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+src/envs/__init__.py,sha256=cTNZm1WxT_V7ZMq2llkY8QMSoW6kFVS4k6YOSZ6W6Mo,1909
+src/envs/cluster_simulator/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+src/envs/cluster_simulator/actions.py,sha256=a89vmxnhPym7HND2JUAtoxQb3GqJ3z-ejgoAO-ZtInc,1615
+src/envs/cluster_simulator/basic.py,sha256=2ZgNEoWg7a-yc2VlPsX2n4fTdBq1L7GPWsJZUJXtp6k,2831
+src/envs/cluster_simulator/base/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+src/envs/cluster_simulator/base/renderer.py,sha256=rY81B6390BTS3AHoWWZsC1_Hs0zMUegjKFdkxC0E3AI,1016
+src/envs/cluster_simulator/base/extractors/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+src/envs/cluster_simulator/base/extractors/information.py,sha256=MEtlsiakBnSVsaFzWI3WqcIGA6sY1aUS9xWcF09E5x0,807
+src/envs/cluster_simulator/base/extractors/observation.py,sha256=JFfMaS-n6XAFyV51RVCVIgbssC7EUID4rdta2WQ4Gjw,1580
+src/envs/cluster_simulator/base/extractors/reward.py,sha256=fL_qVtTV7A2xk2UHgcjQUzRpHmUwXC23DBCOD2RvJzs,1011
+src/envs/cluster_simulator/base/internal/cluster.py,sha256=Da2vkCSR6RyBj3_eAKcg93eQt5DCtPmgdBAVAhH8IlM,4636
+src/envs/cluster_simulator/base/internal/dilation.py,sha256=350iSUZpHHq7t4AAJ9qLScCtUwYGI-RFC-iUgHQ6ZjA,6598
+src/envs/cluster_simulator/base/internal/job.py,sha256=WkN8zWnRlcKaX1xh_63IDEbW8djKrCNpq8vmcXauAk8,1644
+src/envs/cluster_simulator/base/internal/machine.py,sha256=tzE-RFetCNP1OQU5XU46VU3biiuW_nqYwBVpam2E8xM,796
+src/envs/cluster_simulator/deep_rm/__init__.py,sha256=UD9oY-Lkw0i9dn21A1A6IZFhxIUJ8Y8gLBjEcHIM2XQ,5495
+src/envs/cluster_simulator/deep_rm/creator.py,sha256=jwBCaEWMLazyeYI5WU5bXKbXHVqvCID-WA74ChGZv5g,1725
+src/envs/cluster_simulator/deep_rm/observation.py,sha256=uahjW4_sq5u7U0gZNglsjGCm727HAGi2Rm0aGpNuNr4,2741
+src/envs/cluster_simulator/deep_rm/internal/custom_type.py,sha256=kJjdmO2JQnxTWJks0ydPW2LOGqClF8AyL2JTorHK720,808
+src/envs/cluster_simulator/deep_rm/internal/jobs.py,sha256=bvXwh6I5nt3CBTc_QlESLZQPTt_PMUJphvDrBSExcxQ,2568
+src/envs/cluster_simulator/deep_rm/internal/machines.py,sha256=QSsijFY2VQSQG5kzAjwv86Ix5vq42F_e3fbAxWWC5y8,1848
+src/envs/cluster_simulator/metric_based/__init__.py,sha256=ReKV6znBOlAj8_74uyPhjtzTmOap2jjitqsPwf4-w6w,5619
+src/envs/cluster_simulator/metric_based/creator.py,sha256=DsqXbEztbfNeA94kYKirh-Z-sbk0CvBH_y68xaZofKw,1791
+src/envs/cluster_simulator/metric_based/observation.py,sha256=zMT65hfrj8a8V1cmWD3h3f6RptzueDiWfwW_Ez-0fhE,2869
+src/envs/cluster_simulator/metric_based/renderer.py,sha256=aQVIVPKWDZmFM2YrgW6PuSND9LA_eEg9qno_XGoMIG8,18567
+src/envs/cluster_simulator/metric_based/internal/custom_type.py,sha256=RpjLnZiBvuooYuEfOeZoH1Z0qE7B1r8LwwC-ZpyVjQc,719
+src/envs/cluster_simulator/metric_based/internal/dilation.py,sha256=l5E1aNkRjpoSFTpbzM_e7IdPo-L2J0e-Qg8ju0WmgfA,2692
+src/envs/cluster_simulator/metric_based/internal/jobs.py,sha256=AoYMEsoXbXfy0JAP6Ln6FjlxOk9iEgfhmEVLS1Wq6Zo,2579
+src/envs/cluster_simulator/metric_based/internal/machines.py,sha256=NvtU109MUwMsO88cSaP42uCwzIAMovyJvCZYgsBaaqo,1825
+src/envs/cluster_simulator/single_slot/__init__.py,sha256=wcgpd8nDvD6Go4K-B1gUXd103l408qKFTr5wAcnSnR4,2918
+src/envs/cluster_simulator/single_slot/creator.py,sha256=9gZSTM40FonjABr5jDYSBFPc1j7JK9Sf9C403HKsghM,1551
+src/envs/cluster_simulator/single_slot/observation.py,sha256=WGAq6WXy_m81gIDZT4Nj1Eo0p1cfxRqLqdewhkP6sp4,2475
+src/envs/cluster_simulator/single_slot/internal/jobs.py,sha256=O5synsGDznVZsTiGYQJqxkH2NcLAuo7IpFUQ7D32QJk,1385
+src/envs/cluster_simulator/single_slot/internal/machines.py,sha256=OwDwKXYRJcxAPvUIy9qRM-NGzQpVCk4_Uvi9YqAbIBg,1404
+src/envs/cluster_simulator/utils/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+src/envs/cluster_simulator/utils/array_operations.py,sha256=ozytluo1s6mX56yRngvvVcbto0D6XY43yAPn9F3lh5I,5553
+src/scheduler/__init__.py,sha256=nLNJeGpkX0f99MZv7U-9pmO2ABru1crlsAvi8HJYtPM,297
+src/scheduler/base_scheduler.py,sha256=gMjSEegVuQoNi_nQB9Bb3p1R2sfQvC6y-M7jWF3mMhM,1192
+src/scheduler/first_come_first_served_scheduler.py,sha256=13hfdjgHnGRnN3bVUiw5Rwo8ANcFBR4aBAOSY2Dkm98,1134
+src/scheduler/random_scheduler.py,sha256=vdDVmGB_r_9BcKibMe-Hpz-T4VBd2ckx3AYxvp7PjfU,1358
+src/scheduler/round_robin_scheduler.py,sha256=CSaknCXC6E6d7dqMCXN8Gn6PzlUBzodrgcIMEnMQ_kc,1755
+src/scheduler/shortest_job_first_scheduler.py,sha256=6JQ7goW5TXOclZKnFADZlOLJbB7o3oN0lXvJWFGdDgk,1542
+src/wrappers/cluster_simulator/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+src/wrappers/cluster_simulator/dilation_wrapper.py,sha256=559T_h5lVsbCsRjX56F5ydyE4ra3-QMHAtriAE9JRSU,5765
+src/wrappers/cluster_simulator/render_wrapper.py,sha256=VeM70jR6SJ4nMyrLjU72754YgVmhd2l_VCYecOVQmFE,2288
+server_simulator-0.1.0.dist-info/METADATA,sha256=jFYmB2wwPoKls7MrG_whatfrNNbM6loLnQfi_hCz52s,6212
+server_simulator-0.1.0.dist-info/WHEEL,sha256=QccIxa26bgl1E6uMy58deGWi-0aeIkkangHcxk2kWfw,87
+server_simulator-0.1.0.dist-info/licenses/LICENSE,sha256=PCKzzTExyQOa6tToNr00723ehmJu4YuZG8E5p4Z-0m8,1064
+server_simulator-0.1.0.dist-info/RECORD,,

server_simulator-0.1.0.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: hatchling 1.29.0
+Root-Is-Purelib: true
+Tag: py3-none-any

server_simulator-0.1.0.dist-info/licenses/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 dev0Guy
+
+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.

src/envs/__init__.py

@@ -0,0 +1,75 @@
+from src.envs.cluster_simulator.base.extractors.reward import (
+    DifferentInPendingJobsRewardCaculator,
+)
+from src.envs.cluster_simulator.basic import BasicClusterEnv as BasicClusterEnv
+from gymnasium import register
+
+from src.envs.cluster_simulator.deep_rm.creator import (
+    DeepRMEnvCreator,
+    DeepRMCreatorParameters,
+)
+from src.envs.cluster_simulator.metric_based.creator import (
+    MetricBasedEnvCreator,
+    MetricBasedCreatorParameters,
+)
+from src.envs.cluster_simulator.single_slot.creator import (
+    SingleSlotEnvCreator,
+    SingleSlotCreatorParameters,
+)
+
+register(
+    "ClusterScheduling-single-slot-v1",
+    SingleSlotEnvCreator(),
+    kwargs=SingleSlotCreatorParameters(  # type: ignore
+        n_jobs=10,
+        n_machines=2,
+        reward_caculator=DifferentInPendingJobsRewardCaculator(),
+        seed=None,
+    ),
+)
+
+
+register(
+    "ClusterScheduling-deeprm-v1",
+    DeepRMEnvCreator(),
+    kwargs=DeepRMCreatorParameters(  # type: ignore
+        n_jobs=10,
+        n_machines=2,
+        n_resources=3,
+        n_resources_unit=5,
+        n_ticks=5,
+        reward_caculator=DifferentInPendingJobsRewardCaculator(),
+        seed=None,
+    ),
+)
+
+
+register(
+    "ClusterScheduling-metric-offline-v1",
+    MetricBasedEnvCreator(),
+    kwargs=MetricBasedCreatorParameters(  #  type: ignore
+        n_jobs=10,
+        n_machines=2,
+        n_resources=3,
+        n_ticks=5,
+        poisson_lambda=4,
+        offline=True,
+        reward_caculator=DifferentInPendingJobsRewardCaculator(),
+        seed=None,
+    ),
+)
+
+register(
+    "ClusterScheduling-metric-online-v1",
+    MetricBasedEnvCreator(),
+    kwargs=MetricBasedCreatorParameters(  #  type: ignore
+        n_jobs=10,
+        n_machines=2,
+        n_resources=3,
+        n_ticks=5,
+        poisson_lambda=4,
+        offline=False,
+        reward_caculator=DifferentInPendingJobsRewardCaculator(),
+        seed=None,
+    ),
+)

src/envs/cluster_simulator/actions.py

@@ -0,0 +1,55 @@
+from typing import NamedTuple, Tuple, TypeVar
+import gymnasium as gym
+
+from src.envs.cluster_simulator.base.internal.cluster import ClusterAction, ClusterABC
+
+Cluster = TypeVar("Cluster", bound=ClusterABC)
+
+
+class EnvironmentAction(NamedTuple):
+    should_schedule: bool
+    schedule: Tuple[int, int]
+
+
+class DilationEnvironmentAction(NamedTuple):
+    selected_machine_cell: Tuple[int, int]
+    selected_job: int
+    execute_schedule_command: bool  # a.k.a skip time
+    contract: bool
+
+    @classmethod
+    def into_action_space(
+        cls, kernel_shape: Tuple[int, int], n_jobs: int
+    ) -> gym.Space[tuple]:
+        return gym.spaces.Tuple(
+            spaces=(
+                gym.spaces.MultiDiscrete(kernel_shape),
+                gym.spaces.Discrete(n_jobs),
+                gym.spaces.Discrete(2),
+                gym.spaces.Discrete(2),
+            )
+        )
+
+
+class ActionConvertor:
+    @staticmethod
+    def convert(original: EnvironmentAction) -> ClusterAction:
+        if original.should_schedule:
+            return ClusterAction.SkipTime()
+
+        assert all(idx >= 0 for idx in original.schedule)
+        return ClusterAction.Schedule(*original.schedule)
+
+    @staticmethod
+    def create_space(cluster: Cluster) -> gym.Space:
+        return gym.spaces.Tuple(
+            (
+                gym.spaces.Discrete(2),
+                gym.spaces.Tuple(
+                    (
+                        gym.spaces.Discrete(cluster.n_machines),  # type: ignore
+                        gym.spaces.Discrete(cluster.n_jobs),  # type: ignore
+                    )
+                ),
+            )
+        )

src/envs/cluster_simulator/base/extractors/information.py

@@ -0,0 +1,26 @@
+import abc
+from typing import TypeVar, TypedDict, Generic
+import numpy.typing as npt
+
+from src.envs.cluster_simulator.base.extractors.observation import ClusterObservation
+
+
+class ClusterBaseInformation(TypedDict):
+    n_machines: int
+    n_jobs: int
+    jobs_status: npt.ArrayLike
+    current_tick: int
+
+
+ClusterInformation = TypeVar("ClusterInformation", bound=ClusterBaseInformation)
+
+
+class BaceClusterInformationExtractor(Generic[ClusterObservation, ClusterInformation]):
+    @abc.abstractmethod
+    def __call__(self, obs: ClusterObservation) -> ClusterInformation:
+        return ClusterBaseInformation(
+            n_machines=obs["machines"].shape[0],
+            n_jobs=obs["jobs_usage"].shape[0],
+            jobs_status=obs["jobs_status"],
+            current_tick=obs["current_tick"],
+        )

src/envs/cluster_simulator/base/extractors/observation.py

@@ -0,0 +1,41 @@
+import abc
+from typing import Protocol, TypeVar, runtime_checkable, overload, Literal
+import gymnasium as gym
+import numpy.typing as npt
+
+from src.envs.cluster_simulator.base.internal.cluster import ClusterABC
+from src.envs.cluster_simulator.base.internal.job import JobCollectionConvertor
+from src.envs.cluster_simulator.base.internal.machine import MachinesCollectionConvertor
+
+Cluster = TypeVar("Cluster", bound=ClusterABC)
+MachinesRepresentation = TypeVar("MachinesRepresentation")
+JobsRepresentation = TypeVar("JobsRepresentation")
+
+
+@runtime_checkable
+class BaseClusterObservation(Protocol[MachinesRepresentation, JobsRepresentation]):
+    """Protocol ensuring dict-like access with specific required keys"""
+
+    @overload
+    def __getitem__(self, key: Literal["machines"]) -> MachinesRepresentation: ...
+    @overload
+    def __getitem__(self, key: Literal["jobs_usage"]) -> JobsRepresentation: ...
+    @overload
+    def __getitem__(self, key: Literal["jobs_status"]) -> npt.ArrayLike: ...
+    @overload
+    def __getitem__(self, key: Literal["current_tick"]) -> npt.ArrayLike: ...
+    def __getitem__(self, key: str) -> object: ...
+
+
+ClusterObservation = TypeVar("ClusterObservation", bound=BaseClusterObservation)
+
+
+class BaseObservationCreatorProtocol(Protocol[Cluster, ClusterObservation]):
+    _machines_convertor: MachinesCollectionConvertor
+    _jobs_convertor: JobCollectionConvertor
+
+    @abc.abstractmethod
+    def create(self, cluster: Cluster) -> ClusterObservation: ...
+
+    @abc.abstractmethod
+    def create_space(self, cluster: Cluster) -> gym.Space: ...

src/envs/cluster_simulator/base/extractors/reward.py

@@ -0,0 +1,29 @@
+from typing import Generic
+import abc
+
+from src.envs.cluster_simulator.base.internal.job import Status
+from src.envs.cluster_simulator.base.extractors.information import ClusterInformation
+
+
+class RewardCaculator(Generic[ClusterInformation]):
+    @abc.abstractmethod
+    def __call__(
+        self,
+        prev_extra_information: ClusterInformation,
+        current_extra_information: ClusterInformation,
+    ) -> float: ...
+
+
+class DifferentInPendingJobsRewardCaculator(RewardCaculator[ClusterInformation]):
+    def __call__(
+        self,
+        prev_extra_information: ClusterInformation,
+        current_extra_information: ClusterInformation,
+    ) -> float:
+        prev_not_pending_jobs_count = sum(
+            s != Status.Pending for s in prev_extra_information["jobs_status"]
+        )
+        current_not_pending_jobs_count = sum(
+            s != Status.Pending for s in current_extra_information["jobs_status"]
+        )
+        return current_not_pending_jobs_count - prev_not_pending_jobs_count

src/envs/cluster_simulator/base/internal/cluster.py

@@ -0,0 +1,137 @@
+import typing as tp
+import abc
+
+from rust_enum import enum, Case
+
+from src.envs.cluster_simulator.base.internal.job import Job, JobCollection
+from src.envs.cluster_simulator.base.internal.job import Status as JobStatus
+from src.envs.cluster_simulator.base.internal.machine import Machine, MachineCollection
+import logging
+
+T = tp.TypeVar("T")
+
+Machines = tp.TypeVar("Machines", bound=MachineCollection)
+Jobs = tp.TypeVar("Jobs", bound=JobCollection)
+
+
+@enum
+class ClusterAction:
+    SkipTime = Case()
+    Schedule = Case(machine=int, job=int)
+
+
+class ClusterABC(tp.Generic[Machines, Jobs], abc.ABC):
+    @abc.abstractmethod
+    def workload_creator(self, seed: tp.Optional[tp.SupportsFloat] = None) -> Jobs: ...
+
+    @abc.abstractmethod
+    def machine_creator(
+        self, seed: tp.Optional[tp.SupportsFloat] = None
+    ) -> Machines: ...
+
+    @abc.abstractmethod
+    def is_allocation_possible(self, machine: Machine[T], job: Job[T]) -> bool: ...
+
+    @abc.abstractmethod
+    def allocation(self, machine: Machine[T], job: Job[T]) -> None: ...
+
+    def __init__(self, seed: tp.Optional[tp.SupportsFloat]):
+        self._current_tick = 0
+        self._machines = self.machine_creator(seed)
+        self._jobs = self.workload_creator(seed)
+        self._jobs.execute_clock_tick(self._current_tick)
+        self._running_job_to_machine: dict[int, int] = {}
+        self.logger = logging.getLogger(type(self).__name__)
+
+    @property
+    def n_jobs(self) -> int:
+        return len(self._jobs)
+
+    @property
+    def n_machines(self) -> int:
+        return len(self._machines)
+
+    def has_completed(self) -> bool:
+        n_none_finished_jobs = sum(
+            job.status != JobStatus.Completed for job in self._jobs
+        )
+        self.logger.debug("Number of none completed jobs: %d", n_none_finished_jobs)
+        return n_none_finished_jobs == 0
+
+    def are_all_jobs_executed(self) -> bool:
+        arent_executed_jobs = sum(
+            job.status in (JobStatus.NotCreated, JobStatus.Pending)
+            for job in self._jobs
+        )
+        self.logger.debug("Number of none completed jobs: %d", arent_executed_jobs)
+        return arent_executed_jobs == 0
+
+    def schedule(self, m_idx: int, j_idx: int) -> bool:
+        job = self._jobs[j_idx]
+        machine = self._machines[m_idx]
+
+        if job.status != JobStatus.Pending:
+            self.logger.warning(
+                "Invalid action: job %d has status '%s' (expected: 'Pending')",
+                j_idx,
+                job.status.name,
+            )
+            return False
+
+        if not self.is_allocation_possible(machine, job):
+            self.logger.warning(
+                "Schedule rejected: insufficient capacity | machine=%d job=%d",
+                m_idx,
+                j_idx,
+            )
+            return False
+
+        self.allocation(machine, job)
+        self.logger.info(
+            "Scheduling job %d on machine %d",
+            j_idx,
+            m_idx,
+        )
+        job.status = JobStatus.Running
+        job.run_time = 1  # Assume that if start running the in next one will finish
+        self._running_job_to_machine[m_idx] = j_idx
+        self.logger.debug(
+            "Running job %d on machine %d",
+            j_idx,
+            m_idx,
+        )
+        return True
+
+    def execute_clock_tick(self) -> None:
+        self.logger.info(
+            "Executing clock tick: %d → %d",
+            self._current_tick,
+            self._current_tick + 1,
+        )
+        self._current_tick += 1
+        self._jobs.execute_clock_tick(self._current_tick)
+        running_jobs = {
+            j_idx
+            for j_idx, job in enumerate(iter(self._jobs))
+            if job.status != JobStatus.Running
+        }
+        self._running_job_to_machine = {
+            k: v for k, v in self._running_job_to_machine.items() if k in running_jobs
+        }
+        self._machines.execute_clock_tick()
+
+    def reset(self, seed: tp.Optional[tp.SupportsFloat]) -> None:
+        self._current_tick = 0
+        self._jobs = self.workload_creator(seed)
+        self._machines.clean_and_reset(seed)
+
+    def execute(self, action: ClusterAction) -> tp.Optional[bool]:
+        match action:
+            case ClusterAction.SkipTime():
+                return self.execute_clock_tick()
+            case ClusterAction.Schedule(machine_idx, job_idx):
+                return self.schedule(machine_idx, job_idx)
+            case _:
+                raise RuntimeError(
+                    f"Provided command should be {ClusterAction.SkipTime.__class__} or {ClusterAction.Schedule.__class__} and not {type(action).__class__}"
+                )