Package cc.redberry.rings
Interface Ring<E>
-
- Type Parameters:
E
- the type of objects that may be operated by this ring
- All Superinterfaces:
Comparator<E>
,IParser<E>
,Iterable<E>
,Serializable
,Stringifiable<E>
- All Known Subinterfaces:
IPolynomialRing<Poly>
- All Known Implementing Classes:
AlgebraicNumberField
,ARing
,FiniteField
,ImageRing
,Integers
,IntegersZp
,MultipleFieldExtension
,MultivariateRing
,QuotientRing
,Rationals
,SimpleFieldExtension
,UnivariateRing
public interface Ring<E> extends Comparator<E>, Iterable<E>, IParser<E>, Stringifiable<E>, Serializable
Ring of elements. Mathematical operations defined inRing
interface include all field operations, though the particular implementations may represent a more restricted rings (general rings, Euclidean rings etc.), in which case some field operations (e.g. reciprocal) are not applicable (will throw exception).- Since:
- 1.0
-
-
Method Summary
Modifier and Type Method Description default E
abs(E el)
Returns the abs value of element (no copy)default E
add(E... elements)
Total of the array of elementsE
add(E a, E b)
Add two elementsdefault E
addMutable(E a, E b)
Adds two elements and destroys the initial content ofa
.BigInteger
cardinality()
Returns the number of elements in this ring (cardinality) or null if ring is infiniteBigInteger
characteristic()
Returns characteristic of this ringE
copy(E element)
Makes a deep copy of the specified element (for immutable instances the same reference returned).default E[]
createArray(int length)
Creates generic array of ring elements of specified lengthdefault E[]
createArray(E element)
Creates generic array with single elementdefault E[]
createArray(E a, E b)
Creates generic array of{a, b}
default E[]
createArray(E a, E b, E c)
Creates generic array of{a, b, c}
default E[][]
createArray2d(int length)
Creates 2d array of ring elements of specified lengthdefault E[][]
createArray2d(int m, int n)
Creates 2d array of ring elements of specified shapedefault E[]
createZeroesArray(int length)
Creates array filled with zero elementsdefault E[][]
createZeroesArray2d(int m, int n)
Creates 2d array of ring elements of specified shape filled with zero elementsdefault E
decrement(E element)
Returnselement - 1
E[]
divideAndRemainder(E dividend, E divider)
Returns quotient and remainder ofdividend / divider
default E
divideExact(E dividend, E divider)
Dividesdividend
bydivider
or throwsArithmeticException
if exact division is not possibledefault E
divideExactMutable(E dividend, E divider)
Internal APIdefault E
divideOrNull(E dividend, E divider)
Dividesdividend
bydivider
or returnsnull
if exact division is not possibledefault E[]
extendedGCD(E a, E b)
Returns array of[gcd(a,b), s, t]
such thats * a + t * b = gcd(a, b)
default FactorDecomposition<E>
factor(E element)
Factor specified elementdefault E
factorial(long num)
Gives a product ofvalueOf(1) * valueOf(2) * .... * valueOf(num)
default FactorDecomposition<E>
factorSquareFree(E element)
Square-free factorization of specified elementdefault void
fillZeros(E[] array)
Fills array with zerosdefault E[]
firstBezoutCoefficient(E a, E b)
Returns array of[gcd(a,b), s]
such thats * a + t * b = gcd(a, b)
default E
gcd(E... elements)
Returns greatest common divisor of specified elementsdefault E
gcd(E a, E b)
Returns the greatest common divisor of two elementsdefault E
gcd(Iterable<E> elements)
Returns greatest common divisor of specified elementsdefault E
getNegativeOne()
Returns negative unit element of this ring (minus one)E
getOne()
Returns unit element of this ring (one)E
getZero()
Returns zero element of this ringdefault E
increment(E element)
Returnselement + 1
boolean
isEuclideanRing()
Returns whether this ring is a Euclidean ringboolean
isField()
Returns whether this ring is a fielddefault boolean
isFinite()
Returns whether this ring is finitedefault boolean
isFiniteField()
Returns whether this ring is a finite fielddefault boolean
isMinusOne(E e)
Tests whether specified element is minus oneboolean
isOne(E element)
Tests whether specified element is one (exactly)boolean
isPerfectPower()
Returns whether the cardinality is a perfect power (p^k with k > 1)boolean
isUnit(E element)
Tests whether specified element is a ring unitdefault boolean
isUnitOrZero(E element)
Tests whether specified element is a ring unit or zeroboolean
isZero(E element)
Tests whether specified element is zeroIterator<E>
iterator()
Returns iterator over ring elements (for finite rings, otherwise throws exception)default E
lcm(E... elements)
Returns the least common multiple of two elementsdefault E
lcm(E a, E b)
Returns the least common multiple of two elementsdefault E
lcm(Iterable<E> elements)
Returns the least common multiple of two elementsdefault E
max(E a, E b)
Returns the max value (no copy)default E
min(E a, E b)
Returns the min value (no copy)default E
multiply(E... elements)
Multiplies the array of elementsdefault E
multiply(E a, long b)
Multiplies two elementsE
multiply(E a, E b)
Multiplies two elementsdefault E
multiply(Iterable<E> elements)
Multiplies the array of elementsdefault E
multiplyMutable(E a, E b)
Multiplies two elements and destroys the initial content ofa
E
negate(E element)
Negates the given elementdefault E
negateMutable(E element)
Negates the given element and destroys the initial content ofelement
default E
parse(String string)
Parse string into ring elementBigInteger
perfectPowerBase()
Returnsbase
so thatcardinality == base^exponent
or null if cardinality is not finiteBigInteger
perfectPowerExponent()
Returnsexponent
so thatcardinality == base^exponent
or null if cardinality is not finitedefault E
pow(E base, int exponent)
Returnsbase
in a power ofexponent
(non negative)default E
pow(E base, long exponent)
Returnsbase
in a power ofexponent
(non negative)default E
pow(E base, BigInteger exponent)
Returnsbase
in a power ofexponent
(non negative)default E
quotient(E dividend, E divider)
Returns the quotient ofdividend / divider
default E
randomElement()
Returns a random element from this ringdefault E
randomElement(org.apache.commons.math3.random.RandomGenerator rnd)
Returns a random element from this ringdefault E
randomElementTree()
If this ring has a complicated nested structure, this method guaranties that the resulting random element will reflect ring complicated structure, i.e.default E
randomElementTree(org.apache.commons.math3.random.RandomGenerator rnd)
If this ring has a complicated nested structure, this method guaranties that the resulting random element will reflect ring complicated structure, i.e.default E
randomNonZeroElement(org.apache.commons.math3.random.RandomGenerator rnd)
Returns a random non zero element from this ringE
reciprocal(E element)
Gives the inverse elementelement ^ (-1)
default E
remainder(E dividend, E divider)
Returns the remainder ofdividend / divider
default void
setToValueOf(E[] elements)
AppliesvalueOf(Object)
inplace to the specified arraydefault int
signum(E element)
Returns -1 ifelement < 0
, 0 ifelement == 0
and 1 ifelement > 0
, where comparison is specified byComparator.compare(Object, Object)
E
subtract(E a, E b)
Subtractsb
froma
default E
subtractMutable(E a, E b)
Subtractsb
froma
and destroys the initial content ofa
E
valueOf(long val)
Returns ring element associated with specifiedlong
default E[]
valueOf(long[] elements)
Converts array of machine integers to ring elements viavalueOf(long)
E
valueOf(E val)
Converts a value from other ring to this ring.E
valueOfBigInteger(BigInteger val)
Returns ring element associated with specified integer-
Methods inherited from interface java.util.Comparator
compare, equals, reversed, thenComparing, thenComparing, thenComparing, thenComparingDouble, thenComparingInt, thenComparingLong
-
Methods inherited from interface java.lang.Iterable
forEach, spliterator
-
Methods inherited from interface cc.redberry.rings.io.Stringifiable
toString
-
-
-
-
Method Detail
-
isField
boolean isField()
Returns whether this ring is a field- Returns:
- whether this ring is a field
-
isEuclideanRing
boolean isEuclideanRing()
Returns whether this ring is a Euclidean ring- Returns:
- whether this ring is a Euclidean ring
-
isFinite
default boolean isFinite()
Returns whether this ring is finite- Returns:
- whether this ring is finite
-
isFiniteField
default boolean isFiniteField()
Returns whether this ring is a finite field- Returns:
- whether this ring is a finite field
-
cardinality
BigInteger cardinality()
Returns the number of elements in this ring (cardinality) or null if ring is infinite- Returns:
- the number of elements in this ring (cardinality) or null if ring is infinite
-
characteristic
BigInteger characteristic()
Returns characteristic of this ring- Returns:
- characteristic of this ring
-
isPerfectPower
boolean isPerfectPower()
Returns whether the cardinality is a perfect power (p^k with k > 1)- Returns:
- whether the cardinality is a perfect power (p^k with k > 1)
-
perfectPowerBase
BigInteger perfectPowerBase()
Returnsbase
so thatcardinality == base^exponent
or null if cardinality is not finite- Returns:
base
so thatcardinality == base^exponent
or null if cardinality is not finite
-
perfectPowerExponent
BigInteger perfectPowerExponent()
Returnsexponent
so thatcardinality == base^exponent
or null if cardinality is not finite- Returns:
exponent
so thatcardinality == base^exponent
or null if cardinality is not finite
-
add
E add(E a, E b)
Add two elements- Parameters:
a
- the first elementb
- the second element- Returns:
- a + b
-
add
default E add(E... elements)
Total of the array of elements- Parameters:
elements
- elements to sum- Returns:
- sum of the array
-
increment
default E increment(E element)
Returnselement + 1
- Parameters:
element
- the element- Returns:
element + 1
-
decrement
default E decrement(E element)
Returnselement - 1
- Parameters:
element
- the element- Returns:
element - 1
-
subtract
E subtract(E a, E b)
Subtractsb
froma
- Parameters:
a
- the first elementb
- the second element- Returns:
- a - b
-
multiply
E multiply(E a, E b)
Multiplies two elements- Parameters:
a
- the first elementb
- the second element- Returns:
- a * b
-
multiply
default E multiply(E a, long b)
Multiplies two elements- Parameters:
a
- the first elementb
- the second element- Returns:
- a * b
-
multiply
default E multiply(E... elements)
Multiplies the array of elements- Parameters:
elements
- the elements- Returns:
- product of the array
-
multiply
default E multiply(Iterable<E> elements)
Multiplies the array of elements- Parameters:
elements
- the elements- Returns:
- product of the array
-
negate
E negate(E element)
Negates the given element- Parameters:
element
- the ring element- Returns:
- -val
-
addMutable
default E addMutable(E a, E b)
Adds two elements and destroys the initial content ofa
.- Parameters:
a
- the first element (may be destroyed)b
- the second element- Returns:
- a + b
-
subtractMutable
default E subtractMutable(E a, E b)
Subtractsb
froma
and destroys the initial content ofa
- Parameters:
a
- the first element (may be destroyed)b
- the second element- Returns:
- a - b
-
multiplyMutable
default E multiplyMutable(E a, E b)
Multiplies two elements and destroys the initial content ofa
- Parameters:
a
- the first element (may be destroyed)b
- the second element- Returns:
- a * b
-
negateMutable
default E negateMutable(E element)
Negates the given element and destroys the initial content ofelement
- Parameters:
element
- the ring element (may be destroyed)- Returns:
- -element
-
copy
E copy(E element)
Makes a deep copy of the specified element (for immutable instances the same reference returned).- Parameters:
element
- the element- Returns:
- deep copy of specified element
-
signum
default int signum(E element)
Returns -1 ifelement < 0
, 0 ifelement == 0
and 1 ifelement > 0
, where comparison is specified byComparator.compare(Object, Object)
- Parameters:
element
- the element- Returns:
- -1 if
element < 0
, 0 ifelement == 0
and 1 otherwise
-
divideAndRemainder
E[] divideAndRemainder(E dividend, E divider)
Returns quotient and remainder ofdividend / divider
- Parameters:
dividend
- the dividenddivider
- the divider- Returns:
{quotient, remainder}
-
quotient
default E quotient(E dividend, E divider)
Returns the quotient ofdividend / divider
- Parameters:
dividend
- the dividenddivider
- the divider- Returns:
- the quotient of
dividend / divider
-
remainder
default E remainder(E dividend, E divider)
Returns the remainder ofdividend / divider
- Parameters:
dividend
- the dividenddivider
- the divider- Returns:
- the remainder of
dividend / divider
-
divideOrNull
default E divideOrNull(E dividend, E divider)
Dividesdividend
bydivider
or returnsnull
if exact division is not possible- Parameters:
dividend
- the dividenddivider
- the divider- Returns:
dividend / divider
ornull
if exact division is not possible
-
divideExact
default E divideExact(E dividend, E divider)
Dividesdividend
bydivider
or throwsArithmeticException
if exact division is not possible- Parameters:
dividend
- the dividenddivider
- the divider- Returns:
dividend / divider
- Throws:
ArithmeticException
- if exact division is not possible
-
reciprocal
E reciprocal(E element)
Gives the inverse elementelement ^ (-1)
- Parameters:
element
- the element- Returns:
element ^ (-1)
-
gcd
default E gcd(E a, E b)
Returns the greatest common divisor of two elements- Parameters:
a
- the first elementb
- the second element- Returns:
- gcd
-
extendedGCD
default E[] extendedGCD(E a, E b)
Returns array of[gcd(a,b), s, t]
such thats * a + t * b = gcd(a, b)
- Throws:
UnsupportedOperationException
- if this is not the Euclidean ring and there is no special implementation provided by particular subtype
-
firstBezoutCoefficient
default E[] firstBezoutCoefficient(E a, E b)
Returns array of[gcd(a,b), s]
such thats * a + t * b = gcd(a, b)
- Parameters:
a
- the first ring element (for which the Bezout coefficient is computed)b
- the second ring element- Returns:
- array of
[gcd(a,b), s]
such thats * a + t * b = gcd(a, b)
-
lcm
default E lcm(E a, E b)
Returns the least common multiple of two elements- Parameters:
a
- the first elementb
- the second element- Returns:
- lcm
-
lcm
default E lcm(E... elements)
Returns the least common multiple of two elements- Parameters:
elements
- the elements- Returns:
- lcm
-
lcm
default E lcm(Iterable<E> elements)
Returns the least common multiple of two elements- Parameters:
elements
- the elements- Returns:
- lcm
-
gcd
default E gcd(E... elements)
Returns greatest common divisor of specified elements- Parameters:
elements
- the elements- Returns:
- gcd
-
gcd
default E gcd(Iterable<E> elements)
Returns greatest common divisor of specified elements- Parameters:
elements
- the elements- Returns:
- gcd
-
factorSquareFree
default FactorDecomposition<E> factorSquareFree(E element)
Square-free factorization of specified element
-
factor
default FactorDecomposition<E> factor(E element)
Factor specified element
-
getZero
E getZero()
Returns zero element of this ring- Returns:
- 0
-
getOne
E getOne()
Returns unit element of this ring (one)- Returns:
- 1
-
getNegativeOne
default E getNegativeOne()
Returns negative unit element of this ring (minus one)- Returns:
- -1
-
isZero
boolean isZero(E element)
Tests whether specified element is zero- Parameters:
element
- the ring element- Returns:
- whether specified element is zero
-
isOne
boolean isOne(E element)
Tests whether specified element is one (exactly)- Parameters:
element
- the ring element- Returns:
- whether specified element is exactly one
- See Also:
isUnit(Object)
-
isUnit
boolean isUnit(E element)
Tests whether specified element is a ring unit- Parameters:
element
- the ring element- Returns:
- whether specified element is a ring unit
- See Also:
isOne(Object)
-
isUnitOrZero
default boolean isUnitOrZero(E element)
Tests whether specified element is a ring unit or zero- Parameters:
element
- the ring element- Returns:
- whether specified element is a ring unit or zero
-
isMinusOne
default boolean isMinusOne(E e)
Tests whether specified element is minus one- Parameters:
e
- the ring element- Returns:
- whether specified element is minus one
-
valueOf
E valueOf(long val)
Returns ring element associated with specifiedlong
- Parameters:
val
- machine integer- Returns:
- ring element associated with specified
long
-
valueOfBigInteger
E valueOfBigInteger(BigInteger val)
Returns ring element associated with specified integer- Parameters:
val
- integer- Returns:
- ring element associated with specified integer
-
valueOf
default E[] valueOf(long[] elements)
Converts array of machine integers to ring elements viavalueOf(long)
- Parameters:
elements
- array of machine integers- Returns:
- array of ring elements
-
valueOf
E valueOf(E val)
Converts a value from other ring to this ring. The result is not guarantied to be a new instance (i.e.val == valueOf(val)
is possible).- Parameters:
val
- some element from any ring- Returns:
- this ring element associated with specified
val
-
setToValueOf
default void setToValueOf(E[] elements)
AppliesvalueOf(Object)
inplace to the specified array- Parameters:
elements
- the array
-
createArray
default E[] createArray(int length)
Creates generic array of ring elements of specified length- Parameters:
length
- array length- Returns:
- array of ring elements of specified
length
-
createArray2d
default E[][] createArray2d(int length)
Creates 2d array of ring elements of specified length- Parameters:
length
- array length- Returns:
- 2d array of ring elements of specified
length
-
createArray2d
default E[][] createArray2d(int m, int n)
Creates 2d array of ring elements of specified shape- Parameters:
m
- result lengthn
- length of each array in the result- Returns:
- 2d array E[m][n]
-
createZeroesArray
default E[] createZeroesArray(int length)
Creates array filled with zero elements- Parameters:
length
- array length- Returns:
- array filled with zero elements of specified
length
-
fillZeros
default void fillZeros(E[] array)
Fills array with zeros
-
createZeroesArray2d
default E[][] createZeroesArray2d(int m, int n)
Creates 2d array of ring elements of specified shape filled with zero elements- Parameters:
m
- result lengthn
- length of each array in the result- Returns:
- 2d array E[m][n] filled with zero elements
-
createArray
default E[] createArray(E a, E b)
Creates generic array of{a, b}
- Parameters:
a
- the first element of arrayb
- the second element of array- Returns:
- array
{a,b}
-
createArray
default E[] createArray(E element)
Creates generic array with single element- Parameters:
element
- the element- Returns:
- array with single specified element
-
pow
default E pow(E base, int exponent)
Returnsbase
in a power ofexponent
(non negative)- Parameters:
base
- baseexponent
- exponent (non negative)- Returns:
base
in a power ofexponent
-
pow
default E pow(E base, long exponent)
Returnsbase
in a power ofexponent
(non negative)- Parameters:
base
- baseexponent
- exponent (non negative)- Returns:
base
in a power ofexponent
-
pow
default E pow(E base, BigInteger exponent)
Returnsbase
in a power ofexponent
(non negative)- Parameters:
base
- baseexponent
- exponent (non negative)- Returns:
base
in a power ofexponent
-
factorial
default E factorial(long num)
Gives a product ofvalueOf(1) * valueOf(2) * .... * valueOf(num)
- Parameters:
num
- the number- Returns:
valueOf(1) * valueOf(2) * .... * valueOf(num)
-
iterator
Iterator<E> iterator()
Returns iterator over ring elements (for finite rings, otherwise throws exception)
-
randomElement
default E randomElement()
Returns a random element from this ring- Returns:
- random element from this ring
-
randomElement
default E randomElement(org.apache.commons.math3.random.RandomGenerator rnd)
Returns a random element from this ring- Parameters:
rnd
- the source of randomness- Returns:
- random element from this ring
-
randomElementTree
default E randomElementTree(org.apache.commons.math3.random.RandomGenerator rnd)
If this ring has a complicated nested structure, this method guaranties that the resulting random element will reflect ring complicated structure, i.e. the result will be roughly as complicated as the ring is- Returns:
- random element from this ring
-
randomElementTree
default E randomElementTree()
If this ring has a complicated nested structure, this method guaranties that the resulting random element will reflect ring complicated structure, i.e. the result will be roughly as complicated as the ring is- Returns:
- random element from this ring
-
randomNonZeroElement
default E randomNonZeroElement(org.apache.commons.math3.random.RandomGenerator rnd)
Returns a random non zero element from this ring- Parameters:
rnd
- the source of randomness- Returns:
- random non zero element from this ring
-
-