Installation Guide

π-PIC has been tested and confirmed to work on Linux, macOS, and Windows (via WSL).

System Requirements

Before installing π-PIC, ensure you have the following:

Python 3.10+
gcc (C/C++ compiler, 64-bit)
fftw3 (Fast Fourier Transform library, 64-bit)
openmp (OpenMP parallel computing library)

Python packages (automatically installed with pipic):

numba — JIT compiler for Python
numpy — Numerical computing library

Installation Methods

PyPI (Recommended)

The easiest installation method is via PyPI:

pip install pipic

If using a non-standard compiler (e.g., custom gcc on macOS), specify it:

CC=<c-compiler> CXX=<c++-compiler> pip install pipic

Conda (tested for Linux)

If Conda is not installed, follow: https://www.anaconda.com/docs/getting-started/miniconda/install

Then run:

wget -O environment.yml https://raw.githubusercontent.com/hi-chi/pipic/main/environment.yml
conda env create -f environment.yml
conda activate pipic_env

Build and install from source

To install the latest version or a specific branch from GitHub follow these instructions. To build from a local modified version, navigate to project root directory and start from step 4.

Create and enter a directory:
```
mkdir pipic-dev
cd pipic-dev
```

Clone the repository:

git clone https://github.com/hi-chi/pipic.git
cd pipic

(Optional) Switch to a specific branch:
```
git checkout <branch-name>
```
(Optional) Uninstall any existing version:
```
pip uninstall pipic
```
Install from source:
```
python3 -m pip install .
```
(Optional) Test the installation:
```
python3 examples/basic_example.py
```

Platform-Specific Instructions

Linux

On most Linux distributions, install dependencies using your package manager:

Debian/Ubuntu:

sudo apt-get install build-essential python3 python3-dev libfftw3-dev libomp-dev

Fedora/RHEL:

sudo yum install gcc gcc-c++ python3-devel fftw-devel libomp-devel

Then install pipic:

pip install pipic

macOS

Official macOS wheels are currently built for Apple Silicon (arm64) only. If you have this architecture pip install pipic should be sufficient.

On Intel Macs (x86_64), pip install pipic will typically fall back to a source build (sdist). This requires a working compiler toolchain and system libraries (fftw, OpenMP/libomp), otherwise installation may fail.

If pip install pipic fails, try installing the dependecies. How to do that depends on which compiler you use.

Using GCC (via Homebrew)

Homebrew’s gcc includes OpenMP; the built-in macOS gcc (which is actually clang) does not.

Install dependencies:
```
brew install fftw gcc
```
Identify your gcc version (e.g., gcc-14):
```
gcc --version
```

Set environment variables and install:

export LDFLAGS="-L$(brew --prefix)/opt/fftw/lib"
export CPPFLAGS="-I$(brew --prefix)/opt/fftw/include"
CC=gcc-14 CXX=g++-14 pip install pipic

(Replace gcc-14 and g++-14 with your actual gcc version.)

(Optional) Make the exports permanent by adding them to ~/.bashrc or ~/.zprofile:

echo 'export LDFLAGS="-L$(brew --prefix)/opt/fftw/lib"' >> ~/.zprofile
echo 'export CPPFLAGS="-I$(brew --prefix)/opt/fftw/include"' >> ~/.zprofile

Using Clang (with Homebrew libomp)

Install dependencies:
```
brew install fftw libomp
```

Set environment variables and install:

export LDFLAGS="-L$(brew --prefix)/opt/fftw/lib -L$(brew --prefix)/opt/libomp/lib"
export CPPFLAGS="-I$(brew --prefix)/opt/fftw/include -I$(brew --prefix)/opt/libomp/include"
pip install pipic

(Optional) Make the exports permanent by adding them to ~/.bashrc or ~/.zprofile.

Windows

Use Windows Subsystem for Linux (WSL) and follow the Linux instructions above.

Enable WSL:
```
wsl --install
```

Inside WSL, install dependencies (Ubuntu/Debian):

sudo apt-get install build-essential python3 python3-dev libfftw3-dev libomp-dev

Install pipic:
```
pip install pipic
```

Verification

After installation, verify everything works:

python3 -c "import pipic; print(pipic.__version__)"

Or run one of the included examples:

python3 examples/basic_example.py

If successful, you should see output without errors. For example output, refer to examples/.

Troubleshooting

Error: Could not find compiler

Ensure gcc and g++ are installed and in your PATH:

gcc --version
g++ --version

If not found, install them or adjust your PATH.

Error: fftw3 not found

Install fftw3 development libraries:

Linux (Debian): sudo apt-get install libfftw3-dev
Linux (Fedora): sudo yum install fftw-devel
macOS: brew install fftw

Error: OpenMP not found

Linux: Usually included with gcc. If missing, install libomp-dev or libomp-devel.
macOS: brew install libomp