Mode¶

mode ¶

The seven diatonic modes.

The Mode namespace provides the 7 modes of the major scale (ionian, dorian, phrygian, lydian, mixolydian, aeolian, locrian) with their characteristic triad and seventh chord qualities, plus operations for finding relative-mode tonics.

Each mode has an alt field representing its position on the circle of fifths relative to ionian (0). This drives distance and relative_tonic.

Example

from tonal_py import Mode Mode.get("dorian").triad 'm' Mode.notes("dorian", "D") ['D', 'E', 'F', 'G', 'A', 'B', 'C'] Mode.relative_tonic("dorian", "ionian", "C") 'D'

Source parity: @tonaljs/mode

get ¶

get(name: Any) -> Mode

Get a mode by name or alias.

Recognized names: ionian, dorian, phrygian, lydian, mixolydian, aeolian, locrian. The aliases major (for ionian) and minor (for aeolian) also work.

Parameters:

Name	Type	Description	Default
`name`	`Any`	A mode name string (case-insensitive), or an object with a `.name` attribute.	required

Returns:

Type	Description
`Mode`	A `Mode` dataclass. Returns `NO_MODE` for unknown input.

Example

from tonal_py import Mode Mode.get("dorian").alt 2 Mode.get("MAJOR").name # case-insensitive, alias for ionian 'ionian' Mode.get("notamode").empty True

Source code in src/tonal_py/mode.py

def get(name: Any) -> Mode:
    """Get a mode by name or alias.

    Recognized names: ionian, dorian, phrygian, lydian, mixolydian,
    aeolian, locrian. The aliases `major` (for ionian) and `minor`
    (for aeolian) also work.

    Args:
        name: A mode name string (case-insensitive), or an object
            with a `.name` attribute.

    Returns:
        A `Mode` dataclass. Returns `NO_MODE` for unknown input.

    Example:
        >>> from tonal_py import Mode
        >>> Mode.get("dorian").alt
        2
        >>> Mode.get("MAJOR").name      # case-insensitive, alias for ionian
        'ionian'
        >>> Mode.get("notamode").empty
        True
    """
    if isinstance(name, str):
        return _INDEX.get(name.lower(), NO_MODE)
    if name and getattr(name, "name", None):
        return get(name.name)
    return NO_MODE

all ¶

all() -> list[Mode]

Return all 7 modes as a fresh list of Mode dataclasses.

Example

from tonal_py import Mode len(Mode.all()) 7

Source code in src/tonal_py/mode.py

def all() -> list[Mode]:  # noqa: A001
    """Return all 7 modes as a fresh list of `Mode` dataclasses.

    Example:
        >>> from tonal_py import Mode
        >>> len(Mode.all())
        7
    """
    return _MODES.copy()

names ¶

names() -> list[str]

Return the 7 mode names in canonical order.

Example

from tonal_py import Mode Mode.names() ['ionian', 'dorian', 'phrygian', 'lydian', 'mixolydian', 'aeolian', 'locrian']

Source code in src/tonal_py/mode.py

def names() -> list[str]:
    """Return the 7 mode names in canonical order.

    Example:
        >>> from tonal_py import Mode
        >>> Mode.names()
        ['ionian', 'dorian', 'phrygian', 'lydian', 'mixolydian', 'aeolian', 'locrian']
    """
    return [m.name for m in _MODES]

notes ¶

notes(mode_name: str, tonic: str) -> list[str]

Get the notes of a mode at a given tonic.

Parameters:

Name	Type	Description	Default
`mode_name`	`str`	A mode name or alias.	required
`tonic`	`str`	The starting note.	required

Returns:

Type	Description
`list[str]`	The 7 notes of the mode, in order.

Example

from tonal_py import Mode Mode.notes("dorian", "D") ['D', 'E', 'F', 'G', 'A', 'B', 'C'] Mode.notes("phrygian", "E") ['E', 'F', 'G', 'A', 'B', 'C', 'D']

Source code in src/tonal_py/mode.py

def notes(mode_name: str, tonic: str) -> list[str]:
    """Get the notes of a mode at a given tonic.

    Args:
        mode_name: A mode name or alias.
        tonic: The starting note.

    Returns:
        The 7 notes of the mode, in order.

    Example:
        >>> from tonal_py import Mode
        >>> Mode.notes("dorian", "D")
        ['D', 'E', 'F', 'G', 'A', 'B', 'C']
        >>> Mode.notes("phrygian", "E")
        ['E', 'F', 'G', 'A', 'B', 'C', 'D']
    """
    return [_pitch_distance.transpose(tonic, ivl) for ivl in get(mode_name).intervals]

distance ¶

distance(destination: str, source: str) -> str

Get the interval between two modes (used by relative-tonic math).

Computed as the difference in alt (circle-of-fifths position) between the two modes, simplified to a basic interval.

Parameters:

Name	Type	Description	Default
`destination`	`str`	Target mode name.	required
`source`	`str`	Source mode name.	required

Returns:

Type	Description
`str`	The interval name. Empty string if either mode is invalid.

Example

from tonal_py import Mode Mode.distance("dorian", "ionian") # 2 fifths up '2M' Mode.distance("ionian", "dorian") # 2 fifths down '-2M'

Source code in src/tonal_py/mode.py

def distance(destination: str, source: str) -> str:
    """Get the interval between two modes (used by relative-tonic math).

    Computed as the difference in `alt` (circle-of-fifths position) between
    the two modes, simplified to a basic interval.

    Args:
        destination: Target mode name.
        source: Source mode name.

    Returns:
        The interval name. Empty string if either mode is invalid.

    Example:
        >>> from tonal_py import Mode
        >>> Mode.distance("dorian", "ionian")     # 2 fifths up
        '2M'
        >>> Mode.distance("ionian", "dorian")     # 2 fifths down
        '-2M'
    """
    src = get(source)
    dst = get(destination)
    if src.empty or dst.empty:
        return ""
    return _interval_mod.simplify(
        _interval_mod.transpose_fifths("1P", int(dst.alt - src.alt))
    )

relative_tonic ¶

relative_tonic(destination: str, source: str, tonic: str) -> str

Get the tonic of the relative destination mode for a given source.

"C ionian and D dorian have the same notes" — this function expresses that relationship: relative_tonic("dorian", "ionian", "C") returns "D".

Parameters:

Name	Type	Description	Default
`destination`	`str`	Target mode name.	required
`source`	`str`	Source mode name.	required
`tonic`	`str`	Tonic of the source mode.	required

Returns:

Type	Description
`str`	The tonic of the destination mode.

Example

from tonal_py import Mode Mode.relative_tonic("dorian", "ionian", "C") 'D' Mode.relative_tonic("aeolian", "ionian", "C") 'A'

Source code in src/tonal_py/mode.py

def relative_tonic(destination: str, source: str, tonic: str) -> str:
    """Get the tonic of the relative `destination` mode for a given source.

    "C ionian and D dorian have the same notes" — this function expresses
    that relationship: `relative_tonic("dorian", "ionian", "C")` returns
    `"D"`.

    Args:
        destination: Target mode name.
        source: Source mode name.
        tonic: Tonic of the source mode.

    Returns:
        The tonic of the destination mode.

    Example:
        >>> from tonal_py import Mode
        >>> Mode.relative_tonic("dorian", "ionian", "C")
        'D'
        >>> Mode.relative_tonic("aeolian", "ionian", "C")
        'A'
    """
    return _pitch_distance.transpose(tonic, distance(destination, source))