shuffle-go

Shuffle-Go

Shuffle-Go is a constraint-based list randomizer written in Go. It creates randomized sequences while respecting sequential constraints (e.g., max repetitions, minimum gap), making it ideal for experimental stimuli generation.

Constraint Support: Limit consecutive repetitions (Max Repetitions) or ensure minimum distance between identical items (Min Gap).
Dual Algorithms: Fast Constructive (greedy) or Equiprobable (brute-force filtering) for unbiased permutations.
Multiple Interfaces: Native GUI (Gio), Cross-platform GUI (Fyne), and a scriptable CLI.

Read the Paper

Download Releases

Quick Start

1. Download & Install

Download the latest version for your platform from the Releases page.

Platform	Recommended File	Note
Windows	`...-setup.exe`	Standard installer; creates desktop shortcut.
macOS	`...-app.zip`	Extract and move `Shuffle-Go.app` to Applications. See security note.
Linux	`.AppImage`	Make executable (`chmod +x`) and run.

2. Usage

GUI (Recommended): Launch shuffle-gio. Import your .txt or .csv, set constraints, and click Shuffle!.
CLI: Use shuffle-cli for scripts and automation.

Constraints Syntax

Constraints are defined per column (space-separated):

n (Positive): Max consecutive repetitions of the same label.
-m (Negative): Min gap (intervening rows) between identical labels.
0: No constraints for this column.

Example: -c "1 -4" means Column 1 has no adjacent identical labels, and Column 2 requires at least 4 items between repeats.

CLI Tool Reference

./shuffle-cli [flags] < [input_file]

Flag	Description	Default
`-c`	Constraints string (e.g., `"1 2 -3"`)	`""`
`-d`	Field delimiter (whitespace, `,`, etc.)	whitespace
`-e`	Use equiprobable algorithm (slower)	false
`-n`	Limit output to `n` lines	all
`-s`	Random seed for reproducibility	0 (random)

Library Integration

Use the core logic in your own Go projects:

import "github.com/chrplr/shuffle-go"

shuffler := shuffle.NewShuffler(data, []shuffle.Constraint{1, -3}, seed, maxIter, limit)
result, err := shuffler.ShuffleConstructive()

Development

Build all binaries using the provided script (requires Go 1.24+):

bash build.sh

License

If you use this software, please cite this repository as:

Pallier, C. (2026). shuffle-go [Computer software]. GitHub. https://github.com/chrplr/shuffle-go

This site is open source. Improve this page.