ion README
------

WHAT IS IT:
  a collection of generally useful routines 
  (and experimental algorithms :)

INCLUDING:
  * general maths (most functions support both scalars and list/array-likes)
  ** factorials
  ** fast sum of series 1,2,3,4,5 ... N
  ** number of sequences of N size taken from a set of K size
  ** number of places a sequence of length N can be subdivided
  ** round N to nearest power of B
  ** convert a power of B, N, to an exponent of B, such that B**E == N
  ** find common denominator
  ** find all integers that divide evenly into N
  ** linear/spline interpolation of a 1d series of values
  ** binary representation of a number
  * spatial maths
  ** subclassable Grid type
  ** grid snapping and 'is-in-cell'
  ** polar/cartesian transform
  ** polar distance
  ** calculate triple of weights based on position in triangle
  * randomization
  ** return true P% of the time
  ** weighted sampling from a set of items
  ** fill weighted boxes in a roughly even way
  ** randomly dispense contents of a box
  ** convert nested percentage weights to flat 0..1 weights
  ** dice roll (single, and iterative/infinite)
  ** chain iterator, which yields values while percentage chance of success
     rolls succeed, and stops as soon as they fail.
     Like OHRRPGCE 'chain attack/ chain %' option
  * misc
  ** find numeric limits of data types (builtin types or simple numpy types)
  ** sort sequence according to template
  ** reverse of zip (flat sequence a,b,c,a,b,c,a,b,c -> a,b,c tuples)
  ** easily read every line or every byte of a file
  ** calculate minimum number of bits required to store a given integer.
  ** quickly set multiple attributes on an object
  ** Metadata class for easy management of metadata,
     with yaml serialization support.

REQUIREMENTS:

just Python 2.5, as far as I know.

pyYAML is required if you want to de/serialize metadata from/to YAML.

having NumPy installed will make certain parts of the API more
flexible and much faster, though. (eg. sum of series 1,2,3,4,5...N can be
calculated using a single polynomial evaluation)

Matplotlib might be eventually required for generating function plots
in docs. 
it will not be required for just using ion.



CONTRIBUTIONS: 

are welcomed, of course. These are some areas that particularly need work:
 * more comprehensive unit testing
 * better docstrings 
   (use http://www.scipy.org/scipy/numpy/wiki/CodingStyleGuidelines as a guide)
 * better sphinx docs (currently I mostly use autodoc directive, and the docs need
   better organization too)
 * better PEP 8 conformance (partial) -- what I'm aiming for is
   similar, just requires a space between function names and
   (parameter, lists). see ion/__init__.py for a good example.
 * running 'cheesecake_index --with-pep8 -p <sdist-output-package-file>' helps to 
   get a metric of most of the above.
   currently (0.02, first release) it gives 71% kwalitee. 
   when the above points are well addressed, I anticipate the 
   kwalitee index rising to ~93%
 * better PKG-INFO. Does 'provides' field need to be specified?
   of course, a downloadable package is good too.


CONTACT:

please send patches, bug reports, feedback + co. to
David Gowers <00ai99 AT gmail DOT com>
(replacing ' AT ' with '@' and ' DOT ' with '.' )





NOTE:
there are no capitals missing in this document. 
not capitalizing the first word in each sentence is a
deliberate choice inspired by Lojban (www.lojban.org).
