Merge pull request #246 from motiwari/v4.0.2_prerelease

BanditPAM v4.0.2

.github/workflows/build_linux_wheels.yml

@@ -27,8 +27,8 @@ jobs:
       - name: Install Python dependencies 
         run: |
           python -m pip install --upgrade pip
-          pip install pytest
-          pip install -r requirements.txt
+          python -m pip install pytest
+          python -m pip install -r requirements.txt
 
       - name: Build sdist
         run: python setup.py sdist --formats=gztar,zip

.github/workflows/build_mac_wheels.yml

@@ -7,8 +7,8 @@ on:
       - published
 jobs:
   build_wheels_macos:
-    name: Build wheels on macos-10.15
-    runs-on: macos-10.15
+    name: Build wheels on macos-latest
+    runs-on: macos-latest
     strategy:
       fail-fast: false
     steps:

.github/workflows/run_cmake_build.yml

@@ -38,6 +38,14 @@ jobs:
           mkdir -p data
           curl -XGET https://motiwari.com/banditpam_data/MNIST_1k.csv > data/MNIST_1k.csv
 
+      - name: Clone for PR
+        if: ${{ github.event_name == 'pull_request' }}
+        run: git clone -b $GITHUB_HEAD_REF https://github.com/motiwari/BanditPAM
+
+      - name: Clone for Push
+        if: ${{ github.event_name != 'pull_request' }}
+        run: git clone -b ${GITHUB_REF#refs/heads/} https://github.com/motiwari/BanditPAM
+
       # On the MacOS machine, when installing from source,
       # we use LLVM Clang
       # TODO(@motiwari): Clean this environment variables up
@@ -50,7 +58,6 @@ jobs:
           export DYLD_LIBRARY_PATH=/usr/local/opt/libomp/lib:/usr/local/opt/libomp/include
           export CC=/usr/local/opt/llvm/bin/clang
           export CXX=/usr/local/opt/llvm/bin/clang++
-          git clone -b ${GITHUB_REF#refs/heads/} https://github.com/motiwari/BanditPAM
           cd BanditPAM
           mkdir build
           cd build

.github/workflows/run_linux_tests.yml

@@ -24,8 +24,9 @@ jobs:
       - name: Install Python dependencies 
         run: |
           python -m pip install --upgrade pip
-          pip install pytest
-          pip install -r requirements.txt
+          python -m pip install pytest
+          python -m pip install -r requirements.txt
+          python -m pip install --upgrade pip setuptools wheel
 
       - name: Install Armadillo 10.7.5+
         run: |
@@ -50,7 +51,7 @@ jobs:
         run: |
           # The flags are necessary to ignore the pyproject.toml
           # See https://github.com/pypa/pip/issues/9738
-          pip install --no-use-pep517 --no-build-isolation -vvv -e .
+          python -m pip install --no-use-pep517 --no-build-isolation -vvv -e .
         env:
           # The default compiler on the Github Ubuntu runners is gcc
           # Would need to make a respective include change for clang 
@@ -76,9 +77,16 @@ jobs:
       #   run : |
       #     pytest tests/test_larger.py
 
+      - name: Clone for PR
+        if: ${{ github.event_name == 'pull_request' }}
+        run: git clone -b $GITHUB_HEAD_REF https://github.com/motiwari/BanditPAM
+
+      - name: Clone for Push
+        if: ${{ github.event_name != 'pull_request' }}
+        run: git clone -b ${GITHUB_REF#refs/heads/} https://github.com/motiwari/BanditPAM
+
       - name: Verify that the C++ executable compiles and runs
         run : |
-          git clone -b ${GITHUB_REF#refs/heads/} https://github.com/motiwari/BanditPAM
           cd BanditPAM
           mkdir build
           cd build

.github/workflows/run_mac_tests.yml

@@ -25,8 +25,9 @@ jobs:
       - name: Install Python dependencies
         run: |
           python -m pip install --upgrade pip
-          pip install pytest
-          pip install -r requirements.txt
+          python -m pip install pytest
+          python -m pip install -r requirements.txt
+          python -m pip install --upgrade pip setuptools wheel
 
       - name: Install Armadillo 10.7.5+
         run: |
@@ -51,7 +52,7 @@ jobs:
         run: |
           # The flags are necessary to ignore the pyproject.toml
           # See https://github.com/pypa/pip/issues/9738
-          pip install --no-use-pep517 --no-build-isolation -vvv -e .
+          python -m pip install --no-use-pep517 --no-build-isolation -vvv -e .
         env:
           # The default compiler on the Github Ubuntu runners is gcc
           # Would need to make a respective include change for clang

.github/workflows/run_style_checks.yml

@@ -22,8 +22,8 @@ jobs:
       - name: Install Python dependencies
         run: |
           python -m pip install --upgrade pip
-          pip install flake8 pytest cpplint
-          pip install -r requirements.txt
+          python -m pip install flake8 pytest cpplint
+          python -m pip install -r requirements.txt
 
       - name: Lint with flake8
         run: |

.github/workflows/run_windows_tests.yml

@@ -25,8 +25,8 @@ jobs:
       - name: Install Python dependencies 
         run: |
           python -m pip install --upgrade pip
-          pip install pytest
-          pip install -r requirements.txt
+          python -m pip install pytest
+          python -m pip install -r requirements.txt
       - name: Install Armadillo 10.7.5+
         run: |
           cd ~
@@ -45,7 +45,7 @@ jobs:
           cd ~
       - name: Install BanditPAM package
         run: |
-          pip install -vvv -e .
+          python -m pip install -vvv -e .
         env:
           # The default compiler on the Github Ubuntu runners is gcc
           # Would need to make a respective include change for clang 

README.md

@@ -24,7 +24,7 @@ Mo Tiwari, Martin Jinye Zhang, James Mayclin, Sebastian Thrun, Chris Piech, Ilan
 ```
 
 # Requirements
-# TL;DR run `pip install banditpam` or `install.packages(banditpam)` and jump to the [examples](https://github.com/motiwari/BanditPAM#example-1-synthetic-data-from-a-gaussian-mixture-model). 
+# TL;DR run `python -m pip install banditpam` or `install.packages(banditpam)` and jump to the [examples](https://github.com/motiwari/BanditPAM#example-1-synthetic-data-from-a-gaussian-mixture-model). 
 
 If you have any difficulties, please see the [platform-specific guides](https://github.com/motiwari/BanditPAM#platform-specific-installation-guides) and file a Github issue if you have additional trouble.
 
@@ -41,17 +41,17 @@ If you have any difficulties, please see the [platform-specific guides](https://
 ## Install the repo and its dependencies:
 This can be done either through PyPI (recommended)
 ```python
-/BanditPAM/: pip install -r requirements.txt
-/BanditPAM/: pip install banditpam
+/BanditPAM/: python -m pip install -r requirements.txt
+/BanditPAM/: python -m pip install banditpam
 ```
 OR through the source code via
 ```python
 /BanditPAM/: git submodule update --init --recursive
 /BanditPAM/: cd headers/carma
 /BanditPAM/: mkdir build && cd build && cmake -DCARMA_INSTALL_LIB=ON .. && sudo cmake --build . --config Release --target install
 /BanditPAM/: cd ../../..
-/BanditPAM/: pip install -r requirements.txt
-/BanditPAM/: sudo pip install .
+/BanditPAM/: python -m pip install -r requirements.txt
+/BanditPAM/: sudo python -m pip install .
 ```
 
 ### Example 1: Synthetic data from a Gaussian Mixture Model
@@ -201,7 +201,7 @@ The package currently supports a number of distance metrics, including all $L_p$
 
 If you're willing to write a little C++, you only need to add a few lines to [kmedoids_algorithm.cpp](https://github.com/motiwari/BanditPAM/blob/main/src/kmedoids_algorithm.cpp#L560-L615) and [kmedoids_algorithm.hpp](https://github.com/motiwari/BanditPAM/blob/main/headers/kmedoids_algorithm.hpp#L136-L142) to implement your distance metric / pairwise dissimilarity!
 
-Then, be sure to re-install the repository with a `pip install .` (note the trailing `.`).
+Then, be sure to re-install the repository with a `python -m pip install .` (note the trailing `.`).
 
 The maintainers of this repository are working on permitting arbitrary dissimilarity metrics that users write in Python, as well; see [#4](https://github.com/motiwari/BanditPAM/issues/4).
 

docs/install_linux.md

@@ -12,7 +12,7 @@ Please ensure the following dependencies are installed:
  - CARMA: via the instructions in [its guide](https://github.com/RUrlus/carma#installation)
  - Python3: if not installed, we recommend installing Python3 via [Anaconda](https://www.anaconda.com/products/individual), which is CPython compiled with `clang`
  - `pip` for your Python3 installation: this should be completed if installing via Anaconda above
- - The necessary python packages: via `pip install -r requirements.txt`
+ - The necessary python packages: via `python -m pip install -r requirements.txt`
 
  (NOT RECOMMENDED): Instead of LLVM's `clang`, you can also use another C++ compiler and point your `CC` environment variable to it. Please ensure this is the same compiler used to compile your Python installation if using CPython. If you open a `python` REPL it will show the compiler used during the language installation:
 
@@ -30,8 +30,8 @@ Do not attempt to compile the BanditPAM extension with `gcc` if your Python used
 ## BanditPAM Installation
 
 BanditPAM can then be installed via one of the following ways:
-1) Running `pip install banditpam`, OR
-2) Running `pip install .` in the home directory (`/BanditPAM`)
+1) Running `python -m pip install banditpam`, OR
+2) Running `python -m pip install .` in the home directory (`/BanditPAM`)
 
 ## Known Issues 
 The following is a list of issues seen when installing BanditPAM on Linux. To report a bug, please file an issue at https://github.com/motiwari/BanditPAM/

docs/install_mac.md

@@ -11,7 +11,7 @@ Please ensure the following dependencies are installed:
  - CARMA: via the instructions in [its guide](https://github.com/RUrlus/carma#installation)
  - Python3: if not installed, we recommend installing Python3 via [Anaconda](https://www.anaconda.com/products/individual), which is CPython compiled with `clang`
  - `pip` for your Python3 installation; this should be completed if installing via Anaconda above
- - The necessary python packages: via `pip install -r requirements.txt`
+ - The necessary python packages: via `python -m pip install -r requirements.txt`
 
 (NOT RECOMMENDED): Instead of LLVM's `clang`, you can also use another C++ compiler and point your `CC` environment variable to it. Please ensure this is the same compiler used to compile your Python installation if using CPython. If you open a `python` REPL it will show the compiler used during the language installation:
 
@@ -29,8 +29,8 @@ For the default Python2 installed on Mac, the `Apple clang` compiler is used; fo
 ## BanditPAM Installation
 
 BanditPAM can then be installed via one of the following ways:
-1) Running `pip install banditpam`, OR
-2) Running `pip install .` in the home directory (`/BanditPAM`)
+1) Running `python -m pip install banditpam`, OR
+2) Running `python -m pip install .` in the home directory (`/BanditPAM`)
 
 ## Known Issues 
 The following is a list of issues seen when installing BanditPAM on MacOS. To report a bug, please file an issue at https://github.com/motiwari/BanditPAM/

docs/install_windows.md

@@ -1,38 +1,30 @@
 # Installation Tutorial for Windows
 
-The following is a description of the installation process of BanditPAM for Windows. This assumes that:
+The following is a more detailed description of the installation process of BanditPAM for Windows.
 
 ## Prerequisites
 Please ensure the following dependencies are installed:
- - A C++ compiler; we recommend LLVM's `clang`: via the [LLVM installation instructions](https://clang.llvm.org/get_started.html)
- - OpenMP: if using LLVM's `clang`, then OpenMP is already enabled
- - `CMake`: via the [CMake installation instructions](https://cmake.org/install/)
- - Armadillo: via the [Armadillo installation instructions](http://arma.sourceforge.net/download.html)
+ - Visual Studio (2022 is recommended) with "Desktop development with C++" workload: via the [Visual Studio download page](https://visualstudio.microsoft.com/vs/)
+ - The Armadillo library: via `git clone https://gitlab.com/conradsnicta/armadillo-code.git armadillo` in the `headers` directory
  - CARMA: via the instructions in [its guide](https://github.com/RUrlus/carma#installation)
- - Python3: if not installed, we recommend installing Python3 via [Anaconda](https://www.anaconda.com/products/individual), which is CPython compiled with `clang`
+ - Python3: if not installed, we recommend installing Python3 via [Anaconda](https://www.anaconda.com/products/individual)
  - `pip` for your Python3 installation: this should be completed if installing via Anaconda above
- - The necessary python packages: via `pip install -r requirements.txt`
-
- (NOT RECOMMENDED): Instead of LLVM's `clang`, you can also use another C++ compiler and point your `CC` environment variable to it. Please ensure this is the same compiler used to compile your Python installation if using CPython. If you open a `python` REPL it will show the compiler used during the language installation:
-
- ```
- >> python
-Python 3.7.9 (default, Mar  1 2021, 13:32:26)
-[Clang 11.0.0 (clang-1100.0.33.17)] :: Intel Corporation on darwin
-Type "help", "copyright", "credits" or "license" for more information.
-Intel(R) Distribution for Python is brought to you by Intel Corporation.
-Please check out: https://software.intel.com/en-us/python-distribution
-```
-
-Do not attempt to compile the BanditPAM extension with `gcc` if your Python used `clang`, and vice versa.
+ - The necessary python packages: via `python -m pip install -r requirements.txt`
 
 ## BanditPAM Installation
 
-BanditPAM can then be installed via one of the following ways:
-1) Running `pip install banditpam`, OR
-2) Running `pip install .` in the home directory (`/BanditPAM`)
+CMake Build:
 
-## Known Issues 
-The following is a list of issues seen when installing BanditPAM on Windows. To report a bug, please file an issue at https://github.com/motiwari/BanditPAM/
+1) Run `scripts/retrieve_windows_cmake_files.sh` to retrieve the files necessary for the Windows CMake build
+2) Add the Visual Studio IDE location to PATH in Environment Variables (e.g. `C:\Program Files\Microsoft Visual Studio\2022\Community\Common7\IDE`).
+3) Add `${project_dir}\headers\armadillo\examples\lib_win64` to PATH 
+4) Run `devenv BanditPAM.sln /Build "Release|x64"` after `cmake ..` in a prompt other than Git Bash
+5) The `.exe` will be located in `build/src/Release`
 
-- You may run into an error like `error: ‘class arma::Mat<float>’ has no member named ‘n_alloc’`; this is fundamentally due to an [error in CARMA](https://github.com/RUrlus/carma/pull/98). If this isn't fixed by the time you're reading this, follow the fix described in [this issue](https://github.com/motiwari/BanditPAM/issues/169).
+Python Build:
+1) Run `python -m pip install banditpam`, OR
+2) Follow these steps:
+   1) Add the location of `cl.exe` to PATH in Environment Variables (e.g. `C:\Program Files\Microsoft Visual Studio\2022\Community\VC\Tools\MSVC\14.34.31933\bin\Hostx64\x64`).
+   2) Run `python -m pip install .` in the home directory (`/BanditPAM`)
+   2) Add the file `C:\Program Files\Microsoft Visual Studio\2022\Community\VC\Tools\MSVC\14.34.31933\bin\Hostx86\x64\clang_rt.asan_dynamic-x86_64.dll` to `build\lib.win-amd64-cpython-310`
+   3) Run `python -m pip install .` in the home directory (`/BanditPAM`)