MeatAxe  2.4
zsp - Spin Up

# Command Line

```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 ```
Options
Standard options, see Standard Command Line Options
-b Bas
Write a basis of the invariant subspace to Bas.
-c
Combine the span of all seed vectors.
-s Sub
Calculate the action on the subspace and write the matrices to Sub.1, Sub.2, ...
-q Quot
Calculate the action on the quotient and write the matrices to Quot.1, Quot.2, ...
-o Scr
Write a spin-up script to Scr.
-d MaxDim
Set an upper limit of the subspace dimension.
-n Vector
-1
Spin up only one vector.
-e
Find a cyclic vector.
-p
Find a proper subspace.
-m
Generate seed vectors.
-t
Spin up canonically (standard basis).
-x
Assume the subspace is closed, if MaxTries vectors have been multiplied by all generators without yielding a new vector.
-g
Set the number of generators.
-G
GAP output.
Gen1
First generator, if "-g" is not used.
Gen2
Second generator, if "-g" is not used.
Gen
Base name for generators with "-g".
Seed
Seed space file name.

# Input Files

Gen1
First generator, if "-g" is not used.
Gen2
Second generator, if "-g" is not used.
Gen.1, Gen.2, ...
Generators (with "-g").
Seed
Seed vectors.

# Output Files

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

# 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.

## 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 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.

## 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. "-d" cannot be used together with neither "-e" nor "-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.

## Changing the Output Format

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 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. Details on the format of the spin-up script can be found in the library reference under SpinUp().

# Implementation Details

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.

MeatAxe 2.4 documentation, generated on Mon Jun 7 2021 11:42:24