libSingular: Functions¶
Sage implements a C wrapper around the Singular interpreter which allows to call any function directly from Sage without string parsing or interprocess communication overhead. Users who do not want to call Singular functions directly, usually do not have to worry about this interface, since it is handled by higher level functions in Sage.
AUTHORS:
Michael Brickenstein (2009-07): initial implementation, overall design
Martin Albrecht (2009-07): clean up, enhancements, etc.
Michael Brickenstein (2009-10): extension to more Singular types
Martin Albrecht (2010-01): clean up, support for attributes
Simon King (2011-04): include the documentation provided by Singular as a code block.
Burcin Erocal, Michael Brickenstein, Oleksandr Motsak, Alexander Dreyer, Simon King (2011-09) plural support
EXAMPLES:
The direct approach for loading a Singular function is to call the
function singular_function()
with the function name as
parameter:
sage: from sage.libs.singular.function import singular_function
sage: P.<a,b,c,d> = PolynomialRing(GF(7))
sage: std = singular_function('std')
sage: I = sage.rings.ideal.Cyclic(P)
sage: std(I)
[a + b + c + d,
b^2 + 2*b*d + d^2,
b*c^2 + c^2*d - b*d^2 - d^3,
b*c*d^2 + c^2*d^2 - b*d^3 + c*d^3 - d^4 - 1,
b*d^4 + d^5 - b - d,
c^3*d^2 + c^2*d^3 - c - d,
c^2*d^4 + b*c - b*d + c*d - 2*d^2]
If a Singular library needs to be loaded before a certain function is
available, use the lib()
function as shown below:
sage: from sage.libs.singular.function import singular_function, lib as singular_lib
sage: primdecSY = singular_function('primdecSY')
Traceback (most recent call last):
...
NameError: Singular library function 'primdecSY' is not defined
sage: singular_lib('primdec.lib')
sage: primdecSY = singular_function('primdecSY')
There is also a short-hand notation for the above:
sage: import sage.libs.singular.function_factory
sage: primdecSY = sage.libs.singular.function_factory.ff.primdec__lib.primdecSY
The above line will load “primdec.lib” first and then load the
function primdecSY
.
-
class
sage.libs.singular.function.
BaseCallHandler
¶ Bases:
object
A call handler is an abstraction which hides the details of the implementation differences between kernel and library functions.
-
class
sage.libs.singular.function.
Converter
¶ Bases:
sage.structure.sage_object.SageObject
A
Converter
interfaces between Sage objects and Singular interpreter objects.-
ring
()¶ Return the ring in which the arguments of this list live.
EXAMPLES:
sage: from sage.libs.singular.function import Converter sage: P.<a,b,c> = PolynomialRing(GF(127)) sage: Converter([a,b,c],ring=P).ring() Multivariate Polynomial Ring in a, b, c over Finite Field of size 127
-
-
class
sage.libs.singular.function.
KernelCallHandler
¶ Bases:
sage.libs.singular.function.BaseCallHandler
A call handler is an abstraction which hides the details of the implementation differences between kernel and library functions.
This class implements calling a kernel function.
Note
Do not construct this class directly, use
singular_function()
instead.
-
class
sage.libs.singular.function.
LibraryCallHandler
¶ Bases:
sage.libs.singular.function.BaseCallHandler
A call handler is an abstraction which hides the details of the implementation differences between kernel and library functions.
This class implements calling a library function.
Note
Do not construct this class directly, use
singular_function()
instead.
-
class
sage.libs.singular.function.
Resolution
¶ Bases:
object
A simple wrapper around Singular’s resolutions.
-
class
sage.libs.singular.function.
RingWrap
¶ Bases:
object
A simple wrapper around Singular’s rings.
-
characteristic
()¶ Get characteristic.
EXAMPLES:
sage: from sage.libs.singular.function import singular_function sage: P.<x,y,z> = PolynomialRing(QQ) sage: ringlist = singular_function("ringlist") sage: l = ringlist(P) sage: ring = singular_function("ring") sage: ring(l, ring=P).characteristic() 0
-
is_commutative
()¶ Determine whether a given ring is commutative.
EXAMPLES:
sage: from sage.libs.singular.function import singular_function sage: P.<x,y,z> = PolynomialRing(QQ) sage: ringlist = singular_function("ringlist") sage: l = ringlist(P) sage: ring = singular_function("ring") sage: ring(l, ring=P).is_commutative() True
-
ngens
()¶ Get number of generators.
EXAMPLES:
sage: from sage.libs.singular.function import singular_function sage: P.<x,y,z> = PolynomialRing(QQ) sage: ringlist = singular_function("ringlist") sage: l = ringlist(P) sage: ring = singular_function("ring") sage: ring(l, ring=P).ngens() 3
-
npars
()¶ Get number of parameters.
EXAMPLES:
sage: from sage.libs.singular.function import singular_function sage: P.<x,y,z> = PolynomialRing(QQ) sage: ringlist = singular_function("ringlist") sage: l = ringlist(P) sage: ring = singular_function("ring") sage: ring(l, ring=P).npars() 0
-
ordering_string
()¶ Get Singular string defining monomial ordering.
EXAMPLES:
sage: from sage.libs.singular.function import singular_function sage: P.<x,y,z> = PolynomialRing(QQ) sage: ringlist = singular_function("ringlist") sage: l = ringlist(P) sage: ring = singular_function("ring") sage: ring(l, ring=P).ordering_string() 'dp(3),C'
-
par_names
()¶ Get parameter names.
EXAMPLES:
sage: from sage.libs.singular.function import singular_function sage: P.<x,y,z> = PolynomialRing(QQ) sage: ringlist = singular_function("ringlist") sage: l = ringlist(P) sage: ring = singular_function("ring") sage: ring(l, ring=P).par_names() []
-
var_names
()¶ Get names of variables.
EXAMPLES:
sage: from sage.libs.singular.function import singular_function sage: P.<x,y,z> = PolynomialRing(QQ) sage: ringlist = singular_function("ringlist") sage: l = ringlist(P) sage: ring = singular_function("ring") sage: ring(l, ring=P).var_names() ['x', 'y', 'z']
-
-
class
sage.libs.singular.function.
SingularFunction
¶ Bases:
sage.structure.sage_object.SageObject
The base class for Singular functions either from the kernel or from the library.
-
class
sage.libs.singular.function.
SingularKernelFunction
¶ Bases:
sage.libs.singular.function.SingularFunction
EXAMPLES:
sage: from sage.libs.singular.function import SingularKernelFunction sage: R.<x,y> = PolynomialRing(QQ, order='lex') sage: I = R.ideal(x, x+1) sage: f = SingularKernelFunction("std") sage: f(I) [1]
-
class
sage.libs.singular.function.
SingularLibraryFunction
¶ Bases:
sage.libs.singular.function.SingularFunction
EXAMPLES:
sage: from sage.libs.singular.function import SingularLibraryFunction sage: R.<x,y> = PolynomialRing(QQ, order='lex') sage: I = R.ideal(x, x+1) sage: f = SingularLibraryFunction("groebner") sage: f(I) [1]
-
sage.libs.singular.function.
all_singular_poly_wrapper
(s)¶ Tests for a sequence
s
, whether it consists of singular polynomials.EXAMPLES:
sage: from sage.libs.singular.function import all_singular_poly_wrapper sage: P.<x,y,z> = QQ[] sage: all_singular_poly_wrapper([x+1, y]) True sage: all_singular_poly_wrapper([x+1, y, 1]) False
-
sage.libs.singular.function.
all_vectors
(s)¶ Checks if a sequence
s
consists of free module elements over a singular ring.EXAMPLES:
sage: from sage.libs.singular.function import all_vectors sage: P.<x,y,z> = QQ[] sage: M = P**2 sage: all_vectors([x]) False sage: all_vectors([(x,y)]) False sage: all_vectors([M(0), M((x,y))]) True sage: all_vectors([M(0), M((x,y)),(0,0)]) False
-
sage.libs.singular.function.
is_sage_wrapper_for_singular_ring
(ring)¶ Check whether wrapped ring arises from Singular or Singular/Plural.
EXAMPLES:
sage: from sage.libs.singular.function import is_sage_wrapper_for_singular_ring sage: P.<x,y,z> = QQ[] sage: is_sage_wrapper_for_singular_ring(P) True
sage: A.<x,y,z> = FreeAlgebra(QQ, 3) sage: P = A.g_algebra(relations={y*x:-x*y}, order = 'lex') sage: is_sage_wrapper_for_singular_ring(P) True
-
sage.libs.singular.function.
is_singular_poly_wrapper
(p)¶ Checks if p is some data type corresponding to some singular
poly
.EXAMPLES:
sage: from sage.libs.singular.function import is_singular_poly_wrapper sage: A.<x,y,z> = FreeAlgebra(QQ, 3) sage: H.<x,y,z> = A.g_algebra({z*x:x*z+2*x, z*y:y*z-2*y}) sage: is_singular_poly_wrapper(x+y) True
-
sage.libs.singular.function.
lib
(name)¶ Load the Singular library
name
.INPUT:
name
– a Singular library name
EXAMPLES:
sage: from sage.libs.singular.function import singular_function sage: from sage.libs.singular.function import lib as singular_lib sage: singular_lib('general.lib') sage: primes = singular_function('primes') sage: primes(2,10, ring=GF(127)['x,y,z']) (2, 3, 5, 7)
-
sage.libs.singular.function.
list_of_functions
(packages=False)¶ Return a list of all function names currently available.
INPUT:
packages
– include local functions in packages.
EXAMPLES:
sage: from sage.libs.singular.function import list_of_functions sage: 'groebner' in list_of_functions() True
-
sage.libs.singular.function.
singular_function
(name)¶ Construct a new libSingular function object for the given
name
.This function works both for interpreter and built-in functions.
INPUT:
name
– the name of the function
EXAMPLES:
sage: P.<x,y,z> = PolynomialRing(QQ) sage: f = 3*x*y + 2*z + 1 sage: g = 2*x + 1/2 sage: I = Ideal([f,g])
sage: from sage.libs.singular.function import singular_function sage: std = singular_function("std") sage: std(I) [3*y - 8*z - 4, 4*x + 1] sage: size = singular_function("size") sage: size([2, 3, 3]) 3 sage: size("sage") 4 sage: size(["hello", "sage"]) 2 sage: factorize = singular_function("factorize") sage: factorize(f) [[1, 3*x*y + 2*z + 1], (1, 1)] sage: factorize(f, 1) [3*x*y + 2*z + 1]
We give a wrong number of arguments:
sage: factorize() Traceback (most recent call last): ... RuntimeError: error in Singular function call 'factorize': Wrong number of arguments (got 0 arguments, arity code is 303) sage: factorize(f, 1, 2) Traceback (most recent call last): ... RuntimeError: error in Singular function call 'factorize': Wrong number of arguments (got 3 arguments, arity code is 303) sage: factorize(f, 1, 2, 3) Traceback (most recent call last): ... RuntimeError: error in Singular function call 'factorize': Wrong number of arguments (got 4 arguments, arity code is 303)
The Singular function
list
can be called with any number of arguments:sage: singular_list = singular_function("list") sage: singular_list(2, 3, 6) [2, 3, 6] sage: singular_list() [] sage: singular_list(1) [1] sage: singular_list(1, 2, 3, 4, 5, 6, 7, 8, 9, 10) [1, 2, 3, 4, 5, 6, 7, 8, 9, 10]
We try to define a non-existing function:
sage: number_foobar = singular_function('number_foobar') Traceback (most recent call last): ... NameError: Singular library function 'number_foobar' is not defined
sage: from sage.libs.singular.function import lib as singular_lib sage: singular_lib('general.lib') sage: number_e = singular_function('number_e') sage: number_e(10r) 67957045707/25000000000 sage: RR(number_e(10r)) 2.71828182828000
sage: singular_lib('primdec.lib') sage: primdecGTZ = singular_function("primdecGTZ") sage: primdecGTZ(I) [[[y - 8/3*z - 4/3, x + 1/4], [y - 8/3*z - 4/3, x + 1/4]]] sage: singular_list((1,2,3),3,[1,2,3], ring=P) [(1, 2, 3), 3, [1, 2, 3]] sage: ringlist=singular_function("ringlist") sage: l = ringlist(P) sage: l[3].__class__ <class 'sage.rings.polynomial.multi_polynomial_sequence.PolynomialSequence_generic'> sage: l [0, ['x', 'y', 'z'], [['dp', (1, 1, 1)], ['C', (0,)]], [0]] sage: ring=singular_function("ring") sage: ring(l) <RingWrap> sage: matrix = Matrix(P,2,2) sage: matrix.randomize(terms=1) sage: det = singular_function("det") sage: det(matrix) == matrix[0, 0] * matrix[1, 1] - matrix[0, 1] * matrix[1, 0] True sage: coeffs = singular_function("coeffs") sage: coeffs(x*y+y+1,y) [ 1] [x + 1] sage: intmat = Matrix(ZZ, 2,2, [100,2,3,4]) sage: det(intmat) 394 sage: random = singular_function("random") sage: A = random(10,2,3); A.nrows(), max(A.list()) <= 10 (2, True) sage: P.<x,y,z> = PolynomialRing(QQ) sage: M=P**3 sage: leadcoef = singular_function("leadcoef") sage: v=M((100*x,5*y,10*z*x*y)) sage: leadcoef(v) 10 sage: v = M([x+y,x*y+y**3,z]) sage: lead = singular_function("lead") sage: lead(v) (0, y^3) sage: jet = singular_function("jet") sage: jet(v, 2) (x + y, x*y, z) sage: syz = singular_function("syz") sage: I = P.ideal([x+y,x*y-y, y*2,x**2+1]) sage: M = syz(I) sage: M [(-2*y, 2, y + 1, 0), (0, -2, x - 1, 0), (x*y - y, -y + 1, 1, -y), (x^2 + 1, -x - 1, -1, -x)] sage: singular_lib("mprimdec.lib") sage: syz(M) [(-x - 1, y - 1, 2*x, -2*y)] sage: GTZmod = singular_function("GTZmod") sage: GTZmod(M) [[[(-2*y, 2, y + 1, 0), (0, x + 1, 1, -y), (0, -2, x - 1, 0), (x*y - y, -y + 1, 1, -y), (x^2 + 1, 0, 0, -x - y)], [0]]] sage: mres = singular_function("mres") sage: resolution = mres(M, 0) sage: resolution <Resolution> sage: singular_list(resolution) [[(-2*y, 2, y + 1, 0), (0, -2, x - 1, 0), (x*y - y, -y + 1, 1, -y), (x^2 + 1, -x - 1, -1, -x)], [(-x - 1, y - 1, 2*x, -2*y)], [(0)]] sage: A.<x,y> = FreeAlgebra(QQ, 2) sage: P.<x,y> = A.g_algebra({y*x:-x*y}) sage: I= Sequence([x*y,x+y], check=False, immutable=True) sage: twostd = singular_function("twostd") sage: twostd(I) [x + y, y^2] sage: M=syz(I) doctest... sage: M [(x + y, x*y)] sage: syz(M) [(0)] sage: mres(I, 0) <Resolution> sage: M=P**3 sage: v=M((100*x,5*y,10*y*x*y)) sage: leadcoef(v) -10 sage: v = M([x+y,x*y+y**3,x]) sage: lead(v) (0, y^3) sage: jet(v, 2) (x + y, x*y, x) sage: l = ringlist(P) sage: len(l) 6 sage: ring(l) <noncommutative RingWrap> sage: I=twostd(I) sage: l[3]=I sage: ring(l) <noncommutative RingWrap>