piegy 1.0.0__tar.gz

piegy-1.0.0/LICENSE.txt

@@ -0,0 +1,28 @@
+BSD 3-Clause License
+
+Copyright (c) 2025, Chenning Xu
+
+Redistribution and use in source and binary forms, with or without
+modification, are permitted provided that the following conditions are met:
+
+1. Redistributions of source code must retain the above copyright notice, this
+   list of conditions and the following disclaimer.
+
+2. Redistributions in binary form must reproduce the above copyright notice,
+   this list of conditions and the following disclaimer in the documentation
+   and/or other materials provided with the distribution.
+
+3. Neither the name of the copyright holder nor the names of its
+   contributors may be used to endorse or promote products derived from
+   this software without specific prior written permission.
+
+THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
+AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
+IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
+DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE LIABLE
+FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
+DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR
+SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER
+CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY,
+OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
+OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.

piegy-1.0.0/MANIFEST.in

@@ -0,0 +1,2 @@
+include README.md
+include LICENSE.txt

piegy-1.0.0/PKG-INFO

@@ -0,0 +1,104 @@
+Metadata-Version: 2.4
+Name: piegy
+Version: 1.0.0
+Summary: Payoff-Driven Stochastic Spatial Model for Evolutionary Game Theory
+Author-email: Chenning Xu <cxu7@caltech.edu>
+License: BSD 3-Clause License
+        
+        Copyright (c) 2025, Chenning Xu
+        
+        Redistribution and use in source and binary forms, with or without
+        modification, are permitted provided that the following conditions are met:
+        
+        1. Redistributions of source code must retain the above copyright notice, this
+           list of conditions and the following disclaimer.
+        
+        2. Redistributions in binary form must reproduce the above copyright notice,
+           this list of conditions and the following disclaimer in the documentation
+           and/or other materials provided with the distribution.
+        
+        3. Neither the name of the copyright holder nor the names of its
+           contributors may be used to endorse or promote products derived from
+           this software without specific prior written permission.
+        
+        THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
+        AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
+        IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
+        DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE LIABLE
+        FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
+        DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR
+        SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER
+        CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY,
+        OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
+        OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
+        
+Project-URL: Source, https://github.com/Chenning04/piegy.git
+Project-URL: Documentation, https://piegy.readthedocs.io/en/
+Keywords: Game Theory,Evolutionary Game Theory,Spatial Model,Stochastic Model,Payoff Driven
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: Intended Audience :: Science/Research
+Classifier: Intended Audience :: Education
+Classifier: License :: OSI Approved :: BSD License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Operating System :: OS Independent
+Requires-Python: >=3.6
+Description-Content-Type: text/markdown
+License-File: LICENSE.txt
+Requires-Dist: numpy
+Requires-Dist: matplotlib
+Requires-Dist: imageio>=2.37.0
+Requires-Dist: moviepy>=2.1.1
+Requires-Dist: seaborn>=0.13.2
+Dynamic: license-file
+
+# piegy
+
+The package full name is: Payoff-Driven Stochastic Spatial Model for Evolutionary Game Theory
+
+Provides a stochastic spatial model for simulating the interaction and evolution of two species in either 1D or 2D space, as well as analytic tools.
+
+## Installation
+
+```bash
+pip install piegy
+```
+
+## Documentation and Source
+
+See source code at: [GitHub-piegy repo](https://github.com/Chenning04/piegy.git). 
+The *piegy* documentation at: [piegy docs](https://piegy.readthedocs.io/en/). 
+
+## How the Model Works
+
+Our model can be summarized as "classical game theory endowed with a spatial structure and payoff-driven migration rules". Consider two species, predators and preys (denote by *U* and *V*), in a rectangular region. We divide the region into N by M patches and simulate their interaction within a patch by classical game theory (i.e., payoff matrices and carrying capacity). Interactions across patches are simulated by payoff-driven migration rules. An individual migrates to a neighboring patch with probability weighted by payoff in the neighbors.
+
+We use the Gillepie algorithm as the fundamental event-selection algorithm. At each time step, one event is selected and let happen; and step sizes are continuous, dependent on the current state in the space. Data are recorded every some specified time interval.
+
+## Analytic Tools
+
+The *piegy* package also provides a wide range of analytic and supportive tools alongside the main model, such as plotting, numerical tools, data saving & reading, etc. We also provide the *piegy.videos* module for more direct visualizations like how population distribution change over time.
+
+## Examples
+
+To get started, simply get our demo model and run simulation:
+
+```python
+from piegy import model, figures
+
+sim = model.demo_model()
+model.run(sim)
+
+dynamics = figures.UV_dyna(sim)
+U_hmap, V_hmap = figures.UV_heatmap(sim)
+```
+
+The figures reveal the population dynamics and steady state distribution.
+
+
+## Acknowledgments
+
+- Thanks Professor Daniel Cooney at University of Illinois Urbana-Champaign. This package is developed alongside a project with Prof. Cooney and received enormous help from him.
+- Special thanks to the open-source community for making this package possible.

piegy-1.0.0/README.md

@@ -0,0 +1,48 @@
+# piegy
+
+The package full name is: Payoff-Driven Stochastic Spatial Model for Evolutionary Game Theory
+
+Provides a stochastic spatial model for simulating the interaction and evolution of two species in either 1D or 2D space, as well as analytic tools.
+
+## Installation
+
+```bash
+pip install piegy
+```
+
+## Documentation and Source
+
+See source code at: [GitHub-piegy repo](https://github.com/Chenning04/piegy.git). 
+The *piegy* documentation at: [piegy docs](https://piegy.readthedocs.io/en/). 
+
+## How the Model Works
+
+Our model can be summarized as "classical game theory endowed with a spatial structure and payoff-driven migration rules". Consider two species, predators and preys (denote by *U* and *V*), in a rectangular region. We divide the region into N by M patches and simulate their interaction within a patch by classical game theory (i.e., payoff matrices and carrying capacity). Interactions across patches are simulated by payoff-driven migration rules. An individual migrates to a neighboring patch with probability weighted by payoff in the neighbors.
+
+We use the Gillepie algorithm as the fundamental event-selection algorithm. At each time step, one event is selected and let happen; and step sizes are continuous, dependent on the current state in the space. Data are recorded every some specified time interval.
+
+## Analytic Tools
+
+The *piegy* package also provides a wide range of analytic and supportive tools alongside the main model, such as plotting, numerical tools, data saving & reading, etc. We also provide the *piegy.videos* module for more direct visualizations like how population distribution change over time.
+
+## Examples
+
+To get started, simply get our demo model and run simulation:
+
+```python
+from piegy import model, figures
+
+sim = model.demo_model()
+model.run(sim)
+
+dynamics = figures.UV_dyna(sim)
+U_hmap, V_hmap = figures.UV_heatmap(sim)
+```
+
+The figures reveal the population dynamics and steady state distribution.
+
+
+## Acknowledgments
+
+- Thanks Professor Daniel Cooney at University of Illinois Urbana-Champaign. This package is developed alongside a project with Prof. Cooney and received enormous help from him.
+- Special thanks to the open-source community for making this package possible.

piegy-1.0.0/pyproject.toml

@@ -0,0 +1,45 @@
+[build-system]
+requires = ['setuptools>=61.0', 'wheel']
+build-backend = 'setuptools.build_meta'
+
+[project]
+name = 'piegy'
+version = '1.0.0'
+description = 'Payoff-Driven Stochastic Spatial Model for Evolutionary Game Theory'
+readme = 'README.md'
+requires-python = '>=3.6'
+license = {file = "LICENSE.txt"}
+authors = [
+    {name = 'Chenning Xu', email = 'cxu7@caltech.edu'}
+]
+keywords = ['Game Theory', 'Evolutionary Game Theory', 'Spatial Model', 'Stochastic Model', 'Payoff Driven']
+dependencies = [
+    'numpy',
+    'matplotlib',
+    'imageio>=2.37.0',
+    'moviepy>=2.1.1',
+    'seaborn>=0.13.2'
+]
+classifiers = [
+    "Development Status :: 4 - Beta",
+    "Intended Audience :: Developers",
+    "Intended Audience :: Science/Research",
+    "Intended Audience :: Education",
+    "License :: OSI Approved :: BSD License",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.10",
+    "Programming Language :: Python :: 3.11",
+    "Operating System :: OS Independent"
+]
+
+
+[project.urls]
+Source = 'https://github.com/Chenning04/piegy.git'
+Documentation = 'https://piegy.readthedocs.io/en/'
+
+[tool.setuptools]
+package-dir = {'' = 'src'}
+
+[tool.setuptools.packages.find]
+where = ['src']
+

piegy-1.0.0/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

piegy-1.0.0/src/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-1.0.0/src/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-1.0.0/src/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
+
+
+