PyMieSim

PyMieSim logo

Badge	Status
Python versions
Documentation
Scientific article
Continuous integration
Test coverage
Google Colab
PyPI package
PyPI downloads
Anaconda package
Anaconda downloads
Latest Anaconda release

PyMieSim

PyMieSim is an open-source Python package for fast and flexible Mie scattering simulations. It supports spherical, cylindrical and core–shell particles and provides helper classes for custom sources and detectors. The project targets both quick single-scatterer studies and large parametric experiments.

Try the live web GUI: PyMieSim Parameter Sweep Lab.

Features

Solvers for spheres, cylinders and core–shell geometries.
Built-in models for plane wave and Gaussian sources.
Multiple detector types including photodiodes and coherent modes.
Simple data analysis with pandas DataFrame outputs.

Installation

PyMieSim is available on PyPI and Anaconda. Install it with:

pip install PyMieSim
conda install PyMieSim  --channels MartinPdeS

Verify the installation with the same Python interpreter that you will use for your simulations:

python -c "import PyMieSim; print(PyMieSim.__version__)"

The released wheels are the easiest option. Building from source requires a C++20 compiler, Fortran, CMake, pybind11, and OpenMP; see troubleshooting if the compiled extension cannot be imported.

First simulation

Create a source, a scatterer, and a Simulation. Physical quantities use the built-in ureg unit registry, while refractive indices are dimensionless real or complex values.

from PyMieSim import (
    Gaussian,
    PolarizationState,
    Simulation,
    Sphere,
    ureg,
)

source = Gaussian(
    wavelength=633 * ureg.nanometer,
    polarization=PolarizationState(angle=0 * ureg.degree),
    optical_power=1e-3 * ureg.watt,
    numerical_aperture=0.2,
)

scatterer = Sphere(
    diameter=200 * ureg.nanometer,
    material=1.5 + 0.01j,
    medium=1.0,
)

simulation = Simulation(scatterer=scatterer, source=source)
qsca = simulation.run("Qsca")
print(qsca)

This prints a dimensionless scattering efficiency, approximately:

0.2080989068292113 dimensionless

Inspect the measures supported by the configured simulation with:

print(simulation.available_measures)

For explicit measure and unit metadata, request a typed result:

result = simulation.run("Qsca", as_result=True)
print(result.measure, result.quantity, result.units)

Units and material conventions

Always attach units to wavelengths, lengths, powers, and angles:

633 * ureg.nanometer
200 * ureg.nanometer
1e-3 * ureg.watt
0 * ureg.degree

Refractive indices are dimensionless. A complex index such as 1.5 + 0.01j represents an absorbing material under PyMieSim’s optical convention. Built-in and tabulated materials have supported wavelength ranges; use load_material and validate_wavelength when working with real material data.

Parameter sweeps

Use Experiment when you want to evaluate several wavelengths, particle sizes, or material parameters. Results retain named dimensions and coordinates, and can be converted to NumPy or pandas explicitly.

import numpy as np
from PyMieSim import (
    Experiment,
    GaussianSet,
    PolarizationSet,
    SphereSet,
    ureg,
)

source = GaussianSet(
    wavelength=np.linspace(500, 700, 5) * ureg.nanometer,
    polarization=PolarizationSet(angles=0 * ureg.degree),
    optical_power=1e-3 * ureg.watt,
    numerical_aperture=0.2,
)
scatterer = SphereSet(
    diameter=np.linspace(100, 500, 9) * ureg.nanometer,
    material=1.5,
    medium=1.0,
)

experiment = Experiment(scatterer_set=scatterer, source_set=source)
result = experiment.get("Qsca")
values = result.as_numpy()
dataframe = result.as_dataframe()

The experiment grid has five wavelength values and nine diameter values, so values.shape is (5, 9). See the parameter sweep guide for multiple measures and plotting.

Detector coupling

Add a detector when you need collected or coupled power rather than only a scatterer property:

from PyMieSim import (
    Gaussian,
    Photodiode,
    PolarizationState,
    Simulation,
    Sphere,
    ureg,
)

single_source = Gaussian(
    wavelength=633 * ureg.nanometer,
    polarization=PolarizationState(angle=0 * ureg.degree),
    optical_power=1e-3 * ureg.watt,
    numerical_aperture=0.2,
)
single_scatterer = Sphere(
    diameter=200 * ureg.nanometer,
    material=1.5 + 0.01j,
    medium=1.0,
)

detector = Photodiode(
    sampling=500,
    numerical_aperture=0.2,
    phi_offset=0 * ureg.degree,
    gamma_offset=0 * ureg.degree,
    medium=1.0,
)
simulation = Simulation(
    scatterer=single_scatterer,
    source=single_source,
    detector=detector,
)
coupling = simulation.run("coupling")
print(coupling)

coupling requires a detector. Other available detector types include CoherentMode and IntegratingSphere; see the detector coupling guide.

Common issues

If import PyMieSim fails, run python -m pip show PyMieSim and check that it uses the same Python executable as your script.
If a constructor reports a unit error, check that every dimensional input has units and convert it with .to(...) when necessary.
If coupling is unavailable, add a detector and inspect simulation.available_measures.
For slow or memory-heavy sweeps, print experiment.array_shape and experiment.total_iterations before requesting a result.
On servers or in CI, select a non-interactive Matplotlib backend such as Agg before importing plotting code.

See the online documentation for theory, performance guidance, runnable examples, and advanced near-field and far-field workflows.

$Scattering efficiency of a 200 nm sphere with refractive index 4.0.$

Code structure

Here is the architecture for a standard workflow using PyMieSim:

Building from source

For development or manual compilation, clone the repository and run:

git submodule update --init
mkdir build && cd build
cmake ../ -G"Unix Makefiles"
sudo make install
cd ..
python -m pip install .

Testing

Run the unit tests with:

pip install PyMieSim[testing]
pytest

Citing PyMieSim

If you use PyMieSim in academic work, please cite:

@article{PoinsinetdeSivry-Houle:23,
    author = {Martin Poinsinet de Sivry-Houle and Nicolas Godbout and Caroline Boudoux},
    journal = {Opt. Continuum},
    title = {PyMieSim: an open-source library for fast and flexible far-field Mie scattering simulations},
    volume = {2},
    number = {3},
    pages = {520--534},
    year = {2023},
    doi = {10.1364/OPTCON.473102},
}

Contact

For questions or contributions, contact martin.poinsinet.de.sivry@gmail.com.

Release files for PyMieSim 5.2.1

For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.

Built distributions (wheels)

Table of built distributions (wheels) for PyMieSim 5.2.1
File	Interpreter	ABI	Platform	Reset
pymiesim-5.2.1-cp313-cp313-win_amd64.whl 12.8 MB Sep 6, 2026	CPython 3.13	CPython 3.13	Windows x86-64	Details
pymiesim-5.2.1-cp313-cp313-manylinux_2_27_x86_64.manylinux_2_28_x86_64.whl 5.5 MB Sep 6, 2026	CPython 3.13	CPython 3.13	Linux glibc 2.28+ x86-64, Linux glibc 2.27+ x86-64	Details
pymiesim-5.2.1-cp313-cp313-macosx_26_0_arm64.whl 4.4 MB Sep 6, 2026	CPython 3.13	CPython 3.13	macOS 26.0+ ARM64	Details
pymiesim-5.2.1-cp312-cp312-win_amd64.whl 12.8 MB Sep 6, 2026	CPython 3.12	CPython 3.12	Windows x86-64	Details
pymiesim-5.2.1-cp312-cp312-manylinux_2_27_x86_64.manylinux_2_28_x86_64.whl 5.5 MB Sep 6, 2026	CPython 3.12	CPython 3.12	Linux glibc 2.27+ x86-64, Linux glibc 2.28+ x86-64	Details
pymiesim-5.2.1-cp312-cp312-macosx_26_0_arm64.whl 4.4 MB Sep 6, 2026	CPython 3.12	CPython 3.12	macOS 26.0+ ARM64	Details
pymiesim-5.2.1-cp311-cp311-win_amd64.whl 12.7 MB Sep 6, 2026	CPython 3.11	CPython 3.11	Windows x86-64	Details
pymiesim-5.2.1-cp311-cp311-manylinux_2_27_x86_64.manylinux_2_28_x86_64.whl 5.4 MB Sep 6, 2026	CPython 3.11	CPython 3.11	Linux glibc 2.27+ x86-64, Linux glibc 2.28+ x86-64	Details
pymiesim-5.2.1-cp311-cp311-macosx_26_0_arm64.whl 4.3 MB Sep 6, 2026	CPython 3.11	CPython 3.11	macOS 26.0+ ARM64	Details

Total release size: 67.7 MB

Release files / pymiesim-5.2.1-cp313-cp313-win_amd64.whl

Download URL	pymiesim-5.2.1-cp313-cp313-win_amd64.whl
Size	12.8 MB
Tags	CPython 3.13 Windows x86-64
SHA-256 checksum How to use checksums	`105d4a47907742eda0f85c4fb34d4aaf2685bfa6aefc8affe05506ab185ec109`
BLAKE2b-256 checksum How to use checksums	`c3ebdbf2c63cd72ea51b2a96a918804f70797fd989a3dc3b5ddd8d5c7c83e5d8`
Upload date	Sep 6, 2026
Uploaded using Trusted Publishing? What is trusted publishing?	No
Uploaded via	`twine/5.1.0 CPython/3.12.14`

Release files / pymiesim-5.2.1-cp313-cp313-manylinux_2_27_x86_64.manylinux_2_28_x86_64.whl

Download URL	pymiesim-5.2.1-cp313-cp313-manylinux_2_27_x86_64.manylinux_2_28_x86_64.whl
Size	5.5 MB
Tags	CPython 3.13 Linux glibc 2.27+ x86-64 Linux glibc 2.28+ x86-64
SHA-256 checksum How to use checksums	`58f2df8137fd408b761ea6def30fd1070715e038a8a022ecac8a94fdeef2e33d`
BLAKE2b-256 checksum How to use checksums	`27491648fc5af40e7a8df0a3476830ee784b51fb12de7c27b84c6187e4f1b67e`
Upload date	Sep 6, 2026
Uploaded using Trusted Publishing? What is trusted publishing?	No
Uploaded via	`twine/5.1.0 CPython/3.12.14`

Release files / pymiesim-5.2.1-cp313-cp313-macosx_26_0_arm64.whl

Download URL	pymiesim-5.2.1-cp313-cp313-macosx_26_0_arm64.whl
Size	4.4 MB
Tags	CPython 3.13 macOS 26.0+ ARM64
SHA-256 checksum How to use checksums	`ea1e86ef2f8f461df46e93f7dae940c49cfd1b234a4f0f38d77f20c3825a251d`
BLAKE2b-256 checksum How to use checksums	`e1fa7a2092e8d11aa1c8eefb42844787ed8d05587ad01b334844ef26182f565b`
Upload date	Sep 6, 2026
Uploaded using Trusted Publishing? What is trusted publishing?	No
Uploaded via	`twine/5.1.0 CPython/3.12.14`

Release files / pymiesim-5.2.1-cp312-cp312-win_amd64.whl

Download URL	pymiesim-5.2.1-cp312-cp312-win_amd64.whl
Size	12.8 MB
Tags	CPython 3.12 Windows x86-64
SHA-256 checksum How to use checksums	`4389e25aa84a198b63b54368a89a4408593a708a7b28bf998a4bbf2f03caf970`
BLAKE2b-256 checksum How to use checksums	`cca0def4aa88ed3f1081d108eb3e61f437db9faaec99fa10669a504dcea83c42`
Upload date	Sep 6, 2026
Uploaded using Trusted Publishing? What is trusted publishing?	No
Uploaded via	`twine/5.1.0 CPython/3.12.14`

Release files / pymiesim-5.2.1-cp312-cp312-manylinux_2_27_x86_64.manylinux_2_28_x86_64.whl

Download URL	pymiesim-5.2.1-cp312-cp312-manylinux_2_27_x86_64.manylinux_2_28_x86_64.whl
Size	5.5 MB
Tags	CPython 3.12 Linux glibc 2.27+ x86-64 Linux glibc 2.28+ x86-64
SHA-256 checksum How to use checksums	`ee0f7ca3b2afc42dad8fbc71c6de7e2bfd79982b764ba5f211c51c857d24af48`
BLAKE2b-256 checksum How to use checksums	`f27cf3d075327548e68130e579e88f955c3dc6020bd702b4e1837a05435db230`
Upload date	Sep 6, 2026
Uploaded using Trusted Publishing? What is trusted publishing?	No
Uploaded via	`twine/5.1.0 CPython/3.12.14`

Release files / pymiesim-5.2.1-cp312-cp312-macosx_26_0_arm64.whl

Download URL	pymiesim-5.2.1-cp312-cp312-macosx_26_0_arm64.whl
Size	4.4 MB
Tags	CPython 3.12 macOS 26.0+ ARM64
SHA-256 checksum How to use checksums	`bc3e3c4a2a696043b2ac59e55eac26bd282c28a172636795ca5c4ed958e250af`
BLAKE2b-256 checksum How to use checksums	`91fd46cd3a0a4f54060889fcf7d394f750e14f80989be73301aa63f847710238`
Upload date	Sep 6, 2026
Uploaded using Trusted Publishing? What is trusted publishing?	No
Uploaded via	`twine/5.1.0 CPython/3.12.14`

Release files / pymiesim-5.2.1-cp311-cp311-win_amd64.whl

Download URL	pymiesim-5.2.1-cp311-cp311-win_amd64.whl
Size	12.7 MB
Tags	CPython 3.11 Windows x86-64
SHA-256 checksum How to use checksums	`98fd0f2e6f1154c43b5c1c89ee6d75fbfd882acdbe7a2d0aabc8c11b1949e870`
BLAKE2b-256 checksum How to use checksums	`a216a5cca91706d9f017e30cb500cf8d231057e322c7e0f3c2e9d0c6df2f3324`
Upload date	Sep 6, 2026
Uploaded using Trusted Publishing? What is trusted publishing?	No
Uploaded via	`twine/5.1.0 CPython/3.12.14`

Release files / pymiesim-5.2.1-cp311-cp311-manylinux_2_27_x86_64.manylinux_2_28_x86_64.whl

Download URL	pymiesim-5.2.1-cp311-cp311-manylinux_2_27_x86_64.manylinux_2_28_x86_64.whl
Size	5.4 MB
Tags	CPython 3.11 Linux glibc 2.27+ x86-64 Linux glibc 2.28+ x86-64
SHA-256 checksum How to use checksums	`cb82d9414356b4ae6d568cbcaed21492aaf176a3ebe712b49776e4f358bc752f`
BLAKE2b-256 checksum How to use checksums	`004c0ba8612a175081547e841597f84fc6f0d0f9e63ff1c6026ac8744c33e6bc`
Upload date	Sep 6, 2026
Uploaded using Trusted Publishing? What is trusted publishing?	No
Uploaded via	`twine/5.1.0 CPython/3.12.14`

Release files / pymiesim-5.2.1-cp311-cp311-macosx_26_0_arm64.whl

Download URL	pymiesim-5.2.1-cp311-cp311-macosx_26_0_arm64.whl
Size	4.3 MB
Tags	CPython 3.11 macOS 26.0+ ARM64
SHA-256 checksum How to use checksums	`4f48c5eeaa4a8bc2d630e7e10534981ca42e476673026a4a1069d71a70ac7874`
BLAKE2b-256 checksum How to use checksums	`3939030e2b7a8d03b5028df79d41e94c0afd4c9853ff6842682070a817f15c9b`
Upload date	Sep 6, 2026
Uploaded using Trusted Publishing? What is trusted publishing?	No
Uploaded via	`twine/5.1.0 CPython/3.12.14`