TupletSpecifier

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.system" { graph [label="abjad.system"]; node [color=1]; "abjad.system.AbjadObject.AbjadObject" [URL="../api/abjadext/rmakers/../../abjad/system/AbjadObject.html#abjad.system.AbjadObject.AbjadObject", label="Abjad\nObject", target=_top]; "abjad.system.AbjadValueObject.AbjadValueObject" [URL="../api/abjadext/rmakers/../../abjad/system/AbjadValueObject.html#abjad.system.AbjadValueObject.AbjadValueObject", label="Abjad\nValue\nObject", target=_top]; "abjad.system.AbjadObject.AbjadObject" -> "abjad.system.AbjadValueObject.AbjadValueObject"; } subgraph "cluster_abjadext.rmakers" { graph [label="abjadext.rmakers"]; node [color=2]; "abjadext.rmakers.TupletSpecifier.TupletSpecifier" [URL="../api/abjadext/rmakers/TupletSpecifier.html#abjadext.rmakers.TupletSpecifier.TupletSpecifier", color=black, fontcolor=white, label="Tuplet\nSpecifier", 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.AbjadValueObject.AbjadValueObject" -> "abjadext.rmakers.TupletSpecifier.TupletSpecifier"; "builtins.object" -> "abjad.system.AbjadObject.AbjadObject"; }

class abjadext.rmakers.TupletSpecifier.TupletSpecifier(*, denominator=None, diminution=None, duration_bracket=None, extract_trivial=None, force_fraction=None, rewrite_dots=None, rewrite_rest_filled=None, rewrite_sustained=None, trivialize=None)

Tuplet specifier.

>>> specifier = abjadext.rmakers.TupletSpecifier()
>>> abjad.f(specifier)
abjadext.rmakers.TupletSpecifier()

Attributes Summary

__call__ Calls tuplet specifier.
denominator Gets preferred denominator.
diminution Is true when tuplet should be spelled as diminution.
duration_bracket Is true when tuplet should override tuplet number text with note duration bracket giving tuplet duration.
extract_trivial Is true when rhythm-maker should extract trivial tuplets.
force_fraction Is true when tuplet forces tuplet number fraction formatting.
is_sustained_tuplet Is true when argument is sustained tuplet.
rewrite_dots Is true when tuplet rewrites dots.
rewrite_rest_filled Is true when rhythm-maker rewrites rest-filled tuplets.
rewrite_sustained Is true when rhythm-maker rewrites sustained tuplets.
trivialize Is true when trivializable tuplets should be trivialized.

Special methods

__call__(selections, divisions)

Calls tuplet specifier.

Return type:List[Selection]
(AbjadValueObject).__copy__(*arguments)

Copies Abjad value object.

Returns new Abjad value object.

(AbjadValueObject).__eq__(argument)

Is true when all initialization values of Abjad value object equal the initialization values of argument.

Returns true or false.

(AbjadObject).__format__(format_specification='')

Formats Abjad object.

Set format_specification to '' or 'storage'. Interprets '' equal to 'storage'.

Returns string.

(AbjadValueObject).__hash__()

Hashes Abjad value object.

Returns integer.

(AbjadObject).__repr__()

Gets interpreter representation of Abjad object.

Returns string.


Class & static methods

static is_sustained_tuplet(argument)

Is true when argument is sustained tuplet.


Read-only properties

denominator

Gets preferred denominator.

Tuplet numerators and denominators are reduced to numbers that are relatively prime when denominator is set to none. This means that ratios like 6:4 and 10:8 do not arise:

>>> rhythm_maker = abjadext.rmakers.TupletRhythmMaker(
...     tuplet_ratios=[(1, 4)],
...     tuplet_specifier=abjadext.rmakers.TupletSpecifier(
...         rewrite_dots=True,
...         denominator=None,
...         ),
...     )
>>> divisions = [(2, 16), (4, 16), (6, 16), (8, 16)]
>>> selections = rhythm_maker(divisions)
>>> lilypond_file = abjad.LilyPondFile.rhythm(
...     selections,
...     divisions,
...     )
>>> abjad.show(lilypond_file) 

The preferred denominator of each tuplet is set to the numerator of the division that generates the tuplet when denominator is set to the string 'divisions'. This means that the tuplet numerator and denominator are not necessarily relatively prime. This also means that ratios like 6:4 and 10:8 may arise:

>>> rhythm_maker = abjadext.rmakers.TupletRhythmMaker(
...     tuplet_ratios=[(1, 4)],
...     tuplet_specifier=abjadext.rmakers.TupletSpecifier(
...         rewrite_dots=True,
...         denominator='divisions',
...         ),
...     )
>>> divisions = [(2, 16), (4, 16), (6, 16), (8, 16)]
>>> selections = rhythm_maker(divisions)
>>> lilypond_file = abjad.LilyPondFile.rhythm(
...     selections,
...     divisions,
...     )
>>> abjad.show(lilypond_file) 

The preferred denominator of each tuplet is set in terms of a unit duration when denominator is set to a duration. The setting does not affect the first tuplet:

>>> rhythm_maker = abjadext.rmakers.TupletRhythmMaker(
...     tuplet_ratios=[(1, 4)],
...     tuplet_specifier=abjadext.rmakers.TupletSpecifier(
...         rewrite_dots=True,
...         denominator=(1, 16),
...         ),
...     )
>>> divisions = [(2, 16), (4, 16), (6, 16), (8, 16)]
>>> selections = rhythm_maker(divisions)
>>> lilypond_file = abjad.LilyPondFile.rhythm(
...     selections,
...     divisions,
...     )
>>> abjad.show(lilypond_file) 

Sets the preferred denominator of each tuplet in terms 32nd notes. The setting affects all tuplets:

>>> rhythm_maker = abjadext.rmakers.TupletRhythmMaker(
...     tuplet_ratios=[(1, 4)],
...     tuplet_specifier=abjadext.rmakers.TupletSpecifier(
...         rewrite_dots=True,
...         denominator=(1, 32),
...         ),
...     )
>>> divisions = [(2, 16), (4, 16), (6, 16), (8, 16)]
>>> selections = rhythm_maker(divisions)
>>> lilypond_file = abjad.LilyPondFile.rhythm(
...     selections,
...     divisions,
...     )
>>> abjad.show(lilypond_file) 

Sets the preferred denominator each tuplet in terms 64th notes. The setting affects all tuplets:

>>> rhythm_maker = abjadext.rmakers.TupletRhythmMaker(
...     tuplet_ratios=[(1, 4)],
...     tuplet_specifier=abjadext.rmakers.TupletSpecifier(
...         rewrite_dots=True,
...         denominator=(1, 64),
...         ),
...     )
>>> divisions = [(2, 16), (4, 16), (6, 16), (8, 16)]
>>> selections = rhythm_maker(divisions)
>>> lilypond_file = abjad.LilyPondFile.rhythm(
...     selections,
...     divisions,
...     )
>>> abjad.show(lilypond_file) 

The preferred denominator of each tuplet is set directly when denominator is set to a positive integer. This example sets the preferred denominator of each tuplet to 8. Setting does not affect the third tuplet:

>>> rhythm_maker = abjadext.rmakers.TupletRhythmMaker(
...     tuplet_ratios=[(1, 4)],
...     tuplet_specifier=abjadext.rmakers.TupletSpecifier(
...         rewrite_dots=True,
...         denominator=8,
...         ),
...     )
>>> divisions = [(2, 16), (4, 16), (6, 16), (8, 16)]
>>> selections = rhythm_maker(divisions)
>>> lilypond_file = abjad.LilyPondFile.rhythm(
...     selections,
...     divisions,
...     )
>>> abjad.show(lilypond_file) 

Sets the preferred denominator of each tuplet to 12. Setting affects all tuplets:

>>> rhythm_maker = abjadext.rmakers.TupletRhythmMaker(
...     tuplet_ratios=[(1, 4)],
...     tuplet_specifier=abjadext.rmakers.TupletSpecifier(
...         rewrite_dots=True,
...         denominator=12,
...         ),
...     )
>>> divisions = [(2, 16), (4, 16), (6, 16), (8, 16)]
>>> selections = rhythm_maker(divisions)
>>> lilypond_file = abjad.LilyPondFile.rhythm(
...     selections,
...     divisions,
...     )
>>> abjad.show(lilypond_file) 

Sets the preferred denominator of each tuplet to 13. Setting does not affect any tuplet:

>>> rhythm_maker = abjadext.rmakers.TupletRhythmMaker(
...     tuplet_ratios=[(1, 4)],
...     tuplet_specifier=abjadext.rmakers.TupletSpecifier(
...         rewrite_dots=True,
...         denominator=13,
...         ),
...     )
>>> divisions = [(2, 16), (4, 16), (6, 16), (8, 16)]
>>> selections = rhythm_maker(divisions)
>>> lilypond_file = abjad.LilyPondFile.rhythm(
...     selections,
...     divisions,
...     )
>>> abjad.show(lilypond_file) 

Set to 'divisions', duration, positive integer or none.

Return type:Union[str, Duration, int, None]
diminution

Is true when tuplet should be spelled as diminution.

Is false when tuplet should be spelled as augmentation.

Is none when tuplet spelling does not force prolation.

Return type:Optional[bool]
duration_bracket

Is true when tuplet should override tuplet number text with note duration bracket giving tuplet duration.

Return type:Optional[bool]
extract_trivial

Is true when rhythm-maker should extract trivial tuplets.

Return type:Optional[bool]
force_fraction

Is true when tuplet forces tuplet number fraction formatting.

The defaulti.ly 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:

>>> rhythm_maker = abjadext.rmakers.EvenDivisionRhythmMaker(
...     extra_counts_per_division=[1],
...     )
>>> divisions = [(2, 8), (2, 8), (2, 8)]
>>> selections = rhythm_maker(divisions)
>>> lilypond_file = abjad.LilyPondFile.rhythm(
...     selections,
...     divisions,
...     )
>>> abjad.show(lilypond_file) 

We can temporarily restore LilyPond’s default tuplet numbering like this:

>>> rhythm_maker = abjadext.rmakers.EvenDivisionRhythmMaker(
...     extra_counts_per_division=[1],
...     )
>>> divisions = [(2, 8), (2, 8), (2, 8)]
>>> selections = rhythm_maker(divisions)
>>> lilypond_file = abjad.LilyPondFile.rhythm(
...     selections,
...     divisions,
...     )
>>> staff = lilypond_file[abjad.Staff]
>>> string = 'tuplet-number::calc-denominator-text'
>>> abjad.override(staff).tuplet_number.text = string
>>> abjad.show(lilypond_file) 

Which then makes it possible to show that the force fraction property cancels LilyPond’s default tuplet numbering once again:

>>> rhythm_maker = abjadext.rmakers.EvenDivisionRhythmMaker(
...     extra_counts_per_division=[1],
...     tuplet_specifier=abjadext.rmakers.TupletSpecifier(
...         force_fraction=True,
...         ),
...     )
>>> divisions = [(2, 8), (2, 8), (2, 8)]
>>> selections = rhythm_maker(divisions)
>>> lilypond_file = abjad.LilyPondFile.rhythm(
...     selections,
...     divisions,
...     )
>>> staff = lilypond_file[abjad.Staff]
>>> string = 'tuplet-number::calc-denominator-text'
>>> abjad.override(staff).tuplet_number.text = string
>>> abjad.show(lilypond_file) 
Return type:Optional[bool]
rewrite_dots

Is true when tuplet rewrites dots.

Return type:Optional[bool]
rewrite_rest_filled

Is true when rhythm-maker rewrites rest-filled tuplets.

Return type:Optional[bool]
rewrite_sustained

Is true when rhythm-maker rewrites sustained tuplets.

Sustained tuplets generalize a class of rhythms composers are likely to rewrite:

>>> rhythm_maker = abjadext.rmakers.TaleaRhythmMaker(
...     extra_counts_per_division=[2, 1, 1, 1],
...     talea=abjadext.rmakers.Talea(
...         counts=[6, 5, 5, 4, 1],
...         denominator=16,
...         ),
...     tie_specifier=abjadext.rmakers.TieSpecifier(
...         tie_across_divisions=abjad.index([1, 2]),
...         ),
...     )
>>> divisions = [(4, 16), (4, 16), (4, 16), (4, 16)]
>>> selections = rhythm_maker(divisions)
>>> lilypond_file = abjad.LilyPondFile.rhythm(
...     selections,
...     divisions,
...     )
>>> abjad.show(lilypond_file) 

The first three tuplets in the example above qualify as sustained:

>>> staff = lilypond_file[abjad.Staff]
>>> for tuplet in abjad.iterate(staff).components(abjad.Tuplet):
...     abjadext.rmakers.TupletSpecifier.is_sustained_tuplet(tuplet)
... 
True
True
True
False

Tuplets 0 and 1 each contain only a single tuplet-initial attack. Tuplet 2 contains no attack at all. All three fill their duration completely.

Tuplet 3 contains a nonintial attack that rearticulates the tuplet’s duration midway through the course of the figure. Tuplet 3 does not qualify as sustained.

Rewrite sustained tuplets like this:

>>> rhythm_maker = abjadext.rmakers.TaleaRhythmMaker(
...     extra_counts_per_division=[2, 1, 1, 1],
...     talea=abjadext.rmakers.Talea(
...         counts=[6, 5, 5, 4, 1],
...         denominator=16,
...         ),
...     tie_specifier=abjadext.rmakers.TieSpecifier(
...         tie_across_divisions=abjad.index([1, 2]),
...         ),
...     tuplet_specifier=abjadext.rmakers.TupletSpecifier(
...         rewrite_sustained=True,
...         ),
...     )
>>> divisions = [(4, 16), (4, 16), (4, 16), (4, 16)]
>>> selections = rhythm_maker(divisions)
>>> lilypond_file = abjad.LilyPondFile.rhythm(
...     selections,
...     divisions,
...     )
>>> abjad.show(lilypond_file) 

Rewrite sustained tuplets – and then extract the trivial tuplets that result – like this:

>>> rhythm_maker = abjadext.rmakers.TaleaRhythmMaker(
...     extra_counts_per_division=[2, 1, 1, 1],
...     talea=abjadext.rmakers.Talea(
...         counts=[6, 5, 5, 4, 1],
...         denominator=16,
...         ),
...     tie_specifier=abjadext.rmakers.TieSpecifier(
...         tie_across_divisions=abjad.index([1, 2]),
...         ),
...     tuplet_specifier=abjadext.rmakers.TupletSpecifier(
...         extract_trivial=True,
...         rewrite_sustained=True,
...         ),
...     )
>>> divisions = [(4, 16), (4, 16), (4, 16), (4, 16)]
>>> selections = rhythm_maker(divisions)
>>> lilypond_file = abjad.LilyPondFile.rhythm(
...     selections,
...     divisions,
...     )
>>> abjad.show(lilypond_file) 
Return type:Optional[bool]
trivialize

Is true when trivializable tuplets should be trivialized.

Return type:Optional[bool]