Metadata-Version: 2.2
Name: miepy
Version: 1.1.0
Summary: Solve Maxwell's equations for a cluster of particles using the generalized multiparticle Mie theory (GMMT)
Keywords: electrodynamics,mie,scattering
Author-Email: John Parker <johnaparker@users.noreply.github.com>
License: GPLv3
Classifier: License :: OSI Approved :: GNU General Public License v3 (GPLv3)
Classifier: Programming Language :: Python
Classifier: Programming Language :: C++
Classifier: Operating System :: Unix
Classifier: Operating System :: POSIX
Classifier: Operating System :: MacOS
Classifier: Operating System :: Microsoft :: Windows
Classifier: Development Status :: 3 - Alpha
Classifier: Topic :: Scientific/Engineering :: Physics
Classifier: Intended Audience :: Science/Research
Requires-Python: >=3.11
Requires-Dist: matplotlib>=3.10.7
Requires-Dist: numpy>=2.3.3
Requires-Dist: numpy-quaternion>=2024.0.12
Requires-Dist: pandas>=2.3.3
Requires-Dist: pyyaml>=6.0.3
Requires-Dist: scipy>=1.16.2
Requires-Dist: spherical>=1.0.18
Requires-Dist: sympy>=1.14.0
Requires-Dist: tqdm>=4.67.1
Requires-Dist: vpython>=7.6.5
Provides-Extra: gpu
Requires-Dist: jax[cuda12]>=0.9.0.1; extra == "gpu"
Requires-Dist: jaxopt>=0.8.5; extra == "gpu"
Description-Content-Type: text/markdown

MiePy
==============
MiePy is a Python module for the generalized multiparticle Mie theory (GMMT), also known as the aggregate T-matrix method.
MiePy solves the electrodynamics of a collection of spherical or non-spherical scatterers with an arbitrary incident source.

<p align="center">
  <img src="./docs/miepy_thumbnail.png" width="500" alt="Electric field visualization">
  <br>
  <em>Electric field around a 37 particle cluster</em>
</p>

<p align="center">
  <img src="https://jparker.nyc3.digitaloceanspaces.com/gallery/em_three_np_contours.png" width="500" alt="Three particle system">
  <br>
  <em>3D electric field contours around three metal nanoparticles</em>
</p>

Features
--------------
+ **Non-spherical particles** using the T-matrix formulation via the extended boundary condition method (EBCM). Includes cylinders, spheroids, ellipsoids, cubes and polygonal prisms
+ **Arbitrary incident sources** (plane waves, Gaussian beams, HG and LG beams, point dipoles)
+ Evaluation of cluster **cross-sections** and **optical force and torque** on individual particles
+ **Periodic boundary conditions** with various lattice types (square, hexagonal, etc.) and **mirror and discrete rotational symmetries** for faster calculations
+ Optional **planar interface (substrate)** 
+ **3D scene visualization** using the VPython library
+ Image clusters using a **simulated microscope**
+ **OpenMP parallelization** for systems with larger numbers of particles

Installation
--------------
```shell
pip install miepy
```

If using `uv`:
```
uv venv --python 3.13
uv pip install miepy
source .venv/bin/activate
```

### GPU Backend (optional)

To use the GPU-accelerated solver backend:
```shell
pip install miepy[gpu]
```

Then activate the GPU backend:
```python
import miepy
miepy.backends.set_backend('gpu')
```

Usage
--------------

See the [examples](src/miepy/examples) folder for how to use MiePy.

Run any of the available [examples](src/miepy/examples) without explicit installation using `uv`:

| Command | Description |
|---------|-------------|
| `uvx miepy dielectric_sphere` | Dielectric sphere scattering and cross-sections |
| `uvx miepy ag_sphere` | Silver sphere scattering and absorption |
| `uvx miepy ag_shell` | Core-shell particle scattering |
| `uvx miepy vary_index` | Scattering intensity vs wavelength and refractive index |
| `uvx miepy fields` | Electric and magnetic field visualization |
| `uvx miepy dimer_scattering` | Au dimer cross-sections |
| `uvx miepy dimer_force` | Force and torque on dimer particles |
| `uvx miepy far_field` | Far-field radiation patterns |
| `uvx miepy whispering_gallery` | Whispering gallery modes in dielectric sphere |
| `uvx miepy focused_gaussian` | Focused Gaussian beam with orbital angular momentum |
| `uvx miepy imaging` | Near-field, far-field, and microscope imaging |

For an overview of the theory, see [docs](./docs) folder.

Install from source
--------------
MiePy uses [vcpkg](https://vcpkg.io/) for C++ dependency management and uv for Python management, which simplifies building across platforms.

**Prerequisites:**
+ GCC
+ uv

**Build steps:**

1. Clone MiePy and its submodules:
```shell
git clone https://github.com/johnaparker/miepy.git miepy --recurse-submodules && cd miepy
```

2. Bootstrap vcpkg (first time only):
```shell
./vcpkg/bootstrap-vcpkg.sh
```

3. Install MiePy using uv:
```shell
uv sync
```

4. Optionally, run the tests to verify correctness:
```shell
uv run pytest tests
```

License
--------------
MiePy is licensed under the terms of the GPLv3 license.
