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

This installs a pre-built wheel when one is available for your operating system, architecture, and Python version. Wheels are the recommended option for using PyMieSim because they include the compiled C++ and Fortran extensions.

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

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

Named optical materials use PyOptik’s provenance-preserving RefractiveIndex.INFO catalog. Initialize its local snapshot once before using constructors such as SellmeierMaterial("BK7") or TabulatedMaterial("silver"):

python -m PyOptik setup

Building from source is intended for development or platforms without a matching wheel. It 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:

Developer setup

Clone the repository, select the Python interpreter you want to use, install the development and testing dependencies, and build an editable installation:

git clone https://github.com/MartinPdeS/PyMieSim.git
cd PyMieSim
python -m pip install ".[testing,documentation,dev]"
python -m PyOptik setup --no-progress
make PYTHON=python editable

make editable builds the native extensions in the local build directory and installs them into the same environment. Always run tests with that same interpreter:

python -c "import PyMieSim; print(PyMieSim.__version__)"
python -m pytest --config-file=pytest.ini

If the import reports missing native extensions, the build was not completed for this interpreter. Re-run make editable after checking that CMake, Fortran, pybind11, and OpenMP are installed. Do not mix build artifacts from different Python versions or architectures.

Building from source manually

The equivalent lower-level workflow is:

python -m pip install --no-build-isolation -Cbuild-dir=build -e .

The editable workflow is preferred because it keeps the Python sources and compiled extensions aligned. A released wheel does not require a compiler or the native build toolchain.

Testing

After the developer setup, run the unit tests with:

python -m pytest --config-file=pytest.ini

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.

Metadata

Release files for PyMieSim 5.7.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.7.1
File	Interpreter	ABI	Platform	Reset
pymiesim-5.7.1-cp313-cp313-win_amd64.whl 13.7 MB Sep 30, 2026	CPython 3.13	CPython 3.13	Windows x86-64	Details
pymiesim-5.7.1-cp313-cp313-manylinux_2_27_x86_64.manylinux_2_28_x86_64.whl 6.0 MB Sep 30, 2026	CPython 3.13	CPython 3.13	Linux glibc 2.27+ x86-64, Linux glibc 2.28+ x86-64	Details
pymiesim-5.7.1-cp313-cp313-macosx_26_0_arm64.whl 4.8 MB Sep 30, 2026	CPython 3.13	CPython 3.13	macOS 26.0+ ARM64	Details
pymiesim-5.7.1-cp312-cp312-win_amd64.whl 13.7 MB Sep 30, 2026	CPython 3.12	CPython 3.12	Windows x86-64	Details
pymiesim-5.7.1-cp312-cp312-manylinux_2_27_x86_64.manylinux_2_28_x86_64.whl 6.0 MB Sep 30, 2026	CPython 3.12	CPython 3.12	Linux glibc 2.27+ x86-64, Linux glibc 2.28+ x86-64	Details
pymiesim-5.7.1-cp312-cp312-macosx_26_0_arm64.whl 4.8 MB Sep 30, 2026	CPython 3.12	CPython 3.12	macOS 26.0+ ARM64	Details
pymiesim-5.7.1-cp311-cp311-win_amd64.whl 13.6 MB Sep 30, 2026	CPython 3.11	CPython 3.11	Windows x86-64	Details
pymiesim-5.7.1-cp311-cp311-manylinux_2_27_x86_64.manylinux_2_28_x86_64.whl 6.0 MB Sep 30, 2026	CPython 3.11	CPython 3.11	Linux glibc 2.27+ x86-64, Linux glibc 2.28+ x86-64	Details
pymiesim-5.7.1-cp311-cp311-macosx_26_0_arm64.whl 4.8 MB Sep 30, 2026	CPython 3.11	CPython 3.11	macOS 26.0+ ARM64	Details

Total release size: 73.3 MB

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

Download URL	pymiesim-5.7.1-cp313-cp313-win_amd64.whl
Size	13.7 MB
Tags	CPython 3.13 Windows x86-64
SHA-256 checksum How to use checksums	`6b76e913a43f028b936a9acf8404d97f5e165282477bd220654f3011b336b920`
BLAKE2b-256 checksum How to use checksums	`8b977b5ea5f15a073cf1c9a41d20c08ed89711e72b2ab7eb1834c7e1e4447804`
Upload date	Sep 30, 2026
Uploaded using Trusted Publishing? What is trusted publishing?	No
Uploaded via	`twine/7.0.0 CPython/3.13.14`

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

Download URL	pymiesim-5.7.1-cp313-cp313-manylinux_2_27_x86_64.manylinux_2_28_x86_64.whl
Size	6.0 MB
Tags	CPython 3.13 Linux glibc 2.27+ x86-64 Linux glibc 2.28+ x86-64
SHA-256 checksum How to use checksums	`c715b2df298c462581a06dbe75cdd05d75b4ea97e22c43fc79fd28044227e9f6`
BLAKE2b-256 checksum How to use checksums	`c201b49c7ba0c093352b90a84825acda88f2e9e54ff826b7eade062027f729c1`
Upload date	Sep 30, 2026
Uploaded using Trusted Publishing? What is trusted publishing?	No
Uploaded via	`twine/7.0.0 CPython/3.13.14`

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

Download URL	pymiesim-5.7.1-cp313-cp313-macosx_26_0_arm64.whl
Size	4.8 MB
Tags	CPython 3.13 macOS 26.0+ ARM64
SHA-256 checksum How to use checksums	`df4041d43fa68a5551a5e97072e733375e2d7ff38871d81311ade1436491117e`
BLAKE2b-256 checksum How to use checksums	`7944f867950dedf7aafb4cc94d578c14202786c89f8a57f4b5d726dcb74edbeb`
Upload date	Sep 30, 2026
Uploaded using Trusted Publishing? What is trusted publishing?	No
Uploaded via	`twine/7.0.0 CPython/3.13.14`

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

Download URL	pymiesim-5.7.1-cp312-cp312-win_amd64.whl
Size	13.7 MB
Tags	CPython 3.12 Windows x86-64
SHA-256 checksum How to use checksums	`ac63e1fe5f0b6f5c49dabcb1147f8c06b5b55c5e6ce43d6bf633adeae659f647`
BLAKE2b-256 checksum How to use checksums	`094793757905282e1fd989d443a2b0b745a75a7d09b03b17beaca0e457a18d15`
Upload date	Sep 30, 2026
Uploaded using Trusted Publishing? What is trusted publishing?	No
Uploaded via	`twine/7.0.0 CPython/3.13.14`

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

Download URL	pymiesim-5.7.1-cp312-cp312-manylinux_2_27_x86_64.manylinux_2_28_x86_64.whl
Size	6.0 MB
Tags	CPython 3.12 Linux glibc 2.27+ x86-64 Linux glibc 2.28+ x86-64
SHA-256 checksum How to use checksums	`1cb5dd366fda5cc80b0b134bb27dbd91087fde9c182713534728055dfb1c6b85`
BLAKE2b-256 checksum How to use checksums	`a51d48901b8cbff72c595db3831265d0fbfc38915dafecd904cab28d852fd7f2`
Upload date	Sep 30, 2026
Uploaded using Trusted Publishing? What is trusted publishing?	No
Uploaded via	`twine/7.0.0 CPython/3.13.14`

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

Download URL	pymiesim-5.7.1-cp312-cp312-macosx_26_0_arm64.whl
Size	4.8 MB
Tags	CPython 3.12 macOS 26.0+ ARM64
SHA-256 checksum How to use checksums	`80cac83ec68e591936f2c10e6d7fec80ec9e0e644afc26a29aa203d767c97eda`
BLAKE2b-256 checksum How to use checksums	`1e66c0c3db778edf180c9fc70668346ca4b4bacbc340100a8657900f49aa2b4b`
Upload date	Sep 30, 2026
Uploaded using Trusted Publishing? What is trusted publishing?	No
Uploaded via	`twine/7.0.0 CPython/3.13.14`

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

Download URL	pymiesim-5.7.1-cp311-cp311-win_amd64.whl
Size	13.6 MB
Tags	CPython 3.11 Windows x86-64
SHA-256 checksum How to use checksums	`2ec10e05c67fb7e0bcec7b36bb7bd73d21d26e5ffe88076540da5f5403928b08`
BLAKE2b-256 checksum How to use checksums	`c9ba3830390a8b5f267fb70d1797747ab0c14d2693ed0596d2715833bc22985b`
Upload date	Sep 30, 2026
Uploaded using Trusted Publishing? What is trusted publishing?	No
Uploaded via	`twine/7.0.0 CPython/3.13.14`

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

Download URL	pymiesim-5.7.1-cp311-cp311-manylinux_2_27_x86_64.manylinux_2_28_x86_64.whl
Size	6.0 MB
Tags	CPython 3.11 Linux glibc 2.27+ x86-64 Linux glibc 2.28+ x86-64
SHA-256 checksum How to use checksums	`8557cbd90245d12bcaf8a6780a48f33a5aa54933bac7151d0e1d9e75fb480d79`
BLAKE2b-256 checksum How to use checksums	`d7cd6d33dddf13768be37cb80179d628eda1de4883be663d21b4c893e82524b7`
Upload date	Sep 30, 2026
Uploaded using Trusted Publishing? What is trusted publishing?	No
Uploaded via	`twine/7.0.0 CPython/3.13.14`

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

Download URL	pymiesim-5.7.1-cp311-cp311-macosx_26_0_arm64.whl
Size	4.8 MB
Tags	CPython 3.11 macOS 26.0+ ARM64
SHA-256 checksum How to use checksums	`823738f8c63ac2e0dfad21352103188ea0686fa7ff764add0461c40a3adef644`
BLAKE2b-256 checksum How to use checksums	`deb948eeaf6188ca34faa45b2827b084707a9cf0656d04da25a5d99c9b965bb6`
Upload date	Sep 30, 2026
Uploaded using Trusted Publishing? What is trusted publishing?	No
Uploaded via	`twine/7.0.0 CPython/3.13.14`