rhythmtrees

Tools for modeling IRCAM-style rhythm trees.

Classes

`RhythmTreeContainer`	Rhythm-tree container.
`RhythmTreeLeaf`	Rhythm-tree leaf.
`RhythmTreeNode`	Rhythm-tree node.
`RhythmTreeParser`	Rhythm-tree parser.

class abjad.rhythmtrees.RhythmTreeContainer(pair: tuple[int, int], children: Sequence[RhythmTreeNode] = (), *, name: str = '')[source]

Rhythm-tree container.

Extend rhythm-tree containers with rhythm-tree leaves or other rhythm-tree containers:

>>> rtc = abjad.rhythmtrees.RhythmTreeContainer((1, 1))
>>> rtc.append(abjad.rhythmtrees.RhythmTreeLeaf((1, 1)))
>>> rtc.append(abjad.rhythmtrees.RhythmTreeLeaf((2, 1)))
>>> rtc.append(abjad.rhythmtrees.RhythmTreeLeaf((2, 1)))

Use RTM format strings to view the structure of rhythm-tree containers:

>>> print(rtc.rtm_format)
(1 (1 2 2))

>>> print(rtc.pretty_rtm_format)
(1 (
    1
    2
    2))

Call rhythm-tree containers with a duration to make components:

>>> components = rtc(abjad.Duration(1, 1))
>>> voice = abjad.Voice(components)
>>> abjad.setting(voice[0]).Score.proportionalNotationDuration = "#1/12"
>>> abjad.show(voice)  

Attributes Summary

`__add__`	Concatenates `self` and `rtc`.
`__call__`	Makes list of leaves and / or tuplets equal to `duration`.
`__graph__`	Graphs rhythm-tree container.
`__radd__`	Adds `rtc` and `self`.
`__repr__`	Gets interpreter representation of rhythm-tree container.
`rtm_format`	Gets RTM format of rhythm-tree container.

Special methods

__add__(rtc: RhythmTreeContainer) → RhythmTreeContainer[source]

Concatenates self and rtc.

The operation a + b = c returns a new rhythm-tree container c with the contents of a followed by the contents of b; the operation is noncommutative.

>>> rtc_a = abjad.rhythmtrees.parse("(1 (1 1 1))")[0]
>>> components = rtc_a(abjad.Duration(1, 2))
>>> voice = abjad.Voice(components)
>>> leaf = abjad.select.leaf(voice, 0)
>>> abjad.setting(leaf).Score.proportionalNotationDuration = "#1/12"
>>> abjad.show(voice)  

>>> rtc_b = abjad.rhythmtrees.parse("(1 (3 4))")[0]
>>> components = rtc_b(abjad.Duration(1, 2))
>>> voice = abjad.Voice(components)
>>> leaf = abjad.select.leaf(voice, 0)
>>> abjad.setting(leaf).Score.proportionalNotationDuration = "#1/12"
>>> abjad.show(voice)  

>>> rtc_c = rtc_a + rtc_b
>>> components = rtc_c(abjad.Duration(1, 2))
>>> voice = abjad.Voice(components)
>>> leaf = abjad.select.leaf(voice, 0)
>>> abjad.setting(leaf).Score.proportionalNotationDuration = "#1/12"
>>> abjad.show(voice)  

The pair of c equals the sum of the pairs of a and b:

>>> rtc_a.pair
(1, 1)

>>> rtc_b.pair
(1, 1)

>>> rtc_c.pair
(2, 1)

overridden __call__(duration: Duration) → list[Leaf | Tuplet][source]

Makes list of leaves and / or tuplets equal to duration.

>>> string = "(1 (1 (2 (1 1 1)) 2))"
>>> rtc = abjad.rhythmtrees.parse(string)[0]
>>> components = rtc(abjad.Duration(1, 1))
>>> voice = abjad.Voice(components)
>>> abjad.setting(voice[0]).proportionalNotationDuration = "#1/12"
>>> abjad.show(voice)  

(UniqueTreeContainer).__contains__(expr)

(UniqueTreeList).__delitem__(i)

(UniqueTreeList).__getitem__(expr)

__graph__(**keywords) → Graph[source]

Graphs rhythm-tree container.

>>> string = "(1 (1 (2 (1 1 1)) 2))"
>>> rtc = abjad.rhythmtrees.parse(string)[0]
>>> abjad.graph(rtc)  

(UniqueTreeContainer).__iter__()

(UniqueTreeContainer).__len__()

__radd__(rtc) → RhythmTreeContainer[source]: Adds rtc and self.

overridden __repr__() → str[source]: Gets interpreter representation of rhythm-tree container.

(UniqueTreeList).__setitem__(i, new_items)

Methods

(UniqueTreeList).append(expr)

(UniqueTreeContainer).depth_first(top_down=True, prototype=None)

(UniqueTreeList).extend(expr)

(UniqueTreeList).index(expr)

(UniqueTreeList).insert(i, expr)

(UniqueTreeList).pop(i=-1)

(UniqueTreeContainer).recurse(prototype=None)

(UniqueTreeList).remove(node)

Read/write properties

(UniqueTreeNode).name

(RhythmTreeNode).pair

Gets pair of rhythm-tree node.

>>> abjad.rhythmtrees.RhythmTreeLeaf((1, 1)).pair
(1, 1)

>>> abjad.rhythmtrees.RhythmTreeLeaf((2, 4)).pair
(2, 4)

Read-only properties

(UniqueTreeContainer).children

(UniqueTreeNode).depth

(RhythmTreeNode).duration

Gets duration of rhythm-tree node.

>>> string = "(1 ((1 (1 1)) (1 (1 1))))"
>>> rtc = abjad.rhythmtrees.parse(string)[0]
>>> components = rtc(abjad.Duration(1, 1))
>>> voice = abjad.Voice(components)
>>> score = abjad.Score([voice])
>>> abjad.setting(score).proportionalNotationDuration = "#1/12"
>>> abjad.show(score)  

>>> rtc.duration
Duration(1, 1)

>>> rtc[1].duration
Duration(1, 2)

>>> rtc[1][1].duration
Duration(1, 4)

(UniqueTreeNode).graph_order

Get graph-order tuple for node.

>>> from uqbar.containers import UniqueTreeList, UniqueTreeNode
>>> root_container = UniqueTreeList(name="root")
>>> outer_container = UniqueTreeList(name="outer")
>>> inner_container = UniqueTreeList(name="inner")
>>> node_a = UniqueTreeNode(name="a")
>>> node_b = UniqueTreeNode(name="b")
>>> node_c = UniqueTreeNode(name="c")
>>> node_d = UniqueTreeNode(name="d")
>>> root_container.extend([node_a, outer_container])
>>> outer_container.extend([inner_container, node_d])
>>> inner_container.extend([node_b, node_c])

>>> for node in root_container.depth_first():
...     print(node.name, node.graph_order)
... 
a (0,)
outer (1,)
inner (1, 0)
b (1, 0, 0)
c (1, 0, 1)
d (1, 1)

(UniqueTreeNode).parent

(UniqueTreeNode).parentage

(RhythmTreeNode).pretty_rtm_format

Gets pretty-printed RTM format of rhythm-tree node.

>>> string = "(1 ((1 (1 1)) (1 (1 1))))"
>>> rtc = abjad.rhythmtrees.parse(string)[0]

>>> print(rtc.pretty_rtm_format)
(1 (
    (1 (
        1
        1))
    (1 (
        1
        1))))

>>> print(rtc[0].pretty_rtm_format)
(1 (
    1
    1))

>>> print(rtc[0][0].pretty_rtm_format)
1

(RhythmTreeNode).prolation: Gets prolation of rhythm-tree node.

(RhythmTreeNode).prolations: Gets prolations of rhythm-tree node.

(UniqueTreeNode).root

rtm_format

Gets RTM format of rhythm-tree container.

>>> string = "(1 ((1 (1 1)) (1 (1 1))))"
>>> rtc = abjad.rhythmtrees.parse(string)[0]

>>> rtc.rtm_format
'(1 ((1 (1 1)) (1 (1 1))))'

>>> rtc[0].rtm_format
'(1 (1 1))'

>>> rtc[0][0].rtm_format
'1'

(RhythmTreeNode).start_offset

Gets start offset of rhythm-tree node.

>>> string = "(1 ((1 (1 1)) (1 (1 1))))"
>>> rtc = abjad.rhythmtrees.parse(string)[0]

>>> rtc.start_offset
Offset((0, 1))

>>> rtc[1].start_offset
Offset((1, 2))

>>> rtc[1][1].start_offset
Offset((3, 4))

(RhythmTreeNode).stop_offset

Gets stop offset of rhythm-tree node.

>>> string = "(1 ((1 (1 1)) (1 (1 1))))"
>>> rtc = abjad.rhythmtrees.parse(string)[0]

>>> rtc.stop_offset
Offset((1, 1))

>>> rtc[0].stop_offset
Offset((1, 2))

>>> rtc[0][0].stop_offset
Offset((1, 4))

class abjad.rhythmtrees.RhythmTreeLeaf(pair: tuple[int, int], *, is_pitched: bool = True, name: str | None = None)[source]

Rhythm-tree leaf.

Pitched rhythm-tree leaves makes notes:

>>> rtl = abjad.rhythmtrees.RhythmTreeLeaf((5, 1), is_pitched=True)
>>> components = rtl(abjad.Duration(1, 4))
>>> voice = abjad.Voice(components)
>>> abjad.setting(voice[0]).Score.proportionalNotationDuration = "#1/12"
>>> abjad.show(voice)  

Unpitched rhythm-tree leaves make rests:

>>> rtl = abjad.rhythmtrees.RhythmTreeLeaf((5, 1), is_pitched=False)
>>> components = rtl(abjad.Duration(1, 4))
>>> voice = abjad.Voice(components)
>>> abjad.setting(voice[0]).Score.proportionalNotationDuration = "#1/12"
>>> abjad.show(voice)  

Attributes Summary

`__call__`	Makes list of leaves and / or tuplets equal to `duration`.
`__graph__`	Gets Graphviz graph of rhythm-tree leaf.
`__repr__`	Gets interpreter representation of rhythm-tree leaf.
`is_pitched`	Is true when rhythm-tree leaf is pitched.
`rtm_format`	Gets RTM format of rhythm-tree leaf.

Special methods

overridden __call__(duration: Duration) → list[Leaf | Tuplet][source]: Makes list of leaves and / or tuplets equal to duration.

__graph__(**keywords) → Graph[source]: Gets Graphviz graph of rhythm-tree leaf.

overridden __repr__() → str[source]: Gets interpreter representation of rhythm-tree leaf.

Read/write properties

is_pitched: Is true when rhythm-tree leaf is pitched.

(UniqueTreeNode).name

(RhythmTreeNode).pair

Gets pair of rhythm-tree node.

>>> abjad.rhythmtrees.RhythmTreeLeaf((1, 1)).pair
(1, 1)

>>> abjad.rhythmtrees.RhythmTreeLeaf((2, 4)).pair
(2, 4)

Read-only properties

(UniqueTreeNode).depth

(RhythmTreeNode).duration

Gets duration of rhythm-tree node.

>>> string = "(1 ((1 (1 1)) (1 (1 1))))"
>>> rtc = abjad.rhythmtrees.parse(string)[0]
>>> components = rtc(abjad.Duration(1, 1))
>>> voice = abjad.Voice(components)
>>> score = abjad.Score([voice])
>>> abjad.setting(score).proportionalNotationDuration = "#1/12"
>>> abjad.show(score)  

>>> rtc.duration
Duration(1, 1)

>>> rtc[1].duration
Duration(1, 2)

>>> rtc[1][1].duration
Duration(1, 4)

(UniqueTreeNode).graph_order

Get graph-order tuple for node.

>>> from uqbar.containers import UniqueTreeList, UniqueTreeNode
>>> root_container = UniqueTreeList(name="root")
>>> outer_container = UniqueTreeList(name="outer")
>>> inner_container = UniqueTreeList(name="inner")
>>> node_a = UniqueTreeNode(name="a")
>>> node_b = UniqueTreeNode(name="b")
>>> node_c = UniqueTreeNode(name="c")
>>> node_d = UniqueTreeNode(name="d")
>>> root_container.extend([node_a, outer_container])
>>> outer_container.extend([inner_container, node_d])
>>> inner_container.extend([node_b, node_c])

>>> for node in root_container.depth_first():
...     print(node.name, node.graph_order)
... 
a (0,)
outer (1,)
inner (1, 0)
b (1, 0, 0)
c (1, 0, 1)
d (1, 1)

(UniqueTreeNode).parent

(UniqueTreeNode).parentage

(RhythmTreeNode).pretty_rtm_format

Gets pretty-printed RTM format of rhythm-tree node.

>>> string = "(1 ((1 (1 1)) (1 (1 1))))"
>>> rtc = abjad.rhythmtrees.parse(string)[0]

>>> print(rtc.pretty_rtm_format)
(1 (
    (1 (
        1
        1))
    (1 (
        1
        1))))

>>> print(rtc[0].pretty_rtm_format)
(1 (
    1
    1))

>>> print(rtc[0][0].pretty_rtm_format)
1

(RhythmTreeNode).prolation: Gets prolation of rhythm-tree node.

(RhythmTreeNode).prolations: Gets prolations of rhythm-tree node.

(UniqueTreeNode).root

rtm_format

Gets RTM format of rhythm-tree leaf.

>>> abjad.rhythmtrees.RhythmTreeLeaf((5, 1), is_pitched=True).rtm_format
'5'

>>> abjad.rhythmtrees.RhythmTreeLeaf((5, 1), is_pitched=False).rtm_format
'-5'

(RhythmTreeNode).start_offset

Gets start offset of rhythm-tree node.

>>> string = "(1 ((1 (1 1)) (1 (1 1))))"
>>> rtc = abjad.rhythmtrees.parse(string)[0]

>>> rtc.start_offset
Offset((0, 1))

>>> rtc[1].start_offset
Offset((1, 2))

>>> rtc[1][1].start_offset
Offset((3, 4))

(RhythmTreeNode).stop_offset

Gets stop offset of rhythm-tree node.

>>> string = "(1 ((1 (1 1)) (1 (1 1))))"
>>> rtc = abjad.rhythmtrees.parse(string)[0]

>>> rtc.stop_offset
Offset((1, 1))

>>> rtc[0].stop_offset
Offset((1, 2))

>>> rtc[0][0].stop_offset
Offset((1, 4))

class abjad.rhythmtrees.RhythmTreeNode(pair: tuple[int, int])[source]

Rhythm-tree node.

Attributes Summary

`duration`	Gets duration of rhythm-tree node.
`pair`	Gets pair of rhythm-tree node.
`pretty_rtm_format`	Gets pretty-printed RTM format of rhythm-tree node.
`prolation`	Gets prolation of rhythm-tree node.
`prolations`	Gets prolations of rhythm-tree node.
`start_offset`	Gets start offset of rhythm-tree node.
`stop_offset`	Gets stop offset of rhythm-tree node.

Read/write properties

pair

Gets pair of rhythm-tree node.

>>> abjad.rhythmtrees.RhythmTreeLeaf((1, 1)).pair
(1, 1)

>>> abjad.rhythmtrees.RhythmTreeLeaf((2, 4)).pair
(2, 4)

Read-only properties

duration

Gets duration of rhythm-tree node.

>>> string = "(1 ((1 (1 1)) (1 (1 1))))"
>>> rtc = abjad.rhythmtrees.parse(string)[0]
>>> components = rtc(abjad.Duration(1, 1))
>>> voice = abjad.Voice(components)
>>> score = abjad.Score([voice])
>>> abjad.setting(score).proportionalNotationDuration = "#1/12"
>>> abjad.show(score)  

>>> rtc.duration
Duration(1, 1)

>>> rtc[1].duration
Duration(1, 2)

>>> rtc[1][1].duration
Duration(1, 4)

pretty_rtm_format

Gets pretty-printed RTM format of rhythm-tree node.

>>> string = "(1 ((1 (1 1)) (1 (1 1))))"
>>> rtc = abjad.rhythmtrees.parse(string)[0]

>>> print(rtc.pretty_rtm_format)
(1 (
    (1 (
        1
        1))
    (1 (
        1
        1))))

>>> print(rtc[0].pretty_rtm_format)
(1 (
    1
    1))

>>> print(rtc[0][0].pretty_rtm_format)
1

prolation: Gets prolation of rhythm-tree node.

prolations: Gets prolations of rhythm-tree node.

start_offset

Gets start offset of rhythm-tree node.

>>> string = "(1 ((1 (1 1)) (1 (1 1))))"
>>> rtc = abjad.rhythmtrees.parse(string)[0]

>>> rtc.start_offset
Offset((0, 1))

>>> rtc[1].start_offset
Offset((1, 2))

>>> rtc[1][1].start_offset
Offset((3, 4))

stop_offset

Gets stop offset of rhythm-tree node.

>>> string = "(1 ((1 (1 1)) (1 (1 1))))"
>>> rtc = abjad.rhythmtrees.parse(string)[0]

>>> rtc.stop_offset
Offset((1, 1))

>>> rtc[0].stop_offset
Offset((1, 2))

>>> rtc[0][0].stop_offset
Offset((1, 4))

class abjad.rhythmtrees.RhythmTreeParser(debug=False)[source]

Rhythm-tree parser.

Parses a microlanguage resembling Ircam’s Lisp-based RTM syntax. Generates a list of rhythm trees. Composers can manipulate rhythm trees and convert them to score components.

>>> parser = abjad.rhythmtrees.RhythmTreeParser()
>>> string = "(3 (1 (1 ((2 (1 1 1)) 2 2 1))))"
>>> rtc = parser(string)[0]

>>> print(rtc.pretty_rtm_format)
(3 (
    1
    (1 (
        (2 (
            1
            1
            1))
        2
        2
        1))))

>>> components = rtc(abjad.Duration(1, 2))
>>> voice = abjad.Voice(components)
>>> staff = abjad.Staff([voice])
>>> score = abjad.Score([staff])
>>> abjad.setting(score).proportionalNotationDuration = "#1/12"
>>> time_signature = abjad.TimeSignature((6, 4))
>>> leaf = abjad.select.leaf(voice, 0)
>>> abjad.attach(time_signature, leaf)
>>> abjad.show(score)  

Attributes Summary

`lexer_rules_object`
`p_container__LPAREN__DURATION__node_list_closed__RPAREN`	container : LPAREN DURATION node_list_closed RPAREN
`p_error`
`p_leaf__INTEGER`	leaf : DURATION
`p_node__container`	node : container
`p_node__leaf`	node : leaf
`p_node_list__node_list__node_list_item`	node_list : node_list node_list_item
`p_node_list__node_list_item`	node_list : node_list_item
`p_node_list_closed__LPAREN__node_list__RPAREN`	node_list_closed : LPAREN node_list RPAREN
`p_node_list_item__node`	node_list_item : node
`p_toplevel__EMPTY`	toplevel :
`p_toplevel__toplevel__node`	toplevel : toplevel node
`parser_rules_object`
`start`
`t_DURATION`	-?[1-9]d(/[1-9]d)?
`t_LPAREN`
`t_RPAREN`
`t_error`
`t_ignore`
`t_newline`	n+
`tokens`

Special methods

(Parser).__call__(string): Parses string and returns result.

Methods

p_container__LPAREN__DURATION__node_list_closed__RPAREN(p)[source]: container : LPAREN DURATION node_list_closed RPAREN

p_error(p)[source]

p_leaf__INTEGER(p)[source]: leaf : DURATION

p_node__container(p)[source]: node : container

p_node__leaf(p)[source]: node : leaf

p_node_list__node_list__node_list_item(p)[source]: node_list : node_list node_list_item

p_node_list__node_list_item(p)[source]: node_list : node_list_item

p_node_list_closed__LPAREN__node_list__RPAREN(p)[source]: node_list_closed : LPAREN node_list RPAREN

p_node_list_item__node(p)[source]: node_list_item : node

p_toplevel__EMPTY(p)[source]: toplevel :

p_toplevel__toplevel__node(p)[source]: toplevel : toplevel node

t_DURATION(t)[source]: -?[1-9]d*(/[1-9]d*)?

t_error(t)[source]

t_newline(t)[source]: n+

(Parser).tokenize(string): Tokenizes string and print results.

Read-only properties

(Parser).debug: Is true when parser runs in debugging mode.

(Parser).lexer: Gets parser’s PLY Lexer instance.

lexer_rules_object

(Parser).logger: Gets parser’s logger.

(Parser).logger_path: Gets parser’s logfile output path.

(Parser).output_path: Gets output path for files associated with the parser.

(Parser).parser: Gets parser’s PLY LRParser instance.

parser_rules_object

(Parser).pickle_path: Gets output path for the parser’s pickled parsing tables.

Functions

`call`	Calls each node in `nodes` with `duration`.
`extract_trivial_tuplets`	Extracts trivial tuplets from `argument`.
`parse`	Parses RTM `string`.

abjad.rhythmtrees.call(nodes, duration: Duration = Duration(1, 4)) → list[Leaf | Tuplet][source]: Calls each node in nodes with duration.

abjad.rhythmtrees.extract_trivial_tuplets(argument) → None[source]: Extracts trivial tuplets from argument.

abjad.rhythmtrees.parse(string: str) → list[RhythmTreeContainer | RhythmTreeLeaf][source]

Parses RTM string.

Quarter note:

>>> nodes = abjad.rhythmtrees.parse("1")
>>> components = abjad.rhythmtrees.call(nodes)
>>> voice = abjad.Voice(components)
>>> abjad.setting(voice[0]).Score.proportionalNotationDuration = "#1/12"
>>> abjad.show(voice)  

Series of quarter notes:

>>> nodes = abjad.rhythmtrees.parse("1 1 1 1 1 1")
>>> components = abjad.rhythmtrees.call(nodes)
>>> voice = abjad.Voice(components)
>>> abjad.setting(voice[0]).Score.proportionalNotationDuration = "#1/12"
>>> abjad.show(voice)  

Half-note duration divided into 1 part:

>>> string = "(2 (1))"
>>> nodes = abjad.rhythmtrees.parse(string)
>>> components = abjad.rhythmtrees.call(nodes)
>>> voice = abjad.Voice(components)
>>> leaf = abjad.select.leaf(voice, 0)
>>> abjad.setting(leaf).Score.proportionalNotationDuration = "#1/12"
>>> abjad.show(voice)  

>>> abjad.rhythmtrees.extract_trivial_tuplets(voice)
>>> abjad.show(voice)  

Half-note duration divided 1:1:

>>> string = "(2 (1 1))"
>>> nodes = abjad.rhythmtrees.parse(string)
>>> components = abjad.rhythmtrees.call(nodes)
>>> voice = abjad.Voice(components)
>>> leaf = abjad.select.leaf(voice, 0)
>>> abjad.setting(leaf).Score.proportionalNotationDuration = "#1/12"
>>> abjad.show(voice)  

>>> abjad.rhythmtrees.extract_trivial_tuplets(voice)
>>> abjad.show(voice)  

Half-note duration divided 1:2:

>>> string = "(2 (1 2))"
>>> nodes = abjad.rhythmtrees.parse(string)
>>> components = abjad.rhythmtrees.call(nodes)
>>> voice = abjad.Voice(components)
>>> leaf = abjad.select.leaf(voice, 0)
>>> abjad.setting(leaf).Score.proportionalNotationDuration = "#1/12"
>>> abjad.show(voice)  

Successive quarter-note durations, divided 1, 1:1, 1:2:

>>> string = "(1 (1)) (1 (1 1)) (1 (1 2))"
>>> nodes = abjad.rhythmtrees.parse(string)
>>> components = abjad.rhythmtrees.call(nodes)
>>> voice = abjad.Voice(components)
>>> leaf = abjad.select.leaf(voice, 0)
>>> abjad.setting(leaf).Score.proportionalNotationDuration = "#1/12"
>>> abjad.show(voice)  

>>> abjad.rhythmtrees.extract_trivial_tuplets(voice)
>>> abjad.show(voice)  

Dyadic durations:

>>> nodes = abjad.rhythmtrees.parse("1 1/2 1/2 3/2 1/4")
>>> components = abjad.rhythmtrees.call(nodes)
>>> voice = abjad.Voice(components)
>>> abjad.setting(voice[0]).Score.proportionalNotationDuration = "#1/12"
>>> abjad.show(voice)  

Tuplets without dotted values:

>>> string = "(1 (1 (1 (1 1)) 1))"
>>> nodes = abjad.rhythmtrees.parse(string)
>>> components = abjad.rhythmtrees.call(nodes, abjad.Duration(1, 2))
>>> voice = abjad.Voice(components)
>>> leaf = abjad.select.leaf(voice, 0)
>>> abjad.setting(leaf).Score.proportionalNotationDuration = "#1/12"
>>> abjad.show(voice)  

>>> abjad.rhythmtrees.extract_trivial_tuplets(voice)
>>> abjad.show(voice)  