Welcome to OpSimSummary’s documentation!

Overview

OpSimSummary was developed to interact with outputs of the LSST Operations Simulator for the purposes of transient and variable (mostly supernova cosmology) studies. Examples of such outputs are downloadable from the opsim webpage formatted as sqlite databases with fixed schema.

The key functionality of OpSimSummary is to find the set of LSST visits in an OpSim database that will observe a given location of the sky. This set of visits and the properties of these visits (also obtained from OpSim databases) is a useful piece of information for the simulations of observations of Time Domain Astronomy Sources (TDAS). The functionality is available in two ways:

  1. As a library: OpSimSummary can used as a library by a simulation program. In this case, the simulator can use OpSimSummary to obtain the set of visits and their properties in the form of a pandas.DataFrame using a generator. The basic code snippet to be used is demonstrated in the code block below, and a usable example is in the this demo notebook
from opsimsummary import SynOpSim

synopsim = SynOpSim.fromOpSimDB(myopsimv3,
                                opsimversion='lsstv3',
                                usePointingTree=True)

# If we want to obtain visits which observe two transients : ta at  (54., -27.5)
# and tb at (52., -23.0)
gen = synopsim.pointingsEnclosing(ra=(54.0, 52.),
                                  dec=(-27.5, -23.0),
                                  circRadius=0.,
                                  pointingRadius=1.75,
                                  usePointingTree=True)

df_ta = next(gen)
df_tb = next(gen)
# df_ta is a `pandas.dataFrame` with all of the opsim columns for the visits
# observing transient t_a (assumed to be fixed at (54., -27.5) with the
# observationId or obsHistId of the visit as the index of the data frame
  1. Pre-computed files: Alternatively, such sets and visit properties (or derived products) may be obtained written out to a text file for a set of discrete (but possibly large number of locations). Currently, we do this to provide an observation library (formerly called simlib) for SNANA to enable SNANA simulations of LSST. To use this, one could (after installing OpSimSummary) use a script to make the simlib files. The options for the script can be found by using the following code block.
$python scripts/make_simlibs.py -h

A further description of the main building blocks of this code are found in the codestructure.

Installation

The engine of OpSimSummary depends on commonly used python packages. Currently, all of the requirements can be installed with anaconda and pip. To use OpSimSummary as a library or the scripts in OpSimSummary, you will need the requirements listed here .

Installing Dependencies

There are scripts in the ./install directory which can be used to install the dependencies. To use these, you must have a conda python installation. If you don’t have a such a python installation, you can use a script to install a miniconda distribution.

using the code ` bash install_python.sh path_to_desired_python_location ` where path_to_desired_python_location must be a directory that exists.

To install the dependenencies and OpSimSummary, from the root level of the package:

$bash ./install/install_all.sh

installs the dependencies and OpSimSummary.

To just install OpSimSummary if you already have taken care of the requirements, use :

$bash install/install_opsimsummary

To install other dependencies that are useful (for example for notebooks, and utlities for plotting) use:

$conda install jupyter seaborn

Operation Simulator Outputs

OpSimSummary can be used with Operation Simulator Outputs for OpSim version 3, and 4 as well as a set of OpSim outputs released for the work of the DESC Survey Strategy Task Force. The outputs of these versions are different, and as of now, OpSimSummary requires an input to know which of these versions are being used.

The main class of OpSimSummary are required to read in OpSim outputs is OpSimOutputs. Note that the class SynOpSim also uses OpSimOutputs to read in OpSim databases. OpSimOutput can be instantiated using a summary table and proposalTable table read in from any source. The summary table has a set of unique pointings of the telescope with observational characteristics of each of the pointings (such as found in the OpSim summary or summaryAllProps tables). The ProposalTable Table has a list of different proposals with an identifying integer index and descriptive names.

opsimout = OpSimOutput(summary=summary, proposalTable=proposalTable,
                       zeroDDFDithers=False)

It is, however, far easier and strongly recommended to use this directly using a class method and an absolute path to the OpSim database dbname. The following is the example code for lsstv3 (for example minion_1016_sqlite.db. The choices for opsimversion and tableNames for the names of the summary and proposal table in OpSim v3 are important:

$opsout = OpSimOutput.fromOpSimDB(dbname, subset='combined',
                                  tableNames=('Summary', 'Proposal'),
                                  propIDs=None, zeroDDFDithers=True,
                                  opsimversion='lsstv3')

For the set of outputs for OpSim versions used by the DESC Survey Strategy Task Force: these variables are :

$opsout = OpSimOutput.fromOpSimDB(dbname, subset='combined',
                                  tableNames=('summaryAllProps', 'Proposal'),
                                  propIDs=None, zeroDDFDithers=True,
                                  opsimversion='sstf')