Metadata-Version: 2.2
Name: PyMieSim
Version: 3.3.1
Summary: A package for light scattering computation.
Keywords: mie,scattering,backscatter,sphere,cylinder,nanoparticle,phase function,efficiency,rayleigh,backscattering
Author-Email: Martin Poinsinet de Sivry-Houle <martin.poinsinet.de.sivry@gmail.com>
License: MIT License
         
         Copyright (c) 2020 Martin Poinsinet de Sivry-Houle
         
         Permission is hereby granted, free of charge, to any person obtaining a copy
         of this software and associated documentation files (the "Software"), to deal
         in the Software without restriction, including without limitation the rights
         to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
         copies of the Software, and to permit persons to whom the Software is
         furnished to do so, subject to the following conditions:
         
         The above copyright notice and this permission notice shall be included in all
         copies or substantial portions of the Software.
         
         THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
         IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
         FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
         AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
         LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
         OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
         SOFTWARE.
         
Classifier: Programming Language :: Python
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: Implementation :: CPython
Classifier: Development Status :: 5 - Production/Stable
Classifier: Intended Audience :: Science/Research
Classifier: Intended Audience :: Developers
Classifier: Topic :: Scientific/Engineering :: Physics
Classifier: Topic :: Scientific/Engineering :: Mathematics
Classifier: Topic :: Scientific/Engineering :: Visualization
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: OS Independent
Classifier: Framework :: Jupyter
Classifier: Framework :: Sphinx
Project-URL: Documentation, https://martinpdes.github.io/PyMieSim/
Project-URL: Repository, https://github.com/MartinPdeS/PyMieSim
Requires-Python: >=3.10
Requires-Dist: setuptools_scm[toml]~=8.0
Requires-Dist: flexparser<0.5
Requires-Dist: numpy<3.0,>=1.26
Requires-Dist: pydantic<2.11.0,>=2.9.2
Requires-Dist: pint-pandas~=0.6
Requires-Dist: PyOptik~=1.8
Requires-Dist: tabulate~=0.9
Requires-Dist: pyvista==0.44.2
Provides-Extra: testing
Requires-Dist: pytest>=0.6; extra == "testing"
Requires-Dist: pytest-cov>=2.0; extra == "testing"
Requires-Dist: pytest-json-report==1.5.0; extra == "testing"
Requires-Dist: coverage==7.6.12; extra == "testing"
Provides-Extra: documentation
Requires-Dist: numpydoc==1.8.0; extra == "documentation"
Requires-Dist: sphinx>=5.1.1; extra == "documentation"
Requires-Dist: sphinx-rtd-theme==3.0.2; extra == "documentation"
Requires-Dist: sphinx-gallery==0.19.0; extra == "documentation"
Requires-Dist: pydata-sphinx-theme==0.16.1; extra == "documentation"
Provides-Extra: dev
Requires-Dist: flake8==7.1.2; extra == "dev"
Description-Content-Type: text/x-rst

|logo|

.. list-table::
   :widths: 10 25 25 25
   :header-rows: 0

   * - Meta
     - |python|
     - |docs|
     - |zenodo|
   * - Testing
     - |ci/cd|
     - |coverage|
     - |colab|
   * - PyPi
     - |PyPi|
     - |PyPi_download|
     -
   * - Anaconda
     - |anaconda|
     - |anaconda_download|
     - |anaconda_date|




PyMieSim
========

**PyMieSim** is a Python library designed to provide a robust and flexible framework for performing Mie scattering simulations.
The software is easy to install and operate, making it accessible to both new users and experienced researchers.
PyMieSim enables users to explore the scattering properties of particles under various configurations, and is tailored for investigating single scattering events, as well as conducting large-scale parametric experiments.

At its core, PyMieSim includes three solvers optimized for different types of scatterers:

- **Spherical particles**
- **Infinite cylindrical particles**
- **Core-shell spherical particles**

The software also allows the user to customize the light source and detector attributes, depending on the specific simulation needs. The package is modular and provides an intuitive interface for users to model complex scattering scenarios with minimal effort.

|code_structure|

Main Submodules
---------------

PyMieSim is organized into two primary submodules:

1. **single**: Focused on analyzing individual scattering events, such as:
   - Far-field distributions
   - Scattering phase functions
   - Stokes parameters

2. **experiment**: Designed for exploring how scattering parameters, such as `Qsca`, `Qext`, `g`, and `coupling (power)`, behave over large datasets, incorporating variations in sources, scatterers, and detectors.

Both submodules work seamlessly together, making PyMieSim adaptable for a wide range of scattering simulations.


----

Getting Started
---------------

To use PyMieSim in Python, simply install the package and begin incorporating it into your scripts.

Installation
************

PyMieSim supports Windows, Linux, macOS (including Apple M1/M2 chips), and ARM architectures. To install the package, use pip:

.. code-block:: bash

    pip install PyMieSim (using pip package manager)

    conda install PyMieSim (using conda environment manager)

For more details, visit the `documentation <https://pymiesim.readthedocs.io/en/latest/>`_ for a comprehensive guide on how to use the package.

----

Example Code
------------

Here is an example of how to use PyMieSim for a simple Mie scattering simulation. This example demonstrates how to configure a light source, scatterer, and detector, and retrieve the scattering data:

.. code-block:: python

    import numpy as np

    from PyMieSim.experiment.scatterer import Sphere
    from PyMieSim.experiment.source import Gaussian
    from PyMieSim.experiment import Setup
    from PyMieSim.units import nanometer, degree, watt, AU, RIU

    source = Gaussian(
        wavelength=np.linspace(400, 1000, 500) * nanometer,
        polarization=0 * degree,
        optical_power=1e-3 * watt,
        NA=0.2 * AU
    )

    scatterer = Sphere(
        diameter=[200] * nanometer,
        property=[4] * RIU,
        medium_property=1 * RIU,
        source=source
    )

    experiment = Setup(scatterer=scatterer, source=source)

    dataframe = experiment.get('Qsca')

    dataframe.plot_data(x="source:wavelength")


It produces the following figure which is equivalent to the one found on `wikipedia <https://en.wikipedia.org/wiki/Mie_scattering#/media/File:N4wiki.svg>`_.

|wikipedia_example|


This is just one example of PyMieSim in action. You can find more examples in the
`examples section <https://pymiesim.readthedocs.io/en/master/gallery/index.html>`_ of the documentation.

----

Examples
--------

Here are a few more examples showcasing the capabilities of PyMieSim:

Example 1: Plasmonic Resonances for CoreShell Particles
*******************************************************

|example_plasmon|

Example 2: Scattering Efficiency vs Diameter for Spherical Particles
********************************************************************

|example_qsca|

----

Manual Building
---------------

If you prefer or need to build the project manually (e.g., for Apple silicon devices), ensure you have a C++ compiler (such as gcc) and Fortran installed, as well as Python 3.7+.

Build Instructions
******************

Linux/MacOS
~~~~~~~~~~~

.. code-block:: bash

    git clone https://github.com/MartinPdeS/PyMieSim.git
    cd PyMieSim
    git submodule init && git submodule update
    mkdir build
    cd build
    cmake ../ -G"Unix Makefiles"
    sudo make install
    cd ..
    python -m pip install .

For Windows, use `MinGW Makefiles` instead of `Unix Makefiles` when invoking CMake.

----

Testing
-------

You can test the local version of PyMieSim by running the following commands:

.. code-block:: bash

    git clone https://github.com/MartinPdeS/PyMieSim.git
    cd PyMieSim
    pip install PyMieSim[testing]
    pytest

This will run the suite of unit tests and provide coverage details.

----

Google Colab
------------

In 2024, running code on your local machine is optional! You can leverage the power of Google Colab to run PyMieSim remotely. Use the provided
`Colab notebook <https://colab.research.google.com/github/MartinPdeS/PyMieSim/blob/master/notebook.ipynb>`_ for an interactive experience.

|colab|

----

Citing PyMieSim
---------------

If PyMieSim contributes to your research, we kindly ask that you cite the following paper:

.. code-block:: none

   @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},
   }

You can access the full article `here <https://opg.optica.org/optcon/fulltext.cfm?uri=optcon-2-3-520&id=526697>`_

----

Experimental Graphical User Interface (GUI)
-------------------------------------------

Since version 1.7.0, PyMieSim offers an experimental GUI for users who prefer a graphical approach to simulations. While still under development, the GUI can be installed and accessed as follows:

.. code-block:: bash

    pip install PyMieSim
    python -m  PyMieSim

The GUI is not yet as robust as the core Python API, but it provides a simplified interface for generating simulations.

|example_gui|

----

Contact Information
-------------------

PyMieSim is actively developed and maintained by Martin Poinsinet de Sivry-Houle. If you're interested in contributing or have questions, feel free to reach out.

Email: `martin.poinsinet.de.sivry@gmail.ca <mailto:martin.poinsinet.de.sivry@gmail.ca?subject=PyMieSim>`_

Flag_0

----

.. |logo| image:: https://github.com/MartinPdeS/PyMieSim/raw/master/docs/images/logo.png
    :alt: PyOptik logo

.. |python| image:: https://img.shields.io/pypi/pyversions/pymiesim.svg
    :alt: Python
    :target: https://www.python.org/

.. |zenodo| image:: https://zenodo.org/badge/DOI/10.5281/zenodo.5593704.svg
    :alt: Scientific article
    :target: https://doi.org/10.5281/zenodo.4556074

.. |colab| image:: https://colab.research.google.com/assets/colab-badge.svg
    :alt: Google Colab
    :target: https://colab.research.google.com/github/MartinPdeS/PyMieSim/blob/master/notebook.ipynb

.. |docs| image:: https://github.com/martinpdes/pymiesim/actions/workflows/deploy_documentation.yml/badge.svg
    :target: https://martinpdes.github.io/PyMieSim/
    :alt: Documentation Status

.. |PyPi| image:: https://badge.fury.io/py/PyMieSim.svg
    :alt: PyPi version
    :target: https://badge.fury.io/py/PyMieSim

.. |PyPi_download| image:: https://img.shields.io/pypi/dm/PyMieSim?style=plastic&label=PyPi%20downloads&labelColor=hex&color=hex
   :alt: PyPI - Downloads
   :target: https://pypistats.org/packages/pymiesim

.. |coverage| image:: https://raw.githubusercontent.com/MartinPdeS/PyMieSim/python-coverage-comment-action-data/badge.svg
    :alt: Unittest coverage
    :target: https://htmlpreview.github.io/?https://github.com/MartinPdeS/PyMieSim/blob/python-coverage-comment-action-data/htmlcov/index.html

.. |ci/cd| image:: https://github.com/martinpdes/pymiesim/actions/workflows/deploy_coverage.yml/badge.svg
    :alt: Unittest Status

.. |code_structure| image:: https://github.com/MartinPdeS/PyMieSim/raw/master/docs/images/code_structure.png
    :width: 800
    :alt: Structure of the library

.. |example_gui| image:: https://github.com/MartinPdeS/PyMieSim/raw/master/docs/images/example_gui.png
    :width: 800
    :alt: Structure of the library

.. |wikipedia_example| image:: https://github.com/MartinPdeS/PyMieSim/raw/master/docs/images/wikipedia_example.png
    :width: 800
    :alt: Example wikipedia

.. |example_plasmon| image:: https://github.com/MartinPdeS/PyMieSim/raw/master/docs/images/plasmonic_resonances.png
    :width: 800
    :alt: Plasmonic resonances

.. |example_qsca| image:: https://github.com/MartinPdeS/PyMieSim/raw/master/docs/images/Qsca_diameter.png
    :width: 800
    :alt: Qsca vs diameter

.. |anaconda| image:: https://anaconda.org/martinpdes/pymiesim/badges/version.svg
   :alt: Anaconda version
   :target: https://anaconda.org/martinpdes/pymiesim

.. |anaconda_download| image:: https://anaconda.org/martinpdes/pymiesim/badges/downloads.svg
   :alt: Anaconda downloads
   :target: https://anaconda.org/martinpdes/pymiesim

.. |anaconda_date| image:: https://anaconda.org/martinpdes/pymiesim/badges/latest_release_relative_date.svg
    :alt: Latest release date
    :target: https://anaconda.org/martinpdes/pymiesim
