duration

---

Classes

Duration	Duration.
Offset	Offset.

class abjad.duration.Duration(*arguments)

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

---

Attributes Summary

__abs__	Gets absolute value of duration.
__add__	Adds duration to arguments.
__div__	Divides duration by arguments.
__divmod__	Equals the pair (duration // arguments, duration % arguments).
__eq__	Is true when duration equals argument.
__ge__	Is true when duration is greater than or equal to argument.
__gt__	Is true when duration is greater than argument.
__hash__	Hashes duration.
__le__	Is true when duration is less than or equal to argument.
__lt__	Is true when duration is less than argument.
__mod__	Modulus operator applied to duration.
__mul__	Duration multiplied by argument.
__ne__	Redefined explicitly because abjad.Duration inherits from built-in fractions.Fraction:
__neg__	Negates duration.
__new__	Makes new duration.
__pos__	Get positive duration.
__pow__	Raises duration to arguments power.
__radd__	Adds arguments to duration.
__rdiv__	Divides arguments by duration.
__rdivmod__	Documentation required.
__repr__	Gets repr.
__rmod__	Documentation required.
__rmul__	Multiplies arguments by duration.
__rpow__	Raises arguments to the power of duration.
__rsub__	Subtracts duration from arguments.
__rtruediv__	Documentation required.
__sub__	Subtracts arguments from duration.
__truediv__	Documentation required.
dot_count	Gets dot count.
durations_to_nonreduced_fractions	Changes durations to pairs sharing least common denominator.
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.
from_clock_string	Initializes duration (in seconds) from clock string.
from_dot_count	Makes duration from dot_count.
from_lilypond_duration_string	Initializes duration from LilyPond duration string.
implied_prolation	Gets implied prolation.
is_assignable	Is true when duration is assignable.
is_dyadic_rational	Is true when duration is an integer power of two.
is_token	Is true when argument correctly initializes a duration.
lilypond_duration_string	Gets LilyPond duration string.
normalized	Is true when duration is greater than 1/2 and less than 2.
pair	Gets numerator and denominator.
prolation_string	Gets prolation string.
reciprocal	Gets reciprocal.
to_clock_string	Changes duration to clock string.

---

Special methods

overridden __abs__(*arguments)

Gets absolute value of duration.

Returns nonnegative duration.

overridden __add__(*arguments)

Adds duration to arguments.

Returns duration when arguments is a duration:

>>> duration_1 = abjad.Duration(1, 2)
>>> duration_2 = abjad.Duration(3, 2)
>>> duration_1 + duration_2
Duration(2, 1)

Returns duration.

(Fraction).__bool__()

a != 0

(Fraction).__ceil__()

math.ceil(a)

(Real).__complex__()

complex(self) == complex(float(self), 0)

(Fraction).__copy__()

(Fraction).__deepcopy__(memo)

__div__(*arguments)

Divides duration by arguments.

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

Return type:

Fraction

overridden __divmod__(*arguments)

Equals the pair (duration // arguments, duration % arguments).

Returns pair.

overridden __eq__(argument)

Is true when duration equals argument.

Return type:

bool

(Rational).__float__()

float(self) = self.numerator / self.denominator

It’s important that this conversion use the integer’s “true” division rather than casting one side to float before dividing so that ratios of huge integers convert without overflowing.

(Fraction).__floor__()

math.floor(a)

(Fraction).__floordiv__(b)

a // b

overridden __ge__(argument)

Is true when duration is greater than or equal to argument.

Return type:

bool

overridden __gt__(argument)

Is true when duration is greater than argument.

Return type:

bool

overridden __hash__()

Hashes duration.

Return type:

int

(Fraction).__int__(_index=<built-in function index>)

int(a)

overridden __le__(argument)

Is true when duration is less than or equal to argument.

Return type:

bool

overridden __lt__(argument)

Is true when duration is less than argument.

Return type:

bool

overridden __mod__(*arguments)

Modulus operator applied to duration.

Returns duration.

overridden __mul__(argument)

Duration multiplied by argument.

Returns a new duration when argument is a duration:

>>> duration_1 = abjad.Duration(1, 2)
>>> duration_2 = abjad.Duration(3, 2)
>>> duration_1 * duration_2
Duration(3, 4)

Returns duration.

overridden __ne__(argument)

Redefined explicitly because abjad.Duration inherits from built-in fractions.Fraction:

“The __ne__ method follows automatically from __eq__ only if __ne__ isn’t already defined in a superclass. So, if you’re inheriting from a builtin, it’s best to override both.”

See https://bugs.python.org/issue4395#msg89533.

REGRESSION:

>>> offset_1 = abjad.Offset(1)
>>> offset_2 = abjad.Offset(1, displacement=(-1, 16))

>>> offset_1 == offset_2
False

>>> offset_1 != offset_2
True

Return type:

bool

overridden __neg__(*arguments)

Negates duration.

Returns new duration.

overridden static __new__(class_, *arguments)

Makes new duration.

overridden __pos__(*arguments)

Get positive duration.

Returns new duration.

overridden __pow__(*arguments)

Raises duration to arguments power.

Returns new duration.

overridden __radd__(*arguments)

Adds arguments to duration.

Returns new duration.

__rdiv__(*arguments)

Divides arguments by duration.

Returns new duration.

overridden __rdivmod__(*arguments)

Documentation required.

overridden __repr__()

Gets repr.

Return type:

str

(Fraction).__rfloordiv__(a)

a // b

overridden __rmod__(*arguments)

Documentation required.

overridden __rmul__(*arguments)

Multiplies arguments by duration.

Returns new duration.

(Fraction).__round__(ndigits=None)

round(self, ndigits)

Rounds half toward even.

overridden __rpow__(*arguments)

Raises arguments to the power of duration.

Returns new duration.

overridden __rsub__(*arguments)

Subtracts duration from arguments.

Returns new duration.

overridden __rtruediv__(*arguments)

Documentation required.

Returns new duration.

(Fraction).__str__()

str(self)

overridden __sub__(*arguments)

Subtracts arguments from duration.

>>> abjad.Duration(1, 2) - abjad.Duration(2, 8)
Duration(1, 4)

Returns new duration.

overridden __truediv__(*arguments)

Documentation required.

(Fraction).__trunc__()

math.trunc(a)

---

Methods

(Fraction).as_integer_ratio()

Return the integer ratio as a tuple.

Return a tuple of two integers, whose ratio is equal to the Fraction and with a positive denominator.

(Real).conjugate()

Conjugate is a no-op for Reals.

(Fraction).limit_denominator(max_denominator=1000000)

Closest Fraction to self with denominator at most max_denominator.

>>> Fraction("3.141592653589793").limit_denominator(10)
Fraction(22, 7)

>>> Fraction("3.141592653589793").limit_denominator(100)
Fraction(311, 99)

>>> Fraction(4321, 8765).limit_denominator(10000)
Fraction(4321, 8765)

normalized()

Is true when duration is greater than 1/2 and less than 2.

>>> abjad.Duration(3, 2).normalized()
True

Return type:

bool

to_clock_string()

Changes duration to clock string.

Changes duration to clock string:

>>> 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)  

Rounds down to nearest second.

Return type:

str

---

Class & static methods

static durations_to_nonreduced_fractions(durations)

Changes durations to pairs sharing least common denominator.

>>> durations = [abjad.Duration(2, 4), 3, (5, 16)]
>>> result = abjad.Duration.durations_to_nonreduced_fractions(durations)
>>> for x in result:
...     x
... 
(8, 16)
(48, 16)
(5, 16)

Return type:

list[tuple[int, int]]

static from_clock_string(clock_string)

Initializes duration (in seconds) from clock string.

>>> abjad.Duration.from_clock_string("0'00''")
Duration(0, 1)

>>> abjad.Duration.from_clock_string("0'59''")
Duration(59, 1)

>>> abjad.Duration.from_clock_string("1'00''")
Duration(60, 1)

>>> abjad.Duration.from_clock_string("1'17''")
Duration(77, 1)

Return type:

Duration

classmethod (Fraction).from_decimal(dec)

Converts a finite Decimal instance to a rational number, exactly.

static from_dot_count(dot_count)

Makes duration from dot_count.

>>> abjad.Duration.from_dot_count(0)
Duration(1, 1)

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

>>> abjad.Duration.from_dot_count(2)
Duration(7, 4)

>>> abjad.Duration.from_dot_count(3)
Duration(15, 8)

>>> abjad.Duration.from_dot_count(4)
Duration(31, 16)

Return type:

Duration

classmethod (Fraction).from_float(f)

Converts a finite float to a rational number, exactly.

Beware that Fraction.from_float(0.3) != Fraction(3, 10).

static from_lilypond_duration_string(lilypond_duration_string)

Initializes duration from LilyPond duration string.

>>> abjad.Duration.from_lilypond_duration_string("8.")
Duration(3, 16)

Return type:

Duration

static is_token(argument)

Is true when argument correctly initializes a duration.

>>> abjad.Duration.is_token("8.")
True

Return type:

bool

---

Read-only properties

(Fraction).denominator

dot_count

Gets dot count.

Gets dot count:

>>> 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

Dot count defined equal to number of dots required to notate duration.

Raises assignability error when duration is not assignable.

equal_or_greater_assignable

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

Gets equal-or-greater assignable 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.

Gets equal-or-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.

Gets equal-or-lesser assignable 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.

Gets equal-or-lesser power-of-two:

>>> 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.

Gets equal-or-greater power-of-two:

>>> 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.

Gets flag count:

>>> 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

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

(Real).imag

Real numbers have no imaginary component.

implied_prolation

Gets implied prolation.

Gets implied prolation:

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

is_assignable

Is true when duration 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_rational

Is true when duration is an integer power of two.

Is true when duration has power-of-two denominator:

>>> for n in range(1, 16 + 1):
...     duration = abjad.Duration(1, n)
...     result = duration.is_dyadic_rational
...     print(f"{duration!s}\t{result}")
... 
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.

Gets LilyPond duration string:

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

Raises assignability error when duration is not assignable.

(Fraction).numerator

pair

Gets numerator and denominator.

Gets pair:

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

prolation_string

Gets prolation string.

Gets prolation string:

>>> abjad.Duration(3, 16).prolation_string
'16:3'

(Real).real

Real numbers are their real component.

reciprocal

Gets reciprocal.

Gets reciprocal:

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

class abjad.duration.Offset(*arguments, **keywords)

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

---

Attributes Summary

__copy__	Copies offset.
__deepcopy__	Deep copies offset.
__eq__	Is true when offset equals argument.
__ge__	Is true when offset is greater than or equal to argument.
__gt__	Is true when offset is greater than argument.
__hash__	Hashes offset.
__le__	Is true when offset is less than or equal to argument.
__lt__	Is true when offset is less than argument.
__new__	Makes new duration.
__repr__	Gets interpreter representation of offset.
__sub__	Subtracts argument from offset.
displacement	Gets displacement.

---

Special methods

(Duration).__abs__(*arguments)

Gets absolute value of duration.

Returns nonnegative duration.

(Duration).__add__(*arguments)

Adds duration to arguments.

Returns duration when arguments is a duration:

>>> duration_1 = abjad.Duration(1, 2)
>>> duration_2 = abjad.Duration(3, 2)
>>> duration_1 + duration_2
Duration(2, 1)

Returns duration.

(Fraction).__bool__()

a != 0

(Fraction).__ceil__()

math.ceil(a)

(Real).__complex__()

complex(self) == complex(float(self), 0)

overridden __copy__(*arguments)

Copies offset. :rtype: Offset

>>> import copy

Copies offset with displacement:

>>> offset_1 = abjad.Offset((1, 4), displacement=(-1, 16))
>>> offset_2 = copy.copy(offset_1)

>>> offset_1
Offset((1, 4), displacement=Duration(-1, 16))

>>> offset_2
Offset((1, 4), displacement=Duration(-1, 16))

>>> offset_1 == offset_2
True

>>> offset_1 is offset_2
False

overridden __deepcopy__(*arguments)

Deep copies offset. :rtype: Offset

>>> import copy

Copies offset with displacement:

>>> offset_1 = abjad.Offset((1, 4), displacement=(-1, 16))
>>> offset_2 = copy.deepcopy(offset_1)

>>> offset_1
Offset((1, 4), displacement=Duration(-1, 16))

>>> offset_2
Offset((1, 4), displacement=Duration(-1, 16))

>>> offset_1 == offset_2
True

>>> offset_1 is offset_2
False

(Duration).__div__(*arguments)

Divides duration by arguments.

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

Return type:

Fraction

(Duration).__divmod__(*arguments)

Equals the pair (duration // arguments, duration % arguments).

Returns pair.

overridden __eq__(argument)

Is true when offset equals argument.

With equal numerators, denominators and displacement:

>>> offset_1 = abjad.Offset((1, 4), displacement=(-1, 16))
>>> offset_2 = abjad.Offset((1, 4), displacement=(-1, 16))

>>> offset_1 == offset_1
True

>>> offset_1 == offset_2
True

>>> offset_2 == offset_1
True

>>> offset_2 == offset_2
True

With equal numerators and denominators but differing grace displacements:

>>> offset_1 = abjad.Offset((1, 4), displacement=(-1, 8))
>>> offset_2 = abjad.Offset((1, 4), displacement=(-1, 16))

>>> offset_1 == offset_1
True

>>> offset_1 == offset_2
False

>>> offset_2 == offset_1
False

>>> offset_2 == offset_2
True

With differing numerators and denominators. Ignores grace displacements:

>>> offset_1 = abjad.Offset((1, 4))
>>> offset_2 = abjad.Offset((1, 2), displacement=(-99))

>>> offset_1 == offset_1
True

>>> offset_1 == offset_2
False

>>> offset_2 == offset_1
False

>>> offset_2 == offset_2
True

Return type:

bool

(Rational).__float__()

float(self) = self.numerator / self.denominator

It’s important that this conversion use the integer’s “true” division rather than casting one side to float before dividing so that ratios of huge integers convert without overflowing.

(Fraction).__floor__()

math.floor(a)

(Fraction).__floordiv__(b)

a // b

overridden __ge__(argument)

Is true when offset is greater than or equal to argument.

With equal numerators, denominators and displacement:

>>> offset_1 = abjad.Offset((1, 4), displacement=(-1, 16))
>>> offset_2 = abjad.Offset((1, 4), displacement=(-1, 16))

>>> offset_1 >= offset_1
True

>>> offset_1 >= offset_2
True

>>> offset_2 >= offset_1
True

>>> offset_2 >= offset_2
True

With equal numerators and denominators but differing grace displacements:

>>> offset_1 = abjad.Offset((1, 4), displacement=(-1, 8))
>>> offset_2 = abjad.Offset((1, 4), displacement=(-1, 16))

>>> offset_1 >= offset_1
True

>>> offset_1 >= offset_2
False

>>> offset_2 >= offset_1
True

>>> offset_2 >= offset_2
True

With differing numerators and denominators. Ignores grace displacements:

>>> offset_1 = abjad.Offset((1, 4))
>>> offset_2 = abjad.Offset((1, 2), displacement=(-99))

>>> offset_1 >= offset_1
True

>>> offset_1 >= offset_2
False

>>> offset_2 >= offset_1
True

>>> offset_2 >= offset_2
True

Return type:

bool

overridden __gt__(argument)

Is true when offset is greater than argument.

With equal numerators, denominators and displacement:

>>> offset_1 = abjad.Offset((1, 4), displacement=(-1, 16))
>>> offset_2 = abjad.Offset((1, 4), displacement=(-1, 16))

>>> offset_1 > offset_1
False

>>> offset_1 > offset_2
False

>>> offset_2 > offset_1
False

>>> offset_2 > offset_2
False

With equal numerators and denominators but differing grace displacements:

>>> offset_1 = abjad.Offset((1, 4), displacement=(-1, 8))
>>> offset_2 = abjad.Offset((1, 4), displacement=(-1, 16))

>>> offset_1 > offset_1
False

>>> offset_1 > offset_2
False

>>> offset_2 > offset_1
True

>>> offset_2 > offset_2
False

With differing numerators and denominators. Ignores grace displacements:

>>> offset_1 = abjad.Offset((1, 4))
>>> offset_2 = abjad.Offset((1, 2), displacement=(-99))

>>> offset_1 > offset_1
False

>>> offset_1 > offset_2
False

>>> offset_2 > offset_1
True

>>> offset_2 > offset_2
False

Return type:

bool

overridden __hash__()

Hashes offset.

Return type:

int

(Fraction).__int__(_index=<built-in function index>)

int(a)

overridden __le__(argument)

Is true when offset is less than or equal to argument.

With equal numerators, denominators and displacement:

>>> offset_1 = abjad.Offset((1, 4), displacement=(-1, 16))
>>> offset_2 = abjad.Offset((1, 4), displacement=(-1, 16))

>>> offset_1 <= offset_1
True

>>> offset_1 <= offset_2
True

>>> offset_2 <= offset_1
True

>>> offset_2 <= offset_2
True

With equal numerators and denominators but differing grace displacements:

>>> offset_1 = abjad.Offset((1, 4), displacement=(-1, 8))
>>> offset_2 = abjad.Offset((1, 4), displacement=(-1, 16))

>>> offset_1 <= offset_1
True

>>> offset_1 <= offset_2
True

>>> offset_2 <= offset_1
False

>>> offset_2 <= offset_2
True

With differing numerators and denominators. Ignores grace displacements:

>>> offset_1 = abjad.Offset((1, 4))
>>> offset_2 = abjad.Offset((1, 2), displacement=(-99))

>>> offset_1 <= offset_1
True

>>> offset_1 <= offset_2
True

>>> offset_2 <= offset_1
False

>>> offset_2 <= offset_2
True

Return type:

bool

overridden __lt__(argument)

Is true when offset is less than argument.

With equal numerators, denominators and displacement:

>>> offset_1 = abjad.Offset((1, 4), displacement=(-1, 16))
>>> offset_2 = abjad.Offset((1, 4), displacement=(-1, 16))

>>> offset_1 < offset_1
False

>>> offset_1 < offset_2
False

>>> offset_2 < offset_1
False

>>> offset_2 < offset_2
False

With equal numerators and denominators but differing nonzero grace displacements:

>>> offset_1 = abjad.Offset((1, 4), displacement=(-1, 8))
>>> offset_2 = abjad.Offset((1, 4), displacement=(-1, 16))

>>> offset_1 < offset_1
False

>>> offset_1 < offset_2
True

>>> offset_2 < offset_1
False

>>> offset_2 < offset_2
False

With equal numerators and denominators but differing zero-valued displacement:

>>> offset_1 = abjad.Offset((1, 4), displacement=(-1, 8))
>>> offset_2 = abjad.Offset((1, 4))

>>> offset_1 < offset_1
False

>>> offset_1 < offset_2
True

>>> offset_2 < offset_1
False

>>> offset_2 < offset_2
False

With differing numerators and denominators. Ignores grace displacements:

>>> offset_1 = abjad.Offset((1, 4))
>>> offset_2 = abjad.Offset((1, 2), displacement=(-99))

>>> offset_1 < offset_1
False

>>> offset_1 < offset_2
True

>>> offset_2 < offset_1
False

>>> offset_2 < offset_2
False

Return type:

bool

(Duration).__mod__(*arguments)

Modulus operator applied to duration.

Returns duration.

(Duration).__mul__(argument)

Duration multiplied by argument.

Returns a new duration when argument is a duration:

>>> duration_1 = abjad.Duration(1, 2)
>>> duration_2 = abjad.Duration(3, 2)
>>> duration_1 * duration_2
Duration(3, 4)

Returns duration.

(Duration).__ne__(argument)

Redefined explicitly because abjad.Duration inherits from built-in fractions.Fraction:

“The __ne__ method follows automatically from __eq__ only if __ne__ isn’t already defined in a superclass. So, if you’re inheriting from a builtin, it’s best to override both.”

See https://bugs.python.org/issue4395#msg89533.

REGRESSION:

>>> offset_1 = abjad.Offset(1)
>>> offset_2 = abjad.Offset(1, displacement=(-1, 16))

>>> offset_1 == offset_2
False

>>> offset_1 != offset_2
True

Return type:

bool

(Duration).__neg__(*arguments)

Negates duration.

Returns new duration.

overridden static __new__(class_, *arguments, **keywords)

Makes new duration.

(Duration).__pos__(*arguments)

Get positive duration.

Returns new duration.

(Duration).__pow__(*arguments)

Raises duration to arguments power.

Returns new duration.

(Duration).__radd__(*arguments)

Adds arguments to duration.

Returns new duration.

(Duration).__rdiv__(*arguments)

Divides arguments by duration.

Returns new duration.

(Duration).__rdivmod__(*arguments)

Documentation required.

overridden __repr__()

Gets interpreter representation of offset.

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

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

Return type:

str

(Fraction).__rfloordiv__(a)

a // b

(Duration).__rmod__(*arguments)

Documentation required.

(Duration).__rmul__(*arguments)

Multiplies arguments by duration.

Returns new duration.

(Fraction).__round__(ndigits=None)

round(self, ndigits)

Rounds half toward even.

(Duration).__rpow__(*arguments)

Raises arguments to the power of duration.

Returns new duration.

(Duration).__rsub__(*arguments)

Subtracts duration from arguments.

Returns new duration.

(Duration).__rtruediv__(*arguments)

Documentation required.

Returns new duration.

(Fraction).__str__()

str(self)

overridden __sub__(argument)

Subtracts argument from offset.

Offset taken from offset returns duration:

>>> abjad.Offset(2) - abjad.Offset(1, 2)
Duration(3, 2)

Duration taken from offset returns another offset:

>>> abjad.Offset(2) - abjad.Duration(1, 2)
Offset((3, 2))

Coerces argument to offset when argument is neither offset nor duration:

>>> import fractions
>>> abjad.Offset(2) - fractions.Fraction(1, 2)
Duration(3, 2)

(Duration).__truediv__(*arguments)

Documentation required.

(Fraction).__trunc__()

math.trunc(a)

---

Methods

(Fraction).as_integer_ratio()

Return the integer ratio as a tuple.

Return a tuple of two integers, whose ratio is equal to the Fraction and with a positive denominator.

(Real).conjugate()

Conjugate is a no-op for Reals.

(Fraction).limit_denominator(max_denominator=1000000)

Closest Fraction to self with denominator at most max_denominator.

>>> Fraction("3.141592653589793").limit_denominator(10)
Fraction(22, 7)

>>> Fraction("3.141592653589793").limit_denominator(100)
Fraction(311, 99)

>>> Fraction(4321, 8765).limit_denominator(10000)
Fraction(4321, 8765)

(Duration).normalized()

Is true when duration is greater than 1/2 and less than 2.

>>> abjad.Duration(3, 2).normalized()
True

Return type:

bool

(Duration).to_clock_string()

Changes duration to clock string.

Changes duration to clock string:

>>> 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)  

Rounds down to nearest second.

Return type:

str

---

Class & static methods

static (Duration).durations_to_nonreduced_fractions(durations)

Changes durations to pairs sharing least common denominator.

>>> durations = [abjad.Duration(2, 4), 3, (5, 16)]
>>> result = abjad.Duration.durations_to_nonreduced_fractions(durations)
>>> for x in result:
...     x
... 
(8, 16)
(48, 16)
(5, 16)

Return type:

list[tuple[int, int]]

static (Duration).from_clock_string(clock_string)

Initializes duration (in seconds) from clock string.

>>> abjad.Duration.from_clock_string("0'00''")
Duration(0, 1)

>>> abjad.Duration.from_clock_string("0'59''")
Duration(59, 1)

>>> abjad.Duration.from_clock_string("1'00''")
Duration(60, 1)

>>> abjad.Duration.from_clock_string("1'17''")
Duration(77, 1)

Return type:

Duration

classmethod (Fraction).from_decimal(dec)

Converts a finite Decimal instance to a rational number, exactly.

static (Duration).from_dot_count(dot_count)

Makes duration from dot_count.

>>> abjad.Duration.from_dot_count(0)
Duration(1, 1)

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

>>> abjad.Duration.from_dot_count(2)
Duration(7, 4)

>>> abjad.Duration.from_dot_count(3)
Duration(15, 8)

>>> abjad.Duration.from_dot_count(4)
Duration(31, 16)

Return type:

Duration

classmethod (Fraction).from_float(f)

Converts a finite float to a rational number, exactly.

Beware that Fraction.from_float(0.3) != Fraction(3, 10).

static (Duration).from_lilypond_duration_string(lilypond_duration_string)

Initializes duration from LilyPond duration string.

>>> abjad.Duration.from_lilypond_duration_string("8.")
Duration(3, 16)

Return type:

Duration

static (Duration).is_token(argument)

Is true when argument correctly initializes a duration.

>>> abjad.Duration.is_token("8.")
True

Return type:

bool

---

Read-only properties

(Fraction).denominator

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))

(Duration).dot_count

Gets dot count.

Gets dot count:

>>> 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

Dot count defined equal to number of dots required to notate duration.

Raises assignability error when duration is not assignable.

(Duration).equal_or_greater_assignable

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

Gets equal-or-greater assignable 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

(Duration).equal_or_greater_power_of_two

Gets duration equal or just greater power of two.

Gets equal-or-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

(Duration).equal_or_lesser_assignable

Gets assignable duration equal or just less than this duration.

Gets equal-or-lesser assignable 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

(Duration).equal_or_lesser_power_of_two

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

Gets equal-or-lesser power-of-two:

>>> 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

(Duration).exponent

Gets base-2 exponent.

Gets equal-or-greater power-of-two:

>>> 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

(Duration).flag_count

Gets flag count.

Gets flag count:

>>> 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

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

(Real).imag

Real numbers have no imaginary component.

(Duration).implied_prolation

Gets implied prolation.

Gets implied prolation:

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

(Duration).is_assignable

Is true when duration 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

(Duration).is_dyadic_rational

Is true when duration is an integer power of two.

Is true when duration has power-of-two denominator:

>>> for n in range(1, 16 + 1):
...     duration = abjad.Duration(1, n)
...     result = duration.is_dyadic_rational
...     print(f"{duration!s}\t{result}")
... 
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

(Duration).lilypond_duration_string

Gets LilyPond duration string.

Gets LilyPond duration string:

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

Raises assignability error when duration is not assignable.

(Fraction).numerator

(Duration).pair

Gets numerator and denominator.

Gets pair:

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

(Duration).prolation_string

Gets prolation string.

Gets prolation string:

>>> abjad.Duration(3, 16).prolation_string
'16:3'

(Real).real

Real numbers are their real component.

(Duration).reciprocal

Gets reciprocal.

Gets reciprocal:

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

---

Functions

add_pairs
divide_pair	Divides pair by integer n.
durations	Changes durations to durations.
pair	Changes argument to pair.
with_denominator	Spells duration as pair with denominator.

abjad.duration.add_pairs(pair_1, pair_2)

abjad.duration.divide_pair(pair, n)

Divides pair by integer n.

Return type:

tuple[int, int]

abjad.duration.durations(durations)

Changes durations to durations.

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

Return type:

list[Duration]

abjad.duration.pair(argument)

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)

Return type:

tuple[int, int]

abjad.duration.with_denominator(duration, denominator)

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)

Return type:

tuple[int, int]