This is SCSCP.info, produced by Macaulay2, version 1.24.11

SCSCP -- SCSCP (Symbolic Computation Software Composability Protocol) support
*****************************************************************************

Description
===========

This package provides an SCSCP (see https://openmath.org/standard/scscp/ )
(Symbolic Computation Software Composability Protocol) server and client.

Author
======

  * Dan Roozemond (see http://magma.maths.usyd.edu.au/~danr )
    <dan.roozemond@gmail.com>

Version
=======

This documentation describes version 0.2.1 of SCSCP.

Source code
===========

The source code from which this documentation is derived is in the file
SCSCP.m2 (see common/share/Macaulay2/SCSCP.m2 ). The auxiliary files
accompanying it are in the directory SCSCP/ (see common/share/Macaulay2/SCSCP/
).

Exports
=======

  * Types
      * RemoteObject -- The class of all remote SCSCP
        objects
      * SCSCPConnection -- The class of all SCSCP
        connections
  * Functions and commands
      * newConnection -- Create a connection to an SCSCP
        server
      * startServer -- Start an SCSCP server
  * Methods
      * Manipulator SCSCPConnection, --
        Close an SCSCP connection
      * "newConnection(String)" -- see newConnection, --
        Create a connection to an SCSCP server
      * "newConnection(String,String)" -- see newConnection,
        -- Create a connection to an SCSCP server
      * "newConnection(String,ZZ)" -- see newConnection,
        -- Create a connection to an SCSCP server
      * SCSCPConnection <== Thing -- Execute
        computations using SCSCP
      * "SCSCPConnection <=== Thing" -- see SCSCPConnection <== Thing,
        -- Execute computations using SCSCP
      * "SCSCPConnection Thing" -- see SCSCPConnection <== Thing,
        -- Execute computations using SCSCP
      * "startServer(String)" -- see startServer, -- Start
        an SCSCP server
      * "startServer(String,String)" -- see startServer, --
        Start an SCSCP server
      * "startServer(ZZ)" -- see startServer, -- Start an
        SCSCP server

For the programmer
==================

The object SCSCP, is a package (Macaulay2Doc).

Manipulator SCSCPConnection -- Close an SCSCP connection
********************************************************

Synopsis
========

  * Operator: SPACE (Macaulay2Doc),
  * Usage:
        close s
  * Inputs:
      * close, a manipulator (Macaulay2Doc), The manipulator
        called close
      * s, an instance of the type SCSCPConnection, A
        connection, previously created with newConnection

See also
========

  * SCSCPConnection Thing -- Execute
    computations using SCSCP
  * newConnection -- Create a connection to an SCSCP
    server

Ways to use this method:
========================

  * Manipulator SCSCPConnection -- Close an
    SCSCP connection

newConnection -- Create a connection to an SCSCP server
*******************************************************

Synopsis
========

  * Usage:
        newConnection (host, port)
  * Inputs:
      * host, a string (Macaulay2Doc), The name or IP address of
        the host to connect to, with an optional colon followed by the number
        of the port
      * port, a string (Macaulay2Doc), or an integer (Macaulay2Doc),
        providing the port number (this argument may be
        omitted)
  * Outputs:
      * an instance of the type SCSCPConnection, The
        connection that was established

Description
===========

The port to connect to may be specified either by giving only one argument of
the form host:port or by specifying the second argument. If neither of these is
present, the port defaults to 26133.

See also
========

  * SCSCPConnection Thing -- Execute
    computations using SCSCP
  * Manipulator SCSCPConnection -- Close an
    SCSCP connection

Ways to use newConnection:
==========================

  * "newConnection(String)"
  * "newConnection(String,String)"
  * "newConnection(String,ZZ)"

For the programmer
==================

The object newConnection, is a method function (Macaulay2Doc).

RemoteObject -- The class of all remote SCSCP objects
*****************************************************

Description
===========

As an example, we store three polynomials on a remote server, compute their
product both locally and remotely, and then ask the remote server whether the
results are equal. Note that <== and <=== may be used without their first
argument if no confusion can arise about the SCSCP server where the computation
should take place.
+-------------------------------------------+
|i1 : QQ[x];                                |
+-------------------------------------------+
|i2 : p1 = x^2+1; p2 = x^3-1; p3 = x+17;    |
+-------------------------------------------+
|i5 : GAP = newConnection "127.0.0.1:26135";|
+-------------------------------------------+
|i6 : gp1 = GAP <=== p1                     |
|                                           |
|o6 = << Remote GAP object >>               |
|                                           |
|o6 : RemoteObject                          |
+-------------------------------------------+
|i7 : gp2 = GAP <=== p2; gp3 = GAP <=== p3; |
+-------------------------------------------+
|i9 : gp = gp1*gp2*gp3                      |
|                                           |
|o9 = << Remote GAP object >>               |
|                                           |
|o9 : RemoteObject                          |
+-------------------------------------------+
|i10 : p = p1*p2*p3;                        |
+-------------------------------------------+
|i11 : <== (gp == p)                        |
|                                           |
|o11 = true                                 |
+-------------------------------------------+
|i12 : close GAP                            |
+-------------------------------------------+
|i13 :                                      |
+-------------------------------------------+
We create matrices in Macaulay2 and compute the order of the group they
generate in GAP. Note that you may have to set
'SCSCPserverAcceptsOnlyTransientCD := false;' in your GAP configuration
(particularly scscp/config.g) in order for this example to work.
+-------------------------------------------------------+
|i1 : m1 = id_(QQ^10)^{1,6,2,7,3,8,4,9,5,0}             |
|                                                       |
|o1 = | 0 1 0 0 0 0 0 0 0 0 |                           |
|     | 0 0 0 0 0 0 1 0 0 0 |                           |
|     | 0 0 1 0 0 0 0 0 0 0 |                           |
|     | 0 0 0 0 0 0 0 1 0 0 |                           |
|     | 0 0 0 1 0 0 0 0 0 0 |                           |
|     | 0 0 0 0 0 0 0 0 1 0 |                           |
|     | 0 0 0 0 1 0 0 0 0 0 |                           |
|     | 0 0 0 0 0 0 0 0 0 1 |                           |
|     | 0 0 0 0 0 1 0 0 0 0 |                           |
|     | 1 0 0 0 0 0 0 0 0 0 |                           |
|                                                       |
|              10        10                             |
|o1 : Matrix QQ   <--- QQ                               |
+-------------------------------------------------------+
|i2 : m2 = id_(QQ^10)^{1,0,2,3,4,5,6,7,8,9}             |
|                                                       |
|o2 = | 0 1 0 0 0 0 0 0 0 0 |                           |
|     | 1 0 0 0 0 0 0 0 0 0 |                           |
|     | 0 0 1 0 0 0 0 0 0 0 |                           |
|     | 0 0 0 1 0 0 0 0 0 0 |                           |
|     | 0 0 0 0 1 0 0 0 0 0 |                           |
|     | 0 0 0 0 0 1 0 0 0 0 |                           |
|     | 0 0 0 0 0 0 1 0 0 0 |                           |
|     | 0 0 0 0 0 0 0 1 0 0 |                           |
|     | 0 0 0 0 0 0 0 0 1 0 |                           |
|     | 0 0 0 0 0 0 0 0 0 1 |                           |
|                                                       |
|              10        10                             |
|o2 : Matrix QQ   <--- QQ                               |
+-------------------------------------------------------+
|i3 : GAP = newConnection "127.0.0.1:26135"             |
|                                                       |
|o3 = SCSCP Connection to GAP (4.dev) on 127.0.0.1:26135|
|                                                       |
|o3 : SCSCPConnection                                   |
+-------------------------------------------------------+
|i4 : G = GAP <=== matrixGroup({m1,m2})                 |
|                                                       |
|o4 = << Remote GAP object >>                           |
|                                                       |
|o4 : RemoteObject                                      |
+-------------------------------------------------------+
|i5 : <== size G                                        |
|                                                       |
|o5 = 10080                                             |
+-------------------------------------------------------+
|i6 : close GAP                                         |
+-------------------------------------------------------+
|i7 :                                                   |
+-------------------------------------------------------+

See also
========

  * newConnection -- Create a connection to an SCSCP
    server
  * Manipulator SCSCPConnection -- Close an
    SCSCP connection
  * SCSCPConnection Thing -- Execute
    computations using SCSCP

For the programmer
==================

The object RemoteObject, is a type (Macaulay2Doc),
with ancestor classes XMLnode (XML), <
MutableHashTable (Macaulay2Doc) < HashTable (Macaulay2Doc)
< Thing (Macaulay2Doc).

SCSCPConnection -- The class of all SCSCP connections
*****************************************************

Methods that use an object of class SCSCPConnection:
====================================================

  * Manipulator SCSCPConnection -- Close an
    SCSCP connection
  * SCSCPConnection <== Thing -- Execute
    computations using SCSCP
  * "SCSCPConnection <=== Thing" -- see SCSCPConnection <== Thing,
    -- Execute computations using SCSCP
  * "SCSCPConnection Thing" -- see SCSCPConnection <== Thing,
    -- Execute computations using SCSCP

For the programmer
==================

The object SCSCPConnection, is a type (Macaulay2Doc),
with ancestor classes MutableHashTable (Macaulay2Doc),
< HashTable (Macaulay2Doc) <
Thing (Macaulay2Doc).

SCSCPConnection <== Thing -- Execute computations using SCSCP
*************************************************************

Synopsis
========

  * Operator: <== (Macaulay2Doc),
  * Usage:
        s x
  * Inputs:
      * s, an instance of the type SCSCPConnection, The
        server that should compute it
      * x, a thing (Macaulay2Doc), The expression to be computed
  * Outputs:
      * a thing (Macaulay2Doc), The result of the computation

Description
===========

As an example, we connect to a locally running SCSCP server:
+-------------------------------------------------------+
|i1 : s = newConnection("127.0.0.1", 26135)             |
|                                                       |
|o1 = SCSCP Connection to GAP (4.dev) on 127.0.0.1:26135|
|                                                       |
|o1 : SCSCPConnection                                   |
+-------------------------------------------------------+
|i2 : s( (hold 2) + 3)                                  |
|                                                       |
|o2 = 5                                                 |
+-------------------------------------------------------+
|i3 : close s                                           |
+-------------------------------------------------------+
|i4 :                                                   |
+-------------------------------------------------------+
We could also explicitly have a look at the OpenMath that's being passed around
+-------------------------------------------------------+
|i1 : s = newConnection("127.0.0.1", 26135)             |
|                                                       |
|o1 = SCSCP Connection to GAP (4.dev) on 127.0.0.1:26135|
|                                                       |
|o1 : SCSCPConnection                                   |
+-------------------------------------------------------+
|i2 : o = openMath ( (hold 2) + 3 )                     |
|                                                       |
|o2 = <OMA                                              |
|       <OMS cd="arith1" name="plus"                    |
|       <OMI "2"                                        |
|       <OMI "3"                                        |
|                                                       |
|o2 : XMLnode                                           |
+-------------------------------------------------------+
|i3 : s(o)                                              |
|                                                       |
|o3 = <OMOBJ                                            |
|       <OMATTR                                         |
|         <OMATP                                        |
|           <OMS cd="scscp1" name="call_id"             |
|           <OMSTR "1"                                  |
|         <OMA                                          |
|           <OMS cd="scscp1" name="procedure_completed" |
|           <OMI "5"                                    |
|                                                       |
|o3 : XMLnode                                           |
+-------------------------------------------------------+
|i4 : value oo                                          |
|                                                       |
|o4 = 5                                                 |
+-------------------------------------------------------+
|i5 : close s                                           |
+-------------------------------------------------------+
|i6 :                                                   |
+-------------------------------------------------------+
Another syntax offered is using the <== and <=== operators. The first of these
denotes a computation that returns the computed object, whereas the second
denotes a computation that returns a reference (i.e. a remote object).
Fortunately, these operators have lower parsing precedence than most others, so
few parentheses will be required.
+-----------------------------------------------------------------------------+
|i1 : s = newConnection("127.0.0.1", 26136)                                   |
|                                                                             |
|o1 = SCSCP Connection to Magma (0.3.0) on 127.0.0.1:26136                    |
|                                                                             |
|o1 : SCSCPConnection                                                         |
+-----------------------------------------------------------------------------+
|i2 : s <== (hold 2)^32                                                       |
|                                                                             |
|o2 = 4294967296                                                              |
+-----------------------------------------------------------------------------+
|i3 : s <=== (hold 2)^333                                                     |
|                                                                             |
|o3 = << Remote Magma object >>                                               |
|                                                                             |
|o3 : RemoteObject                                                            |
+-----------------------------------------------------------------------------+
|i4 : 2^301                                                                   |
|                                                                             |
|o4 = 407407195266897217253689137681875632210293678733187250127228089870876259|
|-----------------------------------------------------------------------------|
|9526673412366794752                                                          |
+-----------------------------------------------------------------------------+
|i5 : s <== o3/o4                                                             |
|                                                                             |
|o5 = 4294967296                                                              |
|                                                                             |
|o5 : QQ                                                                      |
+-----------------------------------------------------------------------------+
|i6 : close s                                                                 |
+-----------------------------------------------------------------------------+
|i7 :                                                                         |
+-----------------------------------------------------------------------------+

See also
========

  * newConnection -- Create a connection to an SCSCP
    server
  * Manipulator SCSCPConnection -- Close an
    SCSCP connection
  * RemoteObject -- The class of all remote SCSCP objects

Ways to use this method:
========================

  * SCSCPConnection <== Thing -- Execute
    computations using SCSCP

startServer -- Start an SCSCP server
************************************

Synopsis
========

  * Usage:
        startServer (host, port)
  * Inputs:
      * host, a string (Macaulay2Doc), The IP address of the
        interface to bind to (may be omitted, and defaults to binding to all
        interfaces)
      * port, a string (Macaulay2Doc), or an integer (Macaulay2Doc),
        providing the port number (defaults to 26133)

Description
===========

The server will keep running indefinitely; it may be stopped by sending a
Ctrl-C. Furthermore, the server forks for every new incoming connection, so
that it can serve many clients simultaneously. The amount of output printed to
the screen is determined by the value of debugLevel.
+-----------------------------------------------------------+
|i1 : debugLevel = 2;                                       |
+-----------------------------------------------------------+
|i2 : startServer(26137)                                    |
|[SCSCP][Server] Listening on :26137                        |
|[SCSCP][Server] Waiting for incoming connection            |
|[SCSCP][Server] Incoming connection. Forking.              |
|[SCSCP][handleIncoming 1] Handling new connection          |
|[SCSCP][handleIncoming 1] Sending announcement             |
|[SCSCP][handleIncoming 1] Waiting for version request...   |
|[SCSCP][handleIncoming 1] Great! Compatible version: '1.3' |
|[SCSCP][Server] Waiting for incoming connection            |
|[SCSCP][handleIncoming 1] 'start' received                 |
|[SCSCP][handleProcedureCall 1] Evaluating procedure call...|
|[SCSCP][handleProcedureCall 1] Returning response...       |
|[SCSCP][handleIncoming 1]  atEndOFFile                     |
|[SCSCP][Server] Child 1 terminated                         |
|                                                           |
+-----------------------------------------------------------+

Ways to use startServer:
========================

  * "startServer()"
  * "startServer(String)"
  * "startServer(String,String)"
  * "startServer(ZZ)"

For the programmer
==================

The object startServer, is a method function (Macaulay2Doc).