Update queue theory and simulation modules

Author: xabarov

most_queue/__init__.py

@@ -0,0 +1,18 @@
+"""
+Most-Queue: A Python package for simulating and analyzing queueing systems.
+
+This package provides both simulation and numerical calculation methods
+for various types of queueing systems and networks.
+"""
+
+__version__ = "2.05"
+
+# Import main simulation and theory classes for easy access
+from most_queue.sim.base import QsSim
+from most_queue.theory.base_queue import BaseQueue
+
+__all__ = [
+    "QsSim",
+    "BaseQueue",
+    "__version__",
+]

most_queue/constants.py

@@ -0,0 +1,22 @@
+"""
+Constants used throughout the most_queue package.
+"""
+
+# Default number of states for simulation
+DEFAULT_NUM_STATES: int = 100000
+
+# Default number of jobs for simulation
+DEFAULT_NUM_JOBS: int = 1000000
+
+# Default number of probabilities to calculate
+DEFAULT_P_NUM: int = 1000
+
+# Numerical tolerances
+DEFAULT_TOLERANCE: float = 1e-12
+LSTSQ_RCOND: float = 1e-8  # rcond parameter for numpy.linalg.lstsq
+
+# Maximum iterations for fitting algorithms
+MAX_FIT_ITERATIONS: int = 10000
+
+# Default number of dots for approximation
+DEFAULT_DOTS_NUM: int = 10000

most_queue/random/utils/fit.py

@@ -8,6 +8,7 @@
 
 import numpy as np
 
+from most_queue.constants import MAX_FIT_ITERATIONS
 from most_queue.random.utils.params import (
     Cox2Params,
     ErlangParams,
@@ -60,7 +61,7 @@ def fit_h2(moments: list[float]) -> H2Params:
         res = H2Params(p1=q_max, mu1=mu1, mu2=1e6)
         return res
 
-    max_iteration = 10000
+    max_iteration = MAX_FIT_ITERATIONS
     tec = 0
     t1 = 0
     t2 = 0

most_queue/sim/__init__.py

@@ -0,0 +1,10 @@
+"""
+Simulation methods for queueing systems.
+
+This module contains discrete-event simulation implementations for
+various types of queueing systems and networks.
+"""
+
+from most_queue.sim.base import QsSim
+
+__all__ = ["QsSim"]

most_queue/sim/base.py

@@ -8,6 +8,7 @@
 from colorama import Fore, Style, init
 from tqdm import tqdm
 
+from most_queue.constants import DEFAULT_NUM_STATES
 from most_queue.random.utils.create import create_distribution
 from most_queue.random.utils.load import calc_qs_load
 from most_queue.sim.utils.qs_queue import QsQueueDeque, QsQueueList
@@ -39,7 +40,7 @@ def __init__(self, num_of_channels, buffer=None, verbose=True, buffer_type="list
         self.generator = np.random.default_rng()
 
         self.free_channels = self.n
-        self.num_of_states = 100000
+        self.num_of_states = DEFAULT_NUM_STATES
         self.load = 0  # utilization factor
 
         # to track the length of the continuous channel occupancy period:
@@ -131,11 +132,13 @@ def set_servers(self, params, kendall_notation: str = "M"):
             for _i in range(self.n)
         ]
 
-    def calc_load(self):
-        """
-        Calculates the load factor of the QS
+    def calc_load(self) -> float:
         """
+        Calculates the load factor (utilization) of the queueing system.
 
+        Returns:
+            float: The utilization factor (load) of the system, between 0 and 1.
+        """
         return calc_qs_load(
             self.source_kendall_notation,
             self.source_params,
@@ -144,9 +147,13 @@ def calc_load(self):
             self.n,
         )
 
-    def send_task_to_channel(self, is_warm_start=False, tsk=None):
+    def send_task_to_channel(self, is_warm_start: bool = False, tsk=None) -> None:
         """
-        Sends a job to the service channel
+        Sends a job to an available service channel.
+
+        Args:
+            is_warm_start: Whether this is a warm start scenario.
+            tsk: Task to send. If None, a new task is created.
         """
 
         if tsk is None:
@@ -169,9 +176,13 @@ def send_task_to_channel(self, is_warm_start=False, tsk=None):
 
                 break
 
-    def send_task_to_queue(self, new_tsk=None):
+    def send_task_to_queue(self, new_tsk=None) -> None:
         """
-        Send Task to Queue
+        Send a task to the queue.
+
+        Args:
+            new_tsk: Task to add to queue. If None, a new task is created.
+                    If buffer is full, the task will be dropped.
         """
 
         if new_tsk is None:
@@ -188,9 +199,13 @@ def send_task_to_queue(self, new_tsk=None):
                 self.dropped += 1
                 self.in_sys -= 1
 
-    def arrival(self, moment=None, ts=None):
+    def arrival(self, moment: float | None = None, ts=None) -> None:
         """
-        Actions upon arrival of the job by the QS.
+        Handle job arrival event in the queueing system.
+
+        Args:
+            moment: Optional specific arrival moment. If None, uses current arrival_time.
+            ts: Optional task object. If None, a new task is created.
         """
 
         self.arrived += 1
@@ -215,9 +230,16 @@ def arrival(self, moment=None, ts=None):
         else:  # there are free channels:
             self.send_task_to_channel(tsk=ts)
 
-    def serving(self, c, is_network=False):
+    def serving(self, c: int, is_network: bool = False):
         """
-        Actions upon receipt of a service job with - channel number
+        Handle service completion event for a channel.
+
+        Args:
+            c: Channel number that completed service.
+            is_network: Whether this is part of a network simulation.
+
+        Returns:
+            Task: The task that completed service.
         """
         time_to_end = self.servers[c].time_to_end_service
         end_ts = self.servers[c].end_service()
@@ -244,9 +266,13 @@ def serving(self, c, is_network=False):
 
         return end_ts
 
-    def send_head_of_queue_to_channel(self, channel_num, is_network=False):
+    def send_head_of_queue_to_channel(self, channel_num: int, is_network: bool = False) -> None:
         """
-        Send first Task (head of queue) to Channel
+        Send the first task from the queue (head) to an available channel.
+
+        Args:
+            channel_num: Channel number to send the task to.
+            is_network: Whether this is part of a network simulation.
         """
         que_ts = self.queue.pop()
 
@@ -262,9 +288,9 @@ def send_head_of_queue_to_channel(self, channel_num, is_network=False):
         self.servers[channel_num].start_service(que_ts, self.ttek)
         self.free_channels -= 1
 
-    def run_one_step(self):
+    def run_one_step(self) -> None:
         """
-        Run Open step of simulation
+        Execute one step of the simulation (either an arrival or service completion event).
         """
 
         num_of_server_earlier = -1
@@ -286,9 +312,15 @@ def run_one_step(self):
             # Arrival
             self.arrival()
 
-    def run(self, total_served) -> QueueResults:
+    def run(self, total_served: int) -> QueueResults:
         """
-        Run simulation process
+        Run the complete simulation process.
+
+        Args:
+            total_served: Number of jobs to serve before stopping the simulation.
+
+        Returns:
+            QueueResults: Results object containing statistics from the simulation.
         """
         start = time.process_time()
 
@@ -322,29 +354,40 @@ def run(self, total_served) -> QueueResults:
 
         return QueueResults(v=v, w=w, p=p, duration=self.time_spent, utilization=self.calc_load())
 
-    def refresh_busy_stat(self, new_a):
+    def refresh_busy_stat(self, new_a: float) -> None:
         """
-        Updating statistics of the busy period
+        Update statistics of the busy period.
+
+        Args:
+            new_a: New busy period duration to include in statistics.
         """
         self.busy = refresh_moments_stat(self.busy, new_a, self.busy_moments)
 
-    def refresh_v_stat(self, new_a):
+    def refresh_v_stat(self, new_a: float) -> None:
         """
-        Updating statistics of sojourn times
+        Update statistics of sojourn times.
+
+        Args:
+            new_a: New sojourn time value to include in statistics.
         """
         self.v = refresh_moments_stat(self.v, new_a, self.served)
 
-    def refresh_w_stat(self, new_a):
+    def refresh_w_stat(self, new_a: float) -> None:
         """
-        Updating statistics of wait times
+        Update statistics of wait times.
+
+        Args:
+            new_a: New waiting time value to include in statistics.
         """
         self.w = refresh_moments_stat(self.w, new_a, self.taked)
 
-    def get_p(self):
+    def get_p(self) -> list[float]:
         """
-        Returns a list with probabilities of QS states
-        p[j] - the probability that there will be exactly j jobs
-        in the QS at a random moment in time
+        Returns a list with probabilities of queueing system states.
+
+        Returns:
+            list[float]: List where p[j] is the probability that there will be exactly j jobs
+                        in the system at a random moment in time.
         """
         res = [0.0] * len(self.p)
         for j in range(0, self.num_of_states):

most_queue/sim/flow_sum.py

@@ -7,6 +7,7 @@
 
 from tqdm import tqdm
 
+from most_queue.constants import DEFAULT_NUM_JOBS
 from most_queue.random.distributions import (
     ErlangDistribution,
     GammaDistribution,
@@ -21,7 +22,7 @@ class FlowSumSim:
     """
 
     def __init__(
-        self, a, distr="Gamma", verbose=True, num_of_moments=4, num_of_jobs=1000000
+        self, a, distr="Gamma", verbose=True, num_of_moments=4, num_of_jobs=DEFAULT_NUM_JOBS
     ):  # pylint: disable=too-many-positional-arguments, too-many-arguments
         self.n = len(a)
         self.a = a
@@ -102,7 +103,7 @@ def sum_flows(self):
         self.result_flow = self.a[0]
 
     @staticmethod
-    def sum_2_H2_flows(a1, a2, num_of_moments=4, num_of_sim=1000000):
+    def sum_2_H2_flows(a1, a2, num_of_moments=4, num_of_sim=DEFAULT_NUM_JOBS):
         """
         суммирование двух потоков c коэффициентами вариации > 1
         Аппроксимация H2-распределением
@@ -151,7 +152,7 @@ def get_cv(a: list[complex]):
         return cv
 
     @staticmethod
-    def sum_2_Pa_flows(a1, a2, num_of_moments=4, num_of_sim=1000000):
+    def sum_2_Pa_flows(a1, a2, num_of_moments=4, num_of_sim=DEFAULT_NUM_JOBS):
         """
         суммирование двух потоков
         Аппроксимация Pa-распределением
@@ -191,7 +192,7 @@ def sum_2_Pa_flows(a1, a2, num_of_moments=4, num_of_sim=1000000):
         return f
 
     @staticmethod
-    def sum_2_Erlang_flows(a1, a2, num_of_moments=4, num_of_sim=1000000):
+    def sum_2_Erlang_flows(a1, a2, num_of_moments=4, num_of_sim=DEFAULT_NUM_JOBS):
         """
         Summing two Erlang flows with parameters a1 and a2.
         num_of_moments: number of moments to calculate.
@@ -230,7 +231,7 @@ def sum_2_Erlang_flows(a1, a2, num_of_moments=4, num_of_sim=1000000):
         return f
 
     @staticmethod
-    def sum_2_Gamma_flows(a1, a2, num_of_moments=4, num_of_sim=1000000):
+    def sum_2_Gamma_flows(a1, a2, num_of_moments=4, num_of_sim=DEFAULT_NUM_JOBS):
         """
         суммирование двух потоков c коэффициентами вариации > 1
         Аппроксимация H2-распределением

most_queue/sim/networks/base_network_sim.py

@@ -3,6 +3,7 @@
 """
 
 from abc import ABC, abstractmethod
+from typing import Any
 
 from most_queue.structs import NetworkResults, NetworkResultsPriority
 
@@ -22,24 +23,26 @@ def __init__(self):
         self.results: NetworkResults | NetworkResultsPriority | None = None
 
     @abstractmethod
-    def set_sources(self):  # pylint: disable=arguments-differ
+    def set_sources(self, *args: Any, **kwargs: Any) -> None:  # pylint: disable=arguments-differ
         """
         Set sources for the queueing network. This method should be implemented by subclasses.
         :param args: arguments for setting sources
+        :param kwargs: keyword arguments for setting sources
 
         After setting the sources, self.is_sources_set should be True.
         """
 
     @abstractmethod
-    def set_nodes(self):  # pylint: disable=arguments-differ
+    def set_nodes(self, *args: Any, **kwargs: Any) -> None:  # pylint: disable=arguments-differ
         """
-        Set servers for the queueing network. This method should be implemented by subclasses.
-        :param args: arguments for setting servers
+        Set nodes for the queueing network. This method should be implemented by subclasses.
+        :param args: arguments for setting nodes
+        :param kwargs: keyword arguments for setting nodes
 
-        After setting the servers, self.is_servers_set should be True.
+        After setting the nodes, self.is_nodes_set should be True.
         """
 
-    def _check_sources_and_nodes_is_set(self):
+    def _check_sources_and_nodes_is_set(self) -> None:
         """
         Check if sources and nodes are set.
         Raises:
@@ -54,7 +57,12 @@ def _check_sources_and_nodes_is_set(self):
             error_msg += "\nPlease use set_nodes() method."
             raise ValueError(error_msg)
 
-    def _check_if_results_calculated(self):
+    def _check_if_results_calculated(self) -> None:
+        """
+        Check if results have been calculated.
+        Raises:
+            ValueError: If results have not been calculated yet.
+        """
         if self.results is None:
             error_msg = "Results have not been calculated yet."
             error_msg += "For calculating results, use run() method."

most_queue/sim/priority.py

@@ -9,6 +9,7 @@
 from colorama import Fore, Style, init
 from tqdm import tqdm
 
+from most_queue.constants import DEFAULT_NUM_STATES
 from most_queue.random.utils.create import create_distribution
 from most_queue.sim.utils.servers import ServerPriority
 from most_queue.sim.utils.tasks import TaskPriority
@@ -48,7 +49,7 @@ def __init__(self, num_of_channels, num_of_classes, prty_type="No", buffer=None)
         self.buffer = buffer
         self.prty_type = prty_type
         self.free_channels = self.n
-        self.num_of_states = 100000
+        self.num_of_states = DEFAULT_NUM_STATES
         self.load = 0  # load factor of the system
 
         # for tracking the duration of continuous busy periods of channels: