Troubleshooting

Import and installation errors

Install a wheel matching your Python version and platform first:

python -m pip install --upgrade PyMieSim
python -c "import PyMieSim; print(PyMieSim.__version__)"

If importing a compiled extension fails, check that the interpreter running the command is the same one where PyMieSim was installed:

python -m pip show PyMieSim
python -c "import sys, PyMieSim; print(sys.executable); print(PyMieSim.__file__)"

When building from source, a C++20 compiler, Fortran compiler, CMake, pybind11, and OpenMP are required. Prefer a released wheel unless source changes require a local build.

OpenMP and macOS

The macOS build uses libomp. Install it with Homebrew if the linker cannot find OpenMP, then rebuild in a clean build directory. Avoid mixing extension files from different Python versions or architectures.

Units and input validation

Lengths, wavelengths, powers, and angles should carry explicit units:

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

Dimensionless refractive indices may be plain real or complex values. If a constructor reports a unit error, inspect the quantity with .units and convert it before passing it to PyMieSim.

Material wavelength ranges

Built-in and tabulated materials declare a wavelength range. The practical material helpers default to strict range checking:

from PyMieSim import load_material

material = load_material("BK7")

Use extrapolation="linear" only when endpoint-slope extrapolation is physically justified. validate_material and validate_wavelength can be used to diagnose range and passivity problems.

Coupling errors

coupling requires a detector. Add Photodiode, CoherentMode, or IntegratingSphere to a single simulation, or the corresponding detector set to an experiment. Use available_measures to confirm that coupling is enabled.

Unexpected memory use or slow sweeps

Print array_shape and total_iterations before running an experiment. Reduce the grid, request fewer measures, use .as_numpy(), or process the study in chunks. Near-field and far-field sampling can add substantial arrays; start with a coarse sampling value.

Plots and headless environments

For servers and CI, select a non-interactive Matplotlib backend before importing plotting code:

import matplotlib
matplotlib.use("Agg")

Save figures explicitly instead of relying on show(). Matplotlib font or cache warnings are environment warnings and do not generally indicate a scattering failure.

Reporting a bug

Include the PyMieSim version, Python version, operating system, installation method, minimal inputs, requested measure, and complete traceback. For a numerical discrepancy, include the wavelength range, material model, geometry, and sampling settings.