{"id":15760621,"url":"https://github.com/flrs/visual_sandpile","last_synced_at":"2025-05-07T10:49:06.363Z","repository":{"id":201981401,"uuid":"82997017","full_name":"flrs/visual_sandpile","owner":"flrs","description":"Matlab library to visualize the avalanche and power law characteristics of the Bak-Tang-Wiesenfeld sandpile model","archived":false,"fork":false,"pushed_at":"2017-02-26T03:27:22.000Z","size":227,"stargazers_count":6,"open_issues_count":0,"forks_count":3,"subscribers_count":1,"default_branch":"master","last_synced_at":"2025-05-06T06:52:51.208Z","etag":null,"topics":["abelian-sandpile","cellular-automaton","sandpile-model","self-organized-criticality"],"latest_commit_sha":null,"homepage":"","language":"Matlab","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/flrs.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE.md","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null}},"created_at":"2017-02-24T03:25:46.000Z","updated_at":"2024-04-01T17:45:35.000Z","dependencies_parsed_at":null,"dependency_job_id":"a06c5011-0d08-45e5-b3fa-207a4256b54f","html_url":"https://github.com/flrs/visual_sandpile","commit_stats":null,"previous_names":["flrs/visual_sandpile"],"tags_count":1,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/flrs%2Fvisual_sandpile","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/flrs%2Fvisual_sandpile/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/flrs%2Fvisual_sandpile/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/flrs%2Fvisual_sandpile/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/flrs","download_url":"https://codeload.github.com/flrs/visual_sandpile/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":252863369,"owners_count":21816019,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["abelian-sandpile","cellular-automaton","sandpile-model","self-organized-criticality"],"created_at":"2024-10-04T10:59:17.572Z","updated_at":"2025-05-07T10:49:06.340Z","avatar_url":"https://github.com/flrs.png","language":"Matlab","funding_links":[],"categories":[],"sub_categories":[],"readme":"Visual Bak-Tang-Wiesenfeld Sandpile Model for Matlab\n====================================================\nThis Matlab library helps to visualize the avalanche and power law characteristics of the popular sandpile model.\n\nThe library is meant for visualizing the Bak-Tang-Wiesenfeld sandpile model and plotting the sandpile's statistics\non the fly. The visualization has been optimized for performance.\n\nGeneral Description of the Sandpile Model\n-----------------------------------------\nThe Bak-Tang-Wiesenfeld sandpile model (also called *Abelian Sandpile Model*) represents a sandpile to which sand\ngrains are added one by one. It is described in an intuitive way in Per Bak's famous book\n[How nature works: the science of self-organized criticality](https://books.google.com/books/about/How_nature_works.html?id=e5XuAAAAMAAJ).\nThe model gives an easily understandable example of the concept of self-organized criticality and shows how large-scale,\ncomplex behavior can emerge from local, simple patterns in nature.\n\nAs observed in the real world, parts of a sandpile might start \"sliding\" off its slope when enough grains have\naccumulated at a location. Once a sand grain has started its sliding movement, it might also bump into other sand grains\nand cause them to slide. This event is known as \"avalanche\". In his research, Per Bak has observed that the number of\ngrains that take part in an avalanche (as a measure of the avalanche size) follows a power-law distribution.\n\nA power-law distribution means that some quantity *D* can be expressed as some power of another quantity *s*, for\nexample as *D(s) = k*s^-τ*, where *τ* and *k* are constants. When plotted on a log-log plot, a power-law distribution\nshows through the plotted data resembling a straight line.\n\n![Log-log plot showing avalanche size distribution](sandpile_log-log_plot.png \"Avalanche Sizes Follow Power Law\")\n\nThe plot shown above has been created from data gathered by this sandpile model. Up to an avalanche size of 100 grains,\nthe data supports the claim of a power-law distribution: The data resembles a straight line, approximated by the graph\nof a linear fit function shown in green.\n\nThe power-law characteristics of the sandpile system are very important for Bak's line of thought. He remarks:\n\n\u003e The power law indicates that the stationary state is critical.\n\u003e We conclude that he pile has self-organized into a critical state.\n\u003e -- \u003csub\u003e\u003csup\u003eBak, P. *How nature works : the science of self-organized criticality*. New York: Springer, 1996, 57.\u003c/sup\u003e\u003c/sub\u003e\n\nIn this quote, the terms *critical* and *self-organized* jump out. The *critical* state, in the context of the sandpile\nmodel, relates to how individual sand grains behave *as a group*.\n\nA pile of sand that consists of many randomly arranged sand grains might not have a critical state. In this kind of\nsandpile, any grain that is added, at any position, will probably not have global effects on the sandpile. A newly added\ngrain might cause a few grains to topple in its neighborhood, but there is no remarkable pattern of topples or\navalanches this grain causes.\n\nHowever, a sandpile that is in a critical state is different. In such a sandpile, a grain that is added at a random\nposition will eventually cause global effects in the sandpile. The added grain might start an avalanche of toppling\nprocesses that change the entire geometry of the sandpile, reaching far beyond the local domain. For a sandpile that\nhas a typical conical form, the critical state is reached when its slope has reached a certain angle. Keeping all\nparameters the same and adding more sand grains, sand sliding off its slope will prevent the sandpile's slope angle\nfrom becoming any steeper.\n\nTo put it in Bak's words: In a non-critical state, individual grains follow their own local dynamics, while in a\ncritical state, the emergent dynamics are global. In the critical state, a pattern emerges from the observation of the\nsandpile: Avalanche sizes (and other measurable quantities) show a power-law distribution.\n\nThe sandpile does organize itself without external influences into the critical state. It is entirely *self-organized*.\nThis means that even if grains are initially distributed randomly and not in a specific way triggering a critical state,\nthe sandpile will show critical behavior after adding a certain number of sand grains to arbitrary positions.\n\nHow This Sandpile Model Works\n-----------------------------\nIn this sandpile model, the sandpile is built onto a square grid of a specified `pile_width` The total number of\npositions in the square grid is `pile width * pile width`, so for a sandpile with a `pile_width` of 12, 144 grid\npositions are available.\n\nOn every grid position, an arbitrary amount of sand grains can be stacked. However, if the number of sand grains on a\ngrid position is greater than or equal to 4, a toppling event takes place, originating at that grid position.\n\nIn a toppling event, four grains get taken away from the originating grid position and are distributed equally among the\nneighboring grid positions north, east, south, and west of the originating grid position. As a result, the originating\ngrid position possesses four grains less, while the number of grains on all its four neighboring positions has increased\nby one. This behavior eventually leads to a chain reaction, in which a further toppling event on one of the neighboring\npositions is caused. Such a chain reaction is called \"avalanche\". If, through a toppling event, a sand grain is to be\nadded to a position beyond the boundary of the pile, it is ignored and no longer considered in the model. This can be\nimagined as a sand grain \"falling off\" the surface on which the sandpile is created.\n\nIn this model, new sand grains are added to random grid positions. The sand grains are added one by one, except during\ntoppling or avalanche events. In this case, no grains are added until these events are over. The model is initialized\nwith a random number of up to 3 grains at every grid position. (As noted [before](#general-description-of-the-sandpile-model),\nthis random initialization is not necessarily critical, the critical behavior evolves over time.)\n\nMatlab Plots for Visualization\n------------------------------\nDuring execution of this script, Matlab visualizes the sandpile by means of a sandpile plot and a plot showing the\navalanche size distribution. The sandpile plot can be turned off to increase performance.\n\n### Sandpile Plot\nA sample of the sandpile plot is shown in the picture below. The plot shows a \"top view\" of the entire pile. The\npile has a width of 22 positions, so 22*22=484 positions in total. A square is shown for every grid position. The\nlighter the square in color, the more grains are stacked on the grid position. On the color scale, there is no\ndiscrimination between positions that have four and more grains, all of them are white. A black square indicates that\nthere are no grains placed on that position.\n\nThe peach-colored square overlaying a grid position shows the location where the most recent sand grain is dropped. The\nsquare is not shown during an avalanche.\n\nThe sandpile plot is updated automatically as the model is running.\n\n![Matlab sandpile plot](sandpile_grid.png \"Matlab plot showing sandpile\")\n\n### Plot of Avalanche Sizes\nThe plot of avalanche sizes is a log-log plot that is created and updated as the model runs. It shows the quantity of\navalanches and their sizes. In this model, the size of an avalanche is defined as the number of direct and indirect\ntoppling events that were caused by the addition of a single sand grain to the pile.\n\nThrough the log-log scale the plot enables an assessment of whether the avalanche distribution follows a power law. As\nthere are note many observations for the biggest avalanches, the plot usually shows some clutter for the biggest\navalanches.\n\n![Matlab plot of avalanche sizes](sandpile_size_plot.png \"Matlab plot showing avalanche sizes\")\n\nUsage\n-----\nThe code is thoroughly documented, the documentation can be accessed through the `doc simulateSandpile` command. To run\nthe model, call the `simulateSandpile` function, the only user-facing function in the script.\n\nConfigurable **input** parameters of `simulateSandpile` are:\n\n* `pile_width`: Side length of the square pile\n\n* `no_of_grains`: Number of grains that are added one by one to the sandpile as the model runs. The simulation stops\nafter the specified number of grains has been added.\n\n* `draw_speed`: Speed of animation of the plots. A speed of 0 skips the sandpile animation entirely, and will only plot\na chart of avalanche sizes once the simulation has finished running. A value of 0.5 yields a relatively slow animation, smaller\nvalues yield a faster one.\n\nThe following code is a simple usage example:\n```matlab\npile_width = 40;      % Pile represented through 40x40 grid\nno_of_grains = 4000;  % Run the simulation until 4000 new sand grains have been added\ndraw_speed = 0.2;      % Animate the pile relatively slow\navalanche_output = simulateSandpile(pile_width, no_of_grains, draw_speed);\n```\n\nThe `simulateSandpile` function returns a single **output** variable, `avalanche_output`. This variable is a matrix with\nthe shape *max. avalanche size x 2*. The matrix contains information about how many avalanches with a specific size\noccurred during the run. ([The avalanche plot description](#plot-of-avalanche-sizes) shows how the avalanche size is\ndefined in this model.)\n\nHere is an annotated example of a typical `avalanche_output`:\n```matlab\n% Content of avalanche_output:\n[1 50;   % 50 avalanches causing 1 toppling event\n 2 32;   % 32 avalanches causing 2 toppling events\n 3 11;   % 11 avalanche causing 3 toppling events\n ...];\n```\n\nDownload\n--------\nAn archive with the library can be downloaded from the [releases page](https://github.com/flrs/visual_sandpile/releases).\n\nInstallation\n------------\nTo install the library, extract all files into a folder and add them to your Matlab path.\n\nContribution\n------------\nI am happy about any contribution or feedback. Please let me know about your comments via the Issues tab on\n[GitHub](https://github.com/flrs/visual_sandpile/issues).\n\nAcknowledgements\n----------------\nThe main source of inspiration for writing this library is Per Bak's book\n[How nature works: the science of self-organized criticality](https://books.google.com/books/about/How_nature_works.html?id=e5XuAAAAMAAJ).\n\nThe function `rldCumsumDiff` that repeats copies of array elements is taken from [a post byDivakar's on stackoverflow.com](http://stackoverflow.com/a/29079288/2778484).\n\nLicense\n-------\nThe Visual Bak-Tang-Wiesenfeld Sandpile Model for Matlab is distributed under the [MIT License (MIT)](https://github.com/flrs/visual_sandpile/blob/master/LICENSE.md).\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fflrs%2Fvisual_sandpile","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fflrs%2Fvisual_sandpile","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fflrs%2Fvisual_sandpile/lists"}