Braid v17.0 User Documentation


1. Introduction

This document provides user instructions for A. Bartholomew's braid programme; the web-page for the programme is http://www.layer8.co.uk/maths/braids

This file contains the following main sections:

  1. Overall Description

    Starting the Programme

  2. Input Codes

    Braid Words

    Label Codes

  3. Labelled Peer Code

    Labelled Immersion Code

  4. Polynomial Invariants

    Switch Polynomials

    The Active Switch

    The Variable t

  5. Long Knots

    The HOMFLY Polynomial

    Kauffman Bracket Polynomial for Classical and Virtual Links

    The Jones Polynomial for Classical and Virtual Links

    Turaev's Extended Bracket Polynomial for Knotoids

    Kauffman's Affine Index Polynomial for virtual knots

  6. Fixed-point Invariants

  7. The Vogel Algorithm

    Entering Gauss Codes

    Entering Labelled Peer Codes

  8. Sawollek Normalized Conway polynomial

  9. Dynnikov Test for Trivial Braids

  10. Knot and Link Code Conversion

  11. Command Line Options

    Calculating mod p

    Wait Information

  12. Input File Format

    Title Lines

    Braid Definitions

    Switch Definitions

    Gauss Code Definitions

    Labelled Immersion Code Definitions

    Long Knot Definitions

    Putting Programme Options Into Input Files

    Premature Termination of Input Files

  13. Version History

  14. Bug Tracker

2. Overall Description

The braid programme was originally designed to provide a number of tasks relating to virtual, and consequently classical, braids. It has evolved to include tasks that relate to a variety (including virtual, welded, and flat) of knots and links but that do not involve a braid representation. However, in the absence of anything better, the name 'braid' has been retained for the programme.

The tasks provided by the programme support the following:

  1. The Burau and Alexander polynomial invariants
  2. Various quaternionic polynomial invariants
  3. Various matrix-switch polynomial invariants
  4. Various Weyl algebra switch polynomial invariants
  5. Various finite-switch polynomial invariants (also known as rack polynomials)
  6. The fixed-point invariant of a braid
  7. Vogel's algorithm for determining a braid word from a knot or link diagram
  8. The HOMFLY polynomial
  9. The Kauffman bracket polynomial of a classical or virtual link
  10. The Jones polynomial of a classical or virtual link
  11. Turaev's extended bracket polynomial of a knotoid
  12. Kauffman's Affine Index Polynomial for virtual knots
  13. Sawollek's normalized Conway polynomial for a braid word
  14. The Dynnikov test for the trivial braid
  15. The Dowker(-Thistlethwaite) code for the braid
  16. The Gauss code for a braid word
  17. The labelled peer code for a braid word

back to top          back to braid programme

Starting the programme

The programme is started by typing braid at a command prompt, a menu is then displayed that allows the user to choose which task to apply. Alternatively the programme may be started with a number of command line options to select a particular task directly. It is also possible to supply an input file containing the input to the programme that allows the programme to operate in batch mode.

Typing exit at any prompt will cause the programme to terminate.

The word help may be entered at any prompt to display a list of the command line options supported by the programme and other help information. After displaying the help information, the programme terminates.

Note: the words exit and help must be entered in lower case.

Recording the output

As the programme executes, a copy of the data output to the screen is placed in the file 'braid.out', created in the same directory as the one from which the programme was started. This is a normal text file that may be read with any text editor. The filename used for the programme output may be overridden by specifying the name to use in the command line

back to overall description          back to top          back to braid programme

3. Input Codes

The programme takes as input a code describing either a braid or a diagram of a knot or link. The code for braids is just the familiar concept of braid words, and the code for a diagram may be either a labelled peer code or (for backwards compatibility) a labelled immersion code.

Braid Words

Since the programme deals with virtual braids, we cannot use the traditional alphabetical notation for braids. Instead we use the syntax s1, s2, s3 to denote a, b, c, and -s1, -s2, -s3 for A, B, C. This allows us to introduce virtual crossings, t1, t2, t3 etc.

Braid words are therefore entered as a contiguous list of si,-si, and ti, where i is some integer. The following are examples of braid words:

s1s1s1
-s1-s2s1t2-s1s2s1t2
s1s2-s3t1s4-s3-s2t4-s1-s3-s2t3

The programme will carry out basic error checking on the braid word supplied and will refuse to process a word that it cannot understand, displaying a message to the user.

Note: the characters s and t must appear in lower case in a braid word.

The programme determines the number of strands in a braid automatically and does not require that successive braids entered at the prompt have the same number of strands.

Label Codes

Labelled Peer Code

Full details of labelled peer codes are provided in a pdf paper available from the braid programme website. Here we provide only a brief description.

A labelled peer code for a virtual (or classical) link (knot) diagram is obtained from the underlying immersion by choosing an arbitary starting component and semi-arc and numbering each semi-arc of that component consecutively from zero as we trace around the component. When we return to the starting semi-arc we move onto another component and continue the numbering. We require that each time we start a new component we choose one that has a crossing involving a strand belonging to a component that has already been numbered. We also require that we start the numbering of the new component on a semi-arc that ensures that the first crossing we encounter involving a previously numbered strand has both an odd and an even numbered incoming semi-arc, with respect to the orientation induced by the numbering. It is always possible to construct such a numbering, as described in the document referenced above. We view the immersion as a 4-regular plane graph. The numbering results in every vertex having an even and odd numbered terminating edge and an even and odd numbered originating edge with respect to the induced orientation. The two edges terminating at a common vertex are called peer edges.

If the immersion has n vertices, the graph has 2n edges and the peer edges are of the form 2i, 2j-1 (taken mod 2n) for some integers i and j in the range 0,...n-1. The value of i determines a numbering for the vertex (and corresponding crossing) at which edge 2i terminates. We therefore refer to the even edge as the naming edge for the corresponding crossing.

Further, the peer edges will be oriented around the vertex so that the odd edge is located adjacent to the even edge in a clockwise or anticlockwise direction. We call crossings of the first type Type-1 crossings and of the second type Type-2 crossings.

The first part of a labelled peer code is comprised of a list of the odd-numbered peers in the order determined by the vertex numbering. The list is separated by commas into the peers of naming edges that are associated with the same component of the link.

For example, for the immersion and edge numbering shown in the figure above, the list of odd peers is

11 9, 3 1 13 5 7

The list of odd peers may be supplemented to record the type of each crossing by writing each odd peer associated with a Type I crossing as a negative number. Thus, for the diagram above we get

-11 9, -3 1 -13 5 -7

we refer to this code as a peer code.

The second part of a labelled peer code provides information about the original link diagram. For classical crossings we assign the label + if the naming edge forms part of the over-arc of the crossing and the label - if it forms part of the under-arc. For virtual or welded crossings we assign the label * and for flat crossings we assign the label #.

These labels are writen after the list of odd peers separated by a / character. They are written in the order determined by the vertex numbering. Thus continuing the above example if the original link diagram is as follows:

then the full labelled peer code is

-11 9, -3 1 -13 5 -7 / + - - + - + -

For the purposes of distinguishing labelled peer codes from other codes when using a computer the peer code will be enclosed in square brackets, as follows:.

[-11 9, -3 1 -13 5 -7] / + - - + - + -

Labelled Immersion Code

Labelled imersion codes describe only knots and not links, so have been deprecated by labelled peer codes. However the braid programme continues to support them for backwards compatibility. Full details of labelled immersion codes are provided in a pdf paper available from the braid programme website. Here we provide only a brief description.

A labelled immersion code for a virtual (or classical) knot diagram is formed by numbering semi-arcs as in the case of labelled peer codes. The terminating edges 2i, 2j-1 at a vertex (taken mod 2n as before) determine a permutation p of the integers 0,...,n-1 given by p(i)=j.

Crossings are identified as Type-1 or Type-2 crossings as in the labelled peer code case.

The first part of a labelled immersion code comprises the permutation p, written as a product of cycles, with the integers written as negative if the corresponding crossing is Type-1. The second part of a labelled immersion code provides label information in the same manner as labelled peer codes, writen after the signed permutation separated by a / character. They are written in the order corresponding to the crossings shown in the permutation. The following is an example of a labelled immersion code for the Kishino knot K3

(-0 -2 -1 -3 -5 -4) / - + * + - *

back to input codes          back to top          back to braid programme

4. Polynomial Invariants

The programme can calculate a variety of polynomial invariants from braid words or a label code. These may be classified as those calculated from a quandle or biquandle determined by a switch, referred to here as switch polynomials, and those calculated using a skein formula.

Switch Polynomials

Finite switch polynomial invariants

The finite switch polynomial invariant, or rack polynomial, is defined for a sequence of braids B0,B1,...,Bk, where B0 is a braid on n strings and where Bk is obtained from Bk-1 by appending the positive twist sn+k-1 for k=1,...,n.

For a given finite switch the fixed point invariant Fi and writhe Wi (the number of positive braid terms minus the number of negative braid terms) is determined for each braid Bi and the resultant polynomial

F0tW0,..., FktWk

is calculated.

The number, k, of positive and negative terms to consider for the finite switch polynomial invariant is referred to as the number of rack terms. By default the braid programme sets k=n, where n is the size of finite switch being used, but it is possible to override this either on a per-braid basis by adding the braid qualifier rack-terms=k, or globally by using the command line option t=k. Setting the number of rack terms using the command line option overrides any braid qualifier specified.

Other switch polynomial invariants

In each case other than the finite-switch polynomial invariants the matrix representation of the knot or link determined by the active switch is evaluated. If a braid word is used the matrix representation is in Bn or VBn, otherwise it determines the invariant R-module described in [1]. In the case of a braid word, it is possible that the matrix representation is the identity, in which case the calculation stops since the braid is indistinguishable from the unkot (or unlink).

Assuming the matrix representation is not the identity, the programme calculates Delta0, the 0th ideal polynomial, equal to det(M-I) if M is in Bn or VBn and det(M) otherwise. The value of Delta0 is displayed and then the programme proceeds to calculate Delta1, the 1st ideal polynomial (see [1]), regardless of the value of Delta0.

If required, the z option may be supplied to the programme so that Delta1 is only calculated if Delta0 is zero.

Note that in the case of matrix-switch representations and Weyl algebra switch representations we are frequently working with multivariate polynomials and so only a set generators of Delta1 may be calculated. In the Burau, Alexander or quaternionic cases we work with single variable polynomials, so the highest common factor of the set of Delta1 generators is calculated.

Calculating switch polynomial invariants

If the programme is being run interactively, the user is prompted for a braid word or labelled immersion code, once entered the programme will calculate the ideal polynomials as described above and present the user with a prompt for another braid word or labelled immersion code. The user may type exit at this prompt to leave the programme.

Most of the Weyl algebra switch invariants are always calculated with coefficients mod p for some prime. For others polynomial invariants, calculating mod p is an option, as described in the section Calculating mod p. A description of the Weyl algebra case may be found in the section Weyl algebra Switches.

back to top          back to braid programme

The Active Switch

With all the polynomial invariant tasks, the programme operates with an active switch; either a finite switch, or a linear switch as defined in [1].

Finite switches

A finite switch S of order n is a permutation of Xn x Xn written S(x,y) = (yx,xy), where yx is the "up action" and xy is the "down action". These switches are specified as two n x n matrices, row by row in the usual manner, with elements in Xn.

The specification of S is sufficient to handle classical knots, for virtual knots by default the twist T(x,y)=(y,x) is used for virtual crossings. If required the braid programme may be given a non-default twist T, that is another switch with the property T2 = I. As with S, a non-default twist is specified as a pair or matrices, representing the up and down action.

Linear switches used by the braid progamme

As described in [5], given a 2x2 matrix

where A-1 is invertible and where the fundamental equation

[B,(A-1)(A,B)]=0,

is satisfied, then S satifies the conditions of [1] to be a linear switch with C and D determined by A and B as follows:

C=A-1B-1A(1-A)  D=1-A-1B-1AB;

thus we may identify switches by specifying suitable A and B.

The Burau switch is defined by the matrix:

This switch is also used when the Alexander option is requested via a command line option. For the Alexander case, the variable s in the Burau switch is set to 1 before displaying Delta0; in both the Burau and Alexander cases the variable s is set to 1 before evaluating Delta1

The default quaternionic switch is the "Budapest switch", determined by the matrix:

Other quaternionic switches may be specified in an input file.

Matrix switches are elements of a ring of nxn matrices with polynomial entries. The default matrix switch is the "three-variable" switch determined by the matrices

and

Other matrix switches may be specified in an input file.

Weyl algebra switches, which are described in [6], are based on nxn matrix representations of an extended Weyl algebra determined by invertible elements u and v in a commutative ring with the relation

uv-vu=1.

The quantum Weyl algebra described in [6] is also supported. Quantum Weyl algebra switches are based on nxn matrix representations of the quantum Weyl algebra, which is determined by invertible elements u and v in a commutative ring with the relation

uv-qvu=1.

The default Weyl algebra switch is that determined by a 3x3 matrix representation of an extended Weyl algebra over a field of characteristic 3, given by the matrices

and

Given matrix representations U and V of a Weyl algebra we set

A = V-1U-1 and B=U,

then proceed from the fundamental equation (see [6] for details).

Other Weyl algebra switches may be specified in an input file.

The Variable t

Given a linear switch

,

if B is multiplied by a real variable t then the fundamental quation is satisfied by A and Bt and we have another linear switch, where C becomes multiplied by the inverse of t.

Adding the variable t can sometimes provide additional useful information but can also make the calculations unmanagably large. The programme therefore provides the option for including the variable or not, see the section on command line options and switch definitions.

The variable t is not used with the Burau or Alexander switches, these switches are based on the matrices shown above. The default quaternionic switch has the variable t added by default, the default matrix and Weyl algebra switches do not. See the above sections for details of how to override this default behaviour.

Matrix representation of a braid

For a linear switch the matrix representation of the virtual braid group Bn for the braid is obtained by letting si represent the matrix

Si=Ii-1xSxIn-i-1,

where I is the identity matrix and S is the active switch. Similarly, -si represents the matrix

S-1i=Ii-1xS-1xIn-i-1,

where S-1 is the inverse of S, and ti represents the matrix

Ti=Ii-1xTxIn-i-1,

where T is the "twist matrix"

The matrix representatino of the braid is then the product of the corresponding Si, S-1i, and Ti.

Long Knots

In addition to handling closed knots the braid programme is able to calculate polynomial invariants of virtual (hence classical) long knots. These are viewed as (virtual) closed knots on S2 with a mid-point of a semi-arc being chosen as the point at infinity.

The polynomial invariants calculated for long knots are two of the co-dimension zero mu-determinants described in [7]. It calculates both p(0) and op(0) (the determinant of the presentation matrix for the invariant module having generator x0 set to zero). The third invariant described in [7] is that of the closure of the long knot. This is not calculated explicitly by the programme since it already handles closed knots: two separate inputs are therefore required to calculate all three, one for the two long-knot specific invariants and one for its closure.

Given our view of long knots as closed knots on S2, we may use labelled immersion codes for long knots provided we have a mechanism for indicating the semi-arc containing the point at infinity. We use the convention that edge zero contains the point at infinity by default, and introduce a mechanism to 'move' the point at infinity to another semi-arc if required.

The use of a labelled immersion code for a long knot is specified by prefixing the code with an L charcater, details of which are given in section Long Knot Definitions. As noted above two inputs are required to calculate the full set of invariants described in [7], this may be achieved by using the same labelled immersion code prefixed once with the long-knot specifier L and once without.

Movng the point at infinity is required since different invariants are calaulcated for long knots dependent on the coice of infinity. The syntax for long knots given in section Long Knot Definitions allows the point at infinity to be moved forwards or backwards by k semi-arcs with respect to the orientation determined by the labelled immersion code.

When using a labelled immersion code for a long knot, the edge and vertex numbering for the immersion is essentially the same as that for a closed knot, except that edge zero is now non-compact. Similarly, the final edge is non-compact and distinct from edge zero, hence is edge 2n, when the immersed long-knot contains n crossings. The permutation established for closed knots carries over to long knots since only incoming edges are used to determine the permutation, so the presence of edge 2n is irrelevant. It's presence merely produces a presentation matrix for the long knot with one more generator than relation, as described in [7].

back to matrix representations          back to top          back to braid programme

The HOMFLY Polynomial

The "homfly" function uses the skein relation

a^-1 P(L+) - a P(L-) = z P(L0)

P(unknot) = 1

to determine the HOMFLY polynomial of a supplied braid word, using the number of bad crossings as the induction variable. This choice of skein relationship was made to be consistent with the polynomials given by Chuck Livingston's calculator at http://www.indiana.edu/~knotinfo/.

A crossing is bad if it is first encountered on an under-arc, and is good if it is first encountered on an over-arc. If a classical braid has no bad crossings, following the braid according to its orientation means one is always decending, i.e. it is the unlink.

The HOMFLY polynomial was implemented in the hope that it might be extended to virtual knots, so far this has not been achieved.

back to top          back to braid programme

Kauffman Bracket Polynomial for Classical and Virtual Links

Although there are many implementations of the Kauffman bracket polynomial, as defined in [8], the one here arose from the code required to calculate Turaev's extended bracket polynomial for knotoids, so it seemed natural to include the original bracket polynomial as well.

This implementation takes as input either a labelled peer code or a Gauss code and supports both classical and virtual knots and links.

The Jones Polynomial for Classical and Virtual Links

The Jones polynomial is determined from the Kauffman bracket polynomial, so it's inclusion was an immediate consequence of Kauffman polynomial. It takes the same labelled peer code or Gauss code input as the Kauffman bracket polynomial calculation.

Turaev's Extended Bracket Polynomial for Knotoids

Turaev's extended bracket polynomial is defined in [9] for knotoids, which are represented diagramatically as an immersion of the interval [0,1] in the interior of a surface whose only singularities are double points endowed with over/undercrossing data.

A knotoid K is specified using a labelled peer code by adding a shortcut that passes everywhere under K, forming K_ in Turaev's notation. Then, K_ is a knot for which we can write the labelled peer code determined by numbering the semi-arc containing the leg of K as zero and proceeding in the direction from the leg to the head. We then identify the first crossing introduced by the shortcut by writing a ^ symbol after the peer of the crossing's naming edge in the peer code. There is a unique semi-arc that enters this crossing as an under-arc with the orientation of K_ described above. Thus the ^ character uniquely identifies the semi-arc containing the head of K.

For example, given the following knotoid and shortcut (shown dashed)

we obtain the labelled peer code

[-7 13 -11 -1 3 -5 9^]/+ + - + + - -

back to top          back to braid programme

Kauffman's Affine Index Polynomial for virtual knots

Kauffman's affine index polynomial invariant for virtual knots is described in [10]. It is particularly useful to distinguish virtual and classical knots, since the affine index polynomial takes the value zero for a classical knot. Although it is a simple polynomial to calculate by hand for a given knot diagram, it has been added because of its ability to distinguish classical and virtual knots. However, it should be noted that there are virtual knots having zero affine index

5. Fixed-point Invariants

The fixed point invariant determined by a pair of finite switches S and T over Xn, where T2 = I, of a braid with k strings is the number of fixed points Mv=v where v ranges through all vectors in Xnk. Here M is the matrix representation of the braid determined by S and T.

6. The Vogel Algorithm

This task takes the description of a diagram in the form of a labelled peer code and applies the Vogel algorithm to determine an equivalent braid word representation of the knot or link. A complete description of the Vogel Algorithm applied to both the classical and virtual case is given in [2], which is available as vogel.pdf from the braid programme website.

Entering Gauss Codes

A link diagram may be described using a Gauss code in which the crossings of the diagram are numbered and a code produced by following each component of the link from some arbitrary starting point, according to a given orientation. If a crossing is passed on an under-arc the crossing is written as a negative number and if the crossing is passed on an over-arc, it is written as a positive number. Multiple components are written separated by commas.

Gauss codes ignore any virtual crossings in a digram of a virtual knot. Put another way, not all Gauss codes are realizable as classical link diagrams.

To indicate the nature of each crossing, as a positive or negative crossing, we append the sign of the crossing to the Gauss code following a '/' character. Thus a Gauss code for a classical link would have the form

1 -2 5 -4 3 -5, -1 2 -3 4 / ++--+

Entering Labelled Peer Codes

The syntax for labelled peer codes is described under the section on polynomial invariants here.

back to top          back to braid programme

7. Sawollek Normalized Conway polynomial

The Sawollek task evaluates the normalized Conway polynomial described in [3], taking a braid word as input.

8. Dynnikov Test for Trivial Braids

The Dynnikov test uses the action defined by the braid group Bn on Z2n given by Dynnikov's formulae in [4] to determine whether the given braid is trivial.

9. Knot and Link Code Conversion

There are several tasks in this category, used for converting one form of diagramatic representation into another, or calculating the result of some transformation performed on a diagram. These tasks take their input either from the user or from an input file.

The Dowker code calculated by the programme is the Dowker-Thistlethwaite code as used by the programme knotscape. The Dowker code option takes either a braid word or a labelled immersion code as input. In the case of braids it only yields a code if the closure of the braid is a knot, it may therefore be used as test that the closure is indeed connected. (Labelled immersion codes are only defined for knots.)

The Gauss code is the classical Gauss code together with an indication of whether the crossings are positive or negative. Details of the code format are given in the section Gauss Code Definitions. The Gauss code option takes a labelled peer code, labelled immersion code or a braid word as input.

The labelled immersion code has been deprecated by labelled peer codes but continues to be supported for backwards compatibility. Full details of labelled immersion codes are provided in a pdf document from the braid programme website, and there is a brief description in the section Labelled Immersion Code.

The labelled peer code is described in a pdf document from the braid programme website, and there is a brief description in the section Labelled Peer Code. The peer code option will determine a labelled peer code from a braid word or a labelled immersion code, or may be used to renumber a link diagram described by a labelled peer code.

Renumbering Labelled Peer Codes

It is sometimes useful to determine a labelled peer code for a link diagram that has been renumbered in some way from a labelled peer code of the original diagram. The peer code option is cable of producing a labelled peer code for the diagram obtainied by moving the starting point for the numbering of each link component backwards with respect to the orientation by a number of semi-arcs.

The amount of shift for each component is specified by a shift vector giving a value for each component. The shift vector is appended to the labelled immersion code input in the form of a qualifier as follows:

--link 11n455 peer code
;[-3 -21 7, 5 -15 -17, -11 -19, -13 -9 -1]/----++++++- {shift[0,2,2,0]};

A positive shift value as in the above example indicates a backwards shift of the starting point for the numbering of the corresponding component. If it is negative, it represents a backwards shift of the absolute value together with an orientation reversal.

--link 11n455 peer code
;[-3 -21 7, 5 -15 -17, -11 -19, -13 -9 -1]/----++++++- {shift[-1,-3,2,0]};

If the code represents a link and any component is shifted by an odd number of edges, we must have all intersecting components shifted by an odd number of edges, otherwise we will violate the requirement to have an odd and even edge terminating at every crossing. Since the peer code has to be connected to be realizable, this means that every component has to be shifted by an odd number of edges. Thus we have to shift every component by an odd number of edges or every component by an even number of edges.

If a component's orientation is reversed we also violate the requirement to have an odd and even edge terminating at every crossing. Therefore an orientation reversal must be accompanied by an odd shift of the component being reversed or of those other components it meets at a crossing. By considering orientation reversal an "odd" operation, a particular shift vector is valid if every entry is odd or every entry is even. Thus -2 is odd and -1 is even.

back to top          back to braid programme

10. Command Line Options

The programme may be started with a number of command line options that override the default operation and select a task directly, as follows:

braid --<task> [-<options>][<infile>[<outfile>]]

The <task> indicates the primary task of the programme, currently the following tasks are supported:

affine-index: evaluate the affine index polynomial invariant
alexander: evaluate Alexander switch polynomial invariants
burau: evaluate Burau switch polynomial invariants
dowker: calculate the Dowker code for the closure of the braid, provided it is a knot
dynnikov: carry out the Dynnikov test to determine whether the braid is trivial or not
fixed-point: evaluate the fixed-point invariant of a braid
gauss: evaluate Gauss code of a braid
homfly: evaluate the HOMFLY polynomial for the closure of a braid
info: display status information (currently just the number of components) for the braid
immersion: evaluate labelled immersion code
jones-polynomial: evaluate the Jones polynomial for a classical or virtual link
kauffman-bracket: evaluate the Kauffman polynomial for a classical or virtual link
knotoid-bracket: evaluate the Turaev extended bracket polynomial for a knotoid
matrix: evaluate matrix switch polynomial invariants
peer: evaluate labelled peer code
quaternion: evaluate quaternionic switch polynomial invariants
rack-polynomial: evaluate the finite switch polynomial invariants
sawollek: evaluate Sawollek's normalized Conway polynomial
vogel: apply the vogel algorithm to a labelled peer code
weyl: evaluate Weyl algebra switch polynomial invariants

The supported options are:

c[{2}]: calculate DeltaiC rather than DeltaiH for quaternionic switches
- {2} always calculate codimension 2 determinant from complex Study Delta_1
e: test for the switch equality condition A=D and B=C
h: display help information
I: format programme output as a valid input file
N: normalize quaternionic polynomial invariants
o: display the matrix representation, M, of the braid and the elements of the adjoint adj(M-I) for the active switch
p=n: calculate mod p using the given prime (no checking for primality is included)
P: display the polynomial wait indicator
R: use the rho-mapping for Study determinants
S: silent operation, do not generate any output to the command line (for use with system calls) t=n: set the global number of terms for finite switch polynomial invariants.
V: Do not use the t-variable with the default quaternionic switch
W[=n]: force wait iformation to be displayed, if n is supplied, set the wait threshold to n
z: do not calculate Delta1 when Delta0 is non-zero
Z: display Delta1 polynomials only

The 'c' option has a single suboption 2, specified as c{2}

Note: the order in which the options are entered is not important, but no spaces are allowed between option characters. In particular, no spaces are allowed either side of the '=' character when wait information, or the t or p options are specified. Only one '-' character is required at the start of the options list to indicate their presence.

If an <infile> is supplied it may contain a number of braid definitions to which the chosen options are applied successively. The syntax for these is described in the section Input File Format

If an <outfile> is specified it is used to record the programme output. This overrides the default output filename braid.out.

If you want to override the default output filename but are not using an input file, you must indicate that there is no input file on the command line using an empty string (""). Thus an interactive use of the braid programme to calculates the Burau matrix representation, saving the output into a file called fred would be started by the command line

braid --burau "" fred

Note: there may not be any spaces between the double inverted commas.

Complex Delta1 Option

The c option that is used to calculate DeltaiC rather than DeltaiH for quaternionic switches, that is it calculates the GCD of the codimension 1 determinants of the complex Study matrix. It has an optional sub-option that is specified as follows: c[2]. When this sub-option is selected the programme always calculates the GCD of the codimension 2 determinates of the complex Study matrix, rather thatn following the default behaviour which is only to calculate the codimension 2 determinants if the GCD of the codimension 1 determinants is 0.

Calculating mod p

Most of the Weyl algebra switch polynomial invariants are always calculated with coefficients mod p for some prime, as described in the section Weyl algebra Switches. For other polynomial invariants, using the p=n option sets the value of the modulus to n, but note there is no check for primality. Setting the modulus causes the programme to calculate quaternions with mod p components, and polynomials with mod p coefficients.

Omitting the Variable t

As described in the section The Active Switch, the default quaternionic switch includes the use of the real variable t. The use of the V option prevents this from happening.

To override the default behaviour for the default matrix and Wely algebra switches an input file must be used with the use of the variable t included in the switch specification. See the section Switch Definitions.

Wait information

Due to the fact that some quaternionic switches involve processing rational numbers with very large (co-prime) numerators and denominators, the braid programme uses arbitrary precision integer arithmetic. The processing of rational arithmetic is considerably slower than normal computer based arithmetic and the arbitrary precision integers add further delay (though interestingly not as much as the rational processing). As a consequence, calculating large determinants can take a considerable length of time. Similarly, the Sawollek polynomial requires evaluating the determinant of a N-square matrix where N is twice the number of real crossings in the input braid. In both cases, the programme displays wait informaiton, or "comfort dots", that indicates the programme is actually doing something and has not stopped running!

For polynomial invariants the programme determines when it thinks it should display wait information but you can force it to be displayed by adding the W option. The Sawollek calculation relies on input from the user to produce wait information. For further control you can specify a number called the "wait threshold" that determines how frequently the programme puts out another comfort dot. The default for the wait threshold is 5, but you can set it to any value greater than 1; the lower the value the more dots you will see. The threshold actually relates to the completion of a minor in the calculation of a determinant, which is why it must be bigger than 1; if the wait threshold is n, a dot is written to the screen after each nxn minor is calculated. Comfort dots are not written to the output file.

When working with some switches, the size of the polynomials involved is very large, both in terms of the number of variables and the number of terms. Performing arithmetic operations on such polynomials can also take a long time, so it is possible to add the P option. This generates a spinning line to indicate that something is still happening. This option is independent of the comfort dots above, so the output can look a littl messy if both are selected. However, given that some calculations can take days, even on a fast machine, it is useful to have the comfort information available.

Formatting output as input

The I option causes the output from the braid programme to be formatted so that it can be saved and submitted as a programme input file. This capability was introduced for testing tasks such as the Vogel algorithm, or labelled immersion code, so that circular tests could be carried out: calculate a polynomial invariant for a set of braids, calculate their immersion code, calculate the polynomial invariant again, calculate the braid word from the labelled immersion codes, and calculate the polynomial invariant again.

back to command line options          back to top          back to braid programme

Examples

The following are valid command lines for the programme (assuming the current directory is in the search path)

braid --dowker

runs the programme to evaluate the Dowker code/test for braid closure a knot for braids entered at the command prompt

braid --quaternion -Z fred

runs the programme to calculate just the 1st-ideal polynomial for all the braids given in the input file fred. This will use the default quaternionic switch unless directed otherwise by the input file.

braid -oW=4 fred

runs the programme to calculate the 1st-ideal polynomial for all the braids given in the input file fred, showing the matrix representations themselves and forcing the display of wait information with the wait threshold set to 4.

back to command line options          back to top          back to braid programme

11. Input File Format

An input file may be specified on the command line to provide batched input to the braid programme. An input file is a normal text file that may contain title lines, braid definitions, switch definitions, Gauss code definitions, labelled peer code definitions, labelled immersion code definitions, long-knot definitions, programme options, and may contain comments and whitespace.

An input file is first scanned for programme options, then depending on the active programme options, scanned again for switch definitions. Once all options and relevant switches have been determined the file is processed line by line looking for valid input data in the form of braid words or labelled immersion codes. Each valid programme input is then processed according to the active options; scanning for input data continues until then end of the file is reached or a line is encountered that contains only the word exit after comments have been removed.

Note: the presence of an exit line affects only scanning for braid words or labelled immersion codes. Programme options or switch definitions appearing after such a line are still processed. Use comments if you want to omit options or switches.

Comments

Any line beginning with a semi-colon is regarded as a comment.  Any text after a semi-colon is also treated as a comment. When the input file is scanned, each line is read in, and inspected to see if it contains a semi-colon.If it does, the line is truncated at the first semi-colon and any text in front of the semi-colon processed as described below.

Title Lines

If a line in the input file begins with two consecutive dash (-) characters then the text on that line is considered by the programme to be a title for the next switch definition, braid statement, labelled peer code, labelled immersion code or Gauss code. When reading the input file for the next switch or input data, the programme records any titles it encounters, the last of which is associated with the next switch or data input line it finds.

Here is an example of a title line.

-- The virtual trefoil

Titles may comprise any text that usefully identifies the corresponding braid or code; notice that title lines may also contain comments, which are removed before the title is processed.

The programme will scan the input file either for the particular input types the selected task is prepared to accept (eith braid words, labelled peer codes, labelled immersion codes, or Gauss codes) and ignores lines it is not looking for. Thus, if an input file contains both a braid word and a code for the same link, you can use the same title for each, as in the following:

-- The figure 8 knot
1 -3 4 -1 2 -4 3 -2 / ++--
-s2s1-s2s1

or use different title, like this

-- The figure 8 knot
1 -3 4 -1 2 -4 3 -2 / ++--

-- BaBa, figure 8 ; comments are not part of the title
-s2s1-s2s1

Here's an example of a title applied to a switch determined by an essential pair of finite biquandles


-- S = BQ^3_{3} T = Q^3_{1}
S=FTW 0 1 2 2 0 1 1 2 0 0 2 1 0 2 1 0 2 1 0 1 2 0 1 2 0 1 2 0 1 2 0 1 2 0 1 2

back to input file format          back to top          back to braid programme

Braid Definitions

In this context a braid definition comprises an optional list of assignment statements and a braid statement.

Assignment Statements

An assignment statement uses one of the eight word variables, w1,...w8 provided by the programme to construct complicated braid words. An assignment statement assigns to the specified word variable a string formed from elements of the form si,-si and ti for some integer i, or may reference other word variables either positively (wi) or negatively (-wi). Referenced word variables are expanded automatically when the line is processed.

Note: the word variables w1, ..., w8 must appear in lower case

Examples

Here are some valid assignment statements:

w1 = s1s2t3-s1-s2
w2 = s2w1s2w1 ;notice this assignment statement involves other word variables
w3 = -w1-w2w1w2 ;notice how this and the above line contain comments

The interpretation of a negative word is the inverse of that word, so that in the above example -w1 is the word s2s1t3-s2-s1 (note that the inverse of ti is again ti).

Braid Statements

A braid definition ends with a braid statement, which is simply a line with no assignment. A braid statement may reference word variables used previously in the same definition. For example, the above set of assignment statements could be followed by the braid statement

w3t2-w3t2

Care must be taken to define a word variable in an assignment statement before it is referenced by another assignment statement or a braid statement.

Here are some other examples of braid statements, given without the preceding assignment statements

...one or more assignment statements
w4

... one or more assignment statements
-w3-w4w3w4

... one or more assignment statements
-w3s1s2t3-s2-s1w3

... one or more assignment statements
s1s2s3

Once a braid statement is encountered, the programme checks that braid, processes it according to the active options then returns to the file to look for another braid definition. Each new braid definition in the file starts with all word variables set to the null string. There is no limit to the number of braid definitions that a file may contain.

The following simple braids are given by braid statements alone, with no assignment statements.

--virtual trefoil
s1s1t1
-- K1
s1-s2-s1t2s1s2-s1t2
-- K2
-s1-s2s1t2-s1s2s1t2
-- K3
s1s2s1t2-s1-s2-s1t2

The following braid definition generates the braid Stephen Bigelow used to prove that the Burau representation is not faithful for n=5

-- The Bigelow braid
w1=-s3s2s1s1s2s4s4s4s3s2
w2=-s4s3s2-s1-s1s2s1s1s2s2s1s4s4s4s4s4
w3=-w1s4w1
w4=-w2s4s3s2s1s1s2s3s4w2
-w3-w4w3w4

Braid Qualifiers

A braid word may be followed by one or more braid qualifiers that provide additional information about the braid. Two braid qualifiers are currently defined:

Braid qualifiers are specified within braces immediately following the braid statement, multiple qualifiers may be included, separated by spaces. Here are some examples of braid qualifiers:

s1s1s1{rack-terms=4}
-s1-s2s1t2-s1s2s1t2{welded}
s1s2-s3t1s4-s3-s2t4-s1-s3-s2t3{welded rack-terms=4}
s1s2t1t2s2s1 {flip}

The braid programme ignores any braid qualifiers that are irelevant to the task in hand, for examle the welded qualifier is not relevant to the calculation of a labelled immersion code, or the rack-terms qualifier is irelevant to the detmining of the Alexander polynomial.

back to input file format          back to top          back to braid programme

Switch Definitions

If a quaternionic, matrix or Weyl algebra polynomial invariant is to be calculated, the input file is scanned for switch definitions before any braid definitions are processed. Switch definitions may be used to identify one or more non-default switches to be used when processing the braids in the file. If the file contains multiple switch definitions then each switch is loaded from the file in turn and all the braids in the file processed before the next switch is loaded.

Switch definitions may be placed anywhere in the file, and they do not all have to appear in the same place.

Quaternionic Switches

Quaternionic switch definitions take the form of two quaternions A and B written as follows in the input file:

S= A B

The programme checks the fundamental equation is satisfied and then calculates C and D, as described in the section The Active Switch.

Each quaternion x+yi+zj+tk is written in the form (x,y,z,t)

Note:the switch indicator S may appear in either upper or lower case.

Here are some example switch definitions:

S = (1,0,0,-1) (0,1,-1,0)
S = (1,0,0,-1) (-1,1,1,-1)
S = (1,1,0,0) (0,0,0,1)

Older versions of the braid programme did not use the fundamental equation to determine C and D from A and B and therefore required all to be supplied in the inputfile. This format of input is still supported, though C and D are always calculated from the fundamental equation, rather than simply taking the values given. The older format of the above switches was as follows:

S = (1,0,0,-1) (0,1,-1,0) (0,-1/2,1/2,0) (1,0,0,-1)
S = (1,0,0,-1) (-1,1,1,-1) (-1/4,-1/4,-1/4,-1/4) (1/2,1/2,-1/2,-1/2)
S = (1,1,0,0) (0,0,0,1) (0,0,0,-1) (1,1,0,0)

Matrix Switches

Matrix switch definitions are similar to quaternionic switch definitions but now the quantities A and B are n-square matrices. They are written row by row element by element, separated by commas

S= A(0,0),...,A(0,n),...,A(n,0),...,A(n,n),B(0,0),...,B(0,n),...,B(n,0),...,B(n,n)

where A(i,j) represents the element in the ith row and jth column of A, etc.. Each element may of the matrices A and B is of the form p/q, where p and q are polynomials in an arbitrary number of variables, having integer coefficients. If q=1 then only p need be specified.

Note: polynomial variables should be entered in lower case

Since p and q have integer coefficients, the switch may be written without brackets around p and q, since the syntax is unambiguous. Thus we could write xyz-2y^2-2/2z as well as (xyz-2y^2-2)/2z

Here are some examples of matrix switch definitions:

S = a, 0, 0, a/a-1, b, c, b^2+a-1/c-ca b/1-a
S = 2, 0, x, 2, y, z, xyz-2y^2-2/2z, xz-2y/2

As with quaternionic switches the programme checks the fundamental equation is satisfied and calculates C and D as above.

Weyl algebra Switches

There are four types of Weyl algebra switch supported by the programme: three are optimized descriptions of example algebras given in [6] and the fourth provides support for arbitrary Weyl algebras, referred to here as "custom" Weyl algebras.

In [6] an example is given of an nxn matrix representation of extended Weyl algebra over a ring of characteristic prime p, where p divides n. Examples of this class of switch may be specified in an input file using the syntax

S=WP,n,p.

Another example from [6] is a switch derived from a ring of truncated polynomials, with xn=0, over a ring of characteristic p, where p is a prime dividing n. Examples of this class of switch may be specified in an input file using the syntax

S=WT,n,p.

The third example from [6] is a switch derived from the quantum Weyl algebra. In fact, [6] gives two families of nxn matrices that give representations of the quantum Weyl algebra, the one used as the standard representation by the programme is the first family, in variables a,b,c,d,e, and q; examples of this class of switch may be specified in an input file using the syntax

S=WQ,n[,p].

Note that the quantum Weyl algebra switch is not by default calculated mod p, as is the case for the other Weyl algebra switches, hence the value of p above is optional. If it is required to calculate mod p, the appropriate value of p should be supplied with the switch, rather than with the global modulus parameter described in the section describing the mod p option.

The fourth type of Weyl algebra switch is that determined by an arbitrary (custom) extended Weyl algebra specified by two matrix representations of the generators u and v. These switches are specified in the input file using the one of the following forms

S=WUV,p,U(0,0),...,U(0,n),...,U(n,0),...,U(n,n),V(0,0),...,V(0,n),...,V(n,0),...,V(n,n).
S=WQUV,p,U(0,0),...,U(0,n),...,U(n,0),...,U(n,n),V(0,0),...,V(0,n),...,V(n,0),...,V(n,n).
S=WUVG,p,U(0,0),...,U(0,n),...,U(n,0),...,U(n,n),V(0,0),...,V(0,n),...,V(n,0),...,V(n,n).
S=WQUVG,p,U(0,0),...,U(0,n),...,U(n,0),...,U(n,n),V(0,0),...,V(0,n),...,V(n,0),...,V(n,n).

where p specifies the prime modulus to be used for the calculation. Both normal and quantum Weyl algebra representations are permitted: the U and V following the Weyl indicator W in the switch definition indicate that the switch is a custom (i.e. user defined) Weyl algebra, and the presence of a Q indicates that this is a custom representation of the quantum Weyl algebra.

The prime p indicates the modulus for the calculation, as before. In the case of a custom representation of the quantum Weyl algebra, setting p=0 indicates that the calculation should be carried out in the integers.

Weyl algebra polynomial invariants are evaluated as rationals in the form n/d, where n and d are polynomials. In some cases the polynomials are in a single variable and the generators of Delta1 always yield d as a unit. In these cases the programme can evaluate the greatest common divisor of the numerators of the Delta1 generators to give a single polynomial invariant for Delta1. This option is specified by including 'G' in the specification of the custom Weyl algebra.

For the custom Weyl algebra representations, the programme checks the relationship

UV-VU=1

for normal Weyl algebras, and the relationship

UV-qVU=1

for a representation of the quantum Weyl algebra, before proceeding with this type of switch.

Here are some examples of Weyl algebra switch definitions:

S = WP,3,3
S = WT,2,4
S = WQ,3
S = WUV,2, x, 1, 0, x, x, 0, 1, x
S = WQ,2 ,2
S=WUVG, 2, x, 1, 0, x, x, 0, 1, x
S=WQUV, 0, q, 0, 1, 1, 1/1-q, q-1/q, 0, 1/q-q^2
S=WQUVG, 3, q, 0, 1, 1, 1/1-q, q-1/q, 0, 1/q-q^2

Finite Switches

Finite switches are identified in a similar manner to Weyl algebra switches, using the character F to indicate a finite switch, the character T to indicate the presence of a non-default twist and the character W to indicate whether the switch is suitable for application to welded knots. These qualifying characters are followed by the matrices for the up and down actions of the switch, given row by row. If a non-default twist is indicated, the up and down action for the T switch follows those for the S switch.

Thus, a finite switch for use with classical braids is specified as follows, if this switch is applied to a virtual braid, the default twist is used.

S = F U(0,0) U(0,1) ... U(n,n) D(0,0) ... D(n,n)

A finite switch for use with virtual braids with a non-default twist switch T is specified like this, S is specified first (U and D) T second (U' and D').

S = FT U(0,0) U(0,1) ... U(n,n) D(0,0) ... D(n,n) U(0,0) U'(0,1) ... U'(n,n) D'(0,0) ... D'(n,n)

A finite switch for use with welded braids with a non-default twist T is specified like this, a switch for use with welded braids has to be a significant pair.

S = FTW U(0,0) U(0,1) ... U(n,n) D(0,0) ... D(n,n) U(0,0) U'(0,1) ... U'(n,n) D'(0,0) ... D'(n,n)

In the above examples the matrix elements are separated by spaces but any non-digit character or characters may be used as element separators, with the exception of separaters containing the control characters F, T and W. The braid programme simply reads a matrix element (an integer), skips any number of non-digit charaters and reads the next element. This approach allows the user to cut and paste integer matrix descriptions from other formats, such as TeX source code.

Including the t Variable

Quaternionic, matrix and Weyl algebra switches may specify the use of an additional variable t by using the syntax S[t] = to introduce a switch. In this case B is multiplied by the additional variable t , so that C becomes multiplied by t's inverse.

Here are some examples of switch definitions specifying the use of the t variable:

S[t] = (1,0,0,-1) (0,1,-1,0)
S[t] = a, 0, 0, a/a-1, b, c, b^2+a-1/c-ca b/1-a
S[t] = WP,3,3
S[t] = WUV,2, x, 1, 0, x, x, 0, 1, x

back to input file format          back to top          back to braid programme

Gauss Code Definitions

Gauss codes may appear in the input file, written in the form described in the section Entering Gauss Codes

For some Gauss codes, it is impractical to write the entire code on one line, so the '\' character may be used in the first part of the code to split it across multiple lines. The following are valid specifications of Gauss codes:

-- 16n96
1 2 -3 4 -5 6 -2 3 -4 7 -8 5 -6 -9 10 8 -7\
-11 12 -13 9 -10 11 -14 15 -16 13 \
-12 14 -1 16 -15 / + - - - - - - - + + + - - + - -

-- 13a121
1 -2 3 -1 4 -5 2 -3 6 -7 8 -4 5 -6 9 -10 11 -12 13 -8 7 -13 12 -9 10 -11\
/+ + + - - - + + - - - - -

-- link example
1 -2 3 -4 5 -6,\ ; note the comma must still be included
-1 -8 9 -7 -5 6 7 4 -3 2,\
8 -9 -10 11 -12 10 -11 12\
/+-++--+-----

Note: the line break caracter '\'may not appear amongst the after the '/', since the programme uses the '/' as the indication that the Gauss code is complete.

Labelled Peer Code Definitions

Labelled peer codes may appear in the input file, written in the form described in the section Entering Labelled Peer Codes

As with Gauss codes, labelled peer codes may be split across multiple lines by using the '\' character in the first part of the code.The following are valid specifications of labelled immersion codes:

-- virtual figure 8
[-3 5 -7 1]/- * - -

-- this was derived from 8n1 with some crossings made virtual
[-33 -23 -17 13 1 27 19 -21 29 11 -5 -31 9 -35 -3 15 7 -25]\
/ + - - + * - + + - + + - + * + - + +

-- here's an example of a link with 3 components
[-21 -11 7, 1 17 -19 -3 9, -5 -13 15]/- + + + - - + - + - -

-- 16n30
[-29 -31 -65 -77 -89 -59 -43 45 -63 53 71 83 41 17 47\
-1 -49 51 69 81 -11 25 61 15 3 -67 -5 -75 -87 23 39 \
-13 -27 33 -79 -7 -55 85 19 35 -91 -9 -57 73 21 37]\
/ + + - - - - - - + - - - - - + + + - - - + - + - + + + + - + + + - + - + + - + + - + + - + +

Note: the line break caracter '\'may not appear amongst the after the '/', since the programme uses the '/' as the indication that the labelled peer code is complete.

Labelled Immersion Code Definitions

Labelled immersion codes have been deprecated but continue to be supported. They are written in the form described in the section Entering Labelled Immersion Codes

As with labelled peer codes and Gauss codes, labelled immersion codes may be split across multiple lines by using the '\' character in the first part of the code.The following are valid specifications of labelled immersion codes:

-- virtual figure 8
(-0 -2)(1 3) / - * - -

-- this was derived from 8n1 with some crossings made virtual
(-0 -17 -13)(-1 12 5 -14 -2 9 6 -10 3 -7 -11 16 4)(8 15)\
/ + - - + * - + + - + + - + * + - + +

-- here's the same knot written differently
(-0 -17 -13)(-1 12 5 -14 -2 9 6 -10 3 -7 -11 16 4)\
(8 15)/ + - - + * - + + - + + - + * + - + +

-- 16n30
(-0 -15 -1 -16 -25 -34 -40)\
(-2 33 17 -26 -3 39 18 -35 -4 45 19 -41 -5 30 -20 -6 22 -31 7 23 -8 -32 14 24)\
(9 -27 38 10 -36 -28 44 11 -42 29 12 21 13)(37 43)\
/ + + - - - - - - + - - - - - + + + - - - + - + - + + + + - + + + - + - + + - + + - + + - + +

Note: the line break caracter '\'may not appear amongst the after the '/', since the programme uses the '/' as the indication that the labelled immersion code is complete.

Long Knot Definitions

Long knots, as discussed in section Long Knots, are specified in the input file using a labelled peer code as described in sections Entering Labelled Peer Codes and Labelled Peer Code Definitions, prefixed with the upper case character L, indicating a long knot.

The L prefix indicates to the programme that the edge numbering of the immersion is not carried out modulo 2n and that the long knot invariants described in section Long Knots should be calculated.

The following are examples of long knot specifications:

-- the fly
L[3 5 1]/- + *
-- the dead fly
L[-3 -5 -1]/+ - *

As described in section Long Knots it is possible to move the point at infinity and calculate different invariants for long knots. This moving of the point at infinity is specified by following the long-knot specifier L by a plus or minus sign and a number, indicating that the point at infinity be moved forwards (+) or backwards (-) by the specified number of edges. The following examples demonstrate this syntax:

-- the fly with infinity moved backwards 1 edge
L-1(0 2 1)/- + *
-- the fly with infinity moved forwards 2 edges (equivalent to the above)
L+2(0 2 1)/- + *

Note: no spaces may appear between the L and the initial ( character.

In addition to specifying individual long knots the programme is capable of handling the concatenation product for long knots. An input file may specify two or more long knots to be concatenated in a single line of the input file using the ~ character to separate the factors. The syntax for each of the long knots to be concatenated is as specified above, and each may specify a shift in the point at infinity. If the point at infinity of a long knot factor is moved, the move is processed prior to the component being concatenated with the other factors.

An arbitrary number of spaces or tabs may appear either side of the ~ character but the entire concatenation specification must appear on a single line in the input file.

The following is an example of the concatenation product specification in an input file:

L+2(0 4 2)(1 3)/+ - * + +~ L-3(0 4 2) (-1 -3)/+ + - + * ~ L(0 4 2)(1 3)/+ * - + -

back to input file format          back to top          back to braid programme

Putting Programme Options Into Input Files

In order to simplify the operation of the programme in batch mode, and to make it easy to return to an input file long after it was created, it is possible to include programme options in the input file.

Programme options are specified using keywords contained within square brackets '[]'. They may appear anywhere in the file on a separate line of their own. Multiple sets of brackets may appear in a file, and multiple options may be specified within each set of brackets but must be specified on a separate line; they may be followed by a comment on the same line.

Note: only one set of option brackets may appear on each line.

The following keywords may be used, they must appear in lower case.

affine-index: evaluate the affine index polynomial invariant
alexander: evaluate Alexander switch polynomial invariants
bracket-polynomial: evaluate the rack polynomial for the specified braids
burau: evaluate Burau switch polynomial invariants
complex-delta1: calculate Delta_1^C rather than Delta_1^H for quaternionic switches
delta1-only: display polynomial output for Delta_1 only
dowker: calculate the Dowker code for the closure of the braid, provided it is a knot
dynnikov: carry out the Dynnikov test to determine whether the braid is trivial or not
equality: test for the switch equality condition A=D and B=C
extra-output: display the matrix representation, M, of the braid and the elements of the adjoint adj(M-I) for the active switch
fixed-point: evaluate the fixed-point invariant of a braid
format: format the output file so that it may be used as an input file later
gauss: evaluate the Gauss code of a braid
homfly: evaluate the HOMFLY polynomial for the closure of a braid
immersion: evaluate labelled immersion code
info: display status information about a braid
matrix: evaluate matrix switch polynomial invariants
mod-p=<p>: calculate mod p using the specified value for p (only used for non-Weyl algebra switches)
no_auto_delta1: only calculate Delta1 if Delta0=0 (the default is always to calculate delta_1
normalize: normalize quaternionic polynomial invariants
peer: evaluate labelled peer code
power=<n>: causes the programme to evaluate the specified power of a switch and write the result to the output file
quaternion: evaluate quaternionic switch polynomial invariants
rack-polynomial: evaluate the finite switch polynomial invariants
rack-terms=<k>: set the global value k for the number of terms used to calculate rack polynomials
sawollek: evaluate Sawollek's normalized Conway polynomial
silent: do not generate any output to the command line (stdout), used for batch processing
vogel: apply the vogel algorithm to a labelled peer code
wait[=<n>]: force wait information to be displayed
weyl: evaluate Weyl algebra switch polynomial invariants

With the wait option, a value may also be included, wait=n, to set the wait threshold to n.

After each option from a set of option brackets is processed, the programme checks to see that conflicting options have not been specified and terminates if a conflict is found. The programme does not complain if unrelated options are specified.

The following are valid examples of lines in an input file containing options

[burau]
[burau,delta1-only] ; only display the Alexander polynomial for these braids
[quaternion,wait]
[quaternion, output, wait=10]

These programme options are in addition to any specified on the command line, the intention is to allow the user to type

braid fred

and for the file fred to contain all the required parameters. However, if fred contains only the parameter keyword burau, the command

braid -p fred

would, in addition to selecting the Burau matrix representation, only display the Alexander polynomial for the links contained in fred

back to input file format          back to top          back to braid programme

Premature Termination of an Input Files

It is sometimes required to force processing of additional braid or immersion code input to stop after a certain point in the file. As input files grow in size, editing comment characters into the file can be inconvenient, so an alternative is to include a line containing just the uncommented word exit. The programme will then stop searching for input data when it reaches that point in the file.

Note that the whole file is scanned for switch data, it is only when scanning for input data that the exit line is processed.

back to input file format          back to top          back to braid programme

Example Input File

Finally, here is a complete example of an input file, another example is provided with distributions of the braid programme:

;Example Input File for the braid programme

;some alternative programme options, un-comment the one required
;[burau,delta1-only] ; a simple output for the Burau invariants of the braid words in the file
;[vogel] ; run the Vogel algorithm for the labelled peer codes in the file
;[weyl] ; calculate the invariants for all braid words and labelled immersion codes
        ; using all of the Weyl algebra switches in the file
;[matrix] ; calculate the invariants for all braid words and labelled immersion codes
          ; using all of the matrix-switches in the file

;First we define some quaternionic switches, note these will only be used in the quaternion case
S = (1,1,0,0) (0,0,0,1) ; this is the default quaternionic switch without the t-variable
S[t] = (1,0,0,-1) (0,1,-1,0) ; this switch specifies the use of the the variable t

-- virtual trefoil ; this is the title line
s1s1t1
; and a labelled immersion code for it
(-0 -2 -1) / - * -

;exit               ; uncomment the exit on this line to terminate processing here

; in the next braid definition we have a rather trivial braid statement
-- K2
w1 =-s1-s2s1t2-s1s2s1t2 ; comments may appear on any line
w1

-- K3 ; the Kishino knot
s1s2s1t2-s1-s2-s1t2
(-0 -2 -1 -3 -5 -4) / - + * + - *

-- This braid is another example of Stephen Bigelow's
w1 =s4-s5-s2s1
w2 =-s4s5s5s2-s1-s1
w3 =-w1s3w1
w4 =-w2s3w2
-w3-w4w3w4

; Here is a classical braid, the Conway knot
s2s2s2s1-s3-s2-s2s1-s2s1-s3
; and here is the corresponging Gauss code
-1 2 -3 5 -11 1 -2 3 4 -8 9 11 -5 -6 7 -9 10 -4 6 -7 8 -10 / + + + + - - - + - + -

; Let's add a matrix switch as an afterthought
; the switch matrix switch E2, this takes a LONG time to process
S = a, 0, 0, a/a-1, b, c, b^2+a-1/c-ca, b/1-a

; Here's a Weyl algebra switch
; The switches used will depend on the command line options supplied
; or the options that are not commented out in this file.
; example Weyl switches
;S = WP,3 ,3
;S = WT,2,2
;S = WQ,2
;S = WQ,2 ,2
;S=WUVG, 2, x, 1, 0, x, x, 0, 1, x ; Note: lower case variables again
;S=WQUV, 0, q, 0, 1, 1, 1/1-q, q-1/q, 0, 1/q-q^2 ;
;S=WQUVG, 3, q, 0, 1, 1, 1/1-q, q-1/q, 0, 1/q-q^2 ;

; Here are some long knots

;-- the fly
;L(0 2 1)/- + *

;-- the dead fly
;L+2(0 2 1)/+ - * ; infinity moved forwards two arcs

back to input file format          back to top          back to braid programme

12. Version History

The first released version was 6.1.b1, supporting the Burau and quaternion matrix representations, calculation of Alexander polynomials, 0th and 1st ideal polynomials for quaternionic representations, Dynnikov test and Dowker code calculation.

Version 7.0 (not released on the web) introduced calculation of Sawollek's normalized Conway polynomial.

Version 8.0 added the Vogel algorithm for evaluating braid words from Gauss codes, the ability to include programme options in input files, the writing of an output file in "input" format, and support of the alphabetical notation for classical braids.

Version 9.0 added the Gauss code and labelled immersion code calculations. It added the calculation of DeltaiC and DeltaiR as further options to the quaternionic representations. Version 9 changed the meaning of two programme options (see below), and aligned the terminology used for the Burau and Alexander representations to that in [1]. This meant that what had previously been referred to as the Burau representation was henceforth referred to as the Alexander representation and vice versa. The term Alexander polynomial was retained for Delta_1 of the Burau representation according to common practise.

The option changes introduced in version 9 are as follows:

    option               old meaning        new meaning           new option 
                                                                for old meaning 
      c                  dowker code     calculate Delta_1^C          d
      i                 input as output    imersion code              I

Version 9.0 also extended the Vogel algorithm to handle labelled immersion code descriptions of virtual knots. This corrected an error that was found in the version 8.0 implementation of the Vogel algorithm.

Version 10 was a major update to the structure of the code, making it much more object oriented. This was partly motivated by the requirement to add support for matrix switch invariants but was also long overdue from a coding standpoint. Version 10 introduced use of the fundamental equation ([5]) to calculate C and D from A and B when evaluating switch matrices. This version also included support of a simple web interface to the programme.

Version 11 added support for Weyl algebra switches, calaulation mod p for all switches, control over the use of the variable t, and changed the default behaviour for calculating Delta1. Previous versions only calculated Delta1 when Delta0 was zero, now Delta1 is always calculated, unless the user specifies otherwise. Version 11 was also supplied with a much more feature rich web interface that allowed access to most of the common command line options.

Version 11.1 tidied up the internal structure of the code and made several behind-the-scenes changes, but did not alter the functionality from Version 11.0.

Version 11.2 added an option for the programme to report explicitly whether polynomial invariant switch elements satisfy A=D and B=C. It also corrected an error in the HTML used for the web interface that caused a problem with some browsers.

Version 12.0 introduced support for long knots, termination of further calculation of E1 generators if a unit is encountered, and added various improvements to the web interface for the programme. It also corrected an error in the calculation of Delta1 for non-commutative switches when Delta0 was non-zero (see the bug tracker below).

In version 12.0, one of the source code header files was renamed from Quaternion.h to quaternion-scalar.h. This was done to avoid a conflict with another header file quaternion.h experienced in some operating systems, such as Windows and MAC OS X.

In version 12.0, the matrix representation produced from a labelled immersion code was changed so that the switch action at a real crossing was more natural, whilst not affecting the results.

In version 12.0, the option for mapping quaternionic matrix representations into Mn(R[t,t-1]) was removed, since it proved to be of no theoretical value.

Version 12.1 was a maintenance release, see the bug tracker below.

Version 12.2 added automatic handling of the concatenation product for long knots via the # syntax in an input file.

Version 13.0 added support for the HOMFLY polynomial, and changed the command line syntax for selecting programme tasks and options.

Version 14.0 added support for the fixed-point invariant and finite-switch polynomial invariants.

Version 15.0 added the bracket polynomial for knotoids and extended the dowker code tool to accommodate labelled immersion codes as input.

Version 16.0 added support of labelled peer codes and the silent option for batch processing. The Vogel algorithm was updated to support labelled peer codes and had support for Gauss codes and labelled immersion codes removed. This reflected the cleaner structure of the January 2011 update to the Vogel algorithm.

Version 16.0 removed support for the (erroneous) Nicholson polynomial.

Version 16.1 and 16.2 (September 2011 and November 2012 respectively) added the flip-braid option and "flip" braid qualifier that renumbers the strands of a braid in the opposite order (equivalent to turning over a braid in R^3) before calculating fixed point invariants.

Version 17.0 (January 2013)added the Kauffman bracket and Jones Polynomial to the function bracket_polynomial, it also added support for Gauss codes when calculating these two polynomials, which entailed creating a modified form of the generic code data structure for Gauss codes to allow for the fact that Gauss codes describe only classical crossings and not virtual crossings. Version 17.0 also introduced support for the affine index polynomial invariant for virtual knots. A tool for converting labelled peer codes or immersion codes was added to allow testing of the affine index polynomial.

back to top          back to braid programme

13. Bug Tracker

  • The braid word algebra of assignment statements and braid statements did not work in version 6.1.b1, since they were confused with switch definitions in the code(!). This is corrected in version 8.0
  • In version 8.0 the degrees of variables in quotient polynomials with two or more variables was calculated incorrectly. This bug caused the programme to hang in an infinite loop. It was corrected in version 9.0
  • In version 8.0 the function that sets s=1 when evaluating Alexander polynomials was called without first checking that there were indeed variables present in the polynomial. This bug caused a segmentation fault, it was corrected in version 9.0.
  • In version 8.0 the implementation of the Vogel algorithm for virtual braids was found to have a theoretical bug that invalidated the braid words produced in some cases. This was corrected in version 9.0.
  • Version 10 added support for matrix switch representations but the R_module representation for immersion codes set an internal variable incorrectly that made the Delta_1 calculation cause a segmentation fault. This was corrected in version 11.1.
  • In version 11.0 the bigint right-shift operator left redundant leading zeros in the bigint representation that caused the bigint division operator to generate a floating point exception. This was corrected in version 11.1.
  • In version 11.0 the rational<bigint> scalar variant absolute value member function returned the value, not the absolute value(!). This was corrected in version 11.1.
  • In version 11.0 the quaternion class abs() function returned it's argument unchanged so that the polynomial output operator worked properly, which meant that the abs function was mathematically incorrect (it should return the quaternion's modulus). Therefore in 11.1 the abs() function was removed for the quaternion class, since the modulus function is not required, and the polynomial output operator rewritten.
  • In version 11.0 the inverse of the quantum Weyl algebra switch matrix was set incorrectly from a formula, rather than being calculated directly, therefore giving incorrect values for the polynomial invariants calculated with the switch. This was corrected in version 11.1.
  • In version 11.0 the HTML used to generate part of the web interface was incorrect: although some browsers tollerated the error, later versions of Firefox do not. This was corrected in version 11.2.
  • In version 11.0 the default behaviour was changed so that Delta1 was calculated even when Delta0 was non-zero. However, in the non-commutative case Delta0 was not included as a generator of Delta1 which meant that when Delta0 was non-zero the value calculated for Delta1 was not always correct. This error was corrected in version 12.0.
  • Version 12.1 corrected a memory leak in the absolute function for scalars, abs(const scalar& c). It also corrected a memory leak in the function used to calculate R-module representations from labelled immersion codes.
  • Reference [6] contains a typographic error in the description of a Weyl algebra over a truncated poynomial ring, interchanging the matrices u and v. The error was included in version 11.0 and corrected in version 12.1.
  • Version 12.1 also corrected an error for the cases n >= 3 in the setting up of the matrix v for the Weyl algebra over the truncated polynomial ring .
  • Version 12.1 corrected an error that displayed polynomial coefficients equal to -1 mod p incorrectly for the case p > 2.
  • Version 12.2 corrected an error in the renumbering of a labelled immersion code for long knots when the point at infinity is moved by an even number of semi-arcs.
  • back to top          back to braid programme

    References:

    [1] A. Bartholomew and R. Fenn. Quaternionic Invariants of Virtual Knots and Links (J Knot Theory Ramifications Vol. 17 No. 2 (2008) 231-251).

    [2] A. Bartholomew. An Application of Vogel's Algorithm to Classical Links and Virtual Knots

    [3] J. Sawollwk. On Alexander-Conway Polynomials For Virtual Knots and Links

    [4] P. Dehornoy. Braids and Self-Distributivity. Progress in Mathematics no 192 Birkha user,(2000)

    [5] P. Budden and R. Fenn. The equation [B,(A-1)(A,B)]=0 and Virtual Knots and Links Fund. Math 184 (2004).19 29

    [6] R. Fenn and V. Turaev. Weyl Algebras and Knots. J. Geometry and Physics 57 (2007) 1313-1324

    [7] A. Bartholomew, R. Fenn, N. Kamada, S. Kamada, New Invariants of Long Virtual Knots, Kobe J. Math 27 (2010) 21-33

    [8] L. H. Kauffman. Introduction to Virtual Knot Theory, arXiv:1101.0665v1

    [9] V. Turaev. Knotoids, arXiv:1002.4133v4

    [10] L. H. Kauffman. An Affine Index Polynomial Invariant of Virtual Knots, arXiv:1211.1601v1

    back to top          back to braid programme