# zsp man page

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

## Synopsis

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

## Description

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.

## Options

**-Q**- Quiet, no messages.
**-V**- 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.
**-G**- 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.
**-1**- Try only one seed vector.
**-m**- Make (generate) seed vectors.
**-e**- Find a cyclic vector.
**-c**- Combine, make the closure.
**-t**- 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).
*Gen*.{1,2,...}- Generators (with -g).
*Seed*- Seed vectors.

## Output Files

*Sub*.{1,2,...}- Action on the subspace (with -s).
*Quot*.{1,2,...}- Action on the quotient (with -q).
*Basis*- Basis of the invariant subspace (with -b).
*Script*- Spin-up script (with -o).

## See Also

## Referenced By

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