# Operations on Forms ## Arithmetic ### `Conjugate(f): QuadBinElt -> QuadBinElt` Given a form $f = ax^2 + bxy + cy^2$, returns the conjugate form $ax^2 - bxy + cy^2$. ### `f * g: QuadBinElt, QuadBinElt -> QuadBinElt` ### `Composition(f, g): QuadBinElt, QuadBinElt -> QuadBinElt` ```magma Al : MonStgElt Default: "Gauss" Reduction: BoolElt Default: false ``` Returns the composition of two binary quadratic forms $f$ and $g$. The operator ``*'` returns a reduced form equivalent to the product using a fast composition algorithm of Shanks. In contrast, by default `Composition` returns the true composition in the group of forms, unless the parameter `Reduction := true`. The function `Composition` takes a further parameter `Al` which specifies whether the algorithm of Gauss or Shanks, set to `"Gauss"` by default. The algorithm of Shanks performs partial intermediate reductions, so it is not allowed to select `Al := "Shanks"` and `Reduction := false`. ### `f ^ n: QuadBinElt, RngIntElt -> QuadBinElt` ### `Power(f, n): QuadBinElt, RngIntElt -> QuadBinElt` ```magma Al : MonStgElt Default: "Gauss" Reduction: BoolElt Default: false ``` Returns the $n$-th power of a form $f$. The operator ``^'` returns a reduced representative, using the fast composition algorithm of Shanks. In contrast, by default `Power` returns the true composition in the group of forms, unless the parameter `Reduction := true`. The function `Power` takes the further parameter `Al` which specifies whether the algorithm of Gauss or Shanks is used, set to `"Gauss"` by default. The algorithm of Shanks performs partial intermediate reductions, so it is not allowed to select `Al := "Shanks"` and `Reduction := false`. ## Matrix Action The right action of ${\operatorname{SL}}(2,{\mathbb{Z}})$ on the set of quadratic forms of discriminant $D$ is given by the rule $$ f(x,y) \left({r\ s\atop t\ u}\right) = f(rx+sy,tx+uy). $$ ### `f * M: QuadBinElt, GrpMatElt -> QuadBinElt` The right action of $M \in {\operatorname{SL}}(2,{\mathbb{Z}})$ on the binary quadratic form $f$. ## Reduction ### `Reduction(f): QuadBinElt -> QuadBinElt, Mtrx` ### `ReducedForm(f): QuadBinElt -> QuadBinElt, Mtrx` Returns a reduced quadratic form equivalent to $f$, and the transformation matrix. ### `ReductionStep(f): QuadBinElt -> QuadBinElt` The result of applying one reduction step to the quadratic form $f$. ### `ReductionOrbit(f): QuadBinElt -> {@ QuadBinElt @}` For a binary quadratic form $f$ of positive discriminant, this returns an indexed set containing all reduced forms equivalent to $f$. These are obtained by iterating the `ReductionStep` operator, starting with `Reduction(f)`. ### `Order(f): QuadBinElt -> RngIntElt` For a binary quadratic form $f$ of discriminant $D$, this returns the order of $f$ in the class group for discriminant $D$ (see [`ClassGroup`](class-group.md#function-quadbin-classgroup)). Note that the class group is defined using the equivalence relation `IsEquivalent(f1, f2 : Narrow := false)`. ## Attribute Access The coefficient sequence can be accessed as a sequence of integers, providing the inverse operation to the forms coercion constructor. ### `f[i]: QuadBinElt, RngIntElt -> RngIntElt` The $i$-th coefficient of $f$, where $1 \le i \le 3$. ### `Eltseq(f): QuadBinElt -> SeqEnum[RngIntElt]` ### `ElementToSequence(f): QuadBinElt -> SeqEnum[RngIntElt]` The sequence $[a,b,c]$ where $f$ is the form $ax^2 + bxy + cy^2$. ## Boolean Operations ### `f in Q: QuadBinElt, QuadBin -> BoolElt` Return `true` if and only if $f$ is in $Q$, that is $f$ and $Q$ have the same discriminant. ### `f eq g: QuadBinElt, QuadBinElt -> BoolElt` Return `true` if the quadratic form $f$ and $g$ are equal and `false` otherwise. ### `IsIdentity(f): QuadBinElt -> BoolElt` Return `true` if and only if $f$ is the principal form in its parent structure. ### `IsReduced(f): QuadBinElt -> BoolElt` Return `true` if the quadratic form $f$ is reduced; `false` otherwise. ### `IsEquivalent(f, g): QuadBinElt, QuadBinElt -> BoolElt, AlgMatElt` ```magma Narrow: BoolElt Default: true ``` For binary quadratic forms $f$ and $g$ of the same discriminant, this returns whether the forms are equivalent; that is, whether they can be obtained from each other by a unimodular transformation. When the forms are equivalent, a transformation matrix is also returned. If the parameter `Narrow` is `false`, the function tests a different notion of equivalence in the case of positive discriminant, which may be weaker. This is defined by merging the equivalence classes of forms $\langle a,b,c \rangle$ and $\langle -a,b,-c \rangle$ into a single equivalence class. (Another way to describe it is as follows: Forms are equivalent iff their associated ideals are in the same ordinary ideal class. On the other hand, “narrow” equivalence of forms corresponds to narrow ideal classes.) In this case, the transformation matrix may produce the complementary form of $g$. ## Maps of Forms ### `FundamentalQuotient(Q): QuadBin -> Map` The quotient homomorphism from the class group of $Q$ to the class group of fundamental discriminant. ### `QuotientMap(Q1, Q2): QuadBin, QuadBin -> Map` Given two structures of quadratic forms $Q_1$ and $Q_2$, such that the discriminant of $Q_1$ equals a square times the discriminant of $Q_2$, the quotient homomorphism from $Q_1$ to $Q_2$ is returned as a map. ### `Q ! f: QuadBin, QuadBinElt -> QuadBinElt` The `!` operator coerces a binary quadratic form $f$ into the structure $Q$, when they are compatible. This requires that $Q$ is `QuadraticForms(D)` and $f$ has discriminant $m^2D$ for some integer $m$. ## Related Structures ### `Parent(f): QuadBinElt -> QuadBin` ### `Category(Q): QuadBin -> Cat` ### `QuadraticOrder(Q): QuadBin -> RngQuad` Given a structure of quadratic forms of discriminant $D$, returns the quadratic order of discriminant $D$. ### `Ideal(f): QuadBinElt -> RngQuadIdl` Given a quadratic form $f = ax^2 + bxy + cy^2$, returns the ideal $(a,(-b+\sqrt{D})/2)$ in the quadratic order ${\mathbb{Z}}[(t+\sqrt{D})/2]$, where $t$ equals $0$ or $1$.