Using the siteswap generator

A siteswap generator is a program that finds juggling patterns in siteswap notation. You give the generator a list of parameters that define what kinds of patterns you want it to find, and it finds all patterns that fit the given constraints.

Running the generator for the first time

Juggling Lab's siteswap generator panel is shown in the graphic below. To run it for the first time:

1. Click "Defaults".
2. Then click "Run".

The generator should produce a list of five-ball siteswap patterns:

  55555
  64555
  64645
  66355
  66364
  66625
    .
    .
    .
  77461
  77722
  77731
* 66670 *
* 67273 *
* 67570 *
* 75670 *
* 77272 *
* 77470 *

This is an exhaustive list of patterns satisfying the parameters entered on the panel above. (These parameters were reset to their default values when you clicked the "Defaults" button.) Each line is a separate pattern, and clicking on a line will open an animation of it.

Why do some patterns have a '*' before and after them? These patterns require some transition throws to get from the cascade (in this case, siteswap 5) into the pattern, and more transition throws to get from the pattern back into the cascade. The '*' is just a placeholder to indicate that these transition throws are required. Check the "transition throws" box on the input panel and re-run the generator; the explicit values of the transition throws will be filled in.

For example, let's say you wanted to do the pattern 66670 once from the middle of a cascade. Because 66670 has transition throws, you can't just switch into it immediately like this:

       ... 5555555 666706667066670 ...
                 ^     ^

because of the collision indicated. (The space is there to guide the eye; it doesn't correspond to a beat in time.) You need a transition throw, in this case a '6':

       ... 5555555 6 666706667066670 ...

Similarly, you need a transition throw to get back to the cascade, in this case a '4':

       ... 666706667066670 4 5555555 ...

It can be shown that when transition throws are required to get into a pattern, then transition throws will always be required to get back out (and vice versa).

Patterns that require these extra transition throws are called excited state patterns, and the others without transition throws are called ground state patterns. The transition throws for an excited state pattern are not unique; in the case above the sequence '662' could have been used to exit the pattern 66670. Juggling Lab finds the shortest transition sequences possible.

Siteswap generator parameters

Each element of the generator panel specifies a parameter that constrains the generator's search algorithm:

• Balls. Specifies the number of objects the generated patterns are to have.
• Max. throw. Specifies a maximum siteswap throw value in the patterns found. Enter values greater than 9 either as 10, 11, 12, ... or using the conventional a, b, c, ... of siteswap notation. You can also enter '-' (no quotes), or leave the box empty, to indicate no limit on throw values.
• Period. Specifies the period of time, in "beats", before the pattern repeats. For an asynchronous pattern there is 1 beat per throw. In a synchronous pattern there are 2 beats per throw pair (r,l), so the period must be a multiple of 2. In addition to specifying period as a single value, you may specify it as a range like 5-7. Specifying an open range like -7 or 5- means no limit on the minimum or maximum period, respectively. Specifying -, as in the max. throw setting above, means no limit on period. This latter setting only makes sense in prime mode when a max. throw has been specified, since only then will the number of patterns be finite.
• Jugglers. Specifies the number of jugglers in the pattern.
• Rhythm. Selects either asynchronous or synchronous rhythm of throws, i.e., whether the hands alternate throws or throw at the same time.
• Compositions. Sets option to filter out patterns that are combinations (compositions) of simpler patterns. See the section below for a more complete description.
• Find. Sets options to generate ground- or excited-state patterns (or both) and options for displaying them. See the section below for a more complete description.
• Multiplexing. Specifies whether the generator is to find multiplexing patterns, and if so, the maximum number of simultaneous throws to allow from any hand. There are also options to exclude patterns requiring simultaneous catches from different places (such catches are typically quite difficult), and to exclude patterns with "clustered" multiplex throws of the same value (for example [33]). These exclusions apply only to the pattern itself, not to the transition throws of excited-state patterns. "True multiplexing" requires that each pattern have at least one multiplex throw containing no held balls; for example [32] with 5 balls would be excluded.
• Exclude these expressions. Items to exclude from the search, written as regular expressions and separated by spaces if more than one. A pattern will be excluded if it matches any of these expressions. These exclusions apply only to the pattern itself, not to the transition throws of excited-state patterns. See the section below for a more complete description.
• Include these expressions. Requires that patterns match all of the listed regular expressions. See the section below for a more complete description.
• Passing communications delay. Number of time beats jugglers 2, 3, ... are given to react to a trick thrown by juggler 1. See section below for a more complete description.
• Defaults button. Click on this to reset all generator parameters to their defaults.
• Run button. Click on this to start the generator searching for patterns.

Compositions options

This option is a bit complicated and requires a deeper understanding of siteswap notation.

One general observation about siteswap patterns is that any two that share the same transition throws can be strung together to get another valid pattern. Thus the two ground state three ball patterns 441 and 3 are combined to get another valid pattern: 4413. In this case we say that 4413 is a composition of 441 and 3.

Another general observation is that you can cyclically rotate the throws in a pattern to get another valid one. Thus 441 can be rotated left to get 414. Note that 414 is not a ground state pattern, as written, since in the following throw sequence:

         ... 3333333 414414414 ...
                   ^  ^

causes the two indicated throws to collide.

The program generally doesn't list all the rotated versions of the patterns that it finds, since this clutters up the listings. So how does it decide which rotation to display? It displays the rotation that minimizes the length and throw values of the transition throws into the pattern. In the case of 441, this minimum number of transition throws is 0 if the pattern is displayed as 441 (not 414), so it's displayed that way.

Now the three "Compositions" choices break down in the following way:

1. All compositions. Show all patterns, including any compositions.
2. Non-obvious compositions. Do not show patterns that are compositions of other, listed, patterns.
3. No compositions. Show only patterns that are not compositions of any shorter patterns. (These are called prime patterns.)

As an example, consider the three patterns 6316131, 4413, and 51414. The first is not a composition at all, so it will appear regardless of the "Compositions" setting. The second is a composition of two patterns that the program does print, namely 441 and 3; therefore it will be listed only with the "all compositions" setting.

The last pattern, 51414, is a composition of two shorter patterns, 51 (the shower) and 414. When "no compositions" is selected, 51414 will not be displayed. In the "non-obvious compositions" setting, however, this pattern will be displayed because, although 51 is displayed as such by the generator, 414 will be displayed as its ground state rotation 441. If you were looking at a generator listing you would see 51 and 441 with different transition throws, and it wouldn't be obvious that you could rotate the latter and tack it onto the former. These kinds of compositions are called non-obvious.

The default setting is to show all compositions.

Find options

This tells the generator what class of patterns to find: Ground state patterns, excited state patterns, or both. The "transition throws" option causes transition throws to be printed for any excited state patterns found -- otherwise '*' is printed as a placeholder. The "pattern rotations" causes all rotations of a pattern to be printed, for example 441, 414, and 144 would each be printed separately.

The "juggler permutations" option applies when generating passing patterns. As a default, the generator will avoid displaying multiple patterns that are just the same pattern with the jugglers reordered (permuted). For example, the two passing siteswaps <3|4p><2p|3> and <4p|3><3|2p> are the same pattern with the jugglers swapped, so only one of them is shown by the generator. You can show all permutations as distinct patterns by selecting the "juggler permutations" option. (Note: The algorithm Juggling Lab uses to exclude juggler-permuted duplicates is not guaranteed to exclude all of them, although it does exclude the vast majority.)

"Connected patterns only" also applies only to passing patterns. Selecting this option filters out any passing patterns that are two or more patterns (each with fewer jugglers) done together. A simple example is <5|3><1|3>, which is two jugglers standing next to each other doing solo juggling tricks.

"Symmetric patterns only" applies only to passing patterns. Selecting this option generates only patterns where all jugglers share an identical sequence of throws. The (identical) throw sequences for each juggler may be offset in time with respect to one another, as in the pattern <4p|2p><2p|4p>

Aside: Verifying the siteswap counting rule

One of the main results in the mathematics of siteswap patterns is the counting rule: The number of distinct siteswap patterns with b objects and period n is given by F(b, n) = (b+1)^n - b^n. This result was first proved by Buhler, Eisenbud, Graham, and Wright in 1994.

We can verify this formula using Juggling Lab's siteswap generator. For example, select 4 balls, no max. throw (leave the box empty), period 3. Also select the "pattern rotations" checkbox. Then click Run. You will get a listing of 61 patterns, which agrees with the formula: 5^3 - 4^3 = 61.

Exclude / include these expressions

Values entered here specify terms that filter the generator output. Exclude eliminates all patterns that match any of the supplied terms, and include eliminates all patterns that don't match at least one of the supplied terms. Multiple terms may be provided for each, separated by spaces. For example an exclude of 11 2 3 [54] filters out all patterns containing at least one of the following: The throw combination 11 (two 1s in a row), throws 2 or 3, or the multiplex throw [54].

Filters can match patterns as well as literal terms. The terms supplied can be any regular expressions, with a syntax adjusted to accomodate siteswap pattern notation. For example an exclude term of <3p|.*> excludes all passing patterns where the first juggler throws a 3p (the '.*' is a wildcard that matches against any string of characters). As another example, the "true multiplexing only" option is implemented for solo asynch patterns with the [\[^2\]*] include term.

Passing communication delay

This delay setting only has an effect when there is more than one juggler. If you are doing a standard ground state passing pattern (see definition below; an example is <3p|3p><3|3> for six objects), then by definition you and your partner can switch into any ground state pattern instantly with no transition throws. However, many siteswap patterns will require you both to start throwing differently at the same time.

An analagous situation with a single juggler is if I wanted to switch from the pattern (4,4) into (4x,4x). No transition throws would be required, but both of my hands would have to start throwing 4x's at exactly the same time. There is no issue with communication/synchronization when a single juggler is controlling the entire pattern, but it can be an issue in passing. Pattern transitions that require immediate change in throwing behavior from several jugglers typically require the jugglers to count down to the pattern transition in order to ensure synchronization.

It is nice to allow for a communication delay, though, so that person #2 has time to react when person #1 starts throwing a trick (many of the popular passing tricks have this property). This is what this setting determines. The number you input is the number of throws after the beginning of the trick before person #2 needs to throw something different from what he was while doing a standard ground state pattern (like <3p|3p><3|3>).

A few words need to be said about what constitutes a "standard ground state pattern". These are those patterns composed of ground state patterns of length 1. For 6 objects, for example, run the generator with the settings: (balls=6, max throw=4, period=1, jugglers=2, find=ground). You get two ground state patterns of length 1: <3|3> and <3p|3p>. Any combination of these stuck together qualifies as a "standard ground state pattern"; these include standard two-count passing <3p|3p><3|3>, ultimate passing <3p|3p>, and so on. The delay flag lists all patterns which provide the requested communication delay for at least one of these "standard passing patterns". Whew, this is complicated.

As an example, run the generator with settings: (balls=6, max throw=4, period=3, jugglers=2, find=ground, delay=2). (Note that the "excited state patterns" box must be unchecked for the communications delay field to become active.) The list includes the following two patterns; the juggler in the left slot is the one "leading" the tricks:

                  <4|3p><4p|3><3|1>
                        which assumes the people were doing the
                        standard <3p|3p><3|3> before the trick was
                        being done.  Note that person #1 has to begin
                        when his partner is throwing a pass.

                  <4p|3p><4p|3p><3|1>
                        which assumes the people were ultimate
                        passing before starting the trick.

Some of the patterns will require a 2-count passing pattern to get the requested communication delay, others a 3-count, and so on. When you use this feature just scan the list for the patterns relevant to your case.

As a final example, run the generator with settings: (balls=6, max throw=3, period=3, jugglers=2, find=ground, multiplexing=enabled, # allowed throws=2, delay=3). One of the patterns is the popular "left-hand single" multiplexing pattern: <2|3p><2p|3><[3p/2]|3p>. Note that the communication delay setting of 3 has vastly reduced the number of tricks found.

Tips on using the siteswap generator

In general the number of siteswap patterns is very large, larger than you can possibly sift through in a lifetime. To find interesting patterns, the challenge is to constrain your search as much as possible. If you give the generator parameters that are too broad, it will automatically stop rather than run indefinitely (the limits are 1000 patterns found or 15 seconds elapsed, whichever comes first). If you want to do longer searches, run Juggling Lab from the command line where there are no limits on time and pattern count.

Some general tips on constraining the search:

1. Don't make the "max throw" value larger than it needs to be.
2. Exclude as many throw values as possible for self-throws and passes. For example, I tend to avoid '3's in 5-ball patterns. I also might exclude the '1p' and '2p' fast-passes.
3. When multiplexing, limit the number of simultaneous throws and use the "no simultaneous catches" and "no clustered throws" options if you can. Multiplexing makes the number of patterns grow enormously.
4. Try using the "no compositions" option to find only prime patterns, especially in searches for long-period patterns. Most of the best siteswaps happen to be prime anyway.
5. Start with a large "passing communication delay" value if you're looking for passing tricks.