Installation Instructions
Note
Pre-requisites:
To use imSim 2.0 at least versions
GalSim 2.4.11 and skyCatalogs v1.6.0rc2
are required. The instructions below for the cvmfs and stackvana installations should automatically fulfill these requirements for you. If you are using a different installation method, please ensure that you have met these requirements.
These instructions were last updated September of 2023. If you find that parts of this document are out of date or are incorrect, please submit a bug report here.
Warning
If you are using MacOS on an Apple Silicon machine then currently the only binary installation below that will work is to use the CVMFS distribution (method #1). Method #2 (stackvana) will not work. Method #3 (using docker), should work but will run through emulation and will not run at native speed. In the meantime, the best other option is to install the science pipelines yourself via the lsstinstall package as described in the pipelines documentation and then add the extra imSim conda dependencies as needed.
The imSim software is GalSim based, and it also depends on the LSST science pipelines and Rubin simulation framework. It is easiest to work in an environment where someone else has already built the science pipelines, simulation packages and GalSim for you. Luckily, several such options exist.
We list four options below in increasing levels of complexity. These options all use either a conda environment or a docker image.
Method 1: Using the cvmfs distribution
If you are working at the USDF (Rubin Project computing) or at NERSC (DESC computing), perhaps the easiest way to setup and use imSim is to rely on the prebuilt versions of the pipelines contained in the cvmfs distribution which is installed there. This solution is also appropriate for personal laptops and university/lab based computing systems if you are able to install the cvmfs system.
The CernVM file system (cvmfs) is a distributed read-only file system developed at CERN for reliable low-maintenance world-wide software distribution. LSST-France distributes weekly builds of the Rubin science pipelines for both Linux and MacOS. Details and installation instructions can be found at sw.lsst.eu . The distribution includes conda and imSim dependencies from conda-forge along with the science pipelines.
Load and setup the science pipelines
First you need to setup the science pipelines. This involves sourcing a setup file and then using the Rubin eups commands to set them up.
Note
You will need at least version w_2023_32
of the science pipelines to complete these instructions.
Also note: the cvmfs distribution is a read-only distribution. This means you cannot add packages to the included conda environment and packages you install via pip will be installed in the user area. If you need a conda environment you can modify while running imSim, then you may consider Method 2: Conda and the Stackvana package below.
Source the appropriate setup script (note the -ext in the name) and then setup the distribution (if you are on MacOS use darwin-x86_64 instead of linux-x86_64).
source /cvmfs/sw.lsst.eu/linux-x86_64/lsst_distrib/w_2023_21-dev/loadLSST-ext.bash
setup lsst_distrib
Install needed data files
Now go to where you would like to install imSim and download a set of data files that are used by the rubin-simulation framework (you will only need to do this once).
mkdir -p rubin_sim_data/sims_sed_library
curl https://s3df.slac.stanford.edu/groups/rubin/static/sim-data/rubin_sim_data/skybrightness_may_2021.tgz | tar -C rubin_sim_data -xz
curl https://s3df.slac.stanford.edu/groups/rubin/static/sim-data/rubin_sim_data/throughputs_2023_09_07.tgz | tar -C rubin_sim_data -xz
curl https://s3df.slac.stanford.edu/groups/rubin/static/sim-data/sed_library/seds_170124.tar.gz | tar -C rubin_sim_data/sims_sed_library -xz
Setup imSim itself
Next, clone copies of both the imSim and skyCatalog software packages from GitHub.
git clone https://github.com/LSSTDESC/imSim.git
git clone https://github.com/LSSTDESC/skyCatalogs
at this point if you would only like to use imSim you can pip install imSim/
and pip install skyCatalog/
however we instead suggest using the eups tool to simply setup the packages for use without installing them. This will allow you to edit the packages in place, use multiple versions, change branches etc. You should definitely do this if you plan to do any imSim development.
setup -k -r imSim
setup -k -r skyCatalogs
Setup and Run imSim
This setup step should be repeated for each new session. Here is an imsim-setup.sh
file you can use before each session (you should first source the cmvfs setup as above):
setup lsst_distrib
export IMSIM_HOME=*PUT YOUR INSTALL DIRECTORY HERE*
export RUBIN_SIM_DATA_DIR=$IMSIM_HOME/rubin_sim_data
export SIMS_SED_LIBRARY_DIR=$IMSIM_HOME/rubin_sim_data/sims_sed_library
setup -k -r $IMSIM_HOME/imSim
setup -k -r $IMSIM_HOME/skyCatalogs
Now you can run imSim from anywhere with the command:
galsim some_imsim_file.yaml
Method 2: Conda and the Stackvana package
If using the cvmfs distribution is not an appropriate solution, you can install a standalone pre-built conda distribution from conda-forge instead. With this method, you will install a version of lsst_distrib which has been compiled for conda along with extra needed dependencies.
Install Conda
First install conda from Miniforge. You need to download an installer and run the script.
curl -L -O "https://github.com/conda-forge/miniforge/releases/latest/download/Mambaforge-$(uname)-$(uname -m).sh"
bash Mambaforge-$(uname)-$(uname -m).sh
Note
If you prefer you can use MiniConda or your own conda installation but, in that case, be careful to specify that you want to use the conda-forge channel.
Next, create a Conda environment and activate it.
conda create -n imSim
conda activate imSim
Clone imSim and dependencies
Now we are ready to install imSim. First go to the directory where you would like to do the installation. If you are not using Miniforge, first conda install the mamba
package and then:
git clone https://github.com/LSSTDESC/imSim.git
git clone https://github.com/LSSTDESC/skyCatalogs
# conda dependencies:
mamba install -y --file imSim/etc/standalone_conda_requirements.txt
mamba install rubin-sim
# Install imSim:
pip install --no-deps imSim/
pip install --no-deps skyCatalogs/
Install rubin_sim_data
imSim makes use of some external datasets. Here we are putting them in a
directory called rubin_sim_data
, but the choice is yours. If you do change
the locations, make sure to update the RUBIN_SIM_DATA_DIR
and
SIMS_SED_LIBRARY_DIR
paths we set below.
To download:
mkdir -p rubin_sim_data/sims_sed_library
curl https://s3df.slac.stanford.edu/groups/rubin/static/sim-data/rubin_sim_data/skybrightness_may_2021.tgz | tar -C rubin_sim_data -xz
curl https://s3df.slac.stanford.edu/groups/rubin/static/sim-data/rubin_sim_data/throughputs_2023_09_07.tgz | tar -C rubin_sim_data -xz
curl https://s3df.slac.stanford.edu/groups/rubin/static/sim-data/sed_library/seds_170124.tar.gz | tar -C rubin_sim_data/sims_sed_library -xz
Set runtime environment variables for the Conda environment
conda env config vars set RUBIN_SIM_DATA_DIR=$(pwd)/rubin_sim_data
conda env config vars set SIMS_SED_LIBRARY_DIR=$(pwd)/rubin_sim_data/sims_sed_library
Run imSim
Now you can run imSim from anywhere with the command:
galsim some_imsim_file.yaml
Method 3: Using the pre-built imSim Docker image
Here we assume you have Docker installed.
The easiest method is to pull the latest imSim environment Docker image from DockerHub. This has the latest LSST stack and version of imSim preinstalled:
docker pull lsstdesc/imsim-env:latest
Running the Docker image
To then run the image do:
docker run -it --privileged --rm lsstdesc/imsim-env:latest
imSim is installed under /home/lsst
. The LSST
stack is activated automatically on the startup of the image.
Note
If you have trouble accessing the internet within the container, you
may have to add --network host
to the docker run
command.
Method 3: Building your own imSim Docker image
If the imSim Docker image doesn’t quite meet your needs, perhaps you need some additional software or dependencies, or you want to develop an imSim project that is stored locally on your machine actively within a container, then you can use the imSim Docker image as a starting point to build your own Docker image.
The imSim Dockerfile
The imSim Dockerfile
is located in the root directory of the imSim
repository, which you can use as a starting point:
1# Start from the latest release LSST stack image.
2FROM lsstsqre/centos:7-stack-lsst_distrib-w_latest
3
4# Information about image.
5ARG BUILD_DATE
6LABEL lsst-desc.imsim.maintainer="https://github.com/LSSTDESC/imSim"
7LABEL lsst-desc.imsim.description="A Docker image combining the LSST Science Pipelines software stack and imSim (and its dependencies)."
8LABEL lsst-desc.imsim.version="latest"
9LABEL lsst-desc.imsim.build_date=$BUILD_DATE
10
11WORKDIR /home/lsst
12
13# Clone imSim and rubin_sim repos.
14RUN git clone https://github.com/LSSTDESC/imSim.git &&\
15 git clone https://github.com/lsst/rubin_sim.git
16
17# Pull out conda requirements for imSim (excluding stackvana)
18RUN sed '/stackvana/d' imSim/etc/standalone_conda_requirements.txt > imSim/etc/docker_conda_requirements.txt
19
20# 1) Install imSim Conda requirements
21# 2) Install imSim pip requirements
22# 3) Install rubin_sim
23# 4) Install imSim
24RUN source /opt/lsst/software/stack/loadLSST.bash &&\
25 setup lsst_distrib &&\
26 mamba install -y --file imSim/etc/docker_conda_requirements.txt &&\
27 python3 -m pip install batoid skyCatalogs==1.6.0-rc2 gitpython &&\
28 python3 -m pip install rubin_sim/ &&\
29 python3 -m pip install imSim/
30
31WORKDIR /opt/lsst/software/stack
32
33# Download Rubin Sim data.
34RUN mkdir -p rubin_sim_data/sims_sed_library
35RUN curl https://s3df.slac.stanford.edu/groups/rubin/static/sim-data/rubin_sim_data/skybrightness_may_2021.tgz | tar -C rubin_sim_data -xz
36RUN curl https://s3df.slac.stanford.edu/groups/rubin/static/sim-data/rubin_sim_data/throughputs_aug_2021.tgz | tar -C rubin_sim_data -xz
37RUN curl https://s3df.slac.stanford.edu/groups/rubin/static/sim-data/sed_library/seds_170124.tar.gz | tar -C rubin_sim_data/sims_sed_library -xz
38
39# Set location of Rubin sim data (downloaded in step above).
40ENV RUBIN_SIM_DATA_DIR /opt/lsst/software/stack/rubin_sim_data
41
42# Set location of SED library (downloaded in step above).
43ENV SIMS_SED_LIBRARY_DIR /opt/lsst/software/stack/rubin_sim_data/sims_sed_library
44
45WORKDIR /home/lsst
46
47# Make a script to activate the LSST stack
48RUN echo "source /opt/lsst/software/stack/loadLSST.bash" >> .bashrc &&\
49 echo "setup lsst_distrib" >> .bashrc
It builds upon the prebuilt Docker images produced by the Rubin Data
Management team. Standard images are produced on a weekly basis and track the
on-going development of the LSST Stack. For
imsim-env:latest
we build upon the latest LSST stack image, however you can
change this to a specific build if you prefer.
We then install imSim and GalSim and their dependencies, and download the
rubin_sim_data
.
If you want to install additional Python dependencies on-top of the default
build, do it under the RUN
command on line 24.
If you are installing additional general software, this can be done at the start of the image.
Mounting a volume
You could for example use a Docker image as a clean environment to develop
imSim, but keep the active development files locally on your machine. To do
this, remove the imSim installation from the Dockerfile
. Then, when
running the container, mount your local imSim directory like so.
docker run -it --privileged --rm -v ${HOME}/imSim:/home/lsst/imSim lsstdesc/my-imsim-env:latest
The -v
option maps your home imSim directory on the host system to
/home/lsst/imSim
in the Docker container (which is the default working
directory).
Setting user and group ids
The prebuilt Rubin images set the default linux user and group both to lsst
with uid=1000
and gid=1000
. If the desired user and group on the host
system have the same ids, then the lsst
user and group in the Docker image
can be renamed with the following, replacing the line
WORKDIR /home/lsst
with
USER root
ARG user=<desired_username>
ARG group=<desired_group_name>
RUN /usr/sbin/groupmod -n ${group} lsst
RUN /usr/sbin/usermod -l ${user} lsst
USER ${user}
WORKDIR /home/${user}
Alternatively, if the lsst
user doesn’t conflict with the desired
user/group, the latter can be added to the image and set as the default user:
USER root
ARG user=<desired_username>
ARG group=<desired_group_name>
ARG uid=<desired_uid>
ARG gid=<desired_gid>
RUN /usr/sbin/groupadd -g ${gid} ${group}
RUN /usr/sbin/useradd -u ${uid} -g ${gid} ${user}
USER ${user}
WORKDIR /home/${user}
Building the Docker image
Assuming the above Dockerfile
is in the current directory, then the
following command will build the image
docker build -t <repository>:<tag> .
where <repository>
and <tag>
are chosen by the user.
The available images can be listed via
docker images
Testing your installation
If the installation has been done correctly you should now be able to go to a working area of your choosing and run the program.
imSim is run by executing the galsim executable with an imSim yaml file as input:
galsim $IMSIM_HOME/imSim/examples/imsim-user-instcat.yaml
The program should run to completion without errors.