subsequence 0.6.4__py3-none-any.whl

subsequence/cadences.py

@@ -0,0 +1,113 @@
+"""Cadences — the curated formula table behind the producer cadence names.
+
+A cadence is a two-chord tail formula plus a melodic close degree.  The
+producer names are primary — ``"strong"``, ``"soft"``, ``"open"``,
+``"fakeout"`` — with the theory names (authentic, plagal, half, deceptive)
+accepted as aliases, per the standing rule: theory machinery under the hood,
+producer words on the surface.
+
+The table is pure data; the consumers wire it in:
+
+- ``Progression.cadence(name)`` — tail substitution on a progression value.
+- ``Progression.generate(cadence=)`` / ``freeze(cadence=)`` — the formula
+  becomes pins on the final bars of the constrained walk.
+- ``Motif.generate(cadence=)`` — the close degree becomes ``end_on``.
+- ``Composition.request_cadence()`` / ``section_cadence()`` — the live
+  clock steers its walk to arrive at the formula.
+- ``sentence()`` / ``period()`` — the close degree aims the final unit.
+
+Formula elements follow the progression-element grammar: ints are diatonic
+degrees (quality inferred from key+scale at resolution time — ``4`` is IV
+in major and iv in minor), roman strings carry their quality with them
+(``"V"`` is the major dominant even in minor — the cadential convention).
+"""
+
+import dataclasses
+import typing
+
+
+@dataclasses.dataclass(frozen=True)
+class Cadence:
+
+	"""One cadence formula — a named tail plus its melodic close.
+
+	Attributes:
+		name: The producer name (the primary key in the table).
+		theory_name: The traditional name, for the curious.
+		formula: The chord tail, in progression-element grammar, ending on
+			the arrival chord.
+		close_degree: The scale degree a melody lands on at this cadence
+			(1 for full closes; 5 for the open half — and 1 for the
+			fakeout too: the melody resolves as promised while the
+			harmony swerves, which is the trick of it).
+	"""
+
+	name: str
+	theory_name: str
+	formula: typing.Tuple[typing.Any, ...]
+	close_degree: int
+
+
+# The curated table — producer names primary.  Two-chord tails throughout:
+# a cadence is an arrival WITH its approach, and two chords is the smallest
+# honest spelling of that.
+CADENCES: typing.Dict[str, Cadence] = {
+	"strong": Cadence(
+		name = "strong",
+		theory_name = "authentic",
+		formula = ("V", 1),
+		close_degree = 1,
+	),
+	"soft": Cadence(
+		name = "soft",
+		theory_name = "plagal",
+		formula = (4, 1),
+		close_degree = 1,
+	),
+	"open": Cadence(
+		name = "open",
+		theory_name = "half",
+		formula = (4, "V"),
+		close_degree = 5,
+	),
+	"fakeout": Cadence(
+		name = "fakeout",
+		theory_name = "deceptive",
+		formula = ("V", 6),
+		close_degree = 1,
+	),
+}
+
+# Theory names as aliases — accuracy costs nothing here, the words name the
+# same formulas.
+_ALIASES: typing.Dict[str, str] = {
+	"authentic": "strong",
+	"perfect": "strong",
+	"plagal": "soft",
+	"half": "open",
+	"deceptive": "fakeout",
+	"interrupted": "fakeout",
+}
+
+
+def cadence_formula (name: str) -> Cadence:
+
+	"""Look up a cadence by producer name or theory alias, loudly.
+
+	Raises:
+		ValueError: If the name is unknown — the error lists every valid
+			name and alias.
+	"""
+
+	if not isinstance(name, str):
+		raise TypeError(f"a cadence is named by string, got {name!r}")
+
+	key = name.strip().lower()
+	key = _ALIASES.get(key, key)
+
+	if key not in CADENCES:
+		names = ", ".join(sorted(CADENCES))
+		aliases = ", ".join(sorted(_ALIASES))
+		raise ValueError(f"Unknown cadence {name!r}. Cadences: {names} (aliases: {aliases}).")
+
+	return CADENCES[key]

subsequence/chord_graphs/__init__.py

@@ -0,0 +1,100 @@
+"""
+Chord graph builders for different harmonic transition models.
+"""
+
+import abc
+import typing
+
+import subsequence.chords
+import subsequence.intervals
+import subsequence.weighted_graph
+
+
+# Shared transition weights used by all chord graph builders.
+WEIGHT_STRONG = 6
+WEIGHT_MEDIUM = 4
+WEIGHT_COMMON = 3
+WEIGHT_DECEPTIVE = 2
+WEIGHT_WEAK = 1
+
+
+class ChordGraph (abc.ABC):
+
+	"""Abstract base for chord transition graphs."""
+
+	@abc.abstractmethod
+	def build (self, key_name: str) -> typing.Tuple[subsequence.weighted_graph.WeightedGraph[subsequence.chords.Chord], subsequence.chords.Chord]:
+
+		"""Build the weighted graph and return it with the tonic chord."""
+
+		...
+
+	@abc.abstractmethod
+	def gravity_sets (self, key_name: str) -> typing.Tuple[typing.Set[subsequence.chords.Chord], typing.Set[subsequence.chords.Chord]]:
+
+		"""Return (diatonic_set, functional_set) for key gravity weighting."""
+
+		...
+
+
+def validate_key_name (key_name: str) -> int:
+
+	"""Validate a key name and return its pitch class.
+
+	Raises ValueError if the key name is not recognised.
+
+	Parameters:
+		key_name: Note name (e.g., ``"C"``, ``"F#"``, ``"Bb"``)
+
+	Returns:
+		Pitch class integer (0-11)
+	"""
+
+	return subsequence.chords.key_name_to_pc(key_name)
+
+
+def build_diatonic_chords (scale_pcs: typing.List[int], degree_qualities: typing.List[str]) -> typing.List[subsequence.chords.Chord]:
+
+	"""Build chords for each scale degree.
+
+	Parameters:
+		scale_pcs: Pitch class for each degree (e.g., from ``scale_pitch_classes(key_pc, mode)``)
+		degree_qualities: Chord quality for each degree (e.g., ``["major", "minor", ...]``)
+
+	Returns:
+		List of Chord objects, one per scale degree
+	"""
+
+	chords: typing.List[subsequence.chords.Chord] = []
+
+	for root_pc, quality in zip(scale_pcs, degree_qualities):
+		chords.append(subsequence.chords.Chord(root_pc=root_pc, quality=quality))
+
+	return chords
+
+
+def _major_key_gravity_sets (key_name: str) -> typing.Tuple[typing.Set[subsequence.chords.Chord], typing.Set[subsequence.chords.Chord]]:
+
+	"""Return diatonic and functional chord sets for a major key."""
+
+	key_pc = validate_key_name(key_name)
+	scale_pcs = subsequence.intervals.scale_pitch_classes(key_pc, "ionian")
+
+	chords = build_diatonic_chords(scale_pcs, subsequence.intervals.IONIAN_QUALITIES)
+	diatonic: typing.Set[subsequence.chords.Chord] = set(chords)
+
+	# Functional set: I, ii, V, V7.
+	function_intervals = [0, 2, 7]
+	function_qualities = ["major", "minor", "major"]
+
+	function_chords: typing.Set[subsequence.chords.Chord] = set()
+
+	for interval, quality in zip(function_intervals, function_qualities):
+		root_pc = (key_pc + interval) % 12
+		function_chords.add(subsequence.chords.Chord(root_pc=root_pc, quality=quality))
+
+	dominant_7th = subsequence.chords.Chord(root_pc=(key_pc + 7) % 12, quality="dominant_7th")
+	function_chords.add(dominant_7th)
+	diatonic.add(dominant_7th)
+
+	return diatonic, function_chords

subsequence/chord_graphs/aeolian_minor.py

@@ -0,0 +1,158 @@
+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
+WEIGHT_WEAK = subsequence.chord_graphs.WEIGHT_WEAK
+
+# Minor-specific weights.
+WEIGHT_PHRYGIAN = 5
+WEIGHT_PLAGAL = 4
+
+
+class AeolianMinor (subsequence.chord_graphs.ChordGraph):
+
+	"""Natural minor (Aeolian) graph with Phrygian and harmonic minor elements.
+
+	Focuses on the interplay between the natural minor scale and its
+	common variations:
+
+	- Aeolian (i, iv, v, bVI, bVII)
+	- Harmonic Minor (V, vii°) for stronger cadences
+	- Phrygian (bII) for tension
+
+	Suitable for a wide range of minor-key styles.
+	"""
+
+	def __init__ (self, include_dominant_7th: bool = True) -> None:
+
+		"""Configure whether to include dominant seventh chords."""
+
+		self.include_dominant_7th = include_dominant_7th
+
+	def build (self, key_name: str) -> typing.Tuple[subsequence.weighted_graph.WeightedGraph[subsequence.chords.Chord], subsequence.chords.Chord]:
+
+		"""Build an Aeolian minor-key graph."""
+
+		key_pc = subsequence.chord_graphs.validate_key_name(key_name)
+
+		# Natural minor scale: 0, 2, 3, 5, 7, 8, 10
+		tonic = subsequence.chords.Chord(root_pc=key_pc, quality="minor")
+		supertonic_dim = subsequence.chords.Chord(root_pc=(key_pc + 2) % 12, quality="diminished")
+		mediant = subsequence.chords.Chord(root_pc=(key_pc + 3) % 12, quality="major")
+		subdominant = subsequence.chords.Chord(root_pc=(key_pc + 5) % 12, quality="minor")
+		natural_dominant = subsequence.chords.Chord(root_pc=(key_pc + 7) % 12, quality="minor")
+		submediant = subsequence.chords.Chord(root_pc=(key_pc + 8) % 12, quality="major")
+		subtonic = subsequence.chords.Chord(root_pc=(key_pc + 10) % 12, quality="major")
+
+		# Harmonic minor additions.
+		dominant = subsequence.chords.Chord(root_pc=(key_pc + 7) % 12, quality="major")
+		leading_dim = subsequence.chords.Chord(root_pc=(key_pc + 11) % 12, quality="diminished")
+
+		# Phrygian/Neapolitan flat-two.
+		flat_two = subsequence.chords.Chord(root_pc=(key_pc + 1) % 12, quality="major")
+
+		graph: subsequence.weighted_graph.WeightedGraph[subsequence.chords.Chord] = subsequence.weighted_graph.WeightedGraph()
+
+		# --- Tonic departures ---
+		graph.add_transition(tonic, subdominant, WEIGHT_PLAGAL)
+		graph.add_transition(tonic, submediant, WEIGHT_COMMON)
+		graph.add_transition(tonic, subtonic, WEIGHT_COMMON)
+		graph.add_transition(tonic, flat_two, WEIGHT_WEAK)
+		graph.add_transition(tonic, natural_dominant, WEIGHT_COMMON)
+
+		# --- Natural dominant (v) departures ---
+		graph.add_transition(natural_dominant, submediant, WEIGHT_COMMON)
+		graph.add_transition(natural_dominant, subdominant, WEIGHT_COMMON)
+		graph.add_transition(natural_dominant, tonic, WEIGHT_WEAK)
+
+		# --- Minor plagal ---
+		graph.add_transition(subdominant, tonic, WEIGHT_PLAGAL, label="soft")
+		graph.add_transition(subdominant, dominant, WEIGHT_MEDIUM, label="open")
+		graph.add_transition(subdominant, submediant, WEIGHT_WEAK)
+
+		# --- Aeolian cycle: i -> bVI -> bVII -> i ---
+		graph.add_transition(submediant, subtonic, WEIGHT_MEDIUM)
+		graph.add_transition(subtonic, tonic, WEIGHT_MEDIUM)
+
+		# --- Andalusian descent: i -> bVII -> bVI -> V ---
+		graph.add_transition(subtonic, submediant, WEIGHT_COMMON)
+		graph.add_transition(submediant, dominant, WEIGHT_MEDIUM)
+
+		# --- Phrygian cadence: bII -> i ---
+		graph.add_transition(flat_two, tonic, WEIGHT_PHRYGIAN)
+		graph.add_transition(flat_two, dominant, WEIGHT_COMMON)
+
+		# --- Harmonic minor cadence: V -> i ---
+		graph.add_transition(dominant, tonic, WEIGHT_STRONG, label="strong")
+		graph.add_transition(dominant, submediant, WEIGHT_DECEPTIVE, label="fakeout")
+
+		# --- Chromatic connectors ---
+		graph.add_transition(supertonic_dim, dominant, WEIGHT_MEDIUM)
+		graph.add_transition(leading_dim, tonic, WEIGHT_STRONG)
+		graph.add_transition(mediant, submediant, WEIGHT_COMMON)
+		graph.add_transition(mediant, subdominant, WEIGHT_WEAK)
+
+		# Reach the diatonic chords that previously had only outgoing edges, as
+		# occasional colour:
+		#   i  → bIII — the relative major, a staple minor-key move.
+		#   iv → ii°  — predominant into the supertonic dim (which then goes to V).
+		#   iv → vii° — predominant into the harmonic-minor leading-tone triad (→ i).
+		graph.add_transition(tonic, mediant, WEIGHT_WEAK)
+		graph.add_transition(subdominant, supertonic_dim, WEIGHT_WEAK)
+		graph.add_transition(subdominant, leading_dim, WEIGHT_WEAK)
+
+		# --- Optional dominant seventh ---
+		if self.include_dominant_7th:
+			dominant_7th = subsequence.chords.Chord(root_pc=(key_pc + 7) % 12, quality="dominant_7th")
+
+			graph.add_transition(dominant, dominant_7th, WEIGHT_WEAK)
+			graph.add_transition(dominant_7th, tonic, WEIGHT_STRONG, label="strong")
+			graph.add_transition(dominant_7th, submediant, WEIGHT_DECEPTIVE, label="fakeout")
+
+		return graph, tonic
+
+	def gravity_sets (self, key_name: str) -> typing.Tuple[typing.Set[subsequence.chords.Chord], typing.Set[subsequence.chords.Chord]]:
+
+		"""Return minor-key diatonic and functional chord sets."""
+
+		key_pc = subsequence.chord_graphs.validate_key_name(key_name)
+
+		diatonic: typing.Set[subsequence.chords.Chord] = set(
+			subsequence.chord_graphs.build_diatonic_chords(
+				subsequence.intervals.scale_pitch_classes(key_pc, "aeolian"),
+				subsequence.intervals.AEOLIAN_QUALITIES
+			)
+		)
+
+		# Harmonic minor V (major) and bII (Phrygian).
+		dominant_pc = (key_pc + 7) % 12
+		flat_two_pc = (key_pc + 1) % 12
+
+		diatonic.add(subsequence.chords.Chord(root_pc=dominant_pc, quality="major"))
+		diatonic.add(subsequence.chords.Chord(root_pc=flat_two_pc, quality="major"))
+
+		# Harmonic-minor leading-tone triad vii° — now reachable in the graph, so
+		# list it as a diatonic candidate for gravity weighting too.
+		diatonic.add(subsequence.chords.Chord(root_pc=(key_pc + 11) % 12, quality="diminished"))
+
+		dominant_7th = subsequence.chords.Chord(root_pc=dominant_pc, quality="dominant_7th")
+		diatonic.add(dominant_7th)
+
+		# Functional set: i, iv, V(/V7), bII.
+		functional: typing.Set[subsequence.chords.Chord] = set()
+
+		functional.add(subsequence.chords.Chord(root_pc=key_pc, quality="minor"))
+		functional.add(subsequence.chords.Chord(root_pc=(key_pc + 5) % 12, quality="minor"))
+		functional.add(subsequence.chords.Chord(root_pc=dominant_pc, quality="major"))
+		functional.add(subsequence.chords.Chord(root_pc=flat_two_pc, quality="major"))
+		functional.add(dominant_7th)
+
+		return diatonic, functional

subsequence/chord_graphs/chromatic_mediant.py

@@ -0,0 +1,113 @@
+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
+
+# Mediant-specific weight for the signature third-relation shifts.
+WEIGHT_MEDIANT = 5
+
+
+class ChromaticMediant (subsequence.chord_graphs.ChordGraph):
+
+	"""Chromatic third-related harmony - roots move by major or minor thirds.
+
+	Many transitions connect chords whose roots are a major or minor third
+	apart (the characteristic motion); others are chromatic, fourth-, or
+	fifth-related, creating dramatic, colorful shifts that sound both surprising
+	and connected through shared common tones. No dominant-tonic functional
+	motion is used; the one subdominant-tonic edge is the minor-plagal
+	iv → I close from the subdominant-minor connector.
+
+	Good for cinematic, ambient, soundtrack, and experimental music.
+	"""
+
+	def build (self, key_name: str) -> typing.Tuple[subsequence.weighted_graph.WeightedGraph[subsequence.chords.Chord], subsequence.chords.Chord]:
+
+		"""Build a chromatic mediant graph with third-related root movement."""
+
+		key_pc = subsequence.chord_graphs.validate_key_name(key_name)
+
+		# Core chords - major and minor triads at third-related intervals.
+		tonic = subsequence.chords.Chord(root_pc=key_pc, quality="major")
+		flat_mediant = subsequence.chords.Chord(root_pc=(key_pc + 3) % 12, quality="major")
+		mediant = subsequence.chords.Chord(root_pc=(key_pc + 4) % 12, quality="major")
+		flat_submediant = subsequence.chords.Chord(root_pc=(key_pc + 8) % 12, quality="major")
+		submediant = subsequence.chords.Chord(root_pc=(key_pc + 9) % 12, quality="major")
+
+		# Minor variants for color contrast.
+		tonic_minor = subsequence.chords.Chord(root_pc=key_pc, quality="minor")
+		subdominant_minor = subsequence.chords.Chord(root_pc=(key_pc + 5) % 12, quality="minor")
+
+		graph: subsequence.weighted_graph.WeightedGraph[subsequence.chords.Chord] = subsequence.weighted_graph.WeightedGraph()
+
+		# --- Tonic departures (by thirds) ---
+		graph.add_transition(tonic, flat_mediant, WEIGHT_MEDIANT)
+		graph.add_transition(tonic, mediant, WEIGHT_MEDIANT)
+		graph.add_transition(tonic, flat_submediant, WEIGHT_COMMON)
+		graph.add_transition(tonic, submediant, WEIGHT_COMMON)
+		graph.add_transition(tonic, tonic_minor, WEIGHT_WEAK)
+
+		# --- Flat mediant (bIII) departures ---
+		graph.add_transition(flat_mediant, tonic, WEIGHT_MEDIANT)
+		graph.add_transition(flat_mediant, flat_submediant, WEIGHT_COMMON)
+		graph.add_transition(flat_mediant, submediant, WEIGHT_MEDIUM)
+
+		# --- Mediant (III) departures ---
+		graph.add_transition(mediant, tonic, WEIGHT_MEDIANT)
+		graph.add_transition(mediant, flat_submediant, WEIGHT_MEDIUM)
+		graph.add_transition(mediant, submediant, WEIGHT_COMMON)
+		graph.add_transition(mediant, flat_mediant, WEIGHT_WEAK)
+
+		# --- Flat submediant (bVI) departures ---
+		graph.add_transition(flat_submediant, tonic, WEIGHT_MEDIANT)
+		graph.add_transition(flat_submediant, mediant, WEIGHT_COMMON)
+		graph.add_transition(flat_submediant, flat_mediant, WEIGHT_COMMON)
+		graph.add_transition(flat_submediant, subdominant_minor, WEIGHT_WEAK)
+
+		# --- Submediant (VI) departures ---
+		graph.add_transition(submediant, tonic, WEIGHT_MEDIUM)
+		graph.add_transition(submediant, mediant, WEIGHT_COMMON)
+		graph.add_transition(submediant, flat_mediant, WEIGHT_COMMON)
+		graph.add_transition(submediant, flat_submediant, WEIGHT_WEAK)
+
+		# --- Tonic minor departures ---
+		graph.add_transition(tonic_minor, flat_mediant, WEIGHT_MEDIANT)
+		graph.add_transition(tonic_minor, flat_submediant, WEIGHT_COMMON)
+		graph.add_transition(tonic_minor, tonic, WEIGHT_MEDIUM)
+
+		# --- Subdominant minor (iv) connector ---
+		graph.add_transition(subdominant_minor, tonic, WEIGHT_MEDIUM)
+		graph.add_transition(subdominant_minor, flat_submediant, WEIGHT_COMMON)
+		graph.add_transition(subdominant_minor, flat_mediant, WEIGHT_WEAK)
+
+		return graph, tonic
+
+	def gravity_sets (self, key_name: str) -> typing.Tuple[typing.Set[subsequence.chords.Chord], typing.Set[subsequence.chords.Chord]]:
+
+		"""Return chromatic mediant diatonic and functional chord sets."""
+
+		key_pc = subsequence.chord_graphs.validate_key_name(key_name)
+
+		# All chords in the graph form the "diatonic" set for gravity.
+		diatonic: typing.Set[subsequence.chords.Chord] = set()
+
+		for interval in [0, 3, 4, 8, 9]:
+			diatonic.add(subsequence.chords.Chord(root_pc=(key_pc + interval) % 12, quality="major"))
+
+		diatonic.add(subsequence.chords.Chord(root_pc=key_pc, quality="minor"))
+		diatonic.add(subsequence.chords.Chord(root_pc=(key_pc + 5) % 12, quality="minor"))
+
+		# Functional set: I, bIII, bVI (strongest mediant poles).
+		functional: typing.Set[subsequence.chords.Chord] = set()
+
+		functional.add(subsequence.chords.Chord(root_pc=key_pc, quality="major"))
+		functional.add(subsequence.chords.Chord(root_pc=(key_pc + 3) % 12, quality="major"))
+		functional.add(subsequence.chords.Chord(root_pc=(key_pc + 8) % 12, quality="major"))
+
+		return diatonic, functional

subsequence/chord_graphs/diminished.py

@@ -0,0 +1,97 @@
+import typing
+
+import subsequence.chord_graphs
+import subsequence.chords
+import subsequence.weighted_graph
+
+
+WEIGHT_SYMMETRY = 5
+WEIGHT_ESCAPE = 4
+WEIGHT_RESOLVE = 4
+WEIGHT_COMMON = subsequence.chord_graphs.WEIGHT_COMMON
+
+
+class Diminished (subsequence.chord_graphs.ChordGraph):
+
+	"""Diminished chord graph with minor-third symmetry and chromatic escapes.
+
+	Two chord types interlock:
+
+	- 4 diminished triads at roots 0, 3, 6, 9 (the symmetry backbone — the
+	  minor-third cycle that also underpins the half-whole diminished scale)
+	- 4 dominant 7th chords at roots 1, 4, 7, 10 (escape chords)
+
+	Diminished chords connect to each other by minor thirds (the defining
+	rotation). Each dominant 7th sits a half step ABOVE its diminished
+	chord as a chromatic tension point — deliberately outside the
+	half-whole scale on the key root, which is what gives the escape its
+	lift before the half-step-down resolve. The result is angular,
+	disorienting, and cyclical - useful for dark techno, industrial, and
+	experimental electronic music.
+	"""
+
+	def build (self, key_name: str) -> typing.Tuple[subsequence.weighted_graph.WeightedGraph[subsequence.chords.Chord], subsequence.chords.Chord]:
+
+		"""Build an octatonic graph with diminished and dominant 7th chords."""
+
+		key_pc = subsequence.chord_graphs.validate_key_name(key_name)
+
+		# Four diminished triads, each a minor third apart.
+		dim_roots = [(key_pc + i) % 12 for i in [0, 3, 6, 9]]
+		dim_chords = [subsequence.chords.Chord(root_pc=r, quality="diminished") for r in dim_roots]
+
+		# Four dominant 7th chords, each a half step above a diminished chord.
+		dom_roots = [(key_pc + i) % 12 for i in [1, 4, 7, 10]]
+		dom_chords = [subsequence.chords.Chord(root_pc=r, quality="dominant_7th") for r in dom_roots]
+
+		graph: subsequence.weighted_graph.WeightedGraph[subsequence.chords.Chord] = subsequence.weighted_graph.WeightedGraph()
+
+		# --- Diminished ↔ diminished (minor third rotation) ---
+		for i, source in enumerate(dim_chords):
+			for j, target in enumerate(dim_chords):
+				if i != j:
+					graph.add_transition(source, target, WEIGHT_SYMMETRY)
+
+		# --- Diminished → dominant 7th (half step up = escape) ---
+		for i in range(4):
+			graph.add_transition(dim_chords[i], dom_chords[i], WEIGHT_ESCAPE)
+
+		# --- Dominant 7th → diminished (half step down = resolve) ---
+		for i in range(4):
+			graph.add_transition(dom_chords[i], dim_chords[i], WEIGHT_RESOLVE)
+
+		# --- Dominant 7th ↔ dominant 7th (minor third rotation) ---
+		for i, source in enumerate(dom_chords):
+			for j, target in enumerate(dom_chords):
+				if i != j:
+					graph.add_transition(source, target, WEIGHT_COMMON)
+
+		tonic = dim_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 octatonic diatonic and functional chord sets."""
+
+		key_pc = subsequence.chord_graphs.validate_key_name(key_name)
+
+		diatonic: typing.Set[subsequence.chords.Chord] = set()
+
+		# Gravity treats the full 8-chord palette as "home": the dominant
+		# escapes are included by design even though they sit outside the
+		# half-whole scale on the key root (they are the graph's tension
+		# vocabulary, not foreign territory to be damped).
+		for i in [0, 3, 6, 9]:
+			diatonic.add(subsequence.chords.Chord(root_pc=(key_pc + i) % 12, quality="diminished"))
+
+		for i in [1, 4, 7, 10]:
+			diatonic.add(subsequence.chords.Chord(root_pc=(key_pc + i) % 12, quality="dominant_7th"))
+
+		# Functional: the 4 diminished chords (symmetry backbone).
+		functional: typing.Set[subsequence.chords.Chord] = set()
+
+		for i in [0, 3, 6, 9]:
+			functional.add(subsequence.chords.Chord(root_pc=(key_pc + i) % 12, quality="diminished"))
+
+		return diatonic, functional