API Overview

class SOC.common.simulation.Simulation(L: int, save_every: int = 1, wait_for_n_iters: int = 10)

Base class for SOC simulations.

Parameters:
  • L (int) – linear size of lattice, without boundary layers
  • save_every (int or None) – number of iterations per snapshot save
  • wait_for_n_iters (int) – How many iterations to skip to skip before saving data?
AvalancheLoop() → dict

Bring the current simulation’s state to equilibrium by repeatedly toppling and dissipating.

Returns a dictionary with the total size of the avalanche and the number of iterations the avalanche took.

Return type:dict
L_with_boundary

The total width of the simulation grid, with boundaries.

animate_states(notebook: bool = False, with_boundaries: bool = False, interval: int = 30)

Animates the collected states of the simulation.

Parameters:
  • notebook (bool) – if True, displays via html5 video in a notebook; otherwise returns MPL animation
  • with_boundaries (bool) – include boundaries in the animation?
  • interval (int) – number of miliseconds to wait between each frame.
classmethod clean_boundary_inplace(array: numpy.ndarray) → numpy.ndarray

Convenience wrapper to common.clean_boundary_inplace with the simulation’s boundary size.

Parameters:array (np.ndarray) – array to clean
Return type:np.ndarray
data_df

Displays the gathered data as a Pandas DataFrame.

Returns:dataframe with gathered data
Return type:pandas.DataFrame
drive()

Drive the simulation by adding particles from the outside.

Must be overriden in subclasses.

classmethod from_file(filename: str)

Loads simulation state from a saved one.

Parameters:filename (str) – Filename to be loaded.
Returns:simulation object, of the subclass you used
Return type:Simulation
get_exponent(column: str = 'AvalancheSize', low: int = 1, high: int = 10, plot: bool = True, plot_filename: Optional[str] = None) → dict

Plot histogram of gathered data from data_df,

Parameters:
  • column (str) – which column of data_df should be visualized?
  • low (int) – lower cutoff for log-log-linear fit
  • high (int) – higher cutoff for log-log-linear fit
  • plot (bool) – if False, skips all plotting and just returns fit parameters
  • plot_filename (bool) – optional filename for saved plot. This skips displaying the plot!
Returns:

fit parameters
Return type:

dict
classmethod inside(array: numpy.ndarray) → numpy.ndarray

Convenience function to get an array without simulation boundaries

Parameters:array (np.ndarray) – array
Returns:array of width smaller by 2BC
Return type:np.ndarray
plot_state(with_boundaries: bool = False) → matplotlib.figure.Figure

Plots the current state of the simulation.

Parameters:with_boundaries (bool) – should the boundaries be displayed as well?
Returns:figure with plot
Return type:plt.Figure
run(N_iterations: int, filename: str = None, wait_for_n_iters: int = 10) → str

Simulation loop. Drives the simulation, possibly starts avalanches, gathers data.

Parameters:
  • N_iterations (int) – number of iterations (per grid node if scale is True)
  • filename (str) – filename for saving snapshots. if None, saves to memory; by default if False, makes something like array_Manna_2019-12-17T19:40:00.546426.zarr
  • wait_for_n_iters (int) – wait this many iterations before collecting data (lets model thermalize)
Return type:

dict
save(file_name='sim')

serialization of object and saving it to file

size

The total size of the simulation grid, without boundaries

topple_dissipate()

Distribute material from overloaded sites to neighbors.

Must be overriden in subclasses.

class SOC.models.BTW(*args, **kwargs)

Implements the BTW model.

Parameters:L (int) – linear size of lattice, without boundary layers
drive(num_particles: int = 1)

Drive the simulation by adding particles from the outside.

Parameters:num_particles (int) – How many particles to add per iteration (by default, 1)
topple_dissipate() → int

Distribute material from overloaded sites to neighbors.

Convenience wrapper for the numba.njitted topple function defined in manna.py.

Return type:int
class SOC.models.Forest(p: float = 0.05, f: float = 0, *args, **kwargs)

Forest fire model

Parameters:
  • f – probability of thunder setting a tree on fire; set 0 to disable lighting
  • p (float) – probability of a new tree growh per empty cell
drive()

Does nothing in FF!

topple_dissipate() → int

Forest burning and turning into ash.

class SOC.models.Manna(critical_value: int = 1, abelian: bool = True, *args, **kwargs)

Implements the Manna model.

drive(num_particles: int = 1)

Drive the simulation by adding particles from the outside.

Parameters:num_particles (int) – How many particles to add per iteration (by default, 1)
topple_dissipate() → int

Distribute material from overloaded sites to neighbors.

Convenience wrapper for the numba.njitted topple_dissipate function defined in manna.py.

Returns:number of iterations it took to
Return type:bool
class SOC.models.OFC(critical_value: float = 1.0, conservation_lvl: float = 0.25, *args, **kwargs)

Implements the OFC model.

Parameters:
  • L (int) – linear size of lattice, without boundary layers
  • critical_value (float) – 1.0 by default - above this value, nodes start toppling. At 0.25 -> full force distributed (if 4 neighbours)
  • conservation_lvl (float) – 0.25 by default - fraction of the force from a toppling site going to its neighbour
AvalancheLoop() → dict

Bring the current simulation’s state to equilibrium by repeatedly toppling and dissipating.

Returns a dictionary with the total size of the avalanche and the number of iterations the avalanche took.

Return type:dict
drive()

Drive the simulation by adding force from the outside.

topple_dissipate() → int

Distribute material from overloaded sites to neighbors.

Convenience wrapper for the numba.njitted topple function defined in ofc.py.

Return type:int