Functional notation - Utilities

Skip to content
Back to top
View this page
Edit this page

# Functional notation

These are functions so that you can write `foo(x)` instead of `x.foo()` in certain common cases.

AUTHORS:

- William Stein: Initial version

- David Joyner (2005-12-20): More Examples

sage.misc.functional.N(x, prec=None, digits=None, algorithm=None)

  alias of `numerical_approx()`.

sage.misc.functional.additive_order(x)

  Return the additive order of `x`.

  EXAMPLES:

  Sage

      sage: additive_order(5)
      +Infinity
      sage: additive_order(Mod(5,11))
      11
      sage: additive_order(Mod(4,12))
      3

  Python

      >>> from sage.all import *
      >>> additive_order(Integer(5))
      +Infinity
      >>> additive_order(Mod(Integer(5),Integer(11)))
      11
      >>> additive_order(Mod(Integer(4),Integer(12)))
      3

sage.misc.functional.base_field(x)

  Return the base field over which `x` is defined.

  EXAMPLES:

  Sage

      sage: R = PolynomialRing(GF(7), 'x')
      sage: base_ring(R)
      Finite Field of size 7
      sage: base_field(R)
      Finite Field of size 7

  Python

      >>> from sage.all import *
      >>> R = PolynomialRing(GF(Integer(7)), 'x')
      >>> base_ring(R)
      Finite Field of size 7
      >>> base_field(R)
      Finite Field of size 7

  This catches base rings which are fields as well, but does not implement a `base_field` method for objects which do not have one:

  Sage

      sage: R.base_field()
      Traceback (most recent call last):
      ...
      AttributeError: 'PolynomialRing_dense_mod_p_with_category' object has no attribute 'base_field'...

  [Python]

      >>> from sage.all import *
      >>> R.base_field()
      Traceback (most recent call last):
      ...
      AttributeError: 'PolynomialRing_dense_mod_p_with_category' object has no attribute 'base_field'...

sage.misc.functional.base_ring(x)

  Return the base ring over which `x` is defined.

  EXAMPLES:

  Sage

      sage: R = PolynomialRing(GF(7), 'x')
      sage: base_ring(R)
      Finite Field of size 7

  Python

      >>> from sage.all import *
      >>> R = PolynomialRing(GF(Integer(7)), 'x')
      >>> base_ring(R)
      Finite Field of size 7

sage.misc.functional.basis(x)

  Return the fixed basis of `x`.

  EXAMPLES:

  Sage

      sage: V = VectorSpace(QQ, 3)                                                    # needs sage.modules
      sage: S = V.subspace([[1,2,0], [2,2,-1]])                                       # needs sage.modules
      sage: basis(S)                                                                  # needs sage.modules
      [(1, 0, -1), (0, 1, 1/2)]

  Python

      >>> from sage.all import *
      >>> V = VectorSpace(QQ, Integer(3))                                                    # needs sage.modules
      >>> S = V.subspace([[Integer(1),Integer(2),Integer(0)], [Integer(2),Integer(2),-Integer(1)]])                                       # needs sage.modules
      >>> basis(S)                                                                  # needs sage.modules
      [(1, 0, -1), (0, 1, 1/2)]

sage.misc.functional.category(x)

  Return the category of `x`.

  EXAMPLES:

  Sage

      sage: V = VectorSpace(QQ, 3)                                                    # needs sage.modules
      sage: category(V)                                                               # needs sage.modules
      Category of finite dimensional vector spaces with basis over
       (number fields and quotient fields and metric spaces)

  Python

      >>> from sage.all import *
      >>> V = VectorSpace(QQ, Integer(3))                                                    # needs sage.modules
      >>> category(V)                                                               # needs sage.modules
      Category of finite dimensional vector spaces with basis over
       (number fields and quotient fields and metric spaces)

sage.misc.functional.characteristic_polynomial(x, var='x')

  Return the characteristic polynomial of `x` in the given variable.

  EXAMPLES:

  Sage

      sage: # needs sage.libs.pari sage.modules
      sage: M = MatrixSpace(QQ, 3, 3)
      sage: A = M([1,2,3,4,5,6,7,8,9])
      sage: charpoly(A)
      x^3 - 15*x^2 - 18*x
      sage: charpoly(A, 't')
      t^3 - 15*t^2 - 18*t

      sage: k.<alpha> = GF(7^10); k                                                   # needs sage.rings.finite_rings
      Finite Field in alpha of size 7^10
      sage: alpha.charpoly('T')                                                       # needs sage.rings.finite_rings
      T^10 + T^6 + T^5 + 4*T^4 + T^3 + 2*T^2 + 3*T + 3
      sage: characteristic_polynomial(alpha, 'T')                                     # needs sage.rings.finite_rings
      T^10 + T^6 + T^5 + 4*T^4 + T^3 + 2*T^2 + 3*T + 3

  Python

      >>> from sage.all import *
      >>> # needs sage.libs.pari sage.modules
      >>> M = MatrixSpace(QQ, Integer(3), Integer(3))
      >>> A = M([Integer(1),Integer(2),Integer(3),Integer(4),Integer(5),Integer(6),Integer(7),Integer(8),Integer(9)])
      >>> charpoly(A)
      x^3 - 15*x^2 - 18*x
      >>> charpoly(A, 't')
      t^3 - 15*t^2 - 18*t

      >>> k = GF(Integer(7)**Integer(10), names=('alpha',)); (alpha,) = k._first_ngens(1); k                                                   # needs sage.rings.finite_rings
      Finite Field in alpha of size 7^10
      >>> alpha.charpoly('T')                                                       # needs sage.rings.finite_rings
      T^10 + T^6 + T^5 + 4*T^4 + T^3 + 2*T^2 + 3*T + 3
      >>> characteristic_polynomial(alpha, 'T')                                     # needs sage.rings.finite_rings
      T^10 + T^6 + T^5 + 4*T^4 + T^3 + 2*T^2 + 3*T + 3

  Ensure the variable name of the polynomial does not conflict with variables used within the matrix, and that non-integral powers of variables do not confuse the computation (Issue #14403):

  Sage

      sage: # needs sage.libs.pari sage.symbolic
      sage: y = var('y')
      sage: a = matrix([[x,0,0,0], [0,1,0,0], [0,0,1,0], [0,0,0,1]])
      sage: characteristic_polynomial(a).list()
      [x, -3*x - 1, 3*x + 3, -x - 3, 1]
      sage: b = matrix([[y^(1/2),0,0,0], [0,1,0,0], [0,0,1,0], [0,0,0,1]])
      sage: charpoly(b).list()
      [sqrt(y), -3*sqrt(y) - 1, 3*sqrt(y) + 3, -sqrt(y) - 3, 1]

  [Python]

      >>> from sage.all import *
      >>> # needs sage.libs.pari sage.symbolic
      >>> y = var('y')
      >>> a = matrix([[x,Integer(0),Integer(0),Integer(0)], [Integer(0),Integer(1),Integer(0),Integer(0)], [Integer(0),Integer(0),Integer(1),Integer(0)], [Integer(0),Integer(0),Integer(0),Integer(1)]])
      >>> characteristic_polynomial(a).list()
      [x, -3*x - 1, 3*x + 3, -x - 3, 1]
      >>> b = matrix([[y**(Integer(1)/Integer(2)),Integer(0),Integer(0),Integer(0)], [Integer(0),Integer(1),Integer(0),Integer(0)], [Integer(0),Integer(0),Integer(1),Integer(0)], [Integer(0),Integer(0),Integer(0),Integer(1)]])
      >>> charpoly(b).list()
      [sqrt(y), -3*sqrt(y) - 1, 3*sqrt(y) + 3, -sqrt(y) - 3, 1]

sage.misc.functional.charpoly(x, var='x')

  alias of `characteristic_polynomial()`.

sage.misc.functional.coerce(P, x)

  Coerce `x` to type `P` if possible.

  EXAMPLES:

  Sage

      sage: type(5)
      <class 'sage.rings.integer.Integer'>
      sage: type(coerce(QQ,5))
      <class 'sage.rings.rational.Rational'>

  Python

      >>> from sage.all import *
      >>> type(Integer(5))
      <class 'sage.rings.integer.Integer'>
      >>> type(coerce(QQ,Integer(5)))
      <class 'sage.rings.rational.Rational'>

sage.misc.functional.cyclotomic_polynomial(n, var='x')

  Return the \(n\)-th cyclotomic polynomial.

  EXAMPLES:

  Sage

      sage: # needs sage.libs.pari
      sage: cyclotomic_polynomial(3)
      x^2 + x + 1
      sage: cyclotomic_polynomial(4)
      x^2 + 1
      sage: cyclotomic_polynomial(9)
      x^6 + x^3 + 1
      sage: cyclotomic_polynomial(10)
      x^4 - x^3 + x^2 - x + 1
      sage: cyclotomic_polynomial(11)
      x^10 + x^9 + x^8 + x^7 + x^6 + x^5 + x^4 + x^3 + x^2 + x + 1

  Python

      >>> from sage.all import *
      >>> # needs sage.libs.pari
      >>> cyclotomic_polynomial(Integer(3))
      x^2 + x + 1
      >>> cyclotomic_polynomial(Integer(4))
      x^2 + 1
      >>> cyclotomic_polynomial(Integer(9))
      x^6 + x^3 + 1
      >>> cyclotomic_polynomial(Integer(10))
      x^4 - x^3 + x^2 - x + 1
      >>> cyclotomic_polynomial(Integer(11))
      x^10 + x^9 + x^8 + x^7 + x^6 + x^5 + x^4 + x^3 + x^2 + x + 1

sage.misc.functional.decomposition(x)

  Return the decomposition of `x`.

  EXAMPLES:

  Sage

      sage: M = matrix([[2, 3], [3, 4]])                                              # needs sage.libs.pari sage.modules
      sage: M.decomposition()                                                         # needs sage.libs.pari sage.modules
      [(Ambient free module of rank 2 over the principal ideal domain Integer Ring,
        True)]

      sage: # needs sage.groups
      sage: G.<a,b> = DirichletGroup(20)
      sage: c = a * b
      sage: d = c.decomposition(); d
      [Dirichlet character modulo 4 of conductor 4 mapping 3 |--> -1,
       Dirichlet character modulo 5 of conductor 5 mapping 2 |--> zeta4]
      sage: d[0].parent()
      Group of Dirichlet characters modulo 4
       with values in Cyclotomic Field of order 4 and degree 2

  Python

      >>> from sage.all import *
      >>> M = matrix([[Integer(2), Integer(3)], [Integer(3), Integer(4)]])                                              # needs sage.libs.pari sage.modules
      >>> M.decomposition()                                                         # needs sage.libs.pari sage.modules
      [(Ambient free module of rank 2 over the principal ideal domain Integer Ring,
        True)]

      >>> # needs sage.groups
      >>> G = DirichletGroup(Integer(20), names=('a', 'b',)); (a, b,) = G._first_ngens(2)
      >>> c = a * b
      >>> d = c.decomposition(); d
      [Dirichlet character modulo 4 of conductor 4 mapping 3 |--> -1,
       Dirichlet character modulo 5 of conductor 5 mapping 2 |--> zeta4]
      >>> d[Integer(0)].parent()
      Group of Dirichlet characters modulo 4
       with values in Cyclotomic Field of order 4 and degree 2

sage.misc.functional.denominator(x)

  Return the denominator of `x`.

  EXAMPLES:

  Sage

      sage: denominator(17/11111)
      11111
      sage: R.<x> = PolynomialRing(QQ)
      sage: F = FractionField(R)
      sage: r = (x+1)/(x-1)
      sage: denominator(r)
      x - 1

  Python

      >>> from sage.all import *
      >>> denominator(Integer(17)/Integer(11111))
      11111
      >>> R = PolynomialRing(QQ, names=('x',)); (x,) = R._first_ngens(1)
      >>> F = FractionField(R)
      >>> r = (x+Integer(1))/(x-Integer(1))
      >>> denominator(r)
      x - 1

sage.misc.functional.det(x)

  Return the determinant of `x`.

  EXAMPLES:

  Sage

      sage: M = MatrixSpace(QQ, 3, 3)                                                 # needs sage.modules
      sage: A = M([1,2,3, 4,5,6, 7,8,9])                                              # needs sage.modules
      sage: det(A)                                                                    # needs sage.modules
      0

  Python

      >>> from sage.all import *
      >>> M = MatrixSpace(QQ, Integer(3), Integer(3))                                                 # needs sage.modules
      >>> A = M([Integer(1),Integer(2),Integer(3), Integer(4),Integer(5),Integer(6), Integer(7),Integer(8),Integer(9)])                                              # needs sage.modules
      >>> det(A)                                                                    # needs sage.modules
      0

sage.misc.functional.dim(x)

  alias of `dimension()`.

sage.misc.functional.dimension(x)

  Return the dimension of `x`.

  EXAMPLES:

  Sage

      sage: V = VectorSpace(QQ, 3)                                                    # needs sage.modules
      sage: S = V.subspace([[1,2,0], [2,2,-1]])                                       # needs sage.modules
      sage: dimension(S)                                                              # needs sage.modules
      2

  Python

      >>> from sage.all import *
      >>> V = VectorSpace(QQ, Integer(3))                                                    # needs sage.modules
      >>> S = V.subspace([[Integer(1),Integer(2),Integer(0)], [Integer(2),Integer(2),-Integer(1)]])                                       # needs sage.modules
      >>> dimension(S)                                                              # needs sage.modules
      2

sage.misc.functional.disc(x)

  alias of `discriminant()`.

sage.misc.functional.discriminant(x)

  Return the discriminant of `x`.

  EXAMPLES:

  Sage

      sage: R.<x> = PolynomialRing(QQ)
      sage: S = R.quotient(x^29 - 17*x - 1, 'alpha')                                  # needs sage.libs.pari
      sage: K = S.number_field()                                                      # needs sage.libs.pari sage.rings.number_field
      sage: discriminant(K)                                                           # needs sage.libs.pari sage.rings.number_field
      -15975100446626038280218213241591829458737190477345113376757479850566957249523

  Python

      >>> from sage.all import *
      >>> R = PolynomialRing(QQ, names=('x',)); (x,) = R._first_ngens(1)
      >>> S = R.quotient(x**Integer(29) - Integer(17)*x - Integer(1), 'alpha')                                  # needs sage.libs.pari
      >>> K = S.number_field()                                                      # needs sage.libs.pari sage.rings.number_field
      >>> discriminant(K)                                                           # needs sage.libs.pari sage.rings.number_field
      -15975100446626038280218213241591829458737190477345113376757479850566957249523

sage.misc.functional.eta(x)

  Return the value of the \(\eta\) function at `x`, which must be in the upper half plane.

  The \(\eta\) function is

  \[\eta(z) = e^{\pi i z / 12} \prod_{n=1}^{\infty}(1-e^{2\pi inz})\]

  EXAMPLES:

  Sage

      sage: eta(1 + I)                                                                # needs sage.symbolic
      0.7420487758365647 + 0.1988313702299107*I

  Python

      >>> from sage.all import *
      >>> eta(Integer(1) + I)                                                                # needs sage.symbolic
      0.7420487758365647 + 0.1988313702299107*I

sage.misc.functional.fcp(x, var='x')

  Return the factorization of the characteristic polynomial of `x`.

  EXAMPLES:

  Sage

      sage: M = MatrixSpace(QQ, 3, 3)                                                 # needs sage.modules
      sage: A = M([1,2,3, 4,5,6, 7,8,9])                                              # needs sage.modules
      sage: fcp(A, 'x')                                                               # needs sage.libs.pari sage.modules
      x * (x^2 - 15*x - 18)

  Python

      >>> from sage.all import *
      >>> M = MatrixSpace(QQ, Integer(3), Integer(3))                                                 # needs sage.modules
      >>> A = M([Integer(1),Integer(2),Integer(3), Integer(4),Integer(5),Integer(6), Integer(7),Integer(8),Integer(9)])                                              # needs sage.modules
      >>> fcp(A, 'x')                                                               # needs sage.libs.pari sage.modules
      x * (x^2 - 15*x - 18)

sage.misc.functional.gen(x)

  Return the generator of `x`.

  EXAMPLES:

  Sage

      sage: R.<x> = QQ[]; R
      Univariate Polynomial Ring in x over Rational Field
      sage: gen(R)
      x
      sage: gen(GF(7))
      1
      sage: A = AbelianGroup(1, [23])                                                 # needs sage.groups
      sage: gen(A)                                                                    # needs sage.groups
      f

  Python

      >>> from sage.all import *
      >>> R = QQ['x']; (x,) = R._first_ngens(1); R
      Univariate Polynomial Ring in x over Rational Field
      >>> gen(R)
      x
      >>> gen(GF(Integer(7)))
      1
      >>> A = AbelianGroup(Integer(1), [Integer(23)])                                                 # needs sage.groups
      >>> gen(A)                                                                    # needs sage.groups
      f

sage.misc.functional.gens(x)

  Return the generators of `x`.

  EXAMPLES:

  Sage

      sage: R.<x,y> = SR[]                                                            # needs sage.symbolic
      sage: R                                                                         # needs sage.symbolic
      Multivariate Polynomial Ring in x, y over Symbolic Ring
      sage: gens(R)                                                                   # needs sage.symbolic
      (x, y)

      sage: A = AbelianGroup(5, [5,5,7,8,9])                                          # needs sage.groups
      sage: gens(A)                                                                   # needs sage.groups
      (f0, f1, f2, f3, f4)

  Python

      >>> from sage.all import *
      >>> R = SR['x, y']; (x, y,) = R._first_ngens(2)# needs sage.symbolic
      >>> R                                                                         # needs sage.symbolic
      Multivariate Polynomial Ring in x, y over Symbolic Ring
      >>> gens(R)                                                                   # needs sage.symbolic
      (x, y)

      >>> A = AbelianGroup(Integer(5), [Integer(5),Integer(5),Integer(7),Integer(8),Integer(9)])                                          # needs sage.groups
      >>> gens(A)                                                                   # needs sage.groups
      (f0, f1, f2, f3, f4)

sage.misc.functional.hecke_operator(x, n)

  Return the \(n\)-th Hecke operator \(T_n\) acting on `x`.

  EXAMPLES:

  Sage

      sage: M = ModularSymbols(1,12)                                                  # needs sage.modular
      sage: hecke_operator(M,5)                                                       # needs sage.modular
      Hecke operator T_5 on Modular Symbols space of dimension 3 for Gamma_0(1)
       of weight 12 with sign 0 over Rational Field

  Python

      >>> from sage.all import *
      >>> M = ModularSymbols(Integer(1),Integer(12))                                                  # needs sage.modular
      >>> hecke_operator(M,Integer(5))                                                       # needs sage.modular
      Hecke operator T_5 on Modular Symbols space of dimension 3 for Gamma_0(1)
       of weight 12 with sign 0 over Rational Field

sage.misc.functional.image(x)

  Return the image of `x`.

  EXAMPLES:

  Sage

      sage: M = MatrixSpace(QQ, 3, 3)                                                 # needs sage.modules
      sage: A = M([1,2,3, 4,5,6, 7,8,9])                                              # needs sage.modules
      sage: image(A)                                                                  # needs sage.modules
      Vector space of degree 3 and dimension 2 over Rational Field
      Basis matrix:
      [ 1  0 -1]
      [ 0  1  2]

  Python

      >>> from sage.all import *
      >>> M = MatrixSpace(QQ, Integer(3), Integer(3))                                                 # needs sage.modules
      >>> A = M([Integer(1),Integer(2),Integer(3), Integer(4),Integer(5),Integer(6), Integer(7),Integer(8),Integer(9)])                                              # needs sage.modules
      >>> image(A)                                                                  # needs sage.modules
      Vector space of degree 3 and dimension 2 over Rational Field
      Basis matrix:
      [ 1  0 -1]
      [ 0  1  2]

sage.misc.functional.integral(x, *args, **kwds)

  Return an indefinite or definite integral of an object `x`.

  First call `x.integral()` and if that fails make an object and integrate it using Maxima, maple, etc, as specified by algorithm.

  For symbolic expression calls `sage.calculus.calculus.integral()` - see this function for available options.

  EXAMPLES:

  Sage

      sage: f = cyclotomic_polynomial(10)
      sage: integral(f)
      1/5*x^5 - 1/4*x^4 + 1/3*x^3 - 1/2*x^2 + x

  Python

      >>> from sage.all import *
      >>> f = cyclotomic_polynomial(Integer(10))
      >>> integral(f)
      1/5*x^5 - 1/4*x^4 + 1/3*x^3 - 1/2*x^2 + x

  Sage

      sage: integral(sin(x), x)                                                       # needs sage.symbolic
      -cos(x)

  [Python]

      >>> from sage.all import *
      >>> integral(sin(x), x)                                                       # needs sage.symbolic
      -cos(x)

  Sage

      sage: y = var('y')                                                              # needs sage.symbolic
      sage: integral(sin(x), y)                                                       # needs sage.symbolic
      y*sin(x)

  Python

      >>> from sage.all import *
      >>> y = var('y')                                                              # needs sage.symbolic
      >>> integral(sin(x), y)                                                       # needs sage.symbolic
      y*sin(x)

  Sage

      sage: integral(sin(x), x, 0, pi/2)                                              # needs sage.symbolic
      1
      sage: sin(x).integral(x, 0, pi/2)                                               # needs sage.symbolic
      1
      sage: integral(exp(-x), (x, 1, oo))                                             # needs sage.symbolic
      e^(-1)

  [Python]

      >>> from sage.all import *
      >>> integral(sin(x), x, Integer(0), pi/Integer(2))                                              # needs sage.symbolic
      1
      >>> sin(x).integral(x, Integer(0), pi/Integer(2))                                               # needs sage.symbolic
      1
      >>> integral(exp(-x), (x, Integer(1), oo))                                             # needs sage.symbolic
      e^(-1)

  Numerical approximation:

  Sage

      sage: h = integral(tan(x)/x, (x, 1, pi/3))                                      # needs sage.symbolic
      ...
      sage: h                                                                         # needs sage.symbolic
      integrate(tan(x)/x, x, 1, 1/3*pi)
      sage: h.n()                                                                     # needs sage.symbolic
      0.07571599101...

  Python

      >>> from sage.all import *
      >>> h = integral(tan(x)/x, (x, Integer(1), pi/Integer(3)))                                      # needs sage.symbolic
      ...
      >>> h                                                                         # needs sage.symbolic
      integrate(tan(x)/x, x, 1, 1/3*pi)
      >>> h.n()                                                                     # needs sage.symbolic
      0.07571599101...

  Specific algorithm can be used for integration:

  Sage

      sage: integral(sin(x)^2, x, algorithm='maxima')                                 # needs sage.symbolic
      1/2*x - 1/4*sin(2*x)
      sage: integral(sin(x)^2, x, algorithm='sympy')                                  # needs sage.symbolic
      -1/2*cos(x)*sin(x) + 1/2*x

  [Python]

      >>> from sage.all import *
      >>> integral(sin(x)**Integer(2), x, algorithm='maxima')                                 # needs sage.symbolic
      1/2*x - 1/4*sin(2*x)
      >>> integral(sin(x)**Integer(2), x, algorithm='sympy')                                  # needs sage.symbolic
      -1/2*cos(x)*sin(x) + 1/2*x

sage.misc.functional.integral_closure(x)

  Return the integral closure of `x`.

  EXAMPLES:

  Sage

      sage: integral_closure(QQ)
      Rational Field
      sage: K.<a> = QuadraticField(5)                                                 # needs sage.rings.number_field
      sage: O2 = K.order(2 * a); O2                                                   # needs sage.rings.number_field
      Order of conductor 4 generated by 2*a in Number Field in a
       with defining polynomial x^2 - 5 with a = 2.236067977499790?
      sage: integral_closure(O2)                                                      # needs sage.rings.number_field
      Maximal Order generated by 1/2*a + 1/2 in Number Field in a
       with defining polynomial x^2 - 5 with a = 2.236067977499790?

  Python

      >>> from sage.all import *
      >>> integral_closure(QQ)
      Rational Field
      >>> K = QuadraticField(Integer(5), names=('a',)); (a,) = K._first_ngens(1)# needs sage.rings.number_field
      >>> O2 = K.order(Integer(2) * a); O2                                                   # needs sage.rings.number_field
      Order of conductor 4 generated by 2*a in Number Field in a
       with defining polynomial x^2 - 5 with a = 2.236067977499790?
      >>> integral_closure(O2)                                                      # needs sage.rings.number_field
      Maximal Order generated by 1/2*a + 1/2 in Number Field in a
       with defining polynomial x^2 - 5 with a = 2.236067977499790?

sage.misc.functional.integrate(x, *args, **kwds)

  alias of `integral()`.

sage.misc.functional.interval(a, b)

  Integers between \(a\) and \(b\) inclusive (\(a\) and \(b\) integers).

  EXAMPLES:

  Sage

      sage: I = interval(1,3)
      sage: 2 in I
      True
      sage: 1 in I
      True
      sage: 4 in I
      False

  Python

      >>> from sage.all import *
      >>> I = interval(Integer(1),Integer(3))
      >>> Integer(2) in I
      True
      >>> Integer(1) in I
      True
      >>> Integer(4) in I
      False

sage.misc.functional.is_even(x)

  Return whether or not an integer `x` is even, e.g., divisible by 2.

  EXAMPLES:

  Sage

      sage: is_even(-1)
      False
      sage: is_even(4)
      True
      sage: is_even(-2)
      True

  Python

      >>> from sage.all import *
      >>> is_even(-Integer(1))
      False
      >>> is_even(Integer(4))
      True
      >>> is_even(-Integer(2))
      True

sage.misc.functional.is_odd(x)

  Return whether or not `x` is odd.

  This is by definition the complement of `is_even()`.

  EXAMPLES:

  Sage

      sage: is_odd(-2)
      False
      sage: is_odd(-3)
      True
      sage: is_odd(0)
      False
      sage: is_odd(1)
      True

  Python

      >>> from sage.all import *
      >>> is_odd(-Integer(2))
      False
      >>> is_odd(-Integer(3))
      True
      >>> is_odd(Integer(0))
      False
      >>> is_odd(Integer(1))
      True

sage.misc.functional.isqrt(x)

  Return an integer square root, i.e., the floor of a square root.

  EXAMPLES:

  Sage

      sage: isqrt(10)
      3
      sage: isqrt(10r)
      3

  Python

      >>> from sage.all import *
      >>> isqrt(Integer(10))
      3
      >>> isqrt(10)
      3

sage.misc.functional.kernel(x)

  Return the left kernel of `x`.

  EXAMPLES:

  Sage

      sage: # needs sage.modules
      sage: M = MatrixSpace(QQ, 3, 2)
      sage: A = M([1,2, 3,4, 5,6])
      sage: kernel(A)
      Vector space of degree 3 and dimension 1 over Rational Field
      Basis matrix:
      [ 1 -2  1]
      sage: kernel(A.transpose())
      Vector space of degree 2 and dimension 0 over Rational Field
      Basis matrix:
      []

  Python

      >>> from sage.all import *
      >>> # needs sage.modules
      >>> M = MatrixSpace(QQ, Integer(3), Integer(2))
      >>> A = M([Integer(1),Integer(2), Integer(3),Integer(4), Integer(5),Integer(6)])
      >>> kernel(A)
      Vector space of degree 3 and dimension 1 over Rational Field
      Basis matrix:
      [ 1 -2  1]
      >>> kernel(A.transpose())
      Vector space of degree 2 and dimension 0 over Rational Field
      Basis matrix:
      []

  Here are two corner cases:

  Sage

      sage: # needs sage.modules
      sage: M = MatrixSpace(QQ, 0, 3)
      sage: A = M([])
      sage: kernel(A)
      Vector space of degree 0 and dimension 0 over Rational Field
      Basis matrix:
      []
      sage: kernel(A.transpose()).basis()
      [(1, 0, 0), (0, 1, 0), (0, 0, 1)]

  [Python]

      >>> from sage.all import *
      >>> # needs sage.modules
      >>> M = MatrixSpace(QQ, Integer(0), Integer(3))
      >>> A = M([])
      >>> kernel(A)
      Vector space of degree 0 and dimension 0 over Rational Field
      Basis matrix:
      []
      >>> kernel(A.transpose()).basis()
      [(1, 0, 0), (0, 1, 0), (0, 0, 1)]

sage.misc.functional.krull_dimension(x)

  Return the Krull dimension of `x`.

  EXAMPLES:

  Sage

      sage: krull_dimension(QQ)
      doctest:warning...:
      DeprecationWarning: please use the krull_dimension method
      See https://github.com/sagemath/sage/issues/39311 for details.
      0
      sage: ZZ.krull_dimension()
      1
      sage: ZZ[sqrt(5)].krull_dimension()                                             # needs sage.rings.number_field sage.symbolic
      1
      sage: U.<x,y,z> = PolynomialRing(ZZ, 3); U
      Multivariate Polynomial Ring in x, y, z over Integer Ring
      sage: U.krull_dimension()
      4

  Python

      >>> from sage.all import *
      >>> krull_dimension(QQ)
      doctest:warning...:
      DeprecationWarning: please use the krull_dimension method
      See https://github.com/sagemath/sage/issues/39311 for details.
      0
      >>> ZZ.krull_dimension()
      1
      >>> ZZ[sqrt(Integer(5))].krull_dimension()                                             # needs sage.rings.number_field sage.symbolic
      1
      >>> U = PolynomialRing(ZZ, Integer(3), names=('x', 'y', 'z',)); (x, y, z,) = U._first_ngens(3); U
      Multivariate Polynomial Ring in x, y, z over Integer Ring
      >>> U.krull_dimension()
      4

sage.misc.functional.lift(x)

  Lift an object of a quotient ring \(R/I\) to \(R\).

  EXAMPLES:

  We lift an integer modulo \(3\):

  Sage

      sage: Mod(2,3).lift()
      2

  Python

      >>> from sage.all import *
      >>> Mod(Integer(2),Integer(3)).lift()
      2

  We lift an element of a quotient polynomial ring:

  Sage

      sage: R.<x> = QQ['x']
      sage: S.<xmod> = R.quo(x^2 + 1)                                                 # needs sage.libs.pari
      sage: lift(xmod - 7)                                                            # needs sage.libs.pari
      x - 7

  [Python]

      >>> from sage.all import *
      >>> R = QQ['x']; (x,) = R._first_ngens(1)
      >>> S = R.quo(x**Integer(2) + Integer(1), names=('xmod',)); (xmod,) = S._first_ngens(1)# needs sage.libs.pari
      >>> lift(xmod - Integer(7))                                                            # needs sage.libs.pari
      x - 7

sage.misc.functional.log(*args, **kwds)

  Return the logarithm of the first argument to the base of the second argument which if missing defaults to `e`.

  It calls the `log` method of the first argument when computing the logarithm, thus allowing the use of logarithm on any object containing a `log` method. In other words, `log` works on more than just real numbers.

  Note

  In Magma, the order of arguments is reversed from in Sage, i.e., the base is given first. We use the opposite ordering, so the base can be viewed as an optional second argument.

  EXAMPLES:

  Sage

      sage: log(e^2)                                                                  # needs sage.symbolic
      2

  Python

      >>> from sage.all import *
      >>> log(e**Integer(2))                                                                  # needs sage.symbolic
      2

  To change the base of the logarithm, add a second parameter:

  Sage

      sage: log(1000,10)
      3

  [Python]

      >>> from sage.all import *
      >>> log(Integer(1000),Integer(10))
      3

  The synonym `ln` can only take one argument:

  Sage

      sage: # needs sage.symbolic
      sage: ln(RDF(10))
      2.302585092994046
      sage: ln(2.718)
      0.999896315728952
      sage: ln(2.0)
      0.693147180559945
      sage: ln(float(-1))
      3.141592653589793j

      sage: ln(complex(-1))
      3.141592653589793j

  Python

      >>> from sage.all import *
      >>> # needs sage.symbolic
      >>> ln(RDF(Integer(10)))
      2.302585092994046
      >>> ln(RealNumber('2.718'))
      0.999896315728952
      >>> ln(RealNumber('2.0'))
      0.693147180559945
      >>> ln(float(-Integer(1)))
      3.141592653589793j

      >>> ln(complex(-Integer(1)))
      3.141592653589793j

  You can use `RDF`, `RealField` or `n` to get a numerical real approximation:

  Sage

      sage: log(1024, 2)
      10
      sage: RDF(log(1024, 2))
      10.0

      sage: # needs sage.symbolic
      sage: log(10, 4)
      1/2*log(10)/log(2)
      sage: RDF(log(10, 4))
      1.6609640474436813
      sage: log(10, 2)
      log(10)/log(2)
      sage: n(log(10, 2))
      3.32192809488736
      sage: log(10, e)
      log(10)
      sage: n(log(10, e))
      2.30258509299405

  [Python]

      >>> from sage.all import *
      >>> log(Integer(1024), Integer(2))
      10
      >>> RDF(log(Integer(1024), Integer(2)))
      10.0

      >>> # needs sage.symbolic
      >>> log(Integer(10), Integer(4))
      1/2*log(10)/log(2)
      >>> RDF(log(Integer(10), Integer(4)))
      1.6609640474436813
      >>> log(Integer(10), Integer(2))
      log(10)/log(2)
      >>> n(log(Integer(10), Integer(2)))
      3.32192809488736
      >>> log(Integer(10), e)
      log(10)
      >>> n(log(Integer(10), e))
      2.30258509299405

  The log function works for negative numbers, complex numbers, and symbolic numbers too, picking the branch with angle between \(-\pi\) and \(\pi\):

  Sage

      sage: log(-1+0*I)                                                               # needs sage.symbolic
      I*pi
      sage: log(CC(-1))                                                               # needs sage.rings.real_mpfr
      3.14159265358979*I
      sage: log(-1.0)                                                                 # needs sage.symbolic
      3.14159265358979*I

  Python

      >>> from sage.all import *
      >>> log(-Integer(1)+Integer(0)*I)                                                               # needs sage.symbolic
      I*pi
      >>> log(CC(-Integer(1)))                                                               # needs sage.rings.real_mpfr
      3.14159265358979*I
      >>> log(-RealNumber('1.0'))                                                                 # needs sage.symbolic
      3.14159265358979*I

  Small integer powers are factored out immediately:

  Sage

      sage: # needs sage.symbolic
      sage: log(4)
      2*log(2)
      sage: log(1000000000)
      9*log(10)
      sage: log(8) - 3*log(2)
      0
      sage: bool(log(8) == 3*log(2))
      True

  [Python]

      >>> from sage.all import *
      >>> # needs sage.symbolic
      >>> log(Integer(4))
      2*log(2)
      >>> log(Integer(1000000000))
      9*log(10)
      >>> log(Integer(8)) - Integer(3)*log(Integer(2))
      0
      >>> bool(log(Integer(8)) == Integer(3)*log(Integer(2)))
      True

  The `hold` parameter can be used to prevent automatic evaluation:

  Sage

      sage: # needs sage.symbolic
      sage: log(-1, hold=True)
      log(-1)
      sage: log(-1)
      I*pi
      sage: I.log(hold=True)
      log(I)
      sage: I.log(hold=True).simplify()
      1/2*I*pi

  Python

      >>> from sage.all import *
      >>> # needs sage.symbolic
      >>> log(-Integer(1), hold=True)
      log(-1)
      >>> log(-Integer(1))
      I*pi
      >>> I.log(hold=True)
      log(I)
      >>> I.log(hold=True).simplify()
      1/2*I*pi

  For input zero, the following behavior occurs:

  Sage

      sage: log(0)                                                                    # needs sage.symbolic
      -Infinity
      sage: log(CC(0))                                                                # needs sage.rings.real_mpfr
      -infinity
      sage: log(0.0)                                                                  # needs sage.symbolic
      -infinity

  [Python]

      >>> from sage.all import *
      >>> log(Integer(0))                                                                    # needs sage.symbolic
      -Infinity
      >>> log(CC(Integer(0)))                                                                # needs sage.rings.real_mpfr
      -infinity
      >>> log(RealNumber('0.0'))                                                                  # needs sage.symbolic
      -infinity

  The log function also works in finite fields as long as the argument lies in the multiplicative group generated by the base:

  Sage

      sage: # needs sage.libs.pari
      sage: F = GF(13); g = F.multiplicative_generator(); g
      2
      sage: a = F(8)
      sage: log(a, g); g^log(a, g)
      3
      8
      sage: log(a, 3)
      Traceback (most recent call last):
      ...
      ValueError: no logarithm of 8 found to base 3 modulo 13
      sage: log(F(9), 3)
      2

  Python

      >>> from sage.all import *
      >>> # needs sage.libs.pari
      >>> F = GF(Integer(13)); g = F.multiplicative_generator(); g
      2
      >>> a = F(Integer(8))
      >>> log(a, g); g**log(a, g)
      3
      8
      >>> log(a, Integer(3))
      Traceback (most recent call last):
      ...
      ValueError: no logarithm of 8 found to base 3 modulo 13
      >>> log(F(Integer(9)), Integer(3))
      2

  The log function also works for \(p\)-adics (see documentation for \(p\)-adics for more information):

  Sage

      sage: R = Zp(5); R                                                              # needs sage.rings.padics
      5-adic Ring with capped relative precision 20
      sage: a = R(16); a                                                              # needs sage.rings.padics
      1 + 3*5 + O(5^20)
      sage: log(a)                                                                    # needs sage.rings.padics
      3*5 + 3*5^2 + 3*5^4 + 3*5^5 + 3*5^6 + 4*5^7 + 2*5^8 + 5^9 +
      5^11 + 2*5^12 + 5^13 + 3*5^15 + 2*5^16 + 4*5^17 + 3*5^18 +
      3*5^19 + O(5^20)

  [Python]

      >>> from sage.all import *
      >>> R = Zp(Integer(5)); R                                                              # needs sage.rings.padics
      5-adic Ring with capped relative precision 20
      >>> a = R(Integer(16)); a                                                              # needs sage.rings.padics
      1 + 3*5 + O(5^20)
      >>> log(a)                                                                    # needs sage.rings.padics
      3*5 + 3*5^2 + 3*5^4 + 3*5^5 + 3*5^6 + 4*5^7 + 2*5^8 + 5^9 +
      5^11 + 2*5^12 + 5^13 + 3*5^15 + 2*5^16 + 4*5^17 + 3*5^18 +
      3*5^19 + O(5^20)

sage.misc.functional.minimal_polynomial(x, var='x')

  Return the minimal polynomial of `x`.

  EXAMPLES:

  Sage

      sage: # needs sage.libs.pari sage.modules
      sage: a = matrix(ZZ, 2, [1..4])
      sage: minpoly(a)
      x^2 - 5*x - 2
      sage: minpoly(a, 't')
      t^2 - 5*t - 2
      sage: minimal_polynomial(a)
      x^2 - 5*x - 2
      sage: minimal_polynomial(a, 'theta')
      theta^2 - 5*theta - 2

  Python

      >>> from sage.all import *
      >>> # needs sage.libs.pari sage.modules
      >>> a = matrix(ZZ, Integer(2), (ellipsis_range(Integer(1),Ellipsis,Integer(4))))
      >>> minpoly(a)
      x^2 - 5*x - 2
      >>> minpoly(a, 't')
      t^2 - 5*t - 2
      >>> minimal_polynomial(a)
      x^2 - 5*x - 2
      >>> minimal_polynomial(a, 'theta')
      theta^2 - 5*theta - 2

sage.misc.functional.minpoly(x, var='x')

  alias of `minimal_polynomial()`.

sage.misc.functional.multiplicative_order(x)

  Return the multiplicative order of `x`, if `x` is a unit, or raise `ArithmeticError` otherwise.

  EXAMPLES:

  Sage

      sage: a = mod(5, 11)
      sage: multiplicative_order(a)                                                   # needs sage.libs.pari
      5
      sage: multiplicative_order(mod(2, 11))                                          # needs sage.libs.pari
      10
      sage: multiplicative_order(mod(2, 12))                                          # needs sage.libs.pari
      Traceback (most recent call last):
      ...
      ArithmeticError: multiplicative order of 2 not defined since it is not a unit modulo 12

  Python

      >>> from sage.all import *
      >>> a = mod(Integer(5), Integer(11))
      >>> multiplicative_order(a)                                                   # needs sage.libs.pari
      5
      >>> multiplicative_order(mod(Integer(2), Integer(11)))                                          # needs sage.libs.pari
      10
      >>> multiplicative_order(mod(Integer(2), Integer(12)))                                          # needs sage.libs.pari
      Traceback (most recent call last):
      ...
      ArithmeticError: multiplicative order of 2 not defined since it is not a unit modulo 12

sage.misc.functional.n(x, prec=None, digits=None, algorithm=None)

  alias of `numerical_approx()`.

sage.misc.functional.ngens(x)

  Return the number of generators of `x`.

  EXAMPLES:

  Sage

      sage: R.<x,y> = SR[]; R                                                         # needs sage.symbolic
      Multivariate Polynomial Ring in x, y over Symbolic Ring
      sage: ngens(R)                                                                  # needs sage.symbolic
      2
      sage: A = AbelianGroup(5, [5,5,7,8,9])                                          # needs sage.groups
      sage: ngens(A)                                                                  # needs sage.groups
      5
      sage: ngens(ZZ)
      1

  Python

      >>> from sage.all import *
      >>> R = SR['x, y']; (x, y,) = R._first_ngens(2); R                                                         # needs sage.symbolic
      Multivariate Polynomial Ring in x, y over Symbolic Ring
      >>> ngens(R)                                                                  # needs sage.symbolic
      2
      >>> A = AbelianGroup(Integer(5), [Integer(5),Integer(5),Integer(7),Integer(8),Integer(9)])                                          # needs sage.groups
      >>> ngens(A)                                                                  # needs sage.groups
      5
      >>> ngens(ZZ)
      1

sage.misc.functional.norm(x)

  Return the norm of `x`.

  For matrices and vectors, this returns the L2-norm. The L2-norm of a vector \(\textbf{v} = (v_1, v_2, \dots, v_n)\), also called the Euclidean norm, is defined as

  \[|\textbf{v}| = \sqrt{\sum_{i=1}^n |v_i|^2}\]

  where \(|v_i|\) is the complex modulus of \(v_i\). The Euclidean norm is often used for determining the distance between two points in two- or three-dimensional space.

  For complex numbers, the function returns the field norm. If \(c = a + bi\) is a complex number, then the norm of \(c\) is defined as the product of \(c\) and its complex conjugate:

  \[\text{norm}(c) = \text{norm}(a + bi) = c \cdot \overline{c} = a^2 + b^2.\]

  The norm of a complex number is different from its absolute value. The absolute value of a complex number is defined to be the square root of its norm. A typical use of the complex norm is in the integral domain \(\ZZ[i]\) of Gaussian integers, where the norm of each Gaussian integer \(c = a + bi\) is defined as its complex norm.

  For vector fields on a pseudo-Riemannian manifold \((M,g)\), the function returns the norm with respect to the metric \(g\):

  \[|v| = \sqrt{g(v,v)}\]

  See also

  - `sage.matrix.matrix2.Matrix.norm()`

  - `sage.modules.free_module_element.FreeModuleElement.norm()`

  - `sage.rings.complex_double.ComplexDoubleElement.norm()`

  - `sage.rings.complex_mpfr.ComplexNumber.norm()`

  - `sage.symbolic.expression.Expression.norm()`

  - `sage.manifolds.differentiable.vectorfield.VectorField.norm()`

  EXAMPLES:

  The norm of vectors:

  Sage

      sage: # needs sage.modules sage.symbolic
      sage: z = 1 + 2*I
      sage: norm(vector([z]))
      sqrt(5)
      sage: v = vector([-1,2,3])
      sage: norm(v)
      sqrt(14)
      sage: _ = var("a b c d", domain='real')
      sage: v = vector([a, b, c, d])
      sage: norm(v)
      sqrt(a^2 + b^2 + c^2 + d^2)

  Python

      >>> from sage.all import *
      >>> # needs sage.modules sage.symbolic
      >>> z = Integer(1) + Integer(2)*I
      >>> norm(vector([z]))
      sqrt(5)
      >>> v = vector([-Integer(1),Integer(2),Integer(3)])
      >>> norm(v)
      sqrt(14)
      >>> _ = var("a b c d", domain='real')
      >>> v = vector([a, b, c, d])
      >>> norm(v)
      sqrt(a^2 + b^2 + c^2 + d^2)

  The norm of matrices:

  Sage

      sage: # needs sage.modules sage.symbolic
      sage: z = 1 + 2*I
      sage: norm(matrix([[z]]))
      2.23606797749979
      sage: M = matrix(ZZ, [[1,2,4,3], [-1,0,3,-10]])
      sage: norm(M)  # abs tol 1e-14
      10.690331129154467
      sage: norm(CDF(z))
      5.0
      sage: norm(CC(z))
      5.00000000000000

  [Python]

      >>> from sage.all import *
      >>> # needs sage.modules sage.symbolic
      >>> z = Integer(1) + Integer(2)*I
      >>> norm(matrix([[z]]))
      2.23606797749979
      >>> M = matrix(ZZ, [[Integer(1),Integer(2),Integer(4),Integer(3)], [-Integer(1),Integer(0),Integer(3),-Integer(10)]])
      >>> norm(M)  # abs tol 1e-14
      10.690331129154467
      >>> norm(CDF(z))
      5.0
      >>> norm(CC(z))
      5.00000000000000

  The norm of complex numbers:

  Sage

      sage: # needs sage.symbolic
      sage: z = 2 - 3*I
      sage: norm(z)
      13
      sage: a = randint(-10^10, 100^10)
      sage: b = randint(-10^10, 100^10)
      sage: z = a + b*I
      sage: bool(norm(z) == a^2 + b^2)
      True

  Python

      >>> from sage.all import *
      >>> # needs sage.symbolic
      >>> z = Integer(2) - Integer(3)*I
      >>> norm(z)
      13
      >>> a = randint(-Integer(10)**Integer(10), Integer(100)**Integer(10))
      >>> b = randint(-Integer(10)**Integer(10), Integer(100)**Integer(10))
      >>> z = a + b*I
      >>> bool(norm(z) == a**Integer(2) + b**Integer(2))
      True

  The complex norm of symbolic expressions:

  Sage

      sage: # needs sage.symbolic
      sage: a, b, c = var("a, b, c")
      sage: assume((a, 'real'), (b, 'real'), (c, 'real'))
      sage: z = a + b*I
      sage: bool(norm(z).simplify() == a^2 + b^2)
      True
      sage: norm(a + b).simplify()
      a^2 + 2*a*b + b^2
      sage: v = vector([a, b, c])
      sage: bool(norm(v).simplify() == sqrt(a^2 + b^2 + c^2))
      True
      sage: forget()

  [Python]

      >>> from sage.all import *
      >>> # needs sage.symbolic
      >>> a, b, c = var("a, b, c")
      >>> assume((a, 'real'), (b, 'real'), (c, 'real'))
      >>> z = a + b*I
      >>> bool(norm(z).simplify() == a**Integer(2) + b**Integer(2))
      True
      >>> norm(a + b).simplify()
      a^2 + 2*a*b + b^2
      >>> v = vector([a, b, c])
      >>> bool(norm(v).simplify() == sqrt(a**Integer(2) + b**Integer(2) + c**Integer(2)))
      True
      >>> forget()

sage.misc.functional.numerator(x)

  Return the numerator of `x`.

  EXAMPLES:

  Sage

      sage: R.<x> = PolynomialRing(QQ)
      sage: F = FractionField(R)
      sage: r = (x+1)/(x-1)
      sage: numerator(r)
      x + 1
      sage: numerator(17/11111)
      17

  Python

      >>> from sage.all import *
      >>> R = PolynomialRing(QQ, names=('x',)); (x,) = R._first_ngens(1)
      >>> F = FractionField(R)
      >>> r = (x+Integer(1))/(x-Integer(1))
      >>> numerator(r)
      x + 1
      >>> numerator(Integer(17)/Integer(11111))
      17

sage.misc.functional.numerical_approx(x, prec=None, digits=None, algorithm=None)

  Return a numerical approximation of `self` with `prec` bits (or decimal `digits`) of precision.

  No guarantee is made about the accuracy of the result.

  Note

  Lower case `n()` is an alias for `numerical_approx()` and may be used as a method.

  INPUT:

  - `prec` – precision in bits

  - `digits` – precision in decimal digits (only used if `prec` is not given)

  - `algorithm` – which algorithm to use to compute this approximation (the accepted algorithms depend on the object)

  If neither `prec` nor `digits` is given, the default precision is 53 bits (roughly 16 digits).

  EXAMPLES:

  Sage

      sage: # needs sage.symbolic
      sage: numerical_approx(pi, 10)
      3.1
      sage: numerical_approx(pi, digits=10)
      3.141592654
      sage: numerical_approx(pi^2 + e, digits=20)
      12.587886229548403854
      sage: n(pi^2 + e)
      12.5878862295484
      sage: N(pi^2 + e)
      12.5878862295484
      sage: n(pi^2 + e, digits=50)
      12.587886229548403854194778471228813633070946500941

      sage: # needs sage.rings.real_mpfr
      sage: a = CC(-5).n(prec=40)
      sage: b = ComplexField(40)(-5)
      sage: a == b
      True
      sage: parent(a) is parent(b)
      True
      sage: numerical_approx(9)
      9.00000000000000

  Python

      >>> from sage.all import *
      >>> # needs sage.symbolic
      >>> numerical_approx(pi, Integer(10))
      3.1
      >>> numerical_approx(pi, digits=Integer(10))
      3.141592654
      >>> numerical_approx(pi**Integer(2) + e, digits=Integer(20))
      12.587886229548403854
      >>> n(pi**Integer(2) + e)
      12.5878862295484
      >>> N(pi**Integer(2) + e)
      12.5878862295484
      >>> n(pi**Integer(2) + e, digits=Integer(50))
      12.587886229548403854194778471228813633070946500941

      >>> # needs sage.rings.real_mpfr
      >>> a = CC(-Integer(5)).n(prec=Integer(40))
      >>> b = ComplexField(Integer(40))(-Integer(5))
      >>> a == b
      True
      >>> parent(a) is parent(b)
      True
      >>> numerical_approx(Integer(9))
      9.00000000000000

  You can also usually use method notation:

  Sage

      sage: (pi^2 + e).n()                                                            # needs sage.symbolic
      12.5878862295484
      sage: (pi^2 + e).numerical_approx()                                             # needs sage.symbolic
      12.5878862295484

  [Python]

      >>> from sage.all import *
      >>> (pi**Integer(2) + e).n()                                                            # needs sage.symbolic
      12.5878862295484
      >>> (pi**Integer(2) + e).numerical_approx()                                             # needs sage.symbolic
      12.5878862295484

  Vectors and matrices may also have their entries approximated:

  Sage

      sage: v = vector(RDF, [1,2,3])                                                  # needs sage.modules
      sage: v.n()                                                                     # needs sage.modules
      (1.00000000000000, 2.00000000000000, 3.00000000000000)

      sage: # needs sage.modules
      sage: v = vector(CDF, [1,2,3])
      sage: v.n()
      (1.00000000000000, 2.00000000000000, 3.00000000000000)
      sage: _.parent()
      Vector space of dimension 3 over Complex Field with 53 bits of precision
      sage: v.n(prec=20)
      (1.0000, 2.0000, 3.0000)

      sage: u = vector(QQ, [1/2, 1/3, 1/4])                                           # needs sage.modules
      sage: n(u, prec=15)                                                             # needs sage.modules
      (0.5000, 0.3333, 0.2500)
      sage: n(u, digits=5)                                                            # needs sage.modules
      (0.50000, 0.33333, 0.25000)

      sage: # needs sage.modules
      sage: v = vector(QQ, [1/2, 0, 0, 1/3, 0, 0, 0, 1/4], sparse=True)
      sage: u = v.numerical_approx(digits=4)
      sage: u.is_sparse()
      True
      sage: u
      (0.5000, 0.0000, 0.0000, 0.3333, 0.0000, 0.0000, 0.0000, 0.2500)

      sage: # needs sage.modules
      sage: A = matrix(QQ, 2, 3, range(6))
      sage: A.n()
      [0.000000000000000  1.00000000000000  2.00000000000000]
      [ 3.00000000000000  4.00000000000000  5.00000000000000]
      sage: B = matrix(Integers(12), 3, 8, srange(24))
      sage: N(B, digits=2)
      [0.00  1.0  2.0  3.0  4.0  5.0  6.0  7.0]
      [ 8.0  9.0  10.  11. 0.00  1.0  2.0  3.0]
      [ 4.0  5.0  6.0  7.0  8.0  9.0  10.  11.]

  Python

      >>> from sage.all import *
      >>> v = vector(RDF, [Integer(1),Integer(2),Integer(3)])                                                  # needs sage.modules
      >>> v.n()                                                                     # needs sage.modules
      (1.00000000000000, 2.00000000000000, 3.00000000000000)

      >>> # needs sage.modules
      >>> v = vector(CDF, [Integer(1),Integer(2),Integer(3)])
      >>> v.n()
      (1.00000000000000, 2.00000000000000, 3.00000000000000)
      >>> _.parent()
      Vector space of dimension 3 over Complex Field with 53 bits of precision
      >>> v.n(prec=Integer(20))
      (1.0000, 2.0000, 3.0000)

      >>> u = vector(QQ, [Integer(1)/Integer(2), Integer(1)/Integer(3), Integer(1)/Integer(4)])                                           # needs sage.modules
      >>> n(u, prec=Integer(15))                                                             # needs sage.modules
      (0.5000, 0.3333, 0.2500)
      >>> n(u, digits=Integer(5))                                                            # needs sage.modules
      (0.50000, 0.33333, 0.25000)

      >>> # needs sage.modules
      >>> v = vector(QQ, [Integer(1)/Integer(2), Integer(0), Integer(0), Integer(1)/Integer(3), Integer(0), Integer(0), Integer(0), Integer(1)/Integer(4)], sparse=True)
      >>> u = v.numerical_approx(digits=Integer(4))
      >>> u.is_sparse()
      True
      >>> u
      (0.5000, 0.0000, 0.0000, 0.3333, 0.0000, 0.0000, 0.0000, 0.2500)

      >>> # needs sage.modules
      >>> A = matrix(QQ, Integer(2), Integer(3), range(Integer(6)))
      >>> A.n()
      [0.000000000000000  1.00000000000000  2.00000000000000]
      [ 3.00000000000000  4.00000000000000  5.00000000000000]
      >>> B = matrix(Integers(Integer(12)), Integer(3), Integer(8), srange(Integer(24)))
      >>> N(B, digits=Integer(2))
      [0.00  1.0  2.0  3.0  4.0  5.0  6.0  7.0]
      [ 8.0  9.0  10.  11. 0.00  1.0  2.0  3.0]
      [ 4.0  5.0  6.0  7.0  8.0  9.0  10.  11.]

  Internally, numerical approximations of real numbers are stored in base-2. Therefore, numbers which look the same in their decimal expansion might be different:

  Sage

      sage: x = N(pi, digits=3); x                                                    # needs sage.symbolic
      3.14
      sage: y = N(3.14, digits=3); y                                                  # needs sage.rings.real_mpfr
      3.14
      sage: x == y                                                                    # needs sage.rings.real_mpfr sage.symbolic
      False
      sage: x.str(base=2)                                                             # needs sage.symbolic
      '11.001001000100'
      sage: y.str(base=2)                                                             # needs sage.rings.real_mpfr
      '11.001000111101'

  [Python]

      >>> from sage.all import *
      >>> x = N(pi, digits=Integer(3)); x                                                    # needs sage.symbolic
      3.14
      >>> y = N(RealNumber('3.14'), digits=Integer(3)); y                                                  # needs sage.rings.real_mpfr
      3.14
      >>> x == y                                                                    # needs sage.rings.real_mpfr sage.symbolic
      False
      >>> x.str(base=Integer(2))                                                             # needs sage.symbolic
      '11.001001000100'
      >>> y.str(base=Integer(2))                                                             # needs sage.rings.real_mpfr
      '11.001000111101'

  Increasing the precision of a floating point number is not allowed:

  Sage

      sage: CC(-5).n(prec=100)                                                        # needs sage.rings.real_mpfr
      Traceback (most recent call last):
      ...
      TypeError: cannot approximate to a precision of 100 bits, use at most 53 bits
      sage: n(1.3r, digits=20)                                                        # needs sage.rings.real_mpfr
      Traceback (most recent call last):
      ...
      TypeError: cannot approximate to a precision of 70 bits, use at most 53 bits
      sage: RealField(24).pi().n()                                                    # needs sage.rings.real_mpfr
      Traceback (most recent call last):
      ...
      TypeError: cannot approximate to a precision of 53 bits, use at most 24 bits

  Python

      >>> from sage.all import *
      >>> CC(-Integer(5)).n(prec=Integer(100))                                                        # needs sage.rings.real_mpfr
      Traceback (most recent call last):
      ...
      TypeError: cannot approximate to a precision of 100 bits, use at most 53 bits
      >>> n(1.3, digits=Integer(20))                                                        # needs sage.rings.real_mpfr
      Traceback (most recent call last):
      ...
      TypeError: cannot approximate to a precision of 70 bits, use at most 53 bits
      >>> RealField(Integer(24)).pi().n()                                                    # needs sage.rings.real_mpfr
      Traceback (most recent call last):
      ...
      TypeError: cannot approximate to a precision of 53 bits, use at most 24 bits

  As an exceptional case, `digits=1` usually leads to 2 digits (one significant) in the decimal output (see Issue #11647):

  Sage

      sage: # needs sage.symbolic
      sage: N(pi, digits=1)
      3.2
      sage: N(pi, digits=2)
      3.1
      sage: N(100*pi, digits=1)
      320.
      sage: N(100*pi, digits=2)
      310.

  [Python]

      >>> from sage.all import *
      >>> # needs sage.symbolic
      >>> N(pi, digits=Integer(1))
      3.2
      >>> N(pi, digits=Integer(2))
      3.1
      >>> N(Integer(100)*pi, digits=Integer(1))
      320.
      >>> N(Integer(100)*pi, digits=Integer(2))
      310.

  In the following example, `pi` and `3` are both approximated to two bits of precision and then subtracted, which kills two bits of precision:

  Sage

      sage: N(pi, prec=2)                                                             # needs sage.symbolic
      3.0
      sage: N(3, prec=2)                                                              # needs sage.rings.real_mpfr
      3.0
      sage: N(pi - 3, prec=2)                                                         # needs sage.symbolic
      0.00

  Python

      >>> from sage.all import *
      >>> N(pi, prec=Integer(2))                                                             # needs sage.symbolic
      3.0
      >>> N(Integer(3), prec=Integer(2))                                                              # needs sage.rings.real_mpfr
      3.0
      >>> N(pi - Integer(3), prec=Integer(2))                                                         # needs sage.symbolic
      0.00

sage.misc.functional.objgen(x)

  EXAMPLES:

  Sage

      sage: R, x = objgen(FractionField(QQ['x']))
      sage: R
      Fraction Field of Univariate Polynomial Ring in x over Rational Field
      sage: x
      x

  Python

      >>> from sage.all import *
      >>> R, x = objgen(FractionField(QQ['x']))
      >>> R
      Fraction Field of Univariate Polynomial Ring in x over Rational Field
      >>> x
      x

sage.misc.functional.objgens(x)

  EXAMPLES:

  Sage

      sage: R, x = objgens(PolynomialRing(QQ,3, 'x'))
      sage: R
      Multivariate Polynomial Ring in x0, x1, x2 over Rational Field
      sage: x
      (x0, x1, x2)

  Python

      >>> from sage.all import *
      >>> R, x = objgens(PolynomialRing(QQ,Integer(3), 'x'))
      >>> R
      Multivariate Polynomial Ring in x0, x1, x2 over Rational Field
      >>> x
      (x0, x1, x2)

sage.misc.functional.order(x)

  Return the order of `x`.

  If `x` is a ring or module element, this is the additive order of `x`.

  EXAMPLES:

  Sage

      sage: C = CyclicPermutationGroup(10)                                            # needs sage.groups
      sage: order(C)                                                                  # needs sage.groups
      10
      sage: F = GF(7)
      sage: order(F)
      7

  Python

      >>> from sage.all import *
      >>> C = CyclicPermutationGroup(Integer(10))                                            # needs sage.groups
      >>> order(C)                                                                  # needs sage.groups
      10
      >>> F = GF(Integer(7))
      >>> order(F)
      7

sage.misc.functional.quo(x, y, *args, **kwds)

  alias of `quotient()`.

sage.misc.functional.quotient(x, y, *args, **kwds)

  Return the quotient object x/y, e.g., a quotient of numbers or of a polynomial ring x by the ideal generated by y, etc.

  EXAMPLES:

  Sage

      sage: quotient(5, 6)
      5/6
      sage: quotient(5., 6.)
      0.833333333333333
      sage: R.<x> = ZZ[]; R
      Univariate Polynomial Ring in x over Integer Ring
      sage: I = Ideal(R, x^2 + 1)
      sage: quotient(R, I)                                                            # needs sage.libs.pari
      Univariate Quotient Polynomial Ring in xbar over Integer Ring with modulus x^2 + 1

  Python

      >>> from sage.all import *
      >>> quotient(Integer(5), Integer(6))
      5/6
      >>> quotient(RealNumber('5.'), RealNumber('6.'))
      0.833333333333333
      >>> R = ZZ['x']; (x,) = R._first_ngens(1); R
      Univariate Polynomial Ring in x over Integer Ring
      >>> I = Ideal(R, x**Integer(2) + Integer(1))
      >>> quotient(R, I)                                                            # needs sage.libs.pari
      Univariate Quotient Polynomial Ring in xbar over Integer Ring with modulus x^2 + 1

sage.misc.functional.rank(x)

  Return the rank of `x`.

  EXAMPLES:

  We compute the rank of a matrix:

  Sage

      sage: M = MatrixSpace(QQ, 3, 3)                                                 # needs sage.modules
      sage: A = M([1,2,3, 4,5,6, 7,8,9])                                              # needs sage.modules
      sage: rank(A)                                                                   # needs sage.modules
      2

  Python

      >>> from sage.all import *
      >>> M = MatrixSpace(QQ, Integer(3), Integer(3))                                                 # needs sage.modules
      >>> A = M([Integer(1),Integer(2),Integer(3), Integer(4),Integer(5),Integer(6), Integer(7),Integer(8),Integer(9)])                                              # needs sage.modules
      >>> rank(A)                                                                   # needs sage.modules
      2

  We compute the rank of an elliptic curve:

  Sage

      sage: E = EllipticCurve([0,0,1,-1,0])                                           # needs sage.schemes
      sage: rank(E)                                                                   # needs sage.schemes
      1

  [Python]

      >>> from sage.all import *
      >>> E = EllipticCurve([Integer(0),Integer(0),Integer(1),-Integer(1),Integer(0)])                                           # needs sage.schemes
      >>> rank(E)                                                                   # needs sage.schemes
      1

sage.misc.functional.regulator(x)

  Return the regulator of `x`.

  EXAMPLES:

  Sage

      sage: x = polygen(ZZ, 'x')
      sage: regulator(NumberField(x^2 - 2, 'a'))                                      # needs sage.rings.number_field
      0.881373587019543
      sage: regulator(EllipticCurve('11a'))                                           # needs sage.schemes
      1.00000000000000

  Python

      >>> from sage.all import *
      >>> x = polygen(ZZ, 'x')
      >>> regulator(NumberField(x**Integer(2) - Integer(2), 'a'))                                      # needs sage.rings.number_field
      0.881373587019543
      >>> regulator(EllipticCurve('11a'))                                           # needs sage.schemes
      1.00000000000000

sage.misc.functional.round(x, ndigits=0)

  round(number[, ndigits]) - double-precision real number

  Round a number to a given precision in decimal digits (default 0 digits). If no precision is specified this just calls the element’s .round() method.

  EXAMPLES:

  Sage

      sage: # needs sage.symbolic
      sage: round(sqrt(2), 2)
      1.41
      sage: q = round(sqrt(2), 5); q
      1.41421
      sage: type(q)
      <class 'sage.rings.real_double...RealDoubleElement...'>
      sage: q = round(sqrt(2)); q
      1
      sage: type(q)
      <class 'sage.rings.integer.Integer'>
      sage: round(pi)
      3

      sage: b = 5.4999999999999999
      sage: round(b)
      5

  Python

      >>> from sage.all import *
      >>> # needs sage.symbolic
      >>> round(sqrt(Integer(2)), Integer(2))
      1.41
      >>> q = round(sqrt(Integer(2)), Integer(5)); q
      1.41421
      >>> type(q)
      <class 'sage.rings.real_double...RealDoubleElement...'>
      >>> q = round(sqrt(Integer(2))); q
      1
      >>> type(q)
      <class 'sage.rings.integer.Integer'>
      >>> round(pi)
      3

      >>> b = RealNumber('5.4999999999999999')
      >>> round(b)
      5

  This example addresses Issue #23502:

  Sage

      sage: n = round(6); type(n)
      <class 'sage.rings.integer.Integer'>

  [Python]

      >>> from sage.all import *
      >>> n = round(Integer(6)); type(n)
      <class 'sage.rings.integer.Integer'>

  Since we use floating-point with a limited range, some roundings can’t be performed:

  Sage

      sage: round(sqrt(Integer('1'*1000)), 2)                                         # needs sage.symbolic
      +infinity

  Python

      >>> from sage.all import *
      >>> round(sqrt(Integer('1'*Integer(1000))), Integer(2))                                         # needs sage.symbolic
      +infinity

  IMPLEMENTATION: If ndigits is specified, it calls Python’s builtin round function, and converts the result to a real double field element. Otherwise, it tries the argument’s .round() method; if that fails, it reverts to the builtin round function, converted to a real double field element.

  Note

  This is currently slower than the builtin round function, since it does more work - i.e., allocating an RDF element and initializing it. To access the builtin version do `import builtins; builtins.round`.

sage.misc.functional.sqrt(x, *args, **kwds)

  INPUT:

  - `x` – a number

  - `prec` – integer (default: `None`); if `None`, returns an exact square root. Otherwise returns a numerical square root if necessary, to the given bits of precision.

  - `extend` – boolean (default: `True`); this is a placeholder, and is always ignored or passed to the `sqrt` method of `x`, since in the symbolic ring everything has a square root

  - `all` – boolean (default: `False`); if `True`, return all square roots of `self`, instead of just one

  EXAMPLES:

  Sage

      sage: sqrt(4)
      2
      sage: sqrt(4, all=True)
      [2, -2]

      sage: # needs sage.symbolic
      sage: sqrt(-1)
      I
      sage: sqrt(2)
      sqrt(2)
      sage: sqrt(2)^2
      2
      sage: sqrt(x^2)
      sqrt(x^2)

  Python

      >>> from sage.all import *
      >>> sqrt(Integer(4))
      2
      >>> sqrt(Integer(4), all=True)
      [2, -2]

      >>> # needs sage.symbolic
      >>> sqrt(-Integer(1))
      I
      >>> sqrt(Integer(2))
      sqrt(2)
      >>> sqrt(Integer(2))**Integer(2)
      2
      >>> sqrt(x**Integer(2))
      sqrt(x^2)

  For a non-symbolic square root, there are a few options. The best is to numerically approximate afterward:

  Sage

      sage: sqrt(2).n()                                                               # needs sage.symbolic
      1.41421356237310
      sage: sqrt(2).n(prec=100)                                                       # needs sage.symbolic
      1.4142135623730950488016887242

  [Python]

      >>> from sage.all import *
      >>> sqrt(Integer(2)).n()                                                               # needs sage.symbolic
      1.41421356237310
      >>> sqrt(Integer(2)).n(prec=Integer(100))                                                       # needs sage.symbolic
      1.4142135623730950488016887242

  Or one can input a numerical type:

  Sage

      sage: sqrt(2.)
      1.41421356237310
      sage: sqrt(2.000000000000000000000000)
      1.41421356237309504880169
      sage: sqrt(4.0)
      2.00000000000000

  Python

      >>> from sage.all import *
      >>> sqrt(RealNumber('2.'))
      1.41421356237310
      >>> sqrt(RealNumber('2.000000000000000000000000'))
      1.41421356237309504880169
      >>> sqrt(RealNumber('4.0'))
      2.00000000000000

  To prevent automatic evaluation, one can use the `hold` parameter after coercing to the symbolic ring:

  Sage

      sage: sqrt(SR(4), hold=True)                                                    # needs sage.symbolic
      sqrt(4)
      sage: sqrt(4, hold=True)
      Traceback (most recent call last):
      ...
      TypeError: ..._do_sqrt() got an unexpected keyword argument 'hold'

  [Python]

      >>> from sage.all import *
      >>> sqrt(SR(Integer(4)), hold=True)                                                    # needs sage.symbolic
      sqrt(4)
      >>> sqrt(Integer(4), hold=True)
      Traceback (most recent call last):
      ...
      TypeError: ..._do_sqrt() got an unexpected keyword argument 'hold'

  This illustrates that the bug reported in Issue #6171 has been fixed:

  Sage

      sage: a = 1.1
      sage: a.sqrt(prec=100)  # this is supposed to fail
      Traceback (most recent call last):
      ...
      TypeError: ...sqrt() got an unexpected keyword argument 'prec'
      sage: sqrt(a, prec=100)                                                         # needs sage.rings.real_mpfr
      1.0488088481701515469914535137
      sage: sqrt(4.00, prec=250)                                                      # needs sage.rings.real_mpfr
      2.0000000000000000000000000000000000000000000000000000000000000000000000000

  Python

      >>> from sage.all import *
      >>> a = RealNumber('1.1')
      >>> a.sqrt(prec=Integer(100))  # this is supposed to fail
      Traceback (most recent call last):
      ...
      TypeError: ...sqrt() got an unexpected keyword argument 'prec'
      >>> sqrt(a, prec=Integer(100))                                                         # needs sage.rings.real_mpfr
      1.0488088481701515469914535137
      >>> sqrt(RealNumber('4.00'), prec=Integer(250))                                                      # needs sage.rings.real_mpfr
      2.0000000000000000000000000000000000000000000000000000000000000000000000000

  One can use numpy input as well:

  Sage

      sage: import numpy                                                              # needs numpy
      sage: a = numpy.arange(2,5)                                                     # needs numpy
      sage: sqrt(a)                                                                   # needs numpy
      array([1.41421356, 1.73205081, 2.        ])

  [Python]

      >>> from sage.all import *
      >>> import numpy                                                              # needs numpy
      >>> a = numpy.arange(Integer(2),Integer(5))                                                     # needs numpy
      >>> sqrt(a)                                                                   # needs numpy
      array([1.41421356, 1.73205081, 2.        ])

sage.misc.functional.squarefree_part(x)

  Return the square free part of `x`, i.e., a divisor \(z\) such that \(x = z y^2\), for a perfect square \(y^2\).

  EXAMPLES:

  Sage

      sage: squarefree_part(100)
      1
      sage: squarefree_part(12)
      3
      sage: squarefree_part(10)
      10
      sage: squarefree_part(216r) # see #8976
      6

  Python

      >>> from sage.all import *
      >>> squarefree_part(Integer(100))
      1
      >>> squarefree_part(Integer(12))
      3
      >>> squarefree_part(Integer(10))
      10
      >>> squarefree_part(216) # see #8976
      6

  Sage

      sage: x = QQ['x'].0
      sage: S = squarefree_part(-9*x*(x-6)^7*(x-3)^2); S
      -9*x^2 + 54*x
      sage: S.factor()                                                                # needs sage.libs.pari
      (-9) * (x - 6) * x

  [Python]

      >>> from sage.all import *
      >>> x = QQ['x'].gen(0)
      >>> S = squarefree_part(-Integer(9)*x*(x-Integer(6))**Integer(7)*(x-Integer(3))**Integer(2)); S
      -9*x^2 + 54*x
      >>> S.factor()                                                                # needs sage.libs.pari
      (-9) * (x - 6) * x

  Sage

      sage: f = (x^3 + x + 1)^3*(x-1); f
      x^10 - x^9 + 3*x^8 + 3*x^5 - 2*x^4 - x^3 - 2*x - 1
      sage: g = squarefree_part(f); g
      x^4 - x^3 + x^2 - 1
      sage: g.factor()                                                                # needs sage.libs.pari
      (x - 1) * (x^3 + x + 1)

  Python

      >>> from sage.all import *
      >>> f = (x**Integer(3) + x + Integer(1))**Integer(3)*(x-Integer(1)); f
      x^10 - x^9 + 3*x^8 + 3*x^5 - 2*x^4 - x^3 - 2*x - 1
      >>> g = squarefree_part(f); g
      x^4 - x^3 + x^2 - 1
      >>> g.factor()                                                                # needs sage.libs.pari
      (x - 1) * (x^3 + x + 1)

sage.misc.functional.symbolic_prod(expression, *args, **kwds)

  Return the symbolic product \(\prod_{v = a}^b expression\) with respect to the variable \(v\) with endpoints \(a\) and \(b\).

  INPUT:

  - `expression` – a symbolic expression

  - `v` – a variable or variable name

  - `a` – lower endpoint of the product

  - `b` – upper endpoint of the prduct

  - `algorithm` – (default: `'maxima'`) one of

    - `'maxima'` – use Maxima (the default)

    - `'giac'` – (optional) use Giac

    - `'sympy'` – use SymPy

  - `hold` – boolean (default: `False`); if `True` don’t evaluate

  EXAMPLES:

  Sage

      sage: # needs sage.symbolic
      sage: i, k, n = var('i,k,n')
      sage: product(k, k, 1, n)
      factorial(n)
      sage: product(x + i*(i+1)/2, i, 1, 4)
      x^4 + 20*x^3 + 127*x^2 + 288*x + 180
      sage: product(i^2, i, 1, 7)
      25401600
      sage: f = function('f')
      sage: product(f(i), i, 1, 7)
      f(7)*f(6)*f(5)*f(4)*f(3)*f(2)*f(1)
      sage: product(f(i), i, 1, n)
      product(f(i), i, 1, n)
      sage: assume(k>0)
      sage: product(integrate(x^k, x, 0, 1), k, 1, n)
      1/factorial(n + 1)
      sage: product(f(i), i, 1, n).log().log_expand()
      sum(log(f(i)), i, 1, n)

  Python

      >>> from sage.all import *
      >>> # needs sage.symbolic
      >>> i, k, n = var('i,k,n')
      >>> product(k, k, Integer(1), n)
      factorial(n)
      >>> product(x + i*(i+Integer(1))/Integer(2), i, Integer(1), Integer(4))
      x^4 + 20*x^3 + 127*x^2 + 288*x + 180
      >>> product(i**Integer(2), i, Integer(1), Integer(7))
      25401600
      >>> f = function('f')
      >>> product(f(i), i, Integer(1), Integer(7))
      f(7)*f(6)*f(5)*f(4)*f(3)*f(2)*f(1)
      >>> product(f(i), i, Integer(1), n)
      product(f(i), i, 1, n)
      >>> assume(k>Integer(0))
      >>> product(integrate(x**k, x, Integer(0), Integer(1)), k, Integer(1), n)
      1/factorial(n + 1)
      >>> product(f(i), i, Integer(1), n).log().log_expand()
      sum(log(f(i)), i, 1, n)

sage.misc.functional.symbolic_sum(expression, *args, **kwds)

  Return the symbolic sum \(\sum_{v = a}^b expression\) with respect to the variable \(v\) with endpoints \(a\) and \(b\).

  INPUT:

  - `expression` – a symbolic expression

  - `v` – a variable or variable name

  - `a` – lower endpoint of the sum

  - `b` – upper endpoint of the sum

  - `algorithm` – (default: `'maxima'`) one of

    - `'maxima'` – use Maxima (the default)

    - `'maple'` – (optional) use Maple

    - `'mathematica'` – (optional) use Mathematica

    - `'giac'` – (optional) use Giac

    - `'sympy'` – use SymPy

  EXAMPLES:

  Sage

      sage: k, n = var('k,n')                                                         # needs sage.symbolic
      sage: sum(k, k, 1, n).factor()                                                  # needs sage.symbolic
      1/2*(n + 1)*n

  Python

      >>> from sage.all import *
      >>> k, n = var('k,n')                                                         # needs sage.symbolic
      >>> sum(k, k, Integer(1), n).factor()                                                  # needs sage.symbolic
      1/2*(n + 1)*n

  Sage

      sage: sum(1/k^4, k, 1, oo)                                                      # needs sage.symbolic
      1/90*pi^4

  [Python]

      >>> from sage.all import *
      >>> sum(Integer(1)/k**Integer(4), k, Integer(1), oo)                                                      # needs sage.symbolic
      1/90*pi^4

  Sage

      sage: sum(1/k^5, k, 1, oo)                                                      # needs sage.symbolic
      zeta(5)

  Python

      >>> from sage.all import *
      >>> sum(Integer(1)/k**Integer(5), k, Integer(1), oo)                                                      # needs sage.symbolic
      zeta(5)

  Warning

  This function only works with symbolic expressions. To sum any other objects like list elements or function return values, please use python summation, see http://docs.python.org/library/functions.html#sum

  In particular, this does not work:

  Sage

      sage: n = var('n')                                                          # needs sage.symbolic
      sage: mylist = [1,2,3,4,5]
      sage: sum(mylist[n], n, 0, 3)                                               # needs sage.symbolic
      Traceback (most recent call last):
      ...
      TypeError: unable to convert n to an integer

  Python

      >>> from sage.all import *
      >>> n = var('n')                                                          # needs sage.symbolic
      >>> mylist = [Integer(1),Integer(2),Integer(3),Integer(4),Integer(5)]
      >>> sum(mylist[n], n, Integer(0), Integer(3))                                               # needs sage.symbolic
      Traceback (most recent call last):
      ...
      TypeError: unable to convert n to an integer

  Use python `sum()` instead:

  Sage

      sage: sum(mylist[n] for n in range(4))
      10

  [Python]

      >>> from sage.all import *
      >>> sum(mylist[n] for n in range(Integer(4)))
      10

  Also, only a limited number of functions are recognized in symbolic sums:

  Sage

      sage: sum(valuation(n, 2), n, 1, 5)                                         # needs sage.symbolic
      Traceback (most recent call last):
      ...
      TypeError: unable to convert n to an integer

  Python

      >>> from sage.all import *
      >>> sum(valuation(n, Integer(2)), n, Integer(1), Integer(5))                                         # needs sage.symbolic
      Traceback (most recent call last):
      ...
      TypeError: unable to convert n to an integer

  Again, use python `sum()`:

  Sage

      sage: sum(valuation(n + 1, 2) for n in range(5))
      3

  [Python]

      >>> from sage.all import *
      >>> sum(valuation(n + Integer(1), Integer(2)) for n in range(Integer(5)))
      3

  (now back to the Sage `sum` examples)

  A well known binomial identity:

  Sage

      sage: sum(binomial(n, k), k, 0, n)                                              # needs sage.symbolic
      2^n

  Python

      >>> from sage.all import *
      >>> sum(binomial(n, k), k, Integer(0), n)                                              # needs sage.symbolic
      2^n

  The binomial theorem:

  Sage

      sage: x, y = var('x, y')                                                        # needs sage.symbolic
      sage: sum(binomial(n, k) * x^k * y^(n-k), k, 0, n)                              # needs sage.symbolic
      (x + y)^n

  [Python]

      >>> from sage.all import *
      >>> x, y = var('x, y')                                                        # needs sage.symbolic
      >>> sum(binomial(n, k) * x**k * y**(n-k), k, Integer(0), n)                              # needs sage.symbolic
      (x + y)^n

  Sage

      sage: sum(k * binomial(n, k), k, 1, n)                                          # needs sage.symbolic
      2^(n - 1)*n

  Python

      >>> from sage.all import *
      >>> sum(k * binomial(n, k), k, Integer(1), n)                                          # needs sage.symbolic
      2^(n - 1)*n

  Sage

      sage: sum((-1)^k * binomial(n, k), k, 0, n)                                     # needs sage.symbolic
      0

  [Python]

      >>> from sage.all import *
      >>> sum((-Integer(1))**k * binomial(n, k), k, Integer(0), n)                                     # needs sage.symbolic
      0

  Sage

      sage: sum(2^(-k)/(k*(k+1)), k, 1, oo)                                           # needs sage.symbolic
      -log(2) + 1

  Python

      >>> from sage.all import *
      >>> sum(Integer(2)**(-k)/(k*(k+Integer(1))), k, Integer(1), oo)                                           # needs sage.symbolic
      -log(2) + 1

  Another binomial identity (Issue #7952):

  Sage

      sage: t, k, i = var('t,k,i')                                                    # needs sage.symbolic
      sage: sum(binomial(i + t, t), i, 0, k)                                          # needs sage.symbolic
      binomial(k + t + 1, t + 1)

  [Python]

      >>> from sage.all import *
      >>> t, k, i = var('t,k,i')                                                    # needs sage.symbolic
      >>> sum(binomial(i + t, t), i, Integer(0), k)                                          # needs sage.symbolic
      binomial(k + t + 1, t + 1)

  Summing a hypergeometric term:

  Sage

      sage: sum(binomial(n, k) * factorial(k) / factorial(n+1+k), k, 0, n)            # needs sage.symbolic
      1/2*sqrt(pi)/factorial(n + 1/2)

  Python

      >>> from sage.all import *
      >>> sum(binomial(n, k) * factorial(k) / factorial(n+Integer(1)+k), k, Integer(0), n)            # needs sage.symbolic
      1/2*sqrt(pi)/factorial(n + 1/2)

  We check a well known identity:

  Sage

      sage: bool(sum(k^3, k, 1, n) == sum(k, k, 1, n)^2)                              # needs sage.symbolic
      True

  [Python]

      >>> from sage.all import *
      >>> bool(sum(k**Integer(3), k, Integer(1), n) == sum(k, k, Integer(1), n)**Integer(2))                              # needs sage.symbolic
      True

  A geometric sum:

  Sage

      sage: a, q = var('a, q')                                                        # needs sage.symbolic
      sage: sum(a*q^k, k, 0, n)                                                       # needs sage.symbolic
      (a*q^(n + 1) - a)/(q - 1)

  Python

      >>> from sage.all import *
      >>> a, q = var('a, q')                                                        # needs sage.symbolic
      >>> sum(a*q**k, k, Integer(0), n)                                                       # needs sage.symbolic
      (a*q^(n + 1) - a)/(q - 1)

  The geometric series:

  Sage

      sage: assume(abs(q) < 1)                                                        # needs sage.symbolic
      sage: sum(a * q^k, k, 0, oo)                                                    # needs sage.symbolic
      -a/(q - 1)

  [Python]

      >>> from sage.all import *
      >>> assume(abs(q) < Integer(1))                                                        # needs sage.symbolic
      >>> sum(a * q**k, k, Integer(0), oo)                                                    # needs sage.symbolic
      -a/(q - 1)

  A divergent geometric series. Don’t forget to forget your assumptions:

  Sage

      sage: forget()                                                                  # needs sage.symbolic
      sage: assume(q > 1)                                                             # needs sage.symbolic
      sage: sum(a * q^k, k, 0, oo)                                                    # needs sage.symbolic
      Traceback (most recent call last):
      ...
      ValueError: Sum is divergent.

  Python

      >>> from sage.all import *
      >>> forget()                                                                  # needs sage.symbolic
      >>> assume(q > Integer(1))                                                             # needs sage.symbolic
      >>> sum(a * q**k, k, Integer(0), oo)                                                    # needs sage.symbolic
      Traceback (most recent call last):
      ...
      ValueError: Sum is divergent.

  This summation only Mathematica can perform:

  Sage

      sage: sum(1/(1+k^2), k, -oo, oo, algorithm='mathematica')       # optional - mathematica, needs sage.symbolic
      pi*coth(pi)

  [Python]

      >>> from sage.all import *
      >>> sum(Integer(1)/(Integer(1)+k**Integer(2)), k, -oo, oo, algorithm='mathematica')       # optional - mathematica, needs sage.symbolic
      pi*coth(pi)

  Use Maple as a backend for summation:

  Sage

      sage: sum(binomial(n, k) * x^k, k, 0, n, algorithm='maple')     # optional - maple, needs sage.symbolic
      (x + 1)^n

  Python

      >>> from sage.all import *
      >>> sum(binomial(n, k) * x**k, k, Integer(0), n, algorithm='maple')     # optional - maple, needs sage.symbolic
      (x + 1)^n

  Python ints should work as limits of summation (Issue #9393):

  Sage

      sage: sum(x, x, 1r, 5r)                                                         # needs sage.symbolic
      15

  [Python]

      >>> from sage.all import *
      >>> sum(x, x, 1, 5)                                                         # needs sage.symbolic
      15

  Note

  1. Sage can currently only understand a subset of the output of Maxima, Maple and Mathematica, so even if the chosen backend can perform the summation the result might not be convertible into a Sage expression.

sage.misc.functional.transpose(x)

  Return the transpose of `x`.

  EXAMPLES:

  Sage

      sage: M = MatrixSpace(QQ, 3, 3)                                                 # needs sage.modules
      sage: A = M([1,2,3, 4,5,6, 7,8,9])                                              # needs sage.modules
      sage: transpose(A)                                                              # needs sage.modules
      [1 4 7]
      [2 5 8]
      [3 6 9]

  Python

      >>> from sage.all import *
      >>> M = MatrixSpace(QQ, Integer(3), Integer(3))                                                 # needs sage.modules
      >>> A = M([Integer(1),Integer(2),Integer(3), Integer(4),Integer(5),Integer(6), Integer(7),Integer(8),Integer(9)])                                              # needs sage.modules
      >>> transpose(A)                                                              # needs sage.modules
      [1 4 7]
      [2 5 8]
      [3 6 9]

sage.misc.functional.xinterval(a, b)

  Iterator over the integers between \(a\) and \(b\), inclusive.

  EXAMPLES:

  Sage

      sage: I = xinterval(2,5); I
      range(2, 6)
      sage: 5 in I
      True
      sage: 6 in I
      False

  Python

      >>> from sage.all import *
      >>> I = xinterval(Integer(2),Integer(5)); I
      range(2, 6)
      >>> Integer(5) in I
      True
      >>> Integer(6) in I
      False