Installation

The recommended installation workflow for the MoaceanParcels package is:

Clone the code and documentation repository from GitHub
Create a conda environment
Activate the environment and install the package using the “editable” install mode.

Details

Getting the Code

Clone the code and documentation repository from GitHub with:

$ git clone git@github.com:UBC-MOAD/MoaceanParcels.git

or copy the URI (the stuff after git clone above) from the Code button on the repository page.

Note

The git clone command above assumes that your are connecting to GitHub using SSH. If it fails, please follow the instructions in our Secure Remote Access docs to set up your SSH keys and Copy Your Public ssh Key to GitHub.

Create a conda Environment

Setting up an isolated development environment using Conda for each of your coding projects is recommended. Assuming that you have Miniconda3 installed, you can create an environment called moacean-parcels that will have all of the Python packages necessary for development, testing, and building the documentation for the package with the commands below.

$ cd MoaceanParcels
$ conda env create -f envs/environment-dev.yaml

Alternatively, you can use envs/environment-dev.yaml as a guide for creating your own environment description file. All of the dependencies above the

# For code style & repo QA

line are required to use MoaceanParcels with OceanParcels. Put them and any other packages you want in your environment file.

The dependencies below that line are required for various parts of MoaceanParcels Package Development. You will need them if you are adding new kernel functions and particle classes to MoaceanParcels, but not if you just want to use the stuff that is already in the package.

If you decide that you need to add a package to your environment, add it to the dependencies: section of your environment file, then do:

$ conda env update -f envs/environment-dev.yaml

to update your environment.

Activate Environment and Install the Package

Activate your environment:

$ cd MoaceanParcels
$ conda activate moacean-parcels

Here we assume the environment is named moacean-parcels. You should substitute whatever name you used for your environment.

In the mocean-parcels environment MoaceanParcels is installed in editable install mode as part of the conda environment creation process. That means that the package is installed in a way that it can be updated when new features are pushed to GitHub by simply doing a git pull in the MoaceanParcels directory.

If you are using an environment that you created, activate your environment, then install the MoaceanParcels package with:

$ cd MoaceanParcels
$ conda activate my-environment
(my-environment)$ python3 -m pip install --editable .

To deactivate the environment use:

(moacean-parcels)$ conda deactivate