Function: alginit
Section: algebras
C-Name: alginit
Prototype: GGDnD3,L,
Help: alginit(B,C,{v},{flag=3}): initializes the central simple algebra
 defined by data B, C. Binary digits of the flag mean 1: compute a maximal
 order; 2: fully factor the discriminant instead of using a lazy factorisation.
Doc: initializes the central simple algebra defined by data $B$, $C$ and
 variable $v$, as follows.

 \item (multiplication table) $B$ is the base number field $K$ in \tet{nfinit}
 form, $C$ is a ``multiplication table'' over $K$.
 As a $K$-vector space, the algebra is generated by a basis
 $(e_{1} = 1,\dots, e_{n})$; the table is given as a \typ{VEC} of $n$ matrices
 in $M_{n}(K)$, giving the left multiplication by the basis elements~$e_{i}$,
 in the given basis.
 Assumes that $e_{1}= 1$, that the multiplication table is integral, and that
 $(\bigoplus_{i=1}^{n}K e_{i},C)$ describes a central simple algebra over $K$.
 \bprog
 { mi = [0,-1,0, 0;
          1, 0,0, 0;
          0, 0,0,-1;
          0, 0,1, 0];
   mj = [0, 0,-1,0;
          0, 0, 0,1;
          1, 0, 0,0;
          0,-1, 0,0];
   mk = [0, 0, 0, -1;
          0, 0,-1, 0;
          0, 1, 0, 0;
          1, 0, 0, 0];
   A = alginit(nfinit(y), [matid(4), mi,mj,mk], , 0); }
 @eprog represents (in a complicated way) the quaternion algebra $(-1,-1)_{\Q}$.
 See below for a simpler solution.

 \item (cyclic algebra) $B$ is an \kbd{rnf} structure attached to a cyclic
 number field extension $L/K$ of degree $d$, $C$ is a \typ{VEC}
 \kbd{[sigma,b]} with 2 components: \kbd{sigma} is a \typ{POLMOD} representing
 an automorphism generating $\text{Gal}(L/K)$, $b$ is an element in $K^{*}$.
 This represents the cyclic algebra~$(L/K,\sigma,b)$. Currently the element
 $b$ has to be integral.
 \bprog
  ? Q = nfinit(y); T = polcyclo(5, 'x); F = rnfinit(Q, T);
  ? A = alginit(F, [Mod(x^2,T), 3]);
 @eprog defines the cyclic algebra $(L/\Q, \sigma, 3)$, where
 $L = \Q(\zeta_{5})$ and $\sigma:\zeta\mapsto\zeta^{2}$ generates
 $\text{Gal}(L/\Q)$.

 \item (quaternion algebra, special case of the above) $B$ is an \kbd{nf}
 structure attached to a number field $K$, $C = [a,b]$ is a vector
 containing two elements of $K^{*}$ with $a$ not a square in $K$, returns the
 quaternion algebra $(a,b)_{K}$.
 The variable $v$ (\kbd{'x} by default) must have higher priority than the
 variable of $K$\kbd{.pol} and is used to represent elements in the splitting
 field $L = K[x]/(x^{2}-a)$.
 \bprog
  ? Q = nfinit(y); A = alginit(Q, [-1,-1]);  \\@com $(-1,-1)_{\Q}$
 @eprog

 \item (algebra/$K$ defined by local Hasse invariants)
 $B$ is an \kbd{nf} structure attached to a number field $K$,
 $C = [d, [\kbd{PR},h_{f}], h_{i}]$ is a triple
 containing an integer $d > 1$, a pair $[\kbd{PR}, h_{f}]$ describing the
 Hasse invariants at finite places, and $h_{i}$ the Hasse invariants
 at archimedean (real) places. A local Hasse invariant belongs to $(1/d)\Z/\Z
 \subset \Q/\Z$, and is given either as a \typ{FRAC} (lift to $(1/d)\Z$),
 a \typ{INT} or \typ{INTMOD} modulo $d$ (lift to $\Z/d\Z$); a whole vector
 of local invariants can also be given as a \typ{VECSMALL}, whose
 entries are handled as \typ{INT}s. \kbd{PR} is a list of prime ideals
 (\kbd{prid} structures), and $h_{f}$ is a vector of the same length giving the
 local invariants at those maximal ideals. The invariants at infinite real
 places are indexed by the real roots $K$\kbd{.roots}: if the Archimedean
 place $v$ is attached to the $j$-th root, the value of
 $h_{v}$ is given by $h_{i}[j]$, must be $0$ or $1/2$ (or~$d/2$ modulo~$d$), and
 can be nonzero only if~$d$ is even.

 By class field theory, provided the local invariants $h_{v}$ sum to $0$, up
 to Brauer equivalence, there is a unique central simple algebra over $K$
 with given local invariants and trivial invariant elsewhere. In particular,
 up to isomorphism, there is a unique such algebra $A$ of degree $d$.

 We realize $A$ as a cyclic algebra through class field theory. The variable $v$
 (\kbd{'x} by default) must have higher priority than the variable of
 $K$\kbd{.pol} and is used to represent elements in the (cyclic) splitting
 field extension $L/K$ for $A$.

 \bprog
  ? nf = nfinit(y^2+1);
  ? PR = idealprimedec(nf,5); #PR
  %2 = 2
  ? hi = [];
  ? hf = [PR, [1/3,-1/3]];
  ? A = alginit(nf, [3,hf,hi]);
  ? algsplittingfield(A).pol
  %6 = x^3 - 21*x + 7
 @eprog

 \item (matrix algebra, toy example) $B$ is an \kbd{nf} structure attached
 to a number field $K$, $C = d$ is a positive integer. Returns a cyclic
 algebra isomorphic to the matrix algebra $M_{d}(K)$.

 \item (algebras over~$\R$) If $B$ is a \typ{REAL} and $C = 1/2$, returns
 a structure representing the Hamilton quaternion algebra~${\bf H} =
 (-1,-1)_{\R}$. If $B$ is a \typ{REAL} and $C = 0$, returns an algebra structure
 representing~$\R$. If $B$ is a \typ{COMPLEX} and $C = 0$, returns an algebra
 structure representing~$\C$.

 In all cases over a number field, this function factors various discriminants
 and computes a maximal order for the algebra by default, which may require a
 lot of time. This can be controlled by $\fl$, whose binary digits mean:

  \item $1$: compute a maximal order.

  \item $2$: fully factor the discriminants instead of using a lazy
 factorisation. If this digit of $\fl$ is set to~$0$, the local Hasse invariants
 are not computed.

 If only a partial factorisation is known, the computed order is only guaranteed
 to be maximal at the known prime factors.

 The pari object representing such an algebra $A$ is a \typ{VEC} with the
 following data:

  \item A splitting field $L$ of $A$ of the same degree over $K$ as $A$, in
 \kbd{rnfinit} format, accessed with \kbd{algsplittingfield}.

  \item The Hasse invariants at the real places of $K$, accessed with
 \kbd{alghassei}.

  \item The Hasse invariants of $A$ at the finite primes of $K$ that ramify in
 the natural order of $A$, accessed with \kbd{alghassef}.

  \item A basis of an order ${\cal O}_{0}$ expressed on the basis of the natural
 order, accessed with \kbd{algbasis}.

  \item A basis of the natural order expressed on the basis of ${\cal O}_{0}$,
 accessed with \kbd{alginvbasis}.

  \item The left multiplication table of ${\cal O}_{0}$ on the previous basis,
 accessed with \kbd{algmultable}.

  \item The characteristic of $A$ (always $0$), accessed with \kbd{algchar}.

  \item The absolute traces of the elements of the basis of ${\cal O}_{0}$.

  \item If $A$ was constructed as a cyclic algebra~$(L/K,\sigma,b)$ of degree
 $d$, a \typ{VEC} $[\sigma,\sigma^{2},\dots,\sigma^{d-1}]$. The function
 \kbd{algaut} returns $\sigma$.

  \item If $A$ was constructed as a cyclic algebra~$(L/K,\sigma,b)$, the
 element $b$, accessed with \kbd{algb}.

  \item If $A$ was constructed with its multiplication table $mt$ over $K$,
 the \typ{VEC} of \typ{MAT} $mt$, accessed with \kbd{algrelmultable}.

  \item If $A$ was constructed with its multiplication table $mt$ over $K$,
 a \typ{VEC} with three components: a \typ{COL} representing an element of $A$
 generating the splitting field $L$ as a maximal subfield of $A$, a \typ{MAT}
 representing an $L$-basis ${\cal B}$ of $A$ expressed on the $\Z$-basis of
 ${\cal O}_{0}$, and a \typ{MAT} representing the $\Z$-basis of ${\cal O}_{0}$
 expressed on ${\cal B}$. This data is accessed with \kbd{algsplittingdata}.
