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 webapp
Run Mie scattering simulations in your browser—no installation required.
Launch the PyMieSimX webapp to configure optical setups, run parameter sweeps, explore individual particles, and download your results as CSV files. The hosted service brings PyMieSim to a graphical interface, making it easy to try simulations before installing the Python package. The interface is developed in PyMieSimX.
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 MartinPdeSThis 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 setupBuilding 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 dimensionlessInspect 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.degreeRefractive 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.
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 editablemake 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.iniIf 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.iniCiting 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.
1 maintainer
Metadata
1 maintainer
Release files for PyMieSim 5.8.0
For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.
Built distributions (wheels)
Total release size: 98.3 MB
Release files / pymiesim-5.8.0-cp314-cp314-win_amd64.whl
| Download URL | pymiesim-5.8.0-cp314-cp314-win_amd64.whl |
|---|---|
| Size | 14.2 MB |
| Tags | CPython 3.14 Windows x86-64 |
|
SHA-256 checksum How to use checksums |
e88a307af47976bb73f0f373a70585e157ff3d7c291d5e1290e75923fe905713
|
|
BLAKE2b-256 checksum How to use checksums |
442577d9ce3744e6ddd6437b2ffb5ad45f8689a30128b51be7d97eae1616aa9b
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
twine/7.0.0 CPython/3.13.14
|
Release files / pymiesim-5.8.0-cp314-cp314-manylinux_2_27_x86_64.manylinux_2_28_x86_64.whl
| Download URL | pymiesim-5.8.0-cp314-cp314-manylinux_2_27_x86_64.manylinux_2_28_x86_64.whl |
|---|---|
| Size | 6.0 MB |
| Tags | CPython 3.14 Linux glibc 2.27+ x86-64 Linux glibc 2.28+ x86-64 |
|
SHA-256 checksum How to use checksums |
70c59b22d7f69eff9d8178a4d422f5dc7f6ba6209d908599f8dda8b3177747e6
|
|
BLAKE2b-256 checksum How to use checksums |
0281c9604339d0af68534178d9226e61523de3cdcd230c32ad02574262b9267e
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
twine/7.0.0 CPython/3.13.14
|
Release files / pymiesim-5.8.0-cp314-cp314-macosx_26_0_arm64.whl
| Download URL | pymiesim-5.8.0-cp314-cp314-macosx_26_0_arm64.whl |
|---|---|
| Size | 4.8 MB |
| Tags | CPython 3.14 macOS 26.0+ ARM64 |
|
SHA-256 checksum How to use checksums |
93719e2dcaf1ca699bb3be5cbf8f1fa5d35fdf3f5f1a3bf46cd3a6e9b3ae5b40
|
|
BLAKE2b-256 checksum How to use checksums |
c17363b645f2254d6451324da1b6587d21369aefaae47cc96c199e5539da5f10
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
twine/7.0.0 CPython/3.13.14
|
Release files / pymiesim-5.8.0-cp313-cp313-win_amd64.whl
| Download URL | pymiesim-5.8.0-cp313-cp313-win_amd64.whl |
|---|---|
| Size | 13.7 MB |
| Tags | CPython 3.13 Windows x86-64 |
|
SHA-256 checksum How to use checksums |
7c18b0d3561c54934a8470645559c8f71023180caf704599c1b6e7b987f1a1a0
|
|
BLAKE2b-256 checksum How to use checksums |
a3ac75738cf2de1e364f5ee271c08770bc39594d14e684ce6253cefb350a22bf
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
twine/7.0.0 CPython/3.13.14
|
Release files / pymiesim-5.8.0-cp313-cp313-manylinux_2_27_x86_64.manylinux_2_28_x86_64.whl
| Download URL | pymiesim-5.8.0-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 |
63b822845918a1c2a4413b12b1f17674a195b73979899ee74c960e2a05d956c9
|
|
BLAKE2b-256 checksum How to use checksums |
4c6e487640b2a685669585b0481a6f2ece785f0fec27a3aaf89d064561f1945f
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
twine/7.0.0 CPython/3.13.14
|
Release files / pymiesim-5.8.0-cp313-cp313-macosx_26_0_arm64.whl
| Download URL | pymiesim-5.8.0-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 |
2aaa8f43d36cc7cc9aaf3be052293e57bc4e853739131d12cccdd4a789f85ab9
|
|
BLAKE2b-256 checksum How to use checksums |
39257acd8c731cf4642cf45fe11ab8c4462c1b2d63cfbe73edac93cb2c55437f
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
twine/7.0.0 CPython/3.13.14
|
Release files / pymiesim-5.8.0-cp312-cp312-win_amd64.whl
| Download URL | pymiesim-5.8.0-cp312-cp312-win_amd64.whl |
|---|---|
| Size | 13.7 MB |
| Tags | CPython 3.12 Windows x86-64 |
|
SHA-256 checksum How to use checksums |
6eea9fa42ce2654ec55324df614d56b2f5c7fc817ba3a8fcde6cfa2240de586d
|
|
BLAKE2b-256 checksum How to use checksums |
248c40f8e12f94add5fbe01ae837df94e2e123e32f300d26e818a85d7474e227
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
twine/7.0.0 CPython/3.13.14
|
Release files / pymiesim-5.8.0-cp312-cp312-manylinux_2_27_x86_64.manylinux_2_28_x86_64.whl
| Download URL | pymiesim-5.8.0-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 |
0c3fc50c5e37bf1d0349edff5858b9617ef70b5ec13db8eafd42ceb864b9955c
|
|
BLAKE2b-256 checksum How to use checksums |
a2090d23a73d20952fe470e255bf33092e8f82da7b5b8dcd06acf5351454fc4c
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
twine/7.0.0 CPython/3.13.14
|
Release files / pymiesim-5.8.0-cp312-cp312-macosx_26_0_arm64.whl
| Download URL | pymiesim-5.8.0-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 |
4d0fae39dc0767b9162f38dca334fec254f7d8940b909791ffd959e114b46650
|
|
BLAKE2b-256 checksum How to use checksums |
61d2d711025074f38e3b3a15340b9a66964325dacf8ad11cf4be350903ed49ef
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
twine/7.0.0 CPython/3.13.14
|
Release files / pymiesim-5.8.0-cp311-cp311-win_amd64.whl
| Download URL | pymiesim-5.8.0-cp311-cp311-win_amd64.whl |
|---|---|
| Size | 13.6 MB |
| Tags | CPython 3.11 Windows x86-64 |
|
SHA-256 checksum How to use checksums |
8b563b305a045647e538b38de33762876d8394f6c4d2479b89a91c00cd67cce2
|
|
BLAKE2b-256 checksum How to use checksums |
b3d3f043148a8c50bd13237a6bdc18d2e727ac1badb06e9e39733b12614fb3bd
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
twine/7.0.0 CPython/3.13.14
|
Release files / pymiesim-5.8.0-cp311-cp311-manylinux_2_27_x86_64.manylinux_2_28_x86_64.whl
| Download URL | pymiesim-5.8.0-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 |
42ed9b779329e831504531e52af8dc8601658e74f432612d3e6d5b3ac3815e42
|
|
BLAKE2b-256 checksum How to use checksums |
5943a6167bc5066ad2e0c891613850cbff23f77d5c45a7e5cb4b775f0423c0c8
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
twine/7.0.0 CPython/3.13.14
|
Release files / pymiesim-5.8.0-cp311-cp311-macosx_26_0_arm64.whl
| Download URL | pymiesim-5.8.0-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 |
f9edab92378414ef52060a7365712d4fcfb222aa73878e39c57adac85ed12737
|
|
BLAKE2b-256 checksum How to use checksums |
1705656abd7f51f38e8b284d17868c46a8eb77ddd9be25109c44fbb15f856a33
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
twine/7.0.0 CPython/3.13.14
|
