zsp man page

zsp — spin up, split, and standard basis on matrices or permutations


zsp [Options] <Gen1> <Gen2> <Seed>
zsp [Options] -g <#Gen> <Gen> <Seed>


This program takes as input a set of matrices or permutations (the "generators"), and a list of seed vectors. It uses the spin-up 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.

Specifying Input Files

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 generators 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 same field and have the same number of columns. The generators must be square matrices of the same size and over the same field.

Specifying the Seed Mode

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 ony-by-one 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 spin-up 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 1-dimensional 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.

Specifying the Search Mode

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 one-by-one 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. Note that -d cannot be used together with either -e or -c.

Standard Basis

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.

Specifying Output Files

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 and quotient, and writes 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 spin-up script by using the -o option. The spin-up script contains the operations performed by the spin-up 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.


Quiet, no messages.
Verbose, more messages.
-T <MaxTime>
Set CPU time limit
-b <Basis>
Output a basis of the invariant subspace.
-s <Sub>
Calculate the action on the subspace.
-q <Quot>
Calculate the action on the quotient.
-o <Script>
Write a spin-up script.
Produce output in GAP format. This option implies -Q.
-g <#Gen>
Set the number of generators.
-n <Num>
Start with vector Num.
-d <Dim>
Set an upper limit for the subspace dimension.
Try only one seed vector.
Make (generate) seed vectors.
Find a cyclic vector.
Combine, make the closure.
Make standard basis.
-x <Max>
Assume the subspace is closed after Max multiplications without finding a new vector.

Implementation Details

All generators, the seed vectors (depending on -1 and -n), and a workspace are held in memory. The workspace is the size of the 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.

Input Files

Gen1, Gen2
Generators (without -g).
Generators (with -g).
Seed vectors.

Output Files

Action on the subspace (with -s).
Action on the quotient (with -q).
Basis of the invariant subspace (with -b).
Spin-up script (with -o).

See Also

zcl(1), zmu(1), zsc(1)

Referenced By

zbl(1), zcl(1), zsc(1), zts(1).

Explore man page connections for zsp(1).

MeatAxe 2.4.24