{"id":25059944,"url":"https://github.com/stla/ratioofqsprays","last_synced_at":"2025-03-31T11:15:06.639Z","repository":{"id":231437659,"uuid":"781765848","full_name":"stla/ratioOfQsprays","owner":"stla","description":"Fractions of multivariate polynomials with rational coefficients.","archived":false,"fork":false,"pushed_at":"2024-08-04T04:26:48.000Z","size":229,"stargazers_count":0,"open_issues_count":0,"forks_count":0,"subscribers_count":2,"default_branch":"main","last_synced_at":"2024-08-18T09:55:53.381Z","etag":null,"topics":["multivariate-polynomials","polynomials","r","rational-functions"],"latest_commit_sha":null,"homepage":"","language":"R","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":null,"status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/stla.png","metadata":{"files":{"readme":"README.Rmd","changelog":"NEWS.md","contributing":null,"funding":null,"license":null,"code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2024-04-04T01:52:33.000Z","updated_at":"2024-08-04T04:26:51.000Z","dependencies_parsed_at":"2025-02-06T15:56:05.792Z","dependency_job_id":"dbaa05f3-e09a-496d-aaff-72efae24047a","html_url":"https://github.com/stla/ratioOfQsprays","commit_stats":null,"previous_names":["stla/ratioofqsprays"],"tags_count":0,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/stla%2FratioOfQsprays","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/stla%2FratioOfQsprays/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/stla%2FratioOfQsprays/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/stla%2FratioOfQsprays/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/stla","download_url":"https://codeload.github.com/stla/ratioOfQsprays/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":246458010,"owners_count":20780678,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["multivariate-polynomials","polynomials","r","rational-functions"],"created_at":"2025-02-06T15:55:58.950Z","updated_at":"2025-03-31T11:15:06.611Z","avatar_url":"https://github.com/stla.png","language":"R","funding_links":[],"categories":[],"sub_categories":[],"readme":"---\ntitle: \"The 'ratioOfQsprays' package\"\nauthor: \"Stéphane Laurent\"\ndate: \"`r Sys.Date()`\"\noutput: github_document\n---\n\n***Fractions of multivariate polynomials with rational coefficients.***\n\n\u003c!-- badges: start --\u003e\n[![R-CMD-check](https://github.com/stla/ratioOfQsprays/actions/workflows/R-CMD-check.yaml/badge.svg)](https://github.com/stla/ratioOfQsprays/actions/workflows/R-CMD-check.yaml)\n\u003c!-- badges: end --\u003e\n\n___\n\nThe [**qspray** package](https://github.com/stla/qspray) allows arithmetic \n(and more) on multivariate polynomials with rational coefficients. Based on \nthis one, the **ratioOfQsprays** package allows to manipulate *fractions* of\nmultivariate polynomials with rational coefficients.\n\nThese notes about the **ratioOfQsprays** package assume that the reader is a \nbit familiar with the **qspray** package.\n\n```{r setup, include=FALSE}\nknitr::opts_chunk$set(echo = TRUE, collapse = TRUE, message = FALSE)\n```\n\n\n## Creating a `ratioOfQsprays` \n\nA `ratioOfQsprays` object represents a fraction of two multivariate \npolynomials with rational coefficients. Such polynomials are represented by \n`qspray` objects. The easiest way to create a `ratioOfQsprays` is to introduce \nthe variables of the polynomials with the `qlone` function (from the **qspray** \npackage), and then to build a `qspray` numerator and a `qspray` denominator \nwith the arithmetic operations. For example:\n\n```{r}\nlibrary(ratioOfQsprays)\nf \u003c- function(x1, x2, x3) {\n  (2*x1^2 + x2*x3) / (4*x1 - 3*x3 + 1)\n}\n# variables:\nx1 \u003c- qlone(1)\nx2 \u003c- qlone(2)\nx3 \u003c- qlone(3)\n# the 'ratioOfQsprays':\n( roq \u003c- f(x1, x2, x3) )\n```\n\nThe denominator of a `ratioOfQsprays` fraction of polynomials is always *monic*. \nThat means it is a polynomial whose leading coefficient is 1.\n\nArithmetic on `ratioOfQsprays` objects is available:\n\n```{r}\nroq^2\nroq - roq\n1 / roq\n2*roq + (x2 + x3)/x1\n```\n\nYou don't like my quotient bar `%//%`? Be patient, we will see how to change \nit later. I adopted this large quotient bar because it is more easy to find \nit than a single slash `/` in a `ratioOfQsprays` having a long expression.\n\nRational numbers and `qspray` polynomials are coercible to \n`ratioOfQsprays` objects, and then you can also perform arithmetic operations \nbetween a `ratioOfQsprays` and such an object:\n\n```{r}\n2 * roq\n\"1/2\" * roq\nroq + gmp::as.bigq(\"7/3\") \nx1 + roq + x3^2\n```\n\nThe result of an arithmetic operation is always an irreducible fraction. \nTo perform this step, the C++ library **CGAL** is used to compute a greatest \ncommon divisor of the numerator and the denominator of the possibly non-reduced \nfraction resulting from the arithmetic operation, and then to divide both of \nthem by this greatest common divisor. This is very efficient in general.\n\n\n## Evaluating a `ratioOfQsprays` \n\nUse `evalRatioOfQsprays` to evaluate a `ratioOfQsprays`. This function returns \na `bigq` number:\n\n```{r}\nlibrary(gmp) # rational numbers\nx \u003c- c(\"4\", \"3\", \"2/5\")\nevalRatioOfQsprays(roq, x)\nx \u003c- as.bigq(x)\nevalRatioOfQsprays(roq, x)\nf(x[1], x[2], x[3])\n```\n\nIt is also possible to substitute some values to only a subset of the \nvariables, with the help of the function `substituteRatioOfQsprays`. You have \nto indicate the variables you don't want to replace with `NA`:\n\n```{r}\nx \u003c- c(NA, \"3\", \"2/5\")\nsubstituteRatioOfQsprays(roq, x)\nx \u003c- as.bigq(x)\nf(x1, x[2], x[3])\n```\n\nAnd it is possible to convert a `ratioOfQsprays` to a function which is \nevaluated by **Ryacas**:\n\n```{r}\nfyac \u003c- as.function(roq)\nfyac(\"4\", \"3\", \"2/5\") # = evalRatioOfQsprays(roq, c(\"4\", \"3\", \"2/5\"))\n```\n\nActually you can pass some literal variables to this function:\n\n```{r}\nfyac(\"x\", \"3\", \"2/5\") # = substituteRatioOfQsprays(roq, c(NA, \"3\", \"2/5\"))\nfyac(\"x\", \"y\", \"z\")   # = roq\nfyac(\"x\", \"x\", \"x\")\n```\n\nComplex numbers are allowed; the imaginary unit is denoted by `I`. See the \n[**Yacas** documentation](https://yacas.readthedocs.io/en/latest/) for more\ninformation.\n\n```{r}\nfyac(\"Sqrt(2)\", \"2 + 2*I\", \"3\")\n```\n\nYou can get numerical approximations by setting the option `N=TRUE` in \n`as.function`:\n\n```{r}\nfyacN \u003c- as.function(roq, N = TRUE)\nfyacN(\"4\", \"3\", \"2/5\") \nfyacN(\"x\", \"3\", \"2/5\")\nfyacN(\"Sqrt(2)\", \"2 + 2*I\", \"3\")\n```\n\nLet us also mention the `substituteSomeRatioOfQsprays` function. This function \nallows to substitute the variables of a `ratioOfQsprays` fraction of polynomials \nwith some `ratioOfQsprays` objects.\n\n\n## Querying a `ratioOfQsprays` \n\nA couple of functions to query a `ratioOfQsprays` are available:\n\n```{r}\ngetNumerator(roq)\ngetDenominator(roq)\nnumberOfVariables(roq)\nisConstant(roq)\nisConstant(roq / roq)\nisUnivariate(roq)\nisUnivariate(x1 / (x1^2 + 1))\nisPolynomial(roq)\nisPolynomial((x1^2 - x2^2) / (x1 - x2))\n```\n\n\n## Showing a `ratioOfQsprays` \n\nAs you have seen, the variables of `roq` are denoted by `x`, `y`, `z`. This is \nthe default way of printing a `ratioOfQsprays` which has no more than three \nvariables. If it has more than three variables, then they are denoted by \n`x1`, `x2`, `x3`, ...:\n\n```{r}\nx4 \u003c- qlone(4)\nroq / x4\n```\n\nIt is possible to control the way a `ratioOfQsprays` is printed. For example, \nlet's say you want to print `roq` by using `a1`, `a2`, `a3` for the variables \nand you want to change the symbol for the quotient bar:\n\n```{r}\nshowRatioOfQspraysOption(roq, \"x\") \u003c- \"a\"\nshowRatioOfQspraysOption(roq, \"quotientBar\") \u003c- \" / \" \nroq\n```\n\nNow, if you perform an arithmetic operation between `roq` *at first position* \nand an another `ratioOfQsprays`, these show options are passed to the result if\npossible:\n\n```{r}\nroq + (x1 + 1)/x2\n```\n\nIf you perform an arithmetic operation between `roq` and an object coercible to \na `ratioOfQsprays` object but which is not a `ratioOfQsprays` object, such as a\n`bigq` number or a `qspray` object, the show options of `roq` are passed to \nthe result, even if `roq` is not at the first position:\n\n```{r}\nx1 * roq\n```\n\nAn obvious example of a situation in which it is not always possible to \ntransfer the show options is when you use three letters for the variables, e.g.\n\n```{r}\nshowRatioOfQspraysOption(roq, \"showQspray\") \u003c- showQsprayXYZ(c(\"A\", \"B\", \"C\"))\nroq\n```\n\nbut then you add to `roq` a `ratioOfQsprays` containing the fourth variable:\n\n```{r}\nroq + x4/(x4 + 1)\n```\n\nObviously it is not possible to denote the resulting fraction of polynomials \nwith the letters `A`, `B` and `C`. The solution I adopted consists in \ntaking the first of these letters and to index it. The same method is used \nfor the `qspray` polynomials.\n\n\n## Transforming a `ratioOfQsprays`\n\nLet's take a `ratioOfQsprays` fraction of polynomials:\n\n```{r}\nf \u003c- function(x, y, z) {\n  (2*x^2 + y*z) / (4*x - 3*z + 1)\n}\nx \u003c- qlone(1); y \u003c- qlone(2); z \u003c- qlone(3)\nroq \u003c- f(x, y, z)\n```\n\nYou can differentiate it:\n\n```{r}\nderivRatioOfQsprays(roq, 2) # derivative w.r.t. y\n```\n\nYou can permute its variables:\n\n```{r}\nswapVariables(roq, 2, 3) == f(x, z, y)\n```\n\nYou can perform some polynomial changes of its variables:\n\n```{r}\nchangeVariables(roq, list(x+1, y^2, x+y+z)) == f(x+1, y^2, x+y+z)\n```\n\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fstla%2Fratioofqsprays","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fstla%2Fratioofqsprays","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fstla%2Fratioofqsprays/lists"}