source: sage/misc/functional.py @ 1:bf5417bc8931

Revision 1:bf5417bc8931, 18.5 KB checked in by tornaria@…, 7 years ago (diff)

[project @ patch to sage-0.10.13]
Line 
1"""
2Functional notation
3
4These are function so that you can write foo(x) instead of x.foo() in
5certain common cases.
6
7AUTHORS: Initial version -- William Stein
8         More Examples -- David Joyner, 2005-12-20
9"""
10
11#*****************************************************************************
12#       Copyright (C) 2004 William Stein <wstein@ucsd.edu>
13#
14#  Distributed under the terms of the GNU General Public License (GPL)
15#
16#    This code is distributed in the hope that it will be useful,
17#    but WITHOUT ANY WARRANTY; without even the implied warranty of
18#    MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
19#    General Public License for more details.
20#
21#  The full text of the GPL is available at:
22#
23#                  http://www.gnu.org/licenses/
24#*****************************************************************************
25
26from sage.rings.all import (RealField, ComplexField,
27                            PolynomialRing, RationalField, Ideal,
28                            IntegerRing)
29
30import sage.rings.integer_ring
31import sage.categories.all
32QQ = RationalField()
33R = RealField()
34C = ComplexField()
35CC = ComplexField()
36
37from sage.libs.all import pari
38
39##############################################################################
40# There are many functions on elements of a ring, which mathematicians
41# usually write f(x), e.g., it is weird to write x.log() and natural
42# to write log(x).  The functions below allow for the more familiar syntax.
43##############################################################################
44def additive_order(x):
45    """
46    Return the additive order of $x$.
47    """
48    return x.additive_order()
49
50def arg(x):
51    """
52    Return the argument of a complex number $x$.
53
54    EXAMPLES:
55        sage: z = CC(1+2*i)
56        sage: theta = arg(z)
57        sage: cos(theta)*abs(z)
58        1.0000000000000002
59        sage: sin(theta)*abs(z)
60        1.9999999999999998
61    """
62    try: return x.arg()
63    except AttributeError: return CC(x).arg()
64
65def base_ring(x):
66    """
67    Return the base ring over which x is defined.
68
69    EXAMPLES:
70        sage: R = PolynomialRing(GF(7))
71        sage: base_ring(R)
72        Finite Field of size 7
73    """
74    return x.base_ring()
75
76def base_field(x):
77    """
78    Return the base field over which x is defined.
79    """
80    return x.base_field()
81
82def basis(x):
83    """
84    Return the fixed basis of x.
85
86    EXAMPLES:
87        sage: V = VectorSpace(QQ,3)
88        sage: S = V.subspace([[1,2,0],[2,2,-1]])
89        sage: basis(S)
90        [(1, 0, -1), (0, 1, 1/2)]
91    """
92    return x.basis()
93
94def category(x):
95    """
96    Return the category of x.
97
98    EXAMPLES:
99        sage: V = VectorSpace(QQ,3)
100        sage: category(V)
101        Category of vector spaces over Rational Field
102    """
103    try:
104        return x.category()
105    except AttributeError:
106        return sage.categories.all.Objects()
107
108def charpoly(x):
109    """
110    Return the characteristic polynomial of x.
111
112    EXAMPLES:
113        sage: M = MatrixSpace(QQ,3,3)
114        sage: A = M([1,2,3,4,5,6,7,8,9])
115        sage: charpoly(A)
116        x^3 - 15*x^2 - 18*x
117    """
118    try:
119        return x.characteristic_polynomial()
120    except AttributeError:
121        return x.charpoly()
122    except AttributeError:
123        raise NotImplementedError, "computation of charpoly of x (=%s) not implemented"%x
124
125## def conductor(x):
126##     """
127##     Return the conductor of x.
128
129##     EXAMPLES:
130##         sage: E = EllipticCurve([0, -1, 1, -10, -20])
131##         sage: E
132##         Elliptic Curve defined by y^2 + y = x^3 - x^2 - 10*x - 20 over Rational Field
133##         sage: conductor(E)
134##         11
135##     """
136##     return x.conductor()
137
138def cos(x):
139    """
140    Return the cosine of x.
141
142    EXAMPLES:
143        sage: z = CC(1+2*i)
144        sage: theta = arg(z)
145        sage: cos(theta)*abs(z)
146        1.0000000000000002
147        sage: cos(3.141592)
148        -0.99999999999978639
149    """
150    try: return x.cos()
151    except AttributeError: return R(x).cos()
152
153## def cuspidal_submodule(x):
154##     return x.cuspidal_submodule()
155
156## def cuspidal_subspace(x):
157##     return x.cuspidal_subspace()
158
159def cyclotomic_polynomial(n):
160    """
161    EXAMPLES:
162        sage: cyclotomic_polynomial(3)
163        x^2 + x + 1
164        sage: cyclotomic_polynomial(4)
165        x^2 + 1
166        sage: cyclotomic_polynomial(9)
167        x^6 + x^3 + 1
168        sage: cyclotomic_polynomial(10)
169        x^4 - x^3 + x^2 - x + 1
170        sage: cyclotomic_polynomial(11)
171        x^10 + x^9 + x^8 + x^7 + x^6 + x^5 + x^4 + x^3 + x^2 + x + 1
172    """
173    return PolynomialRing(RationalField()).cyclotomic_polynomial(n)
174
175def decomposition(x):
176    """
177    Return the decomposition of x.
178    """
179    return x.decomposition()
180
181def denominator(x):
182    """
183    Return the numerator of x.
184
185    EXAMPLES:
186        sage: denominator(17/11111)
187        11111
188        sage: R = PolynomialRing(RationalField(), 'x')
189        sage: F = FractionField(R)
190        sage: r = (x+1)/(x-1)
191        sage: denominator(r)
192        x - 1
193    """
194    if isinstance(x, (int, long)):
195        return 1
196    return x.denominator()
197
198def derivative(x):
199    """
200    Return the derivative of a polynomial x.
201
202    EXAMPLES:
203        sage: f = cyclotomic_polynomial(10)
204        sage: derivative(f)
205        4*x^3 - 3*x^2 + 2*x - 1
206        sage: R = PolynomialRing(GF(7))
207        sage: gen = R.gen(); x = gen; f = x^7 + x
208        sage: derivative(f)
209        1
210    """
211    return x.derivative()
212
213def det(x):
214    """
215    Return the determinant of x.
216
217    EXAMPLES:
218        sage: M = MatrixSpace(QQ,3,3)
219        sage: A = M([1,2,3,4,5,6,7,8,9])
220        sage: det(A)
221        0
222    """
223    return x.det()
224
225def dimension(x):
226    """
227    Return the dimension of x.
228
229    EXAMPLES:
230        sage: V = VectorSpace(QQ,3)
231        sage: S = V.subspace([[1,2,0],[2,2,-1]])
232        sage: dimension(S)
233        2
234    """
235    return x.dimension()
236
237dim = dimension
238
239def discriminant(x):
240    """
241    EXAMPLES:
242        sage: R = PolynomialRing(RationalField(), 'x'); x = R.gen()
243        sage: S = R.quotient(x**29-17*x-1, 'alpha')
244        sage: K = S.number_field()
245        sage: discriminant(K)
246        -15975100446626038280218213241591829458737190477345113376757479850566957249523
247    """
248    return x.discriminant()
249
250disc = discriminant
251
252# This is dangerous since it gets the scoping all wrong ??
253#import __builtin__
254#def eval(x):
255#    try:
256#        return x._eval_()
257#    except AttributeError:
258#        return __builtin__.eval(x)
259
260def exp(x):
261    """
262    Return the value of the exponentation function at x.
263    """
264    try: return x.exp()
265    except AttributeError: return R(x).exp()
266
267def factor(x, *args, **kwds):
268    """
269    Return the prime factorization of x.
270
271    EXAMPLES:
272        sage: factor(factorial(10))
273        2^8 * 3^4 * 5^2 * 7
274        sage: n = next_prime(10^6); n
275        1000003
276        sage: factor(n)
277        1000003
278    """
279    try: return x.factor(*args, **kwds)
280    except AttributeError: return sage.rings.integer_ring.factor(x, *args, **kwds)
281
282factorization = factor
283factorisation = factor
284
285def fcp(x):
286    """
287    Return the factorization of the characteristic polynomial
288    of x.
289
290    EXAMPLES:
291        sage: M = MatrixSpace(QQ,3,3)
292        sage: A = M([1,2,3,4,5,6,7,8,9])
293        sage: fcp(A)
294        x * (x^2 - 15*x - 18)
295    """
296    try: return x.fcp()
297    except AttributeError: return factor(charpoly(x))
298
299gcd = sage.rings.arith.gcd
300
301def gen(x):
302    """
303    Return the generator of x.
304    """
305    return x.gen()
306
307def gens(x):
308    """
309    Return the generators of x.
310    """
311    return x.gens()
312
313def hecke_operator(x,n):
314    """
315    Return the n-th Hecke operator T_n acting on x.
316
317    EXAMPLES:
318        sage: M = ModularSymbols(1,12)
319        sage: hecke_operator(M,5)
320        Hecke operator T_5 on Full Modular Symbols space for Gamma_0(1) of weight 12 with sign 0 and dimension 3 over Rational Field
321    """
322    return x.hecke_operator(n)
323
324def ideal(*x):
325    """
326    Return the ideal generated by x where x is an element or list.
327
328    EXAMPLES:
329        sage: ideal(x^2-2*x+1, x^2-1)
330        Principal ideal (x - 1) of Univariate Polynomial Ring in x over Rational Field
331        sage: ideal([x^2-2*x+1, x^2-1])
332        Principal ideal (x - 1) of Univariate Polynomial Ring in x over Rational Field
333    """
334    if isinstance(x[0], (list, tuple)):
335        return Ideal(x[0])
336    return Ideal(x)
337
338def image(x):
339    """
340    Return the image of x.
341   
342    EXAMPLES:
343        sage: M = MatrixSpace(QQ,3,3)
344        sage: A = M([1,2,3,4,5,6,7,8,9])
345        sage: image(A)
346        Vector space of degree 3 and dimension 2 over Rational Field
347        Basis matrix:
348        [ 1  0 -1]
349        [ 0  1  2]
350    """
351    return x.image()
352
353def imag(x):
354    """
355    Return the imaginary part of x.
356    """
357    try: return x.imag()
358    except AttributeError: return CC(x).imag()
359
360def imaginary(x):
361    """
362    Return the imaginary part of a complex number.
363
364    EXAMPLES:
365        sage: z = CC(1+2*i)
366        sage: imaginary(z)
367        2.0000000000000000
368        sage: imag(z)
369        2.0000000000000000
370    """
371    return imag(x)
372
373def integral(x):
374    """
375    Return an indefinite integral of an object x.
376
377    EXAMPLES:
378        sage: f = cyclotomic_polynomial(10)
379        sage: integral(f)
380        1/5*x^5 - 1/4*x^4 + 1/3*x^3 - 1/2*x^2 + x
381    """
382    return x.integral()
383
384def integral_closure(x):
385    return x.integral_closure()
386
387def interval(a, b):
388    r"""
389    Integers between a and b \emph{inclusive} (a and b integers).
390
391    EXAMPLES:
392        sage: I = interval(1,3)
393        sage: 2 in I
394        True
395        sage: 1 in I
396        True
397        sage: 4 in I
398        False
399    """
400    return range(a,b+1)
401
402def xinterval(a, b):
403    r"""
404    Iterator over the integers between a and b, \emph{inclusive}.
405    """
406    return xrange(a, b+1)
407
408def is_commutative(x):
409    """
410    EXAMPLES:
411        sage: R = PolynomialRing(RationalField(), 'x')
412        sage: is_commutative(R)
413        True
414    """
415    return x.is_commutative()
416
417def is_even(x):
418    """
419    Return whether or not an integer x is even, e.g., divisible by 2.
420
421    EXAMPLES:
422        sage: is_even(-1)
423        False
424        sage: is_even(4)
425        True
426        sage: is_even(-2)
427        True
428    """
429    try: return x.is_even()
430    except AttributeError: return x%2==0
431
432def is_integrally_closed(x):
433    return x.is_integrally_closed()
434
435def is_field(x):
436    """
437    EXAMPLES:
438        sage: R = PolynomialRing(RationalField(), 'x')
439        sage: F = FractionField(R)
440        sage: is_field(F)
441        True
442    """
443    return x.is_field()
444
445def is_noetherian(x):
446    return x.is_noetherian()
447   
448def is_odd(x):
449    """
450    Return whether or not x is odd.  This is by definition the
451    complement of is_even.
452
453    EXAMPLES:
454        sage: is_odd(-2)
455        False
456        sage: is_odd(-3)
457        True
458        sage: is_odd(0)
459        False
460        sage: is_odd(1)
461        True
462    """
463    return not is_even(x)
464
465## def j_invariant(x):
466##     """
467##     Return the j_invariant of x.
468
469##     EXAMPLES:
470##         sage: E = EllipticCurve([0, -1, 1, -10, -20])
471##         sage: E
472##         Elliptic Curve defined by y^2 + y = x^3 - x^2 - 10*x - 20 over Rational Field
473##         sage: j_invariant(E)
474##         -122023936/161051
475##     """
476##     return x.j_invariant()
477
478def kernel(x):
479    """
480    Return the kernel of x.
481
482    EXAMPLES:
483        sage: M = MatrixSpace(QQ,3,3)
484        sage: A = M([1,2,3,4,5,6,7,8,9])
485        sage: kernel(A)
486        Vector space of degree 3 and dimension 1 over Rational Field
487        Basis matrix:
488        [ 1 -2  1]
489    """
490    return x.kernel()
491
492def krull_dimension(x):
493    return x.krull_dimension()
494
495lcm = sage.rings.arith.lcm
496
497def log(x,b=None):
498    r"""
499    Return the log of x to the base b.  The default base is e.
500
501    INPUT:
502        x -- number
503        b -- base (default: None, which means natural log)
504    OUTPUT:
505        number
506
507    \note{In Magma, the order of arguments is reversed from in
508    \sage, i.e., the base is given first.  We use the opposite
509    ordering, so the base can be viewed as an optional second
510    argument.}
511
512    EXAMPLES:
513        sage: log(10,2)
514        3.3219280948873626
515        sage: log(8,2)
516        3.0000000000000000
517        sage: log(10)
518        2.3025850929940459
519        sage: log(2.718)
520        0.99989631572895199
521    """
522    if b is None:
523        try: return x.log()
524        except AttributeError:
525            return R(x).log()
526    else:
527        try: return x.log(b)
528        except AttributeError:
529            return log(x) / log(b)
530
531def matrix(x, R):
532    """
533    Return the \sage matrix over $R$ obtained from x, if possible.
534    """
535    try:
536        return x._matrix_(R)
537    except AttributeError:
538        raise TypeError, "No known way to create a matrix from %s"%x
539
540def minimal_polynomial(x):
541    """
542    Return the minimal polynomial of x.
543    """
544    return x.minimal_polynomial()
545   
546
547def multiplicative_order(x):
548    r"""
549    Return the multiplicative order of self, if self is a unit, or raise
550    \code{ArithmeticError} otherwise.
551    """
552    return x.multiplicative_order()
553
554## def new_submodule(x):
555##     return x.new_submodule()
556
557## def new_subspace(x):
558##     return x.new_subspace()
559
560def ngens(x):
561    """
562    Return the number of generators of x.
563    """
564    return x.ngens()
565
566def norm(x):
567    """
568    Return the norm of x.
569
570    EXAMPLES:
571        sage: z = CC(1+2*i)
572        sage: norm(z)
573        5.0000000000000000
574    """
575    return x.norm()
576
577def numerator(x):
578    """
579    Return the numerator of x.
580
581    EXAMPLES:
582        sage: R = PolynomialRing(RationalField(), 'x')
583        sage: F = FractionField(R)
584        sage: r = (x+1)/(x-1)
585        sage: numerator(r)
586        x + 1
587        sage: numerator(17/11111)
588        17
589    """
590    if isinstance(x, (int, long)):
591        return x
592    return x.numerator()
593
594def objgens(x, names=None):
595    """
596    EXAMPLES:
597        sage: R, x = objgens(MPolynomialRing(Q,3))
598        sage: R
599        Polynomial Ring in x_0, x_1, x_2 over Rational Field
600        sage: x
601        (x_0, x_1, x_2)
602    """
603    return x.objgens(names)
604
605def objgen(x, names=None):
606    """
607    EXAMPLES:
608        sage: R, x = objgen(FractionField(Q['x']))
609        sage: R
610        Fraction Field of Univariate Polynomial Ring in x over Rational Field
611        sage: x
612        x
613    """
614    return x.objgen(names)
615
616def one(R):
617    """
618    Return the one element of the ring R.
619
620    EXAMPLES:
621    sage: R = PolynomialRing(RationalField(), 'x')
622    sage: one(R)*x == x
623    True
624    sage: one(R) in R
625    True
626
627    """
628    return R(1)
629
630def order(x):
631    """
632    Return the order of x.  If x is a ring or module element, this is
633    the additive order of x.
634
635    EXAMPLES:
636        sage: C = CyclicPermutationGroup(10)
637        sage: order(C)
638        10
639        sage: F = GF(7)
640        sage: order(F)
641        7
642    """
643    return x.order()
644
645def rank(x):
646    """
647    Return the rank of x.
648   
649    EXAMPLES:
650        sage: M = MatrixSpace(QQ,3,3)
651        sage: A = M([1,2,3,4,5,6,7,8,9])
652        sage: rank(A)
653        2
654    """
655    return x.rank()
656
657def real(x):
658    """
659    Return the real part of x.
660
661    EXAMPLES:
662        sage: z = CC(1+2*i)
663        sage: real(z)
664        1.0000000000000000
665    """
666    try: return x.real()
667    except AttributeError: return C(x).real()
668
669def regulator(x):
670    """
671    Return the regulator of x.
672    """
673    return x.regulator()
674
675def quo(x, y, var=None):
676    """
677    Return the quotient object x/y, e.g., a quotient of numbers or of
678    a polynomial ring x by the ideal generated by y, etc.
679    """
680    try:
681        return x.quotient(y, var)
682    except AttributeError:
683        return x/y
684
685quotient = quo
686
687def sqrt(x):
688    """
689    Return a square root of x.
690
691    EXAMPLES:
692        sage: sqrt(10.1)
693        3.1780497164141406
694        sage: sqrt(9)
695        3
696    """
697    try: return x.sqrt()
698    except (AttributeError, ValueError): return ComplexField()(x).sqrt()
699
700def isqrt(x):
701    """
702    Return an integer square root, i.e., the floor of a
703    square root.
704
705    EXAMPLES:
706        sage: isqrt(10)
707        3
708    """
709    try: return x.isqrt()
710    except AttributeError:
711        raise NotImplementedError
712
713def sin(x):
714    """
715    Return the sin of x.
716    """
717    try: return x.sin()
718    except AttributeError: return R(x).sin()
719
720def square_free_part(x):
721    """
722    Return the square free part of $x$, i.e., a divisor $z$ such that $x = z y^2$,
723    for a perfect square $y^2$.
724
725    EXAMPLES:
726        sage: square_free_part(100)
727        1
728        sage: square_free_part(12)
729        3
730        sage: square_free_part(10)
731        10
732       
733        sage: x = Q['x'].0
734        sage: S = square_free_part(-9*x*(x-6)^7*(x-3)^2); S
735        -9*x^2 + 54*x
736        sage: S.factor()
737        (-9) * (x - 6) * x
738
739        sage: f = (x^3 + x + 1)^3*(x-1); f
740        x^10 - x^9 + 3*x^8 + 3*x^5 - 2*x^4 - x^3 - 2*x - 1
741        sage: g = square_free_part(f); g
742        x^4 - x^3 + x^2 - 1
743        sage: g.factor()
744        (x - 1) * (x^3 + x + 1)
745    """
746    try:
747        return x.square_free_part()
748    except AttributeError:
749        pass
750    F = factor(x)
751    n = x.parent()(1)
752    for p, e in F:
753        if e%2 != 0:
754            n *= p
755    return n * F.unit()
756   
757def square_root(x):
758    """
759    Return a square root of x with the same parent as x, if possible,
760    otherwise raise a ValueError.
761
762    EXAMPLES:
763        sage: square_root(9)
764        3
765        sage: square_root(100)
766        10
767    """
768    try:
769        return x.square_root()
770    except AttributeError:
771        raise NotImplementedError
772   
773def tan(x):
774    """
775    Return the tangent of x.
776
777    EXAMPLES:
778        sage: tan(3.1415)
779        -0.000092653590058635411
780        sage: tan(3.1415/4)
781        0.99995367427815607
782    """
783    try: return x.tan()
784    except AttributeError: return R(x).tan()
785
786def transpose(x):
787    """
788    EXAMPLES:
789        sage: M = MatrixSpace(QQ,3,3)
790        sage: A = M([1,2,3,4,5,6,7,8,9])
791        sage: transpose(A)
792        [1 4 7]
793        [2 5 8]
794        [3 6 9]
795    """
796    return x.transpose()
797
798xgcd = sage.rings.arith.xgcd
799
800def vector(x, R):
801    """
802    Return the \sage vector over $R$ obtained from x, if possible.
803    """
804    try:
805        return x._vector_(R)
806    except AttributeError:
807        raise TypeError, "No known way to create a vector from %s"%x
808
809def zero(R):
810    """
811    Return the zero element of the ring R.
812
813    EXAMPLES:
814        sage: R = PolynomialRing(RationalField(), 'x')
815        sage: zero(R) in R
816        True
817        sage: zero(R)*x == zero(R)
818        True
819    """
820    return R(0)
821
822
823
824#################################################################
825# Generic parent
826#################################################################
827def parent(x):
828    """
829    Return x.parent() if defined, or type(x) if not.
830
831    EXAMPLE:
832        sage: Z = parent(int(5))
833        sage: Z(17)
834        17
835        sage: Z
836        <type 'int'>
837    """
838    try:
839        return x.parent()
840    except AttributeError:
841        return type(x)
Note: See TracBrowser for help on using the repository browser.