abjad.math

abjad.math.all_are_equal(argument)	Is true when argument is an iterable collection of equal items.
abjad.math.all_are_integer_equivalent(argument)	Is true when argument is an iterable collection with integer-equivalent items.
abjad.math.all_are_integer_equivalent_numbers(...)	Is true when argument is an iterable collection with integer-equivalent items.
abjad.math.all_are_nonnegative_integer_equivalent_numbers(...)	Is true when argument is an iterable collection of nonnegative integer-equivalent numbers.
abjad.math.all_are_nonnegative_integer_powers_of_two(...)	Is true when argument is an iterable collection of nonnegative integer powers of two.
abjad.math.all_are_nonnegative_integers(argument)	Is true when argument is an iterable collection of nonnegative integers.
abjad.math.all_are_pairs_of_types(argument, ...)	Is true when argument is an iterable collection whose members are all of length 2, and where the first member of each pair is an instance of first_type and where the second member of each pair is an instance of second_type.
abjad.math.all_are_positive_integers(argument)	Is true when argument is an iterable collection of positive integers.
abjad.math.are_relatively_prime(argument)	Is true when argument is an iterable collection of relative primes.
abjad.math.arithmetic_mean(argument)	Gets arithmetic mean of argument.
abjad.math.binomial_coefficient(n, k)	Gets binomial coefficient of n choose k.
abjad.math.clock_string(fraction)	Changes fraction to clock string.
abjad.math.cumulative_products(argument)	Gets cumulative products of argument.
abjad.math.cumulative_sums(argument[, start])	Gets cumulative sums of argument.
abjad.math.difference_series(argument)	Gets difference series of argument.
abjad.math.divide_integer_by_proportion(n, ...)	Divides integer n by tuple proportion.
abjad.math.divisors(n)	Gets positive divisors of n in increasing order.
abjad.math.equal_or_greater_power_of_two(n)	Gets fraction equal or just greater power of two from n.
abjad.math.factors(n)	Gets prime factors less than or equal to positive integer n .
abjad.math.fraction_to_proper_fraction(rational)	Changes rational to proper fraction.
abjad.math.greatest_common_divisor(*integers)	Calculates greatest common divisor of integers.
abjad.math.greatest_power_of_two_less_equal(n)	Gets greatest integer power of two less than or equal to positive n.
abjad.math.integer_equivalent_number_to_integer(number)	Changes integer-equivalent number to integer.
abjad.math.integer_to_base_k_tuple(n, k)	Changes nonnegative integer n to base-k tuple.
abjad.math.integer_to_binary_string(n)	Changes positive integer n to binary string.
abjad.math.is_assignable_integer(argument)	Is true when argument is equivalent to an integer that can be written without recourse to ties.
abjad.math.is_integer_equivalent(argument)	Is true when argument is an integer-equivalent number.
abjad.math.is_integer_equivalent_n_tuple(...)	Is true when argument is a tuple of n integer-equivalent items.
abjad.math.is_integer_equivalent_number(argument)	Is true when argument is a number and argument is equivalent to an integer.
abjad.math.is_nonnegative_integer(argument)	Is true when argument equals a nonnegative integer.
abjad.math.is_nonnegative_integer_equivalent_number(...)	Is true when argument is a nonnegative integer-equivalent number.
abjad.math.is_nonnegative_integer_power_of_two(...)	Is true when argument is a nonnegative integer power of 2.
abjad.math.is_positive_integer(argument)	Is true when argument equals a positive integer.
abjad.math.is_positive_integer_equivalent_number(...)	Is true when argument is a positive integer-equivalent number.
abjad.math.is_positive_integer_power_of_two(...)	Is true when argument is a positive integer power of 2.
abjad.math.least_common_multiple(*integers)	Gets least common multiple of positive integers.
abjad.math.partition_integer_by_proportion(n, ...)	Partitions positive integer-equivalent n by proportion.
abjad.math.partition_integer_into_canonic_parts(n)	Partitions integer n into canonic parts.
abjad.math.sign(n)	Gets sign of n.
abjad.math.weight(sequence, *, start)	Gets weight of sequence.
abjad.math.yield_all_compositions_of_integer(n)	Yields all compositions of positive integer n.
abjad.math.Infinity()	Infinity.
abjad.math.NegativeInfinity()	Negative infinity.

abjad.math.all_are_equal(argument) → bool

Is true when argument is an iterable collection of equal items.

>>> abjad.math.all_are_equal([99, 99, 99, 99, 99, 99])
True

>>> abjad.math.all_are_equal(17)
False

Is true when argument is empty:

>>> abjad.math.all_are_equal([])
True

abjad.math.all_are_integer_equivalent(argument) → bool

Is true when argument is an iterable collection with integer-equivalent items.

>>> import fractions
>>> items = [1, "2", 3.0, fractions.Fraction(4, 1)]
>>> abjad.math.all_are_integer_equivalent(items)
True

>>> abjad.math.all_are_integer_equivalent([1, "2", 3.5, 4])
False

abjad.math.all_are_integer_equivalent_numbers(argument) → bool

Is true when argument is an iterable collection with integer-equivalent items.

>>> import fractions
>>> items = [1, 2, 3.0, fractions.Fraction(4, 1)]
>>> abjad.math.all_are_integer_equivalent_numbers(items)
True

>>> abjad.math.all_are_integer_equivalent_numbers([1, 2, 3.5, 4])
False

abjad.math.all_are_nonnegative_integer_equivalent_numbers(argument) → bool

Is true when argument is an iterable collection of nonnegative integer-equivalent numbers.

>>> import fractions
>>> items = [0, 0.0, fractions.Fraction(0), 2, 2.0, fractions.Fraction(2)]
>>> abjad.math.all_are_nonnegative_integer_equivalent_numbers(items)
True

>>> items = [0, 0.0, fractions.Fraction(0), -2, 2.0, fractions.Fraction(2)]
>>> abjad.math.all_are_nonnegative_integer_equivalent_numbers(items)
False

abjad.math.all_are_nonnegative_integer_powers_of_two(argument) → bool

Is true when argument is an iterable collection of nonnegative integer powers of two.

>>> items = [0, 1, 1, 1, 2, 4, 32, 32]
>>> abjad.math.all_are_nonnegative_integer_powers_of_two(items)
True

>>> abjad.math.all_are_nonnegative_integer_powers_of_two(17)
False

Is true when argument is empty:

>>> abjad.math.all_are_nonnegative_integer_powers_of_two([])
True

abjad.math.all_are_nonnegative_integers(argument) → bool

Is true when argument is an iterable collection of nonnegative integers.

>>> abjad.math.all_are_nonnegative_integers([0, 1, 2, 99])
True

>>> abjad.math.all_are_nonnegative_integers([0, 1, 2, -99])
False

abjad.math.all_are_pairs_of_types(argument, first_type, second_type) → bool

Is true when argument is an iterable collection whose members are all of length 2, and where the first member of each pair is an instance of first_type and where the second member of each pair is an instance of second_type.

>>> items = [(1.0, "a"), (2.1, "b"), (3.45, "c")]
>>> abjad.math.all_are_pairs_of_types(items, float, str)
True

>>> abjad.math.all_are_pairs_of_types("foo", float, str)
False

Is true when argument is empty:

>>> abjad.math.all_are_pairs_of_types([], float, str)
True

abjad.math.all_are_positive_integers(argument) → bool

Is true when argument is an iterable collection of positive integers.

>>> abjad.math.all_are_positive_integers([1, 2, 3, 99])
True

>>> abjad.math.all_are_positive_integers(17)
False

abjad.math.are_relatively_prime(argument) → bool

Is true when argument is an iterable collection of relative primes.

>>> abjad.math.are_relatively_prime([13, 14, 15])
True

>>> abjad.math.are_relatively_prime([13, 14, 15, 16])
False

>>> abjad.math.are_relatively_prime("text")
False

Returns true when argument is empty:

>>> abjad.math.are_relatively_prime([])
True

abjad.math.arithmetic_mean(argument) → int | float | Fraction

Gets arithmetic mean of argument.

Raises exception when argument is not iterable.

>>> abjad.math.arithmetic_mean([1, 2, 2, 20, 30])
11

>>> abjad.math.arithmetic_mean([1, 2, 20])
Fraction(23, 3)

>>> abjad.math.arithmetic_mean([2, 2, 20.0])
8.0

abjad.math.binomial_coefficient(n, k) → int

Gets binomial coefficient of n choose k.

>>> for k in range(8):
...     print(k, "      ", abjad.math.binomial_coefficient(8, k))
... 
0        1
1        8
2        28
3        56
4        70
5        56
6        28
7        8

abjad.math.clock_string(fraction: Fraction) → str

Changes fraction to clock string.

Rounds down to nearest second.

>>> abjad.math.clock_string(abjad.Fraction(117))
"1'57''"

abjad.math.cumulative_products(argument)

Gets cumulative products of argument.

Raises exception when argument is not iterable.

Returns new object of argument type.

>>> abjad.math.cumulative_products([1, 2, 3, 4, 5, 6, 7, 8])
[1, 2, 6, 24, 120, 720, 5040, 40320]

>>> abjad.math.cumulative_products([1, -2, 3, -4, 5, -6, 7, -8])
[1, -2, -6, 24, 120, -720, -5040, 40320]

abjad.math.cumulative_sums(argument, start=0)

Gets cumulative sums of argument.

Raises exception when argument is not iterable.

Returns new object of argument type.

>>> abjad.math.cumulative_sums([1, 2, 3, 4, 5, 6, 7, 8], start=0)
[0, 1, 3, 6, 10, 15, 21, 28, 36]

>>> abjad.math.cumulative_sums([1, 2, 3, 4, 5, 6, 7, 8], start=None)
[1, 3, 6, 10, 15, 21, 28, 36]

abjad.math.difference_series(argument)

Gets difference series of argument.

Returns new object of argument type.

>>> abjad.math.difference_series([1, 1, 2, 3, 5, 5, 6])
[0, 1, 1, 2, 0, 1]

>>> abjad.math.difference_series([9, 6, 8, 5, 7, 4, 6])
[-3, 2, -3, 2, -3, 2]

abjad.math.divide_integer_by_proportion(n: int | float, proportion: tuple[int, ...]) → list[Fraction | float]

Divides integer n by tuple proportion.

>>> abjad.math.divide_integer_by_proportion(1, (1, 1, 3))
[Fraction(1, 5), Fraction(1, 5), Fraction(3, 5)]

>>> abjad.math.divide_integer_by_proportion(1.0, (1, 1, 3))
[0.2, 0.2, 0.6]

abjad.math.divisors(n) → list[int]

Gets positive divisors of n in increasing order.

Raises not implemented error on 0.

>>> abjad.math.divisors(84)
[1, 2, 3, 4, 6, 7, 12, 14, 21, 28, 42, 84]

>>> for x in range(10, 20):
...     print(x, abjad.math.divisors(x))
... 
10 [1, 2, 5, 10]
11 [1, 11]
12 [1, 2, 3, 4, 6, 12]
13 [1, 13]
14 [1, 2, 7, 14]
15 [1, 3, 5, 15]
16 [1, 2, 4, 8, 16]
17 [1, 17]
18 [1, 2, 3, 6, 9, 18]
19 [1, 19]

Allows nonpositive n:

>>> abjad.math.divisors(-27)
[1, 3, 9, 27]

abjad.math.equal_or_greater_power_of_two(n) → Fraction

Gets fraction equal or just greater power of two from n.

>>> for numerator in range(1, 16 + 1):
...     fraction = abjad.Fraction(numerator, 16)
...     result = abjad.math.equal_or_greater_power_of_two(fraction)
...     sixteenths = abjad.duration.pair_with_denominator(fraction, 16)
...     numerator, denominator = sixteenths
...     print(f"{numerator}/{denominator}       {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

abjad.math.factors(n) → list[int]

Gets prime factors less than or equal to positive integer n .

Returns factors in increasing order.

>>> abjad.math.factors(84)
[2, 2, 3, 7]

>>> for n in range(10, 20):
...     print(n, abjad.math.factors(n))
... 
10 [2, 5]
11 [11]
12 [2, 2, 3]
13 [13]
14 [2, 7]
15 [3, 5]
16 [2, 2, 2, 2]
17 [17]
18 [2, 3, 3]
19 [19]

abjad.math.fraction_to_proper_fraction(rational) → tuple[int, Fraction]

Changes rational to proper fraction.

>>> import fractions
>>> abjad.math.fraction_to_proper_fraction(fractions.Fraction(116, 8))
(14, Fraction(1, 2))

abjad.math.greatest_common_divisor(*integers) → int

Calculates greatest common divisor of integers.

Allows nonpositive input.

Raises not implemented error when zero is included in input.

>>> abjad.math.greatest_common_divisor(84, -94, -144)
2

abjad.math.greatest_power_of_two_less_equal(n: int | Fraction) → int

Gets greatest integer power of two less than or equal to positive n.

>>> for n in range(10, 20):
...     result = abjad.math.greatest_power_of_two_less_equal(n)
...     print(f"{n} {result}")
... 
10 8
11 8
12 8
13 8
14 8
15 8
16 16
17 16
18 16
19 16

>>> for numerator in range(1, 8):
...     fraction = abjad.Fraction(numerator, 8)
...     result = abjad.math.greatest_power_of_two_less_equal(fraction)
...     print(f"{fraction} {result}")
... 
1/8 0.125
1/4 0.25
3/8 0.5
1/2 0.5
5/8 1
3/4 1
7/8 1

abjad.math.integer_equivalent_number_to_integer(number) → int | float

Changes integer-equivalent number to integer.

Returns integer-equivalent number as integer:

>>> abjad.math.integer_equivalent_number_to_integer(17.0)
17

Returns noninteger-equivalent number unchanged:

>>> abjad.math.integer_equivalent_number_to_integer(17.5)
17.5

abjad.math.integer_to_base_k_tuple(n, k) → tuple[int, ...]

Changes nonnegative integer n to base-k tuple.

Gets base-10 digits of 1066:

>>> abjad.math.integer_to_base_k_tuple(1066, 10)
(1, 0, 6, 6)

Gets base-2 digits of 1066:

>>> abjad.math.integer_to_base_k_tuple(1066, 2)
(1, 0, 0, 0, 0, 1, 0, 1, 0, 1, 0)

Gets base-26 digits of 1066:

>>> abjad.math.integer_to_base_k_tuple(1066, 26)
(1, 15, 0)

abjad.math.integer_to_binary_string(n) → str

Changes positive integer n to binary string.

>>> for n in range(1, 16 + 1):
...     string = abjad.math.integer_to_binary_string(n)
...     print(f"{n}\t{string}")
... 
1	1
2	10
3	11
4	100
5	101
6	110
7	111
8	1000
9	1001
10	1010
11	1011
12	1100
13	1101
14	1110
15	1111
16	10000

abjad.math.is_assignable_integer(argument) → bool

Is true when argument is equivalent to an integer that can be written without recourse to ties.

>>> for n in range(0, 16 + 1):
...     print("%s\t%s" % (n, abjad.math.is_assignable_integer(n)))
... 
0	False
1	True
2	True
3	True
4	True
5	False
6	True
7	True
8	True
9	False
10	False
11	False
12	True
13	False
14	True
15	True
16	True

abjad.math.is_integer_equivalent(argument) → bool

Is true when argument is an integer-equivalent number.

>>> abjad.math.is_integer_equivalent(12.0)
True

>>> abjad.math.is_integer_equivalent("12")
True

>>> abjad.math.is_integer_equivalent("foo")
False

abjad.math.is_integer_equivalent_n_tuple(argument, n) → bool

Is true when argument is a tuple of n integer-equivalent items.

>>> import fractions
>>> tuple_ = (2.0, "3", fractions.Fraction(4, 1))
>>> abjad.math.is_integer_equivalent_n_tuple(tuple_, 3)
True

>>> tuple_ = (2.5, "3", fractions.Fraction(4, 1))
>>> abjad.math.is_integer_equivalent_n_tuple(tuple_, 3)
False

abjad.math.is_integer_equivalent_number(argument: object) → bool

Is true when argument is a number and argument is equivalent to an integer.

>>> abjad.math.is_integer_equivalent_number(12.0)
True

abjad.math.is_nonnegative_integer(argument) → bool

Is true when argument equals a nonnegative integer.

>>> abjad.math.is_nonnegative_integer(99)
True

>>> abjad.math.is_nonnegative_integer(0)
True

>>> abjad.math.is_nonnegative_integer(-1)
False

abjad.math.is_nonnegative_integer_equivalent_number(argument) → bool

Is true when argument is a nonnegative integer-equivalent number.

>>> fraction = abjad.Fraction(2)
>>> abjad.math.is_nonnegative_integer_equivalent_number(fraction)
True

abjad.math.is_nonnegative_integer_power_of_two(argument) → bool

Is true when argument is a nonnegative integer power of 2.

>>> for n in range(10):
...     print(n, abjad.math.is_nonnegative_integer_power_of_two(n))
... 
0 True
1 True
2 True
3 False
4 True
5 False
6 False
7 False
8 True
9 False

abjad.math.is_positive_integer(argument) → bool

Is true when argument equals a positive integer.

>>> abjad.math.is_positive_integer(99)
True

>>> abjad.math.is_positive_integer(0)
False

>>> abjad.math.is_positive_integer(-1)
False

abjad.math.is_positive_integer_equivalent_number(argument) → bool

Is true when argument is a positive integer-equivalent number.

>>> fraction = abjad.Fraction(2)
>>> abjad.math.is_positive_integer_equivalent_number(fraction)
True

abjad.math.is_positive_integer_power_of_two(argument) → bool

Is true when argument is a positive integer power of 2.

>>> for n in range(10):
...     print(n, abjad.math.is_positive_integer_power_of_two(n))
... 
0 False
1 True
2 True
3 False
4 True
5 False
6 False
7 False
8 True
9 False

abjad.math.least_common_multiple(*integers) → int

Gets least common multiple of positive integers.

>>> abjad.math.least_common_multiple(2, 4, 5, 10, 20)
20

>>> abjad.math.least_common_multiple(4, 4)
4

>>> abjad.math.least_common_multiple(4, 5)
20

>>> abjad.math.least_common_multiple(4, 6)
12

>>> abjad.math.least_common_multiple(4, 7)
28

>>> abjad.math.least_common_multiple(4, 8)
8

>>> abjad.math.least_common_multiple(4, 9)
36

>>> abjad.math.least_common_multiple(4, 10)
20

>>> abjad.math.least_common_multiple(4, 11)
44

abjad.math.partition_integer_by_proportion(n: int, proportion: tuple[int, ...]) → list[int]

Partitions positive integer-equivalent n by proportion.

Returns result with weight equal to absolute value of n.

Partitions positive integer-equivalent n by proportion with positive parts:

>>> abjad.math.partition_integer_by_proportion(10, (1, 2))
[3, 7]

Partitions positive integer-equivalent n by proportion with negative parts:

>>> abjad.math.partition_integer_by_proportion(10, (1, -2))
[3, -7]

Partitions negative integer-equivalent n by proportion:

>>> abjad.math.partition_integer_by_proportion(-10, (1, 2))
[-3, -7]

Partitions negative integer-equivalent n by proportion with negative parts:

>>> abjad.math.partition_integer_by_proportion(-10, (1, -2))
[-3, 7]

More examples:

>>> abjad.math.partition_integer_by_proportion(10, (1,))
[10]

>>> abjad.math.partition_integer_by_proportion(10, (1, 1))
[5, 5]

>>> abjad.math.partition_integer_by_proportion(10, (1, -1, -1))
[3, -4, -3]

>>> abjad.math.partition_integer_by_proportion(-10, (1, 1, 1, 1))
[-3, -2, -3, -2]

>>> abjad.math.partition_integer_by_proportion(-10, (1, 1, 1, 1, 1))
[-2, -2, -2, -2, -2]

abjad.math.partition_integer_into_canonic_parts(n, decrease_parts_monotonically=True) → tuple[int, ...]

Partitions integer n into canonic parts.

Returns tuple with parts that decrease monotonically.

Returns all parts positive on positive n:

>>> for n in range(1, 11):
...     print(n, abjad.math.partition_integer_into_canonic_parts(n))
... 
1 (1,)
2 (2,)
3 (3,)
4 (4,)
5 (4, 1)
6 (6,)
7 (7,)
8 (8,)
9 (8, 1)
10 (8, 2)

Returns all parts negative on negative n:

>>> for n in reversed(range(-20, -10)):
...     print(n, abjad.math.partition_integer_into_canonic_parts(n))
... 
-11 (-8, -3)
-12 (-12,)
-13 (-12, -1)
-14 (-14,)
-15 (-15,)
-16 (-16,)
-17 (-16, -1)
-18 (-16, -2)
-19 (-16, -3)
-20 (-16, -4)

Returns parts that increase monotonically:

>>> for n in range(11, 21):
...     print(
...         n,
...         abjad.math.partition_integer_into_canonic_parts(
...             n, decrease_parts_monotonically=False
...         ),
...     )
... 
11 (3, 8)
12 (12,)
13 (1, 12)
14 (14,)
15 (15,)
16 (16,)
17 (1, 16)
18 (2, 16)
19 (3, 16)
20 (4, 16)

abjad.math.sign(n) → int

Gets sign of n.

Returns -1 on negative n:

>>> abjad.math.sign(-96.2)
-1

Returns 0 when n is 0:

>>> abjad.math.sign(0)
0

Returns 1 on positive n:

>>> abjad.math.sign(abjad.Duration(9, 8))
1

abjad.math.weight(sequence: Sequence, *, start: T) → T

Gets weight of sequence. Weight defined equal to the sum of the absolute value of items in sequence. Types of items in sequence must be homogeneous and must equal the type of start.

>>> abjad.math.weight([-1, -2, 3, 4, 5], start=0)
15

>>> abjad.math.weight([], start=0)
0

>>> durations = abjad.duration.durations([(1, 8), (2, 8), (3, 8)])
>>> abjad.math.weight(durations, start=abjad.Duration(0))
Duration(numerator=3, denominator=4)

abjad.math.yield_all_compositions_of_integer(n: int) → Iterator[tuple[int, ...]]

Yields all compositions of positive integer n.

Lists parts in descending lex order.

Parts sum to n.

Finds small values of n easily.

Takes around 4 seconds for n equal to 17.

>>> for tuple_ in abjad.math.yield_all_compositions_of_integer(5):
...     tuple_
... 
(5,)
(4, 1)
(3, 2)
(3, 1, 1)
(2, 3)
(2, 2, 1)
(2, 1, 2)
(2, 1, 1, 1)
(1, 4)
(1, 3, 1)
(1, 2, 2)
(1, 2, 1, 1)
(1, 1, 3)
(1, 1, 2, 1)
(1, 1, 1, 2)
(1, 1, 1, 1, 1)

class abjad.math.Infinity

Infinity.

Initializes as a system singleton at start-up.

Available as a built-in after Abjad starts.

All numbers compare less than infinity:

>>> 9999999 < abjad.Infinity()
True

>>> 2**38 < abjad.Infinity()
True

Infinity compares equal to itself:

>>> abjad.Infinity() == abjad.Infinity()
True

Negative infinity compares less than infinity:

>>> abjad.NegativeInfinity() < abjad.Infinity()
True

class abjad.math.NegativeInfinity

Negative infinity.

Initializes as a system singleton at start-up.

Available as a built-in after Abjad start.

All numbers compare greater than negative infinity:

>>> abjad.NegativeInfinity() < -9999999
True

Negative infinity compares equal to itself:

>>> abjad.NegativeInfinity() == abjad.NegativeInfinity()
True

Negative infinity compares less than infinity:

>>> abjad.NegativeInfinity() < abjad.Infinity()
True