[Previous] [Next] [Contents]

## `Cat::ModuleWithBasis` -- the category of modules over a distinguished basis

#### Introduction

`Cat::ModuleWithBasis` represents the category of modules over a distinguished basis.

#### Generating the category

`Cat::ModuleWithBasis(R)`

#### Details

- A ``Cat::ModuleWithBasis`(R)` is a `Cat::Module(R)` where `R` is a `Cat::Ring`, with as a distinguished basis indexed by some combinatorial class `C` in `Cat::CombinatorialClass`. By this we mean that there exists a (bλ)λ family of elements of the module such that any element x of the module can be represented as a (formal) linear combination x=∑λ cλ bλ with coefficients in `R`. The linear combination may be finite or infinite, and two syntactically different linear combinations may be mathematically equal.

- ``Cat::ModuleWithBasis`(R)` is the basic super category for anything "that looks like a polynomial or a series". This includes for example differential operators or forms, Ore polynomials, elements of combinatorial algebras, and so on.
- The support of x is the set of all λ's such that cλ≠0. The terms and monomials x are respectively the bλ's and cλ bλ's where λ is in the support of x. When the combinatorial class is totally ordered, the leading support, term, and monomial (and their trailing equivalents) are defined in the natural way by extending the usual notions for polynomials. They need not exist when x has an infinite support.
- By default, the method `"_mult"` is set to `operators::_mult`, which in turn uses `operators::mult2`. Furthermore, the later is overloaded with the following signatures and associated implementations:
  - [dom, R] : `"multcoeffs"`
  - [R, dom] : `"multcoeffsLeft"`
  In other words, a `Cat::ModuleWithBasis` just has to implement `"multcoeffs"` and `"multcoeffsLeft"`. Then, `"_mult"` will be implemented appropriately to handle both left and right multiplication by scalars. This differs from the plain `Cat::Module` category for which the domain has to provide this `"_mult"` method. In a future version, this feature will be extended to `Cat::Module`.
- Defaults implementations are provided for most of the methods; they can be quite inefficient though, so it is highly recommended to redefine them. At the very least, the domain just needs to implement the constructor `"monomial"`, and the methods `"toList"` and `"coeff"`.

#### Basic Entries

basisIndices

the combinatorial class `C` of the indices of the basis; it must be a `Cat::CombinatorialClass`.

zero

the zero element

#### Method term: construct a term

- `term(C c)`

- Returns the basis elements indexed by the element `c` of `C`.

#### Method term: term constructor

- `term(C lambda)`

- Returns the term bλ indexed by the element `lambda` of `C`.

#### Method monomial: monomial constructor

- `monomial(R c C lambda)`

- Returns the monomial c bλ indexed by the element `lambda` of `C` with coefficient `c`.

#### Method fromList: constructor from list

- `fromList(list l)`

- `l` should be a list of the form `[[c1,lambda1],,...[ck,lambdak]]`, where `c1,,...ck` belongs to the coefficient ring `R` and `lambda1,,...lambdak` belongs to the combinatorial class `R`. This list does not need to be sorted in any way, and the λi's are not required to be distinct.
- Returns the linear combination c1 bλ1+...+ckbλk described by the list.
- This method is very similar to the poly2list method for MuPAD polynomials.

#### Method toList: list

- `toList(dom x)`

- Returns a list describing the structure of `x`.
- This is the inverse function of `"toList"`.
- This method is very similar to the `poly2list` method for MuPAD polynomials.

#### Method nterms: nterms

- `nterms(dom x)`

- Returns the number of terms of `x`.

#### Method terms: terms

- `terms(dom x)`

- Returns the list of the terms of `x`.

#### Method monomials: monomials

- `monomials(dom x)`

- Returns the list of the monomials of `x`.

#### Method coeffs: coefficients

- `coeffs(dom x)`

- Returns the list of all the non-zero coefficients cλ of `x`.

#### Method coeff: coefficient(s)

- `coeff(dom x)`

- Returns the sequence of all the non-zero coefficients cλ of `x`.

- `coeff(dom x, C lambda)`

- Returns the coefficient cλ of `x` at the index `lambda`.

#### Method lsupport: support of the leading term

- `lsupport(dom x)`

- Returns the support of the leading term of `x`.
- If `x` is zero, then `FAIL` is returned.

#### Method lterm: leading term

- `lterm(dom x)`

- Returns the leading term of `x`.
- If `x` is zero, then the zero of this domain is returned. This convention ensures the compatibility with standard MuPAD polynomials.

#### Method lmonomial: leading monomial

- `lmonomial(dom x)`

- Returns the leading monomial of `x`.
- If `x` is zero, then the zero of this domain is returned. This convention ensures the compatibility with standard MuPAD polynomials.

#### Method lcoeff: leading coefficient

- `lcoeff(dom x)`

- Returns the leading coefficient of `x`.
- If `x` is zero, then the zero of the coefficient ring is returned.

#### Method tsupport: support of the trailing term

- `tsupport(dom x)`

- Returns the support of the trailing term of `x`.
- If `x` is zero, then `FAIL` is returned.

#### Method tterm: trailing term

- `tterm(dom x)`

- Returns the trailing term of `x`.
- If `x` is zero, then the zero of this domain is returned. This convention ensures the compatibility with standard MuPAD polynomials.

#### Method tmonomial: trailing monomial

- `tmonomial(dom x)`

- Returns the trailing monomial of `x`.
- If `x` is zero, then the zero of this domain is returned. This convention ensures the compatibility with standard MuPAD polynomials.

#### Method tcoeff: trailing coefficient

- `tcoeff(dom x)`

- Returns the trailing coefficient of `x`.
- If `x` is zero, then the zero of the coefficient ring is returned.

#### Method nthsupport: support of the n-th term

- `nthsupport(dom x, positive integer n)`

- Returns the support of the `n`-th term of `x`.
- If `n` exceeds strictly the number of terms of `x`, then `FAIL` is returned.

#### Method nthterm: n-th term

- `nthterm(dom x, positive integer n)`

- Returns the `n`-th term of `x`.
- If `n` exceeds strictly the number of terms of `x`, then `FAIL` is returned.

#### Method nthmonomial: n-th monomial

- `nthmonomial(dom x, positive integer n)`

- Returns the `n`-th monomial of `x`.
- If `n` exceeds strictly the number of terms of `x`, then `FAIL` is returned.

#### Method nthcoeff: n-th coefficient

- `nthcoeff(dom x, positive integer n)`

- Returns the `n`-th coefficient of `x`.
- If `n` exceeds strictly the number of terms of `x`, then `FAIL` is returned.

#### Method mapcoeffs: apply a function on all coefficients

- `mapcoeffs(dom x, function f)`

- Returns a copy of `x`, where `f` has been applied on all coefficients.
- `f` should always return elements of the coefficient ring. This is not necessarily checked.

#### Method multcoeffs: (right) multiplication of all coefficients by a constant

- `multcoeffs(dom x, constant c)`

- Returns a copy of `x`, where all the coefficients have been multiplied (on the right) by `c`.

#### Method multcoeffsLeft: left multiplication of all coefficients by a constant

- `multcoeffsLeft(constant c, dom x)`

- Returns a copy of `x`, where all the coefficients have been multiplied on the left by `c`.

- If the ring is commutative, this method and the method `"multcoeffsLeft"` coincide.

#### Changes

- `Cat::ModuleWithBasis` is a new category

[Previous] [Next] [Contents]

MuPAD Combinat, an open source algebraic combinatorics package