# Multiplier¶

class `durationtools.``Multiplier`

Multiplier.

Example 1. Initializes from integer numerator:

```>>> Multiplier(3)
Multiplier(3, 1)
```

Example 2. Initializes from integer numerator and denominator:

```>>> Multiplier(3, 16)
Multiplier(3, 16)
```

Example 3. Initializes from integer-equivalent numeric numerator:

```>>> Multiplier(3.0)
Multiplier(3, 1)
```

Example 4. Initializes from integer-equivalent numeric numerator and denominator:

```>>> Multiplier(3.0, 16)
Multiplier(3, 16)
```

Example 5. Initializes from integer-equivalent singleton:

```>>> Multiplier((3,))
Multiplier(3, 1)
```

Example 6. Initializes from integer-equivalent pair:

```>>> Multiplier((3, 16))
Multiplier(3, 16)
```

Example 7. Initializes from other duration:

```>>> Multiplier(Duration(3, 16))
Multiplier(3, 16)
```

Example 8. Intializes from fraction:

```>>> Multiplier(Fraction(3, 16))
Multiplier(3, 16)
```

Example 9. Initializes from solidus string:

```>>> Multiplier('3/16')
Multiplier(3, 16)
```

Example 10. Initializes from nonreduced fraction:

```>>> Multiplier(mathtools.NonreducedFraction(6, 32))
Multiplier(3, 16)
```

Example 11. Multipliers inherit from built-in fraction:

```>>> isinstance(Multiplier(3, 16), Fraction)
True
```

Example 12. Multipliers are numeric:

```>>> import numbers
```
```>>> isinstance(Multiplier(3, 16), numbers.Number)
True
```

Example 13. Attaching a multiplier to a score component multiplies that component’s duration:

```>>> note = Note("c'1")
>>> print(format(note))
c'1
```
```>>> multiplier = Multiplier(3, 8)
>>> attach(multiplier, note)
>>> print(format(note))
c'1 * 3/8
```

## Attribute summary¶

 `conjugate`() Conjugate is a no-op for Reals. `denominator` `dot_count` Gets dot count. `durations_to_nonreduced_fractions`(durations) Changes durations to nonreduced fractions 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. `flag_count` Gets flag count. `from_decimal`(dec) Converts a finite Decimal instance to a rational number, exactly. `from_float`(f) Converts a finite float to a rational number, exactly. `from_lilypond_duration_string`(...) Initializes duration from LilyPond duration string. `has_power_of_two_denominator` Is true when duration is an integer power of two. `imag` Real numbers have no imaginary component. `implied_prolation` Gets implied prolation. `is_assignable` Is true when duration is assignable. `is_proper_tuplet_multiplier` Is true when mutliplier is greater than `1/2` and less than `2`. `is_token`(expr) Is true when expr correctly initializes a duration. `lilypond_duration_string` Gets LilyPond duration string. `limit_denominator`([max_denominator]) Closest Fraction to self with denominator at most max_denominator. `numerator` `pair` Gets numerator and denominator. `prolation_string` Gets prolation string. `real` Real numbers are their real component. `reciprocal` Gets reciprocal. `to_clock_string`() Changes duration to clock string. `to_score_markup`() Changes duration to score markup. `with_denominator`(denominator) Changes duration to nonreduced fraction with denominator. `yield_durations`([unique]) Yields all positive durations. `yield_equivalent_durations`([...]) Yields all durations equivalent to this duration. `__abs__`(\*args) Gets absolute value of duration. `__add__`(\*args) Adds duration to args. `__bool__`(a) a != 0 `__ceil__`(a) Will be math.ceil(a) in 3.0. `__complex__`() complex(self) == complex(float(self), 0) `__copy__`() `__deepcopy__`(memo) `__div__`(\*args) Divides duration by args. `__divmod__`(\*args) Equals the pair (duration // args, duration % args). `__eq__`(arg) Is true when duration equals arg. `__float__`() float(self) = self.numerator / self.denominator `__floor__`(a) Will be math.floor(a) in 3.0. `__floordiv__`(a, b) a // b `__format__`([format_specification]) Formats duration. `__ge__`(arg) Is true when duration is greater than or equal to arg. `__gt__`(arg) Is true when duration is greater than arg. `__hash__`() Hashes duration. `__le__`(arg) Is true when duration is less than or equal to arg. `__lt__`(arg) Is true when duration is less than arg. `__mod__`(\*args) Modulus operator applied to duration. `__mul__`(\*args) Multiplier times duration gives duration. `__ne__`(arg) Is true when duration does not equal arg. `__neg__`(\*args) Negates duration. `__new__`(class_, \*args) `__pos__`(\*args) Get positive duration. `__pow__`(\*args) Raises duration to args power. `__radd__`(\*args) Adds args to duration. `__rdiv__`(\*args) Divides args by duration. `__rdivmod__`(\*args) Documentation required. `__repr__`() Gets interpreter representation of Abjad object. `__rfloordiv__`(b, a) a // b `__rmod__`(\*args) Documentation required. `__rmul__`(\*args) Multiplies args by duration. `__round__`([ndigits]) Will be round(self, ndigits) in 3.0. `__rpow__`(\*args) Raises args to the power of duration. `__rsub__`(\*args) Subtracts duration from args. `__rtruediv__`(\*args) Documentation required. `__str__`() str(self) `__sub__`(\*args) Subtracts args from duration. `__truediv__`(\*args) Documentation required. `__trunc__`(a) trunc(a)

`(Fraction).``denominator`
`(Duration).``dot_count`

Gets dot count.

Example. Gets dot count:

```>>> for n in range(1, 16 + 1):
...     try:
...         duration = Duration(n, 16)
...         sixteenths = duration.with_denominator(16)
...         dot_count = duration.dot_count
...         string = '{!s}\t{}'
...         string = string.format(sixteenths, dot_count)
...         print(string)
...     except AssignabilityError:
...         sixteenths = duration.with_denominator(16)
...         string = '{!s}\t{}'
...         string = string.format(sixteenths, '--')
...         print(string)
...
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.

Returns positive integer.

`(Duration).``equal_or_greater_assignable`

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

Example. Gets equal-or-greater assignable duration:

```>>> for numerator in range(1, 16 + 1):
...     duration = Duration(numerator, 16)
...     result = duration.equal_or_greater_assignable
...     sixteenths = duration.with_denominator(16)
...     print('{!s}\t{!s}'.format(sixteenths, result))
...
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
```

Returns new duration.

`(Duration).``equal_or_greater_power_of_two`

Gets duration equal or just greater power of two.

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

```>>> for numerator in range(1, 16 + 1):
...     duration = Duration(numerator, 16)
...     result = duration.equal_or_greater_power_of_two
...     sixteenths = duration.with_denominator(16)
...     print('{!s}\t{!s}'.format(sixteenths, result))
...
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
```

Returns new duration.

`(Duration).``equal_or_lesser_assignable`

Gets assignable duration equal or just less than this duration.

Example. Gets equal-or-lesser assignable duration:

```>>> for numerator in range(1, 16 + 1):
...     duration = Duration(numerator, 16)
...     result = duration.equal_or_lesser_assignable
...     sixteenths = duration.with_denominator(16)
...     print('{!s}\t{!s}'.format(sixteenths, result))
...
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
```

Returns new duration.

`(Duration).``equal_or_lesser_power_of_two`

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

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

```>>> for numerator in range(1, 16 + 1):
...     duration = Duration(numerator, 16)
...     result = duration.equal_or_lesser_power_of_two
...     sixteenths = duration.with_denominator(16)
...     print('{!s}\t{!s}'.format(sixteenths, result))
...
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
```

Returns new duration.

`(Duration).``flag_count`

Gets flag count.

Example. Gets flag count:

```>>> for n in range(1, 16 + 1):
...     duration = Duration(n, 64)
...     sixty_fourths = duration.with_denominator(64)
...     print('{!s}\t{}'.format(sixty_fourths, 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.

Returns nonnegative integer.

`(Duration).``has_power_of_two_denominator`

Is true when duration is an integer power of two. Otherwise false.

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

```>>> for n in range(1, 16 + 1):
...     duration = Duration(1, n)
...     result = duration.has_power_of_two_denominator
...     print('{!s}\t{}'.format(duration, 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
```

Returns true or false.

`(Real).``imag`

Real numbers have no imaginary component.

`(Duration).``implied_prolation`

Gets implied prolation.

Example. Gets implied prolation:

```>>> for denominator in range(1, 16 + 1):
...     duration = Duration(1, denominator)
...     result = duration.implied_prolation
...     print('{!s}\t{!s}'.format(duration, result))
...
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
```

Returns multipler.

`(Duration).``is_assignable`

Is true when duration is assignable. Otherwise false.

Example. Is true when duration is assignable:

```>>> for numerator in range(0, 16 + 1):
...     duration = Duration(numerator, 16)
...     sixteenths = duration.with_denominator(16)
...     print('{!s}\t{}'.format(sixteenths, 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
```

Returns true or false.

`Multiplier.``is_proper_tuplet_multiplier`

Is true when mutliplier is greater than `1/2` and less than `2`. Otherwise false:

```>>> Multiplier(3, 2).is_proper_tuplet_multiplier
True
```

Returns true or false.

`(Duration).``lilypond_duration_string`

Gets LilyPond duration string.

Example. Gets LilyPond duration string:

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

Raises assignability error when duration is not assignable.

Returns string.

`(Fraction).``numerator`
`(Duration).``pair`

Gets numerator and denominator.

Example. Gets pair:

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

Returns integer pair.

`(Duration).``prolation_string`

Gets prolation string.

Example. Gets prolation string:

```>>> generator = Duration.yield_durations(unique=True)
>>> for n in range(16):
...     duration = next(generator)
...     string = '{!s}\t{}'
...     string = string.format(duration, duration.prolation_string)
...     print(string)
...
1	1:1
2	1:2
1/2	2:1
1/3	3:1
3	1:3
4	1:4
3/2	2:3
2/3	3:2
1/4	4:1
1/5	5:1
5	1:5
6	1:6
5/2	2:5
4/3	3:4
3/4	4:3
2/5	5:2
```

Returns string.

`(Real).``real`

Real numbers are their real component.

`(Duration).``reciprocal`

Gets reciprocal.

Example. Gets reciprocal:

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

Returns new duration.

## Methods¶

`(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).``to_clock_string`()

Changes duration to clock string.

Example. Changes duration to clock string:

```>>> note = Note("c'4")
>>> duration = Duration(117)
>>> clock_string = duration.to_clock_string()
>>> clock_string
"1'57''"
```
```>>> string = '"{}"'.format(clock_string)
>>> markup = markuptools.Markup(string, direction=Up)
>>> attach(markup, note)
>>> show(note)
```

Rounds down to nearest second.

Returns string.

`(Duration).``to_score_markup`()

Changes duration to score markup.

Example 1. Changes assignable duration to score markup:

```>>> markup = Duration(3, 16).to_score_markup()
>>> show(markup)
```

Example 2. Changes nonassignable duration to score markup:

```>>> markup = Duration(5, 16).to_score_markup()
>>> show(markup)
```

Example 3. Override tuplet number text like this:

```>>> tuplet = Tuplet((5, 7), "c'16 c' c' c' c' c' c'")
>>> attach(Beam(), tuplet[:])
>>> staff = Staff([tuplet], context_name='RhythmicStaff')
>>> duration = inspect_(tuplet).get_duration()
>>> markup = duration.to_score_markup()
>>> markup = markup.scale((0.75, 0.75))
>>> override(tuplet).tuplet_number.text = markup
>>> show(staff)
```

Returns markup.

`(Duration).``with_denominator`(denominator)

Changes duration to nonreduced fraction with denominator.

Example. Changes duration to nonreduced fraction:

```>>> duration = Duration(1, 4)
>>> for denominator in (4, 8, 16, 32):
...     print(duration.with_denominator(denominator))
...
1/4
2/8
4/16
8/32
```

Returns new duration.

`(Duration).``yield_equivalent_durations`(minimum_written_duration=None)

Yields all durations equivalent to this duration.

Returns output in Cantor diagonalized order.

Ensures written duration never less than minimum_written_duration.

Example 1. Yields durations equivalent to `1/8`:

```>>> pairs = Duration(1, 8).yield_equivalent_durations()
>>> for pair in pairs: pair
...
(Multiplier(1, 1), Duration(1, 8))
(Multiplier(2, 3), Duration(3, 16))
(Multiplier(4, 3), Duration(3, 32))
(Multiplier(4, 7), Duration(7, 32))
(Multiplier(8, 7), Duration(7, 64))
(Multiplier(8, 15), Duration(15, 64))
(Multiplier(16, 15), Duration(15, 128))
(Multiplier(16, 31), Duration(31, 128))
```

Example 2. Yields durations equivalent ot `1/12`:

```>>> pairs = Duration(1, 12).yield_equivalent_durations()
>>> for pair in pairs: pair
...
(Multiplier(2, 3), Duration(1, 8))
(Multiplier(4, 3), Duration(1, 16))
(Multiplier(8, 9), Duration(3, 32))
(Multiplier(16, 9), Duration(3, 64))
(Multiplier(16, 21), Duration(7, 64))
(Multiplier(32, 21), Duration(7, 128))
(Multiplier(32, 45), Duration(15, 128))
```

Yields durations equivalent to `5/48`:

```>>> pairs = Duration(5, 48).yield_equivalent_durations()
>>> for pair in pairs: pair
...
(Multiplier(5, 6), Duration(1, 8))
(Multiplier(5, 3), Duration(1, 16))
(Multiplier(5, 9), Duration(3, 16))
(Multiplier(10, 9), Duration(3, 32))
(Multiplier(20, 21), Duration(7, 64))
(Multiplier(40, 21), Duration(7, 128))
(Multiplier(8, 9), Duration(15, 128))
```

Defaults minimum_written_duration to `1/128`.

Returns generator.

## Class & static methods¶

`(Duration).``durations_to_nonreduced_fractions`(durations)

Changes durations to nonreduced fractions sharing least common denominator.

Example. Changes durations to nonreduced fractions:

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

Returns new object of durations type.

`(Fraction).``from_decimal`(dec)

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

`(Fraction).``from_float`(f)

Converts a finite float to a rational number, exactly.

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

`(Duration).``from_lilypond_duration_string`(lilypond_duration_string)

Initializes duration from LilyPond duration string.

Example. Initializes duration from LilyPond duration string:

```>>> Duration.from_lilypond_duration_string('8.')
Duration(3, 16)
```

Returns duration.

`(Duration).``is_token`(expr)

Is true when expr correctly initializes a duration. Otherwise false.

Example. Is true when expression is a duration token:

```>>> Duration.is_token('8.')
True
```

Returns true or false.

`(Duration).``yield_durations`(unique=False)

Yields all positive durations.

Example 1. Yields all positive durations in Cantor diagonalized order:

```>>> generator = Duration.yield_durations()
>>> for n in range(16):
...     next(generator)
...
Duration(1, 1)
Duration(2, 1)
Duration(1, 2)
Duration(1, 3)
Duration(1, 1)
Duration(3, 1)
Duration(4, 1)
Duration(3, 2)
Duration(2, 3)
Duration(1, 4)
Duration(1, 5)
Duration(1, 2)
Duration(1, 1)
Duration(2, 1)
Duration(5, 1)
Duration(6, 1)
```

Example 2. Yields all positive durations in Cantor diagonalized order uniquely:

```>>> generator = Duration.yield_durations(unique=True)
>>> for n in range(16):
...     next(generator)
...
Duration(1, 1)
Duration(2, 1)
Duration(1, 2)
Duration(1, 3)
Duration(3, 1)
Duration(4, 1)
Duration(3, 2)
Duration(2, 3)
Duration(1, 4)
Duration(1, 5)
Duration(5, 1)
Duration(6, 1)
Duration(5, 2)
Duration(4, 3)
Duration(3, 4)
Duration(2, 5)
```

Returns generator.

## Special methods¶

`(Duration).``__abs__`(*args)

Gets absolute value of duration.

Returns nonnegative duration.

`(Duration).``__add__`(*args)

Example 1. Returns duration when args is a duration:

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

Example 2. Returns nonreduced fraction when args is a nonreduced fraction:

```>>> duration = Duration(1, 2)
>>> nonreduced_fraction = mathtools.NonreducedFraction(3, 6)
>>> duration + nonreduced_fraction
NonreducedFraction(6, 6)
```

Returns duration.

`(Fraction).``__bool__`(a)

a != 0

`(Fraction).``__ceil__`(a)

Will be math.ceil(a) in 3.0.

`(Real).``__complex__`()

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

`(Fraction).``__copy__`()
`(Fraction).``__deepcopy__`(memo)
`(Duration).``__div__`(*args)

Divides duration by args.

Returns multiplier.

`(Duration).``__divmod__`(*args)

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

Returns pair.

`(Duration).``__eq__`(arg)

Is true when duration equals arg. Otherwise false.

Returns true or false.

`(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__`(a)

Will be math.floor(a) in 3.0.

`(Fraction).``__floordiv__`(a, b)

a // b

`(Duration).``__format__`(format_specification='')

Formats duration.

Set format_specification to ‘’ or ‘storage’. Interprets ‘’ equal to ‘storage’.

Returns string.

`(Duration).``__ge__`(arg)

Is true when duration is greater than or equal to arg. Otherwise false.

Returns true or false.

`(Duration).``__gt__`(arg)

Is true when duration is greater than arg. Otherwise false.

Returns true or false.

`(Duration).``__hash__`()

Hashes duration.

Required to be explicitly redefined on Python 3 if __eq__ changes.

Returns integer.

`(Duration).``__le__`(arg)

Is true when duration is less than or equal to arg. Otherwise false.

Returns true or false.

`(Duration).``__lt__`(arg)

Is true when duration is less than arg. Otherwise false.

Returns true or false.

`(Duration).``__mod__`(*args)

Modulus operator applied to duration.

Returns duration.

`Multiplier.``__mul__`(*args)

Multiplier times duration gives duration.

Returns duration.

`(Duration).``__ne__`(arg)

Is true when duration does not equal arg. Otherwise false.

Returns true or false.

`(Duration).``__neg__`(*args)

Negates duration.

Returns new duration.

`(Duration).``__new__`(class_, *args)
`(Duration).``__pos__`(*args)

Get positive duration.

Returns new duration.

`(Duration).``__pow__`(*args)

Raises duration to args power.

Returns new duration.

`(Duration).``__radd__`(*args)

Returns new duration.

`(Duration).``__rdiv__`(*args)

Divides args by duration.

Returns new duration.

`(Duration).``__rdivmod__`(*args)

Documentation required.

`(AbjadObject).``__repr__`()

Gets interpreter representation of Abjad object.

Returns string.

`(Fraction).``__rfloordiv__`(b, a)

a // b

`(Duration).``__rmod__`(*args)

Documentation required.

`(Duration).``__rmul__`(*args)

Multiplies args by duration.

Returns new duration.

`(Fraction).``__round__`(ndigits=None)

Will be round(self, ndigits) in 3.0.

Rounds half toward even.

`(Duration).``__rpow__`(*args)

Raises args to the power of duration.

Returns new duration.

`(Duration).``__rsub__`(*args)

Subtracts duration from args.

Returns new duration.

`(Duration).``__rtruediv__`(*args)

Documentation required.

Returns new duration.

`(Fraction).``__str__`()

str(self)

`(Duration).``__sub__`(*args)

Subtracts args from duration.

Returns new duration.

`(Duration).``__truediv__`(*args)

Documentation required.

`(Fraction).``__trunc__`(a)

trunc(a)