Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
98 changes: 12 additions & 86 deletions README.md
Original file line number Diff line number Diff line change
Expand Up @@ -85,105 +85,31 @@ plt.show()

![layers](./docs/_static/layers.png)

## Installation instructions

## Local development

The development workflow works best by pre-installing python dependencies with
`pip` (or alternatives):

```bash
pip install numpy scipy matplotlib scikit-learn scikit-build-core nanobind setuptools_scm
```

Building the package requires cmake and a C++ 23 compiler with OpenMP support.
The OpenMP version must support user-defined reductions. Selecting the proper
OpenMP version requires some additional configuration, see below. Assuming the
compiler and OpenMP are present, the package can be compiled and installed with:

```bash
pip install --no-deps --no-build-isolation -ve .
```

To change the build type, add `-C cmake.build-type=Debug` or `-C
cmake.build-type=Release` to the command.

`scikit-build-core` also experimentally supports editable installs (see [their
documentation](https://scikit-build-core.readthedocs.io/en/latest/configuration/index.html#editable-installs)):

```bash
pip install --no-deps --no-build-isolation -C editable.rebuild=true -ve .
```

### Linux

It may be necessary to tell cmake which compiler it should use. For example,
using `g++-14` when that is not the system default can be done by adding a `-C
cmake.args="-DCMAKE_CXX_COMPILER=g++-14"` option. The `-C cmake.args=...` option
does not have to be repeated on rebuilds.

### MacOS

MacOS requires installing OpenMP using homebrew:
Pre-build binaries are available on [pypi](https://badge.fury.io/py/fast-plscan), so the package can be installed with `pip` and similar package managers on most systems:

```bash
brew install libomp
pip install fast_plscan
```

Also update the `~/.zshrc` config file with:

```bash
export OpenMP_ROOT=$(brew --prefix)/opt/libomp
```

or pass `OpenMP_ROOT` as cmake argument:

```bash
pip install --no-deps --no-build-isolation \
-C cmake.args="-DOpenMP_ROOT=$(brew --prefix)/opt/libomp" \
-ve .
```

### Windows

The default MSVC C++ compiler on windows does not support
a recent enough OpenMP. In addition, the default powershell terminal on windows
is not configured for cmake to find the correct OpenMP version. Instead, use a
developer powershell configured for a 64-bit target architecture. To open such a
terminal, run the following code in a normal Powershell terminal:

```powershell
$vswhere = "${env:ProgramFiles(x86)}/Microsoft Visual Studio/Installer/vswhere.exe"
$iloc = & $vswhere -products * -latest -property installationpath
$devddl = "$iloc/Common7/Tools/Microsoft.VisualStudio.DevShell.dll"
Import-Module $devddl; Enter-VsDevShell -Arch amd64 -VsInstallPath $iloc -SkipAutomaticLocation
```

In addition, select the MSVC Clang compiler using `-C cmake.args="-T
ClangCL"` the first time the package is installed:

```powershell
pip install --no-deps --no-build-isolation -C cmake.args="-T ClangCL" -ve .
```

The `-C cmake.args=...` option does not have to be repeated on rebuilds.

You may need to install the [visual studio build
tools](https://visualstudio.microsoft.com/downloads/#build-tools-for-visual-studio-2022)
with the optional Clang compiler support enabled.
Conda forge builds are in progress. See [our
documentation](https://fast-plscan.readthedocs.io/en/latest/local_development.html)
for instructions on compiling the package locally.

## Citing

When using this work, please cite our (upcoming) preprint:
When using this work, please cite [our preprint](https://arxiv.org/abs/2512.16558):

```bibtex
@article{bot2025plscan,
@misc{bot2025plscan,
title = {Persistent Multiscale Density-based Clustering},
author = {Dani{\"{e}}l M. Bot and Leland McInnes and Jan Aerts},
author = {Dani{\"{e}}l Bot and Leland McInnes and Jan Aerts},
year = {2025},
month = {12},
eprint = {2512.16558},
archiveprefix = {arXiv},
eprint = {TODO},
primaryclass = {cs.CL}
primaryclass = {cs.LG},
url = {https://arxiv.org/abs/2512.16558}
}
```

Expand Down
26 changes: 20 additions & 6 deletions docs/index.rst
Original file line number Diff line number Diff line change
Expand Up @@ -125,21 +125,35 @@ strengths.
:alt: layers scatterplot


Installation instructions
-------------------------

Pre-build binaries are available on
`pypi <https://badge.fury.io/py/fast-plscan>`_, so the package can be installed
with `pip` and similar package managers on most systems:

.. code-block:: bash

pip install fast-plscan

Conda forge builds are in progress. See `our documentation <local_development.html>`_
for instructions on compiling the package locally.

Citing
------

When using this work, please cite our (upcoming) preprint:
When using this work, please cite our preprint:

.. code-block:: bibtex

@article{bot2025plscan,
@misc{bot2025plscan,
title = {Persistent Multiscale Density-based Clustering},
author = {Dani{\"{e}}l M. Bot and Leland McInnes and Jan Aerts},
author = {Dani{\"{e}}l Bot and Leland McInnes and Jan Aerts},
year = {2025},
month = {12},
eprint = {2512.16558},
archiveprefix = {arXiv},
eprint = {TODO},
primaryclass = {cs.CL}
primaryclass = {cs.LG},
url = {https://arxiv.org/abs/2512.16558}
}


Expand Down