Methods (brat)

 

We describe all of the methods associated with the class brat and provide examples.

 

.change_denominator

Given a polynomial—or data equivalent to a polynomial (see arguments)—returns a new brat, equal to the original, whose denominator is the given polynomial.

(Ordered) keyword arguments:

• expression: the polynomial expression. Default: None.
• signature: the signature for the polynomial expression. See denominator signature method. Default: None.

Example

We construct the following rational function: [ H = \dfrac{(1 + x^3)(1 + x^4)(1 + x^5)}{(1 - x)(1 - x^2)(1 - x^3)^2(1 - x^4)(1 - x^5)} ] from a simplified expression. Then we recover this particular expression using change_denominator.

sage: x = polygens(QQ, 'x')[0]
sage: h = (1 + x^3)*(1 + x^4)*(1 + x^5)/((1 - x)*(1 - x^2)*(1 - x^3)^2*(1 - x^4)*(1 - x^5))
sage: h
(x^10 - 2*x^9 + 3*x^8 - 3*x^7 + 4*x^6 - 4*x^5 + 4*x^4 - 3*x^3 + 3*x^2 - 2*x + 1)/(x^16 - 3*x^15 + 4*x^14 - 6*x^
13 + 9*x^12 - 10*x^11 + 12*x^10 - 13*x^9 + 12*x^8 - 13*x^7 + 12*x^6 - 10*x^5 + 9*x^4 - 6*x^3 + 4*x^2 - 3*x + 1)
sage: H = br.brat(h)
sage: H
(1 - 2*x + 2*x^2 - x^3 + x^4 - x^5 + x^7 - x^8 + x^9 - 2*x^10 + 2*x^11 - x^12)/((1 - x)^3*(1 - x^3)^2*(1 - x^4)
*(1 - x^5))

Note that the denominator is $(1 - x)^3(1 - x^3)^2(1 - x^4)(1 - x^5)$, which is not exactly what we want.

sage: H.change_denominator(
    (1 - x) * (1 - x^2) * (1 - x^3)**2 * (1 - x^4) * (1 - x^5)
)
(1 + x^3 + x^4 + x^5 + x^7 + x^8 + x^9 + x^12)/((1 - x)*(1 - x^2)*(1 - x^3)^2*(1 - x^4)*(1 - x^5))

Equivalently:

sage: H.change_denominator(
    signature={
        "coefficient": 1,
        "monomial": (0,), 
        "factors": {
            (1,): 1, (2,): 1, (3,): 2, (4,): 1, (5,): 1
        }
    }
)
(1 + x^3 + x^4 + x^5 + x^7 + x^8 + x^9 + x^12)/((1 - x)*(1 - x^2)*(1 - x^3)^2*(1 - x^4)*(1 - x^5))

 

.denominator

Returns the polynomial in the denominator as a brat.

Example

We build a brat for the following rational function and extract the denominator: [ f(x,y) = \dfrac{1 + xy^2}{1 - x^2y^4}. ]

sage: x, y = polygens(QQ, 'x,y')
sage: f = br.brat(
    numerator=1 + x*y^2,
    denominator=1 - x^2*y^4
)
sage: f
(1 + x*y^2)/(1 - x^2*y^4)
sage: f.denominator()
1 - x^2*y^4

 

.denominator_signature

Returns the dictionary signature for the denominator. The format of the dictionary is as follows. The keys are

• "coefficient": a positive integer.
• "monomial": a degree tuple.
• "factors": dictionary with keys given by tuples and values in the positive integers.

Example

If the variables are ordered as $(x,y,z)$ and the denominator is [ 3xy^3(1 - x^2y)(1 - y^4)^3(1 - xyz)(1 - x^2)^5 ]

Then the dictionary is

sage: d_sig = {
    "coefficient": 3,
    "monomial": (1, 3, 0),
    "factors": {
        (2, 1, 0): 1, 
        (0, 4, 0): 3, 
        (1, 1, 1): 1, 
        (2, 0, 0): 5,
    },
}

We can extract this dictionary by creating a brat with numerator 1.

sage: x, y, z = polygens(ZZ, 'x,y,z')
sage: F = br.brat(1/(3*x*y^3*(1 - x^2*y)*(1 - y^4)^3*(1 - x*y*z)*(1 - x^2)^5))
sage: F
x^-1*y^-3/(3*(1 - x^2)^5*(1 - x*y*z)*(1 - x^2*y)*(1 - y^4)^3)
sage: F.denominator_signature()
{'coefficient': 3,
 'monomial': (1, 3, 0),
 'factors': {(2, 0, 0): 5, (0, 4, 0): 3, (1, 1, 1): 1, (2, 1, 0): 1}}

 

.factor

Returns a new brat object with the numerator polynomial factored.

 

.increasing_order

This is set to True by default—unless it was set to False upon construction. This can be toggled to either True or False. It will affect the print out and the .latex method.

This method is not callable like the rest of the functions on this page. This means it is called without parentheses

Example

We construct the following polynomial and then switch the display order: [ h = t^3 - 6t^2 + 11t - 6. ]

sage: t = polygens(QQ, 't')[0]
sage: h = br.brat(t^3 - 6*t^2 + 11*t - 6)
sage: h
-(6 - 11*t + 6*t^2 - t^3)
sage: h.increasing_order = False
sage: h
t^3 - 6*t^2 + 11*t - 6

 

.invert_variables

Returns the corresponding brat after inverting all of the variables.

Keyword argument:

• ratio: returns the ratio of the original brat divided by the brat with inverted variables. Default: False.

Example 1

We verify that, after inverting the variables of [ E = \dfrac{1 + 26T + 66T^2 + 26T^3 + T^4}{(1 - T)^5}, ] we obtain a $T$-multiple of it.

sage: T = var('T')
sage: E = br.brat(
    numerator=1 + 26*T + 66*T^2 + 26*T^3 + T^4,
    denominator_signature={"coefficient": 1, "monomial": (0,), "factors": {(1,): 5}}
)
sage: E
(1 + 26*T + 66*T^2 + 26*T^3 + T^4)/(1 - T)^5
sage: E.invert_variables()
-(T + 26*T^2 + 66*T^3 + 26*T^4 + T^5)/(1 - T)^5

Now we can show it more clearly.

sage: E.invert_variables()/E
-T

We can achieve this all in one go by using the keyword ratio.

sage: E.invert_variables(ratio=True)
-T

 

.latex

Returns a string that formats the brat in $\LaTeX$ in the '\dfrac{...}{...}' format.

Additional argument:

• factor: factor the numerator polynomial. Default: False.
• split: if true, returns a pair of strings formatted in $\LaTeX$: the first is the numerator and the second is the denominator. Default: False.

Example

We obtain a $\LaTeX$ formatting of the following rational function: [ \dfrac{1 + 2t^2 + 4t^4 + 4t^6 + 2t^8 + t^{10}}{\prod_{i=1}^5(1 - t^i)} . ]

sage: t = var('t')
sage: F = br.brat(
    numerator=1 + 2*t^2 + 4*t^4 + 4*t^6 + 2*t^8 + t^10,
    denominator=prod(1 - t^i for i in range(1, 6))
)
sage: F
(1 + 2*t^2 + 4*t^4 + 4*t^6 + 2*t^8 + t^10)/((1 - t)*(1 - t^2)*(1 - t^3)*(1 - t^4)*(1 - t^5))
sage: F.latex()
'\\dfrac{1 + 2t^2 + 4t^4 + 4t^6 + 2t^8 + t^{10}}{(1 - t)(1 - t^2)(1 - t^3)(1 - t^4)(1 - t^5)}'

By setting split to True, we get the numerator and denominator separated.

sage: F.latex(split=True)
('1 + 2t^2 + 4t^4 + 4t^6 + 2t^8 + t^{10}',
 '(1 - t)(1 - t^2)(1 - t^3)(1 - t^4)(1 - t^5)')

 

.numerator

Returns the polynomial in the numerator of the rational function as a brat.

Example

We build a brat for the following rational function and extract the numerator: [ f(x,y) = \dfrac{1 + xy^2}{1 - x^2y^4}. ]

sage: x, y = polygens(QQ, 'x,y')
sage: f = br.brat(
    numerator=1 + x*y^2,
    denominator=1 - x^2*y^4
)
sage: f
(1 + x*y^2)/(1 - x^2*y^4)
sage: f.numerator()
1 + x*y^2

 

.rational_function

Returns the reduced rational function. The underlying type of this object is not a brat.

This method should be used if you do not want SageMath to convert to a brat after applying operations to the rational function.

Example

We build a brat for the following rational function and extract the rational function: [ f(x,y) = \dfrac{1 + xy^2}{1 - x^2y^4}. ]

sage: x, y = polygens(QQ, 'x,y')
sage: f = br.brat(
    numerator=1 + x*y^2,
    denominator=1 - x^2*y^4
)
sage: f
(1 + x*y^2)/(1 - x^2*y^4)
sage: f.rational_function()
1/(-x*y^2 + 1)

 

.subs

Given a dictionary of the desired substitutions, return the new brat obtained by performing the substitutions.

This works in the same as the subs method for rational functions in SageMath.

Example

We apply some substitutions to the following rational function: [ C(T,Y) = \dfrac{1 + 3Y + 2Y^2 + (2 + 3Y + Y^2)T}{(1 - T)^2} . ]

sage: Y, T = polygens(QQ, 'Y,T')
sage: C = br.brat(
    numerator=1 + 3*Y + 2*Y^2 + (2 + 3*Y + Y^2)*T,
    denominator=(1 - T)^2
)
sage: C
(1 + 2*T + 3*Y + 3*Y*T + 2*Y^2 + Y^2*T)/(1 - T)^2

We set $Y$ to $0$ by applying a substitution.

sage: C.subs({Y: 0})
(1 + 2*T)/(1 - T)^2

Note that some substitutions may yield rational functions that do not satisfy the main assumption, so the output will not be a brat.

sage: C.subs({T: T - 1})
(Y^2*T + Y^2 + 3*Y*T + 2*T - 1)/(T^2 - 4*T + 4)

 

.variables

Returns the polynomial variables used.

Example

We define the following rational function using symbolic variables [ f(x,y,z) = \dfrac{1 + x^2y^2z^2}{(1 - xy)(1 - xz)(1 - yz)} ]

sage: x, y, z = var('x y z')
sage: f = (1 + x^2*y^2*z^2)/((1 - x*y)*(1 - x*z)*(1 - y*z))
sage: F = br.brat(f)
sage: F
(1 + x^2*y^2*z^2)/((1 - y*z)*(1 - x*z)*(1 - x*y))

We extract the variables and note that the type of variables have changed to be polynomial variables.

sage: varbs = F.variables()
sage: varbs
(x, y, z)
sage: type(varbs[0])
<class 'sage.rings.polynomial.multi_polynomial_libsingular.MPolynomial_libsingular'>

 

.write_latex

Writes the brat object to a file formatted in $\LaTeX$. The (default) output is a displayed equation (using \[ and \]) of the brat. There are many parameters to change the format of the output.

Keyword arguments:

• filename: the string for the output filename. Default: None, which will output a timestamp name of the form %Y-%m-%d_%H-%M-%S.tex; for example 1900-12-31_20-42-00.tex.
• just_numerator: write just the numerator. Default: False.
• just_denominator: write just the denominator. Default: False.
• align: format using the align* environment. Default: False.
• factor: factor the numerator polynomial. Default: False.
• line_width: determines the line width in characters for each line of the align* environment. Only used when align is set to True. Default: 120.
• function_name: turns the expression to an equation by displaying the function name. Default: None.
• save_message: turns on the save message at the end. Default: True.

Example 1

We will write the following function to test.tex with all the other parameters set to their defaults: [ \dfrac{1 + xy^2}{1 - x^2y^4} ]

sage: x, y = polygens(QQ, 'x,y')
sage: f = br.brat(
    numerator=1 + x*y^2,
    denominator=1 - x^2*y^4
)
sage: f
(1 + x*y^2)/(1 - x^2*y^4)
sage: f.write_latex(filename='test.tex')
Output saved to test.tex.

Now we will read the contents of test.tex to verify that it was written correctly.

sage: with open('test.tex', 'r') as out_file:
....:     print(out_file.read())
\[
    \dfrac{1 + x y^2}{(1 - x^2y^4)}
\]

Example 2

We write the expanded polynomial to the file binomial.tex: [ (1 + X)^{20} ]

We will print this in an align environment, leaving the line_width at 120 characters, and we'll give this function a name: $B_{20}(X)$.

sage: X = polygens(QQ, 'X')[0]
sage: f = br.brat((1 + X)^20)
sage: f
1 + 20*X + 190*X^2 + 1140*X^3 + 4845*X^4 + 15504*X^5 + 38760*X^6 + 77520*X^7 + 125970*X^8 + 167960*X^9 + 184756*X^10 + 167960*X^11 + 125970*X^12 + 77520*X^13 + 38760*X^14 + 15504*X^15 + 4845*X^16 + 1140*X^17 + 190*X^18 + 20*X^19 + X^20
sage: f.write_latex(
    filename="binomial.tex",
    align=True,
    function_name="B_{20}(X)"
)
Output saved to binomial.tex.

Now we will read the contents of the binomial.tex to verify it correctly saved.

sage: with open("binomial.tex", "r") as output:
....:     print(output.read())
\begin{align*}
    B_{20}(X) &= 1 + 20X + 190X^2 + 1140X^3 + 4845X^4 + 15504X^5 + 38760X^6 + 77520X^7 + 125970X^8 \\ 
    &\quad + 167960X^9 + 184756X^{10} + 167960X^{11} + 125970X^{12} + 77520X^{13} + 38760X^{14} + 15504X^{15} \\ 
    &\quad + 4845X^{16} + 1140X^{17} + 190X^{18} + 20X^{19} + X^{20}
\end{align*}

The polynomial compiles to

[\begin{aligned} B_{20}(X) &= 1 + 20X + 190X^2 + 1140X^3 + 4845X^4 + 15504X^5 + 38760X^6 + 77520X^7 + 125970X^8 \\ &\quad + 167960X^9 + 184756X^{10} + 167960X^{11} + 125970X^{12} + 77520X^{13} + 38760X^{14} + 15504X^{15} \\ &\quad + 4845X^{16} + 1140X^{17} + 190X^{18} + 20X^{19} + X^{20} \end{aligned}]