math

Abjad’s math library.

---

Classes

Infinity	Infinity.
NegativeInfinity	Negative infinity.

class abjad.math.Infinity

Infinity.

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

Initializes as a system singleton at start-up.

Available as a built-in after Abjad starts.

---

Attributes Summary

__eq__	Compares type.
__float__	Convert infinity to float.
__ge__	Is true for all values of argument.
__gt__	Is true for all noninfinite values of argument.
__hash__	Hashes infinity.
__le__	Is true when argument is infinite.
__lt__	Is true for no values of argument.
__repr__	Gets repr.
__sub__	Subtracts argument from infinity.

---

Special methods

overridden __eq__(argument)

Compares type.

Return type:

bool

__float__()

Convert infinity to float.

Returns float.

overridden __ge__(argument)

Is true for all values of argument.

Returns true.

overridden __gt__(argument)

Is true for all noninfinite values of argument.

Returns true or false.

overridden __hash__()

Hashes infinity.

overridden __le__(argument)

Is true when argument is infinite.

Returns true or false.

overridden __lt__(argument)

Is true for no values of argument.

Returns true or false.

overridden __repr__()

Gets repr.

Return type:

str

__sub__(argument)

Subtracts argument from infinity.

Returns infinity or 0 if argument is also infinity.

class abjad.math.NegativeInfinity

Negative infinity.

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

Initializes as a system singleton at start-up.

Available as a built-in after Abjad start.

---

Special methods

(Infinity).__eq__(argument)

Compares type.

Return type:

bool

(Infinity).__float__()

Convert infinity to float.

Returns float.

(Infinity).__ge__(argument)

Is true for all values of argument.

Returns true.

(Infinity).__gt__(argument)

Is true for all noninfinite values of argument.

Returns true or false.

(Infinity).__hash__()

Hashes infinity.

(Infinity).__le__(argument)

Is true when argument is infinite.

Returns true or false.

(Infinity).__lt__(argument)

Is true for no values of argument.

Returns true or false.

(Infinity).__repr__()

Gets repr.

Return type:

str

(Infinity).__sub__(argument)

Subtracts argument from infinity.

Returns infinity or 0 if argument is also infinity.

---

Functions

all_are_equal	Is true when argument is an iterable collection of equal items.
all_are_integer_equivalent	Is true when argument is an iterable collection with integer-equivalent items.
all_are_integer_equivalent_numbers	Is true when argument is an iterable collection with integer-equivalent items.
all_are_nonnegative_integer_equivalent_numbers	Is true when argument is an iterable collection of nonnegative integer-equivalent numbers.
all_are_nonnegative_integer_powers_of_two	Is true when argument is an iterable collection of nonnegative integer powers of two.
all_are_nonnegative_integers	Is true when argument is an iterable collection of nonnegative integers.
all_are_pairs_of_types	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.
all_are_positive_integers	Is true when argument is an iterable collection of positive integers.
are_relatively_prime	Is true when argument is an iterable collection of relative primes.
arithmetic_mean	Gets arithmetic mean of argument.
binomial_coefficient	Gets binomial coefficient of n choose k.
cumulative_products	Gets cumulative products of argument.
cumulative_sums	Gets cumulative sums of argument.
difference_series	Gets difference series of argument.
divide_integer_by_ratio	Divides integer n by tuple ratio.
divisors	Gets positive divisors of n in increasing order.
factors	Gets prime factors less than or equal to n .
fraction_to_proper_fraction	Changes rational to proper fraction.
greatest_common_divisor	Calculates greatest common divisor of integers.
greatest_power_of_two_less_equal	Gets greatest integer power of two less than or equal to positive n.
integer_equivalent_number_to_integer	Changes integer-equivalent number to integer.
integer_to_base_k_tuple	Changes nonnegative integer n to base-k tuple.
integer_to_binary_string	Changes positive integer n to binary string.
is_assignable_integer	Is true when argument is equivalent to an integer that can be written without recourse to ties.
is_integer_equivalent	Is true when argument is an integer-equivalent number.
is_integer_equivalent_n_tuple	Is true when argument is a tuple of n integer-equivalent items.
is_integer_equivalent_number	Is true when argument is a number and argument is equivalent to an integer.
is_nonnegative_integer	Is true when argument equals a nonnegative integer.
is_nonnegative_integer_equivalent_number	Is true when argument is a nonnegative integer-equivalent number.
is_nonnegative_integer_power_of_two	Is true when argument is a nonnegative integer power of 2.
is_positive_integer	Is true when argument equals a positive integer.
is_positive_integer_equivalent_number	Is true when argument is a positive integer-equivalent number.
is_positive_integer_power_of_two	Is true when argument is a positive integer power of 2.
least_common_multiple	Gets least common multiple of positive integers.
partition_integer_by_ratio	Partitions positive integer-equivalent n by ratio.
partition_integer_into_canonic_parts	Partitions integer n into canonic parts.
sign	Gets sign of n.
weight	Gets weight of argument.
yield_all_compositions_of_integer	Yields all compositions of positive integer n.

abjad.math.all_are_equal(argument)

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

Return type:

bool

abjad.math.all_are_integer_equivalent(argument)

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

Return type:

bool

abjad.math.all_are_integer_equivalent_numbers(argument)

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

Return type:

bool

abjad.math.all_are_nonnegative_integer_equivalent_numbers(argument)

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

Return type:

bool

abjad.math.all_are_nonnegative_integer_powers_of_two(argument)

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

Return type:

bool

abjad.math.all_are_nonnegative_integers(argument)

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

Return type:

bool

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

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

Return type:

bool

abjad.math.all_are_positive_integers(argument)

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

Return type:

bool

abjad.math.are_relatively_prime(argument)

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

Return type:

bool

abjad.math.arithmetic_mean(argument)

Gets arithmetic mean of argument.

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

Raises exception when argument is not iterable.

Return type:

int | float | Fraction

abjad.math.binomial_coefficient(n, k)

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

Return type:

int

abjad.math.cumulative_products(argument)

Gets cumulative products of argument.

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

Raises exception when argument is not iterable.

Returns new object of argument type.

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

Gets cumulative sums of argument.

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

Raises exception when argument is not iterable.

Returns new object of argument type.

abjad.math.difference_series(argument)

Gets difference series of argument.

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

Returns new object of argument type.

abjad.math.divide_integer_by_ratio(n, ratio)

Divides integer n by tuple ratio.

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

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

Return type:

list[Fraction | float]

abjad.math.divisors(n)

Gets positive divisors of n in increasing order.

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

Raises not implemented error on 0.

Return type:

list[int]

abjad.math.factors(n)

Gets prime factors less than or equal to n .

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

n must be a positive integer.

Returns factors in increasing order.

Return type:

list[int]

abjad.math.fraction_to_proper_fraction(rational)

Changes rational to proper fraction.

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

Return type:

tuple[int, Fraction]

abjad.math.greatest_common_divisor(*integers)

Calculates greatest common divisor of integers.

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

Allows nonpositive input.

Raises not implemented error when zero is included in input.

Return type:

int

abjad.math.greatest_power_of_two_less_equal(n, i=0)

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

>>> for n in range(10, 20):
...     print("\t%s\t%s" % (n, abjad.math.greatest_power_of_two_less_equal(n)))
... 
	10	8
	11	8
	12	8
	13	8
	14	8
	15	8
	16	16
	17	16
	18	16
	19	16

Greatest-but-i integer power of 2 less than or equal to positive n:

>>> for n in range(10, 20):
...     print("\t%s\t%s" % (n, abjad.math.greatest_power_of_two_less_equal(n, i=1)))
... 
	10	4
	11	4
	12	4
	13	4
	14	4
	15	4
	16	8
	17	8
	18	8
	19	8

Return type:

int

abjad.math.integer_equivalent_number_to_integer(number)

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

Return type:

int | float

abjad.math.integer_to_base_k_tuple(n, k)

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)

Return type:

tuple[int, ...]

abjad.math.integer_to_binary_string(n)

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

Return type:

str

abjad.math.is_assignable_integer(argument)

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

Return type:

bool

abjad.math.is_integer_equivalent(argument)

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

Return type:

bool

abjad.math.is_integer_equivalent_n_tuple(argument, n)

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

Return type:

bool

abjad.math.is_integer_equivalent_number(argument)

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_integer_equivalent_number(abjad.Duration(1, 2))
False

Return type:

bool

abjad.math.is_nonnegative_integer(argument)

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

Return type:

bool

abjad.math.is_nonnegative_integer_equivalent_number(argument)

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

>>> duration = abjad.Duration(4, 2)
>>> abjad.math.is_nonnegative_integer_equivalent_number(duration)
True

Return type:

bool

abjad.math.is_nonnegative_integer_power_of_two(argument)

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

Return type:

bool

abjad.math.is_positive_integer(argument)

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

Return type:

bool

abjad.math.is_positive_integer_equivalent_number(argument)

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

>>> abjad.math.is_positive_integer_equivalent_number(abjad.Duration(4, 2))
True

Return type:

bool

abjad.math.is_positive_integer_power_of_two(argument)

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

Return type:

bool

abjad.math.least_common_multiple(*integers)

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

Return type:

int

abjad.math.partition_integer_by_ratio(n, ratio)

Partitions positive integer-equivalent n by ratio.

Returns result with weight equal to absolute value of n.

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

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

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

Partitions negative integer-equivalent n by ratio:

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

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

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

More examples:

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

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

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

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

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

Return type:

list[int]

abjad.math.partition_integer_into_canonic_parts(n, decrease_parts_monotonically=True)

Partitions integer n into canonic parts.

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)

Returns tuple with parts that decrease monotonically.

Return type:

tuple[int, ...]

abjad.math.sign(n)

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

Return type:

int

abjad.math.weight(argument)

Gets weight of argument.

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

>>> abjad.math.weight([])
0

Defined equal to sum of the absolute value of items in argument.

Return type:

int

abjad.math.yield_all_compositions_of_integer(n)

Yields all compositions of positive integer n.

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

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.

Return type:

Iterator[tuple[int, ...]]