Power Series Ring¶

This module provides tools for creating and performing arithmetic on univariate power series. It supports rings over the integer ZZ and rational QQ domains.

A power series is represented as a finite sequence of coefficients up to a specified precision. For a ring with precision \(prec\), a series is represented by its terms up to the degree prec - 1. Arithmetic operations that would result in terms of degree \(prec\) or higher are truncated, and this is denoted using the \(O(x**prec)\) notation.

A key feature of this implementation is its handling of precision. If an operation performed using two polynomials results in a polynomial whose degree is strictly less than the ring’s precision, the result is returned as an exact polynomial without any truncation. This ensures that calculations with finite polynomials are mathematically exact, preserving accuracy while leveraging the series framework.

The architecture includes two backends: a pure Python implementation and a high-performance backend using the FLINT library. The system automatically selects the FLINT backend if it is available, falling back to the Python implementation otherwise. The primary factory function, power_series_ring(), handles this selection transparently.

To create a power series ring, use the power_series_ring() function, specifying a domain and the desired precision. Ring elements can then be created by passing a list of coefficients.

For example, let’s create a ring with precision 8 over the integers:

>>> from sympy.polys.series import power_series_ring
>>> from sympy import ZZ
>>> R = power_series_ring(ZZ, prec=8)
>>> f = R([1, 2, 3])
>>> g = R([4, 1])

Arithmetic operations are performed using the ring’s methods. The print method provides a readable string representation.

>>> R.print(R.add(f, g))
5 + 3*x + 3*x**2
>>> R.print(R.multiply(f, g))
4 + 9*x + 14*x**2 + 3*x**3

As shown below, when the result of an operation is a polynomial with a degree less than the ring’s precision, the exact result is returned.

>>> p = R([2, -3])
>>> q = R([0, 7, 6, 1])
>>> R.print(R.multiply(p, q))
14*x - 9*x**2 - 16*x**3 - 3*x**4

However, if an operation produces a result that exceeds the precision threshold, it is automatically truncated.

>>> r = R([1, 2, 3, 4, 5, 6, 7, 8])
>>> s = R([0, 1, 1])
>>> R.print(R.multiply(r, s))
x + 3*x**2 + 5*x**3 + 7*x**4 + 9*x**5 + 11*x**6 + 13*x**7 + O(x**8)

sympy.polys.series.power_series_ring( K: Domain[Er], prec: int = 6, ) → PowerSeriesRingProto[TSeries[Er], Er][source]¶

Create a power series ring over the given domain.

Parameters:

domain : Domain

The ground domain for the power series ring. Must be ZZ or QQ.

prec : int, optional

The default precision for power series operations. Default is 6.

Returns:

PowerSeriesRingZZ | PowerSeriesRingQQ

A power series ring instance. The actual implementation (Flint or Python) depends on whether python-flint is available.

Examples

>>> from sympy import QQ
>>> from sympy.polys.series import power_series_ring
>>> R_QQ = power_series_ring(QQ, 5)
>>> inv = R_QQ.inverse(R_QQ([1, 2, (3, 4), (5, 6)]))
>>> R_QQ.print(inv)
1 - 2*x + 13/4*x**2 - 35/6*x**3 + 523/48*x**4 + O(x**5)

class sympy.polys.series.ring.TSeries¶

Protocols for Power Series Rings¶

class sympy.polys.series.base.PowerSeriesRingProto(prec: int = 6, /)[source]¶: A protocol for a power series ring.

class TSeries¶

Python Implementation¶

class sympy.polys.series.ringpython.PythonPowerSeriesRingZZ(prec: int = 6)[source]¶

Python implementation of power series ring over integers ZZ.

This class provides comprehensive power series operations over the integer ring, supporting both series manipulations with precision handling and truncation.

Parameters:: prec : int, optional

The default precision for power series operations. Default is 6.

Examples

>>> from sympy.polys.series.ringpython import PythonPowerSeriesRingZZ
>>> R = PythonPowerSeriesRingZZ()
>>> s = R([1, 2, 3])  # 1 + 2*x + 3*x^2
>>> R.print(s)
1 + 2*x + 3*x**2

>>> s_pow = R.pow_int(s, 2)  # Square the series
>>> R.print(s_pow)
1 + 4*x + 10*x**2 + 12*x**3 + 9*x**4

>>> s_inv = R.inverse(R([1, 1]))  # Inverse of 1 + x
>>> R.print(s_inv)
1 - x + x**2 - x**3 + x**4 - x**5 + O(x**6)

Note

The recommended way to create a power series ring is using the factory function:

>>> from sympy.polys.series import power_series_ring
>>> from sympy import ZZ
>>> R = power_series_ring(ZZ, prec=6)

This function automatically uses the Flint implementation if available for better performance, falling back to the Python implementation otherwise.

add( s1: USeries[MPZ], s2: USeries[MPZ], ) → USeries[MPZ][source]¶: Add two power series.

compose( s1: USeries[MPZ], s2: USeries[MPZ], ) → USeries[MPZ][source]¶: Compose two power series, \(s1(s2)\).

differentiate( s: USeries[MPZ], ) → USeries[MPZ][source]¶: Compute the derivative of a power series.

divide( s1: USeries[MPZ], s2: USeries[MPZ], ) → USeries[MPZ][source]¶: Divide two power series.

property domain: Domain[int]¶: Return the ground domain of the power series ring.

equal( s1: USeries[MPZ], s2: USeries[MPZ], ) → bool | None[source]¶: Check if two power series are equal up to their minimum precision.

equal_repr( s1: USeries[MPZ], s2: USeries[MPZ], ) → bool[source]¶: Check if two power series have the same representation.

from_list( coeffs: list[MPZ], prec: int | None = None, ) → USeries[MPZ][source]¶

Create a power series from a list of ground coefficients.

If \(prec\) is not specified, it defaults to the ring’s precision.

inverse( s: USeries[MPZ], ) → USeries[MPZ][source]¶: Compute the multiplicative inverse of a power series.

multiply( s1: USeries[MPZ], s2: USeries[MPZ], ) → USeries[MPZ][source]¶: Multiply two power series.

multiply_ground( s: USeries[MPZ], n: MPZ, ) → USeries[MPZ][source]¶: Multiply a power series by a ground element.

negative( s: USeries[MPZ], ) → USeries[MPZ][source]¶: Return the unary negative of a power series.

positive( s: USeries[MPZ], ) → USeries[MPZ][source]¶: Return the unary positive of a power series, adjusted to the ring’s precision.

pow_int( s: USeries[MPZ], n: int, ) → USeries[MPZ][source]¶: Raise a power series to a non-negative integer power.

property prec: int¶: Return the ring’s precision.

pretty( s: USeries[MPZ], ) → str[source]¶: Return a pretty-printed string representation of a power series.

print( s: USeries[MPZ], ) → None[source]¶: Print a pretty-printed representation of a power series.

reversion( s: USeries[MPZ], ) → USeries[MPZ][source]¶: Compute the compositional inverse of a power series.

square( s: USeries[MPZ], ) → USeries[MPZ][source]¶: Compute the square of a power series.

subtract( s1: USeries[MPZ], s2: USeries[MPZ], ) → USeries[MPZ][source]¶: Subtract two power series.

to_list( s: USeries[MPZ], ) → list[MPZ][source]¶: Returns the list of series coefficients.

truncate( s: USeries[MPZ], n: int, ) → USeries[MPZ][source]¶: Truncate a power series to \(n\) terms.

class sympy.polys.series.ringpython.PythonPowerSeriesRingQQ(prec: int = 6)[source]¶

Python implementation of power series ring over rational field QQ.

This class provides comprehensive power series operations over the rational field, supporting series manipulations with precision handling and truncation. It extends the integer ring functionality with support for rational coefficients and integration.

Parameters:: prec : int, optional

The default precision for power series operations. Default is 6.

Examples

>>> from sympy.polys.series.ringpython import PythonPowerSeriesRingQQ
>>> R = PythonPowerSeriesRingQQ()
>>> s = R([1, (1, 2), (1, 3)])  # 1 + x/2 + x^2/3
>>> R.print(s)
1 + 1/2*x + 1/3*x**2

>>> s_int = R.integrate(s)  # Integration
>>> R.print(s_int)
x + 1/4*x**2 + 1/9*x**3

>>> s_inv = R.inverse(R([1, (1, 2)]))  # Inverse of 1 + x/2
>>> R.print(s_inv)
1 - 1/2*x + 1/4*x**2 - 1/8*x**3 + 1/16*x**4 - 1/32*x**5 + O(x**6)

Note

The recommended way to create a power series ring is using the factory function:

>>> from sympy.polys.series import power_series_ring
>>> from sympy import QQ
>>> R = power_series_ring(QQ, prec=6)

This function automatically uses the Flint implementation if available for better performance, falling back to the Python implementation otherwise.

add( s1: USeries[MPQ], s2: USeries[MPQ], ) → USeries[MPQ][source]¶: Add two power series.

compose( s1: USeries[MPQ], s2: USeries[MPQ], ) → USeries[MPQ][source]¶: Compose two power series, \(s1(s2)\).

differentiate( s: USeries[MPQ], ) → USeries[MPQ][source]¶: Compute the derivative of a power series.

divide( s1: USeries[MPQ], s2: USeries[MPQ], ) → USeries[MPQ][source]¶: Divide two power series.

property domain: Domain[PythonMPQ]¶: Return the ground domain of the power series ring.

equal( s1: USeries[MPQ], s2: USeries[MPQ], ) → bool | None[source]¶: Check if two power series are equal up to their minimum precision.

equal_repr( s1: USeries[MPQ], s2: USeries[MPQ], ) → bool[source]¶: Check if two power series have the same representation.

from_list( coeffs: list[MPQ], prec: int | None = None, ) → USeries[MPQ][source]¶

Create a power series from a list of ground coefficients.

If \(prec\) is not specified, it defaults to the ring’s precision.

integrate( s: USeries[MPQ], ) → USeries[MPQ][source]¶: Compute the integral of a power series.

inverse( s: USeries[MPQ], ) → USeries[MPQ][source]¶: Compute the multiplicative inverse of a power series.

multiply( s1: USeries[MPQ], s2: USeries[MPQ], ) → USeries[MPQ][source]¶: Multiply two power series.

multiply_ground( s: USeries[MPQ], n: MPQ, ) → USeries[MPQ][source]¶: Multiply a power series by a ground element.

negative( s: USeries[MPQ], ) → USeries[MPQ][source]¶: Return the unary negative of a power series.

positive( s: USeries[MPQ], ) → USeries[MPQ][source]¶: Return the unary positive of a power series, adjusted to the ring’s precision.

pow_int( s: USeries[MPQ], n: int, ) → USeries[MPQ][source]¶: Raise a power series to a non-negative integer power.

property prec: int¶: Return the ring’s precision.

pretty( s: USeries[MPQ], ) → str[source]¶: Return a pretty-printed string representation of a power series.

print( s: USeries[MPQ], ) → None[source]¶: Print a pretty-printed representation of a power series.

reversion( s: USeries[MPQ], ) → USeries[MPQ][source]¶: Compute the compositional inverse of a power series.

square( s: USeries[MPQ], ) → USeries[MPQ][source]¶: Compute the square of a power series.

subtract( s1: USeries[MPQ], s2: USeries[MPQ], ) → USeries[MPQ][source]¶: Subtract two power series.

to_list( s: USeries[MPQ], ) → list[MPQ][source]¶: Return the list of series coefficients.

truncate( s: USeries[MPQ], n: int, ) → USeries[MPQ][source]¶: Truncate a power series to \(n\) terms.

class sympy.polys.series.ringpython.USeries¶

class sympy.polys.series.ringpython.MPZ¶

class sympy.polys.series.ringpython.MPQ[source]¶

Flint Implementation¶

class sympy.polys.series.ringflint.FlintPowerSeriesRingZZ(prec: int = 6)[source]¶

Flint implementation of power series ring over integers ZZ.

This class provides high-performance power series operations over the integer ring, leveraging the FLINT library for optimized arithmetic and series manipulations precision handling and truncation.

Parameters:: prec : int, optional

The default precision for power series operations. Default is 6.

Examples

>>> from sympy.polys.series.ringflint import FlintPowerSeriesRingZZ
>>> R = FlintPowerSeriesRingZZ()
>>> s = R([1, 2, 3])  # 1 + 2*x + 3*x^2
>>> R.print(s)
1 + 2*x + 3*x**2

>>> s_pow = R.pow_int(s, 2)  # Square the series
>>> R.print(s_pow)
1 + 4*x + 10*x**2 + 12*x**3 + 9*x**4

>>> s_inv = R.inverse(R([1, 1]))  # Inverse of 1 + x
>>> R.print(s_inv)
1 - x + x**2 - x**3 + x**4 - x**5 + O(x**6)

Note

The recommended way to create a power series ring is using the factory function:

>>> from sympy.polys.series import power_series_ring
>>> from sympy.polys.domains import ZZ
>>> R = power_series_ring(ZZ, prec=6)

This function automatically uses the Flint implementation if available for better performance, falling back to the Python implementation otherwise.

add( s1: None, s2: None, ) → None[source]¶: Add two power series.

compose( s1: None, s2: None, ) → None[source]¶: Compose two power series, \(s1(s2)\).

differentiate( s: None, ) → None[source]¶: Compute the derivative of a power series.

divide( s1: None, s2: None, ) → None[source]¶: Divide two power series.

property domain: Domain[int]¶: Return the ground domain of the power series ring.

equal( s1: None, s2: None, ) → bool | None[source]¶: Check if two power series are equal up to their minimum precision.

equal_repr( s1: None, s2: None, ) → bool[source]¶: Check if two power series have the same representation.

from_list( coeffs: list[int], prec: int | None = None, ) → None[source]¶

Create a power series from a list of ground coefficients.

If \(prec\) is not specified, it defaults to the ring’s precision.

inverse(s: None) → None[source]¶: Compute the multiplicative inverse of a power series.

multiply( s1: None, s2: None, ) → None[source]¶: Multiply two power series.

multiply_ground( s: None, n: int, ) → None[source]¶: Multiply a power series by a ground element.

negative(s: None) → None[source]¶: Return the unary negative of a power series.

positive(s: None) → None[source]¶: Return the unary positive of a power series, adjusted to the ring’s precision.

pow_int( s: None, n: int, ) → None[source]¶: Raise a power series to a non-negative integer power.

property prec: int¶: Return the ring’s precision.

pretty(s: None) → str[source]¶: Return a pretty-printed string representation of a power series.

print(s: None) → None[source]¶: Print a pretty-printed representation of a power series.

reversion(s: None) → None[source]¶: Compute the compositional inverse of a power series.

square(s: None) → None[source]¶: Compute the square of a power series.

subtract( s1: None, s2: None, ) → None[source]¶: Subtract two power series.

to_list( s: None, ) → list[int][source]¶: Returns the list of series coefficients.

truncate( s: None, n: int, ) → None[source]¶: Truncate a power series to \(n\) terms.

class sympy.polys.series.ringflint.FlintPowerSeriesRingQQ(prec: int = 6)[source]¶

Flint implementation of power series ring over rational field QQ.

This class provides high-performance power series operations over the rational field, leveraging the FLINT library for optimized arithmetic and series manipulations with precision handling and truncation. It extends the integer ring functionality with support for rational coefficients and integration.

Parameters:: prec : int, optional

The default precision for power series operations. Default is 6.

Examples

>>> from sympy.polys.series.ringflint import FlintPowerSeriesRingQQ
>>> R = FlintPowerSeriesRingQQ()
>>> s = R([1, (1, 2), (1, 3)])  # 1 + x/2 + x^2/3
>>> R.print(s)
1 + 1/2*x + 1/3*x**2

>>> s_int = R.integrate(s)  # Integration
>>> R.print(s_int)
x + 1/4*x**2 + 1/9*x**3

>>> s_inv = R.inverse(R([1, (1, 2)]))  # Inverse of 1 + x/2
>>> R.print(s_inv)
1 - 1/2*x + 1/4*x**2 - 1/8*x**3 + 1/16*x**4 - 1/32*x**5 + O(x**6)

Note

The recommended way to create a power series ring is using the factory function:

>>> from sympy.polys.series import power_series_ring
>>> from sympy.polys.domains import QQ
>>> R = power_series_ring(QQ, prec=6)

This function automatically uses the Flint implementation if available for better performance, falling back to the Python implementation otherwise.

add( s1: None, s2: None, ) → None[source]¶: Add two power series.

compose( s1: None, s2: None, ) → None[source]¶: Compose two power series, \(s1(s2)\).

differentiate( s: None, ) → None[source]¶: Compute the derivative of a power series.

divide( s1: None, s2: None, ) → None[source]¶: Divide two power series.

property domain: Domain[PythonMPQ]¶: Return the ground domain of the power series ring.

equal( s1: None, s2: None, ) → bool | None[source]¶: Check if two power series are equal up to their minimum precision.

equal_repr( s1: None, s2: None, ) → bool[source]¶: Check if two power series have the same representation.

from_list( coeffs: list[PythonMPQ], prec: int | None = None, ) → None[source]¶

Create a power series from a list of ground coefficients.

If \(prec\) is not specified, it defaults to the ring’s precision.

integrate(s: None) → None[source]¶: Compute the integral of a power series.

inverse(s: None) → None[source]¶: Compute the multiplicative inverse of a power series.

multiply( s1: None, s2: None, ) → None[source]¶: Multiply two power series.

multiply_ground( s: None, n: PythonMPQ, ) → None[source]¶: Multiply a power series by a ground element.

negative(s: None) → None[source]¶: Return the unary negative of a power series.

positive(s: None) → None[source]¶: Return the unary positive of a power series, adjusted to the ring’s precision.

pow_int( s: None, n: int, ) → None[source]¶: Raise a power series to a non-negative integer power.

property prec: int¶: Return the ring’s precision.

pretty(s: None) → str[source]¶: Return a pretty-printed string representation of a power series.

print(s: None) → None[source]¶: Print a pretty-printed representation of a power series.

reversion(s: None) → None[source]¶: Compute the compositional inverse of a power series.

square(s: None) → None[source]¶: Compute the square of a power series.

subtract( s1: None, s2: None, ) → None[source]¶: Subtract two power series.

to_list( s: None, ) → list[PythonMPQ][source]¶: Returns the list of series coefficients.

truncate( s: None, n: int, ) → None[source]¶: Truncate a power series to \(n\) terms.