{"id":16507228,"url":"https://github.com/rpep/fmmgen","last_synced_at":"2025-10-11T10:48:30.076Z","repository":{"id":46121306,"uuid":"171658006","full_name":"rpep/fmmgen","owner":"rpep","description":"Automatic code generation of Fast Multipole and Barnes-Hut operators","archived":false,"fork":false,"pushed_at":"2022-10-25T21:10:06.000Z","size":890,"stargazers_count":18,"open_issues_count":1,"forks_count":2,"subscribers_count":0,"default_branch":"master","last_synced_at":"2025-09-21T16:42:45.152Z","etag":null,"topics":["barnes-hut-operators","dipole","fast-multipole-method","hacktoberfest","python","sympy-library"],"latest_commit_sha":null,"homepage":"","language":"C++","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/rpep.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}},"created_at":"2019-02-20T11:09:44.000Z","updated_at":"2025-08-11T14:05:23.000Z","dependencies_parsed_at":"2023-01-20T07:04:03.057Z","dependency_job_id":null,"html_url":"https://github.com/rpep/fmmgen","commit_stats":null,"previous_names":[],"tags_count":2,"template":false,"template_full_name":null,"purl":"pkg:github/rpep/fmmgen","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/rpep%2Ffmmgen","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/rpep%2Ffmmgen/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/rpep%2Ffmmgen/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/rpep%2Ffmmgen/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/rpep","download_url":"https://codeload.github.com/rpep/fmmgen/tar.gz/refs/heads/master","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/rpep%2Ffmmgen/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":279006866,"owners_count":26084208,"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","status":"online","status_checked_at":"2025-10-11T02:00:06.511Z","response_time":55,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"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":["barnes-hut-operators","dipole","fast-multipole-method","hacktoberfest","python","sympy-library"],"created_at":"2024-10-11T15:26:58.959Z","updated_at":"2025-10-11T10:48:30.023Z","avatar_url":"https://github.com/rpep.png","language":"C++","funding_links":[],"categories":[],"sub_categories":[],"readme":"# fmmgen\n![Python version](https://img.shields.io/badge/Python-%3E%3D%203.10-brightgreen.svg)\n![C++14 version](https://img.shields.io/badge/c%2B%2B-14-brightgreen)\n[![DOI](https://zenodo.org/badge/DOI/10.5281/zenodo.3842591.svg)](https://doi.org/10.5281/zenodo.3842591)\n[![Arxiv Paper](https://img.shields.io/badge/arxiv-2005.12351-B31B1B)](https://arxiv.org/abs/2005.12351)\n[![.github/workflows/actions.yml](https://github.com/rpep/fmmgen/actions/workflows/actions.yml/badge.svg)](https://github.com/rpep/fmmgen/actions/workflows/actions.yml)\n\nThis package generates Fast Multipole and Barnes-Hut operators for use in tree codes.\nIt was written as part of the PhD research of Ryan Alexander Pepper at the University of Southampton.\n\nThe library is written in Python, and requires at least version 3.6. The package has few dependencies; the main one is the SymPy library. Some parts of the SymPy library are bundled within fmmgen due to changes needing to be made to the underlying methods for the purposes of this code. Accordingly, fmmgen is licensed under the 3-Clause BSD License.\n\nfmmgen consists of several parts:\n\n1) Symbolical algebraic generation of the operators for fast multipole and Barnes-Hut codes in Cartesian Coordinates. Hand implementation of multipole formulae up to an arbitrary expansion order is non-trivial, and beyond 3rd order is a substantial effort. In general, this leaves most Cartesian fast multipole and Barnes-Hut authors writing operator functions by hand, as can be seen from other similar packages.\n\n2) A code writer, which generates code from the expansion formulae. At present,\nthis generates C or C++ code but in future may be extended. The code makes use of something called 'common subexpression\nelimination' (CSE) which reduces the number of operations which are performed in\nthe compiled code. Compilers already offer this functionality, but only at\nhigher levels of compiler optimisation is it turned on. Other optimisations are also present.\n\nThe code writer can also output a Cython wrapper for this C or C++ code, which can be\nused for quick testing of the operators.\n\n\n## Installation\n\nTo try out the module, first install it and the requirements:\n\n```bash\ngit clone https://github.com/rpep/fmmgen.git\ncd fmmgen\npip install .\n```\n\n## Example\n\nOnce the package is installed, you can get started in using it to generate a C code version of the operators:\n\n```python\nimport fmmgen\nimport numpy as np\n\n# Order of the multipole expansion\norder = 10\n# Order of the sources (i.e. monopole = 0, dipole = 1)\nsource_order = 0\n\n# This module name is used to label the source files, so\n# with this, we get output of 'operators.c' and 'operators.h'\nmodule_name = \"operators\"\n\n# Set whether ultimately, the field or potential are to be calculated.\n# Note that calculating the field constrains the operator functions;\n# no 0th order function is generated for the particle-to-multipole\n# (P2M) operator.\npotential = True\nfield = False\n\n# Choose a language ('c' or 'cpp')\nlanguage = 'c'\n\n# Choose whether to enable the common-subexpression elimination optimisation:\nCSE = True\n\n# Choose at what order expressions like x*x*x*x*x are converted to pow(x, 5)\nminpow = 5\n\n# Enable/disable generation of Cython code to allow the use of the functions from Python:\ncython=True\n\n# To get the unoptimized version of the code, generated without common subexpression elimination:\nfmmgen.generate_code(order, module_name, cython=cython, CSE=CSE,\n                     source_order=source_order,\n                     minpow=minpow,\n                     potential=True,\n                     field=False)\n\n\n# When Cython generation is enabled, it is possible to use the operator functions\n# directly from Python by importing them with pyximport. These have the same\n# API as the C code that is exported.\nimport pyximport\npyximport.install()\nimport operators_wrap as fmm\n\n# To calculate the multipole moments of a charge q located at (0, 0, d)\n# about the origin, for example, you can use the following:\nd = 2.0\nq = 3.0\n# Position of the charge:\nr = np.array([0.0, 0.0, d])\n# Number of entries in a multipole array for quadrupoles:\nNterms = fmmgen.utils.Nterms(2)\n\n# Multipole input array:\nQ = np.zeros(Nterms)\nQ[0] = q\n# Multipole output array:\nM = np.zeros(Nterms)\nfmm.M2M(*r, Q, M, 2)\nprint(M)\n# Expected output:\n#\n# M = [3.0,            [monopole moment]\n#      0.0, 0.0, 6.0,  [x, y, z dipole moments]\n#      0.0, 0.0, 0.0,\n#      0.0, 0.0, 6.0]  [xx, xy, xz, yy, yz, zz quadrupole moments]\n#\n```\n\nWe suggest looking in the 'example' folder for a fully functioning OpenMP parallelised implementation of the FMM and Barnes-Hut methods using the code generated operators, which works for Coulomb, Dipole and higher order sources; all that needs to be done is change the 'source_order' parameter. By making other changes in the example.py file, one can enable or disable optimisations, which affects the run time significantly for some compilers.\n\nIn general, we do not recommend the use of the GNU compiler for this; in testing we find that the performance of the methods are significantly worse than when compiled with the Intel compiler. This has a side effect; we find that the symbolic algebra optimisations have less of an effect on the performance with the Intel compiler, which can factor expressions more effectively to avoid repeated computations than the GNU compiler at high optimisation levels.\n\n## References\n\nThe code was developed with particular reference to the following academic papers.\n\n[1] Visscher, P. B., \u0026 Apalkov, D. M. (2010). Simple recursive implementation of fast multipole method. Journal of Magnetism and Magnetic Materials, 322(2), 275–281. https://doi.org/10.1016/j.jmmm.2009.09.033\n\n[2] Coles, J. P., \u0026 Masella, M. (2015). The fast multipole method and point dipole moment polarizable force fields. The Journal of Chemical Physics, 142(2), 24109. https://doi.org/10.1063/1.4904922\n\n[3] Beatson, R. and Greengard, L. (1997) A short course on fast multipole methods. In \"Wavelets, Multilevel Methods and Elliptic PDEs\", Oxford University Press, ISBN 0 19 850190 0\n\nIn addition, I would also point anyone interested in the Fast Multipole Method to the [video tutorial series](https://www.youtube.com/playlist?list=PLpa6_YduENMF080NikNninGG-7e1hK1eQ) of Dr. Rio Yokota of the Tokyo Institute of Technology for an overview and short course developing the 2-D method in a step-by-step way.\n\nI would also like to thank J. P. Coles for useful discussions regarding the method and implementation.\n\n## Citations\n\nThe following papers have cited or used Fmmgen:\n\n[1] [Efficient Open-Source Implementations of Linear-Scaling Polarizable Embedding: Use Octrees to Save the Trees](https://doi.org/10.1021/acs.jctc.1c00225) M. Scheurer, P. Reinholdt, J. M. H. Olsen, A. Dreuw, J Kongsted, J. Chem. Theory Comput. 17, 6, 3445–3454 (2021)\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Frpep%2Ffmmgen","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Frpep%2Ffmmgen","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Frpep%2Ffmmgen/lists"}