GAP 4.8.9 installation with standard packages -- copy to your CoCalc project to get it

1
  
2
  5 Running SCSCP server
3
  
4
  
5
  5.1 Installation of SCSCP procedures
6
  
7
  There may various ways to run SCSCP server, for example:
8
  
9
      allowing generic services like evaluation of arbitrary OpenMath code;
10
  
11
      offering  highly  specialized procedures like identification of groups
12
        of order 512;
13
  
14
      providing access to a database of mathematical objects.
15
  
16
  Each  of  these  use  cases  requires  certain  control  over  the  level of
17
  functionality  exposed to the client. To achieve this, before starting SCSCP
18
  service its provider must call the function InstallSCSCPprocedure (5.1-1) to
19
  make required procedures visible for the client.
20
  
21
  Additionally,  the  service  can  be  made  made accessible only for clients
22
  running  on  the  same  computer,  or  accessible  only through a particular
23
  network  interface,  or  generally accessible. This customization is made at
24
  the  stage  of  starting  the  SCSCP server with the function RunSCSCPserver
25
  (5.2-1).
26
  
27
  5.1-1 InstallSCSCPprocedure
28
  
29
  InstallSCSCPprocedure( procname, procfunc[, description][, narg1[, narg2][, signature]] )  function
30
  Returns:  nothing
31
  
32
  For  a  string procname and a function procfunc, InstallSCSCPprocedure makes
33
  the procfunc available as SCSCP procedure under the name procname, adding it
34
  to  the  transient  OpenMath  content dictionary scscp_transient_1 that will
35
  exist during the service lifetime.
36
  
37
  The  second  argument  procfunc may be either a standard or user-defined GAP
38
  function (procedure, operation, etc.).
39
  
40
  The  rest  of  arguments  are  optional  and  may  be  used  in  a number of
41
  combinations:
42
  
43
      description  is a string with the description of the procedure. It may
44
        be  used  by  the help system. If it is omitted, the procedure will be
45
        reported as undocumented.
46
  
47
      narg1  is  a  non-negative  integer,  specifying the minimal number of
48
        arguments, and narg2 is a non-negative integer or infinity, specifying
49
        the  maximal number of arguments. If narg2 is omitted then the maximal
50
        number  of arguments will be set to narg1. If both narg1 and narg2 are
51
        omitted  then  the minimal number of arguments will be set to zero and
52
        their maximal number will be set to infinity.
53
  
54
      signature  is  the signature record of the procedure. If the signature
55
        is  given,  then  the number of arguments must be explicitly specified
56
        (by  narg1  with  or  without  narg2)  at  least  to zero and infinity
57
        respectively (to ensure proper matching of arguments). Note that it is
58
        completely acceptable for a symbol from a transient content dictionary
59
        to  overstate the set of symbols which may occur in its children using
60
        the  scscp2.symbol_set_all symbol, and to use standard OpenMath errors
61
        to  reject  requests  later  at  the  stage  of  their evaluation. For
62
        example,   using   such   approach,   we  will  define  the  procedure
63
        WS_Factorial  accepting  not only immediate <OMI> objects but anything
64
        which could be evaluated to an integer.
65
  
66
        .  The  signature  must be either a list of records, where i-th record
67
        corresponds  to  the i-th argument, or a record itself meaning that it
68
        specifies  the  signature  for  all  arguments. In the latter case the
69
        record may be rec( ) corresponding to the scscp2.symbol_set_all symbol
70
        (this will be assumed by default if the signature will be omitted).
71
  
72
        If  more  detailed  description  of  allowed  arguments is needed, the
73
        signature  record  (one  for all arguments or a specific one) may have
74
        components CDgroups, CDs and Symbols. The first two are lists of names
75
        of  content  dictionary groups and content dictionaries, and the third
76
        is  a  record  whose  components  are  names  of content dictionaries,
77
        containing   lists   of   names   of   allowed   symbols   from  these
78
        dictionaries,for example:
79
  
80
          Example  
81
          
82
          signature := rec( CDgroups := [ "scscp" ],
83
                        CDs := [ "arith1", "linalg1" ],
84
                        Symbols := rec( polyd1 := [ "DMP", "term", "SDMP" ],
85
                                        polyu := [ "poly_u_rep", "term" ] ) );
86
          
87
        
88
  
89
  In  the  following example we define the function WS_Factorial that takes an
90
  integers  and  returns  its  factorial,  using  only  mandatory arguments of
91
  InstallSCSCPprocedure:
92
  
93
    Example  
94
    
95
    gap> InstallSCSCPprocedure( "WS_Factorial", Factorial );
96
    InstallSCSCPprocedure : procedure WS_Factorial installed. 
97
    
98
  
99
  
100
  In the following example we install the procedure that will accept a list of
101
  permutations  and  return  the number in the GAP Small Groups library of the
102
  group they generate (for the sake of simplicity we omit tests of validity of
103
  arguments, availability of IdGroup for groups of given order etc.)
104
  
105
    Example  
106
    
107
    gap> IdGroupByGenerators:=function( permlist )
108
    > return IdGroup( Group( permlist ) );
109
    > end;
110
    function( permlist ) ... end
111
    gap> InstallSCSCPprocedure( "GroupIdentificationService", IdGroupByGenerators );
112
    InstallSCSCPprocedure : procedure GroupIdentificationService installed. 
113
    
114
  
115
  
116
  After installation, the procedure may be reinstalled, if necessary:
117
  
118
    Example  
119
    
120
    gap> InstallSCSCPprocedure( "WS_Factorial", Factorial );
121
    WS_Factorial is already installed. Do you want to reinstall it [y/n]? y
122
    InstallSCSCPprocedure : procedure WS_Factorial reinstalled. 
123
    
124
  
125
  
126
  Finally, some examples of various combinations of optional arguments:
127
  
128
    Example  
129
    
130
    InstallSCSCPprocedure( "WS_Phi", Phi, 
131
                           "Euler's totient function, see ?Phi in GAP", 1, 1 );
132
    InstallSCSCPprocedure( "GroupIdentificationService", 
133
                           IdGroupByGenerators, 1, infinity, rec() );
134
    InstallSCSCPprocedure( "IdGroup512ByCode", IdGroup512ByCode, 1 );
135
    InstallSCSCPprocedure( "WS_IdGroup", IdGroup, "See ?IdGroup in GAP" );
136
    
137
  
138
  
139
  Note that it is quite acceptable to overstate the signature of the procedure
140
  and  use  only mandatory arguments in a call to InstallSCSCPprocedure, which
141
  will  be  installed  then as a procedure that can accept arbitrary number of
142
  arguments encoded without any restrictions on OpenMath symbols used, because
143
  anyway  the  GAP  system will return an error in case of the wrong number or
144
  type  of  arguments, though it might be a good practice to give a way to the
145
  client  to  get  more precise procedure description a priori, that is before
146
  sending  request.  See  5.3  about  utilities for obtaining such information
147
  about the SCSCP service.
148
  
149
  Some more examples of installation of SCSCP procedures are given in the file
150
  scscp/example/myserver.g.
151
  
152
  5.1-2 OMsymRecord
153
  
154
  OMsymRecord global variable
155
  
156
  This  is the global record from the OpenMath package used for the conversion
157
  from  OpenMath to GAP. It is extended in the SCSCP package by adding support
158
  for  symbols from scscp1 and scscp2 content dictionaries ([FHK+a], [FHK+c]).
159
  Additionally,  InstallSCSCPprocedure (5.1-1) adds to this record a component
160
  corresponding  to  the appropriate transient content dictionary (by default,
161
  scscp_transient_1)  defining  mappings  between  OpenMath  symbols from this
162
  content dictionary and installed SCSCP procedures.
163
  
164
  
165
  5.2 Starting SCSCP server
166
  
167
  5.2-1 RunSCSCPserver
168
  
169
  RunSCSCPserver( servertype, port )  function
170
  Returns:  nothing
171
  
172
  Will  start  the  SCSCP  server at port given by the integer port. The first
173
  parameter servertype is either true, false or a string containing the server
174
  hostname:
175
  
176
      when  servertype  is  true,  the server will be started in a universal
177
        mode and will accept all incoming connections;
178
  
179
      when  servertype is false, the server will be started at localhost and
180
        will not accept any incoming connections from outside;
181
  
182
      when  servertype is a string, for example, "scscp.gap-system.org", the
183
        server  will  be accessible only by specified server name (this may be
184
        useful  to  manage  accessibility  if,  for  example, the hardware has
185
        several network interfaces).
186
  
187
    Example  
188
    
189
    gap> RunSCSCPserver( "localhost", 26133 );
190
    Ready to accept TCP/IP connections at localhost:26133 ...
191
    Waiting for new client connection at localhost:26133 ...
192
    
193
  
194
  
195
  Actually, there is more than one way to run GAP SCSCP server:
196
  
197
      from the GAP session as shown in the example above;
198
  
199
      starting  GAP  as  gap  myserver.g,  where  myserver.g  is  the server
200
        configuration   file   with   the   last   command   being   the  call
201
        RunSCSCPserver,  which  may  take its arguments from the configuration
202
        file scscp/config.g (an example of such configuration file is given in
203
        scscp/example/myserver.g );
204
  
205
      start  GAP  as  a daemon using the script gapd.sh which is supplied in
206
        the  root  directory  of  the  package  (for  the  description  of all
207
        available   options   see  comments  in  gapd.sh)  and  may  overwrite
208
        parameters from scscp/config.g.
209
  
210
  See Section 2.2 about configuring files config.g and gapd.sh.
211
  
212
  
213
  5.3 Procedures to get information about the SCSCP server
214
  
215
  5.3-1 GetServiceDescription
216
  
217
  GetServiceDescription( server, port )  function
218
  Returns:  record
219
  
220
  Returns  the  record with three components containing strings with the name,
221
  version  and description of the service as specified by the service provider
222
  in the scscp/config.g (for details about configuration files, see 2.2).
223
  
224
    Example  
225
    
226
    gap> GetServiceDescription( "localhost", 26133 );
227
    rec( 
228
      description := "Started with the configuration file scscp/example/myserver.g\
229
      on Thu 16 Feb 2017 16:03:56 GMT", service_name := "GAP SCSCP service", 
230
      version := "GAP 4.8.6 + SCSCP 2.2.1" )
231
    
232
  
233
  
234
  5.3-2 GetAllowedHeads
235
  
236
  GetAllowedHeads( server, port )  function
237
  Returns:  record
238
  
239
  Returns  the  record  with components corresponding to content dictionaries.
240
  The  name  of  each component is the name of the content dictionary, and its
241
  the  value is either a boolean or a list of strings. In case it's value is a
242
  list, it contains names of symbols from the corresponding content dictionary
243
  which  are  allowed  to appear as a head symbol (i.e. the first child of the
244
  outermost  <OMA>)  in an SCSCP procedure call to the SCSCP server running at
245
  server:port.  If  it's value is true, it means the server allows all symbols
246
  from the corresponding content dictionary.
247
  
248
  Note  that  it  is acceptable (although not quite desirable) for a server to
249
  overstate  the set of symbols it accepts and use standard OpenMath errors to
250
  reject requests later.
251
  
252
    Example  
253
    
254
    gap> GetAllowedHeads("localhost",26133);
255
    rec( scscp_transient_1 := [ "AClosestVectorCombinationsMatFFEVecFFE", 
256
          "Determinant", "GroupIdentificationService", 
257
          "IO_UnpickleStringAndPickleItBack", "IdGroup512ByCode", "Identity", 
258
          "IsPrimeInt", "Length", "MathieuGroup", "MatrixGroup", 
259
          "NormalizedUnitCFcommutator", "NormalizedUnitCFpower", 
260
          "NrConjugacyClasses", "NrSmallGroups", "NumberCFGroups", 
261
          "NumberCFSolvableGroups", "PointImages", "QuillenSeriesByIdGroup", 
262
          "ResetMinimumDistanceService", "SCSCPStartTracing", "SCSCPStopTracing", 
263
          "Size", "SylowSubgroup", "WS_AlternatingGroup", "WS_AutomorphismGroup", 
264
          "WS_ConwayPolynomial", "WS_Factorial", "WS_FactorsCFRAC", 
265
          "WS_FactorsECM", "WS_FactorsMPQS", "WS_FactorsPminus1", 
266
          "WS_FactorsPplus1", "WS_FactorsTD", "WS_IdGroup", "WS_LatticeSubgroups",
267
          "WS_Mult", "WS_MultMatrix", "WS_Phi", "WS_PrimitiveGroup", 
268
          "WS_SmallGroup", "WS_SymmetricGroup", "WS_TransitiveGroup", "addition" 
269
         ] )
270
    
271
  
272
  
273
  5.3-3 IsAllowedHead
274
  
275
  IsAllowedHead( cd, symbol, server, port )  function
276
  Returns:  true or false
277
  
278
  Checks  whether  the OpenMath symbol cd.symbol, which may be a symbol from a
279
  standard  or  transient OpenMath content dictionary, is allowed to appear as
280
  head  symbol  (i.e.  the  first  child  of  the  outermost <OMA> in an SCSCP
281
  procedure  call to the SCSCP server running at server:port. This enables the
282
  client  to  check  whether a particular symbol is allowed without requesting
283
  the full list of symbols.
284
  
285
  Also,  it is acceptable (although not necessarily desirable) for a server to
286
  overstate  the set of symbols it accepts and use standard OpenMath errors to
287
  reject requests later.
288
  
289
    Example  
290
    
291
    gap> IsAllowedHead( "permgp1", "group", "localhost", 26133 );
292
    true
293
    gap> IsAllowedHead( "setname1", "Q", "localhost", 26133 );
294
    true
295
    gap> IsAllowedHead( "setname1", "R", "localhost", 26133 );
296
    false
297
    
298
  
299
  
300
  5.3-4 GetTransientCD
301
  
302
  GetTransientCD( transient_cd, server, port )  function
303
  Returns:  record
304
  
305
  Returns a record with the transient content dictionary transient_cd from the
306
  SCSCP  server  running  at  server:port.  Names of components of this record
307
  correspond to symbols from the meta content dictionary.
308
  
309
  By  default,  the name of the transient content dictionary for the GAP SCSCP
310
  server  is  scscp_transient_1.  Other  systems  may  use  transient  content
311
  dictionaries  with  another  names,  which,  however, must always begin with
312
  scscp_transient_  and  may  be  guessed  from  the output of GetAllowedHeads
313
  (5.3-2).
314
  
315
    Example  
316
    
317
    gap> GetTransientCD( "scscp_transient_1", "localhost", 26133 );
318
    rec( CDDate := "2017-02-08", 
319
      CDDefinitions := 
320
        [ rec( Description := "Size is currently undocumented.", Name := "Size" ),
321
          rec( Description := "Length is currently undocumented.", 
322
              Name := "Length" ), 
323
          rec( Description := "NrConjugacyClasses is currently undocumented.", 
324
              Name := "NrConjugacyClasses" ), 
325
    ...
326
          rec( Description := "MatrixGroup is currently undocumented.", 
327
              Name := "MatrixGroup" ) ], CDName := "scscp_transient_1", 
328
      CDReviewDate := "2017-02-08", CDRevision := "0", CDStatus := "private", 
329
      CDVersion := "0", 
330
      Description := "This is a transient CD for the GAP SCSCP service" )
331
    
332
  
333
  
334
  5.3-5 GetSignature
335
  
336
  GetSignature( transientcd, symbol, server, port )  function
337
  Returns:  record
338
  
339
  Returns   a   record   with   the   signature   of   the   OpenMath   symbol
340
  transientcd.symbol from a transient OpenMath content dictionary. This record
341
  contains  components corresponding to the OpenMath symbol whose signature is
342
  described,  the  minimal and maximal number of its children (that is, of its
343
  arguments),  and  symbols  which may be used in the OpenMath encoding of its
344
  children.  Note  that it is acceptable for a symbol from a transient content
345
  dictionary  to  overstate the set of symbols which may occur in its children
346
  using  the scscp2.symbol_set_all symbol, and use standard OpenMath errors to
347
  reject  requests  later, like in the example below: using such approach, the
348
  procedure WS_Factorial is defined to accept not only immediate <OMI> objects
349
  but anything which could be evaluated to an integer.
350
  
351
    Example  
352
    
353
    gap> GetSignature("scscp_transient_1","WS_Factorial","localhost",26133);
354
    rec( maxarg := 1, minarg := 1,
355
      symbol := rec( cd := "scscp_transient_1", name := "WS_Factorial" ),
356
      symbolargs := rec( cd := "scscp2", name := "symbol_set_all" ) )
357
    
358
  
359
  
360

361