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 R
  15 .Oc
  16 .Oo
  17 .Fl H
  18 .Oc
  19 .Oo
  20 .Fl c
  21 .Ar edge-cap
  22 .Oc
  23 .Oo
  24 .Fl l
  25 .Ar start-mutation-len
  26 .Oc
  27 .Oo
  28 .Fl m
  29 .Ar max-mutation-len
  30 .Oc
  31 .Oo
  32 .Fl f
  33 .Ar frozen-vertex
  34 .Oo
  35 .Fl f
  36 .Ar frozen-vertex
  37 .Oo ...
  38 .Oc
  39 .Oc
  40 .Oc
  41 .Sh DESCRIPTION
  42 .Nm
  43 loads two quivers from
  44 .Ar start-file
  45 and
  46 .Ar end-file .
  47 If they have the same number of vertices,
  48 .Nm
  49 will attempt to find all sequences of nontrivial mutations which will transform
  50 .Ar start-file
  51 into
  52 .Ar end-file .
  53 .Pp
  54 Progress is printed
  55 .Po although, due to optimizations used, it is not a good estimator of
  56 completion time
  57 .Pc regularly,
  58 and immediate status is available by sending
  59 .Ar SIGUSR1
  60 to the process
  61 .Pq see Sx BUGS .
  62 .Pp
  63 The search is exhaustive up to interchanging mutations which commute
  64 .Po and up to edge-cap, see
  65 .Sx BUGS
  66 .Pc
  67 and single-threaded, though some care has been taken to make it
  68 efficient. Some known checks, such as trivial connectedness, are not
  69 performed.
  70 .Sh OPTIONS
  71 .Bl -tag -width Ds
  72 .It Fl s
  73 The
  74 .Ar start-file
  75 as written by
  76 .Xr clav-sdl 1
  77 or
  78 .Xr clav-cli 1 .
  79 .It Fl e
  80 The
  81 .Ar end-file
  82 as written by
  83 .Xr clav-sdl 1
  84 or
  85 .Xr clav-cli 1 .
  86 The vertices of
  87 .Ar start-file
  88 and
  89 .Ar end-file
  90 must match.
  91 .It Fl c
  92 Set the
  93 .Ar edge-cap ,
  94 as described in
  95 .Sx BUGS .
  96 If unspecified,
  97 .Fa 1 + F
  98 is used, where
  99 .Fa F
 100 is the maximum fatness of a vertex in
 101 .Ar start-file .
 102 .It Fl R
 103 If set, require all non-frozen vertices to participate in the
 104 mutation. This is useful for trying to find flips.
 105 .It Fl H
 106 If set, use a heuristic check (in not ε, not σ) rather than a
 107 strict graph equality for checking whether a mutation sequence is
 108 acceptable.  This is useful for trying to find flips, in which the
 109 general shape of the desired end graph is known, but it is not known
 110 which labels in the start file correspond to which labels in the
 111 end file.
 112 .It Fl f
 113 Mark a vertex
 114 .Pq by name
 115 as
 116 .Sq frozen .
 117 Frozen vertices are not considered for mutation.  If you know which
 118 vertices are frozen, this can greatly speed up the search.
 119 .It Fl l
 120 Start searching with mutations at length
 121 .Ar start-mutation-length .
 122 If unspecified,
 123 .Ar 0
 124 is used.
 125 .It Fl m
 126 Set the maximum mutation length. If unspecified, the program will perform
 127 a search bounded by
 128 .Fa (size_t) -1
 129 , which
 130 .Pq depending on hardware
 131 may take multiple universe-lifespans to complete.
 132 .El
 133 .Sh EXAMPLES
 134 .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
 135 .Dl Exhausted length 7
 136 .Dl Exhausted length 8
 137 .Dl SEQUENCE: \& \& \& \& 0, ∞, 1, 2, 1*, 1, 2*, 0, 1*
 138 .Dl SEQUENCE: \& \& \& \& 0, ∞, 1, 2, 1*, 2*, 0, 1, 1*
 139 .Dl Exhausted length 9
 140 .Dl \&
 141 .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 -H -R
 142 .Dl Exhausted length 7
 143 .Dl Exhausted length 8
 144 .Dl SEQUENCE:  \& \& \& \& 0, ∞, 1, 2, 1*, 1, 2*, 0, 1*
 145 .Dl SEQUENCE:  \& \& \& \& 0, ∞, 1, 2, 1*, 2*, 0, 1, 1*
 146 .Dl SEQUENCE:  \& \& \& \& 0, ∞, 2, 0, ∞, 2, 1, 2*, 1*
 147 .Dl SEQUENCE:  \& \& \& \& 0, ∞, 2*, 0, ∞, 1*, 2*, 2, 1
 148 .Dl SEQUENCE:  \& \& \& \& 0, ∞, 2*, 0, ∞, 2*, 2, 1, 1*
 149 .Dl SEQUENCE:  \& \& \& \& ∞, 2, 0, ∞, 2*, 0, 1*, 2*, 1
 150 .Dl SEQUENCE:  \& \& \& \& ∞, 2, 0, ∞, 2*, 0, 2*, 1, 1*
 151 .Dl SEQUENCE:  \& \& \& \& ∞, 2, 0, 2*, 0, ∞, 1*, 2*, 1
 152 .Dl SEQUENCE:  \& \& \& \& ∞, 2, 0, 2*, 0, ∞, 2*, 1, 1*
 153 .Dl SEQUENCE:  \& \& \& \& ∞, 2*, 0, ∞, 2, 0, 2, 1, 1*
 154 .Dl SEQUENCE:  \& \& \& \& ∞, 2*, 0, 2, 0, ∞, 2, 1, 1*
 155 .Dl SEQUENCE:  \& \& \& \& 2, 0, ∞, 2*, 0, ∞, 1*, 2*, 1
 156 .Dl SEQUENCE:  \& \& \& \& 2, 0, ∞, 2*, 0, ∞, 2*, 1, 1*
 157 .Dl SEQUENCE:  \& \& \& \& 2, 1, ∞, 0, 2*, 0, 2*, ∞, 1*
 158 .Dl SEQUENCE:  \& \& \& \& 2, 1, 2*, 0, ∞, 1*, ∞, 1*, 0
 159 .Dl SEQUENCE:  \& \& \& \& 2*, 0, ∞, 2, 0, ∞, 2, 1, 1*
 160 .Dl SEQUENCE:  \& \& \& \& 2*, 0, 1*, ∞, 2, 0, ∞, 2, 1
 161 .Dl Exhausted length 9
 162 .Sh SEE ALSO
 163 .Xr clav-sdl 1
 164 .Xr clav-cli 1
 165 .Sh BUGS
 166 In general, mutations in quivers may cause edge weights εᵢⱼ to become
 167 arbitrarily high. In general, mutations which cause edge weights to become
 168 large are not interesting, therefore a rather naive implementation of
 169 rational numbers is used for quiver edges. In order to protect this
 170 implementation from overflow errors
 171 .Po and to prevent the search from wasting time in uninteresting
 172 implementations
 173 .Pc
 174 the finder will prune a sequence of mutations if it yields an edge with
 175 any |εᵢⱼ| higher than
 176 .Ar edge-cap .
 177 .Pp
 178 Sending
 179 .Ar SIGUSR1
 180 to
 181 .Nm
 182 will cause the current status to be printed.  For portability concerns,
 183 even if your system supports
 184 .Ar SIGINFO ,
 185 that signal will not cause the same effect. Patches welcome.
 186 .Sh AUTHORS
 187 .An S. Gilles Aq Mt sgilles@math.umd.edu