piegy 1.1.3__py3-none-any.whl → 1.1.5__py3-none-any.whl

piegy/__init__.py

@@ -20,7 +20,7 @@ Last update: May 12, 2025
 
 from .__version__ import __version__
 
-from .model import simulation, run, demo_model
+from .simulation import model, run, demo_model
 from .videos import make_video, SUPPORTED_FIGURES
 from .data_tools import save_data, read_data
 
@@ -33,13 +33,13 @@ 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']
+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_sim']
+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']
@@ -48,7 +48,7 @@ test_var_members = ['test_var1', 'var_UV1', 'var_pi1', 'var_convergence1', 'get_
                     'test_var2', 'var_UV2', 'var_pi2', 'var_convergence2', 'get_dirs2']
 
 
-__all__ = model_members + videos_members + data_members + figures_members + analysis_members + test_var_members
+__all__ = simulation_memebers + videos_members + data_members + figures_members + analysis_members + test_var_members
 
 
 

piegy/__version__.py

@@ -17,5 +17,7 @@ version history:
 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.
 
 '''

piegy/analysis.py

@@ -3,8 +3,8 @@ This file contains pre-processing, post-processing, and analytical tools for sim
 
 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.
+- 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.
 
@@ -17,7 +17,7 @@ Private Functions:
 
 '''
 
-from . import model as model
+from . import simulation as simulation
 from . import figures as figures
 from .tools import figure_tools as figure_t
 
@@ -27,17 +27,17 @@ import math
 
 
 
-def rounds_expected(sim):
+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 sim.maxtime.
+    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 = sim.N
-    M = sim.M
-    U_expected, V_expected = figures.UV_expected_val(sim)
+    N = mod.N
+    M = mod.M
+    U_expected, V_expected = figures.UV_expected_val(mod)
 
     rates = []
     patch0 = None  # simulate patch i, j
@@ -46,19 +46,19 @@ def rounds_expected(sim):
     # 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])
+            patch0 = simulation.patch(U_expected[i][j], V_expected[i][j], mod.X[i][j], mod.P[i][j])
 
             nb_indices = None
-            if sim.boundary:
-                nb_indices = model.find_nb_zero_flux(N, M, i, j)
+            if mod.boundary:
+                nb_indices = simulation.find_nb_zero_flux(N, M, i, j)
             else:
-                nb_indices = model.find_nb_periodical(N, M, i, j)
+                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 = 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 = 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)
 
@@ -73,40 +73,40 @@ def rounds_expected(sim):
             rates += patch0.mig_rates
     
     delta_t_expected = (1 / sum(rates)) * math.log(1 / 0.5)
-    r_expected = round(sim.maxtime / delta_t_expected)
+    r_expected = round(mod.maxtime / delta_t_expected)
 
     return r_expected
 
 
 
 
-def scale_maxtime(sim1, sim2, scale_interval = True):
+def scale_maxtime(mod1, mod2, 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.
+    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 sim1's interval as well, so that the same number of data will be stored.
+    - 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(sim1)
-    r_expected2 = rounds_expected(sim2)
+    r_expected1 = rounds_expected(mod1)
+    r_expected2 = rounds_expected(mod2)
     ratio = r_expected2 / r_expected1
 
-    new_maxtime = sim1.maxtime * ratio
-    old_max_record = sim1.maxtime / sim1.interval
+    new_maxtime = mod1.maxtime * ratio
+    old_max_record = mod1.maxtime / mod1.interval
 
     if scale_interval:
-        sim1.interval = new_maxtime / old_max_record
+        mod1.interval = new_maxtime / old_max_record
 
-    sim1.change_maxtime(new_maxtime)
+    mod1.change_maxtime(new_maxtime)
 
 
 
 
-def check_convergence(sim, interval = 20, start = 0.8, fluc = 0.07):
+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.
@@ -114,7 +114,7 @@ def check_convergence(sim, interval = 20, start = 0.8, fluc = 0.07):
     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
+    - 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.
@@ -128,25 +128,25 @@ def check_convergence(sim, interval = 20, start = 0.8, fluc = 0.07):
     if (type(interval) != int) or (interval < 1):
         raise ValueError("interval should be an int >= 1")
     
-    interval = figure_t.scale_interval(interval, sim.compress_itv)
+    interval = figure_t.scale_interval(interval, mod.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
+    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(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])
+    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(sim.U[:, :, lower : upper])
-        ave_V = np.mean(sim.V[:, :, lower : upper])
+        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:
@@ -170,51 +170,51 @@ def check_convergence(sim, interval = 20, start = 0.8, fluc = 0.07):
 
 
 
-def combine_sim(sim1, sim2):
+def combine_sim(mod1, mod2):
     '''
-    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 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:
-    - sim1, sim2: both stochastic_model.simulation object. All input parameters the same except for sim_time, print_pct and seed.
+    - 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 simulation object whose U, V, U_pi, V_pi are weighted averages of sim1 and sim2
+    - sim3:     a new model object whose U, V, U_pi, V_pi are weighted averages of mod1 and mod2
                 (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
+                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 (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)):
+    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('sim1 and sim2 have different input parameters (N, M, maxtime, interval, boundary, max_record, or I, X, P).')
+        raise ValueError('mod1 and mod2 have different input parameters (N, M, maxtime, interval, boundary, max_record, or I, X, P).')
 
-    if sim1.seed == sim2.seed:
+    if mod1.seed == mod2.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)
+    # 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] = (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
+                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.U_pi[i][j][k] = (mod1.U_pi[i][j][k] * mod1.sim_time + mod2.U_pi[i][j][k] * mod2.sim_time) / combined_sim_time
+                sim3.V_pi[i][j][k] = (mod1.V_pi[i][j][k] * mod1.sim_time + mod2.V_pi[i][j][k] * mod2.sim_time) / combined_sim_time
 
     return sim3
 

piegy/data_tools.py

@@ -1,33 +1,33 @@
 '''
-Stores and reads a simulation object.
+Stores and reads a model object.
 
 Functions:
-- save_data:    save a simulation object.
-- read_data:    read a simulation object.
+- save_data:    save a model object.
+- read_data:    read a model object.
 '''
 
 
-from . import model as model
+from . import simulation
 
 import json
 import gzip
 import os
 
 
-def save_data(sim, dirs = '', print_msg = True):
+def save_data(mod, dirs = '', print_msg = True):
     '''
-    Saves a simulation object. Data will be stored at dirs/data.json.gz
+    Saves a model object. Data will be stored at dirs/data.json.gz
 
     Inputs:
-    - sim:        Your simulation object.
+    - mod:        Your model object.
     - dirs:       Where to save it.
     - print_msg:  Whether to print message after saving.
     '''
 
     try:
-        _ = sim.N
+        _ = mod.N
     except AttributeError:
-        raise ValueError('sim is not a simulation object')
+        raise ValueError('mod is not a model object')
 
     if dirs != '':
         # add slash '/'
@@ -39,33 +39,33 @@ def save_data(sim, dirs = '', print_msg = True):
     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())
+    inputs1.append(mod.N)
+    inputs1.append(mod.M)
+    inputs1.append(mod.maxtime)
+    inputs1.append(mod.record_itv)
+    inputs1.append(mod.sim_time)
+    inputs1.append(mod.boundary)
+    inputs1.append(mod.I.tolist())
+    inputs1.append(mod.X.tolist())
+    inputs1.append(mod.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)
+    inputs2.append(mod.print_pct)
+    inputs2.append(mod.seed)
+    inputs2.append(mod.UV_dtype)
+    inputs2.append(mod.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())
+    outputs.append(mod.max_record)
+    outputs.append(mod.compress_itv)
+    outputs.append(mod.U.tolist())
+    outputs.append(mod.V.tolist())
+    outputs.append(mod.U_pi.tolist())
+    outputs.append(mod.V_pi.tolist())
     # H&V_pi_total are not saved, will be calculated when reading the data
     data.append(outputs)
     
@@ -83,14 +83,14 @@ def save_data(sim, dirs = '', print_msg = True):
 
 def read_data(dirs):
     '''
-    Reads and returns a simulation object.
+    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 sim.compress_itv != None. Setting print_msg = False will skip ignore this message.
+    - print_msg:  this function prints a message when the mod.compress_itv != None. Setting print_msg = False will skip ignore this message.
 
     Returns:
-    - sim: a piegy.model.simulation object read from the data.
+    - mod: a piegy.model.model object read from the data.
     '''
     
     if dirs != '':
@@ -110,7 +110,7 @@ def read_data(dirs):
 
     # inputs
     try:
-        sim = model.simulation(N = data[0][0], M = data[0][1], maxtime = data[0][2], record_itv = data[0][3],
+        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[1][0], seed = data[1][1], UV_dtype = data[1][2], pi_dtype = data[1][3])
     except:
@@ -118,12 +118,12 @@ def read_data(dirs):
 
     # outputs
     try:
-        sim.set_data(data_empty = False, max_record = data[2][0], compress_itv = data[2][1], 
+        mod.set_data(data_empty = False, max_record = data[2][0], compress_itv = data[2][1], 
                     U = data[2][2], V = data[2][3], U_pi = data[2][4], V_pi = data[2][5])
     except:
-        raise ValueError('Invalid simulation results saved in data')
+        raise ValueError('Invalid model results saved in data')
     
-    return sim
+    return mod