K i{dZddlmZmZddlmZddlmZddlm 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&dZ'GddZ(Gdde(Z)Gdde(eZ*dZ+d*dZ,GddeZ-Gdde-Z.Gd d!Z/Gd"d#e/Z0Gd$d%e0Z1Gd&d'Z2d+d)Z3y(),aRModules 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)QQ)ZZ) DomainMatrix)DMBadInputError)hermite_normal_form)CoercionFailedUnificationFailed)IntegerPowerable)ClosureFailureMissingUnityErrorStructureError) AlgIntPowersis_rat get_num_denomct|Dcgc] }t|c}gdt|ftjScc}w)z>Transform a list of integer coefficients into a column vector.r)r r len transpose)coeffscs f/mnt/ssd/data/python-lab/Trading/venv/lib/python3.12/site-packages/sympy/polys/numberfields/modules.pyto_colr s8 0A"Q%01As6{3CR H R R TT0sAceZdZdZedZdZedZdZddZ dZ dZ ed Z d Z dd Zd Zd ZdZdZdZddZddZdZdZy)Moduleaf 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`. ct)z(The number of generators of this module.NotImplementedErrorselfs rnzModule.ns "!ct)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. r$r&s rmult_tabzModule.mult_tabs T"!r)cy)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 Nr&s rparentz Module.parent s,r)ct)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 r$r'elts r representzModule.represent%s n"!r)cp|j}|gn|jd}|r|j||S)z Return the list of ancestor modules of this module, from the foundational :py:class:`~.PowerBasis` downward, optionally including ``self``. See Also ======== Module T include_self)r. ancestorsappend)r'r5ras rr6zModule.ancestors~s6 KK)B$!?  HHTNr)cdt|tr|S|j}||jSy)z Return the :py:class:`~.PowerBasis` that is an ancestor of this module. See Also ======== Module N) isinstance PowerBasisr.power_basis_ancestor)r'rs rr<zModule.power_basis_ancestors3 dJ 'K KK =))+ +r)c|jd}|jd}d}t||D]\}}||k(r|}|S|S)z Locate the nearest common ancestor of this module and another. Returns ======= :py:class:`~.Module`, ``None`` See Also ======== Module Tr4N)r6zip)r'othersAoAncasaoas rnearest_common_ancestorzModule.nearest_common_ancestors]^^^ . __$_ /"bk FBRx    r)c6|jjS)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`` )r< number_fieldr&s rrGzModule.number_fields(((*777r)ct|txr3|j|jdfk(xr|jj S)z>Say whether *col* is a suitable column vector for this module.r)r:r shaper(domainis_ZZ)r'cols r is_compat_colzModule.is_compat_cols4#|,^tvvqk1I^cjjN^N^^r)ct|trQd|cxkr|jkr>> 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) r:intr(r eyer to_denserM ValueError make_mod_elt)r'specrPs r__call__zModule.__call__spP dC Q$%7%7##DFFB/48AACD!!$'AB BD$e44r)ct)z6Say whether the module's first generator equals unity.r$r&s rstarts_with_unityzModule.starts_with_unitys!!r)c^t|jDcgc] }|| c}Scc}w)zf Get list of :py:class:`~.ModuleElement` being the generators of this module. )ranger()r'js rbasis_elementszModule.basis_elementss$ "'tvv/AQ///s*c|ddzS)z7Return a :py:class:`~.ModuleElement` representing zero.rr-r&s rzeroz Module.zero sAw{r)c$|jdS)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&s ronez Module.ones ))!,,r)ct)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` r$r'r8s rrazModule.element_from_rationals B"!r)Nctfd|Ds tdt|}|dk(r td|dj}|dk(r|djnt |Dcgc]}|jc}}t j|dftj|Dcgc]}||jz|jz c}}|r t||}j||Scc}wcc}w)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 c3<K|]}|jk(ywN)module).0gr's r z-Module.submodule_from_gens..cs2188t#2sz&Generators must belong to this module.rzNeed at least one generator.rDrO) allrTrr(rPrr zerosr hstackrLrsubmodule_from_matrix) r'genshnf hnf_modulusr(mrjdBs ` rsubmodule_from_genszModule.submodule_from_gens<sN2T22EF F I 6;< < GII!VDGMM/FA/F)G 1L  1vr * 1 1TX3YqQ!''\QUU4J3Y Z #A5A))!1)55 0G3Ys (C2)#C7c|j\}}|jjs td||jk(s tdt |||S)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.rO)rIrJrKrTr( Submodule)r'rwrPrur(s rrqzModule.submodule_from_matrixosO`ww1xx~~67 7DFF{GH Hq..r)cltj|jt}|j |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 rRr(r rq)r'rws rwhole_submodulezModule.whole_submodules+   TVVR ())!,,r)ct|S)z8Form the :py:class:`~.EndomorphismRing` for this module.)EndomorphismRingr&s rendomorphism_ringzModule.endomorphism_rings %%r))FrTN)__name__ __module__ __qualname____doc__propertyr(r+r.r2r6r<rErGrMrWrYr]r_rbrarxrqr|rr-r)rr"r"s ""*"X.W"r$"288*_,5\"0-!"F16f5/n -&r)r"cxeZdZdZdZedZdZdZedZ dZ dZ d Z d Z d Zd Zd ZdZdZy)r;z;The module generated by the powers of an algebraic integer.cd}t|tr||jj}}|j t }||_||_|j|_ d|_ y)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) r:r extminpoly_of_element set_domainr KTdegree_n _mult_tab)r'rrs r__init__zPowerBasis.__init__s[  a (aee..0qA LL ((*r)c|jSrg)rr&s rrGzPowerBasis.number_fields vv r)c>d|jjdS)Nz PowerBasis())ras_exprr&s r__repr__zPowerBasis.__repr__sTVV^^-.a00r)c`t|tr|j|jk(StSrg)r:r;rNotImplementedr'r?s r__eq__zPowerBasis.__eq__s% eZ (66UWW$ $r)c|jSrgrr&s rr(z PowerBasis.n wwr)cR|j|j|jSrgrcompute_mult_tabr&s rr+zPowerBasis.mult_tab" >> !  ! ! #~~r)ct|j}i}|j}t|D]&}i||<t||D]}|||z|||<(||_yrg)rrr(r[r)r' theta_powMr(uvs rrzPowerBasis.compute_mult_tabsn (  FFq +AAaD1a[ +#AE*!Q + +r)ct|j|k(r|jdk(r|jStd)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].)rhrPcolumnrr0s rr2zPowerBasis.represents2 :: #))q.::<  !JK Kr)cy)NTr-r&s rrYzPowerBasis.starts_with_unitysr)c|d|zSNrr-rds rraz PowerBasis.element_from_rationalsAw{r)cx|j|j}}||k\r||jz}|dk(r|jSt |j j td\}}tt|}t|}tdg||z z}t||z}|||S)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)convertrO) r(rrr_rrepto_listr listreversedrr r ) r'fr(krvrellzrLs relement_from_polyzPowerBasis.element_from_poly s vvqxxz1 6DFF A 699;  TB1 ! !f UGq3w QUmCq!!r)c||jjjk7r td|j t ||jj S)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.)rrrrrrgen)r'rmods r_element_from_rep_and_modz$PowerBasis._element_from_rep_and_mod&sI* $&&**$$& &#$VW W%%d3 &;< 1TZZL! !Ar)c|jdk(r|St|jg|j}|dk(r|St||j|j |z j t|j|z|jS)af Produce a reduced version of this submodule. Explanation =========== In the reduced version, it is guaranteed that 1 is the only positive integer dividing both the submodule's denominator, and every entry in the submodule's matrix. Returns ======= :py:class:`~.Submodule` rrPr+) rPrrtyper.r convert_tor rr'rjs rreducedzSubmodule.reducedksu" ::?K  *dkk * 6KtDz$++ a'C'CB'Gtzz]^imiwiwxxr)c.|jdd|df}|j|z }d}|j}|?i}t|D]/}i||<t||D]}|||z||z|d|||<1t |j ||j |S)ze Produce a new module by discarding all generators before a given index *r*. Nr)rr(rr[rzr.rP)r'rWsrmtrrs rdiscard_beforezSubmodule.discard_befores KK12  FFQJ  ^^ >A1X 3!q!3A QiA.qr2AaDG3 3atzzAFFr)c|jSrgrr&s rr(z Submodule.nrr)cR|j|j|jSrgrr&s rr+zSubmodule.mult_tabrr)c|j}i}|j}t|D]F}i||<t||D]0}|j||||zj |||<2H||_yrg)basis_element_pullbacksr(r[r2flatr)r'rrrr(rrs rrzSubmodule.compute_mult_tabs++-  FFq CAAaD1a[ C..a47):;@@B!Q C Cr)c|jSrg)rr&s rr.zSubmodule.parent ||r)c|jSrg)rr&s rrzSubmodule.matrixrr)c6|jjSrg)rrr&s rrzSubmodule.coeffss{{!!r)c|jSrg)rr&s rrPzSubmodule.denoms {{r)c|j,|j|jz 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` )rrrPrSr&s r QQ_matrixzSubmodule.QQ_matrixs6D ?? "#{{TZZ7AACDOr)cj|j|djd|_|jS)Nrr)requivr&s rrYzSubmodule.starts_with_unitys/  " " *&*1gmmA&6D #&&&r)cf|jt|j|_|jSrg)ris_sq_maxrank_HNFrr&s rrzSubmodule.is_sq_maxrank_HNFs+  " " *&7 &ED #&&&r)c6t|jtSrg)r:r.r;r&s ris_power_basis_submodulez"Submodule.is_power_basis_submodules$++z22r)cn|jr |d|zS|jj|Sr)rYr.rards rrazSubmodule.element_from_rationals1  ! ! #7Q; ;;44Q7 7r)cd|jDcgc]}|jc}Scc}w)zv Return list of this submodule's basis elements as elements of the submodule's parent module. )r] to_parentr'es rrz!Submodule.basis_element_pullbackss' (,':':'<=! ===s-c0|j|k(r|jS|j|jk(rR |j}|j}|j |dj }|jt}|St|jtr=|jj|}|j|}|j|Std#t$r tdt$r tdwxYw)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.)rhrr.rQQ_col_solverrr rrrr:rzr2)r'r1Abxcoeffs_in_parentparent_elements rr2zSubmodule.represents :: ::<  ZZ4;; & ZNNJJHHQKN,,.LL$ H  Y /#{{44S9 ![[)9:N>>.1 1 !QR R# O$%MNN! Z$%XYY Zs AC--(DcXt|txr|j|jk(Srg)r:rzr.rs ris_compat_submodulezSubmodule.is_compat_submodules!%+K  0KKr)cb|j|r|j|jk(StSrg)rrrrs rrzSubmodule.__eq__s)  # #E *??dnn4 4r)c |j|j}}t||}||z||z}}||jzj||jz} |r t | |} |j j | |S)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` rlrO)rPrrrprr.rq) r'r?rsrtrvrrur8rrws raddz Submodule.add"s{8zz5;;1 AJAvqAv1 _ $ $Q%5 6 #A5A{{00!0<|jDcgc]}||z }}|jj|||S|j|rY|j|j} }|Dcgc]}| D]}||z }}}|jj|||StScc}wcc}}w)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` rNr)rsrt)rrrzr.rrPrr: ModuleElementrhrrxrr) r'r?rsrtr8rrrralphasbetass rmulz Submodule.mulMs7D %= 'DAqA{{ !![[1_DJJN&*,,3GI6} -%,,$++2M(,'C'C'EF!EAIFDF;;224Sk2Z Z  % %e ,!88:E>> 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) rhr.r%rrrr[r(rrP)r'r1msgrwr8irqs rreduce_elementzSubmodule.reduce_elementsvzzT[[(% %%%'OC % %  ( ( * tvvz2r* A!A AGG# AGG(;!SFL "=H H5nHFr)rzc:|jjr|jry|jrm|jd}t |D]O}|||fj }|dkryt |dz|D]#}d|||fj cxkr|kryyQyy)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)rJrK is_squareis_upperrIr[element)dmr(rrvr\s rrrs$ yy2< 1TZZL! !A2sAc|jdk(r|St|jg|j}|dk(r|St||j|j |z j t|j|zS)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. rrO)rPrrrrhrLrr rs rrzModuleElement.reduced"sq ::?K  *dkk * 6KtDz$++!XX\55b9"&**/3 3r)ct|j|jjt |jt |j S)z Produce a version of this :py:class:`~.ModuleElement` in which all numerator coefficients have been reduced mod *p*. rO)rUrhrLrr r rP)r'ps r reduced_mod_pzModuleElement.reduced_mod_p0s? DKK HH//16AA"E"&**. .r)c.t|}||||S)zn Make a :py:class:`~.ModuleElement` from a list of ints (instead of a column vector). rO)r )clsrhrrPrLs r from_int_listzModuleElement.from_int_list9s Vn63e,,r)c.|jjS)z$The length of this element's column.)rhr(r&s rr(zModuleElement.nB{{}}r)c|jSrg)r(r&s r__len__zModuleElement.__len__Gs vv r)Ncp||jjS|jj|S)zY Get a copy of this element's column, optionally converting to a domain. )rLcopyrr'rJs rrzModuleElement.columnJs. >88==? "88&&v. .r)c6|jjSrg)rLrr&s rrzModuleElement.coeffsSsxx}}r)c|j,|j|jz 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 )rrLrPrSr&s rrzModuleElement.QQ_colWs5 <<  HHtzz1;;=DL||r)ct|jts tdt |jj |jj |jz|jj|jzS)zx Transform into a :py:class:`~.ModuleElement` belonging to the parent of this element's module. zNot an element of a Submodule.rO) r:rhrzrTrUr.rrLrPr&s rrzModuleElement.to_parentgsc $++y1=> > KK   2 2TXX =++##djj02 2r)cb||jk(r|S|jj|S)z Transform into a :py:class:`~.ModuleElement` belonging to a given ancestor of this element's module. Parameters ========== anc : :py:class:`~.Module` )rhr to_ancestor)r'ancs rr1zModuleElement.to_ancestorrs- $++ K>>#//4 4r)c|}t|jts+|j}t|jts+|S)zv Transform into a :py:class:`~.PowerBasisElement` over our :py:class:`~.PowerBasis` ancestor. )r:rhr;rrs rover_power_basiszModuleElement.over_power_basiss7 QXXz2 AQXXz2r)cXt|txr|j|jk(S)ze Test whether other is another :py:class:`~.ModuleElement` with same module. )r:rrhrs r is_compatzModuleElement.is_compats# %/OELLDKK4OOr)c|j|jk(r||fS|jj|j}|"|j||j|fStd|d|)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. z Cannot unify z with )rhrEr1r)r'r?rBs runifyzModuleElement.unifyst4 ;;%,, &; kk11%,,? ?##C(%*;*;C*@@ @-vVE7 CDDr)cb|j|r|j|jk(StSrg)r6rrrs rrzModuleElement.__eq__s' >>% ;;%,,. .r)c||k(ryt|tr|j|\}}||k(St|rFt|tr||j d|zk(S|j j|Sy)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)r:rr8rrrhr4r)r'r?r8rs rrzModuleElement.equivs{D 5= } -::e$DAq6M E]$ 12t{{1~555,,.44U;;r)c J|j|r|j|j}}t||}||z||z}}tt |j |j Dcgc]\}}||z||zzc}}} t ||j| |jSt|tr |j|\}}||zSt|r||jj|zStScc}}w#t$r tcYSwxYw)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``. rO)r6rPrr r>rrrhrr:rr8rrrra) r'r?rvrrurrr8rrLs rrzModuleElement.__add__s >>% ::u{{qAQ A616qAC U\\4RSDAq!a%!a%-STC4:dkk3a8@@B B } - &zz%(1q5L E]$++;;EBB BT % &%% &s(D DD"!D"c |dzS)Nr r-r&s r__neg__zModuleElement.__neg__ s byr)c|| zSrgr-rs r__sub__zModuleElement.__sub__ svr)c| |zSrgr-rs r__rsub__zModuleElement.__rsub__suu}r)c |j|r|jj}|jj |jj }}|j }dg|z}t |D]b}t ||D]Q}||||z} ||kDr| ||||zz } | dk7s'|||} t |D]} || xx| | | zz cc<Sd|j|jz} |j|j|| St|tr |j|\} }| |zSt|r\t|\} }| |cxk(rdk(r|St!|j|j| z|j|zj#StS#t$r tcYSwxYw)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. rrOr)r6rhr+rLrr(r[rPr%r:rr8rrrrrUr)r'r?rrrwr(CrrrRrrvr8rs rrzModuleElement.__mul__s$ >>%  $$&A88==?EIINN$4qAAaA1X -q!-A!qt A1uQqTAaD[(AvaDG!&q-AaDA!H,D- - - U[[(A%%dkk1A%> > } - &zz%(1q5L E] 'DAqA{{ $DKK!%ATZZ!^EELWYO% &%% &s+F11GGc6|jjSrg)rhrbr&s r _zeroth_powerzModuleElement._zeroth_powerEs{{  r)c|Srgr-r&s rr zModuleElement._first_powerHr r)czt|rt|}|d|z zSt|tr|d|zzStS)Nr)rr r:rrrds r __floordiv__zModuleElement.__floordiv__Ks> !91A1Q3<  = )1a4= r)c(||jzSrg)r4rds r __rfloordiv__zModuleElement.__rfloordiv__SsD))+++r)ct|r||jjz}t|tr*|j |jk(r|j |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 )rrhr|r:rzr.rr)r'rus r__mod__zModuleElement.__mod__VsR$ !9DKK//11A a #DKK(?##D) )r)rrg)#rrrrrrrr" classmethodr%rr(r)rrrrr1r4r6r8rrrrr=r?rArrrFr rIrKrMr-r)rrrs& 3.--/   25 PEB ,\@H/bH!,r)rceZdZdZedZddZddZedZedZ ddZ dd Z d Z d Z dd Zd ZdZy)rzl Subclass for :py:class:`~.ModuleElement` instances whose module is a :py:class:`~.PowerBasis`. c.|jjS)z?Access the defining polynomial of the :py:class:`~.PowerBasis`.)rhrr&s rrzPowerBasisElement.Tur'r)Nc|xs|jj}tt|j|t S)z4Obtain the numerator as a polynomial over :ref:`ZZ`.rJ)rrrrrr r'rs r numeratorzPowerBasisElement.numeratorzs+ OHT[[)1R88r)c@|j||jzS)z1Obtain the number as a polynomial over :ref:`QQ`.r)rTrPrSs rpolyzPowerBasisElement.polys~~~"djj00r)c@|jddddfjS)z6Say whether this element represents a rational number.rN)rLis_zero_matrixr&s r is_rationalzPowerBasisElement.is_rationalsxxA---r)c|jj}|r,|jjr|jjS|j j S)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. )rhrGr is_aliasedaliasrrr'rs r generatorzPowerBasisElement.generators< KK $ $AEE$4$4quu{{D$&&**Dr)c\|j|xs |jjS)z)Create a Basic expression from ``self``. )rWr_rrSs rrzPowerBasisElement.as_exprs#yy,dnn-5577r)c|xs |j}|j}|j|}|j||j|j zzS)z Compute the norm of this number.rV)rrrT resultantrPr()r'rrrs rnormzPowerBasisElement.normsH K EE NNQN {{1~tvv!555r)c|j}|j|j}|jj |Srg)rWinvertrrhr)r'rf_invs rinversezPowerBasisElement.inverses4 IIK {{,,U33r)c(|j|zSrg)rgrds rrKzPowerBasisElement.__rfloordiv__s||~!!r)c:|jt|zSrg)rgabs)r'rmodulos r_negative_powerz!PowerBasisElement._negative_powers||~Q''r)cttt|jj t j |jjjt S)z,Convert to an equivalent :py:class:`~.ANP`. ) rrrrrr maprrrr&s rto_ANPzPowerBasisElement.to_ANPsC4!1!1!345rvvdffjj>P>P>R7SUWXXr)c|jj}|r|j|jSt d)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 AlgebraicField)rhrG to_alg_numrorr^s rrqzPowerBasisElement.to_alg_nums7: KK $ $ << . .;<>> 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)rJcodomainmapping)r'rJrurvs rrzModuleHomomorphism.__init__s:    r)Nc|jj}|Dcgc],}|jj|j |.}}|s>t j |jjdftjS|dj|dd}|r|jt|}|Scc}w)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. rrN) rJr]rur2rvr ror(r rSrprr )r'modulusbasisr1colsrs rrzModuleHomomorphism.matrixs& **,FKLs '' S(9:LL%%t}}&:B?HHJ J DGNNDH %  R[)A Ms1Cc|j|}||jt}|jjtj }|j 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. rx)rrr nullspacer rrJrq)r'rxrrs rkernelzModuleHomomorphism.kernels]( KKK ( ? R A KKM $ $R ( 2 2 4{{0033r)rg)rrrrrrr~r-r)rrsrss5B8"4r)rsc"eZdZdZfdZxZS)ModuleEndomorphismz)A homomorphism from one module to itself.c(t||||y)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)superr)r'rJrv __class__s rrzModuleEndomorphism.__init__:s 1r)rrrrr __classcell__rs@rrr7s422r)rc"eZdZdZfdZxZS)InnerEndomorphismzz An inner endomorphism on a module, i.e. the endomorphism corresponding to multiplication by a fixed element. c<t||fd|_y)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$. c|zSrgr-)r multipliers rz,InnerEndomorphism.__init__..]s :>r)N)rrr)r'rJrrs `rrzInnerEndomorphism.__init__Qs !9:$r)rrs@rrrKs % %r)rc"eZdZdZdZdZdZy)r~z&The ring of endomorphisms on a module.c||_y)z Parameters ========== domain : :py:class:`~.Module` The domain and codomain of the endomorphisms. NrRr,s rrzEndomorphismRing.__init__ds  r)c.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` )rrJ)r'rs rinner_endomorphismz#EndomorphismRing.inner_endomorphismos !j99r)c t|trt|j|jk(r[|j}|j\}}|dk(r|S|dddfj t d|Dcgc] }|dd|f c}Stcc}w)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. rNr)r:rrJrrIvstackr[r%)r'rrrur(r\s rr2zEndomorphismRing.representsn g1 2w~~7T A77DAqAv!1QT7>>U1a[#AAadG#AB B!!$Bs1B N)rrrrrrr2r-r)rr~r~as1 :$_"r)r~Nc|j}|js td|g}|d}|j||j |}|}d}t d|j dzD]} |j||j |} |j| d} dgt| jD cgc]} | c} z} |xs td}|jrt| ||j}|St| ||}|S|Scc} w#t$r|j| }||z}YwxYw)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.NrrRrrr|)rhrYrr7rr[r(rr to_list_flatris_FFrrrrp)alpharJrpowersrDrb powers_matrixakrurak_colXrrs r find_min_polyrsYD  A    Z[[ ~ A$C MM#JJfJ-M B A 1accAg  b&) $$V,Q/AS1A(BC1QBCCFU3ZA||FJJ7  H62  H'& HD )008M %KB sD* D%*E  E r)NN)4rsympy.core.intfuncrrsympy.core.symbolrsympy.polys.polyclassesrsympy.polys.polytoolsrsympy.polys.densetoolsr"sympy.polys.domains.algebraicfieldr sympy.polys.domains.finitefieldr !sympy.polys.domains.rationalfieldr sympy.polys.domains.integerringr !sympy.polys.matrices.domainmatrixr sympy.polys.matrices.exceptionsr sympy.polys.matrices.normalformsrsympy.polys.polyerrorsrrsympy.polys.polyutilsr exceptionsrrr utilitiesrrrr r"r;rzrrUrrrsrrr~rr-r)rrsrh*#'&3=.0.:;@D2II::U k&k&\KXKX\J(JZ > 7l$l^ `= `=Fb4b4J2+2(%*%,""D_ r)