LSST DESC Note: The Twinkles1 PhoSim Pipeline and Results

doc/LSST_DESC_Notes/desc-0000-twinkles-1-phosim-pipeline/.gitignore

@@ -0,0 +1,24 @@
+### Emacs
+\#*#
+\.#*
+*~
+
+### Latex
+*.fls
+*.aux
+*.log
+*.fdb_*
+*.out
+*.blg
+*.bbl
+*Notes.bib
+main.pdf
+main.tar.gz
+
+### other files produced during compilation
+authors.tex
+contributions.tex
+
+### cookiecutter files
+desc-0000-twinkles-1-phosim-pipeline.pdf
+desc-0000-twinkles-1-phosim-pipeline.tar.gz

doc/LSST_DESC_Notes/desc-0000-twinkles-1-phosim-pipeline/.metadata.json

@@ -0,0 +1,12 @@
+{
+    "author": "Tom Glanzman",
+    "affiliation": "SLAC",
+    "email": "[email protected]",
+    "title": "Twinkles 1 PhoSim Pipeline and Results",
+    "description": "We describe the implementation of the Twinkles 1 PhoSim pipeline, taking pre-made instance catalogs and processing them into e-images. The SLAC workflow engine `pipeline-II` is used to handle the processing, which was performed on the batch system at SLAC. XXX images were generated in a wallclcok time of XXX days, at an efficiency of XX%",
+    "repo_name": "Twinkles",
+    "serial_number": "0000",
+    "short_title": "1-phosim-pipeline",
+    "folder_name": "desc-0000-twinkles-1-phosim-pipeline",
+    "default_format": "rst"
+}

doc/LSST_DESC_Notes/desc-0000-twinkles-1-phosim-pipeline/.travis.yml

@@ -0,0 +1,31 @@
+# Install latex, and the various packages used by the start_paper Makefile:
+before_install:
+  - sudo apt-get -qq update
+  - sudo apt-get install -y gsl-bin libgsl0-dev
+  - sudo apt-get install latexmk
+  - sudo apt-get install latex-xcolor
+addons:
+    apt:
+        packages:
+            - texlive-generic-recommended
+            - texlive-latex-recommended
+            - texlive-latex-extra
+            - texlive-fonts-recommended
+            - texlive-fonts-extra
+            - texlive-publishers
+install:
+
+# Now make the PDF, and move it to the top level, ready for deployment.
+script:
+    - make -C doc/desc-0000-twinkles-1-phosim-pipeline
+    - cp doc/desc-0000-twinkles-1-phosim-pipeline/desc-0000-twinkles-1-phosim-pipeline.pdf .
+
+# Finally, force-push the PDF to an otherwise empty "pdf" branch:
+after_success: |
+    if [ -n "$GITHUB_API_KEY" ] && [ "$TRAVIS_PULL_REQUEST" == "false" ] && [ "$TRAVIS_BRANCH" == "master" ]; then
+        git checkout --orphan pdf
+        git rm -rf .
+        git add -f desc-0000-twinkles-1-phosim-pipeline.pdf
+        git -c user.name='travis' -c user.email='travis' commit -m init
+        git push -q -f https://YourGitHubUserName:[email protected]/DarkEnergyScienceCollaboration/Twinkles pdf
+    fi

doc/LSST_DESC_Notes/desc-0000-twinkles-1-phosim-pipeline/Makefile

@@ -0,0 +1,178 @@
+# To make the document with the default settings:
+# > make
+#
+# To make with a specific format:
+# > make <format>
+#
+# To tar up a flat version of a specific format:
+# > make <format> tar
+#
+# Alex Drlica-Wagner: https://github.com/LSSTDESC/start_paper/issues/new?body=@kadrlica
+
+# Primary file names - avoid cookiecutter variables, to enable `make
+# upgrade` to cleanly over-write this Makefile...
+main=main
+default=$(shell cat .metadata.json | grep 'default_format' | cut -d'"' -f4)
+outname=$(notdir $(shell pwd))
+
+ifeq ($(default), rst)
+ style=tex
+else
+ style=${default}
+endif
+
+# LATEX environment variables
+export TEXINPUTS:=./texmf/styles/:./tables/:
+export BSTINPUTS:=./texmf/bib/:
+
+# LaTeX journal class switcher flags
+# apj=\def\flag{apj}
+# apjl=\def
+# mnras=\def\flag{mnras}
+
+# Submission flags (these need some thought)
+# arxiv=\def\flag{emulateapj}
+# submit=${aastex}
+# draft=\def\linenums{\linenumbers}
+
+# Files to copy when making tarball
+tardir=tmp
+figdir=./figures
+figures=$(figdir)/*.{png,jpg,pdf}
+tabdir=./tables
+tables=$(tabdir)/*.tex
+styles=./texmf/styles/*.{sty,cls}
+bibs=./texmf/bib/*.bst
+source=$(main).{tex,bbl,bib} lsstdesc.bib acknowledgments.tex authors.tex contributions.tex
+
+tarfiles=$(figures) $(tables) $(styles) $(bibs) $(source)
+
+# Interpret `make` with no target as `make tex` (a latex Note).
+# At present, if the default_format is anything other than
+# [apj|apjl|mnras|prd|prl|emulateapj], a latex Note is made.
+# In future, we could think of using `make` to eg run the ipynb
+# notebook and make PDF from the output, but this has not been
+# implemented yet.
+all: export flag = \def\flag{${style}}
+all: main copy
+
+copy:
+	cp ${main}.pdf ${outname}.pdf
+
+touch:
+	touch ${main}.tex
+
+#http://journals.aas.org/authors/aastex/linux.html
+#change the compiler call to allow a "." file
+# 
+main : authlist
+	latexmk -g -pdf  \
+	-pdflatex='openout_any=a pdflatex %O -interaction=nonstopmode "${flag}\input{%S}"'  \
+	${main}
+# 
+
+tar : main
+	mkdir -p ${tardir}
+	cp ${tarfiles} ${tardir} | true
+	cp ${outname}.pdf ${tardir}/${outname}.pdf
+	cd ${tardir} && tar -czf ../${outname}.tar.gz . && cd ..
+	rm -rf ${tardir}
+
+authlist :
+	pip install --upgrade mkauthlist
+	mkauthlist -j ${style} -f -c "LSST Dark Energy Science Collaboration" \
+		--cntrb contributions.tex authors.csv authors.tex
+
+# http://stackoverflow.com/q/8028314/
+TARGETS=apj apjl prd prl mnras tex aastex61 emulateapj
+$(TARGETS): export style = $(@)
+$(TARGETS): export flag = \def\flag{$(@)}
+$(TARGETS):
+	$(MAKE) -e main
+	$(MAKE) -e copy
+	$(MAKE) -e tar
+# NB. the 'tex' target doesn't actually do anything in docswitch - make
+# with no target compiles PDF out of main.tex using lsstdescnote.cls
+# (which is to say, by default we assume you are writing an LSST
+# DESC Note in latex format).
+
+tidy:
+	rm -f *.log *.aux *.out *.dvi *.synctex.gz *.fdb_latexmk *.fls
+	rm -f *.bbl *.blg *Notes.bib ${main}.pdf
+
+clean: tidy
+	rm -f ${outname}.pdf ${outname}.tar.gz
+
+# Update the tex styles etc:
+
+baseurl=https://raw.githubusercontent.com/LSSTDESC/start_paper/master/%7B%7Bcookiecutter.folder_name%7D%7D
+
+UPDATES=\
+texmf/bib/apj.bst \
+texmf/bib/mnras.bst \
+texmf/styles/aas_macros.sty \
+texmf/styles/aastex.cls \
+texmf/styles/aastex61.cls \
+texmf/styles/aps_macros.sty \
+texmf/styles/docswitch.sty \
+texmf/styles/emulateapj.cls \
+texmf/styles/mnras.cls \
+texmf/styles/lsstdescnote.cls \
+texmf/styles/lsstdesc_macros.sty \
+texmf/logos/desc-logo-small.png \
+texmf/logos/desc-logo.png \
+texmf/logos/header.png \
+lsstdesc.bib \
+.travis.yml \
+figures/example.png
+
+.PHONY: $(UPDATES)
+$(UPDATES):
+	curl -s -S -o $(@) ${baseurl}/$(@)
+	@echo " "
+
+update:
+	@echo "\nOver-writing LaTeX style files with the latest versions: \n"
+	@mkdir -p .logos figures texmf/styles texmf/bib
+	$(MAKE) $(UPDATES)
+
+# Get fresh copies of the templates etc, for reference:
+
+TEMPLATES=\
+acknowledgments.tex \
+authors.csv \
+main.ipynb \
+main.md \
+main.rst \
+main.tex \
+main.bib \
+.metadata.json
+
+.PHONY: $(TEMPLATES) templates
+$(TEMPLATES):
+	curl -s -S -o templates/$(@) ${baseurl}/$(@)
+	@echo " "
+
+templates:
+	@echo "\nDownloading the latest versions of the template files, for reference: \n"
+	@mkdir -p templates
+	$(MAKE) $(TEMPLATES)
+	$(MAKE) new
+	ls -a templates/*
+
+# Get a template copy of the latest Makefile, for reference:
+.PHONY: new
+new:
+	@echo "\nDownloading the latest version of the Makefile, for reference: \n"
+	@mkdir -p templates
+	curl -s -S -o templates/Makefile ${baseurl}/Makefile
+	@echo " "
+
+# Over-write this Makefile with the latest version:
+.PHONY: upgrade
+upgrade:
+	@echo "\nDownloading the latest version of the Makefile: \n"
+	curl -s -S -o Makefile ${baseurl}/Makefile
+	@echo "\nUpgrading version of mkauthlist: \n"
+	pip install mkauthlist --upgrade --no-deps
+	@echo "\nNow get the latest styles and templates with\n\n    make update\n    make templates\n"

doc/LSST_DESC_Notes/desc-0000-twinkles-1-phosim-pipeline/README.md

@@ -0,0 +1,62 @@
+
+## desc-0000-twinkles-1-phosim-pipeline
+# Twinkles 1 PhoSim Pipeline and Results
+
+*Tom Glanzman and others*
+
+We describe the implementation of the Twinkles 1 PhoSim pipeline, taking pre-made instance catalogs and processing them into e-images. The SLAC workflow engine `pipeline-II` is used to handle the processing, which was performed on the batch system at SLAC. XXX images were generated in a wallclcok time of XXX days, at an efficiency of XX%
+
+
+## Editing this Paper
+
+Fork and/or clone the project repo, and then
+edit the primary file. The name of this file will vary according to its format, but it should be one of either `main.rst` (if it's a [`reStructuredText`](http://docutils.sourceforge.net/rst.html) Note), `main.md` (if it's a [`Markdown`](https://github.com/adam-p/Markdown-here/wiki/Markdown-Cheatsheet) Note), `main.ipynb` (if it's an [`IPython Notebook`](https://ipython.org/notebook.html)) or `main.tex` (if it's a latex Note or paper).
+Please use the `figures` folder for your images.
+
+## Building this Paper
+
+GitHub is our primary distributor for LSST DESC Notes:
+once the Note has been merged into the project repo's master branch, it will be visible as a *shared* (but not *published*) paper. The presentation of Notes will be improved later, as the LSST DESC Publication System evolves.
+
+You can compile latex papers locally with
+```
+make  [apj|apjl|prd|prl|mnras]
+```
+`make` with no arguments compiles the latex using the `default_format` stored in `.metadata.json`. Choosing `tex` causes the paper to be made using the `texmf/styles/lsstdescnote.cls` class, with commands defined in `texmf/styles/lsstdesc_macros.sty`. Don't edit these style files, as you may want to replace them with newer versions as they become available. Instead, use the `macros.tex` file to add your own `newcommand`'s and `def`'s.
+
+At present, the Makefile is only used to compile latex. In future, we hope to enable compilation of jupyter notebooks, `Markdown` and `reStructuredText` format notes into PDF as well.
+
+## Updating the Styles and Templates
+
+From time to time, the latex style files will be updated: to re-download the latest versions, do
+```
+make update
+```
+This will over-write your folder's copies - but that's OK, as they are not meant to be edited by you!
+The template files (`main.*` etc) are also likely to be updated; to get fresh copies of these files, do
+```
+make templates
+```
+However, since you will have edited at least one of the templates in your folder, `make templates` creates a special `templates` folder for you to refer to. Finally, to get *new* style or template files that are added to the `start_paper` project, you'll need to first get the latest `Makefile`, and then `make update` and/or `make templates`. The command to obtain the latest `Makefile` is
+```
+make new
+```
+This will add the latest `Makefile` to your `templates` folder. If you want to over-write your existing `Makefile`, you can do
+```
+make upgrade
+```
+
+## Automatic PDF Sharing
+
+If this project is in a public GitHub repo, you can use the `.travis.yml` file in this folder to cause [travis-ci](http://travis-ci.org) to compile your paper into a PDF in the base repo at GitHub every time you push a commit to the master branch. The paper should appear as:
+
+**https://github.com/DarkEnergyScienceCollaboration/Twinkles/tree/pdf/desc-0000-twinkles-1-phosim-pipeline.pdf**
+
+To enable this service, you need to follow these steps:
+
+1. Turn on travis continuous integration, by [toggling your repo on your travis profile](https://travis-ci.org/profile). If you don't see your repo listed, you may not have permission to do this: in this case, [contact an admin via the issues](https://github.com/DarkEnergyScienceCollaboration/Twinkles/issues/new?body=@DarkEnergyScienceCollaboration/admin).
+2. Get a [GitHub "personal access token"](https://github.com/settings/tokens). Choose the "repo" option.
+3. Set the `GITHUB_API_KEY` environment variable with the value of this token at your repo's [travis settings page](https://travis-ci.org/DarkEnergyScienceCollaboration/Twinkles/settings).
+4. Copy the `.travis.yml` file in this folder to the top level of your repo (or merge its contents with your existing `.travis.yml` file).
+Edit the final `git push` command with your GitHub username.  
+Commit and push to trigger your travis build, but note that the PDF will only be deployed if the master branch is updated.

doc/LSST_DESC_Notes/desc-0000-twinkles-1-phosim-pipeline/acknowledgments.tex

@@ -0,0 +1,3 @@
+% 
+This is the text imported from \code{acknowledgments.tex}, and will be replaced by some standard LSST DESC boilerplate at some point.
+% 

doc/LSST_DESC_Notes/desc-0000-twinkles-1-phosim-pipeline/authors.csv

@@ -0,0 +1,32 @@
+# ======================================================================
+# authors.csv
+#
+# While we wait for the LSST DESC publications system to generate files
+# like this from its database, we'll need to edit authors.csv by hand.
+# Below are some example entries.
+#
+# Notes:
+#   - If someone has two affiliations, they get two rows, and the last
+#     row is is used for their contribution.
+#   - Try to make your one-sentence contribution statement as
+#     informative as possible, so that it's clear who did what.
+#   - The contribution statement is a _summary of your impact on the
+#     project_, not a _timecard_. So, if you spent 90% of your time
+#     debugging, but 10% of your time designing and implementing the
+#     framework that then needed debugging, your statement should
+#     emphasize the design and implementation rather than the debugging.
+#   - BUG: mkauthlist cannot deal with empty rows, so please avoid them!
+#   - BUG: contributions are re-formatted by mkauthlist into Title case,
+#     removing all other capitalizations. Sorry about this!
+#
+# Example rows for you to adapt:
+#
+# Drlica-Wagner,Alex,A.~Drlica-Wagner,Contact,"Fermi National Accelerator Laboratory, P. O. Box 500, Batavia, IL 60510, USA","Developed algorithms for switching between document styles and generating author lists, implemented and tested software.",[email protected]
+# Marshall,Phil,P.~Marshall,Contributor,"SLAC National Accelerator Laboratory, Menlo Park, CA 94025, USA","Initiated and led project.",[email protected]
+# Marshall,Phil,P.~Marshall,Contributor,"Kavli Institute for Particle Astrophysics \& Cosmology, P. O. Box 2450, Stanford University, Stanford, CA 94305, USA","Initiated and led project, designed templates, tested system.",[email protected]
+# Digel,Seth,S.~Digel,Builder,"SLAC National Accelerator Laboratory, Menlo Park, CA 94025, USA","Advised on LSST DESC publication system requirements.",[email protected]
+# Digel,Seth,S.~Digel,Builder,"Kavli Institute for Particle Astrophysics \& Cosmology, P. O. Box 2450, Stanford University, Stanford, CA 94305, USA","Advised on LSST DESC publication system requirements.",[email protected]
+#
+# ======================================================================
+Lastname,Firstname,Authorname,AuthorType,Affiliation,Contribution,Email
+"Glanzman", "Tom","Tom Glanzman",Contact,"SLAC","Led pipeline development work, operated pipeline.","[email protected]"