1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
/// Generate Fibonacci sequence up to n terms
///
/// The Fibonacci sequence is one of the most famous mathematical sequences, where each
/// number is the sum of the two preceding ones: F(n) = F(n-1) + F(n-2)
///
/// Starting with 1, 1, the sequence goes: 1, 1, 2, 3, 5, 8, 13, 21, 34, 55, 89, 144...
///
/// This sequence appears throughout nature and has been used in composition since the
/// Middle Ages. The ratio between consecutive Fibonacci numbers converges to the
/// golden ratio (φ ≈ 1.618), making it naturally pleasing to human perception.
///
/// Found in:
/// - Flower petal counts (3, 5, 8, 13, 21 petals are common)
/// - Nautilus shell spirals and pine cone patterns
/// - Musical phrase lengths in classical compositions (Bartók, Debussy)
/// - Polyrhythmic relationships
///
/// # Arguments
/// * `n` - Number of Fibonacci terms to generate
///
/// # Returns
/// Vector of the first n Fibonacci numbers: [1, 1, 2, 3, 5, 8, 13, ...]
///
/// # Typical Values
/// - **n = 5-8**: Good for short phrases and melodic fragments
/// - **n = 10-12**: Medium-length sequences, complete melodies
/// - **n = 16-20**: Long evolving patterns, song structure
/// - **n > 20**: Watch out for huge numbers (F(20)=6765), normalize to usable ranges
///
/// # Recipe: Fibonacci Melody in Key
/// ```
/// use tunes::prelude::*;
/// use tunes::sequences;
///
/// let mut comp = Composition::new(Tempo::new(120.0));
///
/// // Generate Fibonacci and map to C major scale
/// let fib = sequences::fibonacci::generate(12);
/// let melody = sequences::map_to_scale(&fib, &sequences::Scale::major(), C4, 2);
///
/// comp.instrument("fib_melody", &Instrument::pluck())
/// .delay(Delay::new(0.375, 0.3, 0.5))
/// .notes(&melody, 0.25);
/// ```
///
/// # Examples
/// ```
/// use tunes::sequences;
///
/// let fib = sequences::fibonacci::generate(8);
/// assert_eq!(fib, vec![1, 1, 2, 3, 5, 8, 13, 21]);
///
/// // Use for rhythm - note durations following Fibonacci
/// # use tunes::prelude::*;
/// # let mut comp = Composition::new(Tempo::new(120.0));
/// let durations = sequences::normalize(&fib, 0.125, 1.0);
/// for (i, &duration) in durations.iter().enumerate() {
/// comp.track("fib_rhythm")
/// .at(i as f32)
/// .note(&[440.0], duration);
/// }
///
/// // Use for phrase lengths (in beats)
/// let phrase_lengths = sequences::fibonacci::generate(5); // [1, 1, 2, 3, 5] beats
/// ```
///
/// # Musical Applications
/// - **Phrase structure**: Use Fibonacci numbers for phrase lengths (5-bar phrases, 8-bar sections)
/// - **Rhythmic patterns**: Note durations or rests following the sequence
/// - **Melodic intervals**: Map to semitone jumps for organic-sounding melodies
/// - **Formal structure**: Section lengths in larger compositions
/// - **Polyrhythms**: Layer rhythms based on different Fibonacci numbers (3 against 5, 5 against 8)
/// - **Dynamic curves**: Volume or filter changes following Fibonacci proportions
///
/// # Usage
/// ```
/// use tunes::sequences::fibonacci;
///
/// // Custom parameters
/// let seq = fibonacci::generate(12);
///
/// // Or use presets
/// let seq = fibonacci::classic();
/// ```
/// Generate Fibonacci sequence with custom length
///
/// See module-level documentation for details on the Fibonacci sequence,
/// musical applications, and typical values.
// ========== PRESETS ==========
/// Short Fibonacci sequence (6 terms) - quick phrases
/// Medium Fibonacci sequence (10 terms) - complete melodies
/// Classic Fibonacci sequence (12 terms) - balanced length
/// Long Fibonacci sequence (16 terms) - evolving patterns
/// Extended Fibonacci sequence (20 terms) - epic structures