MeatAxe
2.4

zsp [Options] [1emc] [b Bas] [s Sub] [q Quot] [o Scr] [n Vector] [d MaxDim] [x MaxTries] Gen1 Gen2 Seed zsp [Options] [1emc] [b Bas] [s Sub] [q Quot] [o Scr] [n Vector] [d MaxDim] [x MaxTries] [g NGen] Gen Seed
This program takes as input a set of matrices or permutations (the "generators"), and a list of seed vectors. It uses the spinup algorithm to find a subspace which is invariant under the generators. If the generators are matrices, zsp can optionally split the representation, i.e., calculate the action of the generators on both subspace and quotient. Splitting is currently not possible for permutations.
There are two ways to inkove zsp. The first form, without ‘g’ expects three arguments, the two generators and the seed vector file. For example,  zsp mat1 mat2 seed reads the generators from ‘mat1’ and ‘mat2’, and the seed vector from ‘seed’.
If the number of generators is not two, you must use the second form, which expects only two arguments. The first argument is treated as a base name. The actual file names are built by appending suffixes ".1", ".2",... to Gen. For example,
zsp g 3 module seed
reads three genrators from "module.1", "module.2", and "module.3". The last argument, Seed is always treated as a single file name, containing the seed vectors. Of course, the seed vectors must be compatible with the generators, i.e., they must be over the save field and have the same number of columns. The generators must be square matrices of the same size and over the same field.
zsp has three ways of interpreting the seed vector file. The default is to treat Seed as a list of seed vectors, which are used onybyone until one seed vector is successful (see below for the meaning of successful), or until all vectors have been used. Normally, zsp starts with the first row of Seed, but this can be changed using the ‘n’ option. For example,
zsp n 4 gen1 gen2 seed
starts with spinning up the fourth row of "seed". If this is not successful, zsp continues with row 5 and so on up to the end of the seed vector file.
With "1" zsp spins up only the first seed vector and stops, even if the spinup was not successful. You can use "n" to select a different row as seed vector. If any of these options is used, zsp loads only the seed vectors that are actually needed.
If you use the "m" option, zsp treats Seed as the basis of a seed space and tries all 1dimensional subspaces as seed vectors. In this mode, seed vectors are constructed by taking linear combinations of the rows of Seed. This option is typically used to search a subspace exhaustively for vectors generating a nontrivial invariant subspace. Of course "1" and "m" cannot be used together. Also, "m" cannot be used together with "n".
What zsp does after spinning up a seed vector depends on the options "e", and "c". Without any of these options, zsp tries to find a proper invariant subspace. If the seed vector generates the whole space, zsp tries the next seed vector and repeats until a proper invariant subspace has been found, or until there are no more seed vectors.
With "e", zsp tries to find a cyclic vector. In this mode, the program spins up seed vectors onebyone until it finds a vector that generates the whole space, or until there are no more seed vectors available.
If you use the the option "c" instead, zsp combines the span of all seed vectors. In other words, "c" calculates the closure of the seed space under the generators. For example  zsp c b sub seed gen1 gen2 calculates the closure of "seed" under the two generators and writes a basis of the invariant subspace to "sub". zsp will print an error message if you try to use "c" together with any of "1", "m", or "e".
Using the "d" option you can set an upper limit on the subspace dimension. When zsp finds an invariant subspace, it will stop searching only if the dimension is at most MaxDim. Otherwise the search continues with the next seed vector. "d" cannot be used together with neither "e" nor "c".
If you use "t", zsp spins up canonically, producing the "standard basis". In this mode, the production of the subspace from the seed vector is independent of the chosen basis. Note that the standard basis algorithm allocates an additional matrix of the same size as the generators.
zsp can produce four different output files, which are all optional. If you use the "b" option, a basis of the invariant subspace is written to Bas. The basis is always in echelon form.
"s" and "q" tell zsp to calculate the action of the generators on the subspace and on the quotient, respectively. The file names are treated as base names with the same convention as explained above. For example,
zsp q quot s sub gen1 gen2 seed
Finds an invariant subspace, calculates the action on subspace an quotient, and write the action to "sub.1", "sub.2", "quot.1", and "quot.2". A second example:
zsp c s std g 3 gen pw
Here, a standard basis is constructed using three generators, "gen.1", "gen.2", and "gen.3", and seed vectors from "pw". The generators are then transformed into the standard basis and written to "std.1", "std.2", and "std.3".
Note that "s" and "q" can only be used if the generators are matrices. If you spin up with permutations, use "b" to make a basis of the invariant subspace, then calculate the action of the generators using ZMU and ZCL. Example:
zsp b sub perm1 perm2 seed zmu sub perm1 img zcl sub img dummy sub1 zmu sub perm2 img zcl sub img dummy sub2
After these commands, sub1 and sub2 contain the action of the permutations on the subspace.
Finally, you can write a spinup script by using the "o" option. The spinup script contains the operations performed by the spinup algorithm to create the subspace from the seed vectors and the generators. It can be used with the zsc program to repeat the same process with different seed vectors and generators. Details on the format of the spinup script can be found in the library reference under SpinUp().
All generators, the seed vectors (depending on "1" and "n"), and a workspace are hold in memory. The workspace is the size as generators unless the maximal dimension has been restricted with "d". In standard basis mode, an additional matrix of the same size as the generators is allocated.