README

   1 ion README
   2 ------
   3
   4 WHAT IS IT:
   5   a collection of generally useful routines
   6   (and experimental algorithms :)
   7
   8 INCLUDING:
   9   * general maths (most functions support both scalars and list/array-likes)
  10   ** factorials
  11   ** fast sum of series 1,2,3,4,5 ... N
  12   ** number of sequences of N size taken from a set of K size
  13   ** number of places a sequence of length N can be subdivided
  14   ** round N to nearest power of B
  15   ** convert a power of B, N, to an exponent of B, such that B**E == N
  16   ** find common denominator
  17   ** find all integers that divide evenly into N
  18   ** linear/spline interpolation of a 1d series of values
  19   * spatial maths
  20   ** subclassable Grid type
  21   ** grid snapping and 'is-in-cell'
  22   ** polar/cartesian transform
  23   ** polar distance
  24   ** calculate triple of weights based on position in triangle
  25   * randomization
  26   ** return true P% of the time
  27   ** weighted sampling from a set of items
  28   ** fill weighted boxes in a roughly even way
  29   ** randomly dispense contents of a box
  30   ** convert nested percentage weights to flat 0..1 weights
  31   ** dice roll (single, and iterative/infinite)
  32   ** chain iterator, which yields values while percentage chance of success
  33      rolls succeed, and stops as soon as they fail.
  34      Like OHRRPGCE 'chain attack/ chain %' option
  35   * misc
  36   ** find numeric limits of data types (builtin types or simple numpy types)
  37   ** sort sequence according to template
  38
  39 REQUIREMENTS:
  40
  41 just Python 2.5, as far as I know.
  42
  43 having NumPy installed will make certain parts of the API more
  44 flexible and much faster, though. (eg. sum of series 1,2,3,4,5...N can be
  45 calculated using a single polynomial evaluation)
  46
  47 Matplotlib might be eventually required for generating function plots
  48 in docs.
  49 it will not be required for just using ion.
  50
  51
  52 CONTRIBUTIONS:
  53
  54 are welcomed, of course. These are some areas that particularly need work:
  55  * more comprehensive unit testing
  56  * better docstrings
  57    (use http://www.scipy.org/scipy/numpy/wiki/CodingStyleGuidelines as a guide)
  58  * better sphinx docs (currently I mostly use autodoc directive, and the docs need
  59    better organization too)
  60  * better PEP 8 conformance (partial) -- what I'm aiming for is
  61    similar, just requires a space between function names and
  62    (parameter, lists). see ion/__init__.py for a good example.
  63
  64
  65 CONTACT:
  66
  67 please send patches, bug reports, feedback + co. to
  68 David Gowers <00ai99 AT gmail DOT com>
  69 (replacing ' AT ' with '@' and ' DOT ' with '.' )
  70
  71
  72
  73
  74
  75 NOTE:
  76 there are no capitals missing in this document.
  77 not capitalizing the first word in each sentence is a
  78 deliberate choice inspired by Lojban (www.lojban.org).