pycharge 2.0.1
Python library for differentiable electrodynamics simulations with jax.
Requires Python: >=3.10
Keywords: differentiable optics, electrodynamics, inverse design, jax, physics

<p align="center">
  <img src="https://raw.githubusercontent.com/MatthewFilipovich/pycharge/main/docs/source/_static/pycharge_logo.png" width="700px">

</p>

<p align="center">
  <em>Electromagnetics simulation library for moving point charges built on JAX</em>
</p>

<div align="center">

[![build](https://github.com/MatthewFilipovich/pycharge/actions/workflows/build.yml/badge.svg)](https://github.com/MatthewFilipovich/pycharge/actions/workflows/build.yml)
[![Codecov](https://img.shields.io/codecov/c/github/matthewfilipovich/pycharge?token=52MBM273IF)](https://codecov.io/gh/MatthewFilipovich/pycharge)
[![Documentation Status](https://readthedocs.org/projects/pycharge/badge/?version=latest)](https://pycharge.readthedocs.io/en/latest/?badge=latest)
[![PyPI version](https://img.shields.io/pypi/v/pycharge.svg)](https://pypi.org/project/pycharge/)
[![Python Version](https://img.shields.io/badge/python-3.10%2B-blue)](https://www.python.org/downloads/)
[![License](https://img.shields.io/github/license/MatthewFilipovich/pycharge?color=blue)](https://github.com/MatthewFilipovich/pycharge/blob/main/LICENSE)

</div>

<p align="center">
  <img width="300" src="https://raw.githubusercontent.com/MatthewFilipovich/pycharge/main/docs/source/_static/oscillating_charge.gif">
</p>



> [!IMPORTANT]
> **Major update (v2):** PyCharge has been rewritten in JAX with significant API changes. 
> The legacy NumPy-based version remains available under the [`v1.1.0`](https://github.com/MatthewFilipovich/pycharge/tree/v1.1.0) tag.

# Key Features

- ⚡️ **Point Charge Electrodynamics:** Compute relativistically-correct electromagnetic potentials and fields generated by moving point charges.
- ⚛️ **Self-Consistent N-Body Electrodynamics:** Simulate the dynamics of electromagnetic sources—such as free charges and dipoles—interacting through their self-generated fields.
- 🔥 **Powered by JAX:** Leverage JAX's just-in-time (XLA) compilation for GPU/TPU acceleration, vectorization, and scalable parallel execution.
- 🛠️ **Fully Differentiable:** End-to-end differentiability enables gradient-based optimization, control, and inverse design workflows.

Learn more about PyCharge in our research paper published in [Computational Physics Communications](https://doi.org/10.1016/j.cpc.2022.108291) and available on [arXiv](https://arxiv.org/abs/2107.12437)

# Installation

PyCharge is available on [PyPI](https://pypi.org/project/pycharge/) and can be installed with:

```bash
pip install pycharge
```

## Documentation

Read the full documentation at [pycharge.readthedocs.io](https://pycharge.readthedocs.io/).

## Usage

This example shows how to simulate an oscillating charge using PyCharge, computing and visualizing the scalar potential along the x-y axis at z=0 and t=0:

```python
import jax
import jax.numpy as jnp
import matplotlib.pyplot as plt
from scipy.constants import e

from pycharge import Charge, potentials_and_fields

# Define an oscillating point charge with charge +e.
oscillating_charge = Charge(lambda t: [2e-9 * jnp.sin(7.5e16 * t), 0.0, 0.0], e)

# Define 1D axes for the observation points (x, y) and fix z, t.
lim, grid_size = 50e-9, 1000
x = jnp.linspace(-lim, lim, grid_size)
y = jnp.linspace(-lim, lim, grid_size)
z = jnp.array([0.0])
t = jnp.array([0.0])

# Form the full 4D spacetime grid (X, Y, Z, T).
X, Y, Z, T = jnp.meshgrid(x, y, z, t, indexing="ij")

# Build and JIT-compile a function that returns potentials and fields.
quantities_fn = potentials_and_fields([oscillating_charge])
jit_quantities_fn = jax.jit(quantities_fn)

# Evaluate all quantities on the grid (returns a `Quantities` object).
quantities = jit_quantities_fn(X, Y, Z, T)

# Extract and plot the scalar potential on the x–y plane at z=0, t=0.
scalar_2d = quantities.scalar[:, :, 0, 0]
plt.imshow(scalar_2d.T, vmax=0.2)
plt.colorbar(label="Scalar Potential (V)")
```
_For more examples and detailed usage, please refer to the [documentation](https://pycharge.readthedocs.io/)._

  
## Contributing

We welcome contributions! See our [Contributing Guide](https://github.com/MatthewFilipovich/pycharge/blob/main/CONTRIBUTING.md) for details.
## Citing PyCharge

If you use PyCharge in your research, please cite our [paper](https://doi.org/10.1016/j.cpc.2022.108291).

```bibtex
  @article{filipovich2022pycharge,
     title={PyCharge: An open-source Python package for self-consistent electrodynamics simulations of Lorentz oscillators and moving point charges},
     author={Matthew J. Filipovich and S. Hughes},
     year={2022},
     journaltitle = {Computer Physics Communications},
     volume = {274},
     pages = {108291},
     issn = {00104655},
     doi = {10.1016/j.cpc.2022.108291},
     url={https://doi.org/10.1016/j.cpc.2022.108291},
   }
```

## License

PyCharge is distributed under the MIT License. See the [LICENSE](https://github.com/MatthewFilipovich/pycharge/blob/main/LICENSE) file for more details.