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

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.3
 Name: sim-tools
-Version: 0.4.0
+Version: 0.6.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.6.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.6.0/sim_tools/__init__.py

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

{sim_tools-0.4.0 → sim_tools-0.6.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.6.0/sim_tools/time_dependent.py

@@ -0,0 +1,266 @@
+"""
+Classes and functions to support time dependent samplingm in DES models.
+"""
+
+import itertools
+import numpy as np
+import pandas as pd
+import matplotlib.pyplot as plt
+
+from typing import Optional, Tuple
+
+
+class NSPPThinning:
+    """
+    Non Stationary Poisson Process via Thinning.
+
+    Thinning is an acceptance-rejection approach to sampling
+    inter-arrival times (IAT) from a time dependent distribution
+    where each time period follows its own exponential distribution.
+
+    There are two random variables employed in sampling: an exponential
+    distribution (used to sample IAT) and a uniform distibution (used
+    to accept/reject samples).
+
+    All IATs are sampled from an Exponential distribution with the highest
+    arrival rate (most frequent). These arrivals are then rejected (thinned)
+    proportional to the ratio of the current arrival rate to the maximum
+    arrival rate.  The algorithm executes until a sample is accepted. The IAT
+    returned is the sum of all the IATs that were sampled.
+
+    """
+
+    def __init__(
+        self,
+        data,
+        random_seed1: Optional[int] = None,
+        random_seed2: Optional[int] = None,
+    ):
+        """
+        Non Stationary Poisson Process via Thinning.
+
+        Time dependency is handled for a single table
+        consisting of equally spaced intervals.
+
+        Params:
+        ------
+        data: pandas.DataFrame
+            list of time points during a period for transition between rates
+            and list arrival rates in that period. Labels should be "t"
+            and "arrival_rate" respectively.
+
+        random_seed1: int, optional (default=None)
+            Random seed for exponential distribution
+
+        random_seed2: int
+            Random seed for the uniform distribution used
+            for acceptance/rejection sampling.
+        """
+        self.data = data
+        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
+
+    def sample(self, simulation_time: float) -> float:
+        """
+        Run a single iteration of acceptance-rejection
+        thinning alg to sample the next inter-arrival time
+
+        Params:
+        ------
+        simulation_time: float
+            The current simulation time.  This is used to look up
+            the arrival rate for the time period.
+
+        Returns:
+        -------
+        float
+            The inter-arrival time
+        """
+        for _ in itertools.count():
+            # this gives us the index of dataframe to use
+            t = int(simulation_time // self.interval) % len(self.data)
+            lambda_t = self.data["arrival_rate"].iloc[t]
+
+            # set to a large number so that at least 1 sample taken!
+            u = np.inf
+
+            # included for audit and tracking purposes.
+            self.rejects_last_sample = 0.0
+
+            interarrival_time = 0.0
+
+            # 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(self.min_iat)
+                u = self.thinning_rng.uniform(0.0, 1.0)
+
+            return interarrival_time
+
+
+def nspp_simulation(
+    arrival_profile: pd.DataFrame,
+    run_length: Optional[float] = None,
+    n_reps: Optional[int] = 1000,
+) -> pd.DataFrame:
+    """
+    Generate a pandas dataframe that contains multiple replications of
+    a non-stationary poisson process for the set arrival profile.
+
+    This uses the sim-tools NSPPThinning class.
+
+    Useful for validating the the NSPP has been set up correctly and is producing the
+    desired profile for the simulation model.
+
+    On each replication the function counts the number of arrivals during the intervals
+    from the arrival profile.  Returns a data frame with reps (rows) and interval arrivals
+    (columns)
+
+    Parameters:
+    -----------
+    arrival_profile: pandas.DataFrame
+        The arrival profile is a pandas data frame containing 't', 'arrival_rate' and
+        'mean_iat' columns.
+
+    run_length: float, optional (default=None)
+        How long should the simulation be run. If none then uses the last value in 't'
+        + the interval (assumes equal width intervals)
+
+    n_reps: int, optional (default=1000)
+        The number of replications to run.
+
+    Returns:
+    --------
+    pd.DataFrame.
+
+
+    """
+    # replication results
+    replication_results = []
+
+    # multiple replications
+    for rep in range(n_reps):
+
+        # method for producing n non-overlapping streams
+        seed_sequence = np.random.SeedSequence(rep)
+
+        # Generate n high quality child seeds
+        seeds = seed_sequence.spawn(2)
+
+        # create nspp
+        nspp_rng = NSPPThinning(arrival_profile, seeds[0], seeds[1])
+
+        # if no run length has been set....
+        if run_length is None:
+            run_length = (
+                arrival_profile["t"].iloc[len(arrival_profile) - 1] + nspp_rng.interval
+            )
+
+        # list - each item is an interval in the arrival profile
+        interval_samples = [0] * arrival_profile.shape[0]
+        simulation_time = 0.0
+        while simulation_time < run_length:
+            iat = nspp_rng.sample(simulation_time)
+            simulation_time += iat
+
+
+            if simulation_time < run_length:
+                # data collection: add one to count for hour of the day
+                # note list NSPPThinning this assume equal intervals
+                interval_of_day = (
+                    int(simulation_time // nspp_rng.interval) % len(arrival_profile)
+                )
+                interval_samples[interval_of_day] += 1
+
+        replication_results.append(interval_samples)
+
+    # produce summary chart of arrivals per interval
+    # format in a dataframe
+    df_replications = pd.DataFrame(replication_results)
+    df_replications.index = np.arange(1, len(df_replications) + 1)
+    df_replications.index.name = "rep"
+
+    return df_replications
+
+
+def nspp_plot(
+    arrival_profile: pd.DataFrame,
+    run_length: Optional[float] = None,
+    n_reps: Optional[int] = 1000,
+) -> Tuple[plt.Figure, plt.Axes]:
+    """Generate a matplotlib chart to visualise a non-stationary poisson process
+    for the set arrival profile.
+
+    This uses the sim-tools NSPPThinning class.
+
+    Useful for validating the the NSPP has been set up correctly and is producing the
+    desired profile for the simulation model.
+
+    Parameters:
+    ----------
+    arrival_profile: pandas.DataFrame
+        The arrival profile is a pandas data frame containing 't', 'arrival_rate' and
+        'mean_iat' columns.
+
+    run_length: float, optional (default=None)
+        How long should the simulation be run. If none then uses the last value in 't'
+        + the interval (assumes equal width intervals)
+
+    n_reps: int, optional (default=1000)
+        The number of replications to run.
+    """
+
+    # verification of arrival_profile
+
+    # is it a dataframe
+    if not isinstance(arrival_profile, pd.DataFrame):
+        raise ValueError(
+            f"arrival_profile expected pd.DataFrame " f"got {type(arrival_profile)}"
+        )
+
+    # all columns are present
+    required_columns = ["t", "arrival_rate", "mean_iat"]
+    for col in required_columns:
+        if col not in arrival_profile.columns:
+            raise ValueError(
+                f"arrival_profile must contain "
+                f"the following columns: {required_columns}. "
+            )
+
+    # generate the sample data
+    df_interval_results = nspp_simulation(arrival_profile, run_length, n_reps)
+
+    interval_means = df_interval_results.mean(axis=0)
+    interval_sd = df_interval_results.std(axis=0)
+
+    upper = interval_means + interval_sd
+    lower = interval_means - interval_sd
+    lower[lower < 0] = 0
+
+    # visualise
+    fig = plt.figure(figsize=(12, 3))
+    ax = fig.add_subplot()
+
+    # chart x ticks
+    x_values = np.arange(0, arrival_profile.shape[0])
+
+    # plot in this case returns a 2D line plot object
+    _ = ax.plot(arrival_profile["t"], interval_means, label="Mean")
+    _ = ax.fill_between(arrival_profile["t"], lower, upper, alpha=0.2, label="+-1SD")
+
+    # chart appearance
+    _ = ax.legend(loc="best", ncol=3)
+    _ = ax.set_ylim(
+        0,
+    )
+    _ = ax.set_xlim(0, arrival_profile.shape[0] - 1)
+    _ = ax.set_ylabel("arrivals")
+    _ = ax.set_xlabel("interval (from profile)")
+    _ = plt.xticks(arrival_profile["t"])
+
+    return fig, ax

sim_tools-0.6.0/sim_tools/trace.py

@@ -0,0 +1,182 @@
+"""
+Simple functionality aiming to enhanced a users a
+ability to trace and debug simulation models.
+"""
+
+from abc import ABC
+from rich.console import Console
+from typing import Optional
+
+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.  Subclasses should
+    override it to implement custom formatting.
+
+    Notes:
+    -----
+    This class provides the same functionality as the function `trace()`
+    in an object orientated framework.  It in theory means cleaner code
+    as the call to trace requires less parameters.  However, it must
+    be setup correctly.
+    '''
+    def __init__(self, debug: Optional[bool] = DEFAULT_DEBUG):
+        """Initialise Traceable
+
+        Parameters:
+        ----------
+        debug: bool, Optional (default=False)
+            show trace(True). do not show trace (False)
+        """
+        self.debug = debug
+        self._config = Traceable._default_config()
+    
+    @classmethod
+    def _default_config(cls) -> dict:
+        """Returns a default trace configuration"""
+        config = {
+            "class":None, 
+            "class_colour":"bold blue", 
+            "time_colour":'bold blue', 
+            "time_dp":2,
+            "message_colour":'black',
+            "tracked":None
+        }
+        return config
+            
+    def _trace_config(self) -> dict:
+        """Overload to return a custom trace configuration"""
+        return Traceable._default_config()
+    
+    def trace(self, time: float, msg: Optional[str] = None, process_id: Optional[str] = None):
+        '''Display a formatted trace of a simulated event.
+
+        Implemented with the rich library Console() object.
+
+        Parameters:
+        ----------
+        time: float
+            The simulation time
+
+        msg: str, Optional (default=None)
+            Event message to display to user
+
+        process_id: str, Optional (default=None)
+            Display an unique identifer for the trace message 
+
+        '''
+        
+        # did not initialise trace
+        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['class'] is not None and process_id is not None:
+                    out += f"[{self._config['class_colour']}]<{self._config['class']} {process_id}>: [/{self._config['class_colour']}]"
+
+                # format traced event message
+                out += f"[{self._config['message_colour']}]{msg}[/{self._config['message_colour']}]"
+
+                # print to rich console
+                _console.print(out)
+
+
+def trace(time: float, debug: Optional[bool] = DEFAULT_DEBUG, msg: Optional[str] = None, 
+          identifier: Optional[str] = None, config: Optional[dict] = None):
+    """Display a formatted trace of a simulated event.
+
+    Implemented with the rich library Console() object.
+
+    Parameters:
+    ----------
+    time: float
+        The simulation time
+
+    debug: bool, Optional (default=False)
+        show trace(True). do not show trace (False)
+
+    msg: str, Optional (default=None)
+        Event message to display to user
+
+    identifier: str, Optional (default=None)
+        Display an unique identifier for the trace message 
+
+    config: dict, Optional (default=None)
+        If None then default colouring is applied to a message
+        Options (with corresponding defaults) include:
+
+            "name":None, 
+            "name_colour":"bold blue", 
+            "time_colour":'bold blue', 
+            "time_dp":2,
+            "message_colour":'black',
+            "tracked":None
+
+        Use tracked to only show trace for specific process IDs. 
+        For example if a process are labelled as integers from 
+        1 to n and we wished to track processes 5, 6 and 25. Then we would set
+        tracked = [1, 6, 25]
+
+    """
+
+    # get default and then update with user settings.
+    _config = Traceable._default_config()
+    if config is None:
+        _config['class'] = "event"
+    else:
+        # update with user settings.
+        _config.update(config)
+
+    # if in debug mode
+    if debug:
+        
+        # conditional logic to limit tracking to specific processes/entities
+        if _config['tracked'] is None or identifier in _config['tracked']:
+
+            # display and format time stamp
+            out = f"[{_config['time_colour']}][{time:.{_config['time_dp']}f}]:[/{_config['time_colour']}]"
+            
+            # if provided display and format a process ID 
+            if _config['class'] is not None and identifier is not None:
+                out += f"[{_config['class_colour']}]<{_config['class']} {identifier}>: [/{_config['class_colour']}]"
+
+            # format traced event message
+            out += f"[{_config['message_colour']}]{msg}[/{_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

sim_tools-0.4.0/sim_tools/time_dependent.py

@@ -1,100 +0,0 @@
-"""
-Classes and functions to support time dependent samplingm in DES models.
-"""
-
-import itertools
-import numpy as np
-
-from typing import Optional
-
-
-class NSPPThinning:
-    """
-    Non Stationary Poisson Process via Thinning.
-
-    Thinning is an acceptance-rejection approach to sampling
-    inter-arrival times (IAT) from a time dependent distribution
-    where each time period follows its own exponential distribution.
-
-    There are two random variables employed in sampling: an exponential
-    distribution (used to sample IAT) and a uniform distibution (used
-    to accept/reject samples).
-
-    All IATs are sampled from an Exponential distribution with the highest
-    arrival rate (most frequent). These arrivals are then rejected (thinned)
-    proportional to the ratio of the current arrival rate to the maximum
-    arrival rate.  The algorithm executes until a sample is accepted. The IAT
-    returned is the sum of all the IATs that were sampled.
-
-    """
-
-    def __init__(
-        self,
-        data,
-        random_seed1: Optional[int] = None,
-        random_seed2: Optional[int] = None,
-    ):
-        """
-        Non Stationary Poisson Process via Thinning.
-
-        Time dependency is handled for a single table
-        consisting of equally spaced intervals.
-
-        Params:
-        ------
-        data: pandas.DataFrame
-            list of time points during a period for transition between rates
-            and list arrival rates in that period. Labels should be "t"
-            and "arrival_rate" respectively.
-
-        random_seed1: int, optional (default=None)
-            Random seed for exponential distribution
-
-        random_seed2: int
-            Random seed for the uniform distribution used
-            for acceptance/rejection sampling.
-        """
-        self.data = data
-        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()
-        # assumes all other intervals are equal in length.
-        self.interval = int(data.iloc[1]["t"] - data.iloc[0]["t"])
-        self.rejects_last_sample = None
-
-    def sample(self, simulation_time: float) -> float:
-        """
-        Run a single iteration of acceptance-rejection
-        thinning alg to sample the next inter-arrival time
-
-        Params:
-        ------
-        simulation_time: float
-            The current simulation time.  This is used to look up
-            the arrival rate for the time period.
-
-        Returns:
-        -------
-        float
-            The inter-arrival time
-        """
-        for _ in itertools.count():
-            # this gives us the index of dataframe to use
-            t = int(simulation_time // self.interval) % len(self.data)
-            lambda_t = self.data["arrival_rate"].iloc[t]
-
-            # set to a large number so that at least 1 sample taken!
-            u = np.Inf
-
-            # included for audit and tracking purposes.
-            self.rejects_last_sample = 0.0
-
-            interarrival_time = 0.0
-
-            # 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)
-                u = self.thinning_rng.uniform(0.0, 1.0)
-
-            return interarrival_time