# Spaces

## Creation of spaces

quadratic_spaceMethod
quadratic_space(K::NumField, n::Int; cached::Bool = true) -> QuadSpace

Create the quadratic space over K with dimension n and Gram matrix equals to the identity matrix.

hermitian_spaceMethod
hermitian_space(E::NumField, n::Int; cached::Bool = true) -> HermSpace

Create the hermitian space over E with dimension n and Gram matrix equals to the identity matrix. The number field E must be a quadratic extension, that is, $degree(E) == 2$ must hold.

quadratic_spaceMethod
quadratic_space(K::NumField, G::MatElem; cached::Bool = true) -> QuadSpace

Create the quadratic space over K with Gram matrix G. The matrix G must be square and symmetric.

hermitian_spaceMethod
hermitian_space(E::NumField, gram::MatElem; cached::Bool = true) -> HermSpace

Create the hermitian space over E with Gram matrix equals to gram. The matrix gram must be square and hermitian with respect to the non-trivial automorphism of E. The number field E must be a quadratic extension, that is, $degree(E) == 2$ must hold.

### Examples

Here are easy examples to see how these constructors work. We will keep the two following spaces for the rest of this section:

julia> K, a = CyclotomicRealSubfield(7);julia> Kt, t = K["t"];julia> E, b = number_field(t^2-a*t+1, "b");julia> Q = quadratic_space(K, K[0 1; 1 0])Quadratic space over
Maximal real subfield of cyclotomic field of order 7
with Gram matrix
[0 1; 1 0]julia> H = hermitian_space(E, 3)Hermitian space over
Relative number field with defining polynomial t^2 - (z_7 + 1/z_7)*t + 1
over Maximal real subfield of cyclotomic field of order 7
with Gram matrix
[1 0 0; 0 1 0; 0 0 1]

## Attributes

Let $(V, \Phi)$ be a space over $E/K$. We define its dimension to be its dimension as a vector space over its base ring $E$ and its rank to be the rank of its Gram matrix. If these two invariants agree, the space is said to be regular.

While dealing with lattices, one always works with regular ambient spaces.

The determinant $\text{det}(V, \Phi)$ of $(V, \Phi)$ is defined to be the class of the determinant of its Gram matrix in $K^{\times}/N(E^{\times})$ (which is similar to $K^{\times}/(K^{\times})^2$ in the quadratic case). The discriminant $\text{disc}(V, \Phi)$ of $(V, \Phi)$ is defined to be $(-1)^{(m(m-1)/2)}\text{det}(V, \Phi)$, where $m$ is the rank of $(V, \Phi)$.

rankMethod
rank(V::AbsSpace) -> Int

Return the rank of the space V.

dimMethod
dim(V::AbsSpace) -> Int

Return the dimension of the space V.

gram_matrixMethod
gram_matrix(V::AbsSpace) -> MatElem

Return the Gram matrix of the space V.

involutionMethod
involution(V::AbsSpace) -> NumField

Return the involution of the space V.

base_ringMethod
base_ring(V::AbsSpace) -> NumField

Return the algebra over which the space V is defined.

fixed_fieldMethod
fixed_field(V::AbsSpace) -> NumField

Return the fixed field of the space V.

detMethod
det(V::AbsSpace) -> FieldElem

Return the determinant of the space V as an element of its fixed field.

discriminantMethod
discriminant(V::AbsSpace) -> FieldElem

Return the discriminant of the space V as an element of its fixed field.

### Examples

So for instance, one could get the following information about the hermitian space $H$:

julia> K, a = CyclotomicRealSubfield(7);julia> Kt, t = K["t"];julia> E, b = number_field(t^2-a*t+1, "b");julia> H = hermitian_space(E, 3);julia> rank(H), dim(H)(3, 3)julia> gram_matrix(H)[1   0   0]
[0   1   0]
[0   0   1]julia> involution(H)Map with following data
Domain:
=======
Relative number field with defining polynomial t^2 - (z_7 + 1/z_7)*t + 1
over Maximal real subfield of cyclotomic field of order 7
Codomain:
=========
Relative number field with defining polynomial t^2 - (z_7 + 1/z_7)*t + 1
over Maximal real subfield of cyclotomic field of order 7julia> base_ring(H)Relative number field with defining polynomial t^2 - (z_7 + 1/z_7)*t + 1
over Maximal real subfield of cyclotomic field of order 7julia> fixed_field(H)Maximal real subfield of cyclotomic field of order 7julia> det(H), discriminant(H)(1, -1)

## Predicates

Let $(V, \Phi)$ be a hermitian space over $E/K$ (resp. quadratic space $K$). We say that $(V, \Phi)$ is definite if $E/K$ is CM (resp. $K$ is totally real) and if there exists an orthogonal basis of $V$ for which the diagonal elements of the associated Gram matrix of $(V, \Phi)$ are either all totally positive or all totally negative. In the former case, $V$ is said to be positive definite, while in the latter case it is negative definite. In all the other cases, we say that $V$ is indefinite.

is_regularMethod
is_regular(V::AbsSpace) -> Bool

Return whether the space V is regular, that is, if the Gram matrix has full rank.

is_quadraticMethod
is_quadratic(V::AbsSpace) -> Bool

Return whether the space V is quadratic.

ishermitianMethod
ishermitian(V::AbsSpace) -> Bool

Return whether the space V is hermitian.

is_positive_definiteMethod
is_positive_definite(V::AbsSpace) -> Bool

Return whether the space V is positive definite.

is_negative_definiteMethod
is_negative_definite(V::AbsSpace) -> Bool

Return whether the space V is negative definite.

is_definiteMethod
is_definite(V::AbsSpace) -> Bool

Return whether the space V is definite.

Note that the ishermitian function tests whether the space is non-quadratic.

### Examples

julia> K, a = CyclotomicRealSubfield(7);julia> Kt, t = K["t"];julia> E, b = number_field(t^2-a*t+1, "b");julia> Q = quadratic_space(K, K[0 1; 1 0]);julia> H = hermitian_space(E, 3);julia> is_regular(Q), is_regular(H)(true, true)julia> is_quadratic(Q), ishermitian(H)(true, true)julia> is_definite(Q), is_positive_definite(H)(false, true)

## Inner products and diagonalization

gram_matrixMethod
gram_matrix(V::AbsSpace, M::MatElem) -> MatElem

Return the Gram matrix of the rows of M with respect to the Gram matrix of the space V.

gram_matrixMethod
gram_matrix(V::AbsSpace, S::Vector{Vector}) -> MatElem

Return the Gram matrix of the sequence S with respect to the Gram matrix of the space V.

inner_productMethod
inner_product(V::AbsSpace, v::Vector, w::Vector) -> FieldElem

Return the inner product of v and w with respect to the bilinear form of the space V.

orthogonal_basisMethod
orthogonal_basis(V::AbsSpace) -> MatElem

Return a matrix M, such that the rows of M form an orthogonal basis of the space V.

diagonalMethod
diagonal(V::AbsSpace) -> Vector{FieldElem}

Return a vector of elements $a_1,\dotsc,a_n$ such that the space V is isometric to the diagonal space $\langle a_1,\dotsc,a_n \rangle$.

The elements are contained in the fixed field of V.

restrict_scalarsMethod
restrict_scalars(V::AbsSpace, K::FlintRationalField,
alpha::FieldElem = one(base_ring(V)))
-> QuadSpace, SpaceRes

Given a space $(V, \Phi)$ and a subfield K of the base algebra E of V, return the quadratic space W obtained by restricting the scalars of $(V, \alpha\Phi)$ to K, together with the map f for extending the scalars back. The form on the restriction is given by $Tr \circ \Phi$ where $Tr: E \to K$ is the trace form. The rescaling factor $\alpha$ is set to 1 by default.

Note that for now one can only restrict scalars to $\mathbb Q$.

### Examples

julia> K, a = CyclotomicRealSubfield(7);julia> Kt, t = K["t"];julia> E, b = number_field(t^2-a*t+1, "b");julia> Q = quadratic_space(K, K[0 1; 1 0]);julia> H = hermitian_space(E, 3);julia> gram_matrix(Q, K[1 1; 2 0])[2   2]
[2   0]julia> gram_matrix(H, E[1 0 0; 0 1 0; 0 0 1])[1   0   0]
[0   1   0]
[0   0   1]julia> inner_product(Q, [1, 1], [0, 2])ERROR: MethodError: no method matching *(::Vector{Int64}, ::AbstractAlgebra.Generic.MatSpaceElem{nf_elem})
Closest candidates are:
*(::Any, ::Any, !Matched::Any, !Matched::Any...) at operators.jl:560
*(::StridedVecOrMat{T} where T, !Matched::LinearAlgebra.Adjoint{var"#s814", var"#s813"} where {var"#s814", var"#s813"<:LinearAlgebra.LQPackedQ}) at /buildworker/worker/package_linux64/build/usr/share/julia/stdlib/v1.6/LinearAlgebra/src/lq.jl:254
*(::StridedVecOrMat{T} where T, !Matched::LinearAlgebra.LQPackedQ) at /buildworker/worker/package_linux64/build/usr/share/julia/stdlib/v1.6/LinearAlgebra/src/lq.jl:278
...julia> orthogonal_basis(H)[1   0   0]
[0   1   0]
[0   0   1]julia> diagonal(Q), diagonal(H)(nf_elem[1, -1], nf_elem[1, 1, 1])

## Equivalence

Let $(V, \Phi)$ and $(V', \Phi')$ be spaces over the same extension $E/K$. A homomorphism of spaces from $V$ to $V'$ is a $E$-linear mapping $f \colon V \to V'$ such that for all $x,y \in V$, one has

$$$\Phi'(f(x), f(y)) = \Phi(x,y).$$$

An automorphism of spaces is called an isometry and a monomorphism is called an embedding.

hasse_invariantMethod
hasse_invariant(V::QuadSpace, p::Union{InfPlc, NfOrdIdl}) -> Int

Returns the Hasse invariant of the quadratic space V at p. This is equal to the product of local Hilbert symbols $(a_i, a_j)_p$, $i < j$, where $V$ is isometric to $\langle a_1, \dotsc, a_n\rangle$. If V is degenerate return the hasse invariant of V/radical(V).

witt_invariantMethod
witt_invariant(V::QuadSpace, p::Union{InfPlc, NfOrdIdl}) -> Int

Returns the Witt invariant of the quadratic space V at p.

See [Definition 3.2.1, Kir16].

is_isometricMethod
is_isometric(L::AbsSpace, M::AbsSpace) -> Bool

Return whether the spaces L and M are isometric.

is_isometricMethod
is_isometric(L::AbsSpace, M::AbsSpace, p::Union{InfPlc, NfOrdIdl}) -> Bool

Return whether the spaces L and M are isometric over the completion at p.

invariantsMethod
invariants(M::QuadSpace)
-> FieldElem, Dict{NfOrdIdl, Int}, Vector{Tuple{InfPlc, Int}}

Returns a tuple (n, k, d, H, I) of invariants of M, which determine the isometry class completely. Here n is the dimension. The dimension of the kernel is k. The element d is the determinant of a Gram matrix of the non-degenerate part, H contains the non-trivial Hasse invariants and I contains for each real place the negative index of inertia.

Note that d is determined only modulo squares.

### Examples

For instance, for the case of $Q$ and the totally ramified prime $\mathfrak p$ of $O_K$ above $7$, one can get:

julia> K, a = CyclotomicRealSubfield(7);julia> Q = quadratic_space(K, K[0 1; 1 0]);julia> OK = maximal_order(K);julia> p = prime_decomposition(OK, 7);julia> hasse_invariant(Q, p), witt_invariant(Q, p)(1, 1)julia> Q2 = quadratic_space(K, K[-1 0; 0 1]);julia> is_isometric(Q, Q2, p)truejulia> is_isometric(Q, Q2)truejulia> invariants(Q2)(2, 0, -1, Dict{NfOrdIdl, Int64}(), Tuple{InfPlc, Int64}[(Real place of
Maximal real subfield of cyclotomic field of order 7
corresponding to the root [-1.801937735804838252472204639014890102331838324263714300107124846398864840856 +/- 2.23e-76], 1), (Real place of
Maximal real subfield of cyclotomic field of order 7
corresponding to the root [-0.4450418679126288085778051289935895189327111375290899106239740317948424640571 +/- 4.42e-77], 1), (Real place of
Maximal real subfield of cyclotomic field of order 7
corresponding to the root [1.2469796037174670610500097680084796212645494617928042107310988781937073049130 +/- 6.52e-77], 1)])

## Embeddings

Let $(V, \Phi)$ and $(V', \Phi')$ be two spaces over the same extension $E/K$, and let $\sigma \colon V \to V'$ be an $E$-linear morphism. $\sigma$ is called a representation of $V$ into $V'$ if for all $x \in V$

$$$\Phi'(\sigma(x), \sigma(x)) = \Phi(x,x).$$$

In such a case, $V$ is said to be represented by $V'$ and $\sigma$ can be seen as an embedding of $V$ into $V'$. This representation property can be also tested locally with respect to the completions at some finite places. Note that in both quadratic and hermitian cases, completions are taken at finite places of the fixed field $K$.

is_locally_represented_byMethod
is_locally_represented_by(U::T, V::T, p::NfOrdIdl) where T <: AbsSpace -> Bool

Given two spaces U and V over the same algebra E, and a prime ideal p in the maximal order $\mathcal O_K$ of their fixed field K, return whether U is represented by V locally at p, i.e. whether $U_p$ embeds in $V_p$.

is_represented_byMethod
is_represented_by(U::T, V::T) where T <: AbsSpace -> Bool

Given two spaces U and V over the same algebra E, return whether U is represented by V, i.e. whether U embeds in V.

### Examples

Still using the spaces $Q$ and $H$, we can decide whether some other spaces embed respectively locally or globally into $Q$ or $H$:

julia> K, a = CyclotomicRealSubfield(7);julia> Kt, t = K["t"];julia> E, b = number_field(t^2-a*t+1, "b");julia> Q = quadratic_space(K, K[0 1; 1 0]);julia> H = hermitian_space(E, 3);julia> OK = maximal_order(K);julia> p = prime_decomposition(OK, 7);julia> Q2 = quadratic_space(K, K[-1 0; 0 1]);julia> H2 = hermitian_space(E, E[-1 0 0; 0 1 0; 0 0 -1]);julia> is_locally_represented_by(Q2, Q, p)truejulia> is_represented_by(Q2, Q)truejulia> is_locally_represented_by(H2, H, p)truejulia> is_represented_by(H2, H)false

## Orthogonality operations

orthogonal_complementMethod
orthogonal_complement(V::AbsSpace, M::MatElem)

Given a space V and a subspace W with basis matrix M, returns a basis matrix of the orthogonal complement of W inside V.

orthogonal_sumMethod
orthogonal_sum(V::AbsSpace, W::AbsSpace) -> AbsSpace, AbsSpaceMor, AbsSpaceMor

Given two spaces V and W of the same kind (either both hermitian or both quadratic) and defined over the same algebra, return their orthogonal sum $V \oplus W$. It is given with the two natural embeddings $V \to V\oplus W$ and $W \to V\oplus W$.

### Example

julia> K, a = CyclotomicRealSubfield(7);julia> Kt, t = K["t"];julia> E, b = number_field(t^2-a*t+1, "b");julia> Q = quadratic_space(K, K[0 1; 1 0]);julia> H = hermitian_space(E, 3);julia> H2 = hermitian_space(E, E[-1 0 0; 0 1 0; 0 0 -1]);julia> orthogonal_complement(Q, matrix(K, 1, 2, [1 0]))[1   0]julia> H3, map1, map2 = orthogonal_sum(H, H2);julia> H3Hermitian space over
Relative number field with defining polynomial t^2 - (z_7 + 1/z_7)*t + 1
over Maximal real subfield of cyclotomic field of order 7
with Gram matrix
[1 0 0 0 0 0; 0 1 0 0 0 0; 0 0 1 0 0 0; 0 0 0 -1 0 0; 0 0 0 0 1 0; 0 0 0 0 0 -1]julia> map1Map with following data
Domain:
=======
Hermitian space over
Relative number field with defining polynomial t^2 - (z_7 + 1/z_7)*t + 1
over Maximal real subfield of cyclotomic field of order 7
with Gram matrix
[1 0 0; 0 1 0; 0 0 1]
Codomain:
=========
Hermitian space over
Relative number field with defining polynomial t^2 - (z_7 + 1/z_7)*t + 1
over Maximal real subfield of cyclotomic field of order 7
with Gram matrix
[1 0 0 0 0 0; 0 1 0 0 0 0; 0 0 1 0 0 0; 0 0 0 -1 0 0; 0 0 0 0 1 0; 0 0 0 0 0 -1]julia> map2Map with following data
Domain:
=======
Hermitian space over
Relative number field with defining polynomial t^2 - (z_7 + 1/z_7)*t + 1
over Maximal real subfield of cyclotomic field of order 7
with Gram matrix
[-1 0 0; 0 1 0; 0 0 -1]
Codomain:
=========
Hermitian space over
Relative number field with defining polynomial t^2 - (z_7 + 1/z_7)*t + 1
over Maximal real subfield of cyclotomic field of order 7
with Gram matrix
[1 0 0 0 0 0; 0 1 0 0 0 0; 0 0 1 0 0 0; 0 0 0 -1 0 0; 0 0 0 0 1 0; 0 0 0 0 0 -1]

## Isotropic spaces

Let $(V, \Phi)$ be a space over $E/K$ and let $\mathfrak p$ be a place in $K$. $V$ is said to be isotropic locally at $\mathfrak p$ if there exists an element $x \in V_{\mathfrak p}$ such that $\Phi_{\mathfrak p}(x,x) = 0$, where $\Phi_{\mathfrak p}$ is the continuous extension of $\Phi$ to $V_{\mathfrak p} \times V_{\mathfrak p}$.

is_isotropicMethod
is_isotropic(V::AbsSpace, p::Union{NfOrdIdl, InfPlc}) -> Bool

Given a space V and a place p in the fixed field K of V, return whether the completion of V at p is isotropic.

### Example

julia> K, a = CyclotomicRealSubfield(7);julia> Kt, t = K["t"];julia> E, b = number_field(t^2-a*t+1, "b");julia> H = hermitian_space(E, 3);julia> OK = maximal_order(K);julia> p = prime_decomposition(OK, 7);julia> is_isotropic(H, p)true

## Hyperbolic spaces

Let $(V, \Phi)$ be a space over $E/K$ and let $\mathfrak p$ be a prime ideal of $\mathcal O_K$. $V$ is said to be hyperbolic locally at $\mathfrak p$ if the completion $V_{\mathfrak p}$ of $V$ can be decomposed as an orthogonal sum of dimension 2 spaces with Gram matrices of the form $\left(\begin{array}{cc} 0&1\\1&0 \end{array}\right)$.

is_locally_hyperbolicMethod
is_locally_hyperbolic(V::Hermspace, p::NfOrdIdl) -> Bool

Return whether the completion of the hermitian space V over $E/K$ at the prime ideal p of $\mathcal O_K$ is hyperbolic.

### Example

julia> K, a = CyclotomicRealSubfield(7);julia> Kt, t = K["t"];julia> E, b = number_field(t^2-a*t+1, "b");julia> H = hermitian_space(E, 3);julia> OK = maximal_order(K);julia> p = prime_decomposition(OK, 7);julia> is_locally_hyperbolic(H, p)false