Tuplet

digraph InheritanceGraph { graph [bgcolor=transparent, color=lightsteelblue2, fontname=Arial, fontsize=10, outputorder=edgesfirst, overlap=prism, penwidth=2, rankdir=LR, splines=spline, style="dashed, rounded", truecolor=true]; node [colorscheme=pastel19, fontname=Arial, fontsize=10, height=0, penwidth=2, shape=box, style="filled, rounded", width=0]; edge [color=lightslategrey, penwidth=1]; subgraph "cluster_abjad.core" { graph [label="abjad.core"]; node [color=1]; "abjad.core.Component.Component" [URL="../api/abjad/core/Component.html#abjad.core.Component.Component", label=Component, shape=oval, style=bold, target=_top]; "abjad.core.Container.Container" [URL="../api/abjad/core/Container.html#abjad.core.Container.Container", label=Container, target=_top]; "abjad.core.Tuplet.Tuplet" [URL="../api/abjad/core/Tuplet.html#abjad.core.Tuplet.Tuplet", color=black, fontcolor=white, label=Tuplet, target=_top]; "abjad.core.Component.Component" -> "abjad.core.Container.Container"; "abjad.core.Container.Container" -> "abjad.core.Tuplet.Tuplet"; } subgraph "cluster_abjad.system" { graph [label="abjad.system"]; node [color=2]; "abjad.system.AbjadObject.AbjadObject" [URL="../api/abjad/core/../system/AbjadObject.html#abjad.system.AbjadObject.AbjadObject", label="Abjad\nObject", target=_top]; } subgraph cluster_builtins { graph [label=builtins]; node [color=3]; "builtins.object" [URL="https://docs.python.org/3.6/library/functions.html#object", label=object, target=_top]; } "abjad.system.AbjadObject.AbjadObject" -> "abjad.core.Component.Component"; "builtins.object" -> "abjad.system.AbjadObject.AbjadObject"; }

class abjad.core.Tuplet.Tuplet(multiplier=(2, 3), components=None, *, denominator=None, force_fraction=None, hide=None, tweaks=None)

Tuplet.

A tuplet:

>>> tuplet = abjad.Tuplet((2, 3), "c'8 d'8 e'8")
>>> abjad.show(tuplet) 

A nested tuplet:

>>> second_tuplet = abjad.Tuplet((4, 7), "g'4. ( a'16 )")
>>> tuplet.insert(1, second_tuplet)
>>> abjad.show(tuplet) 

A doubly nested tuplet:

>>> third_tuplet = abjad.Tuplet((4, 5), [])
>>> third_tuplet.extend("e''32 [ ef''32 d''32 cs''32 cqs''32 ]")
>>> second_tuplet.insert(1, third_tuplet)
>>> abjad.show(tuplet) 

Attributes Summary

append Appends component to tuplet.
augmentation Is true when tuplet multiplier is greater than 1.
denominator Gets and sets preferred denominator of tuplet.
diminution Is true when tuplet multiplier is less than 1.
extend Extends tuplet with argument.
force_fraction Gets and sets force fraction flag.
from_duration Makes tuplet from duration and components.
from_duration_and_ratio Makes tuplet from duration and ratio.
from_leaf_and_ratio Makes tuplet from leaf and ratio.
from_ratio_and_pair Makes tuplet from nonreduced ratio and nonreduced fraction.
hide Is true when tuplet bracket hides.
implied_prolation Gets implied prolation of tuplet.
multiplied_duration Gets multiplied duration of tuplet.
multiplier Gets and sets multiplier of tuplet.
normalize_multiplier Normalizes tuplet multiplier.
rewrite_dots Rewrites dots.
set_minimum_denominator Sets preferred denominator of tuplet to at least denominator.
toggle_prolation Changes augmented tuplets to diminished; changes diminished tuplets to augmented.
trivial Is true when tuplet multiplier is equal to 1 and no multipliers attach to any leaves in tuplet.
trivializable Is true when tuplet is trivializable (can be rewritten with a ratio of 1:1).
trivialize Trivializes tuplet.
tweaks Gets tweaks.

Special methods

(Container).__contains__(argument)

Is true when argument appears in container.

Return type:bool
(Component).__copy__(*arguments)

Shallow copies component.

Copies indicators.

Does not copy spanners.

Does not copy children.

Returns new component.

(Container).__delitem__(i)

Deletes components(s) at index i in container.

Deletes first tuplet in voice:

>>> voice = abjad.Voice()
>>> voice.append(abjad.Tuplet((2, 3), "c'4 d'4 e'4"))
>>> voice.append(abjad.Tuplet((2, 3), "e'4 d'4 c'4"))
>>> leaves = abjad.select(voice).leaves()
>>> abjad.attach(abjad.Slur(), leaves)
>>> abjad.show(voice) 
>>> tuplet_1 = voice[0]
>>> del(voice[0])

First tuplet no longer appears in voice:

>>> abjad.show(voice) 
>>> abjad.inspect(voice).is_well_formed()
True

First tuplet is no longer slurred but is still well-formed:

>>> abjad.show(tuplet_1) 
>>> abjad.inspect(tuplet_1).is_well_formed()
True

Withdraws component(s) from crossing spanners.

Preserves spanners that component(s) cover(s).

Returns none.

(Component).__format__(format_specification='')

Formats component.

Returns string.

(Container).__getitem__(argument)

Gets item or slice identified by argument.

Traverses top-level items only.

Return type:Union[Component, Selection]
(Container).__graph__(spanner=None, **keywords)

Graphviz graph representation of container.

Returns Graphviz graph.

(Component).__illustrate__()

Illustrates component.

Returns LilyPond file.

(Container).__iter__()

Iterates container.

Abjad containers are iterables:

>>> import collections
>>> container = abjad.Container()
>>> isinstance(container, collections.Iterable)
True

Abjad containers are not sequences:

>>> import collections
>>> container = abjad.Container()
>>> isinstance(container, collections.Sequence)
False

Yields container elements.

Returns generator.

(Container).__len__()

Gets number of components in container.

Return type:int
(Component).__mul__(n)

Copies component n times and detaches spanners.

Returns list of new components.

(Component).__repr__()

Gets interpreter representation of leaf.

Returns string.

(Component).__rmul__(n)

Copies component n times and detach spanners.

Returns list of new components.

(Container).__setitem__(i, argument)

Sets container i equal to argument. Finds spanners that dominate self[i] and children of self[i]. Replaces contents at self[i] with ‘argument’. Reattaches spanners to new contents. Always leaves score tree in tact.

Return type:None

Methods

append(component, preserve_duration=False)

Appends component to tuplet.

Appends note to tuplet:

>>> tuplet = abjad.Tuplet((2, 3), "c'4 ( d'4 f'4 )")
>>> abjad.show(tuplet) 
>>> tuplet.append(abjad.Note("e'4"))
>>> abjad.show(tuplet) 

Appends note to tuplet and preserves tuplet duration:

>>> tuplet = abjad.Tuplet((2, 3), "c'4 ( d'4 f'4 )")
>>> abjad.show(tuplet) 
>>> tuplet.append(abjad.Note("e'4"), preserve_duration=True)
>>> abjad.show(tuplet) 
Return type:None
augmentation()

Is true when tuplet multiplier is greater than 1.

Augmented tuplet:

>>> tuplet = abjad.Tuplet((4, 3), "c'8 d'8 e'8")
>>> abjad.show(tuplet) 
>>> tuplet.augmentation()
True

Diminished tuplet:

>>> tuplet = abjad.Tuplet((2, 3), "c'4 d'4 e'4")
>>> abjad.show(tuplet) 
>>> tuplet.augmentation()
False

Trivial tuplet:

>>> tuplet = abjad.Tuplet((1, 1), "c'8. d'8. e'8.")
>>> abjad.show(tuplet) 
>>> tuplet.augmentation()
False
Return type:bool
diminution()

Is true when tuplet multiplier is less than 1.

Augmented tuplet:

>>> tuplet = abjad.Tuplet((4, 3), "c'8 d'8 e'8")
>>> abjad.show(tuplet) 
>>> tuplet.diminution()
False

Diminished tuplet:

>>> tuplet = abjad.Tuplet((2, 3), "c'4 d'4 e'4")
>>> abjad.show(tuplet) 
>>> tuplet.diminution()
True

Trivial tuplet:

>>> tuplet = abjad.Tuplet((1, 1), "c'8. d'8. e'8.")
>>> abjad.show(tuplet) 
>>> tuplet.diminution()
False
Return type:bool
extend(argument, preserve_duration=False)

Extends tuplet with argument.

Extends tuplet with three notes:

>>> tuplet = abjad.Tuplet((2, 3), "c'4 ( d'4 f'4 )")
>>> abjad.show(tuplet) 
>>> notes = [abjad.Note("e'32"), abjad.Note("d'32"), abjad.Note("e'16")]
>>> tuplet.extend(notes)
>>> abjad.show(tuplet) 

Extends tuplet with three notes and preserves tuplet duration:

>>> tuplet = abjad.Tuplet((2, 3), "c'4 ( d'4 f'4 )")
>>> abjad.show(tuplet) 
>>> notes = [abjad.Note("e'32"), abjad.Note("d'32"), abjad.Note("e'16")]
>>> tuplet.extend(notes, preserve_duration=True)
>>> abjad.show(tuplet) 
Return type:None
(Container).index(component)

Returns index of component in container.

Gets index of last element in container:

>>> container = abjad.Container("c'4 d'4 f'4 e'4")
>>> abjad.show(container) 
>>> note = container[-1]
>>> note
Note("e'4")
>>> container.index(note)
3
Return type:int
(Container).insert(i, component, fracture_spanners=False)

Inserts component at index i in container.

Inserts note. Does not fracture spanners:

>>> container = abjad.Container([])
>>> container.extend("fs16 cs' e' a'")
>>> container.extend("cs''16 e'' cs'' a'")
>>> container.extend("fs'16 e' cs' fs")
>>> slur = abjad.Slur(direction=abjad.Down)
>>> abjad.attach(slur, container[:])
>>> abjad.show(container) 
>>> container.insert(-4, abjad.Note("e'4"), fracture_spanners=False)
>>> abjad.show(container) 

Inserts note. Fractures spanners:

>>> container = abjad.Container([])
>>> container.extend("fs16 cs' e' a'")
>>> container.extend("cs''16 e'' cs'' a'")
>>> container.extend("fs'16 e' cs' fs")
>>> slur = abjad.Slur(direction=abjad.Down)
>>> abjad.attach(slur, container[:])
>>> abjad.show(container) 
>>> container.insert(-4, abjad.Note("e'4"), fracture_spanners=True)
>>> abjad.show(container) 
Return type:None
normalize_multiplier()

Normalizes tuplet multiplier.

>>> tuplet = abjad.Tuplet((1, 3), "c'4 d' e'")
>>> abjad.show(tuplet) 
>>> tuplet.multiplier.normalized()
False
>>> tuplet.normalize_multiplier()
>>> abjad.show(tuplet) 
>>> tuplet.multiplier.normalized()
True
>>> tuplet = abjad.Tuplet((8, 3), "c'32 d'32 e'32")
>>> abjad.show(tuplet) 
>>> tuplet.multiplier.normalized()
False
>>> tuplet.normalize_multiplier()
>>> abjad.show(tuplet) 
>>> tuplet.multiplier.normalized()
True
>>> tuplet = abjad.Tuplet((5, 12), "c'4 d'4 e'4")
>>> abjad.show(tuplet) 
>>> tuplet.multiplier.normalized()
False
>>> tuplet.normalize_multiplier()
>>> abjad.show(tuplet) 
>>> tuplet.multiplier.normalized()
True
Return type:None
(Container).pop(i=-1)

Pops component from container at index i.

Pops last element from container:

>>> container = abjad.Container("c'4 ( d'4 f'4 ) e'4")
>>> abjad.show(container) 
>>> container.pop()
Note("e'4")
>>> abjad.show(container) 

Returns component.

(Container).remove(component)

Removes component from container.

Removes note from container:

>>> container = abjad.Container("c'4 ( d'4 f'4 ) e'4")
>>> abjad.show(container) 
>>> note = container[2]
>>> note
Note("f'4")
>>> container.remove(note)
>>> abjad.show(container) 
Return type:None
rewrite_dots()

Rewrites dots.

Rewrites single dots as 3:2 prolation:

>>> tuplet = abjad.Tuplet(1, "c'8. c'8.")
>>> abjad.show(tuplet) 
>>> tuplet.rewrite_dots()
>>> abjad.show(tuplet) 

Rewrites double dots as 7:4 prolation:

>>> tuplet = abjad.Tuplet(1, "c'8.. c'8..")
>>> abjad.show(tuplet) 
>>> tuplet.rewrite_dots()
>>> abjad.show(tuplet) 

Does nothing when dot counts differ:

>>> tuplet = abjad.Tuplet(1, "c'8. d'8. e'8")
>>> abjad.show(tuplet) 
>>> tuplet.rewrite_dots()
>>> abjad.show(tuplet) 

Does nothing when leaves carry no dots:

>>> tuplet = abjad.Tuplet((3, 2), "c'8 d' e'")
>>> abjad.show(tuplet) 
>>> tuplet.rewrite_dots()
>>> abjad.show(tuplet) 

Not yet implemented for multiply nested tuplets.

Return type:None
set_minimum_denominator(denominator)

Sets preferred denominator of tuplet to at least denominator.

Sets preferred denominator of tuplet to 8 at least:

>>> tuplet = abjad.Tuplet((3, 5), "c'4 d'8 e'8 f'4 g'2")
>>> abjad.show(tuplet) 
>>> tuplet.set_minimum_denominator(8)
>>> abjad.show(tuplet) 
Return type:None
toggle_prolation()

Changes augmented tuplets to diminished; changes diminished tuplets to augmented.

Changes augmented tuplet to diminished:

>>> tuplet = abjad.Tuplet((4, 3), "c'8 d'8 e'8")
>>> abjad.show(tuplet) 
>>> tuplet.toggle_prolation()
>>> abjad.show(tuplet) 

Multiplies the written duration of the leaves in tuplet by the least power of 2 necessary to diminshed tuplet.

Changes diminished tuplet to augmented:

>>> tuplet = abjad.Tuplet((2, 3), "c'4 d'4 e'4")
>>> abjad.show(tuplet) 
>>> tuplet.toggle_prolation()
>>> abjad.show(tuplet) 

Divides the written duration of the leaves in tuplet by the least power of 2 necessary to diminshed tuplet.

REGRESSION. Leaves trivial tuplets unchanged:

>>> tuplet = abjad.Tuplet(1, "c'4 d'4 e'4")
>>> abjad.show(tuplet) 
>>> tuplet.toggle_prolation()
>>> abjad.show(tuplet) 

Does not yet work with nested tuplets.

Return type:None
trivial()

Is true when tuplet multiplier is equal to 1 and no multipliers attach to any leaves in tuplet.

>>> tuplet = abjad.Tuplet((1, 1), "c'8 d'8 e'8")
>>> abjad.show(tuplet) 
>>> tuplet.trivial()
True

Tuplet is not trivial when multipliers attach to tuplet leaves:

>>> tuplet = abjad.Tuplet((1, 1), "c'8 d'8 e'8")
>>> abjad.attach(abjad.Multiplier(3, 2), tuplet[0])
>>> abjad.attach(abjad.Multiplier(1, 2), tuplet[-1])
>>> abjad.show(tuplet) 
>>> tuplet.trivial()
False
Return type:bool
trivializable()

Is true when tuplet is trivializable (can be rewritten with a ratio of 1:1).

Redudant tuplet:

>>> tuplet = abjad.Tuplet((3, 4), "c'4 c'4")
>>> measure = abjad.Measure((3, 8), [tuplet])
>>> abjad.show(measure) 
>>> tuplet.trivializable()
True

Can be rewritten without a tuplet bracket:

>>> measure = abjad.Measure((3, 8), "c'8. c'8.")
>>> abjad.show(measure) 

Nontrivializable tuplet:

>>> tuplet = abjad.Tuplet((3, 5), "c'4 c'4 c'4 c'4 c'4")
>>> measure = abjad.Measure((3, 4), [tuplet])
>>> abjad.show(measure) 
>>> tuplet.trivializable()
False

Can not be rewritten without a tuplet bracket.

REGRESSION. Nontrivializable tuplet:

>>> tuplet = abjad.Tuplet((3, 4), "c'2. c4")
>>> measure = abjad.Measure((3, 4), [tuplet])
>>> abjad.show(measure) 
>>> tuplet.trivializable()
False
Return type:bool
trivialize()

Trivializes tuplet.

>>> tuplet = abjad.Tuplet((3, 4), "c'2")
>>> abjad.show(tuplet) 
>>> tuplet.trivializable()
True
>>> tuplet.trivialize()
>>> abjad.show(tuplet) 
Return type:None

Class & static methods

static from_duration(duration, components)

Makes tuplet from duration and components.

Makes diminution:

>>> tuplet = abjad.Tuplet.from_duration((2, 8), "c'8 d' e'")
>>> abjad.show(tuplet) 
Return type:Tuplet
static from_duration_and_ratio(duration, ratio, decrease_monotonic=True)

Makes tuplet from duration and ratio.

Makes tupletted leaves strictly without dots when all ratio equal 1:

>>> tuplet = abjad.Tuplet.from_duration_and_ratio(
...     abjad.Duration(3, 16),
...     abjad.Ratio((1, 1, 1, -1, -1)),
...     )
>>> staff = abjad.Staff(
...     [abjad.Measure((3, 16), [tuplet])],
...     lilypond_type='RhythmicStaff',
...     )
>>> abjad.show(staff) 

Allows tupletted leaves to return with dots when some ratio do not equal 1:

>>> tuplet = abjad.Tuplet.from_duration_and_ratio(
...     abjad.Duration(3, 16),
...     abjad.Ratio((1, -2, -2, 3, 3)),
...     )
>>> staff = abjad.Staff(
...     [abjad.Measure((3, 16), [tuplet])],
...     lilypond_type='RhythmicStaff',
...     )
>>> abjad.show(staff) 

Interprets nonassignable ratio according to decrease_monotonic:

>>> tuplet = abjad.Tuplet.from_duration_and_ratio(
...     abjad.Duration(3, 16),
...     abjad.Ratio((5, -1, 5)),
...     decrease_monotonic=False,
...     )
>>> staff = abjad.Staff(
...     [abjad.Measure((3, 16), [tuplet])],
...     lilypond_type='RhythmicStaff',
...     )
>>> abjad.show(staff) 

Makes augmented tuplet from duration and ratio and encourages dots:

>>> tuplet = abjad.Tuplet.from_duration_and_ratio(
...     abjad.Duration(3, 16),
...     abjad.Ratio((1, 1, 1, -1, -1)),
...     )
>>> staff = abjad.Staff(
...     [abjad.Measure((3, 16), [tuplet])],
...     lilypond_type='RhythmicStaff',
...     )
>>> abjad.show(staff) 

Interprets nonassignable ratio according to decrease_monotonic:

>>> tuplet = abjad.Tuplet.from_duration_and_ratio(
...     abjad.Duration(3, 16),
...     abjad.Ratio((5, -1, 5)),
...     decrease_monotonic=False,
...     )
>>> staff = abjad.Staff(
...     [abjad.Measure((3, 16), [tuplet])],
...     lilypond_type='RhythmicStaff',
...     )
>>> abjad.show(staff) 

Makes diminished tuplet from duration and nonzero integer ratio.

Makes tupletted leaves strictly without dots when all ratio equal 1:

>>> tuplet = abjad.Tuplet.from_duration_and_ratio(
...     abjad.Duration(3, 16),
...     abjad.Ratio((1, 1, 1, -1, -1)),
...     )
>>> staff = abjad.Staff(
...     [abjad.Measure((3, 16), [tuplet])],
...     lilypond_type='RhythmicStaff',
...     )
>>> abjad.show(staff) 

Allows tupletted leaves to return with dots when some ratio do not equal 1:

>>> tuplet = abjad.Tuplet.from_duration_and_ratio(
...     abjad.Duration(3, 16),
...     abjad.Ratio((1, -2, -2, 3, 3)),
...     )
>>> staff = abjad.Staff(
...     [abjad.Measure((3, 16), [tuplet])],
...     lilypond_type='RhythmicStaff',
...     )
>>> abjad.show(staff) 

Interprets nonassignable ratio according to decrease_monotonic:

>>> tuplet = abjad.Tuplet.from_duration_and_ratio(
...     abjad.Duration(3, 16),
...     abjad.Ratio((5, -1, 5)),
...     decrease_monotonic=False,
...     )
>>> staff = abjad.Staff(
...     [abjad.Measure((3, 16), [tuplet])],
...     lilypond_type='RhythmicStaff',
...     )
>>> abjad.show(staff) 

Makes diminished tuplet from duration and ratio and encourages dots:

>>> tuplet = abjad.Tuplet.from_duration_and_ratio(
...     abjad.Duration(3, 16),
...     abjad.Ratio((1, 1, 1, -1, -1)),
...     )
>>> staff = abjad.Staff(
...     [abjad.Measure((3, 16), [tuplet])],
...     lilypond_type = 'RhythmicStaff',
...     )
>>> abjad.show(staff) 

Interprets nonassignable ratio according to direction:

>>> tuplet = abjad.Tuplet.from_duration_and_ratio(
...     abjad.Duration(3, 16),
...     abjad.Ratio((5, -1, 5)),
...     decrease_monotonic=False,
...     )
>>> staff = abjad.Staff(
...     [abjad.Measure((3, 16), [tuplet])],
...     lilypond_type='RhythmicStaff',
...     )
>>> abjad.show(measure) 

Reduces ratio relative to each other.

Interprets negative ratio as rests.

Returns tuplet.

Return type:Tuplet
static from_leaf_and_ratio(leaf, ratio)

Makes tuplet from leaf and ratio.

>>> note = abjad.Note("c'8.")
>>> tuplet = abjad.Tuplet.from_leaf_and_ratio(
...     note,
...     abjad.Ratio((1,)),
...     )
>>> staff = abjad.Staff(
...     [abjad.Measure((3, 16), [tuplet])],
...     lilypond_type='RhythmicStaff',
...     )
>>> abjad.show(staff) 
>>> tuplet = abjad.Tuplet.from_leaf_and_ratio(
...     note,
...     [1, 2],
...     )
>>> staff = abjad.Staff(
...     [abjad.Measure((3, 16), [tuplet])],
...     lilypond_type='RhythmicStaff',
...     )
>>> abjad.show(staff) 
>>> tuplet = abjad.Tuplet.from_leaf_and_ratio(
...     note,
...     abjad.Ratio((1, 2, 2)),
...     )
>>> staff = abjad.Staff(
...     [abjad.Measure((3, 16), [tuplet])],
...     lilypond_type='RhythmicStaff',
...     )
>>> abjad.show(staff) 
>>> tuplet = abjad.Tuplet.from_leaf_and_ratio(
...     note,
...     [1, 2, 2, 3],
...     )
>>> staff = abjad.Staff(
...     [abjad.Measure((3, 16), [tuplet])],
...     lilypond_type='RhythmicStaff',
...     )
>>> abjad.show(staff) 
>>> tuplet = abjad.Tuplet.from_leaf_and_ratio(
...     note,
...     [1, 2, 2, 3, 3],
...     )
>>> staff = abjad.Staff(
...     [abjad.Measure((3, 16), [tuplet])],
...     lilypond_type='RhythmicStaff',
...     )
>>> abjad.show(staff) 
>>> tuplet = abjad.Tuplet.from_leaf_and_ratio(
...     note,
...     abjad.Ratio((1, 2, 2, 3, 3, 4)),
...     )
>>> staff = abjad.Staff(
...     [abjad.Measure((3, 16), [tuplet])],
...     lilypond_type='RhythmicStaff',
...     )
>>> abjad.show(staff) 
>>> tuplet = abjad.Tuplet.from_leaf_and_ratio(
...     note,
...     [1],
...     )
>>> staff = abjad.Staff(
...     [abjad.Measure((3, 16), [tuplet])],
...     lilypond_type='RhythmicStaff',
...     )
>>> abjad.show(staff) 
>>> tuplet = abjad.Tuplet.from_leaf_and_ratio(
...     note,
...     [1, 2],
...     )
>>> staff = abjad.Staff(
...     [abjad.Measure((3, 16), [tuplet])],
...     lilypond_type='RhythmicStaff',
...     )
>>> abjad.show(staff) 
>>> tuplet = abjad.Tuplet.from_leaf_and_ratio(
...     note,
...     [1, 2, 2],
...     )
>>> staff = abjad.Staff(
...     [abjad.Measure((3, 16), [tuplet])],
...     lilypond_type='RhythmicStaff',
...     )
>>> abjad.show(staff) 
>>> tuplet = abjad.Tuplet.from_leaf_and_ratio(
...     note,
...     [1, 2, 2, 3],
...     )
>>> staff = abjad.Staff(
...     [abjad.Measure((3, 16), [tuplet])],
...     lilypond_type='RhythmicStaff',
...     )
>>> abjad.show(staff) 
>>> tuplet = abjad.Tuplet.from_leaf_and_ratio(
...     note,
...     [1, 2, 2, 3, 3],
...     )
>>> staff = abjad.Staff(
...     [abjad.Measure((3, 16), [tuplet])],
...     lilypond_type='RhythmicStaff',
...     )
>>> abjad.show(staff) 
>>> tuplet = abjad.Tuplet.from_leaf_and_ratio(
...     note,
...     [1, 2, 2, 3, 3, 4],
...     )
>>> staff = abjad.Staff(
...     [abjad.Measure((3, 16), [tuplet])],
...     lilypond_type='RhythmicStaff',
...     )
>>> abjad.show(staff) 

Returns tuplet.

Return type:Tuplet
static from_ratio_and_pair(ratio, fraction)

Makes tuplet from nonreduced ratio and nonreduced fraction.

>>> tuplet = abjad.Tuplet.from_ratio_and_pair(
...     abjad.NonreducedRatio((1,)),
...     abjad.NonreducedFraction(7, 16),
...     )
>>> staff = abjad.Staff(
...     [abjad.Measure((7, 16), [tuplet])],
...     lilypond_type='RhythmicStaff',
...     )
>>> abjad.show(staff) 
>>> tuplet = abjad.Tuplet.from_ratio_and_pair(
...     abjad.NonreducedRatio((1, 2)),
...     abjad.NonreducedFraction(7, 16),
...     )
>>> staff = abjad.Staff(
...     [abjad.Measure((7, 16), [tuplet])],
...     lilypond_type='RhythmicStaff',
...     )
>>> abjad.show(staff) 
>>> tuplet = abjad.Tuplet.from_ratio_and_pair(
...     abjad.NonreducedRatio((1, 2, 4)),
...     abjad.NonreducedFraction(7, 16),
...     )
>>> staff = abjad.Staff(
...     [abjad.Measure((7, 16), [tuplet])],
...     lilypond_type='RhythmicStaff',
...     )
>>> abjad.show(staff) 
>>> tuplet = abjad.Tuplet.from_ratio_and_pair(
...     abjad.NonreducedRatio((1, 2, 4, 1)),
...     abjad.NonreducedFraction(7, 16),
...     )
>>> staff = abjad.Staff(
...     [abjad.Measure((7, 16), [tuplet])],
...     lilypond_type='RhythmicStaff',
...     )
>>> abjad.show(staff) 
>>> tuplet = abjad.Tuplet.from_ratio_and_pair(
...     abjad.NonreducedRatio((1, 2, 4, 1, 2)),
...     abjad.NonreducedFraction(7, 16),
...     )
>>> staff = abjad.Staff(
...     [abjad.Measure((7, 16), [tuplet])],
...     lilypond_type='RhythmicStaff',
...     )
>>> abjad.show(staff) 
>>> tuplet = abjad.Tuplet.from_ratio_and_pair(
...     abjad.NonreducedRatio((1, 2, 4, 1, 2, 4)),
...     abjad.NonreducedFraction(7, 16),
...     )
>>> staff = abjad.Staff(
...     [abjad.Measure((7, 16), [tuplet])],
...     lilypond_type='RhythmicStaff',
...     )
>>> abjad.show(staff) 

Interprets d as tuplet denominator.

Return type:Tuplet

Read/write properties

denominator

Gets and sets preferred denominator of tuplet.

Gets preferred denominator of tuplet:

>>> tuplet = abjad.Tuplet((2, 3), "c'8 d'8 e'8")
>>> tuplet.denominator is None
True
>>> abjad.show(tuplet) 

Sets preferred denominator of tuplet:

>>> tuplet = abjad.Tuplet((2, 3), "c'8 d'8 e'8")
>>> abjad.show(tuplet) 
>>> tuplet.denominator = 4
>>> abjad.show(tuplet) 
Return type:Optional[int]
force_fraction

Gets and sets force fraction flag.

The default.ily stylesheet included in all Abjad API examples includes the following:

\override TupletNumber.text = #tuplet-number::calc-fraction-text

This means that even simple tuplets format as explicit fractions:

>>> staff = abjad.Staff()
>>> staff.append(abjad.Tuplet((2, 3), "c'4 d' e'"))
>>> staff.append(abjad.Tuplet((2, 3), "c'4 d' e'"))
>>> staff.append(abjad.Tuplet((2, 3), "c'4 d' e'"))
>>> abjad.show(staff) 

To illustrate the effect of Abjad’s force fraction property, we can temporarily restore LilyPond’s default tuplet number formatting like this:

>>> staff = abjad.Staff()
>>> staff.append(abjad.Tuplet((2, 3), "c'4 d' e'"))
>>> staff.append(abjad.Tuplet((2, 3), "c'4 d' e'"))
>>> staff.append(abjad.Tuplet((2, 3), "c'4 d' e'"))
>>> string = 'tuplet-number::calc-denominator-text'
>>> abjad.override(staff).tuplet_number.text = string
>>> abjad.show(staff) 

Which makes it possible to see the effect of setting force fraction to true on a single tuplet:

>>> tuplet = staff[1]
>>> tuplet.force_fraction = True
>>> abjad.show(staff) 

Ignored when tuplet number text is overridden explicitly:

>>> tuplet = abjad.Tuplet((2, 3), "c'8 d'8 e'8")
>>> duration = abjad.inspect(tuplet).duration()
>>> markup = duration.to_score_markup()
>>> abjad.override(tuplet).tuplet_number.text = markup
>>> staff = abjad.Staff([tuplet])
>>> abjad.show(staff) 
Return type:Optional[bool]
hide

Is true when tuplet bracket hides.

>>> tuplet = abjad.Tuplet((2, 3), "c'8 d'8 e'8")
>>> abjad.show(tuplet) 
>>> tuplet.hide is None
True
>>> tuplet_1 = abjad.Tuplet((2, 3), "c'4 d'4 e'4")
>>> tuplet_2 = abjad.Tuplet((2, 3), "d'4 e'4 f'4")
>>> staff = abjad.Staff([tuplet_1, tuplet_2])
>>> abjad.show(staff) 
>>> staff[0].hide = True
>>> abjad.show(staff) 

Hides tuplet bracket and tuplet number when true.

Return type:Optional[bool]
(Container).identifier

Gets and sets bracket comment.

>>> container = abjad.Container(
...     "c'4 d'4 e'4 f'4",
...     identifier='%*% AB',
...     )
>>> abjad.show(container) 
>>> abjad.f(container)
{   %*% AB
    c'4
    d'4
    e'4
    f'4
}   %*% AB
Return type:Optional[str]
(Container).is_simultaneous

Is true when container is simultaneous.

Gets simultaneity status of container:

>>> container = abjad.Container()
>>> container.append(abjad.Voice("c'8 d'8 e'8"))
>>> container.append(abjad.Voice('g4.'))
>>> abjad.show(container) 
>>> container.is_simultaneous is None
True

Sets simultaneity status of container:

>>> container = abjad.Container()
>>> container.append(abjad.Voice("c'8 d'8 e'8"))
>>> container.append(abjad.Voice('g4.'))
>>> abjad.show(container) 
>>> container.is_simultaneous = True
>>> abjad.show(container) 
Return type:Optional[bool]
multiplier

Gets and sets multiplier of tuplet.

Gets tuplet multiplier:

>>> tuplet = abjad.Tuplet((2, 3), "c'8 d'8 e'8")
>>> abjad.show(tuplet) 
>>> tuplet.multiplier
Multiplier(2, 3)

Sets tuplet multiplier:

>>> tuplet.multiplier = abjad.Multiplier(4, 3)
>>> abjad.show(tuplet) 
Return type:Multiplier
(Container).name

Gets and sets name of container.

Gets container name:

>>> container = abjad.Container("c'4 d'4 e'4 f'4")
>>> abjad.show(container) 
>>> container.name is None
True

Sets container name:

>>> container = abjad.Container(
...     "c'4 d'4 e'4 f'4",
...     name='Special',
...     )
>>> abjad.show(container) 
>>> container.name
'Special'

Container name does not appear in LilyPond output:

>>> abjad.f(container)
{
    c'4
    d'4
    e'4
    f'4
}
Return type:Optional[str]

Read-only properties

(Container).components

Gets components in container.

Return type:tuple
implied_prolation

Gets implied prolation of tuplet.

Defined equal to tuplet multiplier:

>>> tuplet = abjad.Tuplet((2, 3), "c'8 d'8 e'8")
>>> abjad.show(tuplet) 
>>> tuplet.implied_prolation
Multiplier(2, 3)
Return type:Multiplier
multiplied_duration

Gets multiplied duration of tuplet.

>>> tuplet = abjad.Tuplet((2, 3), "c'8 d'8 e'8")
>>> abjad.show(tuplet) 
>>> tuplet.multiplied_duration
Duration(1, 4)
Return type:Duration
tweaks

Gets tweaks.

>>> tuplet_1 = abjad.Tuplet((2, 3), "c'4 ( d'4 e'4 )")
>>> abjad.tweak(tuplet_1).color = 'red'
>>> abjad.tweak(tuplet_1).staff_padding = 2
>>> tuplet_2 = abjad.Tuplet((2, 3), "c'4 ( d'4 e'4 )")
>>> abjad.tweak(tuplet_2).color = 'green'
>>> abjad.tweak(tuplet_2).staff_padding = 2
>>> tuplet_3 = abjad.Tuplet((5, 4), [tuplet_1, tuplet_2])
>>> abjad.tweak(tuplet_3).color = 'blue'
>>> abjad.tweak(tuplet_3).staff_padding = 4
>>> staff = abjad.Staff([tuplet_3])
>>> leaves = abjad.select(staff).leaves()
>>> abjad.attach(abjad.TimeSignature((5, 4)), leaves[0])
>>> literal = abjad.LilyPondLiteral(r'\set tupletFullLength = ##t')
>>> abjad.attach(literal, staff)
>>> abjad.show(staff) 

Todo

Report LilyPond bug that results from removing tupletFullLength in the example above: blue tuplet bracket shrinks to encompass only the second underlying tuplet.