clav-cli.1

   1 .Dd 2016-12-31
   2 .Dt CLAV-CLI 1
   3 .Os
   4 .Sh NAME
   5 .Nm clav-cli
   6 .Nd Visualize quivers on console
   7 .Sh SYNOPSIS
   8 .Nm
   9 .Oo
  10 .Fl f
  11 .Ar filename
  12 .Oc
  13 .Sh DESCRIPTION
  14 .Nm
  15 is a text-based program to interact with quivers.  It is intended to be
  16 used in situations where
  17 .Nm clav-sdl
  18 is unusable, and where by-hand computation is inconvenient.
  19 .Sh OPTIONS
  20 .Bl -tag -width Ds
  21 .It Fl f
  22 Start by opening file
  23 .Ar filename ,
  24 which is of the format written by
  25 .Nm
  26 and
  27 .Nm clav-sdl .
  28 If this option is not provided, a rather uninteresting default quiver is loaded.
  29 .El
  30 .Sh INFORMATION
  31 When
  32 .Nm
  33 starts, it shows a sample quiver, which does not have many interesting
  34 properties.
  35 .Pp
  36 Vertices are displayed in a vertical list.  The left-hand column displays
  37 the index of the vertex, the right displays the name.
  38 .Nm
  39 interacts with vertices by index for compactness' sake.
  40 .Pp
  41 Edges are displayed by weight in a matrix.  The entry of row i, column
  42 j is edge weight ε_{ij} of the quiver
  43 .Pq a blank entry represents 0 .
  44 .Sh CONTROL
  45 The quiver is controlled by primitive text commands. No tab
  46 completion/history is implemented. Help is available by typing
  47 .Sq help .
  48 .Pp
  49 The following commands are available.
  50 .Bl -tag -width Ds
  51 .It help
  52 Print a help message.
  53 .It print
  54 Display the quiver, as described in
  55 .Sx INFORMATION.
  56 .It mutate Ar idx
  57 Mutate the quiver at the vertex with index
  58 .Ar idx .
  59 .It mutatename Ar str
  60 Mutate the quiver at the vertex with name
  61 .Ar str .
  62 .It delete Ar idx
  63 Delete the vertex with index
  64 .Ar idx .
  65 .It delete Ar idx-one idx-two
  66 Delete edges between vertices with indices
  67 .Ar idx-one
  68 and
  69 .Ar idx-two .
  70 The order of the two parameters is unimportant.
  71 .It vertex
  72 Create a new vertex, called
  73 .Sq v .
  74 .It edge Ar i Ar j Ar p / Ar q
  75 Add an edge from
  76 .Ar i
  77 to
  78 .Ar j .
  79 The weights of both directions of the edge will be modifed by the
  80 following formula
  81 .Po where
  82 .Ar i
  83 is
  84 .Ar idx-one
  85 and
  86 .Ar j
  87 is
  88 .Ar idx-two
  89 .Pc :
  90 .Dl ε_{ij} := ε_{ij} + (p · F_j) / (q · GCD(F_i, F_j))
  91 .Dl ε_{ji} := ε_{ij} - (p · F_i) / (q · GCD(F_i, F_j))
  92 where
  93 .Ar F_i
  94 and
  95 .Ar F_j
  96 are the fatnesses of the vertices with indices
  97 .Ar i
  98 and
  99 .Ar j
 100 respectively.
 101 .Pp
 102 Omitting
 103 .Ar q
 104 is permitted; it implies using
 105 .Sq 1
 106 for
 107 .Ar q .
 108 .It rename Ar idx Ar str
 109 Changes the name of the vertex numbered
 110 .Ar idx
 111 .Po which is shown by
 112 .Sq help
 113 .Pc
 114 to be
 115 .Ar str .
 116 .It renamename Ar str1 Ar str2
 117 As
 118 .Sq rename ,
 119 but the vertex is selected by current name. If the name is ambiguous,
 120 this command will fail.
 121 .It incfat Ar idx
 122 Increment the fatness of the vertex at index
 123 .Ar idx
 124 by one.
 125 .It decfat Ar idx
 126 Decrement the fatness of the vertex at index
 127 .Ar idx
 128 by one.
 129 .It save Ar path
 130 Save the current quiver to
 131 .Ar path .
 132 The file will be readable by
 133 .Nm clav-sdl .
 134 .It load Ar path
 135 Load the quiver from
 136 .Ar path
 137 .Pq discarding the current quiver .
 138 The file may have been written by
 139 .Nm clav-sdl .
 140 .El
 141 .Sh EXAMPLES
 142 Example quivers may have been installed along with this program,
 143 typically in
 144 .Pa /usr/share/clav/ .
 145 .Sh SEE ALSO
 146 .Xr clav 1
 147 .Xr clav-cli 1
 148 .Sh BUGS
 149 Edge weights are, for performance reasons
 150 .Po see
 151 .Xr clav-mutation-find 1
 152 .Pc , stored as fractions with
 153 numerator and denominator in system-dependent ranges.  While it probably
 154 will not be an issue for
 155 .Sq interesting
 156 usage, causing edge weights to increase arbitrarily will eventually cause
 157 .Nm
 158 to compute an unrepresentable edge weight.  In this situation,
 159 .Nm
 160 will terminate with a diagnostic message rather than display incorrect
 161 results.
 162 .Pp
 163 Files saved by
 164 .Nm
 165 are readable by
 166 .Nm clav-sdl ,
 167 but because
 168 .Nm
 169 is not graphical, there will be no good x/y information associated with
 170 any vertices created by
 171 .Nm .
 172 This will probably be confusing until the quiver is rarranged by a user.
 173 .Sh AUTHORS
 174 .An S. Gilles Aq Mt sgilles@math.umd.edu