Skip to content


Repository files navigation


Wolfram Models as Set Substitution Systems | Getting Started | Symbols and Functions | Physics | Acknowledgements

Wolfram Models as Set Substitution Systems

Set Substitution Systems

SetReplace is a Wolfram Language package for manipulating set substitution systems. To understand what a set substitution system does consider an unordered set of elements:

{1, 2, 5, 3, 6}

We can set up an operation on this set which would take any of the two elements and replace them with their sum:

{a_, b_} :> {a + b}

In SetReplace, this can be expressed as the following (the new element 1 + 2 -> 3 is put at the end)

In[] := SetReplace[{1, 2, 5, 3, 6}, {a_, b_} :> {a + b}]
Out[] = {5, 3, 6, 3}

Note that this is similar to SubsetReplace function of Wolfram Language (it replaces all non-overlapping subsets at once by default):

In[] := SubsetReplace[{1, 2, 5, 3, 6}, {a_, b_} :> a + b]
Out[] = {3, 8, 6}

Wolfram Models

A more interesting case (which we call a Wolfram model) is one where the set elements are related to each other. Specifically, we can consider a set of ordered lists of atomic vertices; in other words, an ordered hypergraph.

As an example consider a set:

{{1, 2, 3}, {2, 4, 5}, {4, 6, 7}}

We can render it as a collection of ordered hyperedges:

In[] := HypergraphPlot[{{1, 2, 3}, {2, 4, 5}, {4, 6, 7}},
 VertexLabels -> Automatic]

We can then have a rule which would pick a subset of these hyperedges related through common vertices (much like a join query) and replace them with something else:

{{v1_, v2_, v3_}, {v2_, v4_, v5_}} :>
 Module[{v6}, {{v5, v6, v1}, {v6, v4, v2}, {v4, v5, v3}}]

Note the Module on the right-hand side creates a new variable (vertex) which causes the hypergraph to grow. Due to optimizations, it's not always a Module that creates vertices, so its name may be different. After a single replacement we get this (the new vertex is v11):

In[] := HypergraphPlot[SetReplace[{{1, 2, 3}, {2, 4, 5}, {4, 6, 7}},
  {{v1_, v2_, v3_}, {v2_, v4_, v5_}} :>
   Module[{v6}, {{v5, v6, v1}, {v6, v4, v2}, {v4, v5, v3}}]],
 VertexLabels -> Automatic]

After 10 steps, we get a more complicated structure:

In[] := HypergraphPlot[SetReplace[{{1, 2, 3}, {2, 4, 5}, {4, 6, 7}},
  {{v1_, v2_, v3_}, {v2_, v4_, v5_}} :>
   Module[{v6}, {{v5, v6, v1}, {v6, v4, v2}, {v4, v5, v3}}], 10],
 VertexLabels -> Automatic]

And after 100 steps, it gets even more elaborate:

In[] := HypergraphPlot[SetReplace[{{1, 2, 3}, {2, 4, 5}, {4, 6, 7}},
  {{v1_, v2_, v3_}, {v2_, v4_, v5_}} :>
   Module[{v6}, {{v5, v6, v1}, {v6, v4, v2}, {v4, v5, v3}}], 100]]

Exploring the hypergraph models of this variety is the primary purpose of this package.

Getting Started


You only need three things to use SetReplace:

Build Instructions

For users who wish to make use of SetReplace functionality, and not modify the source code itself, we recommend simply building and installing the paclet.

To do this, run the following on the command line:

cd ~/PATH-TO-CHECKOUT/SetReplace

Please note that if you do not have GitLink installed, it will be installed for you.

Now that you have installed the SetReplace paclet, you should evaluate << SetReplace` every time you start a fresh Mathematica session. This will load the paclet and bring the various functions into scope, so that you can call them.

For more info about doing development on the SetReplace codebase and the associated workflows, see the Contributing guide.


If, while building, you see an error message about C++17, make sure the C++ compiler you are using is up-to-date. If your default system compiler does not support C++17, you can choose a different one with environmental variables. The following, for instance, typically works on a Mac:

COMPILER=CCompilerDriver\`ClangCompiler\`ClangCompiler COMPILER_INSTALLATION=/usr/bin ./install.wls

Here ClangCompiler can be replaced with one of << CCompilerDriver`; "Compiler" /. CCompilerDriver`CCompilers[Full] , and COMPILER_INSTALLATION is a directory in which the compiler binary can be found.


Keep in mind that this is an active research project. While we try to keep the main functionality backward compatible, it might change in the future as we adjust our models and find better ways of analysis. Keep that in mind when building on top of SetReplace, and keep track of git SHAs as you go.

SetReplace is an open-source project, and everyone is welcome to contribute. Read our contributing guidelines to get started.

We have a Discord server. If you would like to contribute but have questions or don't know where to start, this is the perfect place! In addition to helping new contributors, we discuss feature and research ideas. So, if you are interested, please join!

Symbols and Functions


A hypothesis is that spacetime at small scales is a network, and the fundamental law of physics is a system similar to the one this package implements.

A slightly different version of this system was first introduced in Stephen Wolfram' s A New Kind Of Science.


In additional to commit authors and reviewers, Stephen Wolfram has contributed to the API design of some functions, and Jeremy Davis has contributed to the visual style of HypergraphPlot , RulePlot and "CausalGraph" .