GroupElement (math 2.1.0 API)

All Superinterfaces:

Element, Representable, UniqueByteRepresentable

All Known Implementing Classes:

BasicGroupElement, DebugGroupElement, LazyGroupElement, ProductGroupElement, RingGroup.RingGroupElement
```
public interface GroupElement
extends Element, UniqueByteRepresentable
```
Immutable objects representing elements of a group.
Potential calls here may return immediately and not block. For example, g.op(h) may immediately return an object representing the result of the group operation applied to g and h. This object is usable as such. Internally, however, the actual computation of the group operation may be deferred until the value is really needed. This has performance advantages, for example, we can use multi-exponentiation algorithms for computations of values like g.pow(x).op(h.pow(y)).
You can (but don't have to) call compute() on a group element. This will start computing its actual value asynchronously in the background.
Example (ElGamal encryption):
```
 c0 = g.pow(r).compute(); // will return immediately, but compute g^r in the background.
 c1 = h.pow(r).op(m).compute(); // will also start computing (in parallel)

 c0.getRepresentation(); // will block until the value of c0 is ready.
 c1.getRepresentation(); // will block until the value of c1 is ready.
 
```
Without the compute() calls, the example still produces the same output, but c0 and c1 will be computed sequentially.
Implementations must properly implement equals() and hashCode().

Method Summary

All Methods Instance Methods Abstract Methods Default Methods
Modifier and Type	Method and Description
`GroupElement`	`compute()` Hint that the concrete value of this GroupElement will be accessed soon (e.g., via `getRepresentation()` or `equals()`).
`GroupElement`	`computeSync()` Will compute stuff synchronously (this call blocks) so that the next call requiring the concrete value of this group element can immediately retrieve it.
`default GroupElementConstantExpr`	`expr()` Returns a `GroupElementExpression` containing exactly this group element.
`Group`	`getStructure()` Returns the `Structure` that this `Element` belongs to.
`GroupElement`	`inv()` Calculates the inverse of this group element.
`boolean`	`isComputed()` Returns true if a concrete value has already been computed.
`default GroupEqualityExpr`	`isEqualTo(GroupElement other)` Returns an expression of the form "this == other".
`default GroupEqualityExpr`	`isEqualTo(GroupElementExpression expr)` Returns an expression of the form "this == expr".
`default GroupEqualityExpr`	`isEqualTo(java.lang.String expr)` Returns an expression of the form "this == expr".
`default boolean`	`isNeutralElement()` Returns true iff this is the neutral element of the group.
`GroupElement`	`op(Element e)` Calculates the result of `this.op(e)`.
`default GroupElementExpression`	`op(GroupElementExpression e)`
`default GroupElementExpression`	`op(java.lang.String variable)`
`GroupElement`	`pow(java.math.BigInteger exponent)` Calculates the result of applying the group operation k times.
`default GroupElementExpression`	`pow(ExponentExpr exponent)`
`default GroupElement`	`pow(long k)` Calculates the result of applying the group operation k times.
`default GroupElement`	`pow(RingElement k)` Calculates the result of applying the group operation k times.
`default GroupElementExpression`	`pow(java.lang.String variable)`
`default GroupElementVector`	`pow(Vector<? extends RingElement> exponents)` Computes vector `(g.pow(exponents[0]), g.pow(exponents[1]), ...)`.
`default GroupElement`	`pow(Zn.ZnElement k)` Calculates the result of applying the group operation k times.
`default GroupElement`	`precomputePow()` Advises the `GroupElement` to prepare it for later `pow()` calls.
`GroupElement`	`precomputePow(int windowSize)` Advises the `GroupElement` to prepare it for later `pow()` calls.
`default GroupElement`	`square()` Computes `this.op(this)`.

Methods inherited from interface org.cryptimeleon.math.structures.Element
equals, hashCode

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

Methods inherited from interface org.cryptimeleon.math.hash.UniqueByteRepresentable
getUniqueByteRepresentation, updateAccumulator

- Method Detail
  - getStructure
```
Group getStructure()
```
    Description copied from interface: Element
    
    Returns the Structure that this Element belongs to.
    
    Specified by:
    
    getStructure in interface Element
  - inv
```
GroupElement inv()
```
    Calculates the inverse of this group element.
    
    Returns:
    
    an element x such that x.op(this).equals(getStructure().getNeutralElement())
  - op
```
GroupElement op(Element e)
         throws java.lang.IllegalArgumentException
```
    Calculates the result of this.op(e).
    
    Parameters:
    
    e - right hand side of the operation
    
    Returns:
    
    the element resulting from the group operation
    
    Throws:
    
    java.lang.IllegalArgumentException - if e is of the wrong type
  - op
```
default GroupElementExpression op(GroupElementExpression e)
```
  - op
```
default GroupElementExpression op(java.lang.String variable)
```
  - square
```
default GroupElement square()
```
    Computes this.op(this).
    Useful if this group allows squaring to be more efficiently implemented than general exponentiation as is the case for elliptic curves.
  - pow
```
GroupElement pow(java.math.BigInteger exponent)
```
    Calculates the result of applying the group operation k times. i.e. it computes k*this (additive group) or this^k (multiplicative group). For negative exponents k, computes this.inv().pow(-k).
  - pow
```
default GroupElement pow(Zn.ZnElement k)
```
    Calculates the result of applying the group operation k times. Note that this is only well-defined if k is from Zn, such that getStructure().size() divides n.
  - pow
```
default GroupElement pow(RingElement k)
```
    Calculates the result of applying the group operation k times. This is only well-defined if this.getStructure().size() divides k.getStructure().getCharacteristic() and k.asInteger() doesn't throw an exception.
  - pow
```
default GroupElement pow(long k)
```
    Calculates the result of applying the group operation k times. i.e. it computes k*this (additive group) or this^k (multiplicative group). For negative exponents k, computes this.inv().pow(-k).
    The caller should be aware that usually, exponents for large groups will not usually fit into a long value (use pow(BigInteger) or pow(ZnElement) if your exponent is large).
  - pow
```
default GroupElementVector pow(Vector<? extends RingElement> exponents)
```
    Computes vector (g.pow(exponents[0]), g.pow(exponents[1]), ...).
    
    Parameters:
    
    exponents - the exponents to use
    
    Returns:
    
    (g.pow(exponents[0]), g.pow(exponents[1]), ...)
  - pow
```
default GroupElementExpression pow(ExponentExpr exponent)
```
  - pow
```
default GroupElementExpression pow(java.lang.String variable)
```
  - isNeutralElement
```
default boolean isNeutralElement()
```
    Returns true iff this is the neutral element of the group.
  - expr
```
default GroupElementConstantExpr expr()
```
    Returns a GroupElementExpression containing exactly this group element.
  - isEqualTo
```
default GroupEqualityExpr isEqualTo(GroupElementExpression expr)
```
    Returns an expression of the form "this == expr". This is meant to write down an expression, usually only useful if you want to express something that depends on variables that become known later. If you just want to compare two GroupElements, just use Element.equals(Object).
    
    Parameters:
    
    expr - an expression to compare this group element to
    
    Returns:
    
    an expression the evaluates to true (for some variable instantiation) if this is equal to expr.
  - isEqualTo
```
default GroupEqualityExpr isEqualTo(java.lang.String expr)
```
    Returns an expression of the form "this == expr". This is meant to write down an expression, usually only useful if you want to express something that depends on variables that become known later. If you just want to compare two GroupElements, just use Element.equals(Object).
    
    Parameters:
    
    expr - an expression to compare this group element to
    
    Returns:
    
    an expression the evaluates to true (for some variable instantiation) if this is equal to expr.
  - isEqualTo
```
default GroupEqualityExpr isEqualTo(GroupElement other)
```
    Returns an expression of the form "this == other". This is meant to write down an expression, usually only useful if you want to express something that depends on variables that become known later. If you just want to compare two GroupElements, just use Element.equals(Object).
    
    Parameters:
    
    other - another group element to compare this group element to
    
    Returns:
    
    an expression the evaluates to true iff this.equals(other).
  - precomputePow
```
default GroupElement precomputePow()
```
    Advises the GroupElement to prepare it for later pow() calls. This will take some time and should only be done ahead of time. That is, the usual usage pattern should be:
```
 //Setting up your encryption scheme (or whatever)
 GroupElement g = group.getUniformlyRandomElement().precomputePow();
 //Then (maybe even multiple) future calls of
 GroupElement encrypt(GroupElement m) {
     return m.op(g.pow(sk)).compute();
 }
 
```
    Don't use g.precomputePow().pow(x).compute(); unless you're planning to do more exponentiations of g in the future. Uses a reasonable default for the memory consumed by this. Use precomputePow(int) to customize.
    Returns:
    
    the same object (for chaining calls)
  - precomputePow
```
GroupElement precomputePow(int windowSize)
```
    Advises the GroupElement to prepare it for later pow() calls. This will take some time and should only be done ahead of time. That is, the usual usage pattern should be:
```
 //Setting up your encryption scheme (or whatever)
 GroupElement g = group.getUniformlyRandomElement().precomputePow();
 //Then (maybe even multiple) future calls of
 GroupElement encrypt(GroupElement m) {
     return m.op(g.pow(sk)).compute();
 }
 
```
    Don't use g.precomputePow().pow(x).compute(); unless you're planning to do more exponentiations of g in the future.
    Parameters:
    
    windowSize - an indicator for how much memory you're willing to invest. Precomputation will take up space of roughly 2^(windowSize) group elements.
    
    Returns:
    
    the same object (for chaining calls)
  - compute
```
GroupElement compute()
```
    Hint that the concrete value of this GroupElement will be accessed soon (e.g., via getRepresentation() or equals()). Will start computing stuff in the background.
    
    Returns:
    
    the same object (for chaining calls)
  - computeSync
```
GroupElement computeSync()
```
    Will compute stuff synchronously (this call blocks) so that the next call requiring the concrete value of this group element can immediately retrieve it. For designers of cryptographic schemes, were should be no reason to call this. Instead, use compute() which does the same, but asynchronously (i.e. concurrently).
    
    Returns:
    
    the same object (for chaining calls)
  - isComputed
```
boolean isComputed()
```
    Returns true if a concrete value has already been computed. No need to call this outside of upb.crypto.math, it's meant to allow for optimizations.

Interface GroupElement

Method Summary

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

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

Methods inherited from interface org.cryptimeleon.math.hash.UniqueByteRepresentable

Method Detail

getStructure

inv

op

op

op

square

pow

pow

pow

pow

pow

pow

pow

isNeutralElement

expr

isEqualTo

isEqualTo

isEqualTo

precomputePow

precomputePow

compute

computeSync

isComputed