example/Demo_make_simlibs.ipynb

{
 "cells": [
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "# Demonstrate the use of `make_simlibs.py`\n",
    "\n",
    "The script `make_simlibs.py` is used to make Simlib files from OpSim DataBases. [Go to script.](https://github.com/LSSTDESC/OpSimSummary/blob/master/scripts/make_simlibs.py)\n",
    "\n",
    "The following commands can be run from the terminal or from a notebook.\n",
    "\n",
    "## Index<a name=\"index\"></a>\n",
    "1. [Options](#options)\n",
    "2. [Example of usage](#usage)\n",
    "    1. [Download the desired file](#download)\n",
    "    2. [Set up options](#chooseOptions)\n",
    "    3. [Run the script](#run)\n",
    "    4. [Output](#output)\n",
    "\n",
    "## Options<a name=\"options\"></a>\n",
    "\n",
    "First, we can look at all the options."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "!python ../scripts/make_simlibs.py -h"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## Example of usage<a name=\"usage\"></a>\n",
    "\n",
    "Consider the case where you want to transform a OpSim DataBases file extracted from to a Simlib file.\n",
    "\n",
    "### 1. Download the desired file<a name=\"download\"></a>\n",
    "\n",
    "In this example, we will download the `baseline_v2.0_10yrs.db` file from [here](https://epyc.astro.washington.edu/~lynnej/opsim_downloads/) via the use of the nix Command Line `curl` tool. After downloaded, I will move it to the Downloads folder in order to showcase some more options of `make_simlibs`.\n",
    "\n",
    "```shell\n",
    "curl -O https://epyc.astro.washington.edu/~lynnej/opsim_downloads/fbs_2.0/baseline/baseline_v2.0_10yrs.db\n",
    "\n",
    "mv baseline_v2.0_10yrs.db ${HOME}/Downloads/\n",
    "\n",
    "# The database file is now in ${HOME}/Downloads/baseline_v2.0_10yrs.db\n",
    "```\n",
    "\n",
    "### 2. Set up options<a name=\"chooseOptions\"></a>\n",
    "\n",
    "- `data_root` $\\rightarrow$ path to the directory containing `dbname`. In this case the package is in `${HOME}`.\n",
    "- `dbname` $\\rightarrow$ relative path to the OpSim DataBase file from `data_root`. In this case it is `Downloads/baseline_v2.0_10yrs.db`. (This could have also been done as `data_root`  $\\rightarrow$   `${HOME}/Downloads` and `dbname` $\\rightarrow$ `baseline_v2.0_10yrs.db` as used below.)\n",
    "\n",
    "- `opsimversion` $\\rightarrow$ version of opsim used. Here we used `fbsv2`.\n",
    "\n",
    "If no `ddf_simlibfilename` and `wfd_simlibfilename` paths are given, the generated files will be output in the current working directory given by `PWD`.\n",
    "\n",
    "### 3. Run the script<a name=\"run\"></a>\n",
    "\n",
    "Go to the folder with the `make_simlibs` script. In this case, the script is in:\n",
    "\n",
    "```shell\n",
    "cd ~/OpSimSummary/scripts\n",
    "```\n",
    "\n",
    "We can then run the script\n",
    "\n",
    "```shell\n",
    "make_simlibs.py --dbname baseline_v2.0_10yrs.db --data_root /Users/user_name/Downloads --opsimversion fbsv2\n",
    "```\n",
    "\n",
    "All the above following commands can be run from the terminal but they can also be run from a notebook by adding `!` before the command. Ex:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "!pwd"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "#### Alternatives\n",
    "\n",
    "The `make_simlibs` script prints several messages while running, and can take some time to run. Hence, it is often convenient to run in the background, and store the output in a log file. Naming the log file `simlib_v2.0.log`, the command to run the script then becames:\n",
    "\n",
    "```shell\n",
    "python make_simlibs.py --dbname baseline_v2.0_10yrs.db --data_root /Users/user_name/Downloads --opsimversion fbsv2 > simlib_v2.0.log 2>&1 &\n",
    "```\n",
    "\n",
    "If you want to leave this running on a remote machine\n",
    "\n",
    "```shell\n",
    "nice nohup python make_simlibs.py --dbname baseline_v2.0_10yrs.db --data_root /Users/user_name/Downloads --opsimversion fbsv2 > simlib_v2.0.log 2>&1 &\n",
    "```\n",
    "should do the job.\n",
    "\n",
    "\n",
    "### 4. Output<a name=\"output\"></a>\n",
    "\n",
    "Using the above command, the output files will be in the `~/OpSimSummary/scripts` folder.\n",
    "\n",
    "The files generated are:\n",
    "- `baseline_v2.0_10yrs_DDF.simlib`\n",
    "- `baseline_v2.0_10yrs_DDF_avail.csv`\n",
    "- `baseline_v2.0_10yrs_DDF_sel.csv`\n",
    "- `baseline_v2.0_10yrs_WFD.simlib`\n",
    "- `baseline_v2.0_10yrs_WFD_avail.csv`\n",
    "- `baseline_v2.0_10yrs_WFD_sel.csv`\n",
    "- `testingDDF`\n",
    "- `simlib_v2.0.log`\n",
    "- `testingWFD`\n",
    "\n",
    "\n",
    "The files ending in `simlib` are the files that can be used as input to `SNANA`. If appropriate for the use, one can further using the `simlib_coadd` script of `SNANA`, which can coadd observations over time intervals to produce more compact simlib files that help `SNANA` generate faster simulations.\n",
    "\n",
    "`avail.csv` files list the spatial parts of the sky (in terms of healpixels) that are part of the survey (WFD or DDF). \n",
    "`sel.csv` is a selection of those healpixels, at which the pointings are used for calculating the SNANA observing library.\n",
    "\n",
    "Go to [Index](#index)."
   ]
  }
 ],
 "metadata": {
  "kernelspec": {
   "display_name": "Python 3",
   "language": "python",
   "name": "python3"
  },
  "language_info": {
   "codemirror_mode": {
    "name": "ipython",
    "version": 3
   },
   "file_extension": ".py",
   "mimetype": "text/x-python",
   "name": "python",
   "nbconvert_exporter": "python",
   "pygments_lexer": "ipython3",
   "version": "3.7.7"
  }
 },
 "nbformat": 4,
 "nbformat_minor": 4
}