%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
%%
%%  quadratic_order.tex       LiDIA documentation
%%
%%  This file contains the documentation of the class quadratic_order
%%
%%  Copyright   (c)   1996   by  LiDIA-Group 
%%
%%  Author: Michael J. Jacobson, Jr.
%%

\begin{lidia_man}
\markright{\BF{quadratic\_order}}

%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%

\NAME
	\BF{quadratic\_order}  \DOTFILL class describing quadratic orders

%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%

\ABSTRACT
	\BF{quadratic\_order} is a class for representing quadratic orders and
	computing many related invariants and functions, such as the ideal
	class number, regulator, L-function, Littlewood indices, etc...

%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%

\DESCRIPTION
	A \BF{quadratic\_order} \MATH{{\cal O}_\Delta}
	is represented simply by a \BF{bigint} \MATH{\Delta}, which
	is a quadratic discriminant, i.e., a non-square integer congruent to
	0 or 1 modulo 4.  Unlike the case of higher degree orders (see the
	description of \BF{order}), we do not require a multiplication
	table to perform arithmetic with elements in the order since we can
	represent any element in \MATH{{\cal O}_\Delta} as
	\MATH{a + b(\Delta + \SQRT{\Delta})/2} where \MATH{a,b \in \Z}.

	Several invariants related to a specific quadratic order are stored
	along with the discriminant, since some of them can be very
	time-consuming to compute and knowledge of them often simplifies
	other computations.  We store the following invariants once they
	have been computed:
\begin{itemize}
\item  factorization of \MATH{\Delta} (\BF{rational\_factorization})
\item  ideal class number (\BF{bigint})
\item  approximation of the regulator (\BF{bigfloat})
\item  elementary divisors of the ideal class group (\BF{base\_vector} of
\BF{bigint})
\item  generators of each cyclic subgroup in the decomposition of
the ideal class group (\BF{base\_vector} of \BF{qi\_class})
\item  approximation of \MATH{L(1,\chi)} (\BF{bigfloat})
\item  approximation of \MATH{C(\Delta)} (\BF{bigfloat})
\end{itemize}


%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%

\CONS

\fcode{ct }{quadratic\_order}{}{
	initializes an empty quadratic order (\MATH{\Delta = 0})).}
\fcode{ct }{quadratic\_order}{long D}{
	if \MATH{D} is a quadratic discriminant, initializes a
	\BF{quadratic\_order} of discriminant \MATH{D}, otherwise an
	empty quadratic order (\MATH{\Delta = 0}) is initialized.}
\fcode{ct }{quadratic\_order}{const bigint \& D}{
        if \MATH{D} is a quadratic discriminant, initializes a
        \BF{quadratic\_order} of discriminant \MATH{D}, otherwise an
        empty quadratic order (\MATH{\Delta = 0}) is initialized.}
\fcode{ct }{quadratic\_order}{const quadratic\_order \& QO}{
	initializes a copy of \MATH{QO}.}
\fcode{dt }{\MATH{\sim}quadratic\_order}{}{}

%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%

\INIT

	Let \MATH{QO} be of type \BF{quadratic\_order}.

\fcode{static void }{quadratic\_order::verbose}{int state}{
	sets the amount of information which is printed during computations.
	If \MATH{state = 1}, then information such as elapsed CPU time is
	printed after and during some computations.  If \MATH{state = 0}, no
	extra information is printed.}

%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%

\ASGN

	Let \MATH{QO} be of type \BF{quadratic\_order}.
        The  operator  \TT{=}  is   overloaded.   For  efficiency
	reasons,  the  following functions are also implemented:

\fcode{bool }{QO.assign}{long D}{
	if \MATH{D} is a quadratic discriminant, \MATH{QO} is set to the
	quadratic order of discriminant \MATH{D} and \TRUE\ is returned,
	otherwise \MATH{QO} is set to an empty quadratic order
	(\MATH{\Delta = 0}) and \FALSE\ is returned.}
\fcode{bool }{QO.assign}{const bigint \& D}{
	if \MATH{D} is a quadratic discriminant, \MATH{QO} is set to the
	quadratic order of discriminant \MATH{D} and \TRUE\ is returned,
	otherwise \MATH{QO} is set to an empty quadratic order
	(\MATH{\Delta = 0}) and \FALSE\ is returned.}
\fcode{void }{QO.assign}{const quadratic\_order \& QO2}{
	\MATH{QO = QO2}.}

%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%

\ACCS

	Let \MATH{QO} be of type \BF{quadratic\_order}.

\cfcode{bigint }{QO.discriminant}{}{
        returns the discriminant \MATH{\Delta} of \MATH{QO}.}

%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%

\COMP

        The  binary operators \TT{==}, \TT{!=}, \TT{<=}, \TT{<} (true subset),
        \TT{>=}, \TT{>} and the unary operator \TT{!} (comparison with
        \MATH{(0)}) are overloaded and can be used in exactly the same way as
        in the programming language C.
	Let \MATH{QO} be of type \BF{quadratic\_order}.

\cfcode{bool }{QO.is\_zero}{}{
        returns \TRUE\ if \MATH{QO = \Z[0]}, \FALSE\ otherwise.}
\cfcode{bool }{QO.is\_equal}{const quadratic\_order \& QO2}{
	returns \TRUE\ if \MATH{QO = QO2}, \FALSE\ otherwise.}
\fcode{bool }{QO.is\_subset}{quadratic\_order \& QO2}{
        returns \TRUE\ if \MATH{QO} is a subset of \MATH{QO2},
	\FALSE\ otherwise.  The discriminant is factored if necessary.}
\fcode{bool }{QO.is\_proper\_subset}{quadratic\_order \& QO2}{
        returns \TRUE\ if \MATH{QO} is a proper subset of \MATH{QO2},
        \FALSE\ otherwise.  The discriminant is factored if necessary.}

%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%

\BASIC

\fcode{bool }{is\_quadratic\_discriminant}{const long D}{
	returns \TRUE\ if \MATH{D} is a quadratic discriminant, \FALSE\
	otherwise.}
\fcode{bool }{is\_quadratic\_discriminant}{const bigint \& D}{
	returns \TRUE\ if \MATH{D} is a quadratic discriminant, \FALSE\
	otherwise.}
\cfcode{bool }{QO.is\_imaginary}{}{
	returns \TRUE\ if \MATH{QO} is an imaginary quadratic order (negative
	discriminant), \FALSE\ otherwise.}
\cfcode{bool }{QO.is\_real}{}{
	returns \TRUE\ if \MATH{QO} is a real quadratic order (positive
	discriminant), \FALSE\ otherwise.}
\fcode{void }{swap}{quadratic\_order \& A, quadratic\_order \& B}{
        exchanges \MATH{A} and \MATH{B}.}


%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%

\HIGH

	Let \MATH{QO} be of type \BF{quadratic\_order}.

\fcode{bigint }{QO.conductor}{}{
	returns the conductor of \MATH{QO}, i.e., the integer \MATH{f_\Delta}
	such that \MATH{\Delta = f_\Delta^2 \Delta_0} where \MATH{\Delta_0} is
	a fundamental discriminant (the discriminant of a maximal order).  
	The factorization of the discriminant is computed if it has not been
	already.}

\fcode{bool }{QO.is\_maximal}{}{
	returns \TRUE\ if \MATH{QO} is a maximal order, \FALSE\ otherwise.}

\fcode{quadratic\_order }{QO.maximize}{}{
	returns the maximal order in which \MATH{QO} is contained.}

%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%

\SSTITLE{L-functions, Littlewood indices, C-function}

	The function \MATH{L(s,\chi) = \SUM{n=1}{\infty}{\FRAC{\chi(n)}{n^s}}},
	where \MATH{\chi} is taken to be the Kronecker symbol, is intimately
	related to computations in class groups of quadratic orders,
	especially at \MATH{s=1} due to the analytic class number formula of
	Dirichlet.

	The Littlewood indices \cite{Lclassnumber,ShLitBounds} are
	values which test the accuracy of Littlewood's bounds on 
	\MATH{L(1,\chi)} and a related function 
	\MATH{L_D(1) = (2 - (\Delta / 2))/2~L(1,\chi)}
	defined by Shanks \cite{ShLitBounds}.  Under the ERH, we expect the
	lower Littlewood indices to be greater than 1 for all discriminants
	\MATH{\Delta} (with a few exceptions of very small discriminants) and
	that they should come close to 1 for discriminants with exceptionally
	small values of \MATH{L(1,\chi)} or \MATH{L_D(1)}.
	Similarly, we expect the upper Littlewood indices to be less than 1
	and to approach 1 for discriminants with exceptionally large values
	of \MATH{L(1,\chi)} or \MATH{L_D(1)}.

	The function
        \MATH{C(\Delta) = \prod_{p \geq 3} 1 - (\Delta/p)/(p-1)}
	provides an indication of whether a related quadratic polynomial will 
	have an asymptotically large number of prime values, based on a 
	conjecture of Hardy and Littlewood \cite{HLConF,FWQuadPoly}.
	If \MATH{\Delta} is odd, then for \MATH{A = (1-\Delta)/4} the
	polynomial \MATH{x^2 + x + A} will have a large asymptotic density of
	prime values when \MATH{C(\Delta)} is large.  If \MATH{\Delta} is 
	even, then for \MATH{A = \Delta / 4} the corresponding polynomial is
	\MATH{x^2 + A}.


\fcode{int }{kronecker}{const bigint \& D, const bigint \& p}{
	computes the value of the Kronecker symbol \MATH{(D/p)}, where \MATH{P}
	is prime.}

\fcode{long }{QO.generate\_optimal\_Q}{}{
	generates the optimal value of \MATH{Q} for the function
	\BF{estimate\_L1} to compute a sufficiently accurate estimate from 
	which a value \MATH{h^*} can be computed satisfying
	\MATH{h^* < h < 2h^*} for imaginary orders and \MATH{h^* < hR < 2h^*}
	for real orders.}
\fcode{long }{QO.get\_optimal\_Q}{}{
	returns, from a precomputed list, a value of Q that is sufficiently 
	large to satisfy the conditions given above.}
\fcode{long }{QO.generate\_optimal\_Q\_cnum}{const bigfloat \& h2, const bigfloat \& t}{
	generates the optimal value of \MATH{Q} for the function
	\BF{estimate\_L1} to compute a sufficiently accurate estimate to prove
	that \MATH{h = h2} when the fractional part of the approximation of
	\MATH{h} is less that \MATH{t}.  See \cite{MWComph} for more details.}
\fcode{long }{QO.get\_optimal\_Q\_cnum}{}{
	returns, from a precomputed list, a value of Q that is sufficiently 
	large to satisfy the conditions given above.}

\fcode{bigfloat }{QO.estimate\_L}{const int s, const long Q}{
	computes a truncated product approximation of \MATH{L(s,\chi)}
	using primes less than \MATH{Q}.}
\fcode{bigfloat }{QO.estimate\_L1}{const long Q}{
	computes an approximation of \MATH{L(1,\chi)} using Bach's averaging
	method \cite{BachEulerProd} with primes less than \MATH{2Q}.}
\fcode{bigfloat }{QO.estimate\_L1\_error}{const long Q}{
	computes an estimate of the error in the approximation of
	\MATH{L(1,\chi)} using Bach's method \cite{BachEulerProd}
	with primes less than \MATH{2Q}.}
\fcode{bigfloat }{QO.Lfunction}{}{
	computes an approximation of \MATH{L(1,\chi)} via the analytic class
	number formula.  The class number and 
	regulator are computed if they have not been already.}
\fcode{bigfloat }{QO.LDfunction}{}{
	returns an approximation of \MATH{L_D(1)}.  The class number and 
	regulator are computed if they have not been already.}
\fcode{bigfloat }{QO.LLI}{}{
	returns an approximation of the lower Littlewood index related to a
	lower bound on \MATH{L(1,\chi)} due to Littlewood.  The class
	number and regulator are computed if they have not been already.}
\fcode{bigfloat }{QO.LLI\_D}{}{
	returns an approximation of the lower Littlewood index related to a
	lower bound on \MATH{L_D(1)} due to Shanks.  The class number and
	regulator are computed if they have not been already.}
\fcode{bigfloat }{QO.ULI}{}{
	returns an approximation of the upper Littlewood index related to an
	upper bound on \MATH{L(1,\chi)} due to Littlewood.  The class number
	and regulator are computed if they have not been already.}
\fcode{bigfloat }{QO.ULI\_D}{}{
	returns an approximation of the upper Littlewood index related to an
	upper bound on \MATH{L_D(1)} due to Shanks.  The class number and
	regulator are computed if they have not been already.}
\fcode{bigfloat }{QO.Cfunction}{}{
	returns an approximation of the function \MATH{C(\Delta)} accurate to
	8 significant digits.  The class number, regulator, and the prime
	factorization of \MATH{\Delta} are computed if they have not been
	already.}

%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%

\SSTITLE{Regulator, class number, and class group}

	The regulator is defined as the natural logarithm of the fundamental
	unit and the class number is the order of the group of ideal
	equivalence classes.  We denote the regulator by \MATH{R},
	the class group by \MATH{CL} and the class number by \MATH{h}.
	By the structure of the class group, we mean the unique positive
	integers \MATH{m_1, \ldots, m_k} with \MATH{m_1 \GT 1}, 
	\MATH{m_i \MID m_{i+1}} for \MATH{1 \LE i \LT k} such that there is
	an isomorphism \MATH{\phi: CL \rightarrow \Z/m_1 \Z \times \cdots
	\Z/m_k \Z}.  The integers \MATH{m_i} are called the invariants of
	the class group.  While computing the structure, we also compute
	a transformation matrix \MATH{U} representing the map \MATH{\phi},
	since it is useful in other computations.


\fcode{bigfloat }{QO.regulator}{}{
	returns an approximation of the regulator of \MATH{QO}.
	If the regulator has not already been
	computed, either \BF{regulator\_BJT} or \BF{regulator\_shanks}
%	or \BF{class\_group\_subexp} 
	is used, depending on the size of the discriminant.  If \MATH{QO} is
	imaginary, the regulator is set to \MATH{1}. }

\fcode{bigint }{QO.class\_number}{}{
	returns the ideal class number of \MATH{QO}.  If the class number has
	not already been computed, either \BF{class\_number\_shanks} or
	\BF{class\_group\_subexp} is used, depending on the size of the
	discriminant. }

\fcode{base\_vector<bigint> }{QO.class\_group}{}{
	returns the vector of invariants representing the structure of the
	ideal class group of \MATH{QO}.  If the class group has not already
	been computed, either \BF{class\_group\_BJT},
	\BF{class\_group\_shanks},
%	\BF{class\_group\_h},
	or \BF{class\_group\_subexp} depending on the size of the
	discriminant.}
%	and whether the class number has already been computed. }

\fcode{bigfloat }{QO.regulator\_BJT}{}{
        computes an unconditionally correct approximation of the regulator
	of \MATH{QO} using a variation of the algorithm of \cite{BBQuadOrd}
	which has unconditional complexity
	\MATH{O(\SQRT{R})}.  If \MATH{QO} is not real, the regulator is set to
	\MATH{1}.  If the regulator has already been computed, the
	function simply returns this value.}

\fcode{bigfloat }{QO.regulator\_shanks}{}{
        computes an unconditionally correct approximation of the regulator
	of \MATH{QO} using the
	algorithm of \cite{JLWNumEx} based on the baby-step giant-step method
	in \cite{MWComph}, which
	has complexity \MATH{O(\Delta^{(1/5)})} under the Extended Riemann
	Hypothesis.  If \MATH{QO} is not real, the regulator is set to
	\MATH{1}.  If the regulator has already been computed, the
	function simply returns this value.}

\fcode{bigint }{QO.class\_number\_shanks}{}{
        computes the ideal class number of \MATH{QO} using the algorithm of
	\cite{FWQuadPoly} based on the ideas of \cite{Lcalculation} for
	imaginary quadratic orders, and the algorithm of \cite{JLWNumEx} based 
	on the ideas in \cite{MWComph} for real quadratic orders.
	Both algorithms have complexity \MATH{O(|\Delta|^{(1/5)})}, and the
	correctness and the complexity are both conditional on the truth of the
	Extended Riemann Hypothesis.
	If the class number has already been computed, the
	function simply returns this value.}

\fcode{base\_vector<bigint> }{QO.class\_group\_BJT}{}{
        computes the structure of the ideal class group of \MATH{QO} using the
	method of \cite{BJTAb} for imaginary orders and an unpublished
	version of this algorithm for real
	orders, which have complexity \MATH{O(\SQRT{h})} and
	\MATH{O(\SQRT{hR})} respectively.
        The correctness of both algorithms is conditional on the truth of the
	Extended Riemann Hypothesis but the complexity results are not.
	If the class group has already been computed, the
	function simply returns this value.}

\fcode{base\_vector<bigint> }{QO.class\_group\_shanks}{}{
        computes the structure of the ideal class group of \MATH{QO} using
	variations of the methods of \cite{SchQuad} which have complexity
	\MATH{O(|\Delta|^{(1/4)})}.  The correctness and complexity of both
	algorithms are conditional on the truth of the Extended Riemann
	Hypothesis.  If the class group has already been computed, the
	function simply returns this value.}

%\fcode{base\_vector<bigint> }{QO.class\_group\_h}{}{
%        computes the structure of the ideal class group of \MATH{QO} using the
%        methods of \cite{BJTordgiven}.
%	The algorithms require knowledge of the class number, so it and the
%	regulator are computed if necessary.
%	If the class group has already been computed, the
%	function simply returns this value.}

\fcode{base\_vector<bigint> }{QO.class\_group\_subexp}{}{
        computes the structure of the ideal class group of \MATH{QO} using
	a variation of the sub-exponential method of Hafner and McCurley
	\cite{JSieve} for imaginary orders.
	At the moment, this function is only implemented for imaginary orders.
%	and a variation of the generalization of this algorithm due to
%	Buchmann \cite{BSub,CAbel} for real orders.
%	Note that if \MATH{QO} is real, this function also computes the
%	regulator.
	If the class group has already been computed, the function simply
	returns this value.}

%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%

\SSTITLE{Additional functions}

\fcode{rational\_factorization }{QO.factor\_h}{}{
	returns a \BF{rational\_factorization} of the class number.  The 
	class number is computed if it has not been already.}

\fcode{bigint }{QO.exponent}{}{
	returns the exponent of the class group, i.e., the largest cyclic
	factor.  The class group is computed if it has not been already.}

\fcode{int }{QO.p\_rank}{const bigint \& p}{
	returns the p-rank of the ideal class group.  The class group is 
	computed if it has not been already.}

\fcode{base\_vector<qi\_class> }{QO.generators}{}{
        returns a vector of generators of the cyclic subgroups of the ideal
	class group of \MATH{QO}.  The class group is computed if it has not
	been already.}

\fcode{rational\_factorization }{QO.factor\_discriminant}{}{
	returns the prime factorization of the discriminant of \MATH{QO} using
	the 2-Sylow subgroup of the class group.  The class group and a set
	of generators are computed if they have not been already.
	At present, this function is only implemented for imaginary orders.
	If \MATH{QO} is real, the discriminant is simply factored with the
	\BF{rational\_factorization} function \BF{factor}.}

%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%

\IO

	Let \MATH{QO} be of type \BF{quadratic\_order}.
	The \BF{istream}  operator  \TT{>>}  and  the \BF{ostream}  operator
	\TT{<<} are overloaded.   Input consists of reading a \BF{bigint} value
	for the discriminant.  Output of a \BF{quadratic\_order} has the
	following format:
\begin{verbatim}
Quadratic Order:
   Delta = (discriminant of QO) (decimal digits)
         = (prime factorization of the discriminant of QO)
   R = (regulator)
   h = (class number)
   CL = (vector of class group invariants)
   generators = (vector of generators of the cyclic subgroups)
   L(1,X) = (L function)
   C(Delta) = (C function)
\end{verbatim}
	The discriminant is always displayed, while the other invariants are
	displayed only if they have been computed.

%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%

\SEEALSO
	qi\_class, qi\_class\_real, order

%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%

\NOTES

	The functions \TT{class\_group\_subexp} and \TT{factor\_discriminant}
	are still under development.  However, a preliminary version of 
	\TT{class\_group\_subexp} is included for imaginary orders which can
	handle discriminants of up to about 30 decimal digits.

%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%

\EXAMPLES
\begin{verbatim}
#include <LiDIA/quadratic_order.h>

main()
{
  bigint D;
  quadratic_order QO;

  do {
    cout << "Please enter a quadratic discriminant: "; cin >> D; 
  while (!QO.assign(D));
  cout << "\n";

  QO.class_group();
  QO.generators();
  QO.Lfunction();

  cout << QO;

  cout << "   ULI = " << QO.ULI() << "\n";
  cout << "   LLI = " << QO.LLI() << "\n";
}
\end{verbatim}

example:

\begin{verbatim}
Please enter a quadratic discriminant: -501510767

Quadratic Order:
   Delta = -501510767 (9)
   h = 18522
   CL = [ 7 7 378 ]
   generators = [ (3286, 1657) (1144, 439) (2934, 61) ]
   L(1,X) = 2.5983498285787
   ULI = 0.243356600232444
   LLI = 16.865670804095
\end{verbatim}

	For further examples please refer to \\
	\TT{LiDIA/src/packages/quadratic\_order/quadratic\_order\_appl.c}.

%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%

\AUTHOR
	Michael J. Jacobson, Jr.

\end{lidia_man}
