Metadata-Version: 2.4
Name: pipic
Version: 1.3rc1
Summary: A Python library for particle-in-cell plasma simulation.
Author: Joel Magnusson
Author-email: Arkady Gonoskov <arkady.gonoskov@physics.gu.se>, Frida Brogren <frida.brogren@physics.gu.se>
Maintainer: The pipic developers team
Project-URL: Homepage, https://github.com/hi-chi/pipic
Project-URL: Issues, https://github.com/hi-chi/pipic/issues
Classifier: Development Status :: 5 - Production/Stable
Classifier: License :: OSI Approved :: GNU General Public License v3 (GPLv3)
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3 :: Only
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Programming Language :: Python :: 3.14
Classifier: Intended Audience :: Science/Research
Classifier: Topic :: Scientific/Engineering :: Physics
Requires-Python: >=3.10
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: numpy<2.3,>=1.22; python_version == "3.10"
Requires-Dist: numpy>=1.24; python_version == "3.11"
Requires-Dist: numpy>=1.26; python_version >= "3.12"
Requires-Dist: numpy>=2.1; python_version >= "3.13"
Requires-Dist: numpy>=2.3.2; python_version >= "3.14"
Requires-Dist: numba>=0.55; python_version == "3.10" and sys_platform != "darwin"
Requires-Dist: numba>=0.57; python_version == "3.11" and sys_platform != "darwin"
Requires-Dist: numba>=0.59; python_version == "3.12" and sys_platform != "darwin"
Requires-Dist: numba>=0.61; python_version == "3.13" and sys_platform != "darwin"
Requires-Dist: numba>=0.63; python_version == "3.14" and sys_platform != "darwin"
Requires-Dist: numba>=0.63; sys_platform == "darwin" and platform_machine == "arm64"
Provides-Extra: mpl
Requires-Dist: matplotlib; extra == "mpl"
Provides-Extra: test
Requires-Dist: pytest; extra == "test"
Provides-Extra: docs
Requires-Dist: sphinx; extra == "docs"
Requires-Dist: sphinx_rtd_theme; extra == "docs"
Provides-Extra: dev
Requires-Dist: pipic[mpl,test]; extra == "dev"
Requires-Dist: setuptools>=64; extra == "dev"
Requires-Dist: setuptools-scm>=8; extra == "dev"
Requires-Dist: wheel; extra == "dev"
Requires-Dist: pybind11; extra == "dev"
Dynamic: license-file

<p align="center">
<img src="https://raw.githubusercontent.com/hi-chi/pipic/main/docs/logo/pipic_logo.png" width="300">
</p>

---
[![Actions Status][actions-badge]][actions-link]
[![PyPI version][pypi-version]][pypi-link]
[![PyPI platforms][pypi-platforms]][pypi-link]

$\pi$-PIC (PIPIC, Python-controlled Interactive PIC) is an open-source collection of relativistic particle-in-cell solvers featuring
- exact energy conservation;
- absence of numerical dispersion.

The solvers provide a way to either suppress or eliminate numerical artefacts (instabilities, heating, numerical Cherenkov radiation, etc.) permitting larger space and time steps, as well as lower number of particles per cell.
Because of reduced computational demands, the solvers can be found useful for quick tests of ideas, as well as for scanning parameter spaces. For a description of the underlying methods see [Reference](#Reference), the [documentation][readthedocs] or a [presentation at PIF24](https://plymouth.cloud.panopto.eu/Panopto/Pages/Viewer.aspx?id=86a17791-6db2-4009-be2f-b1dc00c846d0).

---

# Overview
$\pi$-PIC provides all tools necessary for designing 1D/2D/3D simulations and arbitrary outputs directly from Python. In addition, it has interfaces for incorporating extensions (read/modify field and particles, add/remove particles) that can be developed in Python, C/C++, Fortran or any other language that generate callable functions (see [extensions][extensions] for a list of extensions included in $\pi$-PIC installation). The project and its development are hosted on [GitHub][].

To get started, it should for most cases be sufficient to install $\pi$-PIC via _pip_ (this requires: `gcc`, `openmp` and `fftw3`; for details and information on compilation via CMake see [installation instructions][installation]):
```
pip install pipic
```

The basic layout of a simulation includes five elements:
- creating a container with cells with given parameters
- adding particles of all necessary types
- setting initial electromagnetic field
- defining output (via loops over particles and grid values of field)
- advance and read the state of the defined physical system

We demonstrate the use of these elements in the [tutorial][]. A complete list of all implemented Python interfaces functions can be found [here][interfaces]. The development of extensions is detailed [here][extension_development] and exemplified [here][extension_development_notebook].

The implementation of new solvers is exemplified [here][solver_development_notebook].


# New in $\pi$-PIC v1.3
The following updates has been made for $\pi$-PIC v.3. For more details see Ref.[2].
- [`extension`][extensions] for moving window simulations.
- [`extension`][extensions] for absorbing boundaries.
- Improved structure for handeling fields and particles in C++ extensions.
- An energy conserving solver with improved momentum conservation `emc`.


# New in $\pi$-PIC v1.2
- options for energy correction routine in `ec` and `ec2` (see `docs/guides/INTERFACES.md`)
- [`extension`][extensions] for initializing arbitrary tightly focused pulses, e.g. dipole waves (`focused_pulse`)

# New in $\pi$-PIC v1.1
- [`extensions`][extensions] for QED-PIC simulations (`qed_volokitin2023`, `qed_gonoskov2015`)
- [`extension`][extensions] for ensemble down-sampling (`downsampler_gonoskov2022`)

See all releases [here][releases].

# Reference
[1] A. Gonoskov, Explicit energy-conserving modification of relativistic PIC method, [J. Comput. Phys., 502, 112820](https://doi.org/10.1016/j.jcp.2024.112820); [arXiv:2302.01893][] (2024). <br>
[2] F. Brogren, $\pi$-PIC: a framework for modular particle-in-cell developments and simulations, [arXiv:2511.09950](https://doi.org/10.48550/arXiv.2511.09950) (2025).


<!-- prettier-ignore-start -->
[actions-badge]:            https://github.com/hi-chi/pipic/workflows/CI/badge.svg
[actions-link]:             https://github.com/hi-chi/pipic/actions
[pypi-link]:                https://pypi.org/project/pipic/
[pypi-platforms]:           https://img.shields.io/pypi/pyversions/pipic
[pypi-version]:             https://badge.fury.io/py/pipic.svg

[GitHub]: https://github.com/hi-chi/pipic
[installation]: https://github.com/hi-chi/pipic/blob/main/docs/guides/INSTALLATION.md
[tutorial]: https://github.com/hi-chi/pipic/blob/main/docs/guides/TUTORIAL.md
[interfaces]: https://github.com/hi-chi/pipic/blob/main/docs/guides/INTERFACES.md
[extensions]: https://github.com/hi-chi/pipic/blob/main/docs/EXTENSIONS.md
[extension_development]: https://github.com/hi-chi/pipic/blob/main/docs/guides/EXTENSION_DEVELOPMENT.md
[extension_development_notebook]: https://github.com/hi-chi/pipic/tree/main/tutorials/extensions
[solver_development_notebook]: https://github.com/hi-chi/pipic/tree/main/tutorials/solver
[releases]: https://github.com/hi-chi/pipic/blob/main/docs/RELEASES.md
[arXiv:2302.01893]: https://arxiv.org/abs/2302.01893
[readthedocs]: https://pi-pic.readthedocs.io/en/latest
<!-- prettier-ignore-end -->
