Metadata-Version: 2.4
Name: pulse2percept
Version: 0.9.1
Summary: A Python-based simulation framework for bionic vision
Author-email: Michael Beyeler <mbeyeler@ucsb.edu>, Jacob Granley <jgranley@ucsb.edu>, Apurv Varshney <apurv@ucsb.edu>, Ariel Rokem <arokem@gmail.com>
License: Copyright (c) 2016-2020, the pulse2percept developers
        All rights reserved.
        
        Redistribution and use in source and binary forms, with or without modification, are permitted provided that the following conditions are met:
        
        1. Redistributions of source code must retain the above copyright notice, this list of conditions and the following disclaimer.
        
        2. Redistributions in binary form must reproduce the above copyright notice, this list of conditions and the following disclaimer in the documentation and/or other materials provided with the distribution.
        
        3. Neither the name of the copyright holder nor the names of its contributors may be used to endorse or promote products derived from this software without specific prior written permission.
        
        THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
        
Keywords: bionic vision,simulation,scientific computing
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3 :: Only
Classifier: License :: OSI Approved :: BSD License
Classifier: Operating System :: OS Independent
Requires-Python: >=3.10
Description-Content-Type: text/x-rst
License-File: LICENSE
License-File: AUTHORS
Requires-Dist: numpy<3,>=1.21
Requires-Dist: scipy>=1.6
Requires-Dist: scikit-image>=0.14
Requires-Dist: matplotlib>=3.0.2
Requires-Dist: imageio-ffmpeg>=0.4
Requires-Dist: pandas
Provides-Extra: dev
Requires-Dist: h5py; extra == "dev"
Requires-Dist: pytest>=5; extra == "dev"
Requires-Dist: pytest-cov; extra == "dev"
Requires-Dist: flake8; extra == "dev"
Requires-Dist: seaborn; extra == "dev"
Requires-Dist: neuropythy; extra == "dev"
Provides-Extra: colab
Requires-Dist: numpy<3,>=2; extra == "colab"
Dynamic: license-file

.. |doi| image:: https://img.shields.io/badge/DOI-10.25080/shinma--7f4c6e7--00c-blue
   :target: https://doi.org/10.25080/shinma-7f4c6e7-00c
   :alt: DOI
.. |license| image:: https://img.shields.io/badge/License-BSD%203--Clause-blue.svg
   :target: https://github.com/pulse2percept/pulse2percept/blob/master/LICENSE
   :alt: BSD 3-clause
.. |pypi| image:: https://img.shields.io/pypi/v/pulse2percept.svg
   :target: https://pypi.org/project/pulse2percept
   :alt: PyPI
.. |build| image:: https://github.com/pulse2percept/pulse2percept/actions/workflows/build.yml/badge.svg
   :target: https://github.com/pulse2percept/pulse2percept/actions
   :alt: build
.. |forks| image:: https://img.shields.io/github/forks/pulse2percept/pulse2percept
   :target: https://github.com/pulse2percept/pulse2percept/network/members
   :alt: GitHub forks
.. |stars| image:: https://img.shields.io/github/stars/pulse2percept/pulse2percept
   :target: https://github.com/pulse2percept/pulse2percept/stargazers
   :alt: GitHub stars

|doi| |license| |pypi| |build| |forks| |stars|

====================================================================
pulse2percept: A Python-based simulation framework for bionic vision
====================================================================

Globally, an estimated 43 million people are blind, with limited treatment
options available for many causes of vision loss. For certain conditions,
visual neuroprostheses - such as retinal and cortical implants - may be the
only viable intervention.

However, understanding the perceptual experience generated by these devices
remains a significant challenge. The artificial vision they provide is
shaped by complex interactions between neural stimulation, underlying
neurophysiology, and device-specific parameters.

`pulse2percept`_ (p2p) is an open-source Python package that offers
spatiotemporal models of common `retinal and cortical implants`_,
providing a computational framework to simulate and study artificial
vision.

.. _pulse2percept: https://github.com/pulse2percept/pulse2percept
.. _retinal and cortical implants: https://en.wikipedia.org/wiki/Visual_prosthesis

.. image:: https://raw.githubusercontent.com/pulse2percept/pulse2percept/master/doc/_static/boston-train-combined.gif
   :align: center
   :alt: Input stimulus and predicted percept

*(left: input stimulus, right: predicted percept)*

Simulations such as the above are likely to be critical for providing realistic
estimates of prosthetic vision, thus providing regulatory bodies with guidance
into what sort of visual tests are appropriate for evaluating prosthetic
performance, and improving current and future technology.

If you use p2p in a scholarly publication, please cite as:

.. epigraph::

    M Beyeler, GM Boynton, I Fine, A Rokem (2017). pulse2percept: A
    Python-based simulation framework for bionic vision. *Proceedings of the
    16th Python in Science Conference (SciPy)*, p.81-88,
    doi:`10.25080/shinma-7f4c6e7-00c <https://doi.org/10.25080/shinma-7f4c6e7-00c>`_.

Installation
============

.. quickstart-begin

To install the `stable release`_ of p2p, run:

.. code-block:: bash

    pip install pulse2percept

``pip`` installs NumPy and the other dependencies for you, and will only select
a release that supports the Python version you are running (see
`Compatibility and Building from Source`_ below).

We publish prebuilt wheels on PyPI for 64-bit Linux (``manylinux``, x86-64),
macOS 11 and later (both Apple silicon and Intel), and 64-bit Windows. These
wheels are not tied to a particular distribution or OS release beyond those
minimums. You can find the full documentation
`here <https://pulse2percept.readthedocs.io/en/stable>`_.

.. _stable release: https://pulse2percept.readthedocs.io/en/stable/index.html

.. quickstart-end

Compatibility and Building from Source
--------------------------------------

.. compat-begin

We do not publish wheels for 32-bit platforms or for musl-based distributions
such as Alpine Linux. While other platforms are not explicitly supported, you
may still be able to run p2p with minimal modifications: if ``pip`` does not
find a prebuilt wheel for your system, it will attempt to install from source.

.. note::

   You do **not** need to install NumPy or Cython yourself in order to build
   from source. They are declared as build requirements, so ``pip`` installs
   them into an isolated build environment automatically. What you do need is
   a C compiler: one is already present on most Linux and macOS systems, but
   on Windows you must install `Visual Studio Build Tools`_ and select
   "Desktop development with C++".

   The exception is ``pip install --no-build-isolation``, which deliberately
   skips that step; there you must install NumPy and Cython yourself first.

Supported Python versions:

+----------------------+------+------+------+------+-----+-----+-----+-----+-----+
|        Python        | 3.13 | 3.12 | 3.11 | 3.10 | 3.9 | 3.8 | 3.7 | 3.6 | 3.5 |
+======================+======+======+======+======+=====+=====+=====+=====+=====+
| p2p 0.9.1            | Yes  | Yes  | Yes  | Yes  |     |     |     |     |     |
+----------------------+------+------+------+------+-----+-----+-----+-----+-----+
| p2p 0.9              |      | Yes  | Yes  | Yes  | Yes |     |     |     |     |
+----------------------+------+------+------+------+-----+-----+-----+-----+-----+
| p2p 0.8              |      |      |      | Yes  | Yes | Yes | Yes |     |     |
+----------------------+------+------+------+------+-----+-----+-----+-----+-----+
| p2p 0.7              |      |      |      |      | Yes | Yes | Yes | Yes |     |
+----------------------+------+------+------+------+-----+-----+-----+-----+-----+
| p2p 0.6              |      |      |      |      |     | Yes | Yes | Yes | Yes |
+----------------------+------+------+------+------+-----+-----+-----+-----+-----+

Our `GitHub Action Runners`_ build and test p2p on the ``ubuntu-latest``,
``windows-latest``, and ``macos-latest`` images, on every Python version listed
for the current release above. Those labels track whatever image GitHub
currently ships, so the exact OS releases we test against change over time.

.. _Visual Studio Build Tools: https://visualstudio.microsoft.com/visual-cpp-build-tools/
.. _GitHub Action Runners: https://github.com/pulse2percept/pulse2percept/actions

.. compat-end

Upgrading and Uninstalling
--------------------------

.. upgrade-begin

To upgrade p2p to the latest stable version:

.. code-block:: bash

    pip install -U pulse2percept

To uninstall:

.. code-block:: bash

    pip uninstall pulse2percept -y

.. upgrade-end

Installing the Bleeding-Edge Version
------------------------------------

If you want to install the `latest development version`_ from source, make sure
you have a C compiler available (see the note above), then run:

.. code-block:: bash

    pip install git+https://github.com/pulse2percept/pulse2percept

For more details, see our `Installation Guide`_.

If you encounter issues, check our `Issue Tracker`_ on GitHub for solutions
or contribute fixes for unsupported platforms.

.. _latest development version: https://pulse2percept.readthedocs.io/en/latest/index.html
.. _Installation Guide: https://pulse2percept.readthedocs.io/en/stable/install.html
.. _Issue Tracker: https://github.com/pulse2percept/pulse2percept/issues

Where to go from here
=====================

*  Have a look at some code examples from our `Example Gallery`_.
*  Familiarize yourself with `visual implants`_, `electrical stimuli`_,
   and our `computational models`_.
*  Check the `FAQ`_ to see if your question has already been answered.
*  Request features or report bugs on our `Issue Tracker`_ on GitHub.

.. _Example Gallery: https://pulse2percept.readthedocs.io/en/latest/examples/index.html
.. _visual implants: https://pulse2percept.readthedocs.io/en/latest/topics/implants.html
.. _electrical stimuli: https://pulse2percept.readthedocs.io/en/latest/topics/stimuli.html
.. _computational models: https://pulse2percept.readthedocs.io/en/latest/topics/models.html
.. _FAQ: https://pulse2percept.readthedocs.io/en/latest/users/faq.html
