Add documentation for elliptic curves over finite fields (#1172)

Project.toml

@@ -1,6 +1,6 @@
 name = "Hecke"
 uuid = "3e1990a7-5d81-5526-99ce-9ba3ff248f21"
-version = "0.19.8"
+version = "0.19.9"
 
 [deps]
 AbstractAlgebra = "c3fe647b-3220-5bb0-a1ea-a7954cac585d"

docs/Build.jl

@@ -32,6 +32,10 @@ pages = [
 					      "quad_forms/Zgenera.md",
 					      "quad_forms/discriminant_group.md"
 					    ],
+         "Elliptic curves" => [ "elliptic_curves/intro.md",
+                                "elliptic_curves/basics.md",
+                                "elliptic_curves/finite_fields.md",
+                                "elliptic_curves/number_fields.md",],
          "Abelian groups" => "abelian/introduction.md",
          "Class field theory" => "class_fields/intro.md",
          "Misc" =>  ["FacElem.md",
@@ -64,6 +68,16 @@ pages = [
 # Remove the module prefix
 Base.print(io::IO, b::Base.Docs.Binding) = print(io, b.var)
 
+# the .id in the anchor is derived from the signature, which sometimes contain "<:"
+# it seems mkdocs does not handle "<:" that well inside an <a href="...">.
+function Base.getproperty(obj::Documenter.Anchors.Anchor, sym::Symbol)
+  if sym === :id
+    return replace(getfield(obj, sym), "<:" => "")
+  else
+    return getfield(obj, sym)
+  end
+end
+
 function make(Hecke::Module; strict = false,
                              local_build::Bool = false,
                              doctest = true,

docs/mkdocs.yml

@@ -93,6 +93,11 @@ nav:
       - Genera for hermitian lattices: 'quad_forms/genusherm.md'
       - Genera for integer lattices: 'quad_forms/Zgenera.md'
       - Discriminant groups: 'quad_forms/discriminant_group.md'
+    - Elliptic curves:
+      - Introduction: 'elliptic_curves/intro.md'
+      - Basics: 'elliptic_curves/basics.md'
+      - Finite fields: 'elliptic_curves/finite_fields.md'
+      - Number fields: 'elliptic_curves/number_fields.md'
     - Abelian groups:
       - Introduction:     abelian/introduction.md
       - Elements:     abelian/elements.md

docs/src/elliptic_curves/basics.md

@@ -0,0 +1,67 @@
+# Basics
+
+```@meta
+CurrentModule = Hecke
+DocTestSetup = quote
+    using Hecke
+end
+
+```
+
+## Creation
+
+```@docs
+elliptic_curve
+elliptic_curve_from_j_invariant
+```
+
+## Basic properties
+
+```@docs
+base_field(::EllCrv)
+base_change(::Field, ::EllCrv)
+base_change(::Any, ::EllCrv)
+coefficients(::EllCrv)
+a_invars(::EllCrv)
+b_invars(::EllCrv)
+c_invars(::EllCrv)
+discriminant(::EllCrv)
+j_invariant(::EllCrv)
+equation(::EllCrv)
+hyperelliptic_polynomials(::EllCrv)
+```
+
+## Points
+
+```julia
+    (E::EllCrv)(coords::Vector; check::Bool = true)
+```
+
+Return the point $P$ of $E$ with coordinates specified by `coords`, which can
+be either affine coordinates (`length(coords) == 2`) or projective coordinates
+(`length(coords) == 3`).
+
+Per default, it is checked whether the point lies on $E$. This can be disabled
+by setting `check = false`.
+
+##### Examples
+
+```jldoctest
+julia> E = elliptic_curve(QQ, [1, 2]);
+
+julia> E([1, -2])
+Point  (1 : -2 : 1)  of Elliptic curve with equation
+y^2 = x^3 + x + 2
+
+julia> E([2, -4, 2])
+Point  (1 : -2 : 1)  of Elliptic curve with equation
+y^2 = x^3 + x + 2
+```
+
+```@docs
+infinity(::EllCrv)
+parent(::EllCrvPt)
+is_on_curve(::EllCrv, ::Vector)
++(P::EllCrvPt{T}, Q::EllCrvPt{T}) where {T}
+division_points(::EllCrvPt, ::Int)
+```

docs/src/elliptic_curves/finite_fields.md

@@ -0,0 +1,51 @@
+# Elliptic curves over finite fields
+
+```@meta
+CurrentModule = Hecke
+DocTestSetup = quote
+    using Hecke
+end
+```
+
+## Random points
+
+```
+  rand(E::EllCrv{<: FinFieldElem})
+```
+
+Return a random point on the elliptic curve $E$ defined over a finite field.
+
+```jldoctest; filter = r"Point.*"
+julia> E = elliptic_curve(GF(3), [1, 2]);
+
+julia> rand(E)
+Point  (2 : 0 : 1)  of Elliptic curve with equation
+y^2 = x^3 + x + 2
+```
+
+## Cardinality and orders
+
+```@docs
+order(::EllCrv{<:FinFieldElem})
+order(::EllCrvPt{<:FinFieldElem})
+```
+
+## Frobenius
+
+```@docs
+trace_of_frobenius(::EllCrv{<:FinFieldElem})
+trace_of_frobenius(::EllCrv{<:FinFieldElem}, ::Int)
+```
+
+## Group structure of rational points
+
+```@docs
+gens(::EllCrv{T}) where {T <: FinFieldElem}
+abelian_group(::EllCrv{<:FinFieldElem})
+```
+
+## Discrete logarithm
+
+```@docs
+disc_log(::EllCrvPt, ::EllCrvPt)
+```

docs/src/elliptic_curves/intro.md

@@ -0,0 +1,23 @@
+# Introduction
+
+```@meta
+CurrentModule = Hecke
+DocTestSetup = quote
+    using Hecke
+end
+
+```
+
+This chapter deals with functionality for elliptic curves, which is available over arbitrary fields, with
+specific features available for curvers over the rationals and number fields, and finite fields.
+
+An elliptic curve $E$ is the projective closure of the curve given by the *Weierstrass equation*
+```math
+y^2 + a_1 x y + a_3 y = x^3 + a_2 x^2 + a_4 x + a_6
+```
+specified by the list of coefficients `[a1, a2, a3, a4, a6]`. If $a_1 = a_2 = a_3 = 0$, this simplifies
+to
+```math
+y^2 = x^3 + a_4 x + a_6
+```
+which we refer to as a *short Weierstrass equation* and which is specified by the two element list `[a4, a6]`.

docs/src/elliptic_curves/number_fields.md

@@ -0,0 +1 @@
+# Elliptic curves over rationals and number fields

docs/src/quad_forms/basics.md

@@ -2,8 +2,8 @@
 ```@meta
 CurrentModule = Hecke
 DocTestSetup = quote
-    using Hecke
-  end
+  using Hecke
+end
 ```
 
 ## Creation of spaces

src/Aliases.jl

@@ -214,3 +214,5 @@
 # Depcrecated during 0.19.*
 @alias EmbeddedNumField EmbeddedField
 @alias EmbeddedNumFieldElem EmbeddedElem
+@alias EllipticCurve elliptic_curve
+@alias points_with_x points_with_x_coordinate