NAME
       opetopes - commandline utilies to manipulate XML-encoded opetopes
       
SYNOPSIS
       checkOpetopeFile  XMLFILE
       areIsomorphic  XMLFILE0 XMLFILE1
       listSources  XMLFILE
       computeOneSource  XMLFILE SOURCENAME ?-o OUTPUTPATH?
       computeTarget  XMLFILE ?-o OUTPUTPATH?
       computeAllFacets  XMLFILE
       glueOnto  BOTTOMXMLFILE SOURCENAME TOPXMLFILE ?-o OUTPUTPATH?

DESCRIPTION
       Commandline utilies to manipulate XML-encoded opetopes. In 
       particular, for computing target and source facets, and for 
       computing composition (gluing).  
       
       The notion of opetope (invented by J.Baez and J.Dolan) and the
       algorithms implemented in the scripts refer to the paper
       "Polynomial functors and opetopes" by J.Kock, A.Joyal, M.Batanin,
       and J.-F.Mascari, available from ArXiv:math.QA/.
       
       The scripts require Tcl installed with the tDOM extension.
       
       
       The following commands can be run from the command line.
       They take opetope xml files as input and produce new opetope
       xml files as putput.

checkOpetopeFile  XMLFILE
       Check whether XMLFILE is a valid zoom complex.  This involves 
       checking that dot names and leaf names are unique, that the zoom
       relation holds between consecutive constellations, that every dot
       cuts a valid subtree in the previous constellation, and that
       stopdots have valid references.
       
       Note that the initial condition characterising opetopes among all
       zoom complexes is not checked.  This is to allow working with
       economically represented opetopes (suppressing the constellations in
       degree 0 to 3).

areIsomorphic  XMLFILE0 XMLFILE1
       Try to find an isomorphism between opetope XMLFILE0 and opetope
       XMLFILE1.  If an isormophism is found, the answer is "Opetopes
       isomorphic".  Even if no isomoprhism is found it is still
       theoretically possible that an isomoprhism exists, because the
       comparison algorithm is heuristic.  In that case the answer is 
       "The required bijections could not be found (but might exist)."
       
listSources  XMLFILE
       Return a list of all the names of the source facets of XMLFILE.

computeOneSource  XMLFILE SOURCENAME ?-o OUTPUTPATH?
       Compute the source SOURCENAME of the opetope XMLFILE.  By default
       the result will be written to a file whose name is formed by
       appending "-SOURCENAME.xml" to the name of the opetope in XMLFILE.
       For example,
              computeOneSource foo.xml 13
       will produce a file names foo-13.xml (assuming that the opetope
       inside XMLFILE is called foo).  If the optional argument
       "-o OUTPUTPATH" is given, the new opetope will be written to
       OUTPUTPATH.

computeTarget  XMLFILE ?-o OUTPUTPATH? 
       Compute the target of opetope XMLFILE.  By default the result 
       will be written to a file whose name is formed by appending "-%.xml"
       to the name of the opetope in XMLFILE.  For example, 
              computeTarget foo.xml
       will produce a file names foo-%.xml (assuming that the opetope
       inside XMLFILE is called foo).  If the optional argument 
       "-o OUTPUTPATH" is given, the new opetope will be written to 
       OUTPUTPATH.

computeAllFacets  XMLFILE
       Compute target and all sources of opetop XMLFILE.  The new 
       opetopes are written to separate files according to the default
       name formation rules, as explained in computeOneSource and
       computeTarget, and in the section below.
       
glueOnto  BOTTOMXMLFILE SOURCENAME TOPXMLFILE ?-o OUTPUTPATH?
       Compute the opetope ontained by gluing opetope TOPXMLFILE onto 
       opetope BOTTOMXMLFILE at source SOURCENAME.  For this to make
       sense, it is required that the target of TOPXMLFILE is isomorphic
       to the indicated source of BOTTOMXMLFILE, otherwise the operation
       will fail.  If BOTTOMXMLFILE has name foo, and TOPXMLFILE has
       name bar, then by default the new opetope will be written to
       foo+SOURCENAME+bar.xml.  Another filename can be specified in
       the optional argument "-o OUTPUTPATH".
       

RULES FOR FORMATION OF OPETOPE NAMES
       If an opetope is called "X", then its target will be called "X-%".

       The source of opetope "X" corresponding to dot "12" in ct(X) will be
       called "X-12".

       If opetope "W" is glued onto "X" at source "12", the result will be
       called "X+12+W".

       CAVEAT: The opetope names are those specified at the beginning of
       the XML file, and it might not be the same as the rootname of the
       file.  Of course it is strongly recommended to let the file names
       match the internal name (modulo an .xml extension), to avoid
       confusion.
       
       All xml files produced by the scripts will have concordance between
       the file name (minus the extension) and the internal name, so if a
       new name is specified with an -o newName.xml optional argument, then
       the internal name will automatically be "newName".

       
FILES
       The main file is "opetopes.tcl", source from within the above shell
       scripts.
       
       The DTD file "opetope.xml" is needed internally to parse the opetope
       xml files.  It is ditributed with these scripts, located in the xml 
       directory.

NOTES
       The scripts listed above are only wrappers for much more 
       functionality, which however it would not be convenient to use in
       shell scripts.  To access the full functionality, open a tclsh
       and source the file "opetopes.tcl".  Now the convenience is that
       you can keep the opetopes in memory, assigned to variables, and
       apply operations step by step.  This will generally require some
       basic knowledge about Tcl and the tDOM extension.  
       
       The basic sequence of operations is
              set OP [readOpetope XMLFILE]
       This will create a dom tree in memory corresponding to the XML
       file, and this dom tree can be accessed and manipulated with
       standard Tcl and tDOM techniques.  For example
              set ct [$OP lastChild]
	      set leafList [$ct selectNodes descendant::leaf]
       will produce a list of leaves of the composition tree of the
       opetope.  Many specific opetope operations are implemented
       as domNode methods and can be applied to modify the dom trees
       in place or to produce new dom trees.  In particular, the four
       basic sphere operations (described in [Kock-Joyal-Batanin-Mascari])
       are available.   The last step in the sequence of operations
       may then typically be
              writeOpetope $OP SOMEXMLFILE
       if the opetope resulting from the transformations is desired
       saved to disc.
       
       For the specifications and syntax of the provided procedures, see
       the source file itself which it carefully documented throughout.

SEE ALSO
       The paper "Polynomial functors and opetopes (footnote to a paper of
       Baez and Dolan)", by by J.Kock, A.Joyal, M.Batanin, and
       J.-F.Mascari (ArXiv:math.QA/1234567), as well as the referred-to
       paper "Higher-Dimensional Algebra III: n-Categories and the Algebra
       of Opetopes" by J.Baez and J.Dolan (ArXiv:q-alg/9702014).

AUTHOR
       Joachim Kock <kock@mat.uab.cat>
       
COPYRIGHT
       Copyright (c) 2004-2006, Joachim Kock.  All rights reserved.  
       Distributed under a BSD-style license (see the accompanying file 
       "license").
