wip: doc for WedderburnDecomposition (#42)

* wip: doc for WedderburnDecomposition

* wip: readme, wdec

* wip: readme, wdec

* final version: README, WedderburnDecomposition

* rewrite README

* small fixes in docstring of symmetry_adapted_basis

* document methods using WedderburnDecomposition, not its fields

* fix typos

Co-authored-by: Benoît Legat <[email protected]>

* fix typos

Co-authored-by: Benoît Legat <[email protected]>

* fix typos

Co-authored-by: Benoît Legat <[email protected]>

Co-authored-by: Marek Kaluba <[email protected]>
Co-authored-by: Marek Kaluba <[email protected]>
Co-authored-by: Benoît Legat <[email protected]>

README.md

@@ -3,3 +3,40 @@
 [![codecov](https://codecov.io/gh/kalmarek/SymbolicWedderburn.jl/branch/master/graph/badge.svg)](https://codecov.io/gh/kalmarek/SymbolicWedderburn.jl)
 
 Amazing package providing symbolic Wedderburn decompositions for group *-algebras.
+Group *-algebras are closely related to
+* linear actions of **finite groups** on **finite dimensional** `k`-vector space `V` (i.e. a `k(G)`-module structure on `V`), which can be expressed in the language of
+* representations `ρ : G → GL(V)` of a (finite) group `G` on a (finite dimensional) `k`-vector space `V`.
+
+These objects naturally arise from (non)commutative polynomial optimization with symmetry and the aim of the package is to facilitate such uses.
+
+By Masche's theorem, `V ≅ m₁V₁ ⊕ ⋯ ⊕ mᵣVᵣ ≅ W₁ ⊕ ⋯ ⊕ Wᵣ` can be decomposed uniquely into isotypic/semisimple components `Wᵢ` and nonuniquely into irreducible/simple components `Vᵢ` associated with a group `G`. By (symbolic) computation in `k(G)`, `SymbolicWedderburn.jl` is capable of producing exact
+* isomorphism `V ≅ W₁ ⊕ ⋯ ⊕ Wᵣ`, or
+* projection `V → V₁ ⊕ ⋯ ⊕ Vᵣ`.
+
+The isomorphism gives a decomposition of `End_G(V)` in the sense of Wedderburn-Artin theorem. The projection is enough to reconstruct any matrix `P ∈ End_G(V)'` in the commutant of the endomorphism algebra.
+
+In case of problems of positive semidefinite optimization which enjoy group symmetry this decomposition can be used to reduce an **invariant** psd constraint
+
+> `0 ⪯ P[1:N, 1:N]`
+
+(where `N = dim(V)` is the dimension of `V`), to a sequence of constraints
+> `0 ⪯ P[1:nᵢ, 1:nᵢ]` where `i = 1...r`,
+
+greatly reducing the computational complexity.
+When computing decomposition into isotypic/semisimple components `Wᵢ` we have `nᵢ = mᵢ·dim(Vᵢ)`,
+thus the size of psd constraint is reduced from `N²` to `Σᵢ nᵢ²` where `N = Σᵢ nᵢ`.
+Sometimes even stronger reduction is possible (when the acting group `G` is _sufficiently complicated_ and a heuristic algorithm finding a minimal projection system is successful).
+In such case each `nᵢ = mᵢ`.
+
+
+This package is used by [SumOfSquares.jl](https://github.com/jump-dev/SumOfSquares.jl) to perform exactly this reduction, for an example use see its [documentation](https://jump.dev/SumOfSquares.jl/latest/generated/Symmetry/dihedral_symmetry_of_the_robinson_form/).
+
+#### Related software
+The main aim of `GAP` package [`Wedderga`](https://www.gap-system.org/Manuals/pkg/wedderga/doc/chap0.html) is to
+
+> compute the simple components of the Wedderburn decomposition of semisimple group algebras of finite groups over finite fields and over subfields of finite cyclotomic extensions of the rationals.
+
+The focus is thus on symbolic computations and identifying _isomorphism type_ of the simple components.
+`SymbolicWedderburn.jl` makes no efforts to compute the types or defining fields,
+it's primary goal is to compute symbolic/numerical Wedderburn-Artin isomorphism in a form usable for (polynomial) optimization. `Wedderga` also contains much more sophisticated methods for computing _a complete set of orthogonal primitive idempotents_ (i.e. a minimal projection system) through Shoda pairs.
+In principle those idempotents could be computed using `Oscar.jl` and used in `SymbolicWedderburn.jl`.

src/actions.jl

@@ -10,6 +10,9 @@ implements:
 * action(hom::InducedActionHomomorphism, g::GroupElement, feature) → the action of `g` on `feature`
 =#
 
+"""
+Compute the vector g⋅v which is the result of acting g on v by permutation.
+"""
 function action(
     hom::InducedActionHomomorphism{<:ByPermutations},
     g::GroupElement,
@@ -18,6 +21,9 @@ function action(
     return v^induce(hom, g)
 end
 
+"""
+Compute the vector g⋅v which is the result of acting g on v by linear transformation.
+"""
 function action(
     hom::InducedActionHomomorphism{<:ByLinearTransformation},
     g::GroupElement,
@@ -49,6 +55,9 @@ coeff_type(::ByPermutations) = Int
 _int_type(::Type{<:InducedActionHomomorphism}) = UInt16
 _int_type(hom::InducedActionHomomorphism) = _int_type(typeof(hom))
 
+"""
+Compute the (sparse) matrix corresponding to g acting by linear transformation.
+"""
 function induce(
     ac::ByLinearTransformation,
     hom::InducedActionHomomorphism,

src/sa_basis.jl

@@ -26,38 +26,6 @@ function affordable_real(
     return irr_real, mls_real
 end
 
-"""
-    symmetry_adapted_basis([T::Type,] G::AbstractPermutationGroup[, S=Rational{Int};
-        semisimple=false])
-Compute a basis for the linear space `ℝⁿ` (where `n = degree(G)`) which is
-invariant under the symmetry of `G`.
-
-The basis is returned as a vector of `DirectSummand{T}`s (blocks) corresponding
-to the irreducible characters of `G`. The blocks are orthogonal to **each other**,
-however vectors within a single block may *not* be orthogonal.
-If `T<:LinearAlgebra.BlasFloat` BLAS routines will be used to orthogonalize
-vectors within each `DirectSummand`.
-
-Arguments:
-* `S` controls the types of `Cyclotomic`s used in the computation of
-character table. Exact type are preferred. For larger groups `G` `Rational{BigInt}`
-might be necessary.
-* `T` controls the type of coefficients of the returned basis.
-* `semisimple`: if set to `false` (the default) an effort to find minimal
-projection system is made, so that each block defines a projection to a single
-simple summand within each (isotypical) block. Otherwise an isomorphism to the
-semisimple decomposition is computed.
-
-!!! Note:
-Each returned block (a `DirectSummand`) is invariant under the action of `G`,
-which means that the action may still e.g. permute (row) vectors , but only
-*within* each block.
-
-When `semisimple=true` the blocks constitute an isomorphism. Otherwise blocks
-may represent only a projection onto the commutant of the appropriate matrix
-algebra (which has in general lower dimension). This happens precisely when
-`issimple` on a block returns `true` and `SymbolicWedderburn.degree(ds) == 1`.
-"""
 function symmetry_adapted_basis(
     G::PermutationGroups.AbstractPermutationGroup,
     S::Type = Rational{Int};
@@ -67,6 +35,48 @@ function symmetry_adapted_basis(
     return symmetry_adapted_basis(eltype(tbl), tbl, semisimple = semisimple)
 end
 
+"""
+    symmetry_adapted_basis([T::Type,] G::AbstractPermutationGroup[, S=Rational{Int};
+        semisimple=false])
+Compute a decomposition of `V=𝕂ⁿ` (with `n = degree(G)`) into
+subspaces invariant under the natural permutation action of `G`.
+
+Consider the decomposition of `V` into irreducible (simple) subspaces
+    `V ≅ m₁V₁ ⊕ ⋯ ⊕ mᵣVᵣ`
+and write `Wᵢ = mᵢVᵢ` (the `mᵢ`-fold direct sum of `Vᵢ`). The decomposition is
+returned as a vector of `DirectSummand{T}`s (blocks) corresponding
+to the distinct irreducible characters of `G` (i.e. types of action, here from `1`
+to `r`). Each block contains a basis for a `G`-invariant subspace in `V` (`Vᵢ` or `Wᵢ`). The blocks are guaranteed to be orthogonal to **each other**, however vectors within a single block may *not* be orthogonal.
+
+If `T<:LinearAlgebra.BlasFloat` BLAS routines will be used to orthogonalize
+vectors within each block.
+
+!!! note:
+Each returned block is invariant (as a subspace) under the action of `G`, which
+means that the action may still e.g. permute (row) vectors, but only *within* each block.
+
+Arguments:
+* `T` controls the type of coefficients of the returned basis. Unless specified,
+the coefficients will be computed exactly in the field of cyclotomic numbers.
+If you know that the group has rational characters only (which happens e.g. for
+the full symmetric groups) You may specify `Rational{Int}` here. For a group
+with complex characters specifying `T<:Real` will result in the computation of the realified basis.
+* `S` controls the types of `Cyclotomic`s used in the computation of
+character table. Exact type are preferred. For larger groups `G` (or if
+overflow occurs during the computation of characters) specifying
+`Rational{BigInt}` might be necessary.
+* `semisimple::Bool` controls the nature of the the returned basis.
+  - `semisimple=true`: the returned basis consists of orthogonal blocks
+  (`DirectSummand`s) which define an isomorphism
+  `V ≅ Wₖ ⊕ ⋯ ⊕ Wₖ`.
+  associated to isotypical components `Wₖ`, which are (in general) semi-simple.
+  I.e. each direct summand `ds` may further decopose into `G`-invariant
+  subspaces `Wₖ ≅ mₖVₖ`, all of the same _type_. Multiplicity `mₖ` can be
+  obtained by calling `multiplicity(@ref)`.
+  - `semisimple=false`: (the default) In addition to finding blocks `Wₖ`, an
+  effort to find _minimal projection system_ is made, i.e all, some (or none!)
+  of the returned blocks corresponds to a **projection** `V → Wₖ ≅ mₖVₖ → Vₖ` for a single irreducible subspace `Vₖ`. This means that some blocks can not be further decomposed into nontrivial `G`-invariant subspaces.
+"""
 symmetry_adapted_basis(
     T::Type,
     G::PermutationGroups.AbstractPermutationGroup,
@@ -99,14 +109,16 @@ end
 """
     symmetry_adapted_basis([T::Type,] G::Group, action, basis[, S=Rational{Int}];
         semisimple=false)
-Compute a decomposition of basis into (semi)simple subspaces which are invariant under
-the action of `G`.
+Compute a decomposition of `V=⟨basis⟩` into subspaces invariant under the
+given action of `G`.
 
 It is assumed that `G` acts on a subset of basis and the action needs to be
 extended to the whole `basis`. If `G` is a permutation group already acting on
 the whole `basis`, a call to `symmetry_adapted_basis(G)` is preferred.
+
 * For inducing the action `basis` needs to be indexable and iterable
 (e.g. in the form of an `AbstractVector`).
+
 """
 function symmetry_adapted_basis(
     G::Group,

src/wedderburn_decomposition.jl

@@ -5,6 +5,25 @@ struct WedderburnDecomposition{B,iV,DS<:DirectSummand,Hom}
     hom::Hom
 end
 
+"""
+    WedderburnDecomposition([T::Type, ]G::Group, action::Action, basis_full, basis_half[, S; semisimple])
+Compute `WedderburnDecomposition` related to `G` acting on `basis_half`, representing a form of Wedderburn-Artin decomposition.
+
+This object is intended to be used to simplify problems of positive-semidefinite optimization.
+# Arguments
+ * `basis_full` corresponds to the basis (or index set) for the objective functional (the set of constraints);
+ * `basis_half` corresponds to the basis (or index set) of the PSD constraint.
+
+For description of the remaining arguments see [symmetry_adapted_basis](@ref).
+
+Return a `wd::WedderburnDecomposition` object which defines:
+ * `basis(wd)`: the original `basis_full`.
+ * `invariant_vectors(wd)`: a basis for the subspace `⟨basis_full⟩^G` invariant under the action of `G`.
+ * `direct_summands(wd)`: a vector of `DirectSummands` defining a map from `⟨basis_half⟩` to a direct (orthogonal) sum of subspaces
+ * `diagonalize(M::AbstractMatrix, wd::WedderburnDecomposition)`: a map implementing the Wedderburn-Artin decomposition for matrices `M ∈ End(⟨basis_half⟩)` (i.e. with rows and columns indexed by the elements of `basis_half`).
+
+See also: [symmetry_adapted_basis](@ref).
+"""
 function WedderburnDecomposition(
     T::Type,
     G::Group,