euclidean-rhythm

A Rust library for generating Euclidean rhythms using Bjorklund's algorithm.

Euclidean rhythms are mathematical patterns that distribute pulses as evenly as possible across a given number of steps. These patterns appear in traditional music from around the world and are popular in electronic music production.

Features

Generate Euclidean rhythm patterns with any number of steps and pulses
Rotate patterns to different starting positions
Convert patterns to string representations for visualization
Fast, lightweight implementation with no dependencies
Well-tested with property-based tests

Installation

Add this to your Cargo.toml:

[dependencies]
euclidean-rhythm = "0.1.0"

Usage

Basic Pattern Generation

use euclidean_rhythm::euclidean;

// Generate a tresillo rhythm (3 pulses in 8 steps)
let pattern = euclidean(8, 3, 0);
// Result: [true, false, false, true, false, false, true, false]

Pattern Visualization

use euclidean_rhythm::{euclidean, pattern_to_string};

let pattern = euclidean(8, 3, 0);
println!("{}", pattern_to_string(&pattern, 'x', '.'));
// Output: x..x..x.

// Or use different characters
println!("{}", pattern_to_string(&pattern, '1', '0'));
// Output: 10010010

Pattern Rotation

use euclidean_rhythm::euclidean;

// Rotate the pattern by 2 steps
let pattern = euclidean(8, 3, 2);
// Result: [false, true, false, false, true, false, true, false]

// Rotation wraps around (10 % 8 = 2)
let pattern2 = euclidean(8, 3, 10);
assert_eq!(pattern, pattern2);

Musical Examples

The library generates well-known rhythmic patterns from various musical traditions:

use euclidean_rhythm::{euclidean, pattern_to_string};

// Tresillo - Common in Latin music (Cuba, Haiti)
let tresillo = euclidean(8, 3, 0);
println!("Tresillo:          {}", pattern_to_string(&tresillo, 'x', '.'));
// Output: x..x..x.

// West African bell pattern
let bell = euclidean(8, 5, 0);
println!("West African Bell: {}", pattern_to_string(&bell, 'x', '.'));
// Output: x.xx.xx.

// Persian rhythm
let persian = euclidean(12, 5, 0);
println!("Persian:           {}", pattern_to_string(&persian, 'x', '.'));
// Output: x..x.x..x.x.

// Bossa Nova rhythm
let bossa = euclidean(16, 7, 0);
println!("Bossa Nova:        {}", pattern_to_string(&bossa, 'x', '.'));
// Output: x..x.x.x..x.x.x.

Algorithm

This library implements Bjorklund's algorithm, which generates maximally even distributions of pulses. The algorithm works by:

Starting with separate groups of pulses and rests
Repeatedly pairing groups together
Concatenating pairs until a single pattern emerges

This produces rhythms where pulses are distributed as evenly as possible, which is why these patterns sound natural and appear in traditional music worldwide.

API Reference

`euclidean(steps: u8, pulses: u8, rotation: u8) -> Vec<bool>`

Generates a Euclidean rhythm pattern.

Parameters:

steps - Total number of steps in the pattern (must be > 0)
pulses - Number of pulses to distribute (must be ≤ steps)
rotation - Number of positions to rotate the pattern (wraps with modulo)

Returns:

A Vec<bool> where true represents a pulse and false represents a rest

Panics:

Panics if steps == 0 or pulses > steps

`pattern_to_string(pattern: &[bool], pulse_char: char, rest_char: char) -> String`

Converts a boolean pattern to a string representation.

Parameters:

pattern - The pattern to convert
pulse_char - Character to represent pulses (true values)
rest_char - Character to represent rests (false values)

Returns:

A String with the pattern visualized using the specified characters

Testing

Run the test suite:

cargo test

The library includes:

Unit tests for known musical patterns
Property-based tests (528 test cases)
Edge case tests (empty patterns, full patterns, rotation)
Panic tests for invalid inputs

References

The Euclidean Algorithm Generates Traditional Musical Rhythms by Godfried Toussaint
Bjorklund's Algorithm

License

This project is released into the public domain. See LICENSE for details.

Contributing

Contributions are welcome! Please feel free to submit a Pull Request.

euclidean-rhythm 0.1.0