SeDiMO v3
=========

What is this?
-------------
This is the documentation for version 3 of SeDiMO, a GAP-package for
computing the dimensions of the higher secant varieties of the minimal
orbit in an irreducible representation of a complex semisimple group.

What does it compute?
---------------------
Let G be such a group and let V be a non-trivial irreducible
representation of G. Let B be a Borel subgroup of G and let v0 be the
highest weight vector in V relative to B. Then the set C=(Gv0 union {0})
is the affine cone over the minimal orbit X in the projective space PV,
and likewise the closure of the set

	kC:={(v1+...+vk) | vi in C}, k a natural number

is the affine cone over the (k-1)st secant variety of X. It is the
dimension of kC that is computed in by the program. So if you want to
know, say, the dimension of the chordal variety of X (the closure of the
union of all projective lines spanned by 2 points on X), then you should
compute SecantDimension(2)-1; though see below for the exact syntax.

In principle, the result of SecantDimension(k) is a _lower bound_
to dim(kC), which with high probability is correct. Hence, if
SecantDimension(k) is the `expected dimension' k*dim(C), then you can
be _sure_ that kC has the expected dimension. However, if the outcome is
smaller, then you should redo the computations a few times---discarding
the results of previous computations in between; see below why and
how. If SecantDimension(k) keeps on returning the same number smaller
than k*dim(C), then you can be fairly sure that SecantDimension(k) is
really equal to dim(kC)---a good incentive to try and prove that the
(k-1)st secant variety of X is defective.

How do I use it?
----------------
1. Install GAP on your machine; see http://www-gap.mcs.st-and.ac.uk/
2. Enter the directory sedimovi, where i is the version of our program 
that you downloaded.
3. Run GAP from there.
4. Read our program (this will also load the quagroup package, as well 
as the functions in kostantbasis.g and sparse.g):

gap> Read("sedimo1.g");

5. Now you are ready to use the program!
G is encoded by its Lie algebra g. So, first construct g as a (direct
sum of) simple Lie algebra(s) over the Rationals, for instance:

gap> h:=SimpleLieAlgebra("A",3,Rationals);
gap> g:=DirectSumOfAlgebras([h,h]);

(You may of course choose another letter for g and the variables that
follow.) The module depends on the highest weight:

gap> hw:=[1,0,0,0,0,1];

Now some global variables have to be set for the computations that
follow. This is done as follows:

gap> Results:=InitialData(g,hw,GF(29));;

Here you can replace GF(29) by any field, though it probably only makes
sense to use the prime fields GF(prime) and Rationals. You have to
choose whether you want to do the computations over a finite field or
not. Choosing a small field sometimes makes computations faster, but the
probability of SecantDimension(k) being erroneously smaller than dim(kC)
becomes larger.

The assignment above initialises a record Results, some fields of which
are needed in the secant dimension computations that follow, while the the
results of those computations will be stored in other fields of Results.

Finally, you can type, for instance:

gap> SecantDimension(2,Results);

which returns: 12. Note that in this case V is the space of 4x4-matrices,
acted upon by SL_4 x SL_4 by left-and-right multiplication; C is the set
of matrices of rank at most 1, and 2C is the set of matrices of rank 2,
which is, indeed, 12-dimensional.

If you have once computed SecantDimension(k,Results), then all dimensions
for l<=k are stored in Results and used in further computations. In
particular, if you then compute SecantDimension(l) for l<=k, the
answer computed earlier will be returned instantaneously, while the
SecantDimension(l) for l>k will depend on the results so far. If you do
not trust the outcome so far, or if you want to double-check it, and if
you do trust the outcome up to l for a certain l<k, then you can type:

gap> Discard(l,Results);

And compute again:

gap> SecantDimension(k,Results);

As explained before, you should do this discarding a few times if
SecantDimension(k,Results) is smaller than (you) expected.

How does it work?
-----------------
Choose a maximal torus T in B, let P>=B be the stabiliser of the line
spanned by v0, and let U_ be the unipotent subgroup of G spanned by all
the T-root subgroups of G _not_ in P. Then the U_ - orbit C':=U_v0 is
the intersection of Gv0 with an affine hyperplane, and the set

	C'':={tv| t a complex number v and element of C'}

is dense in C. By Terracini's Lemma we have 

	dim(kC)=dim(kC'')=
		The dimension of T_{v1} C'' + ... + T_{vk} C'' (*)

for generic v1,...,vk in C'', where T_v C'' is the tangent space to C''
at v. This tangent space, in turn, is equal to the span of v and u_ v,
where u_ is the Lie algebra of U_. The basic idea is to choose random
elements g1,...,gk in U_ and compute the dimension of the dimension of (*)
for vi=gi v0. Note that this always gives a lower bound to the dimension
of dim(kC).

To work modulo a prime number p we actually do the following. First we
compute the matrices u1,...,ur of a Chevalley basis of u_ acting on
a Kostant basis of the module, as well as all their `divided powers'
(ui^n)/(n!)---which are integral!---that are non-zero. We then tensor
all these matrices with the required field. The random gi are, in fact,
random elements of the corresponding Chevalley group, each of them
computed as follows: we generate r random elements t1,...,tr of GF(p)
finite field and we compute the element

	g:=exp(t1 u1)...exp(tp up)

of the Chevalley group. This element is applied to v0, and the tangent
space is the GF(p)-space spanned gv0 and g<u1 v0,...,ur v0>.

Note that the dimension of (*) computed in this manner modulo p is a
lower bound to the dimension of (*) without reduction---in particular,
if it equals the largest possible k*dim(C), the outcome proves that this
is the dimension of dim(kC).

For details on all this, see the paper "Secant dimensions: computations 
and conjectures" by Karin Baur, Jan Draisma, and Willem A. de Graaf.
