piegy 2.1.0__cp38-cp38-win32.whl

piegy/__init__.py

@@ -0,0 +1,56 @@
+'''
+Payoff-Driven Stochastic Spatial Model for Evolutionary Game Theory
+-----------------------------------------------------------------------------
+
+Provides:
+    1.  A stochastic spatial model for simulating the interaction and evolution of two species in either 1D or 2D space
+    2.  Plot & video functions to visualize simulation results.
+    3.  Module to test influence of certain variables on results.
+    4.  Data saving & reading module.
+    4.  Additional analytical tools.
+
+Websites:
+    - The *piegy* documentation: https://piegy.readthedocs.io/en/
+    - GitHub repository at: https://github.com/Chenning04/piegy.git
+    - PyPI page: https://pypi.org/project/piegy/
+
+
+Last update: May 12, 2025
+'''
+
+from .__version__ import __version__
+
+from .simulation import model, run, demo_model, UV_expected_val, check_overflow_func
+from .videos import make_video, SUPPORTED_FIGURES
+from .data_tools import save_data, read_data
+
+from .analysis import rounds_expected, scale_maxtime, check_convergence, combine_sim
+
+from .figures import (UV_heatmap, UV_bar, UV_dyna, UV_hist, UV_std, UV_expected, 
+                      pi_heatmap, pi_bar, pi_dyna, pi_hist, pi_std, UV_pi)
+
+from .test_var import (test_var1, var_UV1, var_pi1, var_convergence1, get_dirs1, 
+                       test_var2, var_UV2, var_pi2, var_convergence2, get_dirs2)
+
+
+simulation_memebers = ['model', 'run', 'demo_model']
+
+videos_members = ['make_video', 'SUPPORTED_FIGURES']
+
+data_members = ['save_data', 'read_data']
+
+analysis_members = ['expected_rounds', 'scale_maxtime', 'check_convergence', 'combine_mod']
+
+figures_members = ['UV_heatmap', 'UV_bar', 'UV_dyna', 'UV_hist', 'UV_std', 'UV_expected_val', 'UV_expected', 
+                   'pi_heatmap', 'pi_bar', 'pi_dyna', 'pi_hist', 'pi_std', 'UV_pi']
+
+test_var_members = ['test_var1', 'var_UV1', 'var_pi1', 'var_convergence1', 'get_dirs1', 
+                    'test_var2', 'var_UV2', 'var_pi2', 'var_convergence2', 'get_dirs2']
+
+
+__all__ = simulation_memebers + videos_members + data_members + figures_members + analysis_members + test_var_members
+
+
+
+
+

piegy/__version__.py

@@ -0,0 +1,31 @@
+__version__ = '2.1.0'
+
+'''
+version history:
+
+0.1.0: first publishing, May 11, 2025
+0.1.1: fix dependency errors
+0.1.2: fixing module not find error
+0.1.3: restructuring package
+0.1.4 ~ 0.1.6: fixing moviepy import issue
+0.1.7: changed name back to 'piegy'
+0.1.8: updated installation in README
+0.1.9: first round of full debugging
+
+1.0.0: first version in PyPI.
+1.1.0: debugging. Updated a range of functions, in the following modules: figures, videos, test_var, model, figure_tools
+1.1.1: minor debugging in model module.
+1.1.2: fix text bad location in figure_tools, update labeling and titling in figures and test_var. Add dpi param to make_video in videos. Remove reset_data function in model.
+1.1.3: update README.
+1.1.4: changed name: ``model`` module to ``simulation``, and ``model.simulation`` class to ``simulation.model``. Bug fix in videos.
+1.1.5: update README.
+1.1.6: change name of variables in model class -- for compatability with the new C core. 1.1.6 is the last verion of v1. From v2 on, the piegy package has C core.
+
+2.0.0: update simulation core to C-based.
+2.0.1: re-upload, the C core is not included in package.
+2.0.2: update version number in __version__.py and update README.
+2.0.3: speed boost & debugging in C core. Add check_overflow feature in simulation module, checks whether overflow/too large numbers might be encountered in simulation.
+2.0.4: minor debuggings.
+2.0.5: fix error in random number generator.
+2.1.0: redo random number generator. Update package upload so that more compatible across platforms.
+'''

piegy/analysis.py

@@ -0,0 +1,222 @@
+'''
+This file contains pre-processing, post-processing, and analytical tools for simulations.
+
+Public Funcions:
+- check_convergence:    Check whether a simulation result converges. i.e. whether U, V's fluctuation are very small.
+- combine_sim:          Combine two model objects and return a new one (the first two unchanged).
+                        Intended usage: say you have mod1, mod2 with same parameters except for sim_time, say 10 and 20.
+                                        Then combine_sim takes a weighted average (with ratio 1:2) of results and return a new sim3.
+                                        So that you now have sim3 with 30 sim_time.
+
+Private Functions:
+- rounds_expected:      Roughly calculates how many rounds are expected in a single simulation (which reflects runtime).
+                        NOTE: Not well-developed. Not recommending to use.
+- scale_maxtime:        Given two simulation objects, scale first one's maxtime towards the second, so that the two have the same expected rounds.
+                        Intended to possibly decrease maxtime and save runtime.
+                        NOTE: Not well-developed. Not recommending to use.
+
+'''
+
+from . import simulation as simulation
+from . import figures as figures
+from .tools import figure_tools as figure_t
+
+import numpy as np
+import math
+
+
+
+
+def rounds_expected(mod):
+    '''
+    NOTE: Not well-developed. Not recommending to use.
+
+    Predict how many rounds will run in single_test. i.e., how many for loops from time = 0 to mod.maxtime.
+    Calculated based on expected_UV. 
+    '''
+
+    N = mod.N
+    M = mod.M
+    U_expected, V_expected = figures.UV_expected_val(mod)
+
+    rates = []
+    patch0 = None  # simulate patch i, j
+    patch0_nb = []  # simulate neighbors of patch i, j
+    
+    # loop through N, M, create a sample patch to calculate rates, store them
+    for i in range(N):
+        for j in range(M):
+            patch0 = simulation.patch(U_expected[i][j], V_expected[i][j], mod.X[i][j], mod.P[i][j])
+
+            nb_indices = None
+            if mod.boundary:
+                nb_indices = simulation.find_nb_zero_flux(N, M, i, j)
+            else:
+                nb_indices = simulation.find_nb_periodical(N, M, i, j)
+            
+            for k in range(4):
+                if nb_indices[k] != None:
+                    i_nb = nb_indices[k][0]
+                    j_nb = nb_indices[k][1]
+                    patch0_nb_k = simulation.patch(U_expected[i_nb][j_nb], V_expected[i_nb][j_nb], mod.X[i_nb][j_nb], mod.P[i_nb][j_nb])
+                    patch0_nb_k.update_pi_k()
+                    patch0_nb.append(patch0_nb_k)
+
+                else:
+                    patch0_nb.append(None)
+
+            patch0.nb = patch0_nb
+            patch0.update_pi_k()
+            patch0.update_mig()
+
+            rates += patch0.pi_death_rates
+            rates += patch0.mig_rates
+    
+    delta_t_expected = (1 / sum(rates)) * math.log(1 / 0.5)
+    r_expected = round(mod.maxtime / delta_t_expected)
+
+    return r_expected
+
+
+
+
+def scale_maxtime(mod1, mod2, scale_interval = True):
+    '''
+    NOTE: Not well-developed. Not recommending to use.
+
+    Scale mod1's maxtime towards mod2's, so they will run similar number of rounds in single_test, and hence similar runtime.
+    Intended to reduce the effect of changing params on runtime. 
+    
+    Input:
+    - scale_interval decides whether to scale mod1's interval as well, so that the same number of data will be stored.
+    '''
+
+    r_expected1 = rounds_expected(mod1)
+    r_expected2 = rounds_expected(mod2)
+    ratio = r_expected2 / r_expected1
+
+    new_maxtime = mod1.maxtime * ratio
+    old_max_record = mod1.maxtime / mod1.interval
+
+    if scale_interval:
+        mod1.interval = new_maxtime / old_max_record
+
+    mod1.change_maxtime(new_maxtime)
+
+
+
+
+def check_convergence(mod, interval = 20, start = 0.8, fluc = 0.07):
+    '''
+    Check whether a simulation converges or not.
+    Based on whether the fluctuation of U, V, pi all < 'fluc' in the later 'tail' portion of time.
+    
+    Essentially find the max and min values (of population) in every small interval, and then check whether their difference > min * fluc.
+
+    Inputs:
+    - sim: a simulation.model object
+    - interval: int, how many records to take average over,
+                and then compare this "local mean" with "whole-tail mean" and expect the difference to be less than fluc.
+    - start: (0, 1) float, decides where you expect to check convergence from. Smaller start needs earlier convergence.
+    - fluc: (0, 1) float. How much fluctuation is allowed between the average value of a small interval and the mean.
+    '''
+
+    if (start < 0) or (start > 1):
+        raise ValueError("start should be a float in (0, 1)")
+    if (fluc < 0) or (fluc > 1):
+        raise ValueError("fluc should be a float in (0, 1)")
+    if (type(interval) != int) or (interval < 1):
+        raise ValueError("interval should be an int >= 1")
+    
+    interval = figure_t.scale_interval(interval, mod.compress_itv)
+
+    start_index = int(mod.max_record * start)  # where the tail starts
+    num_interval = int((mod.max_record - start_index) / interval)  # how many intervals in total
+
+    # find the max and min value of the small intervals 
+    # initiate as average of the first interval
+    min_U = np.mean(mod.U[:, :, start_index : start_index + interval])
+    max_U = np.mean(mod.U[:, :, start_index : start_index + interval])
+    min_V = np.mean(mod.V[:, :, start_index : start_index + interval])
+    max_V = np.mean(mod.V[:, :, start_index : start_index + interval])
+
+    for i in range(1, num_interval):
+        # lower and upper bound of current interval
+        lower = start_index + i * interval
+        upper = lower + interval
+
+        ave_U = np.mean(mod.U[:, :, lower : upper])
+        ave_V = np.mean(mod.V[:, :, lower : upper])
+
+        # Compare with min, max
+        if ave_U > max_U:
+            max_U = ave_U
+        if ave_U < min_U:
+            min_U = ave_U
+
+        if ave_V > max_V:
+            max_V = ave_V
+        if ave_V < min_V:
+            min_V = ave_V
+
+        # check whether (max - min) > min * fluc
+        if (max_U - min_U) > min_U * fluc:
+            return False
+        if (max_V - min_V) > min_V * fluc:
+            return False
+            
+    return True
+
+
+
+
+def combine_sim(mod1, mod2):
+    '''
+    Combine data of mod1 and mod2. 
+    Intended usage: assume mod1 and mod2 has the same N, M, maxtime, interval, boundary, max_record, and I, X, P
+    combine_sim then combines the two results and calculate a new weighted average of the two data, return a new sim object. 
+    Essentially allows breaking up many rounds of simulations into several smaller pieces, and then put together.
+
+    Inputs:
+    - mod1, mod2: both simulation.model objects. All input parameters the same except for sim_time, print_pct and seed.
+            Raises error if not.
+
+    Returns:
+
+    - sim3:     a new model object whose U, V, Upi, Vpi are weighted averages of mod1 and mod2
+                (weighted by sim_time). 
+                sim3.print_pct is set to mod1's, seed set to None, sim_time set to sum of mod1's and mod2's. All other params same as mod1
+    '''
+    if not (mod1.N == mod2.N and
+            mod1.M == mod2.M and
+            mod1.maxtime == mod2.maxtime and
+            mod1.record_itv == mod2.record_itv and
+            mod1.boundary == mod2.boundary and
+            mod1.max_record == mod2.max_record and
+            np.array_equal(mod1.I, mod2.I) and
+            np.array_equal(mod1.X, mod2.X) and
+            np.array_equal(mod1.P, mod2.P)):
+        
+        raise ValueError('mod1 and mod2 have different input parameters (N, M, maxtime, interval, boundary, max_record, or I, X, P).')
+
+    if mod1.seed == mod2.seed:
+        raise ValueError('Cannot combine two simulations with the same seed.')
+    
+    # copy mod1, except for no data and a different sim_time
+    combined_sim_time = mod1.sim_time + mod2.sim_time
+    sim3 = mod1.copy(copy_data = False)
+    sim3.sim_time = combined_sim_time
+    sim3.seed = None
+
+    for i in range(sim3.N):
+        for j in range(sim3.M):
+            for k in range(sim3.max_record):
+                sim3.U[i][j][k] = (mod1.U[i][j][k] * mod1.sim_time + mod2.U[i][j][k] * mod2.sim_time) / combined_sim_time
+                sim3.V[i][j][k] = (mod1.V[i][j][k] * mod1.sim_time + mod2.V[i][j][k] * mod2.sim_time) / combined_sim_time
+                sim3.Upi[i][j][k] = (mod1.Upi[i][j][k] * mod1.sim_time + mod2.Upi[i][j][k] * mod2.sim_time) / combined_sim_time
+                sim3.Vpi[i][j][k] = (mod1.Vpi[i][j][k] * mod1.sim_time + mod2.Vpi[i][j][k] * mod2.sim_time) / combined_sim_time
+
+    return sim3
+
+
+

piegy/data_tools.py

@@ -0,0 +1,127 @@
+'''
+Stores and reads a model object.
+
+Functions:
+- save_data:    save a model object.
+- read_data:    read a model object.
+'''
+
+
+from . import simulation
+
+import json
+import gzip
+import os
+
+
+def save_data(mod, dirs = '', print_msg = True):
+    '''
+    Saves a model object. Data will be stored at dirs/data.json.gz
+
+    Inputs:
+    - mod:        Your model object.
+    - dirs:       Where to save it.
+    - print_msg:  Whether to print message after saving.
+    '''
+
+    try:
+        _ = mod.N
+    except AttributeError:
+        raise ValueError('mod is not a model object')
+
+    if dirs != '':
+        # add slash '/'
+        if dirs[:-1] != '/':
+            dirs += '/'
+        if not os.path.exists(dirs):
+            os.makedirs(dirs)
+        
+    data = []
+    
+    inputs = []
+    inputs.append(mod.N)
+    inputs.append(mod.M)
+    inputs.append(mod.maxtime)
+    inputs.append(mod.record_itv)
+    inputs.append(mod.sim_time)
+    inputs.append(mod.boundary)
+    inputs.append(mod.I.tolist())
+    inputs.append(mod.X.tolist())
+    inputs.append(mod.P.tolist())
+    inputs.append(mod.print_pct)
+    inputs.append(mod.seed)
+    inputs.append(mod.check_overflow)
+    data.append(inputs)
+
+    # skipped rng
+    
+    outputs = []
+    outputs.append(mod.max_record)
+    outputs.append(mod.compress_itv)
+    outputs.append(mod.U.tolist())
+    outputs.append(mod.V.tolist())
+    outputs.append(mod.Upi.tolist())
+    outputs.append(mod.Vpi.tolist())
+    # H&Vpi_total are not saved, will be calculated when reading the data
+    data.append(outputs)
+    
+    data_json = json.dumps(data)
+    data_bytes = data_json.encode('utf-8')
+    data_dirs = dirs + 'data.json.gz'
+    
+    with gzip.open(data_dirs, 'w') as f:
+        f.write(data_bytes)
+    
+    if print_msg:
+        print('data saved: ' + data_dirs)
+
+
+
+def read_data(dirs):
+    '''
+    Reads and returns a model object.
+
+    Inputs:
+    - dirs:       where to read from, just provide the folder-subfolder names. Don't include 'data.json.gz'
+    - print_msg:  this function prints a message when the mod.compress_itv != None. Setting print_msg = False will skip ignore this message.
+
+    Returns:
+    - mod: a piegy.model.model object read from the data.
+    '''
+    
+    if dirs != '':
+        # add slash '/'
+        if dirs[:-1] != '/':
+            dirs += '/'
+        if not os.path.exists(dirs):
+            raise FileNotFoundError('dirs not found: ' + dirs)
+            
+    if not os.path.isfile(dirs + 'data.json.gz'):
+        raise FileNotFoundError('data not found in ' + dirs)
+    
+    with gzip.open(dirs + 'data.json.gz', 'r') as f:
+        data_bytes = f.read()
+    data_json = data_bytes.decode('utf-8')
+    data = json.loads(data_json)
+
+    # inputs
+    try:
+        mod = simulation.model(N = data[0][0], M = data[0][1], maxtime = data[0][2], record_itv = data[0][3],
+                            sim_time = data[0][4], boundary = data[0][5], I = data[0][6], X = data[0][7], P = data[0][8], 
+                            print_pct = data[0][9], seed = data[0][10], check_overflow = data[0][11])
+    except:
+        raise ValueError('Invalid input parameters saved in data')
+
+    # outputs
+    try:
+        mod.set_data(data_empty = False, max_record = data[1][0], compress_itv = data[1][1], 
+                    U = data[1][2], V = data[1][3], Upi = data[1][4], Vpi = data[1][5])
+    except:
+        raise ValueError('Invalid model results saved in data')
+    
+    return mod
+
+
+
+
+