helpinfo.txt

                     Braid v28.0 Help Information

The full syntax of the programme is

    braid --<task> [-<short_options>][--<long_option>][<infile>[<outfile>]]
	
The <task> is a keyword identifying the required task, valid task keywords are:

    affine-index		evaluate the affine index polynomial invariant
    alexander           evaluate Alexander switch polynomial invariants
    arrow-polynomial    evaluate the arrow polynomial invariant of a classical or virtual knot, 
	                    link, knotoid or multi-knotoid	
    automorphism        evaluate commutative automorphism switch polynomial invariants
    burau               evaluate Burau switch polynomial invariants
    doodle-Q-poly       the Q-polynomial for doodles with one component
    dowker              calculate the Dowker code for the closure of a braid, provided 
                        it is a knot, or of a labelled peer code or labelled immersion code
    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 a Gauss code
    hamiltonian         determine a Hamiltonian circuit in the shadow of a knot or link
    homfly              evaluate the HOMFLY polynomial for the closure of a braid
    immersion           evaluate a labelled immersion code
    info                display status information about the braid
    jones-polynomial    evaluate the Jones polynomial
    kauffman-bracket    evaluate the normalized Kauffman bracket polynomial
    knotoid-bracket     evaluate Turaev's extended bracket polynomial for a knotoid
    matrix              evaluate matrix switch polynomial invariants
    mock                mock Alexander polynomial invariants of knotoids
    parity-arrow        evaluate Kaestner and Kauffman's parity arrow polynomial
    parity-bracket      evaluate Manturov's parity bracket polynomial
    peer                evaluate a labelled peer code
    prime               determine whether a given diagram is prime; i.e is not a connected sum or has a 3-connected shadow
    quaternion          evaluate quaternionic switch polynomial invariants
    rack-polynomial     evaluate the finite switch polynomial invariants
    sawollek            evaluate Sawollek's normalized Conway polynomial 
    turning-number      evaluate the turning number of a given diagram
    vogel               apply the Vogel algorithm to a labelled peer code
    weyl                evaluate Weyl algebra switch polynomial invariants

In fact, a <task> is just an example of a <long_option>. Any of the programme option keywords that may appear as an input 
file programme option may be used as a <long_option>.  The other <long_options> available are:

    complex-delta1          calculate Delta_1^C rather than Delta_1^H for quaternionic switches
    delta1-only             display polynomial output for Delta_1 only
    double-braid            calculate the Kamada double covering of all the braids in the input file
    equality                test for A=D or B=C in switch when calculating switch polynomial invariants
    extra-output            display additional polynomial invariant output
    fixed-point             finite biquandle fixed point invariant
    flat-crossings          create flat Reidemeister II moves when executing the Vogel algorithm 
                            consider crossings to be flat when testing for prime knots, so include crossing test
    flip-braid              flip all the braids in the input file
    format                  format the output file so that it may be used as an input file later
    invert-braid            invert all the braids in the input file
    HC-count                count the number of Hamiltonian circuits in a diagram
    HC-edges                create Hamiltonian circuits from edges rather than crossings
    HC-list-all             find all of the Hamiltonian circuits in a diagram
    line-reflect            reflect all the braids in the file in a horizontal line drawn south of the braid
    lpgc                    calculate the left preferred Gauss code, rather than a standard gauss code
    mod-p=n                 calculate mod p with p=n (only used for non-Weyl algebra switches)
    no-auto-delta1          only calculate Delta_1 if Delta_0 is zero
    no-even-writhe          normalize the parity bracket polynomial with the full writhe rather than the even writhe
    no-expanded-bracket     do not expand D=(-A^2-A^{-2}) in bracket polynomials
    no-normalize-bracket    do not normalize bracket polynomial invariants
    normalize-quaternions   normalize quaternionic polynomial invariants
    opgc                    calculate the over preferred Gauss code, rather than a standard gauss code;
    OU-format               write Gauss codes as a sequence (O|U)<crossing-num><crossing-sign>;
    PD-format               write Gauss code as a planar diagram
    plane-reflect           reflect all the braids in the file in the plane of the page
    power=n                 evaluate the nth power of the switch when calculating switch polynomial invariants
    raw-output              produce raw output, that is the result only without descriptive text
    relaxed-parity          evaluate the relaxed variant of the parity arrow polynomial
    remove=n                remove the n-th component from a peer code
    rho                     use the Study rho mapping for calculating Study determinants
    satellite[=n]           determine the peer code of the n-parallel cable satellite of a knot's peer code before carrying 
                            out the required programme task, n defaults to 2
    show-parity-peer-codes  show peer codes in addition to unoriented left preferred Gauss codes in parity bracket polynomial output;	
    show-varmaps            show variable mappings instead of substituting mapped variables in polynomial output
    silent                  do not generate any output to the command line (stdout)
    TeX-polynomials         display output polynomials in TeX format (not supported for the Jones polynomial)
    ulpgd                   calculate the unoriented left preferred Gauss data, rather than a standard gauss code;
    uopgc                   calculate the unoriented over preferred Gauss code, rather than a standard gauss code;
    wait[=n]                display determinant wait information, (based on nxn minors, so larger n produces less frequent output)
    zig-zag-delta           include the delta with K_i and Lambda_i variables when calculating the arrow polynomial

The supported <short_options> are:

    #      debug    
    c[{2}] calculate Delta_i^C rather than Delta_i^H for quaternionic switches
      {2}  always calculate codimension 2 determinant from complex Study Delta_1
    d      evaluate the Kamada double covering for braids (used only by the fixed-point task)
    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
    M      do not remove Reidemeister II moves when calculating labelled peer codes from braid words
    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
    O      produce raw output (values only, no descriptive text)
    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 (rack-polynomials)
    V      Do not use the t-variable with quaternionic switches
    W[=n]  force wait information to be displayed, if n is supplied, set the wait threshold to n
    z      do not calculate Delta_1 when Delta_0 is non-zero
    Z      display Delta_1 polynomials only

Multiple options may be specified at once, but no spaces are permitted within the option string.  The 'c' option has a single 
suboption 2, specified as c{2}

When the Burau or Alexander tasks are chosen, the programme evaluates the Burau matrix representation, M, of a braid word or 
immersion code.  For virtual knots and links, the 0th ideal polynomial is evaluated.  By default the programme always calculates 
the 1st ideal polynomial, even if the 0th ideal polynomial is non-zero.  Using the z option this behaviour may be suppressed 
(note that the 0th ideal polynomial is zero for all classical knots and links).  

The switch used for the Burau and Alexander cases is

        S = 1-st  t      
            s     0   

If the Alexander task is selected, the variable s is set to 1 before displaying the 0th ideal polynomial.  The variable s is always 
set to 1 in order to calculate the 1st ideal polynomial so that the hcf of the generators may be evaluated.

When the quaternionic matrix representation is selected, the programme determines a matrix representation based either on the default 
quaternionic switch, or one supplied by the user.  The programme evaluates the 0th and 1st ideal polynomials for both the classical 
and virtual cases, unless the z option is used to suppress the 1st ideal polynomial.

The default quaternionic switch is the Budapest switch:

        S = 1+i   -jt
            jt^-1 (1+i)


The matrix, Weyl and commutative automorphism switch options proceed in a similar manner to the quaternionic option.  Here, however, a 
matrix switch or Wely algebra switch generally contains multiple variables, so only the generators of the 1st ideal polynomial are calculated.

The Dowker and immersion code options only yield a code if the closure of the braid is a knot, and may therefore be used as test that the 
closure is indeed connected.  Note that Dowker codes are only defined for classical braids, whilst labelled immersion codes are defined for 
virtual and classical braids.  The Dowker code option may also be allplied to a labelled immersion code, which are only defined for knots.

During the operation of some of the tasks large determinants may need to be calculated for some input data.  The wait option provides a 
comfort signal that indicates the programme is running when engaged in a particularly time consuming task.  Please see the user documentation 
for more details. 

If an <infile> is supplied it may contain a number of braid definitions Labeled immersion codes or Gauss codes to which the chosen options are 
applied successively.  The input file may also contain a number of quaternionic representations, and even default programme options to be applied 
to the file's contents.  The format of the input file is described in the user documentation

A copy of the output produced by the programme is placed in the file 'braid.out' created in the same directory as the one from which the programme 
was started.  This filename may be overridden by specifying an <outfile>; if no <infile> is used but it is required to specify an <outfile>,
the empty string must be supplied as a placemarker, as in the command line

braid -b "" fred


Input format
============

Since the programme deals with virtual braids, we cannot use the 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 allow us to introduce virtual crossings as t1, t2, t3, etc.

A braid word may be followed by one or more braid qualifiers that provide additional information about the braid.  
Braid qualifiers are specified within braces immediately following the braid statement, multiple qualifiers may be included, 
separated by spaces or commas.  

 - The "doodle" qualifier indicates that the braid should be regarded as a doodle rather than a knot
 - The "double" qualifier indicates that the braid should be replaced by the Kamada double covering of the braid before it is processed.
 - The "flip" qualifier that indicates that the braid strands should be renumbered in the opposite direction before the braid is processed.
 - The "invert" qualifier that indicates that the braid should be inverted (reflected in a vertical line so the order of the generators is 
   reversed and the sign of classical crossings toggled)
 - The "line-reflect" qualifier that indicates that the braid should be reflected in a horizontal line south of the braid (strands renumbered 
   and signs of classical crossings toggled)
 - The "plane-reflect" qualifier that indicates that the braid should be reflected in the plane of the diagram (signs of classical crossings toggled)
 - The "welded" qualifier indicates that the braid should be regarded as a welded knot or link

Here are some examples of braid qualifiers: 

    -s1-s2s1t2-s1s2s1t2{welded}
    s1s2t1t2s2s1 {flip}
    s1s2t1t2s2s1 {flip,invert}
    s1s2t1t2s2s1 {flip,invert,line-reflect}
    s1s3s2s1s3s2s1s3s2{doodle}
	

Labelled peer codes
+++++++++++++++++++

A labelled peer code is derived from labelling consecutive semi-arcs in a diagram and from this labelling determining the odd numbered peer edges 
for each even edge.  The components of a link diagram must be numbered so each crossing has an odd edge and an even edge arriving at the crossing with respect 
to the orientation induced by the numbering.  The odd peer edges are written in the ascending order of  the corresponding even edges, with the peers of even edges
belonging to different components separated by commas.  The peers associated with type I crossings are written as negative numbers and those associated with 
type II crossings are written as positive numbers.  The colection of peers is enclosed within square brackets, followed by a '/' character and followed
the labels associated with each crossing.  Further details of the syntax of a labelled peer code are given in the user documentation; here is an example of a 
labelled peer code for a link with two components.

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

Labelled peer codes may be specified with qualifiers, in a similar manner to braids, enclosed in braces. The following qualifiers are supported:

    shift<shift-vector>
    satellite[=n]

Shift vector
------------
A shift vector moves the starting point for the numbering of each component of a diagram backwards with respect to the orientation by a number of semi-arcs. 

[-11 9,-3 1 -13 5 -7]/ + - - + - + - {shift[0,2]}

If the shift value is positive it 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.  

[-11 9,-3 1 -13 5 -7]/ + - - + - + - {shift[-1,3]} ; this is a valid shift vector

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. 

[-11 9,-3 1 -13 5 -7]/ + - - + - + - {shift[-1,2]} ; another valid shift vector

Satellites
----------

The satellite qualifier causes the peer code to be replaced by that for the satellite link formed by taking a number of concentric copies, n, of the unlink in a 
solid torus and a companion knot, K, described by the original peer code.  The value of n defaults to 2.

If the writhe (sum of signs) of K is w, the solid torus is twisted -2w times, which produces a satellite whose writhe is w*S.

[3 5 1]/+ - * {satellite=3}
 
   

Long knots are specified as labelled immersion codes, prefixed with "L:", as in 


L:[3 5 1]/+ + +

Knotoids
--------

A knotoid K is also specified using immersion codes 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 immersion code determined by labelling 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 crossing number in the immersion 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.  The following is 
the labelled peeeer code of a knotoid

[-3 -11 -1 -9 -5 -7^]/+ + + + + - ; a classical knotoid
[-3 5 -9^ 1 -11, -7]/+ - + * - - ; a virtual multi-knotoid

labelled immersion codes (see below) are also supported, though deprecated:

(-0 4 -2 6^ -5 -3 1) / + + - + + - -

A knot-type knotoid may be specified be prefixing the labelled peer code with "K:"

K:[-3 -5 -1]/+ + +
K:[-5 7 -11 9 3 -1]/+ - + + - -

Gauss codes
+++++++++++

An example of a Gauss code used by the Jones and Kauffman bracket polynomial tasks is

1 -3 4 -1 +2 -4 3 -2 / + + - -

On the left of the '/' character is the code describing the progress around the knot (link components are separated by commas) and to the right of the '/' is 
the parity of each crossing in the link diagram.  Note that the parity of a crossing given in a Gauss code does not have the same meaning as a label
assigned to a crossing in a labelled peer or immersion code.  Full details of the code specifications may be found in the user documentation.

Gauss codes for classical and virtual links are also supported using the "under/over" syntax
O1-O2-U1-O3-O4-U2-U4-U3- ; a virtual knot
U1+U2-,O3-,O1+O2-U3-

The Gauss code of a doodle or flat link similarly numbers the crossings of the diagram and follows each component from an arbitrary staring point.  As we traverse a 
crossing the code records whether the other strand crosses our path from left to right or from right to left, according to the given orientation.  Crossing types are 
then labelled with the "flat" decoration '#'

L1 L2 R1 R2 L3 L4 R3 R4 / # # # #

Planar diagram data
+++++++++++++++++++
 
The programme supports planar diagram descriptions of knots, links, knotoids and multi-knotoids.  Arcs between classical crossings (or the leg and head of a knotoid) 
are labelled sequentially from 1 as we trace each unicursal component. For virtual knots and links, the components may be considered in any order and with any chosen 
orientation and any arc may be chosen as the starting point for each component.  

Each crossing is described by the set of labels that appear at the crossing, using the standard convention of starting at the ingress under-arc and working anticlockwise 
around the crossing. 

X[4,2,5,1] X[2,9,3,8] X[9,4,10,3] X[11,6,1,5] X[7,11,8,10], X[12,7,12,6]

Knotoids may be described by planar diagrams by preceding the description with "K:", as in the case of Gauss codes. For knotoids and multi-knotoids, it is required that 
the numbering start at the leg of the segment component of the knotoid, so that the arc containing the leg is numbered 1. It is also required that the description of the 
crossing involving the leg of the knotoid appear first in the list of crossings. 

K:X[4,1,5,2] X[2,6,3,7] X[7,3,8,4] X[5,8,6,9] X[9,11,10,12] X[10,12,11,1]


Immersion codes
+++++++++++++++

Immersion codes have been deprecated but limited support remains for backwards compatibility.

An immersion code is derived from labelling consecutive semi-arcs in a diagram and from this labelling determining a permutation of n-1 integers, 
where there are n crossings (virtual or classical) in the diagram.  This presentation is written as a product of cycles in the normal manner but has
signs applied to the elements of the cycles to indicate the 'Type' of the crossings.  A labelled immersion code is formed by following an immersion
code with a '/' character and specifying a number of labels, one for each crossing in order.  The full syntax of a labelled immersion code is given 
in the user documentation; here is a labelled immersion code for the Kishino knot K3 as an example.

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

Dowker-Thistlethwaite codes
+++++++++++++++++++++++++++

Dowker-Thistlethwaite codes for prime knots are supported.  They are converted to peer codes and then the selected task is carried out using the peer code.  
The mirror image described by the peer code is determined by the software and not currently controllable by the user.  Dowker Thistlethwaite codes are 
prefixed by DT: to distinguish them from other input formats.

DT:4 8 10 14 2 16 20 6 22 24 12 26 18
DT:6 -10 -14 12 -16 -2 18 -4 -8

User documentation
==================
These help notes provide only an overview of the capabilities of the braid preogramme.  Full details of all options and input syntax is provided in the user 
documentation.

The user documentation should be available with the programme distribution, and is available on-line at www.layer8.co.uk/maths/braids.