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 in Ring 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 elements
    E add​(E a, E b)
    Add two elements
    default E addMutable​(E a, E b)
    Adds two elements and destroys the initial content of a.
    BigInteger cardinality()
    Returns the number of elements in this ring (cardinality) or null if ring is infinite
    BigInteger characteristic()
    Returns characteristic of this ring
    E 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 length
    default E[] createArray​(E element)
    Creates generic array with single element
    default 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 length
    default E[][] createArray2d​(int m, int n)
    Creates 2d array of ring elements of specified shape
    default E[] createZeroesArray​(int length)
    Creates array filled with zero elements
    default E[][] createZeroesArray2d​(int m, int n)
    Creates 2d array of ring elements of specified shape filled with zero elements
    default E decrement​(E element)
    Returns element - 1
    E[] divideAndRemainder​(E dividend, E divider)
    Returns quotient and remainder of dividend / divider
    default E divideExact​(E dividend, E divider)
    Divides dividend by divider or throws ArithmeticException if exact division is not possible
    default E divideExactMutable​(E dividend, E divider)
    Internal API
    default E divideOrNull​(E dividend, E divider)
    Divides dividend by divider or returns null if exact division is not possible
    default E[] extendedGCD​(E a, E b)
    Returns array of [gcd(a,b), s, t] such that s * a + t * b = gcd(a, b)
    default FactorDecomposition<E> factor​(E element)
    Factor specified element
    default E factorial​(long num)
    Gives a product of valueOf(1) * valueOf(2) * .... * valueOf(num)
    default FactorDecomposition<E> factorSquareFree​(E element)
    Square-free factorization of specified element
    default void fillZeros​(E[] array)
    Fills array with zeros
    default E[] firstBezoutCoefficient​(E a, E b)
    Returns array of [gcd(a,b), s] such that s * a + t * b = gcd(a, b)
    default E gcd​(E... elements)
    Returns greatest common divisor of specified elements
    default E gcd​(E a, E b)
    Returns the greatest common divisor of two elements
    default E gcd​(Iterable<E> elements)
    Returns greatest common divisor of specified elements
    default 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 ring
    default E increment​(E element)
    Returns element + 1
    boolean isEuclideanRing()
    Returns whether this ring is a Euclidean ring
    boolean isField()
    Returns whether this ring is a field
    default boolean isFinite()
    Returns whether this ring is finite
    default boolean isFiniteField()
    Returns whether this ring is a finite field
    default boolean isMinusOne​(E e)
    Tests whether specified element is minus one
    boolean 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 unit
    default boolean isUnitOrZero​(E element)
    Tests whether specified element is a ring unit or zero
    boolean isZero​(E element)
    Tests whether specified element is zero
    Iterator<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 elements
    default E lcm​(E a, E b)
    Returns the least common multiple of two elements
    default E lcm​(Iterable<E> elements)
    Returns the least common multiple of two elements
    default 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 elements
    default E multiply​(E a, long b)
    Multiplies two elements
    E multiply​(E a, E b)
    Multiplies two elements
    default E multiply​(Iterable<E> elements)
    Multiplies the array of elements
    default E multiplyMutable​(E a, E b)
    Multiplies two elements and destroys the initial content of a
    E negate​(E element)
    Negates the given element
    default E negateMutable​(E element)
    Negates the given element and destroys the initial content of element
    default E parse​(String string)
    Parse string into ring element
    BigInteger perfectPowerBase()
    Returns base so that cardinality == base^exponent or null if cardinality is not finite
    BigInteger perfectPowerExponent()
    Returns exponent so that cardinality == base^exponent or null if cardinality is not finite
    default E pow​(E base, int exponent)
    Returns base in a power of exponent (non negative)
    default E pow​(E base, long exponent)
    Returns base in a power of exponent (non negative)
    default E pow​(E base, BigInteger exponent)
    Returns base in a power of exponent (non negative)
    default E quotient​(E dividend, E divider)
    Returns the quotient of dividend / divider
    default E randomElement()
    Returns a random element from this ring
    default E randomElement​(org.apache.commons.math3.random.RandomGenerator rnd)
    Returns a random element from this ring
    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.
    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 ring
    E reciprocal​(E element)
    Gives the inverse element element ^ (-1)
    default E remainder​(E dividend, E divider)
    Returns the remainder of dividend / divider
    default void setToValueOf​(E[] elements)
    Applies valueOf(Object) inplace to the specified array
    default int signum​(E element)
    Returns -1 if element < 0, 0 if element == 0 and 1 if element > 0, where comparison is specified by Comparator.compare(Object, Object)
    E subtract​(E a, E b)
    Subtracts b from a
    default E subtractMutable​(E a, E b)
    Subtracts b from a and destroys the initial content of a
    E valueOf​(long val)
    Returns ring element associated with specified long
    default E[] valueOf​(long[] elements)
    Converts array of machine integers to ring elements via valueOf(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 Details

    • 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()
      Returns base so that cardinality == base^exponent or null if cardinality is not finite
      Returns:
      base so that cardinality == base^exponent or null if cardinality is not finite

    • perfectPowerExponent

      BigInteger perfectPowerExponent()
      Returns exponent so that cardinality == base^exponent or null if cardinality is not finite
      Returns:
      exponent so that cardinality == base^exponent or null if cardinality is not finite

    • add

      E add​(E a, E b)
      Add two elements
      Parameters:
      a - the first element
      b - 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)
      Returns element + 1
      Parameters:
      element - the element
      Returns:
      element + 1

    • decrement

      default E decrement​(E element)
      Returns element - 1
      Parameters:
      element - the element
      Returns:
      element - 1

    • subtract

      E subtract​(E a, E b)
      Subtracts b from a
      Parameters:
      a - the first element
      b - the second element
      Returns:
      a - b

    • multiply

      E multiply​(E a, E b)
      Multiplies two elements
      Parameters:
      a - the first element
      b - the second element
      Returns:
      a * b

    • multiply

      default E multiply​(E a, long b)
      Multiplies two elements
      Parameters:
      a - the first element
      b - 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 of a.
      Parameters:
      a - the first element (may be destroyed)
      b - the second element
      Returns:
      a + b

    • subtractMutable

      default E subtractMutable​(E a, E b)
      Subtracts b from a and destroys the initial content of a
      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 of a
      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 of element
      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 if element < 0, 0 if element == 0 and 1 if element > 0, where comparison is specified by Comparator.compare(Object, Object)
      Parameters:
      element - the element
      Returns:
      -1 if element < 0, 0 if element == 0 and 1 otherwise

    • abs

      default E abs​(E el)
      Returns the abs value of element (no copy)

    • max

      default E max​(E a, E b)
      Returns the max value (no copy)

    • min

      default E min​(E a, E b)
      Returns the min value (no copy)

    • divideAndRemainder

      E[] divideAndRemainder​(E dividend, E divider)
      Returns quotient and remainder of dividend / divider
      Parameters:
      dividend - the dividend
      divider - the divider
      Returns:
      {quotient, remainder}

    • quotient

      default E quotient​(E dividend, E divider)
      Returns the quotient of dividend / divider
      Parameters:
      dividend - the dividend
      divider - the divider
      Returns:
      the quotient of dividend / divider

    • remainder

      default E remainder​(E dividend, E divider)
      Returns the remainder of dividend / divider
      Parameters:
      dividend - the dividend
      divider - the divider
      Returns:
      the remainder of dividend / divider

    • divideOrNull

      default E divideOrNull​(E dividend, E divider)
      Divides dividend by divider or returns null if exact division is not possible
      Parameters:
      dividend - the dividend
      divider - the divider
      Returns:
      dividend / divider or null if exact division is not possible

    • divideExact

      default E divideExact​(E dividend, E divider)
      Divides dividend by divider or throws ArithmeticException if exact division is not possible
      Parameters:
      dividend - the dividend
      divider - the divider
      Returns:
      dividend / divider
      Throws:
      ArithmeticException - if exact division is not possible

    • divideExactMutable

      default E divideExactMutable​(E dividend, E divider)
      Internal API

    • reciprocal

      E reciprocal​(E element)
      Gives the inverse element element ^ (-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 element
      b - the second element
      Returns:
      gcd

    • extendedGCD

      default E[] extendedGCD​(E a, E b)
      Returns array of [gcd(a,b), s, t] such that s * 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 that s * 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 that s * 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 element
      b - 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 specified long
      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 via valueOf(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)
      Applies valueOf(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 length
      n - 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 length
      n - 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 array
      b - the second element of array
      Returns:
      array {a,b}

    • createArray

      default E[] createArray​(E a, E b, E c)
      Creates generic array of {a, b, c}

    • 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)
      Returns base in a power of exponent (non negative)
      Parameters:
      base - base
      exponent - exponent (non negative)
      Returns:
      base in a power of exponent

    • pow

      default E pow​(E base, long exponent)
      Returns base in a power of exponent (non negative)
      Parameters:
      base - base
      exponent - exponent (non negative)
      Returns:
      base in a power of exponent

    • pow

      default E pow​(E base, BigInteger exponent)
      Returns base in a power of exponent (non negative)
      Parameters:
      base - base
      exponent - exponent (non negative)
      Returns:
      base in a power of exponent

    • factorial

      default E factorial​(long num)
      Gives a product of valueOf(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)
      Specified by:
      iterator in interface Iterable<E>

    • 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

    • parse

      default E parse​(String string)
      Parse string into ring element
      Specified by:
      parse in interface IParser<E>
      Parameters:
      string - string
      Returns:
      ring element
      See Also:
      Coder