abjad.duration

`abjad.duration.add_pairs`(pair_1, pair_2)	Adds `pair_1` to `pair_2`.
`abjad.duration.divide_pair`(pair, n)	Divides `pair` by integer `n`.
`abjad.duration.durations`(durations)	Changes `durations` to durations.
`abjad.duration.fraction_from_dot_count`(dot_count)	Makes fraction from `dot_count`.
`abjad.duration.pair`(argument)	Changes `argument` to pair.
`abjad.duration.with_denominator`(duration, ...)	Spells `duration` as pair with `denominator`.
`abjad.duration.Duration`(*arguments)	Duration.
`abjad.duration.Offset`(arguments, *keywords)	Offset.
`abjad.duration.Ratio`(numerator, denominator)	Ratio.

abjad.duration.add_pairs(pair_1, pair_2)[source]: Adds pair_1 to pair_2.

abjad.duration.divide_pair(pair, n) → tuple[int, int][source]: Divides pair by integer n.

abjad.duration.durations(durations) → list[Duration][source]

Changes durations to durations.

>>> abjad.durations([(15, 8), (3, 8)])
[Duration(15, 8), Duration(3, 8)]

abjad.duration.fraction_from_dot_count(dot_count: int) → Fraction[source]

Makes fraction from dot_count.

>>> abjad.duration.fraction_from_dot_count(0)
Fraction(1, 1)

>>> abjad.duration.fraction_from_dot_count(1)
Fraction(3, 2)

>>> abjad.duration.fraction_from_dot_count(2)
Fraction(7, 4)

>>> abjad.duration.fraction_from_dot_count(3)
Fraction(15, 8)

>>> abjad.duration.fraction_from_dot_count(4)
Fraction(31, 16)

abjad.duration.pair(argument) → tuple[int, int][source]

Changes argument to pair.

>>> abjad.duration.pair((3, 6))
(3, 6)

>>> abjad.duration.pair(abjad.Fraction(3, 6))
(1, 2)

>>> abjad.duration.pair(abjad.Duration(3, 6))
(1, 2)

>>> abjad.duration.pair(abjad.Offset((3, 6)))
(1, 2)

>>> abjad.duration.pair(abjad.TimeSignature((3, 6)))
(3, 6)

abjad.duration.with_denominator(duration, denominator) → tuple[int, int][source]

Spells duration as pair with denominator.

>>> abjad.duration.with_denominator(abjad.Duration(3, 6), 12)
(6, 12)

>>> for numerator in range(12):
...     fraction = abjad.Fraction(numerator, 6)
...     print(fraction, abjad.duration.with_denominator(fraction, 12))
... 
0 (0, 12)
1/6 (2, 12)
1/3 (4, 12)
1/2 (6, 12)
2/3 (8, 12)
5/6 (10, 12)
1 (12, 12)
7/6 (14, 12)
4/3 (16, 12)
3/2 (18, 12)
5/3 (20, 12)
11/6 (22, 12)

>>> for numerator in range(12):
...     pair = (numerator, 6)
...     print(pair, abjad.duration.with_denominator(pair, 8))
... 
(0, 6) (0, 8)
(1, 6) (1, 6)
(2, 6) (2, 6)
(3, 6) (4, 8)
(4, 6) (4, 6)
(5, 6) (5, 6)
(6, 6) (8, 8)
(7, 6) (7, 6)
(8, 6) (8, 6)
(9, 6) (12, 8)
(10, 6) (10, 6)
(11, 6) (11, 6)

>>> for numerator in range(12):
...     pair = (numerator, 6)
...     print(pair, abjad.duration.with_denominator(pair, 12))
... 
(0, 6) (0, 12)
(1, 6) (2, 12)
(2, 6) (4, 12)
(3, 6) (6, 12)
(4, 6) (8, 12)
(5, 6) (10, 12)
(6, 6) (12, 12)
(7, 6) (14, 12)
(8, 6) (16, 12)
(9, 6) (18, 12)
(10, 6) (20, 12)
(11, 6) (22, 12)

class abjad.duration.Duration(*arguments)[source]

Duration.

Initializes from integer numerator:

>>> abjad.Duration(3)
Duration(3, 1)

Initializes from integer numerator and denominator:

>>> abjad.Duration(3, 16)
Duration(3, 16)

Initializes from integer-equivalent numeric numerator:

>>> abjad.Duration(3.0)
Duration(3, 1)

Initializes from integer-equivalent numeric numerator and denominator:

>>> abjad.Duration(3.0, 16)
Duration(3, 16)

Initializes from integer-equivalent singleton:

>>> abjad.Duration((3,))
Duration(3, 1)

Initializes from integer-equivalent pair:

>>> abjad.Duration((3, 16))
Duration(3, 16)

Initializes from other duration:

>>> abjad.Duration(abjad.Duration(3, 16))
Duration(3, 16)

Intializes from fraction:

>>> import fractions
>>> abjad.Duration(fractions.Fraction(3, 16))
Duration(3, 16)

Initializes from solidus string:

>>> abjad.Duration("3/16")
Duration(3, 16)

Durations inherit from built-in fraction:

>>> isinstance(abjad.Duration(3, 16), fractions.Fraction)
True

Durations are numbers:

>>> import numbers

>>> isinstance(abjad.Duration(3, 16), numbers.Number)
True

`dot_count`	Gets dot count.
`equal_or_greater_assignable`	Gets assignable duration equal to or just greater than this duration.
`equal_or_greater_power_of_two`	Gets duration equal or just greater power of two.
`equal_or_lesser_assignable`	Gets assignable duration equal or just less than this duration.
`equal_or_lesser_power_of_two`	Gets duration of the form `d**2` equal to or just less than this duration.
`exponent`	Gets base-2 exponent.
`flag_count`	Gets flag count.
`is_assignable`	Is true when duration is assignable.
`is_dyadic`()	Is true when denominator of duration is integer power of two.
`lilypond_duration_string`	Gets LilyPond duration string.
`pair`	Gets numerator and denominator pair.
`reciprocal`()	Gets reciprocal.
`to_clock_string`()	Changes duration to clock string.

dot_count

Gets dot count.

Dot count defined equal to number of dots required to notate duration. Raises assignability error when duration is not assignable.

>>> for n in range(1, 16 + 1):
...     try:
...         duration = abjad.Duration(n, 16)
...         sixteenths = abjad.duration.with_denominator(duration, 16)
...         dot_count = duration.dot_count
...         string = f"{sixteenths[0]}/{sixteenths[1]}\t{dot_count}"
...         print(string)
...     except abjad.AssignabilityError:
...         sixteenths = abjad.duration.with_denominator(duration, 16)
...         print(f"{sixteenths[0]}/{sixteenths[1]}\t--")
... 
1/16	0
2/16	0
3/16	1
4/16	0
5/16	--
6/16	1
7/16	2
8/16	0
9/16	--
10/16	--
11/16	--
12/16	1
13/16	--
14/16	2
15/16	3
16/16	0

equal_or_greater_assignable

Gets assignable duration equal to or just greater than this duration.

>>> for numerator in range(1, 16 + 1):
...     duration = abjad.Duration(numerator, 16)
...     result = duration.equal_or_greater_assignable
...     sixteenths = abjad.duration.with_denominator(duration, 16)
...     print(f"{sixteenths[0]}/{sixteenths[1]}\t{result!s}")
... 
1/16	1/16
2/16	1/8
3/16	3/16
4/16	1/4
5/16	3/8
6/16	3/8
7/16	7/16
8/16	1/2
9/16	3/4
10/16	3/4
11/16	3/4
12/16	3/4
13/16	7/8
14/16	7/8
15/16	15/16
16/16	1

equal_or_greater_power_of_two

Gets duration equal or just greater power of two.

>>> for numerator in range(1, 16 + 1):
...     duration = abjad.Duration(numerator, 16)
...     result = duration.equal_or_greater_power_of_two
...     sixteenths = abjad.duration.with_denominator(duration, 16)
...     print(f"{sixteenths[0]}/{sixteenths[1]}\t{result!s}")
... 
1/16	1/16
2/16	1/8
3/16	1/4
4/16	1/4
5/16	1/2
6/16	1/2
7/16	1/2
8/16	1/2
9/16	1
10/16	1
11/16	1
12/16	1
13/16	1
14/16	1
15/16	1
16/16	1

equal_or_lesser_assignable

Gets assignable duration equal or just less than this duration.

>>> for numerator in range(1, 16 + 1):
...     duration = abjad.Duration(numerator, 16)
...     result = duration.equal_or_lesser_assignable
...     sixteenths = abjad.duration.with_denominator(duration, 16)
...     print(f"{sixteenths[0]}/{sixteenths[1]}\t{result!s}")
... 
1/16	1/16
2/16	1/8
3/16	3/16
4/16	1/4
5/16	1/4
6/16	3/8
7/16	7/16
8/16	1/2
9/16	1/2
10/16	1/2
11/16	1/2
12/16	3/4
13/16	3/4
14/16	7/8
15/16	15/16
16/16	1

equal_or_lesser_power_of_two

Gets duration of the form d**2 equal to or just less than this duration.

>>> for numerator in range(1, 16 + 1):
...     duration = abjad.Duration(numerator, 16)
...     result = duration.equal_or_lesser_power_of_two
...     sixteenths = abjad.duration.with_denominator(duration, 16)
...     print(f"{sixteenths[0]}/{sixteenths[1]}\t{result!s}")
... 
1/16	1/16
2/16	1/8
3/16	1/8
4/16	1/4
5/16	1/4
6/16	1/4
7/16	1/4
8/16	1/2
9/16	1/2
10/16	1/2
11/16	1/2
12/16	1/2
13/16	1/2
14/16	1/2
15/16	1/2
16/16	1

exponent

Gets base-2 exponent.

>>> for numerator in range(1, 16 + 1):
...     duration = abjad.Duration(numerator, 16)
...     exponent = duration.exponent
...     sixteenths = abjad.duration.with_denominator(duration, 16)
...     print(f"{sixteenths[0]}/{sixteenths[1]}\t{duration.exponent!s}")
... 
1/16	4
2/16	3
3/16	3
4/16	2
5/16	2
6/16	2
7/16	2
8/16	1
9/16	1
10/16	1
11/16	1
12/16	1
13/16	1
14/16	1
15/16	1
16/16	0

flag_count

Gets flag count.

Flag count defined equal to number of flags required to notate duration.

>>> for n in range(1, 16 + 1):
...     duration = abjad.Duration(n, 64)
...     sixty_fourths = abjad.duration.with_denominator(duration, 64)
...     print(f"{sixty_fourths[0]}/{sixty_fourths[1]}\t{duration.flag_count}")
... 
1/64	4
2/64	3
3/64	3
4/64	2
5/64	2
6/64	2
7/64	2
8/64	1
9/64	1
10/64	1
11/64	1
12/64	1
13/64	1
14/64	1
15/64	1
16/64	0

is_assignable

Is true when duration is assignable.

>>> for numerator in range(0, 16 + 1):
...     duration = abjad.Duration(numerator, 16)
...     sixteenths = abjad.duration.with_denominator(duration, 16)
...     print(f"{sixteenths[0]}/{sixteenths[1]}\t{duration.is_assignable}")
... 
0/16	False
1/16	True
2/16	True
3/16	True
4/16	True
5/16	False
6/16	True
7/16	True
8/16	True
9/16	False
10/16	False
11/16	False
12/16	True
13/16	False
14/16	True
15/16	True
16/16	True

is_dyadic() → bool[source]

Is true when denominator of duration is integer power of two.

>>> for n in range(1, 16 + 1):
...     duration = abjad.Duration(1, n)
...     print(f"{duration!s}\t{duration.is_dyadic()}")
... 
1	True
1/2	True
1/3	False
1/4	True
1/5	False
1/6	False
1/7	False
1/8	True
1/9	False
1/10	False
1/11	False
1/12	False
1/13	False
1/14	False
1/15	False
1/16	True

lilypond_duration_string

Gets LilyPond duration string.

Raises assignability error when duration is not assignable.

>>> abjad.Duration(3, 16).lilypond_duration_string
'8.'

pair

Gets numerator and denominator pair.

>>> abjad.Duration(3, 16).pair
(3, 16)

reciprocal() → Duration[source]

Gets reciprocal.

>>> abjad.Duration(3, 7).reciprocal()
Duration(7, 3)

to_clock_string() → str[source]

Changes duration to clock string.

Rounds down to nearest second.

>>> note = abjad.Note("c'4")
>>> duration = abjad.Duration(117)
>>> clock_string = duration.to_clock_string()
>>> clock_string
"1'57''"

>>> string = rf"\markup {{ {clock_string} }}"
>>> markup = abjad.Markup(string)
>>> abjad.attach(markup, note, direction=abjad.UP)
>>> abjad.show(note)  

class abjad.duration.Offset(*arguments, **keywords)[source]

Offset.

Initializes from integer numerator:

>>> abjad.Offset(3)
Offset((3, 1))

Initializes from integer numerator and denominator:

>>> abjad.Offset(3, 16)
Offset((3, 16))

Initializes from integer-equivalent numeric numerator:

>>> abjad.Offset(3.0)
Offset((3, 1))

Initializes from integer-equivalent numeric numerator and denominator:

>>> abjad.Offset(3.0, 16)
Offset((3, 16))

Initializes from integer-equivalent singleton:

>>> abjad.Offset((3,))
Offset((3, 1))

Initializes from integer-equivalent pair:

>>> abjad.Offset((3, 16))
Offset((3, 16))

Initializes from duration:

>>> abjad.Offset(abjad.Duration(3, 16))
Offset((3, 16))

Initializes from other offset:

>>> abjad.Offset(abjad.Offset(3, 16))
Offset((3, 16))

Initializes from other offset with displacement:

>>> offset = abjad.Offset((3, 16), displacement=(-1, 16))
>>> abjad.Offset(offset)
Offset((3, 16), displacement=Duration(-1, 16))

Intializes from fraction:

>>> import fractions
>>> abjad.Offset(fractions.Fraction(3, 16))
Offset((3, 16))

Initializes from solidus string:

>>> abjad.Offset("3/16")
Offset((3, 16))

Offsets inherit from built-in fraction:

>>> isinstance(abjad.Offset(3, 16), fractions.Fraction)
True

Offsets are numbers:

>>> import numbers

>>> isinstance(abjad.Offset(3, 16), numbers.Number)
True

displacement

Gets displacement.

displacement

Gets displacement.

Gets displacement equal to none:

>>> offset = abjad.Offset(1, 4)
>>> offset.displacement is None
True

Gets displacement equal to a negative sixteenth:

>>> offset = abjad.Offset(1, 4, displacement=(-1, 16))
>>> offset.displacement
Duration(-1, 16)

Stores zero-valued displacement as none:

>>> offset = abjad.Offset(1, 4, displacement=0)
>>> offset.displacement is None
True

>>> offset
Offset((1, 4))

class abjad.duration.Ratio(numerator: int, denominator: int)[source]

Ratio.

Abjad ratios are two-term, unreduced integer ratios of the form n:d.

These are used primarily in modeling tuplet ratios like 3:2 and 6:4.

`as_fraction`()	Changes (unreduced) ratio to (reduced) fraction.
`is_augmented`()	Is true when ratio numerator is less than ratio denominator.
`is_canonical`()	Is true when ratio is normalized diminution.
`is_diminished`()	Is true when ratio denominator is less than ratio numerator.
`is_dyadic`()	Is true when ratio denominator is nonnegative integer power of two.
`is_normalized`()	Is true when fraction form of ratio is greater than `1/2` and less than `2`.
`is_reduced`()	Is true when ratio numerator and denominator are relatively prime.
`is_trivial`()	Is true when ratio numerator equals ratio denominator.
`reciprocal`()	Get reciprocal of ratio.

as_fraction()[source]

Changes (unreduced) ratio to (reduced) fraction.

>>> abjad.Ratio(6, 4).as_fraction()
Fraction(3, 2)

is_augmented() → bool[source]

Is true when ratio numerator is less than ratio denominator.

>>> abjad.Ratio(6, 4).is_augmented()
False

>>> abjad.Ratio(3, 2).is_augmented()
False

>>> abjad.Ratio(4, 6).is_augmented()
True

>>> abjad.Ratio(2, 3).is_augmented()
True

>>> abjad.Ratio(2, 2).is_augmented()
False

>>> abjad.Ratio(1, 1).is_augmented()
False

is_canonical() → bool[source]

Is true when ratio is normalized diminution.

>>> abjad.Ratio(6, 4).is_canonical()
True

>>> abjad.Ratio(3, 2).is_canonical()
True

>>> abjad.Ratio(4, 6).is_canonical()
False

>>> abjad.Ratio(2, 3).is_canonical()
False

>>> abjad.Ratio(2, 2).is_canonical()
False

>>> abjad.Ratio(1, 1).is_canonical()
False

is_diminished() → bool[source]

Is true when ratio denominator is less than ratio numerator.

>>> abjad.Ratio(6, 4).is_diminished()
True

>>> abjad.Ratio(3, 2).is_diminished()
True

>>> abjad.Ratio(4, 6).is_diminished()
False

>>> abjad.Ratio(2, 3).is_diminished()
False

>>> abjad.Ratio(2, 2).is_diminished()
False

>>> abjad.Ratio(1, 1).is_diminished()
False

is_dyadic() → bool[source]

Is true when ratio denominator is nonnegative integer power of two.

>>> abjad.Ratio(6, 4).is_dyadic()
True

>>> abjad.Ratio(3, 2).is_dyadic()
True

>>> abjad.Ratio(4, 6).is_dyadic()
False

>>> abjad.Ratio(2, 3).is_dyadic()
False

>>> abjad.Ratio(2, 2).is_dyadic()
True

>>> abjad.Ratio(1, 1).is_dyadic()
True

is_normalized() → bool[source]

Is true when fraction form of ratio is greater than 1/2 and less than 2.

>>> abjad.Ratio(6, 4).is_normalized()
True

>>> abjad.Ratio(3, 2).is_normalized()
True

>>> abjad.Ratio(4, 6).is_normalized()
True

>>> abjad.Ratio(2, 3).is_normalized()
True

>>> abjad.Ratio(2, 2).is_normalized()
True

>>> abjad.Ratio(1, 1).is_normalized()
True

>>> abjad.Ratio(10, 4).is_normalized()
False

>>> abjad.Ratio(4, 10).is_normalized()
False

>>> abjad.Ratio(9, 4).is_normalized()
False

>>> abjad.Ratio(4, 9).is_normalized()
False

is_reduced() → bool[source]

Is true when ratio numerator and denominator are relatively prime.

>>> abjad.Ratio(6, 4).is_reduced()
False

>>> abjad.Ratio(3, 2).is_reduced()
True

>>> abjad.Ratio(4, 6).is_reduced()
False

>>> abjad.Ratio(2, 3).is_reduced()
True

>>> abjad.Ratio(2, 2).is_reduced()
False

>>> abjad.Ratio(1, 1).is_reduced()
True

is_trivial() → bool[source]

Is true when ratio numerator equals ratio denominator.

>>> abjad.Ratio(6, 4).is_trivial()
False

>>> abjad.Ratio(3, 2).is_trivial()
False

>>> abjad.Ratio(4, 6).is_trivial()
False

>>> abjad.Ratio(2, 3).is_trivial()
False

>>> abjad.Ratio(2, 2).is_trivial()
True

>>> abjad.Ratio(1, 1).is_trivial()
True

reciprocal() → Ratio[source]

Get reciprocal of ratio.

>>> abjad.Ratio(6, 4).reciprocal()
Ratio(numerator=4, denominator=6)