Stack requirements:

There are some general LSST software stack requirements before installation: please check that your system has these pre-requisites installed.

There are some additional requirements for the simulations packages, mostly python dependencies that are so ubiquitous in scientific computing environments that it is more difficult for users for us to provide new versions than it is to supply them with the stack. These requirements are (there is some overlap here with the basic stack requirements):

 

The recommended install instructions will provide these dependencies for you through an Anaconda distribution.  

Installing from Source

The recommended (simplest) approach is to use the newest LSST software stack, and use the LSST-provided version miniconda python. (See here if you want to use your own python). 

1. Start by installing the necessary parts of the LSST software stack and the LSST-installed anaconda. 

In these instructions we assume you are installing in ~/lsst, however the install directory can be any place in the file system, including a place visible to all users.  To install in another location, replace ~/lsst with the desired path in the following instructions.  For multi user stacks, permissions are typically restricted to read only for the main stack so packages are not accidentally installed in the main stack.

For the basic install of lsst_apps, please follow the directions here: https://pipelines.lsst.io/install/newinstall.html  and then from there, install lsst_sims following the directions below.

 2. Set up the environment and install the simulations code and data.

Source the appropriate shell script and use eups (see here for more info) to install the software and data. 

source ~/lsst/loadLSST.csh 
eups distrib install lsst_sims -t sims

This will install all packages currently in the catalogs simulations framework (CatSim) and metrics analysis framework and all dependencies.  The installation should take on the order of 2 hours, with a final required installation size of 10GB. 

Currently the complete list of installed packages is:

Any of the above packages and all their dependencies can be installed by replacing lsst_sims with the appropriate package name in the above code snippet (e.g. sims_maf).  Installation is now complete.  See package specific pages for documentation.

4. Setup installed packages

You have now downloaded and built all of the packages in lsst_sims.  These packages are designed to be totally self-contained.  They have been built in the directories

$LSST_HOME/yourOperatingSystem/yourPackageName/

where yourOperatingSystem is 'DarwinX86' for Mac users and 'Linux64' for Linux users.  In order to use the packages you installed, you must add these directories to your $PYTHONPATH.  This is done using

setup your_package_name -t your_package_tag

setup is an eups command.  your_package_name is the name of one of the packages you have installed (e.g. sims_maf or sims_catUtils).  your_package_tag is a tag eups uses to keep track of the versions of each package you have built on your machine.  This corresponds to the argument of '-t' in the 'eups distrib install' command above.  So, if you wanted to setup the version of MAF you just downloaded, you would use

setup sims_maf -t sims

When you setup a package, eups inspects it and determines what other packages it depends on.  Eups will also setup those prerequisite packages, preferring versions tagged with the tag you specified and defaulting to versions with the tag 'current'.  If you do not want to default to 'current', you can specify more than one tag.

setup sims_maf -t $USER -t sims

will setup sims_maf and all of its dependencies, and then using versions matching the tags (resolved from left to right).  This system of eups tags allows you to have multiple versions of the stack built on your system simultaneously.  You will only ever be using the one that eups has setup.  To see which versions of a package exist on your system (and which has been setup) use

eups list -v your_package_name

or 

eups list -s


Known issues: 

Binary Installation (using conda)

WARNING: as of July 2016, the conda binary installation is no longer supported.  We strongly recommend that, if at all possible, you use the "install from source" instructions above.  Installing the conda binary will give you a very out-of-date LSST Simulations stack.  We are working on a new framework for distributing binary installations and will post to the sims-announce category at community.lsst.org when that is available.

These installation instructions are very similar to those on the https://pipelines.lsst.io/install/conda.html page, but note that we point to a different conda channel. 

1) Install the Anaconda Scientific Python Distribution (or the stripped-down Miniconda, for a quicker install).  

1a) If you didn't just install anaconda or miniconda, or even if you did:

conda update conda

2) Add the LSST simulations software channel (note that this is DIFFERENT than the standard 'DM stack' channel! This is because of versioning issues between DM and Sims and is related to simulations having a more frequent release schedule. You can also get an older version of sims from the 'stack' channel). 

Current version of simulations from the sims conda channel is: sims_2.2.6, built against DM lsst_apps v12.0. The version of sims available on the stack channel is v12.0 (equivalent to sims_2.2.5), built against DM lsst_apps v12.0. 

conda config --add channels http://conda.lsst.codes/sims

Note: if you have installed sims conda binaries in the past, you may have an 'eupsforge.net' channel in your ~/.condarc file. This channel no longer exists and should be removed from your ~/.condarc file. 


3) Install the desired sims and apps packages

conda install lsst-apps
conda install lsst-sims

or just a single package .. (e.g. for just MAF)

conda install lsst-sims-maf


Then, every time you open a new shell, you can setup the sims packages using the following code. Note that the file `eups-setups.sh` is in `$ROOT/bin` where `$ROOT` is the conda environment that you installed into or if you did not specifically setup an environment (following the above method) it points to the conda installation. However, the location of the file does not matter, as the `ROOT/bin` directory should be in your path if you are using conda, and then you can launch the following commands from any working directory.


source eups-setups.sh
setup lsst_sims (or setup sims_maf)

to later update use

conda update lsst-sims

Mixing Installed Stack with Development Repositories

If you are going beyond simply using software packages provided by LSST and need a direct git clone of a particular repository (because you wish to contribute development work directly back into repository or because a new feature is available but has not been released officially yet), you can mix an installed stack with development repositories. For pure python packages, this is straightforward.  The following steps will put a local copy of the sims_maf git repository into a pre-existing stack.   **Note you do not have to do this just to install and use any sims package, such as MAF.

All packages may be declared with a version and a tag.  The version distinguishes on instance of a particular package from another.  The eups tag can be used to define a coherent set of packages.  The philosophy is to tag all personal package (packages downloaded via git) with a custom tag using the username.  Using this workflow allows packages to be set up with the -t $USER switch which means that custom packages are used if they are declared and main stack packages are used otherwise.

1. Move to a directory to hold the working repository and clone it:

mkdir ~/lsstRepos; cd ~/lsstRepos
# if you are using ssh
git clone git@github.com:lsst/sims_maf.git
# or if you are using https
git clone https://github.com/lsst/sims_maf.git 

Note that you will need a password on the stash server (or have set up ssh keys) to push to the server.

2. Declare and build the package:

cd sims_maf
eups declare -r . -t $USER
setup sims_maf -t $USER
scons


You can check running the following that your dev version is being used by the following method.

> eups list sims_maf
...
tag: username  username setup


See here for the confluence question dealing with how to be polite in a shared stack.  

Note that when you are trying to simply use your git cloned version of the package, rather than install it, you simply need to 'setup sims_maf -t $USER'. 

3. Code, commit and push

Code reviews should be handled by branching the repository and issuing a pull request through stash.