{"id":17038197,"url":"https://github.com/bchao1/poissonpy","last_synced_at":"2025-04-28T14:48:40.333Z","repository":{"id":113819653,"uuid":"496199540","full_name":"bchao1/poissonpy","owner":"bchao1","description":"📈 poissonpy is a Python Poisson Equation library for scientific computing, image and video processing, and computer graphics.","archived":false,"fork":false,"pushed_at":"2022-05-28T07:39:05.000Z","size":21431,"stargazers_count":14,"open_issues_count":0,"forks_count":1,"subscribers_count":2,"default_branch":"master","last_synced_at":"2025-03-30T10:41:31.708Z","etag":null,"topics":["differential-equations","image-processing","pde","pde-solver","poisson","poisson-equation","scientific-computing"],"latest_commit_sha":null,"homepage":"","language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"other","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/bchao1.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","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":"2022-05-25T11:21:19.000Z","updated_at":"2024-12-11T02:47:26.000Z","dependencies_parsed_at":null,"dependency_job_id":"531c4e3a-1d8f-4bb1-b533-541cc58c822c","html_url":"https://github.com/bchao1/poissonpy","commit_stats":null,"previous_names":[],"tags_count":0,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/bchao1%2Fpoissonpy","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/bchao1%2Fpoissonpy/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/bchao1%2Fpoissonpy/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/bchao1%2Fpoissonpy/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/bchao1","download_url":"https://codeload.github.com/bchao1/poissonpy/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":251334073,"owners_count":21572943,"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":["differential-equations","image-processing","pde","pde-solver","poisson","poisson-equation","scientific-computing"],"created_at":"2024-10-14T08:56:14.897Z","updated_at":"2025-04-28T14:48:40.322Z","avatar_url":"https://github.com/bchao1.png","language":"Python","funding_links":[],"categories":[],"sub_categories":[],"readme":"# poissonpy\nPlug-and-play standalone library for solving 2D Poisson equations. Useful tool in scientific computing prototyping, image and video processing, computer graphics.\n\n## Features\n- Solves the Poisson equation on sqaure or non-square rectangular grids.\n- Solves the Poisson equation on regions with arbitrary shape.\n- Supports arbitrary boundary and interior conditions using `sympy` function experssions or `numpy` arrays.\n- Supports Dirichlet, Neumann, or mixed boundary conditions.\n\n## Disclaimer\nThis package is only used to solve 2D Poisson equations. If you are looking for a general purpose and optimized PDE library, you might want to checkout the [FEniCSx project](https://fenicsproject.org/index.html).\n\n## Usage \nImport necessary libraries. `poissonpy` utilizes `numpy` and `sympy` greatly, so its best to import both:\n\n```python\nimport numpy as np\nfrom sympy import sin, cos\nfrom sympy.abc import x, y\n\nfrom poissonpy import functional, utils, sovlers\n```\n\n### Defining `sympy` functions\nIn the following examples, we use a ground truth function to create a mock Poisson equation and compare the solver's solution with the analytical solution. \n   \nDefine functions using `sympy` function expressions or `numpy` arrays:\n\n```python\nf_expr = sin(x) + cos(y) # create sympy function expression\nlaplacian_expr = functional.get_sp_laplacian_expr(f_expr) # create sympy laplacian function expression\n\nf = functional.get_sp_function(f_expr) # create sympy function\nlaplacian = functional.get_sp_function(laplacian_expr) # create sympy function\n```\n\n### Dirichlet Boundary Conditions\nDefine interior and Dirichlet boundary conditions:\n\n```python\ninterior = laplacian\nboundary = {\n    \"left\": (f, \"dirichlet\"),\n    \"right\": (f, \"dirichlet\"),\n    \"top\": (f, \"dirichlet\"),\n    \"bottom\": (f, \"dirichlet\")\n}\n```\n\nInitialize solver and solve Poisson equation:\n\n```python\nsolver = Poisson2DRectangle(((-2*np.pi, -2*np.pi), (2*np.pi, 2*np.pi)), \n    interior, boundary, X=100, Y=100)\nsolution = solver.solve()\n```\n\nPlot solution and ground truth:\n```python\npoissonpy.plot_3d(solver.x_grid, solver.y_grid, solution)\npoissonpy.plot_3d(solver.x_grid, solver.y_grid, f(solver.x_grid, solver.y_grid))\n```\n\n|Solution|Ground truth|Error|\n|--|--|--|\n|![](data/sol_dirichlet.png)|![](data/gt_dirichlet.png)|![](data/err_dirichlet.png)|\n\n### Neumann Boundary Conditions\nYou can also define Neumann boundary conditions by specifying `neumann_x` and `neumann_y` in the boundary condition parameter.\n\n```python\n\nx_derivative_expr = functional.get_sp_derivative_expr(f_expr, x)\ny_derivative_expr = functional.get_sp_derivative_expr(f_expr, y)\n\ninterior = laplacian\nboundary = {\n    \"left\": (f, \"dirichlet\"),\n    \"right\": (functional.get_sp_function(x_derivative_expr), \"neumann_x\"),\n    \"top\": (f, \"dirichlet\"),\n    \"bottom\": (functional.get_sp_function(y_derivative_expr), \"neumann_y\")\n}\n```\n\n|Solution|Ground truth|Error|\n|--|--|--|\n|![](data/sol_neumann.png)|![](data/gt_neumann.png)|![](data/err_neumann.png)|\n\n### Zero-mean solution\nIf the boundary condition is purely Neumann, then the solution is not unique. Naively solving the Poisson equation gives bad results. In this case, you can set the `zero_mean` paramter to `True`, such that the solver finds a zero-mean solution. \n\n```python\nsolver = solvers.Poisson2DRectangle(\n    ((-2*np.pi, -2*np.pi), (2*np.pi, 2*np.pi)), interior, boundary, \n    X=100, Y=100, zero_mean=True)\n```\n\n|`zero_mean=False`|`zero_mean=True`|Ground truth|\n|--|--|--|\n|![](data/zero_mean_false.png)|![](data/zero_mean_true.png)|![](data/gt_neumann.png)|\n\n### Laplace Equation\nIt's also straightforward to define a Laplace equation - **we simply set the interior laplacian value to 0**. In the following example, we set the boundary values to be spatially-varying periodic functions.\n\n```python\ninterior = 0 # laplace equation form\nleft = poissonpy.get_2d_sympy_function(sin(y))\nright = poissonpy.get_2d_sympy_function(sin(y))\ntop = poissonpy.get_2d_sympy_function(sin(x))\nbottom = poissonpy.get_2d_sympy_function(sin(x))\n\nboundary = {\n    \"left\": (left, \"dirichlet\"),\n    \"right\": (right, \"dirichlet\"),\n    \"top\": (top, \"dirichlet\"),\n    \"bottom\": (bottom, \"dirichlet\")\n}\n```\n\nSolve the Laplace equation:\n\n```python\nsolver = Poisson2DRectangle(\n    ((-2*np.pi, -2*np.pi), (2*np.pi, 2*np.pi)), interior, boundary, 100, 100)\nsolution = solver.solve()\npoissonpy.plot_3d(solver.x_grid, solver.y_grid, solution, \"solution\")\npoissonpy.plot_2d(solution, \"solution\")\n```\n\n|3D surface plot|2D heatmap|\n|--|--|\n|![](data/laplace_sol_3d.png)|![](data/laplace_sol_2d.png)|\n\n### Arbitrary-shaped domain\nUse the `Poisson2DRegion` class to solve the Poisson eqaution on a arbitrary-shaped function domain. `poissonpy` can be seamlessly integrated in gradient-domain image processing algorithms.\n   \nThe following is an example where `poissonpy` is used to implement the image cloning algorithm proposed in [Poisson Image Editing](https://www.cs.jhu.edu/~misha/Fall07/Papers/Perez03.pdf) by Perez et al., 2003. See `examples/poisson_image_editing.py` for more details. \n\n```python\n# compute laplacian of interpolation function\nGx_src, Gy_src = functional.get_np_gradient(source)\nGx_target, Gy_target = functional.get_np_gradient(target)\nG_src_mag = (Gx_src**2 + Gy_src**2)**0.5\nG_target_mag = (Gx_target**2 + Gy_target**2)**0.5\nGx = np.where(G_src_mag \u003e G_target_mag, Gx_src, Gx_target)\nGy = np.where(G_src_mag \u003e G_target_mag, Gy_src, Gy_target)\nGxx, _ = functional.get_np_gradient(Gx, forward=False)\n_, Gyy = functional.get_np_gradient(Gy, forward=False)\nlaplacian = Gxx + Gyy\n    \n# solve interpolation function\nsolver = solvers.Poisson2DRegion(mask, laplacian, target)\nsolution = solver.solve()\n\n# alpha-blend interpolation and target function\nblended = mask * solution + (1 - mask) * target\n```\n\n\u003cp align=\"center\"\u003e\n    \u003cimg src=\"data/poisson_image_editing/result.png\" width=600\u003e\n\u003c/p\u003e\n\nAnother example of using `poissonpy` to implement flash artifacts and reflection removal, using the algorithm proposed in [Removing Photography Artifacts using Gradient Projection and Flash-Exposure Sampling](http://www.cs.columbia.edu/cg/pdfs/114-flashReflectionsRaskarSig05.pdf) by Agrawal et al. 2005. See `examples/flash_noflash.py` for more details.\n\n```python\nGx_a, Gy_a = functional.get_np_gradient(ambient)\nGx_f, Gy_f = functional.get_np_gradient(flash)\n\n# gradient projection\nt = (Gx_a * Gx_f + Gy_a * Gy_f) / (Gx_a**2 + Gy_a**2 + 1e-8)\nGx_f_proj = t * Gx_a\nGy_f_proj = t * Gy_a\n\n# compute laplacian (div of gradient)\nlap = functional.get_np_div(Gx_f_proj, Gy_f_proj)\n\n# integrate laplacian field\nsolver = solvers.Poisson2DRegion(mask, lap, flash)\nres = solver.solve()\n```\n\n\u003cp align=\"center\"\u003e\n    \u003cimg src=\"data/flash_noflash/result.png\" width=600\u003e\n\u003c/p\u003e\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fbchao1%2Fpoissonpy","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fbchao1%2Fpoissonpy","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fbchao1%2Fpoissonpy/lists"}