PolyPhy is an unconventional toolkit for reconstructing continuous networks out of sparse 2D or 3D data. Such data can be defined as collections of discrete points, or a continuous sparse scalar field. PolyPhy produces a scalar density field that defines the recovered network structure. With the help of GPU-accelerated simulation and visualization, PolyPhy provides domain experts an interactive way to reconstruct discrete geometric data with an underlying network structure. The reconstruction is driven by the Monte Carlo Physarum Machine algorithm, a metaheuristic inspired by the morphology and dynamics of Physarum polycephalum aka 'slime mold'.

• PolyPhy is a successor of Polyphorm
• Main GitHub page: PolyPhy Hub
• Official website: polyphy.io
• Underlying research: overview and publications

• Decent GPU, currently tested NVIDIA GPUs, other brands subject to support by the Taichi API
  • CPU fallback available for debugging purposes
• Recent Windows, Linux or Mac OS
• Python 3.x, Anaconda recommended

The repository is located at the following GitHub URL:
https://github.com/PolyPhyHub/PolyPhy.git

The use-cases currently supported by PolyPhy are divided according to the data workflow they are built around. Each use-case has a corresponding Jupyter notebook that implements it located in ./experiments/Jupyter. This section reviews them case by case, and the following section provides an extensive tutorial recorded at the recent OSPO Symposium 2022.

• 2D self-patterning is the most basic use-case implemented within the ./experiments/Jupyter/PolyPhy_2D_discrete_data notebook. The ability of MCPM to generate a diversity of patterns with network characteristics is achieved by disabling the data marker deposition, leaving only the MCPM agents to generate the marker responsible for maintaining structure.

  

• 2D procedural pipeline provide an easy environment to experiment with the behavior of PolyPhy in the presence of discrete data with different spatial frequencies. Editing (adding new data points) is also supported. This pipeline is implemented in the ./experiments/Jupyter/PolyPhy_2D_discrete_data notebook.

  

• 2D discrete pipeline implements the canonical way of working with custom data defined by a CSV file. The example below demonstrates fitting to a 2D projection of the SDSS galaxy dataset. This pipeline is implemented in the ./experiments/Jupyter/PolyPhy_2D_discrete_data notebook.

  

• 2D continuous pipeline demonstrates the workflow with a continuous user-provided dataset. Instead of a discrete set of points as in the previous use-cases, the data is defined by a scalar field, which in 2D amounts to a grayscale image. The example below approximates the US road network using only a sparse population density map as the input. This pipeline is implemented in the ./experiments/Jupyter/PolyPhy_2D_continuous_data notebook.

  

• 3D discrete pipeline represents an equivalent functionality to the original Polyphorm implementation. The dataset consists of SDSS galaxies defined as a weighted collection of 3D points. THe visualization is based on volumetric ray marching simultaneously fetching the deposit and the trace fields. This pipeline is implemented in the ./experiments/Jupyter/PolyPhy_3D_discrete_data notebook.

  

Below is a recording of the PolyPhy Workshop given as part of the OSPO Symposium 2022.
This 93-minute workshop covers PolyPhy's research background, all of the 5 above usecases, and extended technical discussion.

To build the docker image:

docker build . -t polyphy

To run the docker container:

docker run -it polyphy

Optional:
If you want to work with jupyter notebook and develop:

docker run -it -p 8000:8000 -p 8888:8888 polyphy

Navigate to the repository root and run:

pip install . -U

From the command line run:

pip install polyphy

Please note that the latest PolyPhy code is currently undergoing refactoring and the latest functionality presented in the Jupyter notebooks described above is not fully ported yet.

Running PolyPhy from the command line:

✗ polyphy
[Taichi] version 1.0.3, llvm 10.0.0, commit fae94a21, osx, python 3.8.9
usage: polyphy [-h] [-v] [-q] {run2d,run3d} ...

positional arguments:
  {run2d,run3d}  sub command help
    run2d        run 2D PolyPhy
    run3d        run 3D PolyPhy

optional arguments:
  -h, --help     show this help message and exit
  -v, --version  show program's version number and exit
  -q, --quiet    suppress output

Running polyphy2d/3d using the Python interface:

✗ python
Python 3.8.9 (default, Apr 13 2022, 08:48:06)
[Clang 13.1.6 (clang-1316.0.21.2.5)] on darwin
Type "help", "copyright", "credits" or "license" for more information.
>>> import polyphy
[Taichi] version 1.0.3, llvm 10.0.0, commit fae94a21, windows, python 3.8.9
>>> polyphy.lib.run_2D()
[Taichi] Starting on arch=CUDA
...

Tox is a virtual environment management and test tool that allows you to define and run custom tasks that call executables from Python packages. Tox will download the dependencies you have specified, build the package, install it in a virtual environment and run the tests using pytest. Make sure to install tox in the root of your project if you intend to work on the development.

tox # download dependencies, build and install package, run tests
tox -e docs  # to build your documentation
tox -e build  # to build your package distribution
tox -e publish  # to test your project uploads correctly in test.pypi.org
tox -e publish --repository pypi  # to release your package to PyPI
tox -av  # to list all the tasks available

GitHub Actions is being used to test on MacOs as well as Linux. It allows for the automation of the building, testing, and deployment pipline.

A service that generates a visual report of how much code has been tested. All configuration settings can be found in the codecov.yml file.

A service that can be used to test Windows. All configuration settings can be found in the appveyor.yml file.