chap2.txt

  
  2 OpenMath functionality in GAP
  
  
  2.1 Viewing OpenMath representation of an object
  
  2.1-1 OMPrint
  
  OMPrint( obj )  function
  
  OMPrint  writes  the  default XML OpenMath encoding of GAP object obj to the
  standard output.
  
  One can try it with different GAP objects to see if they can be converted to
  OpenMath  and  learn  how  their OpenMath representation looks like. Here we
  show the encoding for lists of integers and rationals:
  
    Example  
    
    gap> OMPrint( [ 1, 1/2 ] );     
    <OMOBJ xmlns="http://www.openmath.org/OpenMath" version="2.0">
    	<OMA>
    		<OMS cd="list1" name="list"/>
    		<OMI>1</OMI>
    		<OMA>
    			<OMS cd="nums1" name="rational"/>
    			<OMI>1</OMI>
    			<OMI>2</OMI>
    		</OMA>
    	</OMA>
    </OMOBJ>
    
  
  
  Strings are encoded using <OMSTR> tags:
  
    Example  
    
    gap> OMPrint( "This is a string" );
    <OMOBJ xmlns="http://www.openmath.org/OpenMath" version="2.0">
    	<OMSTR>This is a string</OMSTR>
    </OMOBJ>
    
  
  
  Cyclotomics   may   be  encoded  in  different  ways  dependently  on  their
  properties:
  
    Example  
    
    gap> OMPrint( 1-2*E(4) );      
    <OMOBJ xmlns="http://www.openmath.org/OpenMath" version="2.0">
    	<OMA>
    		<OMS cd="complex1" name="complex_cartesian"/>
    		<OMI>1</OMI>
    		<OMI>-2</OMI>
    	</OMA>
    </OMOBJ>
    gap> OMPrint(E(3));       
    <OMOBJ xmlns="http://www.openmath.org/OpenMath" version="2.0">
    	<OMA>
    		<OMS cd="arith1" name="plus"/>
    		<OMA>
    			<OMS cd="arith1" name="times"/>
    			<OMI>1</OMI>
    			<OMA>
    				<OMS cd="algnums" name="NthRootOfUnity"/>
    				<OMI>3</OMI>
    				<OMI>1</OMI>
    			</OMA>
    		</OMA>
    	</OMA>
    </OMOBJ>
    
  
  
  Various encodings may be used for various types of groups:
  
    Example  
    
    gap> OMPrint( Group( (1,2) ) );
    <OMOBJ xmlns="http://www.openmath.org/OpenMath" version="2.0">
    	<OMA>
    		<OMS cd="permgp1" name="group"/>
    		<OMS cd="permutation1" name="right_compose"/>
    		<OMA>
    			<OMS cd="permut1" name="permutation"/>
    			<OMI>2</OMI>
    			<OMI>1</OMI>
    		</OMA>
    	</OMA>
    </OMOBJ>
    gap> OMPrint( Group( [ [ [ 1, 2 ],[ 0, 1 ] ] ] ) );
    <OMOBJ xmlns="http://www.openmath.org/OpenMath" version="2.0">
    	<OMA>
    		<OMS cd="group1" name="group_by_generators"/>
    		<OMA>
    			<OMS cd="linalg2" name="matrix"/>
    			<OMA>
    				<OMS cd="linalg2" name="matrixrow"/>
    				<OMI>1</OMI>
    				<OMI>2</OMI>
    			</OMA>
    			<OMA>
    				<OMS cd="linalg2" name="matrixrow"/>
    				<OMI>0</OMI>
    				<OMI>1</OMI>
    			</OMA>
    		</OMA>
    	</OMA>
    </OMOBJ>
    gap> OMPrint( FreeGroup( 2 ) );                      
    <OMOBJ xmlns="http://www.openmath.org/OpenMath" version="2.0">
    	<OMA>
    		<OMS cd="fpgroup1" name="free_groupn"/>
    		<OMI>2</OMI>
    	</OMA>
    </OMOBJ>
    
  
  
  Producing OpenMath representation of polynomials, one may get a warning:
  
    Example  
    
    gap> x:=Indeterminate(Rationals,"x");; y:=Indeterminate(Rationals,"y");;
    gap> OMPrint(x^2+y);
    #I  Warning : polynomial will be printed using its default ring 
    #I  because the default OpenMath polynomial ring is not specified 
    #I  or it is not contained in the default OpenMath polynomial ring.
    #I  You may ignore this or call SetOpenMathDefaultPolynomialRing to fix it.
    <OMOBJ xmlns="http://www.openmath.org/OpenMath" version="2.0">
    	<OMA>
    		<OMS cd="polyd1" name="DMP"/>
    		<OMA id="polyring9qiY2oOaiITWUORb" >
    			<OMS cd="polyd1" name="poly_ring_d"/>
    			<OMS cd="setname1" name="Q"/>
    			<OMI>2</OMI>
    		</OMA>
    		<OMA>
    			<OMS cd="polyd1" name="SDMP"/>
    			<OMA>
    				<OMS cd="polyd1" name="term"/>
    				<OMI>1</OMI>
    				<OMI>0</OMI>
    				<OMI>1</OMI>
    			</OMA>
    			<OMA>
    				<OMS cd="polyd1" name="term"/>
    				<OMI>1</OMI>
    				<OMI>2</OMI>
    				<OMI>0</OMI>
    			</OMA>
    		</OMA>
    	</OMA>
    </OMOBJ>
    
  
  
  Indeed,  now  when  another  polynomial will be printed, it will belong to a
  ring  with  a  different  identifier  (despite  GAP  will be able to perform
  arithmetical  operations  on  these polynomials like when they belong to the
  same ground ring):
  
    Example  
    
    gap> OMPrint(x+1);
    #I  Warning : polynomial will be printed using its default ring 
    #I  because the default OpenMath polynomial ring is not specified 
    #I  or it is not contained in the default OpenMath polynomial ring.
    #I  You may ignore this or call SetOpenMathDefaultPolynomialRing to fix it.
    <OMOBJ xmlns="http://www.openmath.org/OpenMath" version="2.0">
    	<OMA>
    		<OMS cd="polyd1" name="DMP"/>
    		<OMA id="polyring0LqlkhnCyLldcoBl" >
    			<OMS cd="polyd1" name="poly_ring_d_named"/>
    			<OMS cd="setname1" name="Q"/>
    			<OMV name="x"/>
    		</OMA>
    		<OMA>
    			<OMS cd="polyd1" name="SDMP"/>
    			<OMA>
    				<OMS cd="polyd1" name="term"/>
    				<OMI>1</OMI>
    				<OMI>1</OMI>
    			</OMA>
    			<OMA>
    				<OMS cd="polyd1" name="term"/>
    				<OMI>1</OMI>
    				<OMI>0</OMI>
    			</OMA>
    		</OMA>
    	</OMA>
    </OMOBJ>
    
  
  
  Thus,  the  warning means that it is not guaranteed that the polynomial ring
  will  have  the same identifier <OMA id="polyring..." > when another or same
  polynomial  from this ring will be printed next time. If this may constitute
  a  problem,  for  example,  if  a list of polynomial is being exchanged with
  another  system  and  it is crucial that all of them will belong to the same
  ring,    then    such   ring   must   be   created   explicitly   and   then
  SetOpenMathDefaultPolynomialRing must be called:
  
    Example  
    
    gap> x:=Indeterminate(Rationals,"x");; y:=Indeterminate(Rationals,"y");;
    gap> R:=PolynomialRing(Rationals,[x,y]);;
    gap> SetOpenMathDefaultPolynomialRing(R);
    gap> OMPrint(x^2+y);
    <OMOBJ xmlns="http://www.openmath.org/OpenMath" version="2.0">
    	<OMA>
    		<OMS cd="polyd1" name="DMP"/>
    		<OMA id="polyring9eNcBGFHXkjl2kWh" >
    			<OMS cd="polyd1" name="poly_ring_d"/>
    			<OMS cd="setname1" name="Q"/>
    			<OMI>2</OMI>
    		</OMA>
    		<OMA>
    			<OMS cd="polyd1" name="SDMP"/>
    			<OMA>
    				<OMS cd="polyd1" name="term"/>
    				<OMI>1</OMI>
    				<OMI>0</OMI>
    				<OMI>0</OMI>
    			</OMA>
    			<OMA>
    				<OMS cd="polyd1" name="term"/>
    				<OMI>1</OMI>
    				<OMI>0</OMI>
    				<OMI>0</OMI>
    			</OMA>
    		</OMA>
    	</OMA>
    </OMOBJ>
    
  
  
  Now  we  can  see  that  both  polynomials  belong to the ring with the same
  identifier,  and  the OpenMath representation of the 2nd polynomial properly
  reflects that it belongs to a polynomial ring with two variables.
  
    Example  
    
    gap> OMPrint(x+1);  
    <OMOBJ xmlns="http://www.openmath.org/OpenMath" version="2.0">
    	<OMA>
    		<OMS cd="polyd1" name="DMP"/>
    		<OMR href="#polyring9eNcBGFHXkjl2kWh" />
    		<OMA>
    			<OMS cd="polyd1" name="SDMP"/>
    			<OMA>
    				<OMS cd="polyd1" name="term"/>
    				<OMI>1</OMI>
    				<OMI>0</OMI>
    				<OMI>0</OMI>
    			</OMA>
    			<OMA>
    				<OMS cd="polyd1" name="term"/>
    				<OMI>1</OMI>
    				<OMI>0</OMI>
    				<OMI>0</OMI>
    			</OMA>
    		</OMA>
    	</OMA>
    </OMOBJ> 
    
  
  
  2.1-2 OMString
  
  OMString( obj )  function
  
  OMString  returns  a  string  with  the default XML OpenMath encoding of GAP
  object  obj. If used with the noomobj option, then initial and final <OMOBJ>
  tags will be omitted.
  
    Example  
    
    gap> OMString(42);
    "<OMOBJ xmlns=\"http://www.openmath.org/OpenMath\" version=\"2.0\"> <OMI>42</OMI> </OMOBJ>"
    gap> OMString([1,2]:noomobj);    
    "<OMA> <OMS cd=\"list1\" name=\"list\"/> <OMI>1</OMI> <OMI>2</OMI> </OMA>"
    
  
  
  
  2.2 Reading OpenMath code from streams and strings
  
  2.2-1 OMGetObject
  
  OMGetObject( stream )  function
  
  stream  is  an  input  stream (see InputTextFile (Reference: InputTextFile),
  InputTextUser   (Reference:   InputTextUser),   InputTextString  (Reference:
  InputTextString),             InputOutputLocalProcess            (Reference:
  InputOutputLocalProcess),  InputOutputTCPStream (SCSCP: InputOutputTCPStream
  (for   client)),   InputOutputTCPStream  (SCSCP:  InputOutputTCPStream  (for
  server)))  with  an  OpenMath  object on it. OMGetObject takes precisely one
  object  off  stream  and  returns  it  as  a GAP object. Both XML and binary
  OpenMath encoding are supported: autodetection is used.
  
  This  may  be used to retrieve objects from a file. In the following example
  we  demonsrate  reading the same content in binary and XML formats using the
  test files supplied with the package (the package autodetects whether binary
  or XML encoding is used):
  
    Example  
    
    gap> txml:=Filename(DirectoriesPackageLibrary("openmath","tst"),"test3.omt");;   
    gap> tbin:=Filename(DirectoriesPackageLibrary("openmath","tst"),"test3.bin");;   
    gap> xstream := InputTextFile( txml );; bstream := InputTextFile( tbin );;   
    gap> x:=OMGetObject(xstream); y:=OMGetObject(bstream);
    912873912381273891
    912873912381273891
    gap> x:=OMGetObject(xstream); y:=OMGetObject(bstream);
    E(4)
    E(4)
    gap> CloseStream(xstream);CloseStream(bstream);
    
  
  
  To  paste  an  OpenMath  object  directly  into  standard  input execute the
  following command in GAP:
  
    Example  
    
    gap> s:= InputTextUser();; g := OMGetObject(s); CloseStream(s);
    gap> 
    
  
  
  For  XML  OpenMath,  this  function  requires that the GAP package GAPDoc is
  available.
  
  2.2-2 EvalOMString
  
  EvalOMString( omstr )  function
  
  This  function  is  an  analog  of  EvalString  (Reference: EvalString). Its
  argument  omstr  must  be  a  string  containing  a  single OpenMath object.
  EvalOMString will return the GAP object represented by omstr.
  
  If omstr contains more OpenMath objects, the rest will be ignored.
  
    Example  
    
    gap> s:="<OMOBJ><OMS cd=\"setname1\" name=\"Z\"/></OMOBJ>";;
    gap> EvalOMString(s);
    Integers
    gap> G:=SL(2,5);; G=EvalOMString(OMString(G));
    true
    
  
  
  
  2.3 Writing OpenMath code to streams
  
  While  it  is possible to read OpenMath code directly from a stream, writing
  OpenMath  to  streams  uses  a  different setup. It requires special objects
  called  OpenMath  writers,  which  encapsulate  streams and may be viewed as
  transducers accepting GAP objects and writing them to a stream in the XML or
  binary OpenMath
  
  Such  setup  makes it possible to re-use the same stream for both binary and
  XML  OpenMath  communication,  using different OpenMath writers in different
  calls.  It  also  allows  to  re-use  most of the high-level code for GAP to
  OpenMath  conversion,  having separate methods for generating binary and XML
  OpenMath  only  for low-level output (OpenMath tags and basic objects). This
  makes  easier adding support to new mathematical objects and private content
  dictionaries  as  described  in Chapter 3 since it does not require changing
  the low-level functionality.
  
  2.3-1 IsOpenMathWriter
  
  IsOpenMathWriter Category
  IsOpenMathXMLWriter Category
  IsOpenMathBinaryWriter Category
  
  IsOpenMathWriteris   a   category   for   OpenMath   writers.   It  has  two
  subcategories: IsOpenMathXMLWriter and IsOpenMathBinaryWriter.
  
  2.3-2 OpenMathXMLWriter
  
  OpenMathXMLWriter( s )  function
  
  for  a  stream  s,  returns  an  object  in the category IsOpenMathXMLWriter
  (2.3-1).
  
  2.3-3 OpenMathBinaryWriter
  
  OpenMathBinaryWriter( s )  function
  
  for a stream s, returns an object in the category OpenMathBinaryWriter.
  
  2.3-4 OMPutObject
  
  OMPutObject( stream, obj )  function
  OMPutObjectNoOMOBJtags( stream, obj )  function
  
  OMPutObject writes (appends) the XML OpenMath encoding of the GAP object obj
  to  output  stream  stream  (see  InputTextFile  (Reference: InputTextFile),
  OutputTextUser  (Reference:  OutputTextUser),  OutputTextString  (Reference:
  OutputTextString),  InputOutputTCPStream  (SCSCP:  InputOutputTCPStream (for
  client)), InputOutputTCPStream (SCSCP: InputOutputTCPStream (for server))).
  
  The  second  version  does  the  same  but without <OMOBJ> tags, what may be
  useful for assembling complex OpenMath objects.
  
    Example  
    
    gap> g := [[1,2],[1,0]];;
    gap> t := "";
    ""
    gap> s := OutputTextString(t, true);;
    gap> w:=OpenMathXMLWriter( s );
    <OpenMath XML writer to OutputTextString(0)>
    gap> OMPutObject(w, g);
    gap> CloseStream(s);
    gap> Print(t);
    <OMOBJ xmlns="http://www.openmath.org/OpenMath" version="2.0">
    	<OMA>
    		<OMS cd="linalg2" name="matrix"/>
    		<OMA>
    			<OMS cd="linalg2" name="matrixrow"/>
    			<OMI>1</OMI>
    			<OMI>2</OMI>
    		</OMA>
    		<OMA>
    			<OMS cd="linalg2" name="matrixrow"/>
    			<OMI>1</OMI>
    			<OMI>0</OMI>
    		</OMA>
    	</OMA>
    </OMOBJ>
    
  
  
  2.3-5 OMPlainString
  
  OMPlainString( string )  function
  
  OMPlainString wraps the string into a GAP object of a special kind called an
  OpenMath  plain  string.  Internally such object is represented as a string,
  but  OMPutObject (2.3-4) threat it in a different way: instead of converting
  it  into  a  <OMSTR>  object,  an  OpenMath  plain  string  will  be plainly
  substituted  into  the output (this explains its name) without decorating it
  with <OMSTR> tags.
  
  It  is  assumed  that OpenMath plain string contains valid OpenMath code; no
  actual  validation  is performed during its creation. Such functionality may
  be  useful  to compose some OpenMath code at the GAP level to communicate it
  to  the  other  system,  in  particular, to send there symbols which are not
  supported by GAP, for example:
  
    Example  
    
    gap> s:=OMPlainString("<OMS cd=\"nums1\" name=\"pi\"/>");
    <OMS cd="nums1" name="pi"/>
    gap> OMPrint(s);                                       
    <OMOBJ xmlns="http://www.openmath.org/OpenMath" version="2.0">
    	<OMS cd="nums1" name="pi"/>
    </OMOBJ>
    
  
  
  
  2.4 Utilities
  
  2.4-1 OMTestXML
  
  OMTestXML( obj )  function
  OMTest( obj )  function
  
  Converts  obj  to  XML OpenMath and back. Returns true if and only if obj is
  unchanged  (as  a  GAP object) by this operation. The OpenMath standard does
  not  stipulate  that  converting to and from OpenMath should be the identity
  function so this is a useful diagnostic tool.
  
    Example  
    
    gap> OMTestXML([[1..10],[1/2,2+E(4)],ZmodnZObj(2,6),(1,2),true,"string"]);     
    true
    
  
  
  OMTest is a synonym to OMTestXML
  
  2.4-2 OMTestBinary
  
  OMTestBinary( obj )  function
  
  Converts obj to binary OpenMath and back. Returns true if and only if obj is
  unchanged  (as  a  GAP object) by this operation. The OpenMath standard does
  not  stipulate  that  converting to and from OpenMath should be the identity
  function so this is a useful diagnostic tool.
  
    Example  
    
    gap> OMTestBinary([[1..10],[1/2,2+E(4)],ZmodnZObj(2,6),(1,2),true,"string"]);     
    true