Operads.cabal

name:                   Operads
version:                1.0
-- Stability:              beta
license:                BSD3
license-file:           LICENSE
category:               Math
copyright:              © 2009 Mikael Vejdemo Johansson
author:                 Mikael Vejdemo Johansson
-- Maintainer:             mik@stanford.edu
-- Bug-reports:            mailto:mik@stanford.edu
-- Homepage:               http://math.stanford.edu/~mik/operads
build-type:             Simple
cabal-version:          >= 1.8
extra-source-files:     
  README 
  CHANGELOG 
  examples/preLieBad.hs 
  examples/example.hs 
  examples/altDual.hs 
  examples/Alternative.hs 
  OperadTest.hs
synopsis:               Groebner basis computation for Operads.
description:            
  This is an implementation of the operadic Buchberger algorithm from Vladimir Dotsenko & 
  Anton Khoroshkin: Groebner bases for operads (arXiv:0812.4069).
  .
  In writing this package, invaluable help has been given by Vladimir Dotsenko and Eric Hoffbeck.
  .
  The user is recommended to run this from within the GHC interpreter
  for exploration, and to write small Haskell scripts for batch
  processing. We hope herewithin to give enough of an overview of the
  available functionality to help the user figure out how to use the
  software package.
  .
  A declaration of a new variable is done in a Haskell script by a
  statement on the form
  .
  @
  var = value
  @
  .
  and in the interpreter by a statement on the form
  .
  @
  let var = value
  @
  .
  Using these, the following instructions should help get you started. I will be writing 
  the instructions aiming for use in the interpreter, for quick starts.
  .
  It is possible to force types by following a declaration by :: and the type signature 
  you'll which. This enables you, for instance, to pick a ground ring without having to set
  coefficients explicitly - see the examples below.
  .
  Note that the Buchberger algorithm in its current shape expects at least a division ring
  as scalar ring.
  .
  The expected workflow for a normal user is as follows.
  .
   1. write the generators of the operadic ideal using 'corolla' and 'leaf' to construct 
      buildingblocks and 'nsCompose', 'shuffleCompose' and 'symmetricCompose' to assemble 
      them into trees. The trees, subsequently, may be assembled into tree polynomials by
  .
      * picking an ordering. The orderings available are 
        'PathPerm', 'RPathPerm', 'PathRPerm', 'RPathRPerm', 
        'PermPath', 'RPermPath', 'PermRPath' and 'RPermRPath', distinguished by reversal 
        of order for either the path comparison or the permutation comparison, as well as
        by whether path or permutation comparison takes precedence.
  .
      * assembling trees and coefficients into an element of the free operad, using '+' for
        addition of operadic elements and '.*.' for scalar multiplication.
  .
  Useful functions for doing this includes, furthermore:
  .
    [@'oet'@] takes a tree and an ordering and gives an operad element. You will have to
              specify the relevant type for this to work -- but we provide the extra type
              'FreeOperad' that only asks for a /LabelType/ to cover most common uses:
  .
    @
    oet tree :: OperadElement /LabelType/ /ScalarType/ /TreeOrdering/
    @
  .
    [@'oek'@] takes a tree, an ordering and a coefficient and gives an operad element
  .
    @
    oek tree PathPerm (3::Rational)
    @
  .
  Example: 
  .
  @
  let t1 = nsCompose 1 (corolla 'a' [2,1]) (corolla 'b' [1,2])
  .
  let b = corolla 'l' [1,2]
  .
  let lb1 = shuffleCompose 1 [1,2,3] b b
  .
  let lb2 = shuffleCompose 1 [1,3,2] b b
  .
  let lb3 = shuffleCompose 2 [1,2,3] b b
  .
  let lo1 = oet lb1 :: FreeOperad Char
  .
  let lo2 = oet lb2 :: FreeOperad Char
  .
  let lo3 = oet lb3 :: FreeOperad Char
  @
  .
  Note that while the Haskell compiler in general is very skilled at guessing types of objects, 
  the system guessing will give up if the type is not well defined. There are several different
  monomial orders allowed, and they are encoded in the type system -- hence the need to annotate
  the instantiation of elements in the free operad with appropriate types.
  .
  2. assemble all generators into a list. Lists are formed by enclosing the elements, 
     separated by commas, in square brackets. Lists must have identical type on all its 
     elements - hence, for instance, you cannot have operadic elements with different monomial
     orderings in the same list. 
  .
  Example:
  .
  @
  let lgb = [lo1 - lo2 - lo3, 2.*.lo1 + 3.*. lo3]
  @
  .
  3. run the algorithm on your basis and wait for it to finish. The entry point to the Buchberger
     algorithm is, not surprisingly, 'operadicBuchberger'.
  .
  Example: 
  .
  @
  let grobner = operadicBuchberger lgb
  @
  .
  The output of 'operadicBuchberger', if it finishes, is a finite Gröbner basis for the ideal spanned 
  by the original generators. If this is quadratic then the operad presented by this ideal is Koszul -
  this may be tested with something like:
  .
  @
  all (==2) $ concatMap operationDegrees grobner
  @
  .
  If you wish to inspect elements yourself, the recommended way to do it is by using the 'pP' function, 
  which outputs most of the interesting elements in a human-readable format. For objects that don't work 
  with pP, just writing the variable name on its own will print it in some format.
  .
  The difference here is related to the ability to save computational states to disk. There are two 
  different functions that will represent a tree or an element of an operad as a String: 'show' and 'pp'.
  Using the former guarantees (with the same version of the source code) that the data can be read back 
  into the system and reused later one; whereas using 'pp' will build a human readable string.


flag MapOperad
  description:       Use the Data.Map based storage for formal linear combinations.
  default:           False

flag UseOldMap
  description:       Don't use the Data.Map wrapper class Math.Operad.Map. This will slow down computation.
  default:           False

library 
  hs-source-dirs: src
  build-depends: 
    base >= 4 && < 5,
    mtl, 
    containers
                                       
  exposed-modules:
    Math.Operad
    Math.Operad.OperadGB
    Math.Operad.OrderedTree 
    Math.Operad.PPrint 
    Math.Operad.MapOperad 
    Math.Operad.Map

  ghc-options:            -Wall -O2 -funbox-strict-fields -Wredundant-constraints
  ghc-prof-options:       -auto-all

  if flag(mapoperad)
    cpp-options:         -DUSE_MAPOPERAD
  if flag(useoldmap)
    cpp-options:         -DUSE_OLDMAP