piegy 1.0.0__py3-none-any.whl

piegy/__init__.py

@@ -0,0 +1,96 @@
+'''
+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 .model import simulation, run, demo_model
+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_val, 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)
+
+
+model_members = ['simulation', 'run', 'get_demo_model']
+
+videos_members = ['make_video', 'SUPPORTED_FIGURES']
+
+data_members = ['save_data', 'read_data']
+
+analysis_members = ['expected_rounds', 'scale_maxtime', 'check_convergence', 'combine_sim']
+
+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__ = model_members + videos_members + data_members + figures_members + analysis_members + test_var_members
+
+
+
+
+
+
+
+# Below might be better suited for documents
+'''
+To run a simulation, start by defining some parameter. Here is a complete set of params::
+
+    >>> N = 5
+    >>> M = 5
+    >>> maxtime = 300
+    >>> sim_time = 3
+    >>> I = [[[22, 44] for i in range(N)] for j in range(M)]
+    >>> X = [[[-0.1, 0.4, 0, 0.2] for i in range(N)] for j in range(M)]
+    >>> X[1][1] = [0.1, 0.6, 0.2, 0.4]
+    >>> P = [[[0.5, 0.5, 100, 100, 0.001, 0.001] for i in range(N)] for j in range(M)]
+    >>> boundary = True
+    >>> print_pct = 5
+    >>> seed = None
+
+These parameters essentially define the spatial size, initial population, payoff matrices...
+For a detailed explanation, see simulation object.
+
+Then create a 'simulation' object with those parameters::
+
+    >>> sim = simulation(N, M, maxtime, sim_time, I, X, P, boundary, print_pct, seed)
+
+This 'sim' object will be the basis of our simulation. It carries all the necessary parameters
+and storage bin for the results.
+
+Now let's run the simulation (assuming you imported)::
+
+    >>> multi_test(sim)
+
+And that's the simulation! It takes 30s ~ 1min. You can see the progress.
+
+Now, to see the results, let's use figures::
+
+    >>> fig = UV_heatmap(sim)
+    
+
+'''

piegy/__version__.py

@@ -0,0 +1,17 @@
+__version__ = '1.0.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
+
+'''

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 simulation objects and return a new one (the first two unchanged).
+                        Intended usage: say you have sim1, sim2 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 model as model
+from . import figures as figures
+from .tools import figure_tools as figure_t
+
+import numpy as np
+import math
+
+
+
+
+def rounds_expected(sim):
+    '''
+    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 sim.maxtime.
+    Calculated based on expected_UV. 
+    '''
+
+    N = sim.N
+    M = sim.M
+    U_expected, V_expected = figures.UV_expected_val(sim)
+
+    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 = model.patch(U_expected[i][j], V_expected[i][j], sim.X[i][j], sim.P[i][j])
+
+            nb_indices = None
+            if sim.boundary:
+                nb_indices = model.find_nb_zero_flux(N, M, i, j)
+            else:
+                nb_indices = model.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 = model.patch(U_expected[i_nb][j_nb], V_expected[i_nb][j_nb], sim.X[i_nb][j_nb], sim.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(sim.maxtime / delta_t_expected)
+
+    return r_expected
+
+
+
+
+def scale_maxtime(sim1, sim2, scale_interval = True):
+    '''
+    NOTE: Not well-developed. Not recommending to use.
+
+    Scale sim1's maxtime towards sim2'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 sim1's interval as well, so that the same number of data will be stored.
+    '''
+
+    r_expected1 = rounds_expected(sim1)
+    r_expected2 = rounds_expected(sim2)
+    ratio = r_expected2 / r_expected1
+
+    new_maxtime = sim1.maxtime * ratio
+    old_max_record = sim1.maxtime / sim1.interval
+
+    if scale_interval:
+        sim1.interval = new_maxtime / old_max_record
+
+    sim1.change_maxtime(new_maxtime)
+
+
+
+
+def check_convergence(sim, 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 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, sim.compress_itv)
+
+    start_index = int(sim.max_record * start)  # where the tail starts
+    num_interval = int((sim.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(sim.U[:, :, start_index : start_index + interval])
+    max_U = np.mean(sim.U[:, :, start_index : start_index + interval])
+    min_V = np.mean(sim.V[:, :, start_index : start_index + interval])
+    max_V = np.mean(sim.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(sim.U[:, :, lower : upper])
+        ave_V = np.mean(sim.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(sim1, sim2):
+    '''
+    Combine data of sim1 and sim2. 
+    Intended usage: assume sim1 and sim2 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:
+    - sim1, sim2: both stochastic_model.simulation object. All input parameters the same except for sim_time, print_pct and seed.
+            Raises error if not.
+
+    Returns:
+
+    - sim3:       a new simulation object whose U, V, U_pi, V_pi are weighted averages of sim1 and sim2
+                (weighted by sim_time). 
+                sim3.print_pct is set to sim1's, seed set to None, sim_time set to sum of sim1's and sim2's. All other params same as sim1
+    '''
+    if not (sim1.N == sim2.N and
+            sim1.M == sim2.M and
+            sim1.maxtime == sim2.maxtime and
+            sim1.record_itv == sim2.record_itv and
+            sim1.boundary == sim2.boundary and
+            sim1.max_record == sim2.max_record and
+            np.array_equal(sim1.I, sim2.I) and
+            np.array_equal(sim1.X, sim2.X) and
+            np.array_equal(sim1.P, sim2.P)):
+        
+        raise ValueError('sim1 and sim2 have different input parameters (N, M, maxtime, interval, boundary, max_record, or I, X, P).')
+
+    if sim1.seed == sim2.seed:
+        raise ValueError('Cannot combine two simulations with the same seed.')
+    
+    # copy sim1, except for no data and a different sim_time
+    combined_sim_time = sim1.sim_time + sim2.sim_time
+    sim3 = sim1.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] = (sim1.U[i][j][k] * sim1.sim_time + sim2.U[i][j][k] * sim2.sim_time) / combined_sim_time
+                sim3.V[i][j][k] = (sim1.V[i][j][k] * sim1.sim_time + sim2.V[i][j][k] * sim2.sim_time) / combined_sim_time
+                sim3.U_pi[i][j][k] = (sim1.U_pi[i][j][k] * sim1.sim_time + sim2.U_pi[i][j][k] * sim2.sim_time) / combined_sim_time
+                sim3.V_pi[i][j][k] = (sim1.V_pi[i][j][k] * sim1.sim_time + sim2.V_pi[i][j][k] * sim2.sim_time) / combined_sim_time
+
+    return sim3
+
+
+

piegy/data_tools.py

@@ -0,0 +1,129 @@
+'''
+Stores and reads a simulation object.
+
+Functions:
+- save_data:    save a simulation object.
+- read_data:    read a simulation object.
+'''
+
+
+from . import model as model
+
+import json
+import gzip
+import os
+
+
+def save_data(sim, dirs = '', print_msg = True):
+    '''
+    Saves a simulation object. Data will be stored at dirs/data.json.gz
+
+    Inputs:
+    - sim:        Your simulation object.
+    - dirs:       Where to save it.
+    - print_msg:  Whether to print message after saving.
+    '''
+
+    try:
+        _ = sim.N
+    except AttributeError:
+        raise ValueError('sim is not a simulation object')
+
+    if dirs != '':
+        # add slash '/'
+        if dirs[:-1] != '/':
+            dirs += '/'
+        if not os.path.exists(dirs):
+            os.makedirs(dirs)
+        
+    data = []
+    
+    inputs1 = []
+    inputs1.append(sim.N)
+    inputs1.append(sim.M)
+    inputs1.append(sim.maxtime)
+    inputs1.append(sim.record_itv)
+    inputs1.append(sim.sim_time)
+    inputs1.append(sim.boundary)
+    inputs1.append(sim.I.tolist())
+    inputs1.append(sim.X.tolist())
+    inputs1.append(sim.P.tolist())
+    data.append(inputs1)
+
+    inputs2 = []
+    inputs2.append(sim.print_pct)
+    inputs2.append(sim.seed)
+    inputs2.append(sim.UV_dtype)
+    inputs2.append(sim.pi_dtype)
+    data.append(inputs2)
+
+    # skipped rng
+    
+    outputs = []
+    outputs.append(sim.max_record)
+    outputs.append(sim.compress_itv)
+    outputs.append(sim.U.tolist())
+    outputs.append(sim.V.tolist())
+    outputs.append(sim.U_pi.tolist())
+    outputs.append(sim.V_pi.tolist())
+    # H&V_pi_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 simulation 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 sim.compress_itv != None. Setting print_msg = False will skip ignore this message.
+
+    Returns:
+    - sim: a piegy.model.simulation 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:
+        sim = model.simulation(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[1][0], seed = data[1][1], UV_dtype = data[1][2], pi_dtype = data[1][3])
+    except:
+        raise ValueError('Invalid input parameters saved in data')
+
+    # outputs
+    try:
+        sim.set_data(False, data[2][0], data[2][1], data[2][2], data[2][3], data[2][4], data[2][5])
+    except:
+        raise ValueError('Invalid simulation results saved in data')
+    
+    return sim
+    
+
+
+