piegy 1.1.2__py3-none-any.whl → 1.1.4__py3-none-any.whl

piegy/{model.py → simulation.py}

@@ -1,13 +1,13 @@
 '''
-Main Module of Stochastic Model
--------------------------------
+Main Module of Stochastic Simulation
+-------------------------------------------
 
-Contains all the necessary tools to build a model and run simulations based on Gillespie Algorithm.
+Contains all the necessary tools to build a model and run models based on Gillespie Algorithm.
 
 Classes:
 - patch:        (Private) Simulates a single patch in the N x M space. Assume no spatial structure within a patch.
                 All spatial movements are based on patches.
-- simulation:   Stores input parameters and data generated during simulation.
+- model:        Stores input parameters and data generated during simulation.
 
 
 Functions:
@@ -16,14 +16,14 @@ Functions:
 - find_event:               (Private) Pick a random event to happen.
 - make_signal_zero_flux:    (Private) Expand event index (return value of find_event) to a detailed signal, under zero-flux boundary condition.
 - make_signal_periodical:   (Private) Expand event index (return value of find_event) to a detailed signal, under periodical boundary condition.
-- single_init:              (Private) Initialize a single simulation. Meaning of 'single': see single_test and run.
-- single_test:              (Private) Run a single simulation.
-                            'single' means a single round of simulation. You can run many single rounds and then take the average --- that's done by <run> function.
-- run:                      Run multiple simulations and then take the average. All the simulation will use the same parameters.
+- single_init:              (Private) Initialize a single model. Meaning of 'single': see single_test and run.
+- single_test:              (Private) Run a single model.
+                            'single' means a single round of model. You can run many single rounds and then take the average --- that's done by <run> function.
+- run:                      Run multiple models and then take the average. All the model will use the same parameters.
                             Set a seed for reproducible results.
-- demo_model:               Returns a demo model (a simulation object).
+- demo_model:               Returns a demo model (a model object).
 
-NOTE: Only simulation class and run function are intended for direct usages.
+NOTE: Only model class and run function are intended for direct usages.
 '''
 
 
@@ -32,10 +32,10 @@ import numpy as np
 from timeit import default_timer as timer
 
 
-# data type used by simulation.U and simulation.V
+# data type used by model.U and model.V
 UV_DTYPE = 'float64'
 
-# data type used by simulation.U_pi and V_pi
+# data type used by model.U_pi and V_pi
 PI_DTYPE = 'float64'
 
 # data type for storing rates in single_test an single_init
@@ -122,7 +122,7 @@ class patch:
     
     def set_nb_pointers(self, nb):
         # nb is a list of pointers (point to patches)
-        # nb is passed from the simulation class
+        # nb is passed from the model class
         self.nb = nb
     
     
@@ -220,7 +220,7 @@ class patch:
 
     
     def change_popu(self, s):
-        # convert s (a signal, passed from simulation class) to a change in population
+        # convert s (a signal, passed from model class) to a change in population
         
         # s = 0, 1, 2 are for U
         # s = 0 for migration IN, receive an immigrant
@@ -251,23 +251,23 @@ class patch:
                 
 
 
-class simulation:
+class model:
     '''
-    Store simulation data and input parameters.
-    Initialize a simulation object to run simulations.
+    Store model data and input parameters.
+    Initialize a model object to run models.
 
     Public Class Functions:
 
         __init__:
-            Create a simulation object. Also initialize data storage.
+            Create a model object. Also initialize data storage.
 
         __str__:
-            Print simulation object in a nice way.
+            Print model object in a nice way.
 
         copy:
             Return a deep copy of self. Can choose whether to copy data as well. Default is to copy.
 
-        clear:
+        clear_data:
             clear all data stored, set U, V, U_pi, V_pi to zero arrays
 
         change_maxtime:
@@ -276,7 +276,7 @@ class simulation:
         set_seed:
             Set a new seed. 
 
-        compress:
+        compress_data:
             compress data by only storing average values
     '''
 
@@ -286,7 +286,7 @@ class simulation:
         
         self.N = N                      # int, N x M is spatial dimension
         self.M = M                      # int, can't be 1. If want to make 1D space, use N = 1. And this model doesn't work for 1x1 space (causes NaN)
-        self.maxtime = maxtime          # float or int, run simulation for how long time
+        self.maxtime = maxtime          # float or int, run model for how long time
         self.record_itv = record_itv        # float, record data every record_itv of time
         self.sim_time = sim_time        # int, run this many of rounds (of single_test)
         self.boundary = boundary        # bool, the N x M space have boundary or not (i.e., zero-flux (True) or periodical (False))
@@ -296,7 +296,7 @@ class simulation:
         self.print_pct = print_pct      # int, print how much percent is done, need to be non-zero
         self.seed = seed                # non-negative int, seed for random generator
         self.UV_dtype = UV_dtype        # what data type to store population, should be a float format. This value is passed to np.array. 
-                                        # Default is 'float32', use lower accuracy to reduce data size.
+                                        # Default is 'float64', use lower accuracy to reduce data size.
         self.pi_dtype = pi_dtype        # what data type to store payoff, should be a float format. This value is passed to np.array. 
                                         # Default is 'float64'
 
@@ -309,7 +309,7 @@ class simulation:
         self.data_empty = True                      # whether data storage bins are empty. model.run will refuse to run (raise error) if not empty.
         self.max_record = int(self.maxtime / self.record_itv)                         # int, how many data points to store sin total
         self.compress_itv = 1                       # int, intended to reduce size of data (if not 1). Updated by compress_data function
-                                                    # if set to an int, say 20, sim will take average over every 20 data points and save them as new data.
+                                                    # if set to an int, say 20, mod will take average over every 20 data points and save them as new data.
                                                     # May be used over and over again to recursively reduce data size. 
                                                     # Default is 1, not to take average.
         self.U = np.zeros((self.N, self.M, self.max_record), dtype = self.UV_dtype)      # N x M x max_record np.array, float32, stores population of U in every patch over tiem
@@ -373,7 +373,7 @@ class simulation:
    
 
     def __str__(self):
-        # print this sim in a nice format
+        # print this mod in a nice format
 
         self_str = ''
         self_str += 'N = ' + str(self.N) + '\n'
@@ -443,7 +443,7 @@ class simulation:
         if type(copy_data) != bool:
             raise TypeError('Please give a bool as argument: whether to copy data or not')
 
-        sim2 = simulation(N = self.N, M = self.M, maxtime = self.maxtime, record_itv = self.record_itv, sim_time = self.sim_time, boundary = self.boundary,
+        sim2 = model(N = self.N, M = self.M, maxtime = self.maxtime, record_itv = self.record_itv, sim_time = self.sim_time, boundary = self.boundary,
                           I = np.copy(self.I), X = np.copy(self.X), P = np.copy(self.P), 
                           print_pct = self.print_pct, seed = self.seed, UV_dtype = self.UV_dtype, pi_dtype = self.pi_dtype)
 
@@ -455,7 +455,7 @@ class simulation:
 
 
     def calculate_ave(self):
-        # get the average value over sim_time many simulations
+        # get the average value over sim_time many models
         if self.sim_time != 1:
             for i in range(self.N):
                 for j in range(self.M):
@@ -481,7 +481,7 @@ class simulation:
         self.seed = seed
 
 
-    def clear(self):
+    def clear_data(self):
         # clear all data stored, set all to 0
         self.init_storage()
 
@@ -500,7 +500,7 @@ class simulation:
         self.V_pi = np.copy(V_pi)
 
 
-    def compress(self, compress_itv = 5):
+    def compress_data(self, compress_itv = 5):
         # compress data by only storing average values
         
         if type(compress_itv) != int:
@@ -811,33 +811,33 @@ def nb_need_change(ni, signal):
 
 
 
-def single_init(sim, rng):
+def single_init(mod, rng):
     '''
     The first major function for the model.
     Initialize all variables and run 1 round, then pass variables and results to single_test.
 
     Input:
-        sim is a simulation object
+        mod is a model object
         rng is random number generator (np.random.default_rng), initialized by model.run
     '''
 
     #### Initialize Data Storage ####
 
-    world = [[patch(sim.I[i][j][0], sim.I[i][j][1], sim.X[i][j], sim.P[i][j]) for j in range(sim.M)] for i in range(sim.N)]  # N x M patches
-    patch_rates = np.zeros((sim.N, sim.M), dtype = RATES_DTYPE)  # every patch's sum-of-12-srates
-    sum_rates_by_row = np.zeros((sim.N), dtype = RATES_DTYPE)  # every row's sum-of-patch, i.e., sum of 12 * M rates in every row.
+    world = [[patch(mod.I[i][j][0], mod.I[i][j][1], mod.X[i][j], mod.P[i][j]) for j in range(mod.M)] for i in range(mod.N)]  # N x M patches
+    patch_rates = np.zeros((mod.N, mod.M), dtype = RATES_DTYPE)  # every patch's sum-of-12-srates
+    sum_rates_by_row = np.zeros((mod.N), dtype = RATES_DTYPE)  # every row's sum-of-patch, i.e., sum of 12 * M rates in every row.
     sum_rates = 0  # sum of all N x M x 12 rates
 
     signal = None
 
     nb_indices = None
-    if sim.boundary:
-        nb_indices = [[find_nb_zero_flux(sim.N, sim.M, i, j) for j in range(sim.M)] for i in range(sim.N)]
+    if mod.boundary:
+        nb_indices = [[find_nb_zero_flux(mod.N, mod.M, i, j) for j in range(mod.M)] for i in range(mod.N)]
     else:
-        nb_indices = [[find_nb_periodical(sim.N, sim.M, i, j) for j in range(sim.M)] for i in range(sim.N)]
+        nb_indices = [[find_nb_periodical(mod.N, mod.M, i, j) for j in range(mod.M)] for i in range(mod.N)]
         
-    for i in range(sim.N):
-        for j in range(sim.M):
+    for i in range(mod.N):
+        for j in range(mod.M):
             nb = []
             for k in range(4):
                 if nb_indices[i][j][k] != None:
@@ -853,13 +853,13 @@ def single_init(sim, rng):
     #### Begin Running ####
 
     # initialize payoff & natural death rates
-    for i in range(sim.N):
-        for j in range(sim.M):
+    for i in range(mod.N):
+        for j in range(mod.M):
             world[i][j].update_pi_k()
     
     # initialize migration rates & the rates list
-    for i in range(sim.N):
-        for j in range(sim.M):
+    for i in range(mod.N):
+        for j in range(mod.M):
             world[i][j].update_mig()
             # store rates & sum of rates
             patch_rates[i][j] = world[i][j].get_sum_rates()
@@ -875,10 +875,10 @@ def single_init(sim, rng):
     e0 = world[i0][j0].find_event(expected_sum - current_sum)
 
     # initialize signal
-    if sim.boundary:
+    if mod.boundary:
         signal = make_signal_zero_flux(i0, j0, e0)   # walls around world
     else:
-        signal = make_signal_periodical(sim.N, sim.M, i0, j0, e0)  # no walls around world
+        signal = make_signal_periodical(mod.N, mod.M, i0, j0, e0)  # no walls around world
     
     # change U&V based on signal
     for si in signal:
@@ -888,15 +888,15 @@ def single_init(sim, rng):
     time = (1 / sum_rates) * math.log(1 / rng.random())
     
     # record
-    if time > sim.record_itv:
-        record_index = int(time / sim.record_itv)
-        for i in range(sim.N):
-            for j in range(sim.M):
+    if time > mod.record_itv:
+        record_index = int(time / mod.record_itv)
+        for i in range(mod.N):
+            for j in range(mod.M):
                 for k in range(record_index):
-                    sim.U[i][j][k] += world[i][j].U
-                    sim.V[i][j][k] += world[i][j].V
-                    sim.U_pi[i][j][k] += world[i][j].U_pi
-                    sim.V_pi[i][j][k] += world[i][j].V_pi
+                    mod.U[i][j][k] += world[i][j].U
+                    mod.V[i][j][k] += world[i][j].V
+                    mod.U_pi[i][j][k] += world[i][j].U_pi
+                    mod.V_pi[i][j][k] += world[i][j].V_pi
                     # we simply add to that entry, and later divide by sim_time to get the average (division in run function)
     
     return time, world, nb_indices, patch_rates, sum_rates_by_row, sum_rates, signal
@@ -904,54 +904,54 @@ def single_init(sim, rng):
 
 
 
-def single_test(sim, front_info, end_info, update_sum_frequency, rng):
+def single_test(mod, front_info, end_info, update_sum_frequency, rng):
     '''
-    Runs a single simulation, from time = 0 to sim.maxtime.
+    Runs a single model, from time = 0 to mod.maxtime.
     run recursively calls single_test to get the average data. 
 
     Inputs:
-        sim:                    a simulation object, created by user and carries all parameters & storage bins.
+        sim:                    a model object, created by user and carries all parameters & storage bins.
         front_info, end_info:   passed by run to show messages, like the current round number in run. Not intended for direct usages.
-        update_sum_frequency:   re-calculate sums this many times in simulation. 
+        update_sum_frequency:   re-calculate sums this many times in model. 
                                 Our sums are gradually updated over time. So might have precision errors for large maxtime.
         rng:                    np.random.default_rng. Initialized by model.run
     '''
 
     # initialize helper variables
     # used to print progress, i.e., how much percent is done
-    one_time = sim.maxtime / max(100, update_sum_frequency) 
+    one_time = mod.maxtime / max(100, update_sum_frequency) 
     one_progress = 0
-    if sim.print_pct != None:
+    if mod.print_pct != None:
         # print progress, x%
         print(front_info +  ' 0%' + end_info, end = '\r')
-        one_progress = sim.maxtime * sim.print_pct / 100
+        one_progress = mod.maxtime * mod.print_pct / 100
     else:
-        one_progress = 2 * sim.maxtime     # not printing
+        one_progress = 2 * mod.maxtime     # not printing
 
     # our sums (sum_rates_by_row and sum_rates) are gradually updated over time. This may have precision errors for large maxtime.
     # So re-sum everything every some percentage of maxtime.
-    one_update_sum = sim.maxtime / update_sum_frequency
+    one_update_sum = mod.maxtime / update_sum_frequency
 
     current_time = one_time
     current_progress = one_progress
     current_update_sum = one_update_sum
 
-    max_record = int(sim.maxtime / sim.record_itv)
+    max_record = int(mod.maxtime / mod.record_itv)
 
     
     # initialize
-    time, world, nb_indices, patch_rates, sum_rates_by_row, sum_rates, signal = single_init(sim, rng)
-    record_index = int(time / sim.record_itv)
+    time, world, nb_indices, patch_rates, sum_rates_by_row, sum_rates, signal = single_init(mod, rng)
+    record_index = int(time / mod.record_itv)
     # record_time is how much time has passed since the last record
     # if record_time > record_itv:
     #    we count how many record_itvs are there in record_time, denote the number by multi_records
     #    then store the current data in multi_records number of cells in the list
     #    and subtract record_time by the multiple of record_itv, so that record_time < record_itv
-    record_time = time - record_index * sim.record_itv
+    record_time = time - record_index * mod.record_itv
 
     ### Large while loop ###
     
-    while time < sim.maxtime:
+    while time < mod.maxtime:
     
         # print progress & correct error of sum_rates
         if time > current_time:
@@ -959,12 +959,12 @@ def single_test(sim, front_info, end_info, update_sum_frequency, rng):
             current_time += one_time
             if time > current_progress:
                 # print progress
-                print(front_info +  ' ' + str(round(time / sim.maxtime * 100)) + '%' + end_info, end = '\r')
+                print(front_info +  ' ' + str(round(time / mod.maxtime * 100)) + '%' + end_info, end = '\r')
                 current_progress += one_progress
 
             if time > current_update_sum:
                 current_update_sum += one_update_sum
-                for i in range(sim.N):
+                for i in range(mod.N):
                     sum_rates_by_row[i] = sum(patch_rates[i])
                 sum_rates = sum(sum_rates_by_row)
 
@@ -1011,10 +1011,10 @@ def single_test(sim, front_info, end_info, update_sum_frequency, rng):
         e0 = world[i0][j0].find_event(expected_sum - current_sum)
 
         # make signal
-        if sim.boundary:
+        if mod.boundary:
             signal = make_signal_zero_flux(i0, j0, e0)
         else:
-            signal = make_signal_periodical(sim.N, sim.M, i0, j0, e0)
+            signal = make_signal_periodical(mod.N, mod.M, i0, j0, e0)
 
         # let the event happen
         for si in signal:
@@ -1026,91 +1026,91 @@ def single_test(sim, front_info, end_info, update_sum_frequency, rng):
         time += dt
         record_time += dt
     
-        if time < sim.maxtime:
+        if time < mod.maxtime:
             # if not exceeds maxtime
-            if record_time > sim.record_itv:
-                multi_records = int(record_time / sim.record_itv)
-                record_time -= multi_records * sim.record_itv
+            if record_time > mod.record_itv:
+                multi_records = int(record_time / mod.record_itv)
+                record_time -= multi_records * mod.record_itv
 
-                for i in range(sim.N):
-                    for j in range(sim.M):
+                for i in range(mod.N):
+                    for j in range(mod.M):
                         for k in range(record_index, record_index + multi_records):
-                            sim.U[i][j][k] += world[i][j].U
-                            sim.V[i][j][k] += world[i][j].V
-                            sim.U_pi[i][j][k] += world[i][j].U_pi
-                            sim.V_pi[i][j][k] += world[i][j].V_pi
+                            mod.U[i][j][k] += world[i][j].U
+                            mod.V[i][j][k] += world[i][j].V
+                            mod.U_pi[i][j][k] += world[i][j].U_pi
+                            mod.V_pi[i][j][k] += world[i][j].V_pi
                 record_index += multi_records
         else:
             # if already exceeds maxtime
-            for i in range(sim.N):
-                for j in range(sim.M):
+            for i in range(mod.N):
+                for j in range(mod.M):
                     for k in range(record_index, max_record):
-                        sim.U[i][j][k] += world[i][j].U
-                        sim.V[i][j][k] += world[i][j].V
-                        sim.U_pi[i][j][k] += world[i][j].U_pi
-                        sim.V_pi[i][j][k] += world[i][j].V_pi
+                        mod.U[i][j][k] += world[i][j].U
+                        mod.V[i][j][k] += world[i][j].V
+                        mod.U_pi[i][j][k] += world[i][j].U_pi
+                        mod.V_pi[i][j][k] += world[i][j].V_pi
 
     ### Large while loop ends ###
     
-    if sim.print_pct != None:
+    if mod.print_pct != None:
         print(front_info + ' 100%' + ' ' * 20, end = '\r')  # empty spaces to overwrite predicted runtime
 
 
 
 
-def run(sim, predict_runtime = False, message = ''):
+def run(mod, predict_runtime = False, message = ''):
     '''
-    Main function. Recursively calls single_test to run many simulations and then takes the average.
+    Main function. Recursively calls single_test to run many models and then takes the average.
 
     Inputs:
-    - sim is a simulation object.
+    - mod is a model object.
     - predict_runtime = False will not predict how much time still needed, set to True if you want to see.
     - message is used by some functions in figures.py to print messages.
     '''
 
-    if not sim.data_empty:
-        raise RuntimeError('sim has non-empty data')
+    if not mod.data_empty:
+        raise RuntimeError('mod has non-empty data')
     
     start = timer()   # runtime
 
-    sim.data_empty = False
-    rng = np.random.default_rng(sim.seed)
+    mod.data_empty = False
+    rng = np.random.default_rng(mod.seed)
     
     # passed to single_test to print progress
-    if sim.print_pct == 0:
-        sim.print_pct = 5    # default print_pct
+    if mod.print_pct == 0:
+        mod.print_pct = 5    # default print_pct
 
     update_sum_frequency = 4   # re-calculate sums this many times. See input desciption of single_test
     
-    ### simulations ###
+    ### models ###
     i = 0
     
-    while i < sim.sim_time:
+    while i < mod.sim_time:
         # use while loop so that can go backwards if got numerical issues
 
         end_info = ''
         if predict_runtime:
             if i > 0:
                 time_elapsed = timer() - start
-                pred_runtime = time_elapsed / i * (sim.sim_time - i)
+                pred_runtime = time_elapsed / i * (mod.sim_time - i)
                 end_info = ', ~' + str(round(pred_runtime, 2)) + 's left'
         
         front_info = ''
-        if sim.print_pct != None:
+        if mod.print_pct != None:
             front_info = message + 'round ' + str(i) + ':'
             print(front_info + ' ' * 30, end = '\r')  # the blank spaces are to overwrite percentages, e.g. 36 %
         
         try:
-            single_test(sim, front_info, end_info, update_sum_frequency, rng)
+            single_test(mod, front_info, end_info, update_sum_frequency, rng)
             i += 1
         except IndexError:
             update_sum_frequency *= 4
             print('Numerical issue at round ' + str(i) + '. Trying higher precision now. See doc if err repeats')
             # not increasing i: redo current round.
         
-    ### simulations end ###
+    ### models end ###
 
-    sim.calculate_ave()
+    mod.calculate_ave()
     
     stop = timer()
     print(' ' * 30, end = '\r')  # overwrite all previous prints
@@ -1122,14 +1122,14 @@ def run(sim, predict_runtime = False, message = ''):
 
 def demo_model():
     '''
-    Returns a demo model.simulation object
+    Returns a demo model.model object
     '''
 
     N = 10                  # Number of rows
     M = 10                  # Number of cols
     maxtime = 300           # how long you want the model to run
     record_itv = 0.1        # how often to record data.
-    sim_time = 1            # repeat simulation to reduce randomness
+    sim_time = 1            # repeat model to reduce randomness
     boundary = True         # boundary condition.
 
     # initial population for the N x M patches. 
@@ -1146,10 +1146,10 @@ def demo_model():
     UV_dtype = 'float32'    # data type for population
     pi_dyna = 'float64'    # data type for payoff
 
-    # create a simulation object
-    sim = simulation(N, M, maxtime, record_itv, sim_time, boundary, I, X, P, 
+    # create a model object
+    mod = model(N, M, maxtime, record_itv, sim_time, boundary, I, X, P, 
                             print_pct = print_pct, seed = seed, UV_dtype = UV_dtype, pi_dtype = pi_dyna)
     
-    return sim
+    return mod