Class Sha

x.__init__(...) initializes x; see x.__class__.__doc__ for signature

Overrides: object.__init__

(inherited documentation)

    Return the numerical analytic order of Sha, which is
    a floating point number in all cases.

    INPUT:
        prec -- integer (default: 53) bits precision -- just used
                for the L-series computation; not for regulator, etc. 
        use_database -- whether the rank and regulator should
                be looked up in the database if possible.
        proof -- bool or None (default: None, see proof.[tab] or
                       sage.structure.proof) proof option passed
                onto regulator and rank computation.

    NOTE: See also the an() command, which will return a
    provably correct integer when the rank is 0 or 1.

    EXAMPLES:
        sage: EllipticCurve('11a').sha().an_numerical()
        1.00000000000000
        sage: EllipticCurve('37a').sha().an_numerical()
        1.00000000000000
        sage: EllipticCurve('389a').sha().an_numerical()    # random low order bits
        1.00000000000000
        sage: EllipticCurve('66b3').sha().an_numerical()
        4.00000000000000
        sage: EllipticCurve('5077a').sha().an_numerical()   # random low bit
        1.00000000000000

    A rank 4 curve:
        sage: EllipticCurve([1, -1, 0, -79, 289]).sha().an_numerical()   # long time
        1.00000000000000

A rank 5 curve:
        sage: EllipticCurve([0, 0, 1, -79, 342]).sha().an_numerical(prec=4, proof=False)          # long time -- about 30 seconds.
        1.0                
    

Returns the Birch and Swinnerton-Dyer conjectural order of Sha
as a provably corret integer, unless the analytic rank is > 1,
in which case this function returns a numerical value.

This result is proved correct if the order of vanishing is 0
and the Manin constant is <= 2.

If the optional parameter use_database is True (default:
False), this function returns the analytic order of Sha as
listed in Cremona's tables, if this curve appears in Cremona's
tables.

EXAMPLES:
    sage: E = EllipticCurve([0, -1, 1, -10, -20])   # 11A  = X_0(11)
    sage: E.sha().an()
    1
    sage: E = EllipticCurve([0, -1, 1, 0, 0])       # X_1(11)
    sage: E.sha().an()
    1

    sage: EllipticCurve('14a4').sha().an()
    1
    sage: EllipticCurve('14a4').sha().an(use_database=True)  # optional -- requires large Cremona database package
    1

The smallest conductor curve with nontrivial Sha:
    sage: E = EllipticCurve([1,1,1,-352,-2689])     # 66b3
    sage: E.sha().an()
    4

The four optimal quotients with nontrivial Sha and conductor <= 1000:
    sage: E = EllipticCurve([0, -1, 1, -929, -10595])       # 571A
    sage: E.sha().an()
    4
    sage: E = EllipticCurve([1, 1, 0, -1154, -15345])       # 681B
    sage: E.sha().an()
    9
    sage: E = EllipticCurve([0, -1, 0, -900, -10098])       # 960D
    sage: E.sha().an()
    4
    sage: E = EllipticCurve([0, 1, 0, -20, -42])            # 960N
    sage: E.sha().an()
    4

The smallest conductor curve of rank > 1:
    sage: E = EllipticCurve([0, 1, 1, -2, 0])       # 389A (rank 2)
    sage: E.sha().an()
    0.999999999999998

The following are examples that require computation of the Mordell-Weil
group and regulator:

    sage: E = EllipticCurve([0, 0, 1, -1, 0])                     # 37A  (rank 1)
    sage: E.sha().an()
    1

    sage: E = EllipticCurve("1610f3")
    sage: E.sha().an()
    4

In this case the input curve is not minimal, and if this function didn't
transform it to be minimal, it would give nonsense:
    sage: E = EllipticCurve([0,-432*6^2])
    sage: E.sha().an()
    1

Returns the conjectural order -- up to sign -- of Sha(E),
according to the $p$-adic analogue of the BSD conjecture.

INPUT:
    p -- a prime > 3
    prec (optional) -- the precision used in the computation of the 
    p-adic L-Series

OUTPUT:
    p-adic number -- that conjecturally equals $\#Sha(E)(p)$ or $-\#Sha(E)(p)$.

NOTE:
    If prec is set to zero (default) then the precision is set so that
    at least the first p-adic digit of conjectural $\#Sha(E)(p)$ is
    determined.

BUG: 
    Currently for supersingular primes for curves of rank > 0, only the 
    first digit will be correct. More is hard to compute anyway.

EXAMPLES:

Good ordinary examples:

    sage: EllipticCurve('11a1').sha().an_padic(5)  #rank 0
    1 + O(5^2)
    sage: EllipticCurve('43a1').sha().an_padic(5)  #rank 1
    1 + O(5)
    sage: EllipticCurve('389a1').sha().an_padic(5,4) #rank 2   (long time)
    1 + O(5^3)
    sage: EllipticCurve('858k2').sha().an_padic(7)  #rank 0, non trivial sha  (long time)
    7^2 + O(7^3)
    
Exceptional cases:

    sage: EllipticCurve('11a1').sha().an_padic(11) #rank 0
    1 + O(11)

The output maybe be only up to sign, as the following two examples illustrate:

    sage: EllipticCurve('123a1').sha().an_padic(41) #rank 1    (long time) -- random output (can be either 1 + O(41) or 40 + O(41)).   
    40 + O(41)
    sage: EllipticCurve('817a1').sha().an_padic(43) #rank 2    (long time)
    42 + O(43) 
    
Supersingular cases:

    sage: EllipticCurve('34a1').sha().an_padic(5) # rank 0     (long time)
    1 + O(5^3)
    sage: EllipticCurve('43a1').sha().an_padic(7) # rank 1    (very long time -- nearly a minute)
    1 + O(7)
    sage: EllipticCurve('1483a1').sha().an_padic(5) # rank 2   (long time)
    1 + O(5)

Returns an upper bound of $\#Sha(E)(p)$. 

INPUT:
    p -- a prime > 3

OUTPUT:
    integer -- power of p that bounds #Sha(E)(p) from above

NOTE:
    The result is a proven upper bound on the order of $Sha(E)(p)$.
    So in particular it proves it finiteness even if the rank of 
    the curve is larger than 1. Note also that this bound is sharp
    if one assumes the main conjecture of Iwasawa theory of
    elliptic curves (and this is known in certain cases).

EXAMPLES:
    sage: e = EllipticCurve('858k2')
    sage: e.sha().p_primary_bound(3)           # long time
    0
    sage: e.sha().p_primary_bound(7)           # long time
    2

Given a fundamental discriminant D (!= -3,-4) that satisfies the
Heegner hypothesis, return a list of primes so that
Kolyvagin's theorem (as in Gross's paper) implies that any
prime divisor of $\#Sha$ is in this list.

INPUT:
    D -- (optional) a fundamental discriminant < -4 that satisfies the
         Heegner hypothesis for E; if not given, use the first such D
         
    regulator -- (optional) regulator of E(K); if not given, will
                 be computed (which could take a long time)

                 
    ignore_nonsurj_hypothesis (optional: default False) --
              If True, then gives the bound coming from Heegner point
              index, but without any hypothesis on surjectivity
              of the mod-p representation.
              

OUTPUT:
    bound and index

More precisely:

        0 -- if E/K has complex multiplication or analytic rank >= 2
    or 
        B -- list of primes such that if p divides Sha(E/K), then p
             is in B.

    and

        I -- the odd part of the index of the Heegner point in the full
             group of K-rational points on E.  (If E has CM, returns 0.)

REMARKS:
    (1) We do not have to assume that the Manin constant is 1
        (or a power of 2).  If the Manin constant were
        divisible by a prime, that prime would get included in
        the list of bad primes.

    (2) We assume the Gross-Zagier theorem is True under the
        hypothesis that gcd(N,D) = 1, instead of the stronger
        hypothesis gcd(2*N,D)=1 that is in the original
        Gross-Zagier paper.  That Gross-Zagier is true when
        gcd(N,D)=1 is"well-known" to the experts, but doesn't
        seem to written up well in the literature.

    (3) Correctness of the computation is guaranteed using
        interval arithmetic, under the assumption that the
        regulator, square root, and period lattice are
        computed to precision at least $10^{-10}$, i.e., they are
        correct up to addition or a real number with absolute
        value less than $10^{-10}$.

EXAMPLES:
    sage: E = EllipticCurve('37a')
    sage: E.sha().bound_kolyvagin()
    ([2], 1)
    sage: E = EllipticCurve('141a')
    sage: E.sha().an()
    1
    sage: E.sha().bound_kolyvagin()
    ([2, 7], 49)

We get no information the curve has rank $2$.
    sage: E = EllipticCurve('389a')
    sage: E.sha().bound_kolyvagin()
    (0, 0)
    sage: E = EllipticCurve('681b')
    sage: E.sha().an()
    9
    sage: E.sha().bound_kolyvagin()
    ([2, 3], 9)        

Returns a list p of primes such that the theorems of Kato's
and others (e.g., as explained in a paper/thesis of Grigor
Grigorov) imply that if p divides $\#Sha(E)$ then $p$ is in
the list.

If L(E,1) = 0, then Kato's theorem gives no information, so
this function returns False.

THEOREM (Kato): Suppose p >= 5 is a prime so the p-adic
representation rho_{E,p} is surjective.  Then $ord_p(\#Sha(E))$
divides $ord_p(L(E,1)/Omega_E)$.

EXAMPLES:
    sage: E = EllipticCurve([0, -1, 1, -10, -20])   # 11A  = X_0(11)
    sage: E.sha().bound_kato()
    [2, 3, 5]
    sage: E = EllipticCurve([0, -1, 1, 0, 0])       # X_1(11)
    sage: E.sha().bound_kato()
    [2, 3, 5]
    sage: E = EllipticCurve([1,1,1,-352,-2689])     # 66B3
    sage: E.sha().bound_kato()
    [2, 3]

For the following curve one really has 25 | $\#Sha$ (by Grigorov-Stein paper):
    sage: E = EllipticCurve([1, -1, 0, -332311, -73733731])   # 1058D1
    sage: E.sha().bound_kato()                 # long time (about 1 second)
    [2, 3, 5]
    sage: E.non_surjective()                # long time (about 1 second)
    []

For this one, Sha is divisible by 7.
    sage: E = EllipticCurve([0, 0, 0, -4062871, -3152083138])   # 3364C1
    sage: E.sha().bound_kato()                 # long time (< 10 seconds)
    [2, 3, 7]

No information about curves of rank > 0:
    sage: E = EllipticCurve([0, 0, 1, -1, 0])       # 37A  (rank 1)
    sage: E.sha().bound_kato()
    False

Compute a provably correct bound on the order of the Shafarevich-Tate
group of this curve. The bound is a either False (no bound) or a list
B of primes such that any divisor of Sha is in this list.