From b32d8e29de552dd3613e166cdd0d4482bb4278f5 Mon Sep 17 00:00:00 2001
From: Daniel King <43149077+dakinggg@users.noreply.github.com>
Date: Fri, 6 Sep 2024 01:00:19 -0700
Subject: [PATCH] Add nmslib support matrix (#524)

---
 README.md | 38 +++++++++++++++++++++++++++++++++-----
 1 file changed, 33 insertions(+), 5 deletions(-)

diff --git a/README.md b/README.md
index 916fcd5..7fd2f01 100644
--- a/README.md
+++ b/README.md
@@ -27,25 +27,53 @@ Take a look below in the "Setting up a virtual environment" section if you need
 Additionally, scispacy uses modern features of Python and as such is only available for **Python 3.6 or greater**.
 
 
+### Installation note: nmslib
+Over the years, installing nmslib has becomes quite difficult. There are a number of GitHub issues on scispaCy and the nmslib repo itself about this. This matrix is an attempt to help users install nmslib in whatever environment they have. I don't have access to every type of environment, so if you are able to test something out, please open an issue or pull request!
+
+|               | Windows 11 | Windows Subsystem for Linux | Mac M1  | Mac M2  | Mac M3  | Intel Mac |
+|---------------|------------|----------------------------|---------|---------|---------|-----------|
+| Python 3.8    | ✅         | ✅                         | 💻      | ❓      | ❓      | ❓         |
+| Python 3.9    | ❌🐍       | ✅                         | 💻      | ❓      | ❓      | ❓         |
+| Python 3.10   | ❌🐍       | ✅                         | ❓      | ❓      | ❓      | ✅         |
+| Python 3.11   | ❌🐍       | ❌🐍                       | ❓      | ❓      | ❓      | ❌         |
+| Python 3.12   | ❌🐍       | ❌🐍🧠                     | ❓      | ❓      | ❓      | ❓         |
+
+
+✅ = works normally with pip install of scispacy
+
+❌ = does not work normally with pip install of scispacy
+
+🐍 = can be installed with `mamba install nmslib`
+
+💻 = can be installed with `CFLAGS="-mavx -DWARN(a)=(a)" pip install nmslib`
+
+🧠 = can be installed with `pip install nmslib-metabrainz`
+
+❓ = unconfirmed
+
+Other methods mentioned in GitHub issues, but unconfirmed what versions they work for:
+- `CFLAGS="-mavx -DWARN(a)=(a)" pip install nmslib`
+- `pip install --no-binary :all: nmslib`
+- `pip install --upgrade pybind11` + `pip install --verbose 'nmslib @ git+https://github.com/nmslib/nmslib.git#egg=nmslib&subdirectory=python_bindings'`
 
 #### Setting up a virtual environment
 
-[Conda](https://conda.io/) can be used set up a virtual environment with the
+[Mamba](https://mamba.readthedocs.io/en/latest/) can be used set up a virtual environment with the
 version of Python required for scispaCy.  If you already have a Python
 environment you want to use, you can skip to the 'installing via pip' section.
 
-1.  [Follow the installation instructions for Conda](https://conda.io/projects/conda/en/latest/user-guide/install/index.html?highlight=conda#regular-installation).
+1.  [Follow the installation instructions for Mamba](https://mamba.readthedocs.io/en/latest/installation/mamba-installation.html).
 
 2.  Create a Conda environment called "scispacy" with Python 3.9 (any version >= 3.6 should work):
 
     ```bash
-    conda create -n scispacy python=3.9
+    mamba create -n scispacy python=3.10
     ```
 
-3.  Activate the Conda environment. You will need to activate the Conda environment in each terminal in which you want to use scispaCy.
+3.  Activate the Mamba environment. You will need to activate the Conda environment in each terminal in which you want to use scispaCy.
 
     ```bash
-    source activate scispacy
+    mamba activate scispacy
     ```
 
 Now you can install `scispacy` and one of the models using the steps above.