sim-tools 0.4.0__tar.gz → 0.5.0__tar.gz

{sim_tools-0.4.0 → sim_tools-0.5.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.3
 Name: sim-tools
-Version: 0.4.0
+Version: 0.5.0
 Summary: Simulation Tools for Education and Practice
 Project-URL: Homepage, https://github.com/TomMonks/sim-tools
 Project-URL: Bug Tracker, https://github.com/TomMonks/sim-tools/issues
@@ -20,35 +20,56 @@ Requires-Dist: scikit-learn>=1.0.0
 Requires-Dist: scipy>=1.4.1
 Description-Content-Type: text/markdown
 
-# sim-tools: tools to support the simulation process in python.
+# `sim-tools`: tools to support the Discrete-Event Simulation process in python.
 
 [![Binder](https://mybinder.org/badge_logo.svg)](https://mybinder.org/v2/gh/TomMonks/sim-tools/HEAD)
 [![DOI](https://zenodo.org/badge/225608065.svg)](https://zenodo.org/badge/latestdoi/225608065)
 [![PyPI version fury.io](https://badge.fury.io/py/sim-tools.svg)](https://pypi.python.org/pypi/sim-tools/)
+[![Anaconda-Server Badge](https://anaconda.org/conda-forge/sim-tools/badges/version.svg)](https://anaconda.org/conda-forge/sim-tools)
+[![Anaconda-Server Badge](https://anaconda.org/conda-forge/sim-tools/badges/platforms.svg)](https://anaconda.org/conda-forge/sim-tools)
 [![Read the Docs](https://readthedocs.org/projects/pip/badge/?version=latest)](https://tommonks.github.io/sim-tools)
 [![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
 [![Python 3.10+](https://img.shields.io/badge/python-3.10+-blue.svg)](https://www.python.org/downloads/release/python-360+/)
 [![License: MIT](https://img.shields.io/badge/ORCID-0000--0003--2631--4481-brightgreen)](https://orcid.org/0000-0003-2631-4481)
 
-sim-tools is being developed to support simulation education and applied simulation research.  It is MIT licensed and freely available to practitioners, students and researchers via PyPi.  There is a longer term plan to make sim-tools available via conda-forge.
+
+`sim-tools` is being developed to support Discrete-Event Simulation (DES) education and applied simulation research.  It is MIT licensed and freely available to practitioners, students and researchers via [PyPi](https://pypi.org/project/sim-tools/) and [conda-forge](https://anaconda.org/conda-forge/sim-tools)
 
  # Vision for sim-tools
 
- 1. Deliver high quality reliable code for simulation education and practice with full documentation.
+ 1. Deliver high quality reliable code for DES education and practice with full documentation.
  2. Provide a simple to use pythonic interface.
- 3. To improve the quality of simulation education and encourage the use of best practice.
+ 3. To improve the quality of DES education using FOSS tools and encourage the use of best practice.
 
 # Features:
 
-1. Implementation of classic optimisation via Simulation procedures such as KN, KN++, OBCA and OBCA-m
+1. Implementation of classic Optimisation via Simulation procedures such as KN, KN++, OBCA and OBCA-m
 2. Distributions module that includes classes that encapsulate a random number stream, seed, and distribution parameters.
-3. Implementation of Thinning to sample from Non-stationary poisson processes in a discrete-event simulation
+3. Implementation of Thinning to sample from Non-stationary poisson processes in a DES.
+
+## Installation
+
+### Pip and PyPi
+
+```bash
+pip install sim-tools
+```
+
+### Conda-forge
+
+```bash
+conda install -c conda-forge sim-tools
+```
+
+### Binder
+
+[![Binder](https://mybinder.org/badge_logo.svg)](https://mybinder.org/v2/gh/TomMonks/sim-tools/HEAD)
+
 
-## Three simple ways to explore sim-tools
+## Learn how to use `sim-tools`
 
-1. `pip install sim-tools`
-2. Click on the launch-binder at the top of this readme. This will open example Jupyter notebooks in the cloud via Binder.
-3. Oneline documentation: https://tommonks.github.io/sim-tools
+* Online documentation: https://tommonks.github.io/sim-tools
+* Introduction to DES in python: https://health-data-science-or.github.io/simpy-streamlit-tutorial/
 
 ## Citation
 

{sim_tools-0.4.0 → sim_tools-0.5.0}/README.md

@@ -1,32 +1,53 @@
-# sim-tools: tools to support the simulation process in python.
+# `sim-tools`: tools to support the Discrete-Event Simulation process in python.
 
 [![Binder](https://mybinder.org/badge_logo.svg)](https://mybinder.org/v2/gh/TomMonks/sim-tools/HEAD)
 [![DOI](https://zenodo.org/badge/225608065.svg)](https://zenodo.org/badge/latestdoi/225608065)
 [![PyPI version fury.io](https://badge.fury.io/py/sim-tools.svg)](https://pypi.python.org/pypi/sim-tools/)
+[![Anaconda-Server Badge](https://anaconda.org/conda-forge/sim-tools/badges/version.svg)](https://anaconda.org/conda-forge/sim-tools)
+[![Anaconda-Server Badge](https://anaconda.org/conda-forge/sim-tools/badges/platforms.svg)](https://anaconda.org/conda-forge/sim-tools)
 [![Read the Docs](https://readthedocs.org/projects/pip/badge/?version=latest)](https://tommonks.github.io/sim-tools)
 [![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
 [![Python 3.10+](https://img.shields.io/badge/python-3.10+-blue.svg)](https://www.python.org/downloads/release/python-360+/)
 [![License: MIT](https://img.shields.io/badge/ORCID-0000--0003--2631--4481-brightgreen)](https://orcid.org/0000-0003-2631-4481)
 
-sim-tools is being developed to support simulation education and applied simulation research.  It is MIT licensed and freely available to practitioners, students and researchers via PyPi.  There is a longer term plan to make sim-tools available via conda-forge.
+
+`sim-tools` is being developed to support Discrete-Event Simulation (DES) education and applied simulation research.  It is MIT licensed and freely available to practitioners, students and researchers via [PyPi](https://pypi.org/project/sim-tools/) and [conda-forge](https://anaconda.org/conda-forge/sim-tools)
 
  # Vision for sim-tools
 
- 1. Deliver high quality reliable code for simulation education and practice with full documentation.
+ 1. Deliver high quality reliable code for DES education and practice with full documentation.
  2. Provide a simple to use pythonic interface.
- 3. To improve the quality of simulation education and encourage the use of best practice.
+ 3. To improve the quality of DES education using FOSS tools and encourage the use of best practice.
 
 # Features:
 
-1. Implementation of classic optimisation via Simulation procedures such as KN, KN++, OBCA and OBCA-m
+1. Implementation of classic Optimisation via Simulation procedures such as KN, KN++, OBCA and OBCA-m
 2. Distributions module that includes classes that encapsulate a random number stream, seed, and distribution parameters.
-3. Implementation of Thinning to sample from Non-stationary poisson processes in a discrete-event simulation
+3. Implementation of Thinning to sample from Non-stationary poisson processes in a DES.
+
+## Installation
+
+### Pip and PyPi
+
+```bash
+pip install sim-tools
+```
+
+### Conda-forge
+
+```bash
+conda install -c conda-forge sim-tools
+```
+
+### Binder
+
+[![Binder](https://mybinder.org/badge_logo.svg)](https://mybinder.org/v2/gh/TomMonks/sim-tools/HEAD)
+
 
-## Three simple ways to explore sim-tools
+## Learn how to use `sim-tools`
 
-1. `pip install sim-tools`
-2. Click on the launch-binder at the top of this readme. This will open example Jupyter notebooks in the cloud via Binder.
-3. Oneline documentation: https://tommonks.github.io/sim-tools
+* Online documentation: https://tommonks.github.io/sim-tools
+* Introduction to DES in python: https://health-data-science-or.github.io/simpy-streamlit-tutorial/
 
 ## Citation
 

sim_tools-0.5.0/sim_tools/__init__.py

@@ -0,0 +1,4 @@
+__version__ = '0.5.0'
+__author__ = 'Thomas Monks'
+
+from . import datasets, distributions, time_dependent, ovs

{sim_tools-0.4.0 → sim_tools-0.5.0}/sim_tools/distributions.py

@@ -169,70 +169,66 @@ class Lognormal(Distribution):
 
 
 class Normal(Distribution):
-    """
+    '''
     Convenience class for the normal distribution.
     packages up distribution parameters, seed and random generator.
 
-    Option to prevent negative samples by resampling
-
-    """
-
+    Use the minimum parameter to truncate the distribution
+    '''
     def __init__(
         self,
         mean: float,
         sigma: float,
-        allow_neg: Optional[bool] = True,
+        minimum: Optional[float] = None,
         random_seed: Optional[int] = None,
     ):
-        """
+        '''
         Constructor
-
+        
         Params:
         ------
         mean: float
             The mean of the normal distribution
-
+            
         sigma: float
             The stdev of the normal distribution
 
-        allow_neg: bool, optional (default=True)
-            False = resample on negative values
-            True = negative samples allowed.
-
+        minimum: float
+            Truncate the normal distribution to a minimum 
+            value.
+        
         random_seed: int, optional (default=None)
             A random seed to reproduce samples.  If set to none then a unique
             sample is created.
-        """
-        super().__init__(random_seed)
+        '''
+        self.rng = np.random.default_rng(seed=random_seed)
         self.mean = mean
         self.sigma = sigma
-        self.allow_neg = allow_neg
-
+        self.minimum = minimum
+        
     def sample(self, size: Optional[int] = None) -> float | np.ndarray:
-        """
+        '''
         Generate a sample from the normal distribution
-
+        
         Params:
         -------
         size: int, optional (default=None)
             the number of samples to return.  If size=None then a single
             sample is returned.
-        """
-        # initial sample
+        '''
         samples = self.rng.normal(self.mean, self.sigma, size=size)
 
-        # no need to check if neg allowed.
-        if self.allow_neg:
+        if self.minimum is None:
+            return samples
+        elif size is None:
+            return max(self.minimum, samples)
+        else:
+            # index of samples with negative value
+            neg_idx = np.where(samples < 0)[0]
+            samples[neg_idx] = self.minimum
             return samples
 
-        # repeatedly resample negative values
-        negs = np.where(samples < 0)[0]
-        while len(negs) > 0:
-            resample = self.rng.normal(self.mean, self.sigma, size=len(negs))
-            samples[negs] = resample
-            negs = np.where(samples < 0)[0]
 
-        return samples
 
 
 class Uniform(Distribution):

{sim_tools-0.4.0 → sim_tools-0.5.0}/sim_tools/time_dependent.py

@@ -58,6 +58,7 @@ class NSPPThinning:
         self.arr_rng = np.random.default_rng(random_seed1)
         self.thinning_rng = np.random.default_rng(random_seed2)
         self.lambda_max = data["arrival_rate"].max()
+        self.min_iat = data["mean_iat"].min()
         # assumes all other intervals are equal in length.
         self.interval = int(data.iloc[1]["t"] - data.iloc[0]["t"])
         self.rejects_last_sample = None
@@ -94,7 +95,7 @@ class NSPPThinning:
             # reject samples if u >= lambda_t / lambda_max
             while u >= (lambda_t / self.lambda_max):
                 self.rejects_last_sample += 1
-                interarrival_time += self.arr_rng.exponential(1 / self.lambda_max)
+                interarrival_time += self.arr_rng.exponential(self.min_iat)
                 u = self.thinning_rng.uniform(0.0, 1.0)
 
             return interarrival_time

sim_tools-0.5.0/sim_tools/trace.py

@@ -0,0 +1,95 @@
+"""
+Simple functionality aiming to enhanced a users a
+ability to trace and debug simulation models.
+"""
+
+from abc import ABC
+from rich.console import Console
+
+DEFAULT_DEBUG = False
+
+CONFIG_ERROR = ("Your trace has not been initialised. " 
+                "Call super__init__(debug=True) in class initialiser" 
+                "or omit debug for default of no trace.")
+
+
+## single rich console - module level.
+_console = Console()
+
+class Traceable(ABC):
+    '''Provides basic trace functionality for a process to subclass
+    
+    Abstract base class Traceable
+    
+    Subclasses must call 
+    
+    super().__init__(debug=True) in their __init__() method to 
+    initialise trace.
+    
+    Subclasses inherit the following methods:
+
+    trace() - use this function print out a traceable event
+
+    _trace_config(): use this function to return a dict containing
+    the trace configuration for the class.
+    '''
+    def __init__(self, debug=DEFAULT_DEBUG):
+        self.debug = debug
+        self._config = self._default_config()
+    
+    def _default_config(self):
+        """Returns a default trace configuration"""
+        config = {
+            "name":None, 
+            "name_colour":"bold blue", 
+            "time_colour":'bold blue', 
+            "time_dp":2,
+            "message_colour":'black',
+            "tracked":None
+        }
+        return config
+        
+    
+    def _trace_config(self):
+        config = {
+            "name":None, 
+            "name_colour":"bold blue", 
+            "time_colour":'bold blue', 
+            "time_dp":2,
+            "message_colour":'black',
+            "tracked":None
+        }
+        return config
+    
+    
+    def trace(self, time, msg=None, process_id=None):
+        '''
+        Display a trace of an event
+        '''
+        
+        if not hasattr(self, '_config'):
+            raise AttributeError(CONFIG_ERROR)
+        
+        # if in debug mode
+        if self.debug:
+            
+            # check for override to default configs
+            process_config = self._trace_config()
+            self._config.update(process_config)
+            
+            # conditional logic to limit tracking to specific processes/entities
+            if self._config['tracked'] is None or process_id in self._config['tracked']:
+
+                # display and format time stamp
+                out = f"[{self._config['time_colour']}][{time:.{self._config['time_dp']}f}]:[/{self._config['time_colour']}]"
+                
+                # if provided display and format a process ID 
+                if self._config['name'] is not None and process_id is not None:
+                    out += f"[{self._config['name_colour']}]<{self._config['name']} {process_id}>: [/{self._config['name_colour']}]"
+
+                # format traced event message
+                out += f"[{self._config['message_colour']}]{msg}[/{self._config['message_colour']}]"
+
+                # print to rich console
+                _console.print(out)
+        

sim_tools-0.4.0/sim_tools/__init__.py

@@ -1,4 +0,0 @@
-__version__ = '0.4.0'
-__author__ = 'Thomas Monks'
-
-from . import datasets, distributions, time_dependent, ovs