Installation¶

Installing WiPPLPy as a Contributor¶

This installation is very similar to how PlasmaPy installation is done for contributors: https://docs.plasmapy.org/en/stable/contributing/getting_ready.html. We’ve done some copy-pasting as to which steps should be followed.

If you are stuck or don’t understand something, please ask for help or take a look at the PlasmaPy’s code contribution workflow.

Pre-requisites¶

Opening a terminal¶

The commands in this page are intended to be run in a Unix terminal. If you are new to Unix, check out this Unix tutorial and these frequently used Unix commands.

Windows¶

There are several options for terminals on Windows.

Powershell comes pre-installed with Windows. These instructions cover opening Powershell. We recommend Powershell for a quick start, if Windows is the only operating system you use, or if you have not used Unix before.
We recommend Windows Subsystem for Linux (WSL) if you are familiar with Unix, you use macOS or Linux too, or you expect to contribute to WiPPLPy extensively. These instructions cover installing WSL. If you choose WSL, follow the tabs for Linux/WSL below.

macOS¶

In the Finder, go to Applications. Enter the Utilities folder and double click on Terminal.

Linux/WSL¶

Open a terminal by using Ctrl + Alt + T.

Installing Python¶

We suggest using Mamba to install Python. Mamba is a versatile package and environment management system which is widely used in the data science and scientific Python communities that is similar to Conda. It is a command line interface for installing packages.

If you already have Conda installed, then follow the installing Mamba from an existing Conda install.
Otherwise, follow the installing Mamba instructions.

Using git and GitHub¶

Code contributions to WiPPLPy are made using git and GitHub. Before contributing code to WiPPLPy, please take the following steps:

Sign up on GitHub for a free account.
Verify that git is installed by opening a terminal and running:
```
git --version
```
If there is an error, follow these instructions to install git.
Optionally, configure git with your name with a command like:
```
git config --global user.name "Your Name"
```
You can also configure git with your email with a command like:
```
git config --global user.email "your.email@example.com"
```
You may also set your default editor with a command like the following, where notepad can be replaced with the name or path of your preferred editor:
```
git config --global core.editor notepad
```
For different editor and configuration options, check out `git commands for setup and config`_.
Add a new SSH key to your GitHub account. This step is needed for authentication purposes.

Forking and cloning the repository¶

Log into GitHub.
Go to the WiPPLPy repository.
Create a fork of WiPPLPy by clocking on Fork, followed by Create Fork.
Open a terminal. Navigate to the folder where you want to clone the WiPPLPy repository. For example, to clone the repository into the ~/repos/ directory, run:
```
mkdir ~/repos
cd ~/repos
```
Clone the WiPPLPy repository with the following command, replacing YOUR-USERNAME with your GitHub username. This will create a subdirectory called WiPPLPy/ containing your local clone of the repository.
```
git clone git@github.com:YOUR-USERNAME/WiPPLPy.git
```
Tip

If you have trouble connecting to GitHub, you may need to add a new SSH key to your GitHub account.
Enter the newly created directory with:
```
cd WiPPLPy
```
Add a remote called upstream for the WiPPLPy’s repository by using the following command.
```
git remote add upstream git@github.com:kuchtact/WiPPLPy.git
```
If you run git remote -v, you should see that origin corresponds to your fork and upstream corresponds to the WiPPLPy repository.

Installing WiPPLPy from a Fork¶

Once Mamba is installed and you have cloned your fork of the git repository then we need to create an environment for running the code in.

Open a terminal.
Navigate to the directory for your clone of WiPPLPy, which should be named WiPPLPy. For example, if you ran the git clone command in the ~/repos/ directory, then run:
```
cd ~/repos/WiPPLPy
```
Note

In Windows, the directory path will be C:\Users\<username>\repos\WiPPLPy.
Create a Mamba environment using the packages from mamba_environment.yml. If you are on Windows, Linux, or macOS that doesn’t use the silicon processor you can do so by running:
```
mamba env create -f ./mamba_environment.yml
```
If you are on a computer that uses the Mac silicon processor you can do so by
```
CONDA_SUBDIR=osx-64 mamba env create -f ./mamba_environment.yml
```
This will create a new environment called WiPPLPy.
Activate the environment and start python by running:
```
mamba activate WiPPLPy
python
```

We need to add the WiPPLPy/source/ directory to the Python path. We can find the path to WiPPLPy/source/ and the site-packages directory by running the following Python code:

from distutils.sysconfig import get_python_lib

print("site-packaged directory:", get_python_lib())
import os

print("WiPPLPy source code directory:", os.getcwd())

Exit out of python and navigate to the site-packages directory that was printed. It should end in site-packages.
Create a file called wipplpy.pth. This file should contain the path to the WiPPLPy/src/ directory. For example, if the path to the WiPPLPy/src/ directory is /Users/username/repos/WiPPLPy/src/ then the wipplpy.pth file should contain the following:
```
/Users/username/repos/WiPPLPy/src/
```
Test that the installation was successful by running the following Python code:
```
from wipplpy.modules import shot_loader
```
If there are no errors then the installation was successful.

Installing WiscVPN for Remote Data Access¶

To access data remotely, you will need to have access to the UW-Madison Plasma Network. This can be done by installing WiscVPN and getting your static IP address added to the network.

Creating Documentation¶

To create the documentation, you will need to have nox installed. nox then installs Sphinx and creates the documentation when you run the following command:

nox -s docs

This will create the documentation in the docs/build/html/ directory. Open the documentation by double clicking on the index.html file in the docs/build/html/ directory.

Installing Pre-commit¶

Follow the instruction found here: https://docs.plasmapy.org/en/stable/contributing/pre-commit.html