Ring (math 2.1.0 API)

All Superinterfaces:

Representable, RepresentationRestorer, StandaloneRepresentable, Structure

All Known Subinterfaces:

Field

All Known Implementing Classes:

BooleanStructure, ExtensionField, IntegerRing, PolynomialRing, ProductRing, Zn, Zp
```
public interface Ring
extends Structure, RepresentationRestorer
```
An algebraic ring with 1.

Method Summary

All Methods Instance Methods Abstract Methods Default Methods
Modifier and Type	Method and Description
`default RingGroup`	`asAdditiveGroup()` Returns an object representing the additive group of this ring.
`default RingGroup`	`asUnitGroup()` Returns an object representing the (multiplicative) unit group of this ring.
`double`	`estimateCostInvPerOp()` Estimates the number of inversions that can be done per group operation for the same cost.
`double`	`estimateCostNegPerOp()` Estimates the number of negations (additive inversions) that can be done per group operation for the same cost.
`default java.util.ArrayList<RingElement>`	`extendedEuclideanAlgorithm(java.util.List<RingElement> elements)` This function executes the extended euclidean algorithm of the passed elements.
`default RingElement[]`	`extendedEuclideanAlgorithm(RingElement a, RingElement b)` This function executes the extended euclidean algorithm for the elements a and b.
`java.math.BigInteger`	`getCharacteristic()` Returns the characteristic of the ring.
`RingElement`	`getElement(java.math.BigInteger i)` Maps the integer i into this ring \(R\), such that this map is a ring homomorphism \(\mathbb{Z}_{\text{getCharacteristic()}} \rightarrow R\).
`default RingElement`	`getElement(long i)` Maps the integer i into this ring \(R\), such that this map is a ring homomorphism \(\mathbb{Z}_{\text{getCharacteristic()}} \rightarrow R\).
`RingElement`	`getOneElement()` Returns the multiplicative neutral element of this ring.
`RingElement`	`getUniformlyRandomElement()` Returns an element of this structure that is drawn uniformly at random using a cryptographically strong RNG.
`default RingElementVector`	`getUniformlyRandomElements(int n)` Returns n elements of this structure that are drawn uniformly and independently at random using a cryptographically strong RNG.
`default RingElement`	`getUniformlyRandomNonzeroElement()` Generates a nonzero element from this ring uniformly at random using a cryptographically strong RNG.
`default RingElementVector`	`getUniformlyRandomNonzeroElements(int n)` Generates n nonzero elements from this ring uniformly and independently at random using a cryptographically strong RNG.
`default RingElement`	`getUniformlyRandomUnit()` Generates an invertible element from this ring uniformly at random using a cryptographically strong RNG.
`default RingElementVector`	`getUniformlyRandomUnits(int n)` Generates n invertible elements from this ring uniformly and independently at random using a cryptographically strong RNG.
`RingElement`	`getZeroElement()` Returns the additive neutral element of this ring.
`boolean`	`isCommutative()` Returns true if this ring is known to be commutative.
`RingElement`	`restoreElement(Representation repr)` Creates an element of this structure from its representation.
`default java.lang.Object`	`restoreFromRepresentation(java.lang.reflect.Type type, Representation repr)` Takes a representation and creates an object of the given type from it if the type is supported by the restorer.
`default RingElementVector`	`restoreVector(Representation repr)` Restores a `RingElementVector` containing ring elements from this `Ring` from a `Representation` of that vector.
`java.math.BigInteger`	`sizeUnitGroup()` Returns the number of units in this ring.

Methods inherited from interface org.cryptimeleon.math.structures.Structure
getUniqueByteLength, hasPrimeSize, size

Methods inherited from interface org.cryptimeleon.math.serialization.Representable
getRepresentation

- Method Detail
  - asAdditiveGroup
```
default RingGroup asAdditiveGroup()
```
    Returns an object representing the additive group of this ring.
  - asUnitGroup
```
default RingGroup asUnitGroup()
```
    Returns an object representing the (multiplicative) unit group of this ring.
  - sizeUnitGroup
```
java.math.BigInteger sizeUnitGroup()
                            throws java.lang.UnsupportedOperationException
```
    Returns the number of units in this ring.
    
    Returns:
    
    size of the unit group or null if infinite
    
    Throws:
    
    java.lang.UnsupportedOperationException - if size is unknown or is computationally too expensive to compute
  - getZeroElement
```
RingElement getZeroElement()
```
    Returns the additive neutral element of this ring.
  - getOneElement
```
RingElement getOneElement()
```
    Returns the multiplicative neutral element of this ring.
  - restoreElement
```
RingElement restoreElement(Representation repr)
```
    Description copied from interface: Structure
    
    Creates an element of this structure from its representation.
    
    Specified by:
    
    restoreElement in interface Structure
    
    Parameters:
    
    repr - the Representation returned by Representable.getRepresentation()
    
    Returns:
    
    the decoded element corresponding to the representation
  - restoreVector
```
default RingElementVector restoreVector(Representation repr)
```
    Restores a RingElementVector containing ring elements from this Ring from a Representation of that vector.
    
    Parameters:
    
    repr - a representation of a RingElementVector (obtained via RingElementVector.getRepresentation()).
  - restoreFromRepresentation
```
default java.lang.Object restoreFromRepresentation(java.lang.reflect.Type type,
                                                   Representation repr)
```
    Description copied from interface: RepresentationRestorer
    
    Takes a representation and creates an object of the given type from it if the type is supported by the restorer.
    
    Specified by:
    
    restoreFromRepresentation in interface RepresentationRestorer
    
    Parameters:
    
    type - tells the restorer which type the restored object should have
    
    repr - the representation to restore the object from
    
    Returns:
    
    the restored object
  - getUniformlyRandomElement
```
RingElement getUniformlyRandomElement()
                               throws java.lang.UnsupportedOperationException
```
    Description copied from interface: Structure
    
    Returns an element of this structure that is drawn uniformly at random using a cryptographically strong RNG.
    
    Specified by:
    
    getUniformlyRandomElement in interface Structure
    
    Throws:
    
    java.lang.UnsupportedOperationException - if the operation is not supported
  - getUniformlyRandomElements
```
default RingElementVector getUniformlyRandomElements(int n)
                                              throws java.lang.UnsupportedOperationException
```
    Description copied from interface: Structure
    
    Returns n elements of this structure that are drawn uniformly and independently at random using a cryptographically strong RNG.
    
    Specified by:
    
    getUniformlyRandomElements in interface Structure
    
    Throws:
    
    java.lang.UnsupportedOperationException - if the operation is not supported
  - getUniformlyRandomUnit
```
default RingElement getUniformlyRandomUnit()
                                    throws java.lang.UnsupportedOperationException
```
    Generates an invertible element from this ring uniformly at random using a cryptographically strong RNG.
    The default implementation generates random ring elements until it hits a unit. Implementors should override if this is not feasible or if there is a better way!
    
    Throws:
    
    java.lang.UnsupportedOperationException - if the ring does not support this method
  - getUniformlyRandomUnits
```
default RingElementVector getUniformlyRandomUnits(int n)
                                           throws java.lang.UnsupportedOperationException
```
    Generates n invertible elements from this ring uniformly and independently at random using a cryptographically strong RNG.
    The default implementation generates random ring elements until it hits a unit. Implementors should override if this is not feasible or if there is a better way!
    
    Throws:
    
    java.lang.UnsupportedOperationException - if the ring does not support this method
  - getUniformlyRandomNonzeroElement
```
default RingElement getUniformlyRandomNonzeroElement()
```
    Generates a nonzero element from this ring uniformly at random using a cryptographically strong RNG.
    
    Throws:
    
    java.lang.UnsupportedOperationException - if the ring does not support this method
  - getUniformlyRandomNonzeroElements
```
default RingElementVector getUniformlyRandomNonzeroElements(int n)
```
    Generates n nonzero elements from this ring uniformly and independently at random using a cryptographically strong RNG.
    
    Throws:
    
    java.lang.UnsupportedOperationException - if the ring does not support this method
  - getCharacteristic
```
java.math.BigInteger getCharacteristic()
                                throws java.lang.UnsupportedOperationException
```
    Returns the characteristic of the ring.
    The characteristic of a ring is defined to be the number n such that there is a ring homomorphism from Zn to the ring.
    
    Throws:
    
    java.lang.UnsupportedOperationException - if unknown
  - getElement
```
RingElement getElement(java.math.BigInteger i)
```
    Maps the integer i into this ring \(R\), such that this map is a ring homomorphism \(\mathbb{Z}_{\text{getCharacteristic()}} \rightarrow R\).
    
    Parameters:
    
    i - the integer to map
    
    Returns:
    
    an element of the ring
  - getElement
```
default RingElement getElement(long i)
```
    Maps the integer i into this ring \(R\), such that this map is a ring homomorphism \(\mathbb{Z}_{\text{getCharacteristic()}} \rightarrow R\).
    
    Parameters:
    
    i - the integer to map
    
    Returns:
    
    an element of the ring
  - extendedEuclideanAlgorithm
```
default RingElement[] extendedEuclideanAlgorithm(RingElement a,
                                                 RingElement b)
```
    This function executes the extended euclidean algorithm for the elements a and b.
    Specifically, it computes an array \([x, y, gcd(a,b)]\) such that \(ax+by=gcd(a,b)\).
    The gcd(a,b) is an element such that
    - c divides a
    - c divides b implies that c divides gcd(a,b).
    (the result is not unique - they may vary by a unit factor)
    This algorithm only works on euclidean domains, i.e. the RingElement in this ring must implement divideWithRemainder.
    Parameters:
    
    a - First argument to the extended euclidean algorithm.
    
    b - Second argument to the extended euclidean algorithm.
    
    Returns:
    
    [x, y, gcd(a,b)]
  - extendedEuclideanAlgorithm
```
default java.util.ArrayList<RingElement> extendedEuclideanAlgorithm(java.util.List<RingElement> elements)
```
    This function executes the extended euclidean algorithm of the passed elements.
    Specifically, it computes an array [x[0], x[1], ..., x[n-1], gcd(elements)] such that gcd(elements)=elements[0]*x[0]+elements[1]*x[1]+...+elements[n-1]*x[n-1].
    The gcd(elements) is an element such that
    - c divides all elements implies that c divides gcd(elements).
    (the result is not unique - they may vary by a unit factor)
    This algorithm only works on euclidean domains i.e. the RingElement in this ring must implement divideWithRemainder.
    Parameters:
    
    elements - List of elements to apply the extended euclidean algorithm to
    
    Returns:
    
    an array with coefficients and the gcd: [x[0], x[1], ..., x[n-1], gcd(elements)]
  - estimateCostInvPerOp
```
double estimateCostInvPerOp()
```
    Estimates the number of inversions that can be done per group operation for the same cost. For example, 2 would mean that an inversion costs half as much as a group operation, on average.
    
    Returns:
    
    estimated number of inversions that can be done per group operation for the same cost
  - estimateCostNegPerOp
```
double estimateCostNegPerOp()
```
    Estimates the number of negations (additive inversions) that can be done per group operation for the same cost. For example, 2 would mean that a negation costs half as much as a group operation, on average.
    
    Returns:
    
    estimated number of inversions that can be done per group operation for the same cost
  - isCommutative
```
boolean isCommutative()
```
    Returns true if this ring is known to be commutative.

Interface Ring

Method Summary

Methods inherited from interface org.cryptimeleon.math.structures.Structure

Methods inherited from interface org.cryptimeleon.math.serialization.Representable

Method Detail

asAdditiveGroup

asUnitGroup

sizeUnitGroup

getZeroElement

getOneElement

restoreElement

restoreVector

restoreFromRepresentation

getUniformlyRandomElement

getUniformlyRandomElements

getUniformlyRandomUnit

getUniformlyRandomUnits

getUniformlyRandomNonzeroElement

getUniformlyRandomNonzeroElements

getCharacteristic

getElement

getElement

extendedEuclideanAlgorithm

extendedEuclideanAlgorithm

estimateCostInvPerOp

estimateCostNegPerOp

isCommutative