Installing PsyNet via virtualenv (macOS)¶

One-time setup¶

The following steps need to performed each time you setup a new computer to run PsyNet experiments.

Check MacOS version¶

We recommend that you update MacOS to the latest version before proceeding.

Install Python¶

PsyNet requires a recent version of Python 3. To check the minimum and recommended versions of Python, look at PsyNet’s pyproject.toml file, specifically at the line beginning with requires-python. To see the current version of Python 3 on your system, enter python3 --version in your terminal. If your current version is lower than the minimum version, you should update your Python to the recommended version. We recommend doing this by going to the Python website, and downloading the installer corresponding to the latest patch of the recommended version. If the recommended version is 3.11, this means searching for Python version 3.11.x where ‘x’ is as high as possible. At the time of writing this installer can be found by looking under the section ‘Looking for a specific release?’, clicking the desired Python version, then clicking ‘macOS 64-bit universal2 installer’.

One installation is complete, try python3 --version again to ensure that the correct version is found. To install old versions you might need to run brew uninstall python3, or go to the Applications folder and delete the appropriate version of Python.

Install Homebrew¶

/bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)"

Install Google Chrome¶

brew install --cask google-chrome

Install and setup PostgreSQL¶

brew install postgresql@14
brew services start postgresql@14
createuser -P dallinger --createdb

When prompted, enter the follwing password: dallinger

createdb -O dallinger dallinger
createdb -O dallinger dallinger-import

brew services restart postgresql@14

Install libpq¶

brew install libpq

In the ensuing text, you should see something like this:

For compilers to find libpq you may need to set:
  export LDFLAGS="-L/usr/local/opt/libpq/lib"
  export CPPFLAGS="-I/usr/local/opt/libpq/include"

Execute the following:

touch ~/.zshrc
open ~/.zshrc

Then paste those two lines beginning with “export” at the bottom of the file (as new lines).

Warning

If you skip this step you might see error messages like “symbol not found in flat namespace ‘_PQbackendPID’” once you try and run PsyNet.

Install Heroku¶

brew install heroku/brew/heroku

Install Redis¶

brew install redis
brew services start redis

Setup Git¶

If you don’t have Git already, install it with the following commands, inserting your name and email address as appropriate.

brew install git
git config --global user.email "you@example.com"
git config --global user.name "Your Name"

Installing virtualenv¶

You need to use virtual environments to work with PsyNet. This can be confusing if you haven’t used Python virtual environments before. We strongly recommend you take half an hour at this point to read some online tutorials about virtual environments and managing them with virtualenvwrapper before continuing.

The following code installs virtualenvwrapper:

pip3 install virtualenv
pip3 install virtualenvwrapper
export WORKON_HOME=$HOME/.virtualenvs
mkdir -p $WORKON_HOME
export VIRTUALENVWRAPPER_PYTHON=$(which python3)
source $(which virtualenvwrapper.sh)
echo "export VIRTUALENVWRAPPER_PYTHON=$(which python3)" >> ~/.zshrc  # If you are on Linux, you may need to replace ~/.zshrc with ~/.bashrc
echo "source $(which virtualenvwrapper.sh)" >> ~/.zshrc  # If you are on Linux, you may need to replace ~/.zshrc with ~/.bashrc

Download the PsyNet repository¶

We recommend downloading the PsyNet repository so that you can access its collection of built-in demos and explore the source code. However, you do not need to download it for running your own experiments.

We recommend downloading PsyNet to your home directory if possible, there are some PsyNet features that run smoother if it is located there.

cd
git clone https://gitlab.com/PsyNetDev/PsyNet

You can then find the PsyNet demos within the demos directory.

By default this will download the latest version of PsyNet’s master branch, but new versions are released regularly. To get the latest version, run the following:

cd ~/PsyNet
git pull

If you want to ensure that this version of PsyNet is exactly the same as the one that your experiment will use, you can check out a specific version of PsyNet like this:

cd ~/PsyNet
git checkout v10.4.0

where 10.4.0 matches the PsyNet version number specified in the experiment’s requirements.txt file.

Disable AirPlay¶

macOS’s ‘AirPlay Receiver’ functionality clashes with the default ports used by Dallinger and PsyNet. You should disable this functionality before proceeding. To achieve this, go to System Preferences, then Sharing, and then untick the box labeled ‘Airplay Receiver’.

If you are interested in contributing to PsyNet, you should also complete the Additional developer installation steps.

Setting up a new project¶

The following steps need to be performed each time you start a new project.

The first step is to identify which project you want to set up. A PsyNet project is identified with an ‘experiment directory’, which is a folder containing various standardized files defining an experiment implementation, most importantly an experiment.py file and a requirements.txt file. If you are exploring PsyNet for the first time, we recommend that you start with one of the demo experiments, which can be found in the demos folder of the PsyNet repository. Alternatively, you can download one of the example experiments listed on the PsyNet website. If you are planning to create your own experiment, you can start by copying one of the demo experiments to a new directory and modifying it as appropriate.

To open a project in PyCharm (e.g. a demo), click ‘Open’ in the PyCharm welcome screen, then navigate to the directory containing the project, select the project, and click ‘Open’. Alternatively, if you already have a PyCharm project open, click ‘File’ > ‘Open’, find the directory, select it, and click ‘Open’.

When you open a new project in PyCharm, you should see a dialogue box that says something like “File requirements.txt contains project dependencies. Would you like to create a virtual environment using it?”. In the dependencies field you should see a path ending in requirements.txt. Replace “requirements.txt” with “constraints.txt” and then click “OK”. PyCharm will then create a virtual environment for you and install all the required packages.

Note

This workflow uses virtualenv to create an isolated virtual environment for each project. PyCharm remembers which virtual environment to use for each project, and will load it automatically when you open the project.

Note

If you are not using PyCharm, you can install the required packages using the following command:

pip install -r constraints.txt

Note

Why do we install from constraints.txt rather than requirements.txt? requirements.txt is written manually by the experimenter, and lists all the packages that they want to use in their experiment. constraints.txt is then automatically generated by PsyNet, and additionally lists all the dependencies of the packages in requirements.txt. Importantly, PsyNet ensures that the versions of the packages in constraints.txt are compatible with the current version of PsyNet. Moreover, listing these versions explicitly in constraints.txt means that when future experimenters come to run the experiment, they will be able to install exactly the same versions of the packages that we originally used.

If you do not see this PyCharm dialogue box, you can instead create the virtual environment by clicking the interpreter box in the bottom right corner of the screen (it might say something like ‘No interpreter selected’ or ‘Python 3.X’), then clicking ‘Add new interpreter’ > ‘Add local interpreter’. Select ‘Virtualenv environment’, select ‘New’, make sure that the correct version of Python is selected, then press OK. PyCharm will spend some time processing this selection, but then when you open a new terminal tab it should load your virtual environment automatically.

If you are working as a PsyNet developer, now is the moment to install PsyNet and Dallinger in development mode. To do this, run the following commands (assuming you have installed PsyNet and Dallinger in the default locations):

pip install -e ~/PsyNet
pip install -e ~/Dallinger

Whenever you develop or deploy an experiment using PsyNet (assuming you are not using Docker) you will need to make sure you are in the appropriate virtual environment. You can confirm that you are in the correct virtual environment by looking at the start of your terminal prompt. It should look something like this: (my-project) your-name@your-computer-name ~ %. If you have only just created your new virtual environment in PyCharm, you might need to open a new terminal window for your virtual environment to be loaded. Your virtual environment should activate automatically when you open your project in PyCharm; if it does not, you can select it by clicking the interpreter box in the bottom right corner of the screen.

Once PyCharm has finished installing the required packages, you should be able to run the experiment with the following command:

psynet debug local

Note

If you are not using PyCharm, you can create a virtual environment using the following command:

mkvirtualenv my-project --python $(which python3.12)

where in this case my-project is the name of the virtual environment.

You can activate your virtual environment by running the following command:

workon my-project

You can then delete your virtual environment by running the following command:

rmvirtualenv my-project

Note

If you experience problems setting up the virtual environment:

Check in which directory virtualenvwrapper.sh is installed. This might be a different directory than ‘~/.local/bin/’. In that case, adapt the code above to source this file accordingly.
Check whether the directory where virtualenvwrapper.sh was installed is added to PATH. If not, add the directory to PATH.