subsequence 0.6.4__py3-none-any.whl

subsequence/chord_graphs/suspended.py

@@ -0,0 +1,109 @@
+import typing
+
+import subsequence.chord_graphs
+import subsequence.chords
+import subsequence.weighted_graph
+
+
+WEIGHT_MEDIUM = subsequence.chord_graphs.WEIGHT_MEDIUM
+WEIGHT_COMMON = subsequence.chord_graphs.WEIGHT_COMMON
+WEIGHT_WEAK = subsequence.chord_graphs.WEIGHT_WEAK
+
+# Suspended-specific weight for same-root sus2 ↔ sus4 colour changes.
+WEIGHT_COLOUR = 5
+
+
+class Suspended (subsequence.chord_graphs.ChordGraph):
+
+	"""Open harmony using suspended chords - no major or minor thirds.
+
+	All chords are sus2 or sus4, creating ambiguous, open textures.
+	Same-root sus2 ↔ sus4 movement (colour change without root movement)
+	is heavily weighted. Root movement favors fourths/fifths and whole
+	steps. A single minor tonic provides occasional grounding.
+
+	Good for ambient, post-rock, drone, and minimalist electronic music.
+	"""
+
+	def build (self, key_name: str) -> typing.Tuple[subsequence.weighted_graph.WeightedGraph[subsequence.chords.Chord], subsequence.chords.Chord]:
+
+		"""Build a suspended-chord graph with open, ambiguous harmony."""
+
+		key_pc = subsequence.chord_graphs.validate_key_name(key_name)
+
+		# Core suspended chords.
+		tonic_sus2 = subsequence.chords.Chord(root_pc=key_pc, quality="sus2")
+		tonic_sus4 = subsequence.chords.Chord(root_pc=key_pc, quality="sus4")
+		sub_sus2 = subsequence.chords.Chord(root_pc=(key_pc + 5) % 12, quality="sus2")
+		sub_sus4 = subsequence.chords.Chord(root_pc=(key_pc + 5) % 12, quality="sus4")
+		dom_sus2 = subsequence.chords.Chord(root_pc=(key_pc + 7) % 12, quality="sus2")
+		dom_sus4 = subsequence.chords.Chord(root_pc=(key_pc + 7) % 12, quality="sus4")
+		subtonic_sus2 = subsequence.chords.Chord(root_pc=(key_pc + 10) % 12, quality="sus2")
+
+		# Minor tonic as the one "resolved" chord.
+		tonic_minor = subsequence.chords.Chord(root_pc=key_pc, quality="minor")
+
+		graph: subsequence.weighted_graph.WeightedGraph[subsequence.chords.Chord] = subsequence.weighted_graph.WeightedGraph()
+
+		# --- Same-root colour changes (sus2 ↔ sus4) ---
+		graph.add_transition(tonic_sus2, tonic_sus4, WEIGHT_COLOUR)
+		graph.add_transition(tonic_sus4, tonic_sus2, WEIGHT_COLOUR)
+		graph.add_transition(sub_sus2, sub_sus4, WEIGHT_COLOUR)
+		graph.add_transition(sub_sus4, sub_sus2, WEIGHT_COLOUR)
+		graph.add_transition(dom_sus2, dom_sus4, WEIGHT_COLOUR)
+		graph.add_transition(dom_sus4, dom_sus2, WEIGHT_COLOUR)
+
+		# --- Root motion by fourths/fifths ---
+		graph.add_transition(tonic_sus2, sub_sus2, WEIGHT_MEDIUM)
+		graph.add_transition(tonic_sus4, sub_sus4, WEIGHT_MEDIUM)
+		graph.add_transition(sub_sus2, tonic_sus2, WEIGHT_MEDIUM)
+		graph.add_transition(sub_sus4, tonic_sus4, WEIGHT_MEDIUM)
+
+		graph.add_transition(tonic_sus2, dom_sus2, WEIGHT_COMMON)
+		graph.add_transition(tonic_sus4, dom_sus4, WEIGHT_COMMON)
+		graph.add_transition(dom_sus2, tonic_sus2, WEIGHT_MEDIUM)
+		graph.add_transition(dom_sus4, tonic_sus4, WEIGHT_MEDIUM)
+
+		# --- bVII whole-step motion ---
+		graph.add_transition(tonic_sus2, subtonic_sus2, WEIGHT_COMMON)
+		graph.add_transition(subtonic_sus2, tonic_sus2, WEIGHT_COMMON)
+		graph.add_transition(subtonic_sus2, sub_sus2, WEIGHT_WEAK)
+		graph.add_transition(sub_sus2, subtonic_sus2, WEIGHT_WEAK)
+
+		# --- Minor tonic as resolution ---
+		graph.add_transition(tonic_sus4, tonic_minor, WEIGHT_WEAK)
+		graph.add_transition(dom_sus4, tonic_minor, WEIGHT_WEAK)
+		graph.add_transition(tonic_minor, tonic_sus2, WEIGHT_MEDIUM)
+		graph.add_transition(tonic_minor, tonic_sus4, WEIGHT_COMMON)
+
+		# --- Cross-root colour movement ---
+		graph.add_transition(sub_sus2, dom_sus4, WEIGHT_WEAK)
+		graph.add_transition(dom_sus2, sub_sus4, WEIGHT_WEAK)
+
+		return graph, tonic_sus2
+
+	def gravity_sets (self, key_name: str) -> typing.Tuple[typing.Set[subsequence.chords.Chord], typing.Set[subsequence.chords.Chord]]:
+
+		"""Return suspended diatonic and functional chord sets."""
+
+		key_pc = subsequence.chord_graphs.validate_key_name(key_name)
+
+		# All chords in the graph form the diatonic set.
+		diatonic: typing.Set[subsequence.chords.Chord] = set()
+
+		for interval in [0, 5, 7, 10]:
+			diatonic.add(subsequence.chords.Chord(root_pc=(key_pc + interval) % 12, quality="sus2"))
+
+		for interval in [0, 5, 7]:
+			diatonic.add(subsequence.chords.Chord(root_pc=(key_pc + interval) % 12, quality="sus4"))
+
+		diatonic.add(subsequence.chords.Chord(root_pc=key_pc, quality="minor"))
+
+		# Functional set: tonic sus2/sus4 and the minor resolution.
+		functional: typing.Set[subsequence.chords.Chord] = set()
+
+		functional.add(subsequence.chords.Chord(root_pc=key_pc, quality="sus2"))
+		functional.add(subsequence.chords.Chord(root_pc=key_pc, quality="sus4"))
+		functional.add(subsequence.chords.Chord(root_pc=key_pc, quality="minor"))
+
+		return diatonic, functional

subsequence/chord_graphs/turnaround_global.py

@@ -0,0 +1,157 @@
+import typing
+
+import subsequence.chord_graphs
+import subsequence.chords
+import subsequence.intervals
+import subsequence.weighted_graph
+
+
+WEIGHT_STRONG = subsequence.chord_graphs.WEIGHT_STRONG
+WEIGHT_MEDIUM = subsequence.chord_graphs.WEIGHT_MEDIUM
+WEIGHT_COMMON = subsequence.chord_graphs.WEIGHT_COMMON
+WEIGHT_DECEPTIVE = subsequence.chord_graphs.WEIGHT_DECEPTIVE
+
+
+def _build_major_key_chords (key_pc: int) -> typing.Dict[str, subsequence.chords.Chord]:
+
+	"""Return common functional chords for a major key root."""
+
+	chords = subsequence.chord_graphs.build_diatonic_chords(
+		subsequence.intervals.scale_pitch_classes(key_pc, "ionian"),
+		subsequence.intervals.IONIAN_QUALITIES
+	)
+
+	return {
+		"I": chords[0],
+		"ii": chords[1],
+		"iii": chords[2],
+		"IV": chords[3],
+		"V": chords[4],
+		"vi": chords[5],
+		"vii": chords[6],
+	}
+
+
+def _add_turnaround_edges (
+	graph: subsequence.weighted_graph.WeightedGraph[subsequence.chords.Chord],
+	chords: typing.Dict[str, subsequence.chords.Chord],
+	include_dominant_7th: bool
+) -> None:
+
+	"""Add ii-V-I style edges for a single major key."""
+
+	tonic = chords["I"]
+	supertonic = chords["ii"]
+	submediant = chords["vi"]
+	subdominant = chords["IV"]
+	dominant = chords["V"]
+	dominant_7th = subsequence.chords.Chord(root_pc=dominant.root_pc, quality="dominant_7th")
+
+	# Decision path: allow the dominant seventh to drive stronger resolutions.
+	dominant_target = dominant_7th if include_dominant_7th else dominant
+
+	graph.add_transition(tonic, submediant, WEIGHT_COMMON)
+	graph.add_transition(submediant, supertonic, WEIGHT_COMMON)
+	graph.add_transition(supertonic, dominant_target, WEIGHT_STRONG)
+	graph.add_transition(dominant_target, tonic, WEIGHT_STRONG)
+
+	graph.add_transition(tonic, subdominant, WEIGHT_MEDIUM)
+	graph.add_transition(tonic, dominant, WEIGHT_MEDIUM)
+
+	if include_dominant_7th:
+		# Decision path: deceptive resolution only applies to dominant sevenths.
+		graph.add_transition(dominant_7th, submediant, WEIGHT_DECEPTIVE)
+
+
+def _add_minor_turnaround (
+	graph: subsequence.weighted_graph.WeightedGraph[subsequence.chords.Chord],
+	key_pc: int,
+	minor_turnaround_weight: float,
+	include_dominant_7th: bool
+) -> None:
+
+	"""Add a minor ii-V-I turnaround using a weight multiplier."""
+
+	if minor_turnaround_weight <= 0:
+		# Decision path: weight of zero disables minor turnarounds entirely.
+		return
+
+	scale_pcs = subsequence.intervals.scale_pitch_classes(key_pc, "aeolian")
+	supertonic_pc = scale_pcs[1]
+	dominant_pc = scale_pcs[4]
+	tonic_pc = scale_pcs[0]
+
+	supertonic = subsequence.chords.Chord(root_pc=supertonic_pc, quality="half_diminished_7th")
+	dominant_7th = subsequence.chords.Chord(root_pc=dominant_pc, quality="dominant_7th")
+	tonic_minor = subsequence.chords.Chord(root_pc=tonic_pc, quality="minor")
+	tonic_major = subsequence.chords.Chord(root_pc=tonic_pc, quality="major")
+
+	minor_weight_strong = max(1, int(round(WEIGHT_STRONG * minor_turnaround_weight)))
+	minor_weight_entry = max(1, int(round(WEIGHT_MEDIUM * minor_turnaround_weight)))
+
+	# Entry edges — without these the iio7 chords are unreachable and the
+	# minor turnaround can never start.  The tonic minor aliases existing
+	# diatonic nodes (e.g. C minor is the ii of Bb major), and the parallel
+	# major tonic is each key's own I, so both hooks connect the minor
+	# turnaround to the core ii-V-I graph.
+	graph.add_transition(tonic_minor, supertonic, minor_weight_strong)
+	graph.add_transition(tonic_major, supertonic, minor_weight_entry)
+
+	if include_dominant_7th:
+		graph.add_transition(supertonic, dominant_7th, minor_weight_strong)
+		graph.add_transition(dominant_7th, tonic_minor, minor_weight_strong)
+
+	else:
+		# Decision path: if dominant sevenths are disabled, resolve via the triad.
+		dominant = subsequence.chords.Chord(root_pc=dominant_pc, quality="major")
+		graph.add_transition(supertonic, dominant, minor_weight_strong)
+		graph.add_transition(dominant, tonic_minor, minor_weight_strong)
+
+
+class TurnaroundModulation (subsequence.chord_graphs.ChordGraph):
+
+	"""Global ii-V-I turnaround graph enabling modulation between all keys."""
+
+	def __init__ (self, include_dominant_7th: bool = True, minor_turnaround_weight: float = 0.0) -> None:
+
+		"""Configure dominant sevenths and minor turnaround strength."""
+
+		if minor_turnaround_weight < 0 or minor_turnaround_weight > 1:
+			raise ValueError("Minor turnaround weight must be between 0 and 1")
+
+		self.include_dominant_7th = include_dominant_7th
+		self.minor_turnaround_weight = minor_turnaround_weight
+
+	def build (self, key_name: str) -> typing.Tuple[subsequence.weighted_graph.WeightedGraph[subsequence.chords.Chord], subsequence.chords.Chord]:
+
+		"""Build the global turnaround graph for all 12 keys."""
+
+		tonic_pc = subsequence.chord_graphs.validate_key_name(key_name)
+
+		graph: subsequence.weighted_graph.WeightedGraph[subsequence.chords.Chord] = subsequence.weighted_graph.WeightedGraph()
+
+		for key_pc in range(12):
+			chords = _build_major_key_chords(key_pc)
+			_add_turnaround_edges(graph, chords, self.include_dominant_7th)
+			_add_minor_turnaround(graph, key_pc, self.minor_turnaround_weight, self.include_dominant_7th)
+		tonic = subsequence.chords.Chord(root_pc=tonic_pc, quality="major")
+
+		return graph, tonic
+
+	def gravity_sets (self, key_name: str) -> typing.Tuple[typing.Set[subsequence.chords.Chord], typing.Set[subsequence.chords.Chord]]:
+
+		"""Return major-key diatonic and functional chord sets."""
+
+		return subsequence.chord_graphs._major_key_gravity_sets(key_name)
+
+
+def build_graph (key_name: str, include_dominant_7th: bool = True, minor_turnaround_weight: float = 0.0) -> typing.Tuple[subsequence.weighted_graph.WeightedGraph[subsequence.chords.Chord], subsequence.chords.Chord]:
+
+	"""Build a global turnaround graph and return it with the chosen key tonic."""
+
+	graph_obj = TurnaroundModulation(
+		include_dominant_7th = include_dominant_7th,
+		minor_turnaround_weight = minor_turnaround_weight
+	)
+
+	return graph_obj.build(key_name)

subsequence/chord_graphs/whole_tone.py

@@ -0,0 +1,77 @@
+import typing
+
+import subsequence.chord_graphs
+import subsequence.chords
+import subsequence.weighted_graph
+
+
+WEIGHT_STEP = 4
+WEIGHT_THIRD = 3
+WEIGHT_LEAP = 2
+
+
+class WholeTone (subsequence.chord_graphs.ChordGraph):
+
+	"""Symmetrical whole-tone chord graph.
+
+	Scale: 0, 2, 4, 6, 8, 10 (six equally-spaced pitches).
+	All chords are augmented triads. Every position is equivalent  - 
+	there is no functional hierarchy, only proximity.
+
+	Step-wise motion (whole step) is weighted highest, thirds next,
+	larger leaps lowest. The result is a drifting, dreamlike quality
+	with no sense of resolution. Useful for IDM, ambient, and
+	experimental electronic music.
+	"""
+
+	def build (self, key_name: str) -> typing.Tuple[subsequence.weighted_graph.WeightedGraph[subsequence.chords.Chord], subsequence.chords.Chord]:
+
+		"""Build a fully-connected whole-tone graph."""
+
+		key_pc = subsequence.chord_graphs.validate_key_name(key_name)
+
+		# Six augmented triads, each a whole step apart.
+		roots = [(key_pc + i) % 12 for i in range(0, 12, 2)]
+		chords = [subsequence.chords.Chord(root_pc=r, quality="augmented") for r in roots]
+
+		graph: subsequence.weighted_graph.WeightedGraph[subsequence.chords.Chord] = subsequence.weighted_graph.WeightedGraph()
+
+		# Fully connected: every chord links to every other chord.
+		for i, source in enumerate(chords):
+			for j, target in enumerate(chords):
+				if i == j:
+					continue
+
+				# Distance in whole-tone steps (1-3, since the scale is symmetric).
+				step_distance = min(abs(i - j), 6 - abs(i - j))
+
+				if step_distance == 1:
+					weight = WEIGHT_STEP
+				elif step_distance == 2:
+					weight = WEIGHT_THIRD
+				else:
+					weight = WEIGHT_LEAP
+
+				graph.add_transition(source, target, weight)
+
+		tonic = chords[0]
+
+		return graph, tonic
+
+	def gravity_sets (self, key_name: str) -> typing.Tuple[typing.Set[subsequence.chords.Chord], typing.Set[subsequence.chords.Chord]]:
+
+		"""Return whole-tone diatonic and functional chord sets."""
+
+		key_pc = subsequence.chord_graphs.validate_key_name(key_name)
+
+		roots = [(key_pc + i) % 12 for i in range(0, 12, 2)]
+		diatonic: typing.Set[subsequence.chords.Chord] = set()
+
+		for r in roots:
+			diatonic.add(subsequence.chords.Chord(root_pc=r, quality="augmented"))
+
+		# Minimal functional pull - only the tonic augmented chord.
+		functional: typing.Set[subsequence.chords.Chord] = set()
+		functional.add(subsequence.chords.Chord(root_pc=key_pc, quality="augmented"))
+
+		return diatonic, functional