Mercurial > public > m209

annotate docs/keylist.rst @ 72:8028e409d728 0.1.0

Find changesets by keywords (author, files, the commit message), revision number or hash, or revset expression.
Setting version to 0.1.0. Created MANIFEST.in.
author Brian Neal <bgneal@gmail.com>
date Tue, 23 Jul 2013 20:49:59 -0500
parents 854c5d361011
children
rev   line source
bgneal@64 1 Key lists
bgneal@64 2 ---------
bgneal@64 3
bgneal@64 4 Key lists are represented as a named tuple called ``KeyList``.
bgneal@64 5
bgneal@64 6 .. class:: m209.keylist.KeyList(indicator, lugs, pin_list, letter_check)
bgneal@64 7
bgneal@64 8 As a named tuple, ``KeyList`` has the following attributes:
bgneal@64 9
bgneal@64 10 * ``indicator`` - the string name for the ``KeyList``; must be 2 letters in
bgneal@64 11 the range ``AA`` - ``ZZ``
bgneal@64 12 * ``lugs`` - a string representing the drum lug settings; see below
bgneal@64 13 * ``pin_list`` - a list of six strings which represent key wheel pin
bgneal@64 14 settings; see below
bgneal@64 15 * ``letter_check`` - a string representing the letter check used to verify
bgneal@64 16 operator settings; if unknown this can be ``None`` or an empty string
bgneal@64 17
bgneal@65 18 .. _lug-settings:
bgneal@65 19
bgneal@64 20 Lug settings format
bgneal@64 21 ~~~~~~~~~~~~~~~~~~~
bgneal@64 22
bgneal@64 23 Drum lug settings are often conveniently represented as strings consisting of
bgneal@64 24 at most 27 whitespace-separated pairs of integers separated by dashes. For
bgneal@64 25 example::
bgneal@64 26
bgneal@64 27 lugs = '1-0 2-0 2-0 0-3 0-5 0-5 0-5 0-6 2-4 3-6'
bgneal@64 28
bgneal@64 29 Each integer pair must be in the form ``m-n`` where m & n are integers
bgneal@64 30 between 0 and 6, inclusive. Each integer represents a lug position where
bgneal@64 31 0 is a neutral position, and 1-6 correspond to key wheel positions. If
bgneal@64 32 m & n are both non-zero, they cannot be equal.
bgneal@64 33
bgneal@64 34 If a string has less than 27 pairs, it is assumed all remaining bars have both
bgneal@71 35 lugs in the neutral positions, i.e. ``0-0``.
bgneal@64 36
bgneal@71 37 The order of the pairs within the string does not matter.
bgneal@64 38
bgneal@64 39 To reduce typing and to aid in readability, an alternate shortcut notation is
bgneal@64 40 supported::
bgneal@64 41
bgneal@64 42 lugs = '1-0 2-0*2 0-3 0-5*3 0-6 2-4 3-6'
bgneal@64 43
bgneal@64 44 Any pair that is suffixed by ``*k``, where k is a positive integer, means there
bgneal@64 45 are ``k`` copies of the preceeding lug pair combination. For example, these two
bgneal@64 46 strings describe identical drum configurations::
bgneal@64 47
bgneal@64 48 lugs1 = '2-4 2-4 2-4 0-1 0-1'
bgneal@64 49 lugs2 = '2-4*3 0-1*2'
bgneal@64 50
bgneal@65 51 .. _pin-settings:
bgneal@65 52
bgneal@64 53 Key wheel pin settings
bgneal@64 54 ~~~~~~~~~~~~~~~~~~~~~~
bgneal@64 55
bgneal@64 56 Key wheel pin settings are represented as iterables of letters whose pins are
bgneal@64 57 slid to the "effective" position (to the right). Letters not appearing in this
bgneal@64 58 sequence are considered to be in the "ineffective" position (to the left). If
bgneal@64 59 None or empty, all pins are set to be ineffective.
bgneal@64 60
bgneal@64 61 Examples::
bgneal@64 62
bgneal@64 63 all_ineffective = ''
bgneal@64 64 wheel1 = 'ABDEFHIJMQSUXZ'
bgneal@64 65 wheel2 = 'EINPQRTVXZ'
bgneal@64 66 wheel3 = 'DEFGIKNOSUX'
bgneal@64 67 wheel4 = 'BFGJKRS'
bgneal@64 68 wheel5 = 'ABCDFGHIJMPS'
bgneal@64 69 wheel6 = 'ADEFHIJKN'
bgneal@64 70
bgneal@64 71 Key list example
bgneal@64 72 ~~~~~~~~~~~~~~~~
bgneal@64 73
bgneal@64 74 An example of using the :class:`~m209.keylist.KeyList` is:
bgneal@64 75
bgneal@64 76 .. code-block:: python
bgneal@64 77
bgneal@64 78 from m209.keylist import KeyList
bgneal@64 79
bgneal@64 80 key_list1 = KeyList(
bgneal@64 81 indicator='AA',
bgneal@64 82 lugs='0-4 0-5*4 0-6*6 1-0*5 1-2 1-5*4 3-0*3 3-4 3-6 5-6',
bgneal@64 83 pin_list=[
bgneal@64 84 'FGIKOPRSUVWYZ',
bgneal@64 85 'DFGKLMOTUY',
bgneal@64 86 'ADEFGIORTUVX',
bgneal@64 87 'ACFGHILMRSU',
bgneal@64 88 'BCDEFJKLPS',
bgneal@64 89 'EFGHIJLMNP'
bgneal@64 90 ],
bgneal@64 91 letter_check='QLRRN TPTFU TRPTN MWQTV JLIJE J')
bgneal@64 92
bgneal@64 93 Key list file I/O
bgneal@64 94 ~~~~~~~~~~~~~~~~~
bgneal@64 95
bgneal@64 96 Key lists can be stored in files in config file ("INI") style format using
bgneal@64 97 functions found in the ``m209.keylist.config`` module.
bgneal@64 98
bgneal@64 99 .. function:: m209.keylist.config.read_key_list(fname[, indicator=None])
bgneal@64 100
bgneal@64 101 Reads key list information from the file given by ``fname``.
bgneal@64 102
bgneal@64 103 Searches the config file for the key list with the given indicator. If
bgneal@64 104 found, returns a :class:`~m209.keylist.KeyList` object. Returns ``None`` if
bgneal@64 105 not found.
bgneal@64 106
bgneal@64 107 If ``indicator`` is ``None``, a key list is chosen from the file at random.
bgneal@64 108
bgneal@64 109 .. function:: m209.keylist.config.write(fname, key_lists)
bgneal@64 110
bgneal@64 111 Writes the key lists to the file named ``fname`` in config file format.
bgneal@64 112
bgneal@64 113 ``key_lists`` must be an iterable of :class:`~m209.keylist.KeyList` objects.
bgneal@64 114
bgneal@71 115 .. _key-list-file-format-label:
bgneal@71 116
bgneal@64 117 Key list file format
bgneal@69 118 ~~~~~~~~~~~~~~~~~~~~
bgneal@64 119
bgneal@64 120 An example key list file in config file format is presented below. The label
bgneal@64 121 for each section of the file is the key list indicator.
bgneal@64 122
bgneal@64 123 ::
bgneal@64 124
bgneal@64 125 [CA]
bgneal@64 126 lugs = 0-5*5 0-6*2 1-0*7 1-2 1-3*3 1-6 2-0 3-0*3 3-5*2 3-6 4-5
bgneal@64 127 wheel1 = ABCDFGHJLOPRVWYZ
bgneal@64 128 wheel2 = BCDEIJKPQSUVX
bgneal@64 129 wheel3 = ACDGLNQRSTUV
bgneal@64 130 wheel4 = FGHIJNQRSU
bgneal@64 131 wheel5 = DEIJOQS
bgneal@64 132 wheel6 = BCDEILMNOP
bgneal@64 133 check = RGPRO RTYOO TWYSN GXTPF PNWIH P
bgneal@64 134
bgneal@64 135 [CD]
bgneal@64 136 lugs = 0-4*4 0-5 1-0*7 1-2*2 1-4*3 2-0*2 2-4*2 2-6*2 3-0*4
bgneal@64 137 wheel1 = AEFHIKMPQRSUVZ
bgneal@64 138 wheel2 = ABFGHINORSUVZ
bgneal@64 139 wheel3 = BDEHJKLMNOQRSU
bgneal@64 140 wheel4 = CDEFGHJKMRU
bgneal@64 141 wheel5 = FGHIJOQS
bgneal@64 142 wheel6 = EGIJKLP
bgneal@64 143 check = ZRLWL YRMIZ RZOPN UWMVZ DVGPM H
bgneal@64 144
bgneal@64 145 Generating key lists
bgneal@64 146 ~~~~~~~~~~~~~~~~~~~~
bgneal@64 147
bgneal@64 148 The ``m209`` library contains a function to pseudo-randomly generate a key list
bgneal@71 149 that is based on the procedure described in the 1944 M-209 manual
bgneal@71 150 (see :ref:`references-label` [4]).
bgneal@64 151
bgneal@71 152 .. function:: m209.keylist.generate.generate_key_list(indicator[, lug_selection=None[, max_lug_attempts=MAX_LUG_ATTEMPTS[, max_pin_attempts=MAX_PIN_ATTEMPTS]]])
bgneal@64 153
bgneal@64 154 The only required parameter is ``indicator``, the two-letter indicator for
bgneal@64 155 the key list.
bgneal@64 156
bgneal@64 157 If successful, a :class:`~m209.keylist.KeyList` object is returned.
bgneal@64 158
bgneal@64 159 If a :class:`~m209.keylist.KeyList` could not be generated
bgneal@64 160 a ``KeyListGenError`` exception is raised.
bgneal@64 161
bgneal@64 162 The algorithm is heuristic-based and makes random decisions based upon the
bgneal@64 163 1944 procedure. The actual procedure is loosely specified in the manual, and
bgneal@64 164 much is left up to the human operator. It is possible that the algorithm
bgneal@64 165 cannot find a solution to meet the key list requirements specified in the
bgneal@64 166 manual, in which case it simply tries again up to some set of limits. These
bgneal@64 167 limits can be tweaked using the optional parameters to the algorithm. If no
bgneal@64 168 solution is found after exhausting the limits, a ``KeyListGenError`` is
bgneal@64 169 raised.
bgneal@64 170
bgneal@64 171 The optional parameters are:
bgneal@64 172
bgneal@64 173 * ``lug_selection`` - a list of 6 integers used to drive the lug settings
bgneal@64 174 portion of the algorithm. If not supplied, a list of 6 integers is chosen
bgneal@64 175 from data tables that appear in the 1944 manual. For more information on
bgneal@64 176 the requirements for these integers, see the manual.
bgneal@64 177
bgneal@64 178 * ``max_lug_attempts`` - the maximum number of times to attempt to create
bgneal@64 179 lug settings before giving up
bgneal@64 180
bgneal@64 181 * ``max_pin_attempts`` - the maximum number of times to attempt to generate
bgneal@64 182 key wheel pin settings before giving up
bgneal@64 183