a RG5d @sdZddlmZmZddlmZddlmZddlm Z ddl m Z ddl m Z ddlmZdd lmZdd lmZdd lmZdd lmZdd lmZddlmZmZddlmZddlm Z m!Z!m"Z"ddl#m$Z$m%Z%m&Z&ddZ'GdddZ(Gddde(Z)Gddde(eZ*ddZ+d.ddZ,Gdd d eZ-Gd!d"d"e-Z.Gd#d$d$Z/Gd%d&d&e/Z0Gd'd(d(e0Z1Gd)d*d*Z2d/d,d-Z3d+S)0aRModules in number fields. The classes defined here allow us to work with finitely generated, free modules, whose generators are algebraic numbers. There is an abstract base class called :py:class:`~.Module`, which has two concrete subclasses, :py:class:`~.PowerBasis` and :py:class:`~.Submodule`. Every module is defined by its basis, or set of generators: * For a :py:class:`~.PowerBasis`, the generators are the first $n$ powers (starting with the zeroth) of an algebraic integer $\theta$ of degree $n$. The :py:class:`~.PowerBasis` is constructed by passing either the minimal polynomial of $\theta$, or an :py:class:`~.AlgebraicField` having $\theta$ as its primitive element. * For a :py:class:`~.Submodule`, the generators are a set of $\mathbb{Q}$-linear combinations of the generators of another module. That other module is then the "parent" of the :py:class:`~.Submodule`. The coefficients of the $\mathbb{Q}$-linear combinations may be given by an integer matrix, and a positive integer denominator. Each column of the matrix defines a generator. >>> from sympy.polys import Poly, cyclotomic_poly, ZZ >>> from sympy.abc import x >>> from sympy.polys.matrices import DomainMatrix, DM >>> from sympy.polys.numberfields.modules import PowerBasis >>> T = Poly(cyclotomic_poly(5, x)) >>> A = PowerBasis(T) >>> print(A) PowerBasis(x**4 + x**3 + x**2 + x + 1) >>> B = A.submodule_from_matrix(2 * DomainMatrix.eye(4, ZZ), denom=3) >>> print(B) Submodule[[2, 0, 0, 0], [0, 2, 0, 0], [0, 0, 2, 0], [0, 0, 0, 2]]/3 >>> print(B.parent) PowerBasis(x**4 + x**3 + x**2 + x + 1) Thus, every module is either a :py:class:`~.PowerBasis`, or a :py:class:`~.Submodule`, some ancestor of which is a :py:class:`~.PowerBasis`. (If ``S`` is a :py:class:`~.Submodule`, then its ancestors are ``S.parent``, ``S.parent.parent``, and so on). The :py:class:`~.ModuleElement` class represents a linear combination of the generators of any module. Critically, the coefficients of this linear combination are not restricted to be integers, but may be any rational numbers. This is necessary so that any and all algebraic integers be representable, starting from the power basis in a primitive element $\theta$ for the number field in question. For example, in a quadratic field $\mathbb{Q}(\sqrt{d})$ where $d \equiv 1 \mod{4}$, a denominator of $2$ is needed. A :py:class:`~.ModuleElement` can be constructed from an integer column vector and a denominator: >>> U = Poly(x**2 - 5) >>> M = PowerBasis(U) >>> e = M(DM([[1], [1]], ZZ), denom=2) >>> print(e) [1, 1]/2 >>> print(e.module) PowerBasis(x**2 - 5) The :py:class:`~.PowerBasisElement` class is a subclass of :py:class:`~.ModuleElement` that represents elements of a :py:class:`~.PowerBasis`, and adds functionality pertinent to elements represented directly over powers of the primitive element $\theta$. Arithmetic with module elements =============================== While a :py:class:`~.ModuleElement` represents a linear combination over the generators of a particular module, recall that every module is either a :py:class:`~.PowerBasis` or a descendant (along a chain of :py:class:`~.Submodule` objects) thereof, so that in fact every :py:class:`~.ModuleElement` represents an algebraic number in some field $\mathbb{Q}(\theta)$, where $\theta$ is the defining element of some :py:class:`~.PowerBasis`. It thus makes sense to talk about the number field to which a given :py:class:`~.ModuleElement` belongs. This means that any two :py:class:`~.ModuleElement` instances can be added, subtracted, multiplied, or divided, provided they belong to the same number field. Similarly, since $\mathbb{Q}$ is a subfield of every number field, any :py:class:`~.ModuleElement` may be added, multiplied, etc. by any rational number. >>> from sympy import QQ >>> from sympy.polys.numberfields.modules import to_col >>> T = Poly(cyclotomic_poly(5)) >>> A = PowerBasis(T) >>> C = A.submodule_from_matrix(3 * DomainMatrix.eye(4, ZZ)) >>> e = A(to_col([0, 2, 0, 0]), denom=3) >>> f = A(to_col([0, 0, 0, 7]), denom=5) >>> g = C(to_col([1, 1, 1, 1])) >>> e + f [0, 10, 0, 21]/15 >>> e - f [0, 10, 0, -21]/15 >>> e - g [-9, -7, -9, -9]/3 >>> e + QQ(7, 10) [21, 20, 0, 0]/30 >>> e * f [-14, -14, -14, -14]/15 >>> e ** 2 [0, 0, 4, 0]/9 >>> f // g [7, 7, 7, 7]/15 >>> f * QQ(2, 3) [0, 0, 0, 14]/15 However, care must be taken with arithmetic operations on :py:class:`~.ModuleElement`, because the module $C$ to which the result will belong will be the nearest common ancestor (NCA) of the modules $A$, $B$ to which the two operands belong, and $C$ may be different from either or both of $A$ and $B$. >>> A = PowerBasis(T) >>> B = A.submodule_from_matrix(2 * DomainMatrix.eye(4, ZZ)) >>> C = A.submodule_from_matrix(3 * DomainMatrix.eye(4, ZZ)) >>> print((B(0) * C(0)).module == A) True Before the arithmetic operation is performed, copies of the two operands are automatically converted into elements of the NCA (the operands themselves are not modified). This upward conversion along an ancestor chain is easy: it just requires the successive multiplication by the defining matrix of each :py:class:`~.Submodule`. Conversely, downward conversion, i.e. representing a given :py:class:`~.ModuleElement` in a submodule, is also supported -- namely by the :py:meth:`~sympy.polys.numberfields.modules.Submodule.represent` method -- but is not guaranteed to succeed in general, since the given element may not belong to the submodule. The main circumstance in which this issue tends to arise is with multiplication, since modules, while closed under addition, need not be closed under multiplication. Multiplication -------------- Generally speaking, a module need not be closed under multiplication, i.e. need not form a ring. However, many of the modules we work with in the context of number fields are in fact rings, and our classes do support multiplication. Specifically, any :py:class:`~.Module` can attempt to compute its own multiplication table, but this does not happen unless an attempt is made to multiply two :py:class:`~.ModuleElement` instances belonging to it. >>> A = PowerBasis(T) >>> print(A._mult_tab is None) True >>> a = A(0)*A(1) >>> print(A._mult_tab is None) False Every :py:class:`~.PowerBasis` is, by its nature, closed under multiplication, so instances of :py:class:`~.PowerBasis` can always successfully compute their multiplication table. When a :py:class:`~.Submodule` attempts to compute its multiplication table, it converts each of its own generators into elements of its parent module, multiplies them there, in every possible pairing, and then tries to represent the results in itself, i.e. as $\mathbb{Z}$-linear combinations over its own generators. This will succeed if and only if the submodule is in fact closed under multiplication. Module Homomorphisms ==================== Many important number theoretic algorithms require the calculation of the kernel of one or more module homomorphisms. Accordingly we have several lightweight classes, :py:class:`~.ModuleHomomorphism`, :py:class:`~.ModuleEndomorphism`, :py:class:`~.InnerEndomorphism`, and :py:class:`~.EndomorphismRing`, which provide the minimal necessary machinery to support this. )igcdilcm)Dummy)ANP)Poly)dup_clear_denoms)AlgebraicField)FF)QQZZ) DomainMatrix)DMBadInputError)hermite_normal_form)CoercionFailedUnificationFailed)IntegerPowerable)ClosureFailureMissingUnityErrorStructureError) AlgIntPowersis_rat get_num_denomcCs$tdd|Dgdt|ftS)z>Transform a list of integer coefficients into a column vector.cSsg|] }t|qSr .0crr\/var/www/html/django/DPS/env/lib/python3.9/site-packages/sympy/polys/numberfields/modules.py zto_col..r)r lenr transpose)coeffsrrrto_colsr$c@seZdZdZeddZddZeddZdd Zd,d d Z d dZ ddZ eddZ ddZ d-ddZddZddZddZddZd d!Zd.d$d%Zd/d&d'Zd(d)Zd*d+Zd#S)0Moduleaf Generic finitely-generated module. This is an abstract base class, and should not be instantiated directly. The two concrete subclasses are :py:class:`~.PowerBasis` and :py:class:`~.Submodule`. Every :py:class:`~.Submodule` is derived from another module, referenced by its ``parent`` attribute. If ``S`` is a submodule, then we refer to ``S.parent``, ``S.parent.parent``, and so on, as the "ancestors" of ``S``. Thus, every :py:class:`~.Module` is either a :py:class:`~.PowerBasis` or a :py:class:`~.Submodule`, some ancestor of which is a :py:class:`~.PowerBasis`. cCstdS)z(The number of generators of this module.NNotImplementedErrorselfrrrnszModule.ncCstdS)ad Get the multiplication table for this module (if closed under mult). Explanation =========== Computes a dictionary ``M`` of dictionaries of lists, representing the upper triangular half of the multiplication table. In other words, if ``0 <= i <= j < self.n``, then ``M[i][j]`` is the list ``c`` of coefficients such that ``g[i] * g[j] == sum(c[k]*g[k], k in range(self.n))``, where ``g`` is the list of generators of this module. If ``j < i`` then ``M[i][j]`` is undefined. Examples ======== >>> from sympy.polys import Poly, cyclotomic_poly >>> from sympy.polys.numberfields.modules import PowerBasis >>> T = Poly(cyclotomic_poly(5)) >>> A = PowerBasis(T) >>> print(A.mult_tab()) # doctest: +SKIP {0: {0: [1, 0, 0, 0], 1: [0, 1, 0, 0], 2: [0, 0, 1, 0], 3: [0, 0, 0, 1]}, 1: {1: [0, 0, 1, 0], 2: [0, 0, 0, 1], 3: [-1, -1, -1, -1]}, 2: {2: [-1, -1, -1, -1], 3: [1, 0, 0, 0]}, 3: {3: [0, 1, 0, 0]}} Returns ======= dict of dict of lists Raises ====== ClosureFailure If the module is not closed under multiplication. Nr&r(rrrmult_tabs*zModule.mult_tabcCsdS)ae The parent module, if any, for this module. Explanation =========== For a :py:class:`~.Submodule` this is its ``parent`` attribute; for a :py:class:`~.PowerBasis` this is ``None``. Returns ======= :py:class:`~.Module`, ``None`` See Also ======== Module Nrr(rrrparent sz Module.parentcCstdS)aa Represent a module element as an integer-linear combination over the generators of this module. Explanation =========== In our system, to "represent" always means to write a :py:class:`~.ModuleElement` as a :ref:`ZZ`-linear combination over the generators of the present :py:class:`~.Module`. Furthermore, the incoming :py:class:`~.ModuleElement` must belong to an ancestor of the present :py:class:`~.Module` (or to the present :py:class:`~.Module` itself). The most common application is to represent a :py:class:`~.ModuleElement` in a :py:class:`~.Submodule`. For example, this is involved in computing multiplication tables. On the other hand, representing in a :py:class:`~.PowerBasis` is an odd case, and one which tends not to arise in practice, except for example when using a :py:class:`~.ModuleEndomorphism` on a :py:class:`~.PowerBasis`. In such a case, (1) the incoming :py:class:`~.ModuleElement` must belong to the :py:class:`~.PowerBasis` itself (since the latter has no proper ancestors) and (2) it is "representable" iff it belongs to $\mathbb{Z}[\theta]$ (although generally a :py:class:`~.PowerBasisElement` may represent any element of $\mathbb{Q}(\theta)$, i.e. any algebraic number). Examples ======== >>> from sympy import Poly, cyclotomic_poly >>> from sympy.polys.numberfields.modules import PowerBasis, to_col >>> from sympy.abc import zeta >>> T = Poly(cyclotomic_poly(5)) >>> A = PowerBasis(T) >>> a = A(to_col([2, 4, 6, 8])) The :py:class:`~.ModuleElement` ``a`` has all even coefficients. If we represent ``a`` in the submodule ``B = 2*A``, the coefficients in the column vector will be halved: >>> B = A.submodule_from_gens([2*A(i) for i in range(4)]) >>> b = B.represent(a) >>> print(b.transpose()) # doctest: +SKIP DomainMatrix([[1, 2, 3, 4]], (1, 4), ZZ) However, the element of ``B`` so defined still represents the same algebraic number: >>> print(a.poly(zeta).as_expr()) 8*zeta**3 + 6*zeta**2 + 4*zeta + 2 >>> print(B(b).over_power_basis().poly(zeta).as_expr()) 8*zeta**3 + 6*zeta**2 + 4*zeta + 2 Parameters ========== elt : :py:class:`~.ModuleElement` The module element to be represented. Must belong to some ancestor module of this module (including this module itself). Returns ======= :py:class:`~.DomainMatrix` over :ref:`ZZ` This will be a column vector, representing the coefficients of a linear combination of this module's generators, which equals the given element. Raises ====== ClosureFailure If the given element cannot be represented as a :ref:`ZZ`-linear combination over this module. See Also ======== .Submodule.represent .PowerBasis.represent Nr&r)eltrrr represent%sWzModule.representFcCs0|j}|durgn |jdd}|r,|||S)z Return the list of ancestor modules of this module, from the foundational :py:class:`~.PowerBasis` downward, optionally including ``self``. See Also ======== Module NT include_self)r, ancestorsappend)r)r1rarrrr2~s  zModule.ancestorscCs(t|tr|S|j}|dur$|SdS)z Return the :py:class:`~.PowerBasis` that is an ancestor of this module. See Also ======== Module N) isinstance PowerBasisr,power_basis_ancestor)r)rrrrr7s zModule.power_basis_ancestorcCsF|jdd}|jdd}d}t||D]\}}||kr<|}q&qBq&|S)z Locate the nearest common ancestor of this module and another. Returns ======= :py:class:`~.Module`, ``None`` See Also ======== Module Tr0N)r2zip)r)otherZsAZoAncasaoarrrnearest_common_ancestors  zModule.nearest_common_ancestorcCs |jS)a# Return the associated :py:class:`~.AlgebraicField`, if any. Explanation =========== A :py:class:`~.PowerBasis` can be constructed on a :py:class:`~.Poly` $f$ or on an :py:class:`~.AlgebraicField` $K$. In the latter case, the :py:class:`~.PowerBasis` and all its descendant modules will return $K$ as their ``.number_field`` property, while in the former case they will all return ``None``. Returns ======= :py:class:`~.AlgebraicField`, ``None`` )r7 number_fieldr(rrrr>szModule.number_fieldcCs"t|to |j|jdfko |jjS)z>Say whether *col* is a suitable column vector for this module.r)r5r shaper*domainis_ZZ)r)colrrr is_compat_colszModule.is_compat_colrcCsbt|trBd|kr |jkrBnnt|jtdd|f}||sTtdt |||dS)a Generate a :py:class:`~.ModuleElement` belonging to this module. Examples ======== >>> from sympy.polys import Poly, cyclotomic_poly >>> from sympy.polys.numberfields.modules import PowerBasis, to_col >>> T = Poly(cyclotomic_poly(5)) >>> A = PowerBasis(T) >>> e = A(to_col([1, 2, 3, 4]), denom=3) >>> print(e) # doctest: +SKIP [1, 2, 3, 4]/3 >>> f = A(2) >>> print(f) # doctest: +SKIP [0, 0, 1, 0] Parameters ========== spec : :py:class:`~.DomainMatrix`, int Specifies the numerators of the coefficients of the :py:class:`~.ModuleElement`. Can be either a column vector over :ref:`ZZ`, whose length must equal the number $n$ of generators of this module, or else an integer ``j``, $0 \leq j < n$, which is a shorthand for column $j$ of $I_n$, the $n \times n$ identity matrix. denom : int, optional (default=1) Denominator for the coefficients of the :py:class:`~.ModuleElement`. Returns ======= :py:class:`~.ModuleElement` The coefficients are the entries of the *spec* vector, divided by *denom*. rNz"Compatible column vector required.denom) r5intr*r eyer to_denserC ValueError make_mod_elt)r)specrErrr__call__s ($ zModule.__call__cCstdS)z6Say whether the module's first generator equals unity.Nr&r(rrrstarts_with_unityszModule.starts_with_unitycsfddtjDS)zf Get list of :py:class:`~.ModuleElement` being the generators of this module. csg|] }|qSrrrjr(rrr r z)Module.basis_elements..)ranger*r(rr(rbasis_elementsszModule.basis_elementscCs |ddS)z7Return a :py:class:`~.ModuleElement` representing zero.rrr(rrrzero sz Module.zerocCs |dS)z Return a :py:class:`~.ModuleElement` representing unity, and belonging to the first ancestor of this module (including itself) that starts with unity. r)element_from_rationalr(rrronesz Module.onecCstdS)a* Return a :py:class:`~.ModuleElement` representing a rational number. Explanation =========== The returned :py:class:`~.ModuleElement` will belong to the first module on this module's ancestor chain (including this module itself) that starts with unity. Examples ======== >>> from sympy.polys import Poly, cyclotomic_poly, QQ >>> from sympy.polys.numberfields.modules import PowerBasis >>> T = Poly(cyclotomic_poly(5)) >>> A = PowerBasis(T) >>> a = A.element_from_rational(QQ(2, 3)) >>> print(a) # doctest: +SKIP [2, 0, 0, 0]/3 Parameters ========== a : int, :ref:`ZZ`, :ref:`QQ` Returns ======= :py:class:`~.ModuleElement` Nr&r)r4rrrrSs!zModule.element_from_rationalTNcstfdd|Dstdt|}|dkr6td|dj}|dkrR|djntdd|Dt|dftj fd d|D}|rt ||d }j |d S) a Form the submodule generated by a list of :py:class:`~.ModuleElement` belonging to this module. Examples ======== >>> from sympy.polys import Poly, cyclotomic_poly >>> from sympy.polys.numberfields.modules import PowerBasis >>> T = Poly(cyclotomic_poly(5)) >>> A = PowerBasis(T) >>> gens = [A(0), 2*A(1), 3*A(2), 4*A(3)//5] >>> B = A.submodule_from_gens(gens) >>> print(B) # doctest: +SKIP Submodule[[5, 0, 0, 0], [0, 10, 0, 0], [0, 0, 15, 0], [0, 0, 0, 4]]/5 Parameters ========== gens : list of :py:class:`~.ModuleElement` belonging to this module. hnf : boolean, optional (default=True) If True, we will reduce the matrix into Hermite Normal Form before forming the :py:class:`~.Submodule`. hnf_modulus : int, None, optional (default=None) Modulus for use in the HNF reduction algorithm. See :py:func:`~sympy.polys.matrices.normalforms.hermite_normal_form`. Returns ======= :py:class:`~.Submodule` See Also ======== submodule_from_matrix c3s|]}|jkVqdSN)modulergr(rr cr z-Module.submodule_from_gens..z&Generators must belong to this module.rzNeed at least one generator.rcSsg|] }|jqSrrDrXrrrrir z.Module.submodule_from_gens..csg|]}|j|jqSr)rErBrX)drrrjr DrD) allrIr!r*rErr zerosr hstackrsubmodule_from_matrix)r)genshnf hnf_modulusr*mBr)r[r)rsubmodule_from_gens<s' $$ zModule.submodule_from_genscCs:|j\}}|jjstd||jks,tdt|||dS)a Form the submodule generated by the elements of this module indicated by the columns of a matrix, with an optional denominator. Examples ======== >>> from sympy.polys import Poly, cyclotomic_poly, ZZ >>> from sympy.polys.matrices import DM >>> from sympy.polys.numberfields.modules import PowerBasis >>> T = Poly(cyclotomic_poly(5)) >>> A = PowerBasis(T) >>> B = A.submodule_from_matrix(DM([ ... [0, 10, 0, 0], ... [0, 0, 7, 0], ... ], ZZ).transpose(), denom=15) >>> print(B) # doctest: +SKIP Submodule[[0, 10, 0, 0], [0, 0, 7, 0]]/15 Parameters ========== B : :py:class:`~.DomainMatrix` over :ref:`ZZ` Each column gives the numerators of the coefficients of one generator of the submodule. Thus, the number of rows of *B* must equal the number of generators of the present module. denom : int, optional (default=1) Common denominator for all generators of the submodule. Returns ======= :py:class:`~.Submodule` Raises ====== ValueError If the given matrix *B* is not over :ref:`ZZ` or its number of rows does not equal the number of generators of the present module. See Also ======== submodule_from_gens zMatrix must be over ZZ.z(Matrix row count must match base module.rD)r?r@rArIr* Submodule)r)rfrErer*rrrraos 0  zModule.submodule_from_matrixcCst|jt}||S)a" Return a submodule equal to this entire module. Explanation =========== This is useful when you have a :py:class:`~.PowerBasis` and want to turn it into a :py:class:`~.Submodule` (in order to use methods belonging to the latter). )r rGr*r ra)r)rfrrrwhole_submodules zModule.whole_submodulecCst|S)z8Form the :py:class:`~.EndomorphismRing` for this module.)EndomorphismRingr(rrrendomorphism_ringszModule.endomorphism_ring)F)r)TN)r)__name__ __module__ __qualname____doc__propertyr*r+r,r/r2r7r=r>rCrLrMrQrRrTrSrgrarirkrrrrr%s. , Y   .# 3 7r%c@seZdZdZddZeddZddZdd Zed d Z d d Z ddZ ddZ ddZ ddZddZddZddZddZdS)r6z;The module generated by the powers of an algebraic integer.cCsHd}t|tr||j}}|t}||_||_||_ d|_ dS)a Parameters ========== T : :py:class:`~.Poly`, :py:class:`~.AlgebraicField` Either (1) the monic, irreducible, univariate polynomial over :ref:`ZZ`, a root of which is the generator of the power basis, or (2) an :py:class:`~.AlgebraicField` whose primitive element is the generator of the power basis. N) r5rextminpoly_of_element set_domainr KTdegree_n _mult_tab)r)rurtrrr__init__s    zPowerBasis.__init__cCs|jSrV)rtr(rrrr>szPowerBasis.number_fieldcCsd|jdS)Nz PowerBasis())ruas_exprr(rrr__repr__szPowerBasis.__repr__cCst|tr|j|jkStSrV)r5r6ruNotImplementedr)r9rrr__eq__s  zPowerBasis.__eq__cCs|jSrVrwr(rrrr*sz PowerBasis.ncCs|jdur||jSrVrxcompute_mult_tabr(rrrr+s zPowerBasis.mult_tabcCsXt|j}i}|j}t|D]0}i||<t||D]}||||||<q2q||_dSrV)rrur*rPrx)r)Z theta_powMr*uvrrrrs  zPowerBasis.compute_mult_tabcCs(|j|kr|jdkr|StddS)z Represent a module element as an integer-linear combination over the generators of this module. See Also ======== .Module.represent .Submodule.represent rz'Element not representable in ZZ[theta].N)rWrEcolumnrr-rrrr/s zPowerBasis.representcCsdS)NTrr(rrrrMszPowerBasis.starts_with_unitycCs |d|SNrrrUrrrrSsz PowerBasis.element_from_rationalc Cs|j|}}||kr"||j}|dkr2|St|jjtdd\}}tt|}t |}t dg||}t ||}|||dS)aE Produce an element of this module, representing *f* after reduction mod our defining minimal polynomial. Parameters ========== f : :py:class:`~.Poly` over :ref:`ZZ` in same var as our defining poly. Returns ======= :py:class:`~.PowerBasisElement` rT)convertrD) r*rvrurRrrepr listreversedr!r r$) r)fr*kr[rellzrBrrrelement_from_poly s   zPowerBasis.element_from_polycCs*||jjjkrtd|t||jjS)a Produce a PowerBasisElement representing a given algebraic number. Parameters ========== rep : list of coeffs Represents the number as polynomial in the primitive element of the field. mod : list of coeffs Represents the minimal polynomial of the primitive element of the field. Returns ======= :py:class:`~.PowerBasisElement` z0Element does not appear to be in the same field.)rurrrrgen)r)rmodrrr_element_from_rep_and_mod&sz$PowerBasis._element_from_rep_and_modcCs||j|jS)z)Convert an ANP into a PowerBasisElement. )rrrrUrrrelement_from_ANP?szPowerBasis.element_from_ANPcCs||jj|jjjS)z5Convert an AlgebraicNumber into a PowerBasisElement. )rrminpolyrUrrrelement_from_alg_numCszPowerBasis.element_from_alg_numN)rlrmrnroryrpr>r|rr*r+rr/rMrSrrrrrrrrr6s"   r6c@seZdZdZd9ddZddZdd Zd d Zed d Z ddZ ddZ eddZ eddZ eddZeddZeddZddZddZd d!Zd"d#Zd$d%Zd&d'Zd(d)Zd*d+Zd:d-d.Zd/d0ZeZd;d1d2Zd3d4ZeZd5d6Zd7d8Z dS)t|j||j|dS)ze Produce a new module by discarding all generators before a given index *r*. Nr)rr*rxrPrhr,rE)r)rWsrmtrrrrrdiscard_befores  (zSubmodule.discard_beforecCs|jSrVrr(rrrr*sz Submodule.ncCs|jdur||jSrVrr(rrrr+s zSubmodule.mult_tabcCsd|}i}|j}t|D]>}i||<t||D]&}||||||||<q0q||_dSrV)basis_element_pullbacksr*rPr/flatrx)r)rbrr*rrrrrrs &zSubmodule.compute_mult_tabcCs|jSrV)rr(rrrr,szSubmodule.parentcCs|jSrV)rr(rrrrszSubmodule.matrixcCs |jSrV)rrr(rrrr#szSubmodule.coeffscCs|jSrV)rr(rrrrEszSubmodule.denomcCs"|jdur|j|j|_|jS)a1 :py:class:`~.DomainMatrix` over :ref:`QQ`, equal to ``self.matrix / self.denom``, and guaranteed to be dense. Explanation =========== Depending on how it is formed, a :py:class:`~.DomainMatrix` may have an internal representation that is sparse or dense. We guarantee a dense representation here, so that tests for equivalence of submodules always come out as expected. Examples ======== >>> from sympy.polys import Poly, cyclotomic_poly, ZZ >>> from sympy.abc import x >>> from sympy.polys.matrices import DomainMatrix >>> from sympy.polys.numberfields.modules import PowerBasis >>> T = Poly(cyclotomic_poly(5, x)) >>> A = PowerBasis(T) >>> B = A.submodule_from_matrix(3*DomainMatrix.eye(4, ZZ), denom=6) >>> C = A.submodule_from_matrix(DomainMatrix.eye(4, ZZ), denom=2) >>> print(B.QQ_matrix == C.QQ_matrix) True Returns ======= :py:class:`~.DomainMatrix` over :ref:`QQ` N)rrrErHr(rrr QQ_matrixs" zSubmodule.QQ_matrixcCs |jdur|dd|_|jS)Nrr)requivr(rrrrMs zSubmodule.starts_with_unitycCs|jdurt|j|_|jSrV)ris_sq_maxrank_HNFrr(rrrrs  zSubmodule.is_sq_maxrank_HNFcCs t|jtSrV)r5r,r6r(rrris_power_basis_submodulesz"Submodule.is_power_basis_submodulecCs$|r|d|S|j|SdSr)rMr,rSrUrrrrSs zSubmodule.element_from_rationalcCsdd|DS)zv Return list of this submodule's basis elements as elements of the submodule's parent module. cSsg|] }|qSr) to_parentrerrrrr z5Submodule.basis_element_pullbacks..)rQr(rrrrsz!Submodule.basis_element_pullbackscCs|j|kr|S|j|jkrz,|j}|j}||d}|t}Wn2t ydt dYnt y|t dYn0|St |jt r|j|}||}||St ddS)z Represent a module element as an integer-linear combination over the generators of this module. See Also ======== .Module.represent .PowerBasis.represent rz&Element outside QQ-span of this basis.z1Element in QQ-span but not ZZ-span of this basis.z.Element outside ancestor chain of this module.N)rWrr,rQQ_col_solver"rr rrrr5rhr/)r)r.AbxZcoeffs_in_parentZparent_elementrrrr/s$         zSubmodule.representcCst|to|j|jkSrV)r5rhr,r~rrris_compat_submoduleszSubmodule.is_compat_submodulecCs||r|j|jkStSrV)rrr}r~rrrrs  zSubmodule.__eq__Tc Cs`|j|j}}t||}||||}}||j||j} |rPt| |d} |jj| |dS)a Add this :py:class:`~.Submodule` to another. Explanation =========== This represents the module generated by the union of the two modules' sets of generators. Parameters ========== other : :py:class:`~.Submodule` hnf : boolean, optional (default=True) If ``True``, reduce the matrix of the combined module to its Hermite Normal Form. hnf_modulus : :ref:`ZZ`, None, optional If a positive integer is provided, use this as modulus in the HNF reduction. See :py:func:`~sympy.polys.matrices.normalforms.hermite_normal_form`. Returns ======= :py:class:`~.Submodule` r\rD)rErrr`rr,ra) r)r9rcrdr[rrer4rrfrrradd"s  z Submodule.addcCs||r||StSrV)rrr}r~rrr__add__Fs  zSubmodule.__add__cstrTt\}}||kr(dkr0nn|St|j|j||j|ddSn~ttrj |jkrfdd| D}|jj |||dS| r|  }fdd|D}|jj |||dSt S)a Multiply this :py:class:`~.Submodule` by a rational number, a :py:class:`~.ModuleElement`, or another :py:class:`~.Submodule`. Explanation =========== To multiply by a rational number or :py:class:`~.ModuleElement` means to form the submodule whose generators are the products of this quantity with all the generators of the present submodule. To multiply by another :py:class:`~.Submodule` means to form the submodule whose generators are all the products of one generator from the one submodule, and one generator from the other. Parameters ========== other : int, :ref:`ZZ`, :ref:`QQ`, :py:class:`~.ModuleElement`, :py:class:`~.Submodule` hnf : boolean, optional (default=True) If ``True``, reduce the matrix of the product module to its Hermite Normal Form. hnf_modulus : :ref:`ZZ`, None, optional If a positive integer is provided, use this as modulus in the HNF reduction. See :py:func:`~sympy.polys.matrices.normalforms.hermite_normal_form`. Returns ======= :py:class:`~.Submodule` rNrcsg|] }|qSrrr)r9rrrzr z!Submodule.mul..)rcrdcsg|]}D] }||q qSrrrr4r)betasrrrr )rrrhr,rrErr5 ModuleElementrWrrgrr})r)r9rcrdr4rrbalphasr)rr9rmulMs "   z Submodule.mulcCs ||SrV)rr~rrr__mul__szSubmodule.__mul__cCs|SrVrr(rrr _first_powerszSubmodule._first_powercCs|j|jkst|s$d}t||}|}t|jdddD]8}||}|j||j |j||j }|||8}qB|S)aD If this submodule $B$ has defining matrix $W$ in square, maximal-rank Hermite normal form, then, given an element $x$ of the parent module $A$, we produce an element $y \in A$ such that $x - y \in B$, and the $i$th coordinate of $y$ satisfies $0 \leq y_i < w_{i,i}$. This representative $y$ is unique, in the sense that every element of the coset $x + B$ reduces to it under this procedure. Explanation =========== In the special case where $A$ is a power basis for a number field $K$, and $B$ is a submodule representing an ideal $I$, this operation represents one of a few important ways of reducing an element of $K$ modulo $I$ to obtain a "small" representative. See [Cohen00]_ Section 1.4.3. Examples ======== >>> from sympy import QQ, Poly, symbols >>> t = symbols('t') >>> k = QQ.alg_field_from_poly(Poly(t**3 + t**2 - 2*t + 8)) >>> Zk = k.maximal_order() >>> A = Zk.parent >>> B = (A(2) - 3*A(0))*Zk >>> B.reduce_element(A(2)) [3, 0, 0] Parameters ========== elt : :py:class:`~.ModuleElement` An element of this submodule's parent module. Returns ======= elt : :py:class:`~.ModuleElement` An element of this submodule's parent module. Raises ====== NotImplementedError If the given :py:class:`~.ModuleElement` does not belong to this submodule's parent module. StructureError If this submodule's defining matrix is not in square, maximal-rank Hermite normal form. References ========== .. [Cohen00] Cohen, H. *Advanced Topics in Computational Number Theory.* z;Reduction not implemented unless matrix square max-rank HNFr) rWr,r'rrrrPr*r#rE)r)r.msgrfr4irqrrrreduce_elements;  zSubmodule.reduce_element)rN)TN)TN)!rlrmrnroryr|rrrpr*r+rr,rr#rErrMrrrSrr/rrrr__radd__rr__rmul__rrrrrrrhHsF        %# $ 7rhcCs|jjr|jr|jr|jd}t|D]\}|||fj}|dkrFdSt|d|D],}d|||fjkrv|ksTndSqTq&dSdS)ar Say whether a :py:class:`~.DomainMatrix` is in that special case of Hermite Normal Form, in which the matrix is also square and of maximal rank. Explanation =========== We commonly work with :py:class:`~.Submodule` instances whose matrix is in this form, and it can be useful to be able to check that this condition is satisfied. For example this is the case with the :py:class:`~.Submodule` ``ZK`` returned by :py:func:`~sympy.polys.numberfields.basis.round_two`, which represents the maximal order in a number field, and with ideals formed therefrom, such as ``2 * ZK``. rFrT)r@rA is_squareis_upperr?rPelement)dmr*rr[rOrrrrs    rcCs*t|trt|||dSt|||dSdS)z Factory function which builds a :py:class:`~.ModuleElement`, but ensures that it is a :py:class:`~.PowerBasisElement` if the module is a :py:class:`~.PowerBasis`. rDN)r5r6PowerBasisElementr)rWrBrErrrrJs rJc@seZdZdZd:ddZddZddZd d Zed;d d Z e d dZ ddZ d.rr)strrBrrErrrrr|s zModuleElement.__repr__cCsT|jdkr|St|jg|jR}|dkr.|St||j|j|t|j|dS)z Produce a reduced version of this ModuleElement, i.e. one in which the gcd of the denominator together with all numerator coefficients is 1. rrD)rErr#rrWrBrr rrrrr"s  zModuleElement.reducedcCs$t|j|jt|t|jdS)z Produce a version of this :py:class:`~.ModuleElement` in which all numerator coefficients have been reduced mod *p*. rD)rJrWrBrr r rE)r)prrr reduced_mod_p0szModuleElement.reduced_mod_pcCst|}||||dS)zn Make a :py:class:`~.ModuleElement` from a list of ints (instead of a column vector). rD)r$)clsrWr#rErBrrr from_int_list9szModuleElement.from_int_listcCs|jjS)z$The length of this element's column.)rWr*r(rrrr*BszModuleElement.ncCs|jSrV)r*r(rrr__len__GszModuleElement.__len__NcCs |j|S)zY Get a copy of this element's column, optionally converting to a domain. )rBrr)r@rrrrJszModuleElement.columncCs |jSrV)rBrr(rrrr#PszModuleElement.coeffscCs"|jdur|j|j|_|jS)z :py:class:`~.DomainMatrix` over :ref:`QQ`, equal to ``self.col / self.denom``, and guaranteed to be dense. See Also ======== .Submodule.QQ_matrix N)rrBrErHr(rrrrTs zModuleElement.QQ_colcCs:t|jtstdt|jj|jj|j|jj|jdS)zx Transform into a :py:class:`~.ModuleElement` belonging to the parent of this element's module. zNot an element of a Submodule.rD) r5rWrhrIrJr,rrBrEr(rrrrds   zModuleElement.to_parentcCs ||jkr|S||SdS)z Transform into a :py:class:`~.ModuleElement` belonging to a given ancestor of this element's module. Parameters ========== anc : :py:class:`~.Module` N)rWr to_ancestor)r)Zancrrrros zModuleElement.to_ancestorcCs|}t|jts|}q|S)zv Transform into a :py:class:`~.PowerBasisElement` over our :py:class:`~.PowerBasis` ancestor. )r5rWr6r)r)rrrrover_power_basiss  zModuleElement.over_power_basiscCst|to|j|jkS)ze Test whether other is another :py:class:`~.ModuleElement` with same module. )r5rrWr~rrr is_compatszModuleElement.is_compatcCsV|j|jkr||fS|j|j}|dur>||||fStd|d|dS)a Try to make a compatible pair of :py:class:`~.ModuleElement`, one equivalent to this one, and one equivalent to the other. Explanation =========== We search for the nearest common ancestor module for the pair of elements, and represent each one there. Returns ======= Pair ``(e1, e2)`` Each ``ei`` is a :py:class:`~.ModuleElement`, they belong to the same :py:class:`~.Module`, ``e1`` is equivalent to ``self``, and ``e2`` is equivalent to ``other``. Raises ====== UnificationFailed If ``self`` and ``other`` have no common ancestor module. Nz Cannot unify z with )rWr=rr)r)r9r:rrrunifys  zModuleElement.unifycCs||r|j|jkStSrV)rrr}r~rrrrs  zModuleElement.__eq__cCsb||kr dSt|tr,||\}}||kSt|r^t|trP||d|kS||SdS)a A :py:class:`~.ModuleElement` may test as equivalent to a rational number or another :py:class:`~.ModuleElement`, if they represent the same algebraic number. Explanation =========== This method is intended to check equivalence only in those cases in which it is easy to test; namely, when *other* is either a :py:class:`~.ModuleElement` that can be unified with this one (i.e. one which shares a common :py:class:`~.PowerBasis` ancestor), or else a rational number (which is easy because every :py:class:`~.PowerBasis` represents every rational number). Parameters ========== other : int, :ref:`ZZ`, :ref:`QQ`, :py:class:`~.ModuleElement` Returns ======= bool Raises ====== UnificationFailed If ``self`` and ``other`` do not share a common :py:class:`~.PowerBasis` ancestor. TrF)r5rrrrrWrr)r)r9r4rrrrrs"  zModuleElement.equivcs||rn|j|j}}t||}||||tfddt|j|jD}t||j||dSt |t rz| |\}}Wnt yt YS0||St|r||j|St S)a. A :py:class:`~.ModuleElement` can be added to a rational number, or to another :py:class:`~.ModuleElement`. Explanation =========== When the other summand is a rational number, it will be converted into a :py:class:`~.ModuleElement` (belonging to the first ancestor of this module that starts with unity). In all cases, the sum belongs to the nearest common ancestor (NCA) of the modules of the two summands. If the NCA does not exist, we return ``NotImplemented``. cs g|]\}}||qSrrrrrrrrr z)ModuleElement.__add__..rD)rrErr$r8r#rrWrr5rrrr}rrS)r)r9r[rrerBr4rrrrrs  "   zModuleElement.__add__cCs|dS)Nrrr(rrr__neg__szModuleElement.__neg__cCs || SrVrr~rrr__sub__ szModuleElement.__sub__cCs | |SrVrr~rrr__rsub__ szModuleElement.__rsub__c Csv||r|j}|j|j}}|j}dg|}t|D]z}t||D]j}||||} ||kr| ||||7} | dkrP|||} t|D]} || | | | 7<qqPqB|j|j} |j|j|| dSt |t rz| |\} }Wnt yt YS0| |St|rrt|\} }| |krJdkrRnn|St|j|j| |j|dSt S)a A :py:class:`~.ModuleElement` can be multiplied by a rational number, or by another :py:class:`~.ModuleElement`. Explanation =========== When the multiplier is a rational number, the product is computed by operating directly on the coefficients of this :py:class:`~.ModuleElement`. When the multiplier is another :py:class:`~.ModuleElement`, the product will belong to the nearest common ancestor (NCA) of the modules of the two operands, and that NCA must have a multiplication table. If the NCA does not exist, we return ``NotImplemented``. If the NCA does not have a mult. table, ``ClosureFailure`` will be raised. rrDr)rrWr+rBrr*rPrErr5rrrr}rrrJr)r)r9rrrfr*CrrrRrr[r4rrrrrs<            zModuleElement.__mul__cCs |jSrV)rWrTr(rrr _zeroth_powerBszModuleElement._zeroth_powercCs|SrVrr(rrrrEszModuleElement._first_powercCs6t|rt|}|d|St|tr2|d|StS)Nr)rr r5rr}rUrrr __floordiv__Hs    zModuleElement.__floordiv__cCs ||SrV)rrUrrr __rfloordiv__PszModuleElement.__rfloordiv__cCs:t|r||j}t|tr6|j|jkr6||StS)a Reduce this :py:class:`~.ModuleElement` mod a :py:class:`~.Submodule`. Parameters ========== m : int, :ref:`ZZ`, :ref:`QQ`, :py:class:`~.Submodule` If a :py:class:`~.Submodule`, reduce ``self`` relative to this. If an integer or rational, reduce relative to the :py:class:`~.Submodule` that is our own module times this constant. See Also ======== .Submodule.reduce_element )rrWrir5rhr,rr})r)rerrr__mod__Ss  zModuleElement.__mod__)r)r)N)#rlrmrnroryr|rr classmethodrrpr*rrr#rrrrrrrrrrrrrrrrrrrrrrrrrsD         !. 1rc@seZdZdZeddZdddZdddZed d Zed d Z dd dZ dddZ ddZ ddZ dddZddZddZdS) rzl Subclass for :py:class:`~.ModuleElement` instances whose module is a :py:class:`~.PowerBasis`. cCs|jjS)z?Access the defining polynomial of the :py:class:`~.PowerBasis`.)rWrur(rrrrurszPowerBasisElement.TNcCs |p |jj}tt|j|tdS)z4Obtain the numerator as a polynomial over :ref:`ZZ`.r@)rurrrr#r r)rrrr numeratorws zPowerBasisElement.numeratorcCs|j|d|jS)z1Obtain the number as a polynomial over :ref:`QQ`.r)rrErrrrpoly|szPowerBasisElement.polycCs|jddddfjS)z6Say whether this element represents a rational number.rN)rBis_zero_matrixr(rrr is_rationalszPowerBasisElement.is_rationalcCs$|jj}|r|jjr|jjS|jjS)a^ Return a :py:class:`~.Symbol` to be used when expressing this element as a polynomial. If we have an associated :py:class:`~.AlgebraicField` whose primitive element has an alias symbol, we use that. Otherwise we use the variable of the minimal polynomial defining the power basis to which we belong. )rWr>rq is_aliasedaliasrurr)rtrrr generators zPowerBasisElement.generatorcCs||p |jS)z)Create a Basic expression from ``self``. )rrr{rrrrr{szPowerBasisElement.as_exprcCs2|p|j}|j}|j|d}|||j|jS)z Compute the norm of this number.r)rurr resultantrEr*)r)rurrrrrnorms  zPowerBasisElement.normcCs |}||j}|j|SrV)rinvertrurWr)r)rZf_invrrrinverses zPowerBasisElement.inversecCs ||SrV)rrUrrrrszPowerBasisElement.__rfloordiv__cCs|t|SrV)rabs)r)rmodulorrr_negative_powersz!PowerBasisElement._negative_powercCs&ttt|jt|jjjtS)z,Convert to an equivalent :py:class:`~.ANP`. ) rrrrrr maprurr(rrrto_ANPszPowerBasisElement.to_ANPcCs&|jj}|r||StddS)a Try to convert to an equivalent :py:class:`~.AlgebraicNumber`. Explanation =========== In general, the conversion from an :py:class:`~.AlgebraicNumber` to a :py:class:`~.PowerBasisElement` throws away information, because an :py:class:`~.AlgebraicNumber` specifies a complex embedding, while a :py:class:`~.PowerBasisElement` does not. However, in some cases it is possible to convert a :py:class:`~.PowerBasisElement` back into an :py:class:`~.AlgebraicNumber`, namely when the associated :py:class:`~.PowerBasis` has a reference to an :py:class:`~.AlgebraicField`. Returns ======= :py:class:`~.AlgebraicNumber` Raises ====== StructureError If the :py:class:`~.PowerBasis` to which this element belongs does not have an associated :py:class:`~.AlgebraicField`. zNo associated AlgebraicFieldN)rWr> to_alg_numrrrrrrrszPowerBasisElement.to_alg_num)N)N)N)N)N)rlrmrnrorprurrrrr{rrrrrrrrrrrls        rc@s,eZdZdZddZd ddZd ddZdS) ModuleHomomorphismz*A homomorphism from one module to another.cCs||_||_||_dS)a Parameters ========== domain : :py:class:`~.Module` The domain of the mapping. codomain : :py:class:`~.Module` The codomain of the mapping. mapping : callable An arbitrary callable is accepted, but should be chosen so as to represent an actual module homomorphism. In particular, should accept elements of *domain* and return elements of *codomain*. Examples ======== >>> from sympy import Poly, cyclotomic_poly >>> from sympy.polys.numberfields.modules import PowerBasis, ModuleHomomorphism >>> T = Poly(cyclotomic_poly(5)) >>> A = PowerBasis(T) >>> B = A.submodule_from_gens([2*A(j) for j in range(4)]) >>> phi = ModuleHomomorphism(A, B, lambda x: 6*x) >>> print(phi.matrix()) # doctest: +SKIP DomainMatrix([[3, 0, 0, 0], [0, 3, 0, 0], [0, 0, 3, 0], [0, 0, 0, 3]], (4, 4), ZZ) N)r@codomainmapping)r)r@rrrrrryszModuleHomomorphism.__init__Ncsdj}fdd|D}|s8tjjdftS|dj|dd}|r`| t |}|S)a Compute the matrix of this homomorphism. Parameters ========== modulus : int, optional A positive prime number $p$ if the matrix should be reduced mod $p$. Returns ======= :py:class:`~.DomainMatrix` The matrix is over :ref:`ZZ`, or else over :ref:`GF(p)` if a modulus was given. csg|]}j|qSr)rr/r)rr.r(rrrr z-ModuleHomomorphism.matrix..rrN) r@rQr r_rr*r rHr`rr )r)modulusbasiscolsrrr(rrs zModuleHomomorphism.matrixcCs<|j|d}|dur|t}|t}|j|S)a Compute a Submodule representing the kernel of this homomorphism. Parameters ========== modulus : int, optional A positive prime number $p$ if the kernel should be computed mod $p$. Returns ======= :py:class:`~.Submodule` This submodule's generators span the kernel of this homomorphism over :ref:`ZZ`, or else over :ref:`GF(p)` if a modulus was given. rN)rrr nullspacer r"r@ra)r)rrrtrrrkernels   zModuleHomomorphism.kernel)N)N)rlrmrnroryrrrrrrrs! rcs eZdZdZfddZZS)ModuleEndomorphismz)A homomorphism from one module to itself.cst|||dS)az Parameters ========== domain : :py:class:`~.Module` The common domain and codomain of the mapping. mapping : callable An arbitrary callable is accepted, but should be chosen so as to represent an actual module endomorphism. In particular, should accept and return elements of *domain*. N)superry)r)r@r __class__rrry7szModuleEndomorphism.__init__rlrmrnrory __classcell__rrrrr4srcs eZdZdZfddZZS)InnerEndomorphismzz An inner endomorphism on a module, i.e. the endomorphism corresponding to multiplication by a fixed element. cs t|fdd|_dS)a Parameters ========== domain : :py:class:`~.Module` The domain and codomain of the endomorphism. multiplier : :py:class:`~.ModuleElement` The element $a$ defining the mapping as $x \mapsto a x$. cs|SrVrr multiplierrrZr z,InnerEndomorphism.__init__..N)rryr)r)r@rrr rryNs zInnerEndomorphism.__init__r rrrrr Hsr c@s(eZdZdZddZddZddZdS) rjz&The ring of endomorphisms on a module.cCs ||_dS)z Parameters ========== domain : :py:class:`~.Module` The domain and codomain of the endomorphisms. Nrrrrrryas zEndomorphismRing.__init__cCs t|j|S)a> Form an inner endomorphism belonging to this endomorphism ring. Parameters ========== multiplier : :py:class:`~.ModuleElement` Element $a$ defining the inner endomorphism $x \mapsto a x$. Returns ======= :py:class:`~.InnerEndomorphism` )r r@)r)rrrrinner_endomorphismlsz#EndomorphismRing.inner_endomorphismcsft|tr^|j|jkr^|j\}}|dkr4Sdddfjfddtd|DStdS)a Represent an element of this endomorphism ring, as a single column vector. Explanation =========== Let $M$ be a module, and $E$ its ring of endomorphisms. Let $N$ be another module, and consider a homomorphism $\varphi: N \rightarrow E$. In the event that $\varphi$ is to be represented by a matrix $A$, each column of $A$ must represent an element of $E$. This is possible when the elements of $E$ are themselves representable as matrices, by stacking the columns of such a matrix into a single column. This method supports calculating such matrices $A$, by representing an element of this endomorphism ring first as a matrix, and then stacking that matrix's columns into a single column. Examples ======== Note that in these examples we print matrix transposes, to make their columns easier to inspect. >>> from sympy import Poly, cyclotomic_poly >>> from sympy.polys.numberfields.modules import PowerBasis >>> from sympy.polys.numberfields.modules import ModuleHomomorphism >>> T = Poly(cyclotomic_poly(5)) >>> M = PowerBasis(T) >>> E = M.endomorphism_ring() Let $\zeta$ be a primitive 5th root of unity, a generator of our field, and consider the inner endomorphism $\tau$ on the ring of integers, induced by $\zeta$: >>> zeta = M(1) >>> tau = E.inner_endomorphism(zeta) >>> tau.matrix().transpose() # doctest: +SKIP DomainMatrix( [[0, 1, 0, 0], [0, 0, 1, 0], [0, 0, 0, 1], [-1, -1, -1, -1]], (4, 4), ZZ) The matrix representation of $\tau$ is as expected. The first column shows that multiplying by $\zeta$ carries $1$ to $\zeta$, the second column that it carries $\zeta$ to $\zeta^2$, and so forth. The ``represent`` method of the endomorphism ring ``E`` stacks these into a single column: >>> E.represent(tau).transpose() # doctest: +SKIP DomainMatrix( [[0, 1, 0, 0, 0, 0, 1, 0, 0, 0, 0, 1, -1, -1, -1, -1]], (1, 16), ZZ) This is useful when we want to consider a homomorphism $\varphi$ having ``E`` as codomain: >>> phi = ModuleHomomorphism(M, E, lambda x: E.inner_endomorphism(x)) and we want to compute the matrix of such a homomorphism: >>> phi.matrix().transpose() # doctest: +SKIP DomainMatrix( [[1, 0, 0, 0, 0, 1, 0, 0, 0, 0, 1, 0, 0, 0, 0, 1], [0, 1, 0, 0, 0, 0, 1, 0, 0, 0, 0, 1, -1, -1, -1, -1], [0, 0, 1, 0, 0, 0, 0, 1, -1, -1, -1, -1, 1, 0, 0, 0], [0, 0, 0, 1, -1, -1, -1, -1, 1, 0, 0, 0, 0, 1, 0, 0]], (4, 16), ZZ) Note that the stacked matrix of $\tau$ occurs as the second column in this example. This is because $\zeta$ is the second basis element of ``M``, and $\varphi(\zeta) = \tau$. Parameters ========== element : :py:class:`~.ModuleEndomorphism` belonging to this ring. Returns ======= :py:class:`~.DomainMatrix` Column vector equalling the vertical stacking of all the columns of the matrix that represents the given *element* as a mapping. rNcsg|]}dd|fqSrVrrNrrrrr z.EndomorphismRing.represent..r)r5rr@rr?vstackrPr')r)rrer*rrrr/~sW *zEndomorphismRing.representN)rlrmrnroryrr/rrrrrj^s rjNc Cs|j}|std|dur"g}|d}|||j|d}|}d}td|jdD]} |||j|d} z|| d} Wn$ty| | }||9}YqX0dgddt | D} |pt d}|j rt| ||jd }nt| ||d}qqX|S) a| Find a polynomial of least degree (not necessarily irreducible) satisfied by an element of a finitely-generated ring with unity. Examples ======== For the $n$th cyclotomic field, $n$ an odd prime, consider the quadratic equation whose roots are the two periods of length $(n-1)/2$. Article 356 of Gauss tells us that we should get $x^2 + x - (n-1)/4$ or $x^2 + x + (n+1)/4$ according to whether $n$ is 1 or 3 mod 4, respectively. >>> from sympy import Poly, cyclotomic_poly, primitive_root, QQ >>> from sympy.abc import x >>> from sympy.polys.numberfields.modules import PowerBasis, find_min_poly >>> n = 13 >>> g = primitive_root(n) >>> C = PowerBasis(Poly(cyclotomic_poly(n, x))) >>> ee = [g**(2*k+1) % n for k in range((n-1)//2)] >>> eta = sum(C(e) for e in ee) >>> print(find_min_poly(eta, QQ, x=x).as_expr()) x**2 + x - 3 >>> n = 19 >>> g = primitive_root(n) >>> C = PowerBasis(Poly(cyclotomic_poly(n, x))) >>> ee = [g**(2*k+2) % n for k in range((n-1)//2)] >>> eta = sum(C(e) for e in ee) >>> print(find_min_poly(eta, QQ, x=x).as_expr()) x**2 + x + 5 Parameters ========== alpha : :py:class:`~.ModuleElement` The element whose min poly is to be found, and whose module has multiplication and starts with unity. domain : :py:class:`~.Domain` The desired domain of the polynomial. x : :py:class:`~.Symbol`, optional The desired variable for the polynomial. powers : list, optional If desired, pass an empty list. The powers of *alpha* (as :py:class:`~.ModuleElement` instances) from the zeroth up to the degree of the min poly will be recorded here, as we compute them. Returns ======= :py:class:`~.Poly`, ``None`` The minimal polynomial for alpha, or ``None`` if no polynomial could be found over the desired domain. Raises ====== MissingUnityError If the module to which alpha belongs does not start with unity. ClosureFailure If the module to which alpha belongs is not closed under multiplication. z8alpha must belong to finitely generated ring with unity.NrrrcSsg|] }| qSrrrrrrr8r z!find_min_poly..rr)rWrMrr3rrPr*rrr`r to_list_flatris_FFrr) alphar@rpowersrrTZ powers_matrixakrerZak_colXr#rrr find_min_polys2B       r)r)NN)4rosympy.core.numbersrrsympy.core.symbolrsympy.polys.polyclassesrsympy.polys.polytoolsrsympy.polys.densetoolsr"sympy.polys.domains.algebraicfieldrZsympy.polys.domains.finitefieldr !sympy.polys.domains.rationalfieldr sympy.polys.domains.integerringr Z!sympy.polys.matrices.domainmatrixr Zsympy.polys.matrices.exceptionsrZ sympy.polys.matrices.normalformsrsympy.polys.polyerrorsrrsympy.polys.polyutilsr exceptionsrrr utilitiesrrrr$r%r6rhrrJrrrrr rjrrrrrsP5            q nce