Loading...
Searching...
No Matches
Singular Interpreter and related functionality

Main Singular application and its iterpreter (also available as a library)

Some functions are just wrappers over Several involved mathematical algorithms (kernel).

Singular can be easily extended by means of dynamic modules:

- Dynamic modules

How to add kernel functions to the interpreter:

    How to add new kernel commands
    - create a new dynamic module, add your new commands as PROC:
      - create a sub directory of Singular/dyn_modules: Singular/dyn_modules/bla
      - add the name of your sub directory to Singular/dyn_modules/Makefile.am
      - create Singular/dyn_modules/bla/Makefile.am
        (have a look at the other Singular/dyn_modules/*/Makefile.am for an example)
      - your module must contain the following initialization routine,
        where "bla" refers to the (Singular) name for your new procedure
        and bla_proc refers to the C++-implementation of it with
        the following head: static BOOLEAN bla_proc(leftv result, leftv args)

    //------------------------------------------------------------------------
    // initialisation of the module
    extern "C" int SI_MOD_INIT(bla)(SModulFunctions* p)
    {
      p->iiAddCproc("bla.so","bla",FALSE,bla_proc);
      return (MAX_TOK);
    }

    -----------------------------------------------------------------------------
    The following describes how the main Singular kernel commands were constructed,
    but we do not want to change this any more as this would change the Singular
    language (unless an error is found).
    The files not to change are: grammar.y, scanner.l, table.h, tok.h
    and the derived files: grammar.cc, grammar.h, scanner.cc, iparith.inc
    If one of these files really need a change, run make_grammar (for grammar.*)
    or make_table (for table.h).
    The following text serves only as a remainder how iiExprArith etc. work:

    Example: bla

    - add a new CMD token to tok.h (in alphabetic order):
      ....
      BLA_CMD,
      ...
    - decide, how many argument bla should have and find the tok_type:
      1: CMD_1
      2: CMD_2
      3: CMD_3
      1 or 2: CMD_12
      1 or 3: CMD_13
      2 or 3: CMD_23
      1, 2 or 3: CMD_123
      not covered above: CMD_M

    - add a line describing the name, the token and the tok_type
      to array cmds in Singular/table.h:
      { "bla", 0, BLA_CMD, CMD_1},
      (the array is sorted by the name).

    - choose the requirements: one from each group, combined by |
      ALLOW_PLURAL: non-commutative rings allowed
      NO_PLURAL: non-commutative rings not allowed

      ALLOW_RING: coefficients/cring elements may be a ring
      NO_RING: coefficients/cring elements must be a field

      ALLOW_ZERODIVISOR: coefficients/cring elements may be zero divisors
      NO_ZERODIVISOR: coefficients/cring elements must be a domain

      if a requirement from a group is omited,
      the defaults are:  NO_PLURAL | NO_RING | ALLOW_ZERODIVISOR

    - add one (or more) lines for the procedures to call:
      if there is more than one line, all lines for the same operation
      must directly following each other within dArith*

      if tok_type is CMD_1, CND_12, CMD_13, CMD_123,
      to dArith1:
      ,{D(jjBLAH1),   BLA_CMD,   <return type>,  <argument type>  , ALLOW_PLURAL |ALLOW_RING}

      analog for CMD_12, CMD_2, CMD_23, CMD_123
      to dArith2:
      ,{D(jjBLAH2),   BLA_CMD,   <return type>,  <arg1 type>, <arg2 type>, ALLOW_PLURAL |ALLOW_RING}

      analog for CMD_13, CMD_23, CMD_123, CMD_3
      to dArith3:
      ,{D(jjBLAH3),   BLA_CMD,   <return type>,  <arg1 type>, <arg2 type>, <arg3 type>, ALLOW_PLURAL |ALLOW_RING}

      CMD_M is different:
      ,{D(jjBLA_M),   BLA_CMD,  <return type>,  <number of arguments>, ALLOW_PLURAL |ALLOW_RING}

      where a negative "number of arguments" represents:
        -1: any number of arguments
        -2: any number of arguments >0

    Remark: the wrapper routines jjBLA* should be implemented as
        static routines in Singular/iparith.cc

    Remark: valid types for return type/arguments type are:
      - types from table.h: cmds with tok_type ROOT_DECL
      - types from table.h: cmds with tok_type ROOT_DECL_LIST
      - types from table.h: cmds with tok_type RING_DECL
        (require a base ring/currRing!=NULL)
      - types from table.h: cmds with tok_type RING_DECL_LIST
        (require a base ring/currRing!=NULL)
      - matrix types: INTMAT_CMD, BIGINTMAT_CMD, MATRIX_CMD
        (MATRIX_CMD requires a base ring/currRing!=NULL)
      - pseudo types for arguments:
        IDHDL: argument must be an interpreter variable
        ANY_TYPE: changes to pseudo data (for "defined", "typeof", etc.)
      - pseudo types for results:
        NONE: void
        ANY_TYPE: the jjBLA* routine decides about the return type
          (including NONE)

    Remark: the order of these lines is important:
      first the interpreter tries a perfect match of the data types,
      but, if none is found, the second pass tries automatic type conversion
      starting with the first line:
      for example: bla(<matrix>,<module>)
      ,{D(jjBLAH21),   BLA_CMD,   <return type>,  MATRIX_CMD, MATRIX_CMD, ALLOW_PLURAL |ALLOW_RING}
      ,{D(jjBLAH22),   BLA_CMD,   <return type>,  MODUL_CMD,  MODUL_CMD, ALLOW_PLURAL |ALLOW_RING}
      would call jjBLAH21, while
      ,{D(jjBLAH22),   BLA_CMD,   <return type>,  MODUL_CMD,  MODUL_CMD, ALLOW_PLURAL |ALLOW_RING}
      ,{D(jjBLAH21),   BLA_CMD,   <return type>,  MATRIX_CMD, MATRIX_CMD, ALLOW_PLURAL |ALLOW_RING}
      would call jjBLAH22.
      If certain conversions should not be allowed, add a line/several lines like:
      ,{jjWRONG,   BLA_CMD,   NONE,  MATRIX_CMD, MODUL_CMD, ALLOW_PLURAL |ALLOW_RING}
      at the end of the block with operations for "bla".

    Remark: alias: 0: normal reserved word
                   1: alias for an reserver word: allowed as input, never as output
    	       2: outdated alias: allowed as input, never as output,
    	          output a warning at first use

    			 Singular version 4.2
    		     University of Kaiserslautern
         Department of Mathematics        Centre for Computer Algebra
    	  Authors: W.Decker, G.-M. Greuel, G. Pfister, H. Schoenemann
    		  (C) 1986-2021 All Rights Reserved

    		   README FILE FOR SINGULAR INTERPRETER
    		   ====================================

    This directory contains the source files for the Singular interpreter and
    the following subdirectories:

      'LIB'   -- contains Singular libraries written in Singular's
                 programming language

    If you receive this file as part of a complete Singular distribution,
    see also the files contained in the top
    directory of the full Singular distribution.

    GOOD LUCK and ENJOY!                         Your Singular team.

TODO: The sub-package structure is not yet defined for Singular package...