clav-mutation-find.1

   1 .Dd 2016-12-30
   2 .Dt CLAV-MUTATION-FIND 1
   3 .Os
   4 .Sh NAME
   5 .Nm clav-mutation-find
   6 .Nd Find a sequence of mutations transforming one quiver to another.
   7 .Sh SYNOPSIS
   8 .Nm
   9 .Fl s
  10 .Ar start-file
  11 .Fl e
  12 .Ar end-file
  13 .Oo
  14 .Fl c
  15 .Ar edge-cap
  16 .Oc
  17 .Oo
  18 .Fl l
  19 .Ar start-mutation-len
  20 .Oc
  21 .Oo
  22 .Fl m
  23 .Ar max-mutation-len
  24 .Oc
  25 .Oo
  26 .Fl f
  27 .Ar frozen-vertex
  28 .Oo
  29 .Fl f
  30 .Ar frozen-vertex
  31 .Oo ...
  32 .Oc
  33 .Oc
  34 .Oc
  35 .Sh DESCRIPTION
  36 .Nm
  37 loads two quivers from
  38 .Ar start-file
  39 and
  40 .Ar end-file .
  41 If they have the same number of vertices,
  42 .Nm
  43 will attempt to find all sequences of nontrivial mutations which will transform
  44 .Ar start-file
  45 into
  46 .Ar end-file .
  47 .Pp
  48 Progress is printed
  49 .Po although, due to optimizations used, it is not a good estimator of
  50 completion time
  51 .Pc regularly,
  52 and immediate status is available by sending
  53 .Ar SIGUSR1
  54 to the process
  55 .Pq see Sx BUGS .
  56 .Pp
  57 The search is exhaustive up to interchanging mutations which commute
  58 .Po and up to edge-cap, see
  59 .Sx BUGS
  60 .Pc
  61 and single-threaded, though some care has been taken to make it
  62 efficient. Some known checks, such as trivial connectedness, are not
  63 performed.
  64 .Sh OPTIONS
  65 .Bl -tag -width Ds
  66 .It Fl s
  67 The
  68 .Ar start-file
  69 as written by
  70 .Xr clav-sdl 1
  71 or
  72 .Xr clav-cli 1 .
  73 .It Fl e
  74 The
  75 .Ar end-file
  76 as written by
  77 .Xr clav-sdl 1
  78 or
  79 .Xr clav-cli 1 .
  80 The vertices of
  81 .Ar start-file
  82 and
  83 .Ar end-file
  84 must match.
  85 .It Fl c
  86 Set the
  87 .Ar edge-cap ,
  88 as described in
  89 .Sx BUGS .
  90 If unspecified,
  91 .Fa 1 + F
  92 is used, where
  93 .Fa F
  94 is the maximum fatness of a vertex in
  95 .Ar start-file .
  96 .It Fl f
  97 Mark a vertex
  98 .Pq by name
  99 as
 100 .Sq frozen .
 101 Frozen vertices are not considered for mutation.  If you know which
 102 vertices are frozen, this can greatly speed up the search.
 103 .It Fl l
 104 Start searching with mutations at length
 105 .Ar start-mutation-length .
 106 If unspecified,
 107 .Ar 0
 108 is used.
 109 .It Fl m
 110 Set the maximum mutation length. If unspecified, the program will perform
 111 a search bounded by
 112 .Fa (size_t) -1
 113 , which
 114 .Pq depending on hardware
 115 may take multiple universe-lifespans to complete.
 116 .El
 117 .Sh EXAMPLES
 118 .Dl % clav-mutation-find -s "data/C2_U02_C2.txt" -e "data/μ(C2_U02_C2).txt" -f 01 -f 10 -f 12 -f 21 -f 23 -f 32 -f 30 -f 03 -l 7 -m 9
 119 .Dl Exhausted length 7
 120 .Dl Exhausted length 8
 121 .Dl SEQUENCE: \& \& \& \& 0, ∞, 1, 2, 1*, 1, 2*, 0, 1*
 122 .Dl SEQUENCE: \& \& \& \& 0, ∞, 1, 2, 1*, 2*, 0, 1, 1*
 123 .Dl Exhausted length 9
 124 .Sh SEE ALSO
 125 .Xr clav-sdl 1
 126 .Xr clav-cli 1
 127 .Sh BUGS
 128 In general, mutations in quivers may cause edge weights εᵢⱼ to become
 129 arbitrarily high. In general, mutations which cause edge weights to become
 130 large are not interesting, therefore a rather naive implementation of
 131 rational numbers is used for quiver edges. In order to protect this
 132 implementation from overflow errors
 133 .Po and to prevent the search from wasting time in uninteresting
 134 implementations
 135 .Pc
 136 the finder will prune a sequence of mutations if it yields an edge with
 137 any |εᵢⱼ| higher than
 138 .Ar edge-cap .
 139 .Pp
 140 Sending
 141 .Ar SIGUSR1
 142 to
 143 .Nm
 144 will cause the current status to be printed.  For portability concerns,
 145 even if your system supports
 146 .Ar SIGINFO ,
 147 that signal will not cause the same effect. Patches welcome.
 148 .Sh AUTHORS
 149 .An S. Gilles Aq Mt sgilles@math.umd.edu