Function: alginit
Section: algebras
C-Name: alginit
Prototype: GGDnD1,L,
Help: alginit(B, C, {v}, {maxord = 1}): initializes the central simple algebra
 defined by data B, C. If maxord = 1, compute a maximal order.
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}^nK 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, 0;
          0, 0,-1, 0;
          0, 1, 0, 0;
          1, 0, 0,-1];
   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)$.

 In all cases, this function computes a maximal order for the algebra by default,
 which may require a lot of time. Setting $maxord = 0$ prevents this computation.

 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}.
