mpyc.fingroups
index
github.com/lschoe/mpyc/blob/v0.11/mpyc/fingroups.py

This module supports several types of finite groups.
 
A finite group is a set of group elements together with a group operation.
The group operation is a binary operation, usually written multiplicatively
(optionally, the group operation can be written additively).
 
The default Python operators to manipulate group elements are the (binary)
operator @ for the group operation, the (unary) operator ~ for inversion of
group elements, and the (binary) operator ^ for repeated application of
the group operation. The alternative Python operators used for additive and
multiplicative notation are:
 
    - default:         a @ b,    ~a,    a^n    (a^-1 = ~a)
    - additive:        a + b,    -a,    n*a    (-1*a = -a)
    - multiplicative:  a * b,   1/a,    a**n   (a**-1 = 1/a)
 
for arbitrary group elements a, b, and integer n.
 
Six types of groups are currently supported, aimed mainly at applications
in cryptography:
 
    - symmetric groups of any degree n (n>=0)
    - quadratic residue groups modulo a safe prime
    - Schnorr groups (prime-order subgroups of the multiplicative group of a finite field)
    - elliptic curve groups (Edwards curves, a Koblitz curve, and Barreto-Naehrig curves)
    - hyperelliptic curve groups, mainly of genus 2 and 3
    - class groups of imaginary quadratic fields
 
The structure of most of these groups will be trivial, preferably cyclic or even
of prime order. Where applicable, a generator of the group (or a sufficiently
large subgroup) is provided to accommodate discrete log and Diffie-Hellman
hardness assumptions.

 
Modules
       
decimal
functools
math
random

 
Classes
       
builtins.object
FiniteGroupElement
ClassGroupForm
EllipticCurvePoint
EdwardsCurvePoint
EdwardsAffine
EdwardsExtended
EdwardsProjective
WeierstrassCurvePoint
WeierstrassAffine
WeierstrassJacobian
WeierstrassProjective
HyperellipticCurveDivisor
HCDivisorCL
QuadraticResidue
SchnorrGroupElement
SymmetricGroupElement

 
class ClassGroupForm(FiniteGroupElement)
    ClassGroupForm(value=None, check=True)
 
Common base class for class groups of imaginary quadratic fields.
 
Represented by primitive positive definite forms (a,b,c) of discriminant D<0.
That is, all forms (a,b,c) with D=b^2-4ac<0 satisfying gcd(a,b,c)=1 and a>0.
 
 
Method resolution order:
ClassGroupForm
FiniteGroupElement
builtins.object

Methods defined here:
__getitem__(self, key)
__init__(self, value=None, check=True)
Create a binary quadratic form (a,b,c).
 
Invariant: form (a,b,c) is reduced.

Class methods defined here:
decode(M, Z)
Decode message from given group elements.
encode(m)
Encode message m in the first coefficient of a form.
equality(f1, f2, /)
"Test equality of (reduced) forms f1 and f2.
inversion(f, /)
Inverse 1/f of form f.
operation(f1, f2, /)
Compose (and reduce) form f1 with form f2.
operation2(f, /)
Compose (and reduce) form f with itself.

Data and other attributes defined here:
bit_length = None
gap = None
is_abelian = True
is_multiplicative = True
order = None

Methods inherited from FiniteGroupElement:
__add__(self, other)
__eq__(self, other)
Return self==value.
__hash__(self)
Make finite group elements hashable (e.g., for LRU caching).
__invert__(self)
__matmul__(self, other)
__mul__(self, other)
__neg__(self)
__pow__(self, other)
__repr__(self)
Return repr(self).
__rmul__(self, other)
__rtruediv__(self, other)
__sub__(self, other)
__truediv__(self, other)
__xor__(self, other)
inverse(self)
For convenience.

Static methods inherited from FiniteGroupElement:
repeat(a, n)
Return nth @-power of a (written a^n), for any integer n.

Data descriptors inherited from FiniteGroupElement:
value

Data and other attributes inherited from FiniteGroupElement:
generator = None
identity = None
is_additive = False
is_cyclic = None

 
class EdwardsAffine(EdwardsCurvePoint)
    EdwardsAffine(value=None, check=True)
 
Edwards curves with affine coordinates.
 
 
Method resolution order:
EdwardsAffine
EdwardsCurvePoint
EllipticCurvePoint
FiniteGroupElement
builtins.object

Methods defined here:
normalize(self)
Convert to unique (affine) representation.

Class methods defined here:
equality(pt1, pt2, /)
Test equality of points pt1 and pt2.
inversion(pt, /)
Invert Edwards point using affine coordinates.
operation(pt1, pt2, /)
Add Edwards points using affine coordinates (projective with z=1).

Data and other attributes defined here:
oblivious = True

Methods inherited from EdwardsCurvePoint:
__init__(self, value=None, check=True)
Initialize self.  See help(type(self)) for accurate signature.

Class methods inherited from EdwardsCurvePoint:
ysquared(x)
Return value of y^2 as a function of x, for a point (x, y) on the curve.

Data and other attributes inherited from EdwardsCurvePoint:
a = None
d = None

Methods inherited from EllipticCurvePoint:
__getitem__(self, key)

Class methods inherited from EllipticCurvePoint:
decode(M, Z)
Decode message from given group elements.
encode(m)
Encode message m in x-coordinate of a point on the curve.

Readonly properties inherited from EllipticCurvePoint:
x
y
z

Data and other attributes inherited from EllipticCurvePoint:
gap = None
is_abelian = True
is_additive = True
is_multiplicative = False

Methods inherited from FiniteGroupElement:
__add__(self, other)
__eq__(self, other)
Return self==value.
__hash__(self)
Make finite group elements hashable (e.g., for LRU caching).
__invert__(self)
__matmul__(self, other)
__mul__(self, other)
__neg__(self)
__pow__(self, other)
__repr__(self)
Return repr(self).
__rmul__(self, other)
__rtruediv__(self, other)
__sub__(self, other)
__truediv__(self, other)
__xor__(self, other)
inverse(self)
For convenience.

Class methods inherited from FiniteGroupElement:
operation2(a, /)
Return a @ a.

Static methods inherited from FiniteGroupElement:
repeat(a, n)
Return nth @-power of a (written a^n), for any integer n.

Data descriptors inherited from FiniteGroupElement:
value

Data and other attributes inherited from FiniteGroupElement:
generator = None
identity = None
is_cyclic = None
order = None

 
class EdwardsCurvePoint(EllipticCurvePoint)
    EdwardsCurvePoint(value=None, check=True)
 
Common base class for (twisted) Edwards curves.
 
 
Method resolution order:
EdwardsCurvePoint
EllipticCurvePoint
FiniteGroupElement
builtins.object

Methods defined here:
__init__(self, value=None, check=True)
Initialize self.  See help(type(self)) for accurate signature.

Class methods defined here:
ysquared(x)
Return value of y^2 as a function of x, for a point (x, y) on the curve.

Data and other attributes defined here:
a = None
d = None

Methods inherited from EllipticCurvePoint:
__getitem__(self, key)
normalize(self)
Convert to unique (affine) representation.

Class methods inherited from EllipticCurvePoint:
decode(M, Z)
Decode message from given group elements.
encode(m)
Encode message m in x-coordinate of a point on the curve.
equality(pt1, pt2, /)
Test equality of points pt1 and pt2.

Readonly properties inherited from EllipticCurvePoint:
x
y
z

Data and other attributes inherited from EllipticCurvePoint:
gap = None
is_abelian = True
is_additive = True
is_multiplicative = False
oblivious = None

Methods inherited from FiniteGroupElement:
__add__(self, other)
__eq__(self, other)
Return self==value.
__hash__(self)
Make finite group elements hashable (e.g., for LRU caching).
__invert__(self)
__matmul__(self, other)
__mul__(self, other)
__neg__(self)
__pow__(self, other)
__repr__(self)
Return repr(self).
__rmul__(self, other)
__rtruediv__(self, other)
__sub__(self, other)
__truediv__(self, other)
__xor__(self, other)
inverse(self)
For convenience.

Class methods inherited from FiniteGroupElement:
inversion(a, /)
Return @-inverse of a (written ~a).
operation(a, b, /)
Return a @ b.
operation2(a, /)
Return a @ a.

Static methods inherited from FiniteGroupElement:
repeat(a, n)
Return nth @-power of a (written a^n), for any integer n.

Data descriptors inherited from FiniteGroupElement:
value

Data and other attributes inherited from FiniteGroupElement:
generator = None
identity = None
is_cyclic = None
order = None

 
class EdwardsExtended(EdwardsCurvePoint)
    EdwardsExtended(value=None, check=True)
 
Edwards curves with extended coordinates.
 
 
Method resolution order:
EdwardsExtended
EdwardsCurvePoint
EllipticCurvePoint
FiniteGroupElement
builtins.object

Methods defined here:
normalize(self)
Convert to unique (affine) representation.

Class methods defined here:
equality(pt1, pt2, /)
Test equality of points pt1 and pt2.
inversion(pt, /)
Invert (twisted a=-1) Edwards point in extended projective coordinates.
operation(pt1, pt2, /)
Add (twisted a=-1) Edwards points in extended projective coordinates.
operation2(pt, /)
Doubling (twisted a=-1) Edwards point in extended projective coordinates.

Data and other attributes defined here:
oblivious = True

Methods inherited from EdwardsCurvePoint:
__init__(self, value=None, check=True)
Initialize self.  See help(type(self)) for accurate signature.

Class methods inherited from EdwardsCurvePoint:
ysquared(x)
Return value of y^2 as a function of x, for a point (x, y) on the curve.

Data and other attributes inherited from EdwardsCurvePoint:
a = None
d = None

Methods inherited from EllipticCurvePoint:
__getitem__(self, key)

Class methods inherited from EllipticCurvePoint:
decode(M, Z)
Decode message from given group elements.
encode(m)
Encode message m in x-coordinate of a point on the curve.

Readonly properties inherited from EllipticCurvePoint:
x
y
z

Data and other attributes inherited from EllipticCurvePoint:
gap = None
is_abelian = True
is_additive = True
is_multiplicative = False

Methods inherited from FiniteGroupElement:
__add__(self, other)
__eq__(self, other)
Return self==value.
__hash__(self)
Make finite group elements hashable (e.g., for LRU caching).
__invert__(self)
__matmul__(self, other)
__mul__(self, other)
__neg__(self)
__pow__(self, other)
__repr__(self)
Return repr(self).
__rmul__(self, other)
__rtruediv__(self, other)
__sub__(self, other)
__truediv__(self, other)
__xor__(self, other)
inverse(self)
For convenience.

Static methods inherited from FiniteGroupElement:
repeat(a, n)
Return nth @-power of a (written a^n), for any integer n.

Data descriptors inherited from FiniteGroupElement:
value

Data and other attributes inherited from FiniteGroupElement:
generator = None
identity = None
is_cyclic = None
order = None

 
class EdwardsProjective(EdwardsCurvePoint)
    EdwardsProjective(value=None, check=True)
 
Edwards curves with projective coordinates.
 
 
Method resolution order:
EdwardsProjective
EdwardsCurvePoint
EllipticCurvePoint
FiniteGroupElement
builtins.object

Methods defined here:
normalize(self)
Convert to unique (affine) representation.

Class methods defined here:
equality(pt1, pt2, /)
Test equality of points pt1 and pt2.
inversion(pt, /)
Invert Edwards point with projective coordinates.
operation(pt1, pt2, /)
Add Edwards points with (homogeneous) projective coordinates.

Data and other attributes defined here:
oblivious = True

Methods inherited from EdwardsCurvePoint:
__init__(self, value=None, check=True)
Initialize self.  See help(type(self)) for accurate signature.

Class methods inherited from EdwardsCurvePoint:
ysquared(x)
Return value of y^2 as a function of x, for a point (x, y) on the curve.

Data and other attributes inherited from EdwardsCurvePoint:
a = None
d = None

Methods inherited from EllipticCurvePoint:
__getitem__(self, key)

Class methods inherited from EllipticCurvePoint:
decode(M, Z)
Decode message from given group elements.
encode(m)
Encode message m in x-coordinate of a point on the curve.

Readonly properties inherited from EllipticCurvePoint:
x
y
z

Data and other attributes inherited from EllipticCurvePoint:
gap = None
is_abelian = True
is_additive = True
is_multiplicative = False

Methods inherited from FiniteGroupElement:
__add__(self, other)
__eq__(self, other)
Return self==value.
__hash__(self)
Make finite group elements hashable (e.g., for LRU caching).
__invert__(self)
__matmul__(self, other)
__mul__(self, other)
__neg__(self)
__pow__(self, other)
__repr__(self)
Return repr(self).
__rmul__(self, other)
__rtruediv__(self, other)
__sub__(self, other)
__truediv__(self, other)
__xor__(self, other)
inverse(self)
For convenience.

Class methods inherited from FiniteGroupElement:
operation2(a, /)
Return a @ a.

Static methods inherited from FiniteGroupElement:
repeat(a, n)
Return nth @-power of a (written a^n), for any integer n.

Data descriptors inherited from FiniteGroupElement:
value

Data and other attributes inherited from FiniteGroupElement:
generator = None
identity = None
is_cyclic = None
order = None

 
class EllipticCurvePoint(FiniteGroupElement)
    Common base class for elliptic curve groups.
 
 
Method resolution order:
EllipticCurvePoint
FiniteGroupElement
builtins.object

Methods defined here:
__getitem__(self, key)
normalize(self)
Convert to unique (affine) representation.

Class methods defined here:
decode(M, Z)
Decode message from given group elements.
encode(m)
Encode message m in x-coordinate of a point on the curve.
equality(pt1, pt2, /)
Test equality of points pt1 and pt2.
ysquared(x)
Return value of y^2 as a function of x, for a point (x, y) on the curve.

Readonly properties defined here:
x
y
z

Data and other attributes defined here:
gap = None
is_abelian = True
is_additive = True
is_multiplicative = False
oblivious = None

Methods inherited from FiniteGroupElement:
__add__(self, other)
__eq__(self, other)
Return self==value.
__hash__(self)
Make finite group elements hashable (e.g., for LRU caching).
__invert__(self)
__matmul__(self, other)
__mul__(self, other)
__neg__(self)
__pow__(self, other)
__repr__(self)
Return repr(self).
__rmul__(self, other)
__rtruediv__(self, other)
__sub__(self, other)
__truediv__(self, other)
__xor__(self, other)
inverse(self)
For convenience.

Class methods inherited from FiniteGroupElement:
inversion(a, /)
Return @-inverse of a (written ~a).
operation(a, b, /)
Return a @ b.
operation2(a, /)
Return a @ a.

Static methods inherited from FiniteGroupElement:
repeat(a, n)
Return nth @-power of a (written a^n), for any integer n.

Data descriptors inherited from FiniteGroupElement:
value

Data and other attributes inherited from FiniteGroupElement:
generator = None
identity = None
is_cyclic = None
order = None

 
class FiniteGroupElement(builtins.object)
    Abstract base class for finite groups.
 
Overview Python operators for group operation, inverse, and repeated operation:
 
    - default notation: @, ~, ^ (matmul, invert, xor).
    - additive notation: +, -, * (add, sub, mul)
    - multiplicative notation: *, 1/ (or, **-1), ** (mul, truediv (or, pow), pow)
 
  Methods defined here:
__add__(self, other)
__eq__(self, other)
Return self==value.
__hash__(self)
Make finite group elements hashable (e.g., for LRU caching).
__invert__(self)
__matmul__(self, other)
__mul__(self, other)
__neg__(self)
__pow__(self, other)
__repr__(self)
Return repr(self).
__rmul__(self, other)
__rtruediv__(self, other)
__sub__(self, other)
__truediv__(self, other)
__xor__(self, other)
inverse(self)
For convenience.

Class methods defined here:
equality(a, b, /)
Return a == b.
inversion(a, /)
Return @-inverse of a (written ~a).
operation(a, b, /)
Return a @ b.
operation2(a, /)
Return a @ a.

Static methods defined here:
repeat(a, n)
Return nth @-power of a (written a^n), for any integer n.

Data descriptors defined here:
value

Data and other attributes defined here:
generator = None
identity = None
is_abelian = None
is_additive = False
is_cyclic = None
is_multiplicative = False
order = None

 
class HCDivisorCL(HyperellipticCurveDivisor)
    HCDivisorCL(value=None, check=True)
 
Costello-Lauter formulas for genus 2.
 
With one exception, only divisors (u,v) with u of full degree 2 are assumed.
Such divisors are represented by a 6-tuple (u1,u0,v1,v0,u1u1,u1u0),
where u(x)=x^2+u1x+u0 and v(x)=v1x+v0.
 
The exception is that the identity (1,0) is also considered,
represented by the 6-tuple (0,0,0,0,0,0).
 
See "Group Law Computations on Jacobians of Hyperelliptic Curves" by Costello and Lauter.
 
 
Method resolution order:
HCDivisorCL
HyperellipticCurveDivisor
FiniteGroupElement
builtins.object

Methods defined here:
__init__(self, value=None, check=True)
Initialize self.  See help(type(self)) for accurate signature.
__repr__(self)
Return repr(self).

Class methods defined here:
decode(M, Z)
Decode message from given group elements.
encode(m)
Encode message m in terms of monic polynomial of divisor.
 
Divisor (u,v) with deg u=2, u(x)=(x+m)^2=x^2+2mx+m^2=0
and deg v=0, v(x)=y, where x=-m and y^2=f(x).
Hence, u[2]=1, u[1]=2m=-2x, u[0]=m^2, v[0]=yfor rational point (x,y).
inversion(D, /)
Inverse -D of divisor D.
operation(D1, D2, /)
Add divisor D1 to D2.
operation2(D, /)
Add divisor D to itself.

Readonly properties defined here:
u
v

Data descriptors defined here:
__dict__
dictionary for instance variables
__weakref__
list of weak references to the object

Data and other attributes defined here:
genus = 2

Methods inherited from HyperellipticCurveDivisor:
__getitem__(self, key)

Class methods inherited from HyperellipticCurveDivisor:
class_number()
Count elements of Jacobian by counting unique Mumford representations (u,v).
equality(D1, D2, /)
Test equality of (reduced) divisors D1 and D2.
ysquared(x)

Data and other attributes inherited from HyperellipticCurveDivisor:
gap = None
is_abelian = True
is_additive = True
is_cyclic = True
is_multiplicative = False

Methods inherited from FiniteGroupElement:
__add__(self, other)
__eq__(self, other)
Return self==value.
__hash__(self)
Make finite group elements hashable (e.g., for LRU caching).
__invert__(self)
__matmul__(self, other)
__mul__(self, other)
__neg__(self)
__pow__(self, other)
__rmul__(self, other)
__rtruediv__(self, other)
__sub__(self, other)
__truediv__(self, other)
__xor__(self, other)
inverse(self)
For convenience.

Static methods inherited from FiniteGroupElement:
repeat(a, n)
Return nth @-power of a (written a^n), for any integer n.

Data descriptors inherited from FiniteGroupElement:
value

Data and other attributes inherited from FiniteGroupElement:
generator = None
identity = None
order = None

 
class HyperellipticCurveDivisor(FiniteGroupElement)
    HyperellipticCurveDivisor(value=None, check=True)
 
Common base class for divisors in Jacobian of a hyperelliptic curve.
 
Arbitrary genus, using (affine) Mumford representation and algorithms from Cantor's 1987 paper.
 
 
Method resolution order:
HyperellipticCurveDivisor
FiniteGroupElement
builtins.object

Methods defined here:
__getitem__(self, key)
__init__(self, value=None, check=True)
Initialize self.  See help(type(self)) for accurate signature.

Class methods defined here:
class_number()
Count elements of Jacobian by counting unique Mumford representations (u,v).
decode(M, Z)
Decode message from given group elements.
encode(m)
Encode message m in constant term of monic polynomial of divisor.
 
Divisor (u,v) with deg u=1, u(x)=0 and deg v=0, v(x)=y, where x=-m and y^2=f(x).
Hence, u[0]=m=-x, u[1]=1, and v[0]=y for rational point (x,y).
equality(D1, D2, /)
Test equality of (reduced) divisors D1 and D2.
inversion(D, /)
Inverse -D of divisor D.
operation(D1, D2, /)
Add divisor D1 to D2.
operation2(D, /)
Add divisor D to itself.
ysquared(x)

Readonly properties defined here:
u
v

Data and other attributes defined here:
gap = None
genus = None
is_abelian = True
is_additive = True
is_cyclic = True
is_multiplicative = False

Methods inherited from FiniteGroupElement:
__add__(self, other)
__eq__(self, other)
Return self==value.
__hash__(self)
Make finite group elements hashable (e.g., for LRU caching).
__invert__(self)
__matmul__(self, other)
__mul__(self, other)
__neg__(self)
__pow__(self, other)
__repr__(self)
Return repr(self).
__rmul__(self, other)
__rtruediv__(self, other)
__sub__(self, other)
__truediv__(self, other)
__xor__(self, other)
inverse(self)
For convenience.

Static methods inherited from FiniteGroupElement:
repeat(a, n)
Return nth @-power of a (written a^n), for any integer n.

Data descriptors inherited from FiniteGroupElement:
value

Data and other attributes inherited from FiniteGroupElement:
generator = None
identity = None
order = None

 
class QuadraticResidue(FiniteGroupElement)
    QuadraticResidue(value=1, check=True)
 
Common base class for groups of quadratic residues modulo an odd prime.
 
Quadratic residues modulo p represented by GF(p)* elements.
 
 
Method resolution order:
QuadraticResidue
FiniteGroupElement
builtins.object

Methods defined here:
__init__(self, value=1, check=True)
Initialize self.  See help(type(self)) for accurate signature.
__int__(self)

Class methods defined here:
decode(M, Z)
Decode message from given group elements.
encode(m)
Encode message m in a quadratic residue.
equality(a, b, /)
Return a == b.
inversion(a, /)
Return @-inverse of a (written ~a).
operation(a, b, /)
Return a @ b.
repeat(a, n)
Return nth @-power of a (written a^n), for any integer n.

Data and other attributes defined here:
gap = None
is_abelian = True
is_cyclic = True
is_multiplicative = True

Methods inherited from FiniteGroupElement:
__add__(self, other)
__eq__(self, other)
Return self==value.
__hash__(self)
Make finite group elements hashable (e.g., for LRU caching).
__invert__(self)
__matmul__(self, other)
__mul__(self, other)
__neg__(self)
__pow__(self, other)
__repr__(self)
Return repr(self).
__rmul__(self, other)
__rtruediv__(self, other)
__sub__(self, other)
__truediv__(self, other)
__xor__(self, other)
inverse(self)
For convenience.

Class methods inherited from FiniteGroupElement:
operation2(a, /)
Return a @ a.

Data descriptors inherited from FiniteGroupElement:
value

Data and other attributes inherited from FiniteGroupElement:
generator = None
identity = None
is_additive = False
order = None

 
class SchnorrGroupElement(FiniteGroupElement)
    SchnorrGroupElement(value=1, check=True)
 
Common base class for prime-order subgroups of the multiplicative group of a finite field.
 
 
Method resolution order:
SchnorrGroupElement
FiniteGroupElement
builtins.object

Methods defined here:
__init__(self, value=1, check=True)
Initialize self.  See help(type(self)) for accurate signature.
__int__(self)

Class methods defined here:
decode(M, Z)
Decode message from given group element.
encode(m)
Encode message m in group element g^m.
equality(a, b, /)
Return a == b.
inversion(a, /)
Return @-inverse of a (written ~a).
operation(a, b, /)
Return a @ b.
repeat(a, n)
Return nth @-power of a (written a^n), for any integer n.

Data and other attributes defined here:
is_abelian = True
is_cyclic = True
is_multiplicative = True

Methods inherited from FiniteGroupElement:
__add__(self, other)
__eq__(self, other)
Return self==value.
__hash__(self)
Make finite group elements hashable (e.g., for LRU caching).
__invert__(self)
__matmul__(self, other)
__mul__(self, other)
__neg__(self)
__pow__(self, other)
__repr__(self)
Return repr(self).
__rmul__(self, other)
__rtruediv__(self, other)
__sub__(self, other)
__truediv__(self, other)
__xor__(self, other)
inverse(self)
For convenience.

Class methods inherited from FiniteGroupElement:
operation2(a, /)
Return a @ a.

Data descriptors inherited from FiniteGroupElement:
value

Data and other attributes inherited from FiniteGroupElement:
generator = None
identity = None
is_additive = False
order = None

 
class SymmetricGroupElement(FiniteGroupElement)
    SymmetricGroupElement(value=None, check=True)
 
Common base class for symmetric groups.
 
Symmetric groups contains all permutations of a fixed length (degree).
Permutations of {0,...,n-1} represented as length-n tuples with unique
entries in {0,...,n-1}, n>=0.
 
 
Method resolution order:
SymmetricGroupElement
FiniteGroupElement
builtins.object

Methods defined here:
__init__(self, value=None, check=True)
Initialize self.  See help(type(self)) for accurate signature.

Class methods defined here:
equality(p, q, /)
Test equality of permutations p and q.
inversion(p, /)
Inverse of permutation p.
operation(p, q, /)
First p then q.

Data and other attributes defined here:
degree = None

Methods inherited from FiniteGroupElement:
__add__(self, other)
__eq__(self, other)
Return self==value.
__hash__(self)
Make finite group elements hashable (e.g., for LRU caching).
__invert__(self)
__matmul__(self, other)
__mul__(self, other)
__neg__(self)
__pow__(self, other)
__repr__(self)
Return repr(self).
__rmul__(self, other)
__rtruediv__(self, other)
__sub__(self, other)
__truediv__(self, other)
__xor__(self, other)
inverse(self)
For convenience.

Class methods inherited from FiniteGroupElement:
operation2(a, /)
Return a @ a.

Static methods inherited from FiniteGroupElement:
repeat(a, n)
Return nth @-power of a (written a^n), for any integer n.

Data descriptors inherited from FiniteGroupElement:
value

Data and other attributes inherited from FiniteGroupElement:
generator = None
identity = None
is_abelian = None
is_additive = False
is_cyclic = None
is_multiplicative = False
order = None

 
class WeierstrassAffine(WeierstrassCurvePoint)
    WeierstrassAffine(value=None, check=True)
 
Short Weierstrass curves with affine coordinates.
 
 
Method resolution order:
WeierstrassAffine
WeierstrassCurvePoint
EllipticCurvePoint
FiniteGroupElement
builtins.object

Methods defined here:
normalize(self)
Convert to unique (affine) representation.

Class methods defined here:
equality(pt1, pt2, /)
Test equality of points pt1 and pt2.
inversion(pt, /)
Invert Weierstrass point with affine coordinates.
operation(pt1, pt2, /)
Add Weierstrass points with affine coordinates.
operation2(pt, /)
Double Weierstrass point with affine coordinates.

Data and other attributes defined here:
oblivious = False

Methods inherited from WeierstrassCurvePoint:
__init__(self, value=None, check=True)
Initialize self.  See help(type(self)) for accurate signature.

Class methods inherited from WeierstrassCurvePoint:
ysquared(x)
Return value of y^2 as a function of x, for a point (x, y) on the curve.

Data and other attributes inherited from WeierstrassCurvePoint:
a = None
b = None

Methods inherited from EllipticCurvePoint:
__getitem__(self, key)

Class methods inherited from EllipticCurvePoint:
decode(M, Z)
Decode message from given group elements.
encode(m)
Encode message m in x-coordinate of a point on the curve.

Readonly properties inherited from EllipticCurvePoint:
x
y
z

Data and other attributes inherited from EllipticCurvePoint:
gap = None
is_abelian = True
is_additive = True
is_multiplicative = False

Methods inherited from FiniteGroupElement:
__add__(self, other)
__eq__(self, other)
Return self==value.
__hash__(self)
Make finite group elements hashable (e.g., for LRU caching).
__invert__(self)
__matmul__(self, other)
__mul__(self, other)
__neg__(self)
__pow__(self, other)
__repr__(self)
Return repr(self).
__rmul__(self, other)
__rtruediv__(self, other)
__sub__(self, other)
__truediv__(self, other)
__xor__(self, other)
inverse(self)
For convenience.

Static methods inherited from FiniteGroupElement:
repeat(a, n)
Return nth @-power of a (written a^n), for any integer n.

Data descriptors inherited from FiniteGroupElement:
value

Data and other attributes inherited from FiniteGroupElement:
generator = None
identity = None
is_cyclic = None
order = None

 
class WeierstrassCurvePoint(EllipticCurvePoint)
    WeierstrassCurvePoint(value=None, check=True)
 
Common base class for (short) Weierstrass curves.
 
 
Method resolution order:
WeierstrassCurvePoint
EllipticCurvePoint
FiniteGroupElement
builtins.object

Methods defined here:
__init__(self, value=None, check=True)
Initialize self.  See help(type(self)) for accurate signature.

Class methods defined here:
ysquared(x)
Return value of y^2 as a function of x, for a point (x, y) on the curve.

Data and other attributes defined here:
a = None
b = None

Methods inherited from EllipticCurvePoint:
__getitem__(self, key)
normalize(self)
Convert to unique (affine) representation.

Class methods inherited from EllipticCurvePoint:
decode(M, Z)
Decode message from given group elements.
encode(m)
Encode message m in x-coordinate of a point on the curve.
equality(pt1, pt2, /)
Test equality of points pt1 and pt2.

Readonly properties inherited from EllipticCurvePoint:
x
y
z

Data and other attributes inherited from EllipticCurvePoint:
gap = None
is_abelian = True
is_additive = True
is_multiplicative = False
oblivious = None

Methods inherited from FiniteGroupElement:
__add__(self, other)
__eq__(self, other)
Return self==value.
__hash__(self)
Make finite group elements hashable (e.g., for LRU caching).
__invert__(self)
__matmul__(self, other)
__mul__(self, other)
__neg__(self)
__pow__(self, other)
__repr__(self)
Return repr(self).
__rmul__(self, other)
__rtruediv__(self, other)
__sub__(self, other)
__truediv__(self, other)
__xor__(self, other)
inverse(self)
For convenience.

Class methods inherited from FiniteGroupElement:
inversion(a, /)
Return @-inverse of a (written ~a).
operation(a, b, /)
Return a @ b.
operation2(a, /)
Return a @ a.

Static methods inherited from FiniteGroupElement:
repeat(a, n)
Return nth @-power of a (written a^n), for any integer n.

Data descriptors inherited from FiniteGroupElement:
value

Data and other attributes inherited from FiniteGroupElement:
generator = None
identity = None
is_cyclic = None
order = None

 
class WeierstrassJacobian(WeierstrassCurvePoint)
    WeierstrassJacobian(value=None, check=True)
 
Short Weierstrass curves with Jacobian coordinates.
 
 
Method resolution order:
WeierstrassJacobian
WeierstrassCurvePoint
EllipticCurvePoint
FiniteGroupElement
builtins.object

Methods defined here:
normalize(self)
Convert to unique (affine) representation.

Class methods defined here:
equality(pt1, pt2, /)
Test equality of points pt1 and pt2.
inversion(pt, /)
Invert Weierstrass point with Jacobian coordinates.
operation(pt1, pt2, /)
Add Weierstrass points with Jacobian coordinates.
operation2(pt, /)
Double Weierstrass point with Jacobian coordinates.

Data and other attributes defined here:
oblivious = False

Methods inherited from WeierstrassCurvePoint:
__init__(self, value=None, check=True)
Initialize self.  See help(type(self)) for accurate signature.

Class methods inherited from WeierstrassCurvePoint:
ysquared(x)
Return value of y^2 as a function of x, for a point (x, y) on the curve.

Data and other attributes inherited from WeierstrassCurvePoint:
a = None
b = None

Methods inherited from EllipticCurvePoint:
__getitem__(self, key)

Class methods inherited from EllipticCurvePoint:
decode(M, Z)
Decode message from given group elements.
encode(m)
Encode message m in x-coordinate of a point on the curve.

Readonly properties inherited from EllipticCurvePoint:
x
y
z

Data and other attributes inherited from EllipticCurvePoint:
gap = None
is_abelian = True
is_additive = True
is_multiplicative = False

Methods inherited from FiniteGroupElement:
__add__(self, other)
__eq__(self, other)
Return self==value.
__hash__(self)
Make finite group elements hashable (e.g., for LRU caching).
__invert__(self)
__matmul__(self, other)
__mul__(self, other)
__neg__(self)
__pow__(self, other)
__repr__(self)
Return repr(self).
__rmul__(self, other)
__rtruediv__(self, other)
__sub__(self, other)
__truediv__(self, other)
__xor__(self, other)
inverse(self)
For convenience.

Static methods inherited from FiniteGroupElement:
repeat(a, n)
Return nth @-power of a (written a^n), for any integer n.

Data descriptors inherited from FiniteGroupElement:
value

Data and other attributes inherited from FiniteGroupElement:
generator = None
identity = None
is_cyclic = None
order = None

 
class WeierstrassProjective(WeierstrassCurvePoint)
    WeierstrassProjective(value=None, check=True)
 
Short Weierstrass curves with projective coordinates.
 
 
Method resolution order:
WeierstrassProjective
WeierstrassCurvePoint
EllipticCurvePoint
FiniteGroupElement
builtins.object

Methods defined here:
normalize(self)
Convert to unique (affine) representation.

Class methods defined here:
equality(pt1, pt2, /)
Test equality of points pt1 and pt2.
inversion(pt, /)
Invert Weierstrass point with projective coordinates.
operation(pt1, pt2, /)
Add Weierstrass points with projective coordinates.
operation2(pt, /)
Double Weierstrass point with projective coordinates.

Data and other attributes defined here:
oblivious = True

Methods inherited from WeierstrassCurvePoint:
__init__(self, value=None, check=True)
Initialize self.  See help(type(self)) for accurate signature.

Class methods inherited from WeierstrassCurvePoint:
ysquared(x)
Return value of y^2 as a function of x, for a point (x, y) on the curve.

Data and other attributes inherited from WeierstrassCurvePoint:
a = None
b = None

Methods inherited from EllipticCurvePoint:
__getitem__(self, key)

Class methods inherited from EllipticCurvePoint:
decode(M, Z)
Decode message from given group elements.
encode(m)
Encode message m in x-coordinate of a point on the curve.

Readonly properties inherited from EllipticCurvePoint:
x
y
z

Data and other attributes inherited from EllipticCurvePoint:
gap = None
is_abelian = True
is_additive = True
is_multiplicative = False

Methods inherited from FiniteGroupElement:
__add__(self, other)
__eq__(self, other)
Return self==value.
__hash__(self)
Make finite group elements hashable (e.g., for LRU caching).
__invert__(self)
__matmul__(self, other)
__mul__(self, other)
__neg__(self)
__pow__(self, other)
__repr__(self)
Return repr(self).
__rmul__(self, other)
__rtruediv__(self, other)
__sub__(self, other)
__truediv__(self, other)
__xor__(self, other)
inverse(self)
For convenience.

Static methods inherited from FiniteGroupElement:
repeat(a, n)
Return nth @-power of a (written a^n), for any integer n.

Data descriptors inherited from FiniteGroupElement:
value

Data and other attributes inherited from FiniteGroupElement:
generator = None
identity = None
is_cyclic = None
order = None

 
Functions
       
ClassGroup(Delta=None, l=None)
Create type for class group, given (bit length l of) discriminant Delta.
 
The following conditions are imposed on discriminant Delta:
 
    - Delta < 0, only supporting class groups of imaginary quadratic field
    - Delta = 1 (mod 4), preferably Delta = 1 (mod 8)
    - -Delta is prime
 
This implies that Delta is a fundamental discriminant.
EllipticCurve(curvename='Ed25519', coordinates=None)
Create elliptic curve type for a selection of built-in curves.
The default coordinates used with these curves are 'affine'.
 
The following Edwards curves and Weierstrass curves are built-in:
 
    - 'Ed25519': see https://en.wikipedia.org/wiki/EdDSA#Ed25519
    - 'Ed448': aka "Goldilocks", see https://en.wikipedia.org/wiki/Curve448
    - 'secp256k1': Bitcoin's Koblitz curve from https://www.secg.org/sec2-v2.pdf
    - 'BN256': Barreto-Naehrig curve, https://eprint.iacr.org/2010/186
    - 'BN256_twist': sextic twist of Barreto-Naehrig curve
 
These curves can be used with 'affine' (default) and 'projective' coordinates.
The Edwards curves can also be used with 'extended' coordinates, and the
Weierstrass curves with 'jacobian' coordinates.
HyperellipticCurve(curvename=None, coordinates=None, p=None, l=None, genus=None)
Create type for hyperelliptic curve group with given parameters.
 
With curvename='kummer1271' the genus-2 curve due to Gaudry and Schost is obtained,
which is defined modulo p=2^127-1, the twelfth Mersenne prime.
 
By default, curvename='DGS', which stands for Dobson, Galbraith, and Smith, who
specified a way to generate random Jacobians together with a ...
 
Alternatively, given p or its bit length l as modulus for the underlying prime field,
a random curve of the specified genus (default 3) will be generated, using the method
of Dobson, Galbraith and Smith (Algorithm 4 from https://eprint.iacr.org/2020/196).
The randomness is seeded with the prime number p.
 
The coordinates used with these curves are 'affine', by default.
Currently, the only alternative coordinates are the Costello--Lauter 'extended' coordinates.
QuadraticResidues(p=None, l=None)
Create type for quadratic residues group given (bit length l of) odd prime modulus p.
 
The group of quadratic residues modulo p is of order n=(p-1)/2.
Given bit length l>2, p will be chosen such that n is also an odd prime.
If l=2, the only possibility is p=3, hence n=1.
SchnorrGroup(p=None, q=None, g=None, l=None, n=None)
Create type for Schnorr group of odd prime order q.
 
If q is not given, q will be the largest n-bit prime, n>=2.
If p is not given, p will be the least l-bit prime, l>n, such that q divides p-1.
 
If l and/or n are not given, default bit lengths will be set (2<=n<l).
SymmetricGroup(n)
Create type for symmetric group of degree n, n>=0.
gcdext(...)
gcdext(a, b, /) -> tuple[mpz, mpz, mpz]
 
Return a 3-element tuple (g,s,t) such that g == gcd(a,b)
and g == a*s + b*t.
iroot(...)
iroot(x,n,/) -> tuple[mpz, bool]
 
Return the integer n-th root of x and boolean value that is `True`
iff the root is exact. x >= 0. n > 0.
is_prime(...)
is_prime(x, n=25, /) -> bool
 
Return `True` if x is *probably* prime, else `False` if x is
definitely composite. x is checked for small divisors and up
to n Miller-Rabin tests are performed.
isqrt(object, /)
isqrt(x, /) -> mpz
 
Return the integer square root of a non-negative integer x.
legendre(...)
legendre(x, y, /) -> mpz
 
Return the Legendre symbol (x|y). y is assumed to be an odd prime.
next_prime(object, /)
next_prime(x, /) -> mpz
 
Return the next *probable* prime number > x.
powmod(...)
powmod(x, y, m, /) -> mpz
 
Return (x**y) mod m. Same as the three argument version of Python's
built-in `pow`, but converts all three arguments to `mpz`.
prev_prime(object, /)
prev_prime(x, /) -> mpz
 
Return the previous *probable* prime number < x.
Only present when compiled with GMP 6.3.0 or later.