# PCX -- Predictive Coding Networks Made Simple
## Introduction
PCX is a Python JAX-based library designed to develop highly configurable predictive coding networks. Please refer to the tutorial notebooks in the examples folder to get started. PCX can be installed by following one of the listed three methods.
## Default: Installation via PIP [Method #1].
First, create an environment with Python >= 3.10 and [install JAX](https://github.com/google/jax#installation) in the correct version for your accelerator device. For cuda >= 12.0, the command is
```shell
pip install -U "jax[cuda12]"
```
For CPU only:
```shell
pip install -U "jax[cpu]"
```
Then you hav two options:
- Install a stable version
- Clone this repository and install the package by linking to the this folder. The installation of this libary only links to this folder and thus dynamically updates with all your changes.
### Install stable version
On the right side of the repository, click on "releases" and download the wheel file. You can install it using
```shell
pip install path/to/wheel_file.whl
```
Alternatively you can use the PyPi version by [work in progress...]
### Install dynamically from github
Clone this repository locally and then:
```shell
pip install -e /path/to/this/repo/ --config-settings editable_mode=strict
```
## Ensuring Reproducibility: Installation via `poetry` [Method #2]
**TL;DR** This is an alternative installation method that creates a fully configured environment to ensure your results are reproducible (no pip install, see previous section for that; no docker install, see the next section for docker install):
1. Install [conda](https://www.anaconda.com/).
2. Install [poetry](https://python-poetry.org/).
3. `poetry config virtualenvs.create false`.
4. Create a conda environment with python>=3.10: `conda create -n pcax python=3.10`.
5. Activate the environment: `conda activate pcax`.
6. `cd` into the root pcax folder.
7. `poetry install --no-root`.
In this way, we use [poetry](https://python-poetry.org/) to make sure the environment is 100% reproducible. If you are not familiar with `poetry`, now is a good time to skim through the docs.
### Development Notes:
1. If you need to add a Python package to the environment, use `poetry add package`. Avoid `pip install`!
2. If you want to update a version of an existing package, run `poetry update package`. It will update the package to the latest available version that fits the constraints.
3. **DO NOT** update the package versions in the `pyproject.toml` file manually. Surprisingly, `pyproject.toml` **DOES NOT** specify the versions that will be installed, `poetry.lock` does. So, first check the package version in `poetry.lock`.
4. **DO NOT** update the package versions in the `poetry.lock` file manually. Use `poetry update package` instead. `poetry.lock` **HAS** to be generated and signed automatically.
5. If `pyproject.toml` and `poetry.lock` have diverged for some reason (for example, you've merged another branch and resolved conflicts in `poetry.lock`), use `poetry lock --no-update` to fix the `poetry.lock` file.
6. **DO NOT** commit changes to `pyproject.toml` without running `poetry lock --no-update` to synchronize the `poetry.lock` file. If you commit `pyproject.toml` that is not in sync with `poetry.lock` this will break the automatic environment configuration for everyone.
## Fully Automatic: Environment in Docker with Dev Containers [Method #3]
Run your development environment in a docker container. This is the most straightforward option to work with `pcx`, as the development environment is pre-configured for you.
The `Dockerfile` is located in `pcx/docker`, with the `run.sh` script that builds and runs it. You can play with the `Dockerfile` directly if you know what you are doing or if you don't use VSCode. If you want a fully automated environment setup, then forget about the `pcx/docker` directory and read on.
**Warning**: This image should run on CUDA 12.2 or later, but not earlier. Make sure that your `nvidia-smi` reports CUDA >=12.2. If not, update the base `nvidia/cuda` image and the fix at the bottom in the `docker/Dockerfile` to use the same version of CUDA as your host does.
Requirements:
1. A CUDA >=12.2 enabled machine with an NVIDIA GPU. You can do without a GPU, probably, just omit the steps related to the GPU passthrough and configuration.
2. [Install docker](https://docs.docker.com/engine/install/).
3. Install [nvidia-container-toolkit](https://github.com/NVIDIA/nvidia-container-toolkit) to enable docker to use the GPU.
4. **Make sure to re-start the docker daemon after the previous step**. For example, on Ubuntu this will be `sudo systemctl restart docker`.
5. Install [Visual Studio Code](https://code.visualstudio.com/download).
6. Install the [Dev Containers extension](https://marketplace.visualstudio.com/items?itemName=ms-vscode-remote.remote-containers) in VSCode.
7. Optionally, [read how to develop inside container with VS Code](https://code.visualstudio.com/docs/devcontainers/containers).
Once everything is done, open this project in VS Code and execute the `Dev Containers: Reopen in Container` command (Ctrl/Cmd+Shift+P). This will build the docker image and open the project inside that docker image. Building the docker image for the first time may take around 15-30 minutes, depending on your internet speed.
You can always exit the container by running the `Dev Containers: Reopen folder locally` command.
You can rebuild the container by running the `Dev Containers: Rebuild Container` command.
You can check that you're running inside a container by running `hostname`. If it outputs meaningless 12 characters, then you are inside a container. If it outputs the name of your machine, you are not in a container.
When running a Jupyter Notebook it will prompt you to select an environment. Select Python Environments -> Python 3.10 (any of them, as they are the same).
**Important notes**:
- You are not supposed to modify the `docker/Dockerfile` unless you perfectly know what you are doing and why.
- You are not supposed to run the docker container directly. The Dev Containers extension will do this for you. If you think you need to `docker run -it` then something is really wrong.
- Use `poetry` to add a python package to the environment: `poetry add --group dev [package]`. The `--group dev` part should be omitted if this package is needed for the core `pcx` code. Try not to install packages with `pip`.
- Please update your docker to >>20.10.9. [This image is known not to work with docker <= 20.10.9](https://stackoverflow.com/questions/71941032/why-i-cannot-run-apt-update-inside-a-fresh-ubuntu22-04). It failes with the following message: `E: Problem executing scripts APT::Update::Post-Invoke 'rm -f /var/cache/apt/archives/*.deb /var/cache/apt/archives/partial/*.deb /var/cache/apt/*.bin || true'`.
- Sometimes Pylance fails to start because it depends on the Python extension that starts later. In this case, just reload the window by running the `Developer: Reload window` command.
**PyTorch with GPU support**: By default, the image will install a CPU-only PyTorch. If you need GPU support with PyTorch, do the following:
1. Open the project in a container using DevContainers as described above.
2. Replace ALL occurrences of `source = "torch-cpu"` with `source = "torch-gpu"` in the [pyproject.toml](./pyproject.toml) file.
3. Run `poetry lock --no-update` to re-generate the `poetry.lock` file. Note that you should do it while running inside the container.
4. Run `poetry install`. Make sure you run it inside the container. It will take up to 20 minutes.
## Citation
If you found this library to be useful in your work, then please cite: [arXiv link](https://arxiv.org/abs/2407.01163)
```bibtex
@article{pinchetti2024benchmarkingpredictivecodingnetworks,
title={Benchmarking Predictive Coding Networks -- Made Simple},
author={Luca Pinchetti and Chang Qi and Oleh Lokshyn and Gaspard Olivers and Cornelius Emde and Mufeng Tang and Amine M'Charrak and Simon Frieder and Bayar Menzat and Rafal Bogacz and Thomas Lukasiewicz and Tommaso Salvatori},
year={2024},
eprint={2407.01163},
archivePrefix={arXiv},
primaryClass={cs.LG},
url={https://arxiv.org/abs/2407.01163},
}
```
For the code relative to the experiments performed in the above paper, please refer to the [Submission of Benchmark Paper](https://github.com/liukidar/pcax/releases/tag/v0.6.1) code release.
## Documentation
The documentation is available at: [https://pcx.readthedocs.io/en/stable/](https://pcx.readthedocs.io/en/stable/)
To learn how to build it yourself, go to `/docs/README.md`.
## Contributing
If you want to contribute to the project, please read [CONTRIBUTING.md](CONTRIBUTING.md)
Raw data
{
"_id": null,
"home_page": "https://github.com/liukidar/pcx",
"name": "pcx",
"maintainer": null,
"docs_url": null,
"requires_python": "<4.0,>=3.11",
"maintainer_email": null,
"keywords": "predictive coding, machine learning, neuroscience",
"author": "Luca Pinchetti",
"author_email": "luca.pinchetti@cs.ox.ac.uk",
"download_url": "https://files.pythonhosted.org/packages/81/eb/84b295fcddae9af095baed76a1cc19a640a50303216a688dfa8a9487b947/pcx-0.6.2.post3.tar.gz",
"platform": null,
"description": "# PCX -- Predictive Coding Networks Made Simple\n\n## Introduction\n\nPCX is a Python JAX-based library designed to develop highly configurable predictive coding networks. Please refer to the tutorial notebooks in the examples folder to get started. PCX can be installed by following one of the listed three methods.\n\n## Default: Installation via PIP [Method #1].\n\nFirst, create an environment with Python >= 3.10 and [install JAX](https://github.com/google/jax#installation) in the correct version for your accelerator device. For cuda >= 12.0, the command is\n\n```shell\npip install -U \"jax[cuda12]\"\n```\n\nFor CPU only:\n\n```shell\npip install -U \"jax[cpu]\"\n```\n\nThen you hav two options:\n\n- Install a stable version\n- Clone this repository and install the package by linking to the this folder. The installation of this libary only links to this folder and thus dynamically updates with all your changes.\n\n### Install stable version\n\nOn the right side of the repository, click on \"releases\" and download the wheel file. You can install it using\n\n```shell\npip install path/to/wheel_file.whl\n```\n\nAlternatively you can use the PyPi version by [work in progress...]\n\n### Install dynamically from github\n\nClone this repository locally and then:\n\n```shell\npip install -e /path/to/this/repo/ --config-settings editable_mode=strict\n```\n\n## Ensuring Reproducibility: Installation via `poetry` [Method #2]\n\n**TL;DR** This is an alternative installation method that creates a fully configured environment to ensure your results are reproducible (no pip install, see previous section for that; no docker install, see the next section for docker install):\n\n1. Install [conda](https://www.anaconda.com/).\n2. Install [poetry](https://python-poetry.org/).\n3. `poetry config virtualenvs.create false`.\n4. Create a conda environment with python>=3.10: `conda create -n pcax python=3.10`.\n5. Activate the environment: `conda activate pcax`.\n6. `cd` into the root pcax folder.\n7. `poetry install --no-root`.\n\nIn this way, we use [poetry](https://python-poetry.org/) to make sure the environment is 100% reproducible. If you are not familiar with `poetry`, now is a good time to skim through the docs.\n\n### Development Notes:\n\n1. If you need to add a Python package to the environment, use `poetry add package`. Avoid `pip install`!\n2. If you want to update a version of an existing package, run `poetry update package`. It will update the package to the latest available version that fits the constraints.\n3. **DO NOT** update the package versions in the `pyproject.toml` file manually. Surprisingly, `pyproject.toml` **DOES NOT** specify the versions that will be installed, `poetry.lock` does. So, first check the package version in `poetry.lock`.\n4. **DO NOT** update the package versions in the `poetry.lock` file manually. Use `poetry update package` instead. `poetry.lock` **HAS** to be generated and signed automatically.\n5. If `pyproject.toml` and `poetry.lock` have diverged for some reason (for example, you've merged another branch and resolved conflicts in `poetry.lock`), use `poetry lock --no-update` to fix the `poetry.lock` file.\n6. **DO NOT** commit changes to `pyproject.toml` without running `poetry lock --no-update` to synchronize the `poetry.lock` file. If you commit `pyproject.toml` that is not in sync with `poetry.lock` this will break the automatic environment configuration for everyone.\n\n## Fully Automatic: Environment in Docker with Dev Containers [Method #3]\n\nRun your development environment in a docker container. This is the most straightforward option to work with `pcx`, as the development environment is pre-configured for you.\n\nThe `Dockerfile` is located in `pcx/docker`, with the `run.sh` script that builds and runs it. You can play with the `Dockerfile` directly if you know what you are doing or if you don't use VSCode. If you want a fully automated environment setup, then forget about the `pcx/docker` directory and read on.\n\n**Warning**: This image should run on CUDA 12.2 or later, but not earlier. Make sure that your `nvidia-smi` reports CUDA >=12.2. If not, update the base `nvidia/cuda` image and the fix at the bottom in the `docker/Dockerfile` to use the same version of CUDA as your host does.\n\nRequirements:\n\n1. A CUDA >=12.2 enabled machine with an NVIDIA GPU. You can do without a GPU, probably, just omit the steps related to the GPU passthrough and configuration.\n2. [Install docker](https://docs.docker.com/engine/install/).\n3. Install [nvidia-container-toolkit](https://github.com/NVIDIA/nvidia-container-toolkit) to enable docker to use the GPU.\n4. **Make sure to re-start the docker daemon after the previous step**. For example, on Ubuntu this will be `sudo systemctl restart docker`.\n5. Install [Visual Studio Code](https://code.visualstudio.com/download).\n6. Install the [Dev Containers extension](https://marketplace.visualstudio.com/items?itemName=ms-vscode-remote.remote-containers) in VSCode.\n7. Optionally, [read how to develop inside container with VS Code](https://code.visualstudio.com/docs/devcontainers/containers).\n\nOnce everything is done, open this project in VS Code and execute the `Dev Containers: Reopen in Container` command (Ctrl/Cmd+Shift+P). This will build the docker image and open the project inside that docker image. Building the docker image for the first time may take around 15-30 minutes, depending on your internet speed.\n\nYou can always exit the container by running the `Dev Containers: Reopen folder locally` command.\nYou can rebuild the container by running the `Dev Containers: Rebuild Container` command.\n\nYou can check that you're running inside a container by running `hostname`. If it outputs meaningless 12 characters, then you are inside a container. If it outputs the name of your machine, you are not in a container.\n\nWhen running a Jupyter Notebook it will prompt you to select an environment. Select Python Environments -> Python 3.10 (any of them, as they are the same).\n\n**Important notes**:\n\n- You are not supposed to modify the `docker/Dockerfile` unless you perfectly know what you are doing and why.\n- You are not supposed to run the docker container directly. The Dev Containers extension will do this for you. If you think you need to `docker run -it` then something is really wrong.\n- Use `poetry` to add a python package to the environment: `poetry add --group dev [package]`. The `--group dev` part should be omitted if this package is needed for the core `pcx` code. Try not to install packages with `pip`.\n- Please update your docker to >>20.10.9. [This image is known not to work with docker <= 20.10.9](https://stackoverflow.com/questions/71941032/why-i-cannot-run-apt-update-inside-a-fresh-ubuntu22-04). It failes with the following message: `E: Problem executing scripts APT::Update::Post-Invoke 'rm -f /var/cache/apt/archives/*.deb /var/cache/apt/archives/partial/*.deb /var/cache/apt/*.bin || true'`.\n- Sometimes Pylance fails to start because it depends on the Python extension that starts later. In this case, just reload the window by running the `Developer: Reload window` command.\n\n**PyTorch with GPU support**: By default, the image will install a CPU-only PyTorch. If you need GPU support with PyTorch, do the following:\n\n1. Open the project in a container using DevContainers as described above.\n2. Replace ALL occurrences of `source = \"torch-cpu\"` with `source = \"torch-gpu\"` in the [pyproject.toml](./pyproject.toml) file.\n3. Run `poetry lock --no-update` to re-generate the `poetry.lock` file. Note that you should do it while running inside the container.\n4. Run `poetry install`. Make sure you run it inside the container. It will take up to 20 minutes.\n\n## Citation\nIf you found this library to be useful in your work, then please cite: [arXiv link](https://arxiv.org/abs/2407.01163)\n\n```bibtex\n@article{pinchetti2024benchmarkingpredictivecodingnetworks,\n title={Benchmarking Predictive Coding Networks -- Made Simple}, \n author={Luca Pinchetti and Chang Qi and Oleh Lokshyn and Gaspard Olivers and Cornelius Emde and Mufeng Tang and Amine M'Charrak and Simon Frieder and Bayar Menzat and Rafal Bogacz and Thomas Lukasiewicz and Tommaso Salvatori},\n year={2024},\n eprint={2407.01163},\n archivePrefix={arXiv},\n primaryClass={cs.LG},\n url={https://arxiv.org/abs/2407.01163}, \n}\n```\n\nFor the code relative to the experiments performed in the above paper, please refer to the [Submission of Benchmark Paper](https://github.com/liukidar/pcax/releases/tag/v0.6.1) code release.\n\n## Documentation\n\nThe documentation is available at: [https://pcx.readthedocs.io/en/stable/](https://pcx.readthedocs.io/en/stable/)\n\nTo learn how to build it yourself, go to `/docs/README.md`.\n\n##\u00a0Contributing\n\nIf you want to contribute to the project, please read [CONTRIBUTING.md](CONTRIBUTING.md)\n\n",
"bugtrack_url": null,
"license": "Apache-2.0",
"summary": "PCX is a Python JAX-based library designed to develop highly configurable predictive coding networks.",
"version": "0.6.2.post3",
"project_urls": {
"Documentation": "https://pcx.readthedocs.io/en/latest/",
"Homepage": "https://github.com/liukidar/pcx",
"Repository": "https://github.com/liukidar/pcx"
},
"split_keywords": [
"predictive coding",
" machine learning",
" neuroscience"
],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "ea81ffe01761fcdc5c745676e513f4fdd43926eb734d03ffce4bf2b14bc49f8f",
"md5": "53714ed96194e9828ab4edef585d9332",
"sha256": "9d75d202ac44f5f5765550b34f57b055e1b71fc84003088645561a08a70e4cc5"
},
"downloads": -1,
"filename": "pcx-0.6.2.post3-py3-none-any.whl",
"has_sig": false,
"md5_digest": "53714ed96194e9828ab4edef585d9332",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": "<4.0,>=3.11",
"size": 49406,
"upload_time": "2024-11-03T18:21:17",
"upload_time_iso_8601": "2024-11-03T18:21:17.491147Z",
"url": "https://files.pythonhosted.org/packages/ea/81/ffe01761fcdc5c745676e513f4fdd43926eb734d03ffce4bf2b14bc49f8f/pcx-0.6.2.post3-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "81eb84b295fcddae9af095baed76a1cc19a640a50303216a688dfa8a9487b947",
"md5": "ef215570b9c4fac9ecb794dbb1b97199",
"sha256": "4e3d310554f11c649e6a0f36085b554e1009974f95d86b81a539ecb91d0f1d04"
},
"downloads": -1,
"filename": "pcx-0.6.2.post3.tar.gz",
"has_sig": false,
"md5_digest": "ef215570b9c4fac9ecb794dbb1b97199",
"packagetype": "sdist",
"python_version": "source",
"requires_python": "<4.0,>=3.11",
"size": 42565,
"upload_time": "2024-11-03T18:21:19",
"upload_time_iso_8601": "2024-11-03T18:21:19.028047Z",
"url": "https://files.pythonhosted.org/packages/81/eb/84b295fcddae9af095baed76a1cc19a640a50303216a688dfa8a9487b947/pcx-0.6.2.post3.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2024-11-03 18:21:19",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "liukidar",
"github_project": "pcx",
"travis_ci": false,
"coveralls": false,
"github_actions": true,
"lcname": "pcx"
}
JSON
