Installation

PCDS uses Conda to manage Python packaging. This allows users to quickly assemble virtual environments with different combinations of packages. An elementary understanding of what Conda is, and how to use it is assumed in the tutorial below. If you need a refresher, here is a good place to start.

Using an Existing Environment

A Conda deployment is maintained in /reg/g/pcds/pyps/conda with different versions of the pcds environment. Activate the latest one by:

$ source /reg/g/pcds/pyps/conda/py36env.sh

If you want an older release, set the PCDS_CONDA_VER environment variable:

$ export PCDS_CONDA_VER=2.1.0

The environment contained is read-only. You should not try to add packages to these environments. If you believe that a package should be included that is not present, contact PCDS or post an issue here and we will include it a subsequent release.

Note

Do not create your own environments here. See Creating Your Own Environment if you want to try different packages

Using In-Development Packages

It is possible to develop new packages without creating your own environment. This is useful if you made changes to one or multiple libraries and want to test how they interact with each other and with the rest of the released environment. The recommended way to do this is to use $PYTHONPATH to mask the shared packages with your in-development packages.

Tools are provided in our Engineering Tools repo to keep this process manageable. You can stay up-to-date with the most recent tools releases by keeping /reg/g/pcds/engineering_tools/engineering_tools/scripts in your path, or by cloning the Github repository. You can also use these scripts as a starting point for your own. The relevant scripts are:

  • pydev_env: Source this to activate your development environment.

  • pydev_register <path> <module or bin>: Use this to set up your development environment.

These scripts work by:

  1. Activating the shared environment

  2. Prepending $PYTHONPATH with ~/pydev

  3. Prepending $PATH with ~/pydev/bin

  4. Filling ~/pydev and ~/pydev/bin with softlinks to your checked-out packages and scripts

See Development for instructions on checking out and modifying packages. See below for examples on using these scripts.

Note

You can use this in a hutch-python instance too! Just add source pydev_env to the end of the hutchnameversion file. Warning: Do not check this in or include it in a release, or else each user may have slightly different startup behavior…

# Local repository checkouts
$ ls
happi hutch-python pcdsdevices special_package

# Add the modules to our PYTHONPATH
$ pydev_register happi/happi module
$ pydev_register hutch-python/hutch_python module
$ pydev_register pcdsdevices/pcdsdevices module
$ pydev_register special_package/special_package module

# The module softlinks are created here
$ ls ~/pydev
bin happi hutch_python pcdsdevices special_package

# Add the hutch-python script to our PATH
$ pydev_register hutch-python/bin/hutch-python bin

# The bin softlinks are created here
$ ls ~/pydev/bin
hutch-python

# Activate our environment
$ source pydev_env
$ ipython

In [1]: import special_package

In [2]: import pcdsdaq

In [3]: import pcdsdevices

In [4]: pcdsdaq.__file__
Out[4]: '/reg/g/pcds/pyps/conda/py36/envs/pcds-1.0.0/lib/python3.6/site-packages/pcdsdaq/__init__.py'

In [5]: pcdsdevices.__file__
Out[5]: '/reg/neh/home/username/pydev/pcdsdevices/__init__.py'

# Some time later: our PRs are done, clear our development path
$ rm ~/pydev/*
$ rm ~/pydev/bin/*

Creating Your Own Environment

Many developers may want to create their own environments to experiment with different packages and tools. We recommend that you do this in your own Miniconda installation. From a machine with internet access:

$ wget https://repo.continuum.io/miniconda/Miniconda3-latest-Linux-x86_64.sh -O miniconda.sh;

$ bash miniconda.sh -b -p ~/miniconda

This will give you a clean installation of Conda for you to play around with. Feel free to create and name environments as you please. You can make conda ready to use by sourcing the following scripts. You may want to include this in your .bashrc or startup file equivalent:

$ source ~/miniconda/etc/profile.d/conda.sh

or, for tcsh:

$ source ~/miniconda/etc/profile.d/conda.csh

If you want to create a copy of the latest PCDS deployment environment the easiest way is to use the .yaml specification that we keep with the main Conda deployment.

$ conda env create -n myenvname -f /reg/g/pcds/pyps/conda/pcds-envs/envs/pcds/env.yaml

This will create an environment myenvname that is an exact copy of the deployed release environment in your own Conda installation.

You can activate or deactivate an environment with the following commands:

$ conda activate myenvname
$ conda deactivate