# pypolyhedralcubature
<!-- badges: start -->
[](http://pypolyhedralcubature.readthedocs.io)
<!-- badges: end -->
*Multiple integration over a convex polytope.*
___
This package allows to evaluate a multiple integral whose integration
bounds are some linear combinations of the variables, e.g.
$$\int\_{-5}^4\int\_{-5}^{3-x}\int\_{-10}^{6-x-y} f(x, y, z)\\,\text{d}z\\,\text{d}y\\,\text{d}x.$$
In other words, the domain of integration is given by a set of linear
inequalities:
$$\left\{\begin{matrix} -5 & \leq & x & \leq & 4 \\\ -5 & \leq & y & \leq & 3-x \\\ -10 & \leq & z & \leq & 6-x-y \end{matrix}\right..$$
These linear inequalities define a convex polytope (in dimension 3, a
polyhedron).
In order to use the package, one has to get the *matrix-vector representation*
of these inequalities, of the form
$$A {(x,y,z)}' \leqslant b.$$
The matrix $A$ and the vector $b$ appear when one rewrites the linear
inequalities above as:
$$\left\{\begin{matrix} -x & \leq & 5 \\\ x & \leq & 4 \\\ -y & \leq & 5 \\\ x+y & \leq & 3 \\\ -z & \leq & 10 \\\ x+y+z & \leq & 6 \end{matrix}\right..$$
The matrix $A$ is given by the coefficients of $x$, $y$, $z$ at the
left-hand sides, and the vector $b$ is made of the upper bounds at the
right-hand sides:
```python
import numpy as np
A = np.array([
[-1, 0, 0], # -x
[ 1, 0, 0], # x
[ 0,-1, 0], # -y
[ 1, 1, 0], # x+y
[ 0, 0,-1], # -z
[ 1, 1, 1] # x+y+z
])
b = np.array([5, 4, 5, 3, 10, 6])
```
The function `getAb` provided by the package allows to get $A$ and $b$ in a
user-friendly way:
```python
from pypolyhedralcubature.polyhedralcubature import getAb
from sympy.abc import x, y, z
# linear inequalities defining the integral bounds
i1 = (x >= -5) & (x <= 4)
i2 = (y >= -5) & (y <= 3 - x)
i3 = (z >= -10) & (z <= 6 - x - y)
# get the matrix-vector representation of these inequalities
A, b = getAb([i1, i2, i3], [x, y, z])
```
Now assume for example that $f(x,y,z) = x(x+1) - yz^2$. Once we have $A$ and
$b$, here is how to evaluate the integral of $f$ over the convex polytope:
```python
from pypolyhedralcubature.polyhedralcubature import integrateOnPolytope
# function to integrate
f = lambda x, y, z : x*(x+1) - y*z**2
# integral of f over the polytope defined by the linear inequalities
g = lambda v : f(v[0], v[1], v[2])
I_f = integrateOnPolytope(g, A, b)
I_f["integral"]
# 57892.275000000016
```
In the case when the function to be integrated is, as in our current example,
a polynomial function, it is better to use the `integratePolynomialOnPolytope`
function provided by the package. This function implements a procedure
calculating the exact value of the integral. Here is how to use it:
```python
from pypolyhedralcubature.polyhedralcubature import integratePolynomialOnPolytope
from sympy import Poly
from sympy.abc import x, y, z
# polynomial to integrate
P = Poly(x*(x+1) - y*z**2, domain = "RR")
# integral of P over the polytope
integratePolynomialOnPolytope(P, A, b)
# 57892.2750000001
```
Actually the exact value of the integral is $57892.275$, so there is a slight
numerical error in the procedure. We can get this exact value by using the
field of rational numbers as the domain of the polynomial:
```python
# polynomial to integrate
P = Poly(x*(x+1) - y*z**2, domain = "QQ")
# integral of P over the polytope
integratePolynomialOnPolytope(P, A, b)
# 2315691/40
```
## Acknowledgments
I am grateful to the StackOverflow user @Davide_sd for the help he provided
regarding the `getAb` function.
Raw data
{
"_id": null,
"home_page": "https://github.com/stla/PyPolyhedralCubature",
"name": "pypolyhedralcubature",
"maintainer": "",
"docs_url": null,
"requires_python": ">=3.10,<3.13",
"maintainer_email": "",
"keywords": "integration,polyhedron,polytope",
"author": "St\u00e9phane Laurent",
"author_email": "laurent_step@outlook.fr",
"download_url": "https://files.pythonhosted.org/packages/3a/2e/7ddaa4b1c3fa2143169aa3b2cb3f647883f8e1b08e848af20e3aceafe94d/pypolyhedralcubature-0.2.0.tar.gz",
"platform": null,
"description": "# pypolyhedralcubature\n\n<!-- badges: start -->\n[](http://pypolyhedralcubature.readthedocs.io)\n<!-- badges: end -->\n\n*Multiple integration over a convex polytope.*\n\n___\n\nThis package allows to evaluate a multiple integral whose integration \nbounds are some linear combinations of the variables, e.g.\n\n$$\\int\\_{-5}^4\\int\\_{-5}^{3-x}\\int\\_{-10}^{6-x-y} f(x, y, z)\\\\,\\text{d}z\\\\,\\text{d}y\\\\,\\text{d}x.$$\n\nIn other words, the domain of integration is given by a set of linear \ninequalities:\n\n$$\\left\\{\\begin{matrix} -5 & \\leq & x & \\leq & 4 \\\\\\ -5 & \\leq & y & \\leq & 3-x \\\\\\ -10 & \\leq & z & \\leq & 6-x-y \\end{matrix}\\right..$$\n\nThese linear inequalities define a convex polytope (in dimension 3, a \npolyhedron). \nIn order to use the package, one has to get the *matrix-vector representation* \nof these inequalities, of the form\n\n$$A {(x,y,z)}' \\leqslant b.$$\n\nThe matrix $A$ and the vector $b$ appear when one rewrites the linear \ninequalities above as:\n\n$$\\left\\{\\begin{matrix} -x & \\leq & 5 \\\\\\ x & \\leq & 4 \\\\\\ -y & \\leq & 5 \\\\\\ x+y & \\leq & 3 \\\\\\ -z & \\leq & 10 \\\\\\ x+y+z & \\leq & 6 \\end{matrix}\\right..$$\n\nThe matrix $A$ is given by the coefficients of $x$, $y$, $z$ at the \nleft-hand sides, and the vector $b$ is made of the upper bounds at the \nright-hand sides:\n\n```python\nimport numpy as np\nA = np.array([\n [-1, 0, 0], # -x\n [ 1, 0, 0], # x\n [ 0,-1, 0], # -y\n [ 1, 1, 0], # x+y\n [ 0, 0,-1], # -z\n [ 1, 1, 1] # x+y+z\n])\nb = np.array([5, 4, 5, 3, 10, 6])\n```\n\nThe function `getAb` provided by the package allows to get $A$ and $b$ in a \nuser-friendly way:\n\n```python\nfrom pypolyhedralcubature.polyhedralcubature import getAb\nfrom sympy.abc import x, y, z\n# linear inequalities defining the integral bounds\ni1 = (x >= -5) & (x <= 4)\ni2 = (y >= -5) & (y <= 3 - x)\ni3 = (z >= -10) & (z <= 6 - x - y)\n# get the matrix-vector representation of these inequalities\nA, b = getAb([i1, i2, i3], [x, y, z])\n```\n\nNow assume for example that $f(x,y,z) = x(x+1) - yz^2$. Once we have $A$ and \n$b$, here is how to evaluate the integral of $f$ over the convex polytope:\n\n```python\nfrom pypolyhedralcubature.polyhedralcubature import integrateOnPolytope\n# function to integrate\nf = lambda x, y, z : x*(x+1) - y*z**2\n# integral of f over the polytope defined by the linear inequalities\ng = lambda v : f(v[0], v[1], v[2])\nI_f = integrateOnPolytope(g, A, b)\nI_f[\"integral\"]\n# 57892.275000000016\n```\n\nIn the case when the function to be integrated is, as in our current example, \na polynomial function, it is better to use the `integratePolynomialOnPolytope` \nfunction provided by the package. This function implements a procedure \ncalculating the exact value of the integral. Here is how to use it:\n\n```python\nfrom pypolyhedralcubature.polyhedralcubature import integratePolynomialOnPolytope\nfrom sympy import Poly\nfrom sympy.abc import x, y, z\n# polynomial to integrate\nP = Poly(x*(x+1) - y*z**2, domain = \"RR\")\n# integral of P over the polytope \nintegratePolynomialOnPolytope(P, A, b)\n# 57892.2750000001\n```\n\nActually the exact value of the integral is $57892.275$, so there is a slight \nnumerical error in the procedure. We can get this exact value by using the \nfield of rational numbers as the domain of the polynomial:\n\n```python\n# polynomial to integrate\nP = Poly(x*(x+1) - y*z**2, domain = \"QQ\")\n# integral of P over the polytope \nintegratePolynomialOnPolytope(P, A, b)\n# 2315691/40\n```\n \n\n## Acknowledgments\n\nI am grateful to the StackOverflow user @Davide_sd for the help he provided \nregarding the `getAb` function.\n ",
"bugtrack_url": null,
"license": "GPL-3.0-only",
"summary": "Multiple integration on convex polytopes.",
"version": "0.2.0",
"project_urls": {
"Documentation": "https://pypolyhedralcubature.readthedocs.io/en/latest/",
"Homepage": "https://github.com/stla/PyPolyhedralCubature"
},
"split_keywords": [
"integration",
"polyhedron",
"polytope"
],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "3b9eb07c0421d16859d423a78425c109e7462b6289e771aeb6e2082965b8ebf2",
"md5": "abba5d72f041c67e9b03ac1028b63977",
"sha256": "d3c44a062b355beadd68255bff02e684c9e5d9f8a0a5a6dd1c360d039f1c5490"
},
"downloads": -1,
"filename": "pypolyhedralcubature-0.2.0-py3-none-any.whl",
"has_sig": false,
"md5_digest": "abba5d72f041c67e9b03ac1028b63977",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.10,<3.13",
"size": 5010,
"upload_time": "2023-11-14T00:18:34",
"upload_time_iso_8601": "2023-11-14T00:18:34.145883Z",
"url": "https://files.pythonhosted.org/packages/3b/9e/b07c0421d16859d423a78425c109e7462b6289e771aeb6e2082965b8ebf2/pypolyhedralcubature-0.2.0-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "3a2e7ddaa4b1c3fa2143169aa3b2cb3f647883f8e1b08e848af20e3aceafe94d",
"md5": "38c35d411d5232637c78cea366a64503",
"sha256": "7f8672601c0272a38c8a1ddc77cf0c78540f22f6cc86dd71e31cc89be73eda07"
},
"downloads": -1,
"filename": "pypolyhedralcubature-0.2.0.tar.gz",
"has_sig": false,
"md5_digest": "38c35d411d5232637c78cea366a64503",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.10,<3.13",
"size": 4579,
"upload_time": "2023-11-14T00:18:35",
"upload_time_iso_8601": "2023-11-14T00:18:35.652198Z",
"url": "https://files.pythonhosted.org/packages/3a/2e/7ddaa4b1c3fa2143169aa3b2cb3f647883f8e1b08e848af20e3aceafe94d/pypolyhedralcubature-0.2.0.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2023-11-14 00:18:35",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "stla",
"github_project": "PyPolyhedralCubature",
"travis_ci": false,
"coveralls": false,
"github_actions": false,
"lcname": "pypolyhedralcubature"
}
JSON
