Installing PsyNet via virtualenv (Windows)¶
Installing PsyNet on a Windows machine depends on the “Windows Subsystem for Linux” (WSL). All code you run using your the installation needs to be run within the Linux subsystem.
Step 0: Install WSL¶
Here is a simple tutorial for installing WSL 2 and Ubuntu on Windows: https://ubuntu.com/tutorials/install-ubuntu-on-wsl2-on-windows-11-with-gui-support#1-overview. Note: it is WSL 2 we want, not just WSL. Bear this in mind when looking for online tutorials.
WSL is a platform for installing particular Linux operating systems. In addition to installing WSL, the above tutorial also installs Ubuntu, which is a particular flavor of the Linux operating system. This is important for getting Docker to work.
Once you’ve installed Ubuntu, it’s important that you select it as the default distro within WSL. You can list available distros within WSL by running the following command in your terminal:
wsl -l --all
You want to set your default to the Ubuntu option. That probably means writing something like this:
wsl --setdefault Ubuntu
Note: If you see a message beginning “Hardware assisted virtualization and data execution protection must be enabled in the BIOS”, you need to restart your computer into BIOS and change some settings to enable those two things. The precise set of steps will depend on your computer. The first step though is to restart your computer, and press a certain key to launch into BIOS – ordinarily that key will be printed on the screen at some point during the startup sequence. Hint – you might find that the option you need to select is called ‘SVM mode’….
Once you’ve installed WSL, you probably will need to restart your computer before continuing. Then open your Ubuntu terminal and follow the below instructions:
Step 1: Perform Linux installation¶
The following installation instructions are tested with Ubuntu 22.04 LTS (Jammy Jellyfish). They address both experiment authors as well as developers who want to work on PsyNet’s source code.
One-time setup¶
The following steps need to performed each time you setup a new computer to run PsyNet experiments.
Check Linux version¶
The following installation instructions are tested with Ubuntu 20.04 LTS (Focal Fossa). You may wish to check that you have an up-to-date version of Linux before proceeding.
Update and install required system packages¶
sudo apt update
sudo apt upgrade
sudo apt install vim python3.11-dev python3.11-venv python3-pip redis-server git libenchant-2-2 postgresql postgresql-contrib libpq-dev unzip
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.
The easiest way to do this is via the apt install command above, for example
sudo apt install python3.11-dev for Python 3.11.
Install Docker and Docker plugins¶
sudo apt install ca-certificates curl gnupg
sudo install -m 0755 -d /etc/apt/keyrings
curl -fsSL https://download.docker.com/linux/ubuntu/gpg | sudo gpg --dearmor -o /etc/apt/keyrings/docker.gpg
sudo chmod a+r /etc/apt/keyrings/docker.gpg
echo \
"deb [arch="$(dpkg --print-architecture)" signed-by=/etc/apt/keyrings/docker.gpg] https://download.docker.com/linux/ubuntu \
"$(. /etc/os-release && echo "$VERSION_CODENAME")" stable" | \
sudo tee /etc/apt/sources.list.d/docker.list > /dev/null
sudo apt update
sudo apt install docker.io docker-compose-plugin docker-buildx-plugin
Install Google Chrome¶
wget -q -O - https://dl.google.com/linux/linux_signing_key.pub | sudo apt-key add -
sudo sh -c 'echo "deb [arch=amd64] http://dl.google.com/linux/chrome/deb/ stable main" >> /etc/apt/sources.list.d/google-chrome.list'
sudo apt update
sudo apt install google-chrome-stable
Setup PostgreSQL¶
sudo service postgresql start
sudo -u postgres -i
createuser -P dallinger --createdb
Password: dallinger
createdb -O dallinger dallinger
createdb -O dallinger dallinger-import
exit
sudo service postgresql reload
Install heroku client¶
curl https://cli-assets.heroku.com/install-ubuntu.sh | sh
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.
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
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.
Troubleshooting¶
WSL 2 installation is incomplete¶
If you see a message beginning with “WSL 2 installation is incomplete”, you probably need to do the following:
Click on the link it gives you
Click on the link under ‘download the latest package’, open and run the installer once it has downloaded
Continue with the next steps of the installation
Note: if you run Powershell, it might fail if you run it on admin mode! If you get stuck (Access Denied), try running it again without admin mode and see if it works.
Hardware assisted virtualization¶
If you see a message beginning “Hardware assisted virtualization and data execution protection must be enabled in the BIOS”, you need to restart your computer into BIOS and change some settings to enable those two things. The precise set of steps will depend on your computer. The first step though is to restart your computer, and press a certain key to launch into BIOS – ordinarily that key will be printed on the screen at some point during the startup sequence. Hint – you might find that the option you need to select is called ‘SVM mode’…