Merge pull request #378 from LSSTDESC/ccl_paper

CCL paper

doc/0000-ccl_note/main.bib

@@ -1,3 +1,39 @@
+@ARTICLE{CODATA14,
+   author = {{Mohr}, P.~J. and {Newell}, D.~B. and {Taylor}, B.~N.},
+    title = "{CODATA recommended values of the fundamental physical constants: 2014*}",
+  journal = {Reviews of Modern Physics},
+archivePrefix = "arXiv",
+   eprint = {1507.07956},
+ primaryClass = "physics.atom-ph",
+     year = 2016,
+    month = jul,
+   volume = 88,
+   number = 3,
+      eid = {035009},
+    pages = {035009},
+      doi = {10.1103/RevModPhys.88.035009},
+   adsurl = {http://adsabs.harvard.edu/abs/2016RvMP...88c5009M},
+  adsnote = {Provided by the SAO/NASA Astrophysics Data System}
+}
+
+@ARTICLE{IAU15,
+   author = {{Mamajek}, E.~E. and {Prsa}, A. and {Torres}, G. and {Harmanec}, P. and 
+	{Asplund}, M. and {Bennett}, P.~D. and {Capitaine}, N. and {Christensen-Dalsgaard}, J. and 
+	{Depagne}, E. and {Folkner}, W.~M. and {Haberreiter}, M. and 
+	{Hekker}, S. and {Hilton}, J.~L. and {Kostov}, V. and {Kurtz}, D.~W. and 
+	{Laskar}, J. and {Mason}, B.~D. and {Milone}, E.~F. and {Montgomery}, M.~M. and 
+	{Richards}, M.~T. and {Schou}, J. and {Stewart}, S.~G.},
+    title = "{IAU 2015 Resolution B3 on Recommended Nominal Conversion Constants for Selected Solar and Planetary Properties}",
+  journal = {ArXiv e-prints},
+archivePrefix = "arXiv",
+   eprint = {1510.07674},
+ primaryClass = "astro-ph.SR",
+ keywords = {Astrophysics - Solar and Stellar Astrophysics, Astrophysics - Earth and Planetary Astrophysics, Astrophysics - Astrophysics of Galaxies, Astrophysics - High Energy Astrophysical Phenomena, Astrophysics - Instrumentation and Methods for Astrophysics},
+     year = 2015,
+    month = oct,
+   adsurl = {http://adsabs.harvard.edu/abs/2015arXiv151007674M},
+  adsnote = {Provided by the SAO/NASA Astrophysics Data System}
+}
 @ARTICLE{Lawrence17,
    author = {{Lawrence}, E. and {Heitmann}, K. and {Kwan}, J. and {Upadhye}, A. and 
 	{Bingham}, D. and {Habib}, S. and {Higdon}, D. and {Pope}, A. and 

doc/0000-ccl_note/main.tex

@@ -289,10 +289,12 @@ \section{Functionality}
 \label{sec:func}
 
 \subsection{Physical constants}
-
 \label{sec:constants}
+We have performed a comparison of the physical constants used in \ccl and included dependencies and external sources. See Table \ref{tab:constants} for absolute fractional differences of the constants between these sources. Our final choice of constants for \ccl mainly relies on CODATA 2014 \citep{CODATA14} in as much as possible, except for ${\rm M}_\odot$, where we adopt the IAU 2015 value \citep{IAU15}, and for the conversion between parsec and meters, where we take the PDG 2013\footnote{\url{http://pdg.lbl.gov/2013/}} value. Notice that NIST\footnote{\url{https://physics.nist.gov/cuu/Constants/index.html}} adopts the CODATA 2014 values. 
+
+Notice there are some inconsistencies with the constants adopted by {\tt CLASS}. This includes the value of the gravitational constant, the Boltzmann constant, the Planck constant, the speed of light, and the electron charge. Also, the value of $\rho_c$ is derived from other constants, while PDG 2013 fixes it to a given value (this is the reason there is only one entry for that column).
 
-We have performed a comparison of the physical constants used in \ccl and included dependencies and external sources. See Table \ref{tab:constants} for percent differences of the constants between these sources.
+After comparison between the physical constants used in \ccl and those of the sources mentioned above, we have found better than $10^{−4}$ agreement for all constants of interest except for the gravitational constant and the value of the solar mass. 
 
 \input{table_constants}
 

doc/0000-ccl_note/tables/table_constants.tex

@@ -1,16 +1,17 @@
 \begin{table}
-  \begin{center}
-  \caption{Physical constants in \ccl. \label{tab:constants}}
+  \centering
+  \caption{Absolute fractional differences between different constants as tabulated in the sources listed below. Entries marked with zero indicate that this is the value adopted by \ccl. \label{tab:constants}}
   \begin{tabular}{lccccccccc}
-\hline\hline
- & $G_{Newt}$ & $k_b$ & $\sigma_{SB}$ & $h$ & $c$ & eV  & $M_\odot$ & pc \\ 
-\hline
-NIST & -3.0e-05 & -1.4e-06 & -5.9e-06 & 1.6e-07 & 0.0e+00 & 8.4e-08 & \--- & \--- \\[3pt]
- PDG 2013 & -6.0e-05 & -1.1e-06 & -4.8e-06 & 9.2e-08 & 0.0e+00 & 4.9e-08 & -2.0e-04 & 1.1e-09 \\[3pt] 
-GSL & -1.9e-04 & 0.0e+00 & 0.0e+00 & 0.0e+00 & 0.0e+00 & 0.0e+00 & 0.0e+00 & -4.5e-11 \\ [3pt]
-CLASS & 0.0e+00 & 0.0e+00 & \--- & 0.0e+00 & 0.0e+00 & 0.0e+00 & \--- & -6.7e-11 
-\\\hline\hline
-\end{tabular}
-\end{center}
+    \hline\hline
+    & $G_{Newt}$ & $k_b$ & $\sigma_{SB}$ & $h$ & $c$ & eV & $\rho_c$ & $M_\odot$ & pc \\
+    \hline
+    PDG 2013 & 3e-05 & 2.1e-07 & 1.1e-06 & 7e-08 & 0.0e+00 & 3.5e-08 & 8.8e-10 & 2.2e-05 & 0.0e+00 \\[3pt]
+    NIST & 0.0e+00 & 0.0e+00 & 0.0e+00 & 0.0e+00 & 0.0e+00 & 0.0e+00 & \--- & \--- & \--- \\[3pt]
+    GSL 2.4 & 1.6e-04 & 1.1e-06 & 5.8e-06 & 6e-09 & 1.5e-06 & 2.1e-06 & \--- & 2.2e-04 & 7.8e-07 \\[3pt]
+    CLASS & 3.0e-05 & 1.4e-06 & \--- & 1.6e-07 & 0.0e+00 & 8.4e-08 & \--- & \--- & 1.2e-09 \\[3pt]
+    CODATA 2014 & 0.0e+00 & 0.0e+00 & 0.0e+00 & 0.0e+00 & 0.0e+00 & 0.0e+00 & \--- & \--- & \--- \\[3pt]
+    IAU 2015 & 0.0e+00 & \--- & \--- & \--- & \--- & \--- & \--- & 0.0e+00 & \--- \\
+    \hline\hline
+  \end{tabular}
 \end{table}
 

doc/ccl_paper/.metadata.json

@@ -0,0 +1,12 @@
+{
+    "author": "David Alonso",
+    "affiliation": "University of Oxford",
+    "email": "--",
+    "title": "Core Cosmology Library: Precision Cosmological Predictions for LSST",
+    "description": "The Core Cosmology Library ({\tt CCL}) provides routines to compute basic cosmological observables with validated numerical accuracy. These routines have been validated to a hereby documented accuracy level against the results of the Code Comparsion Project. In the current version, predictions are provided for distances and background quantities, angular auto- and cross-spectra of cosmic shear and clustering and the halo mass function. Fiducial specifications for the expected LSST galaxy distributions and clustering bias are also included, together with a facility to compute redshift distributions for a user-defined photometric redshift model. {\tt CCL} is written in C with a Python interface. In this note, we explain the functionality of the first release ({\tt CCL} v0.1) of the library. ",
+    "repo_name": "CCL",
+    "serial_number": "0000",
+    "short_title": "note",
+    "folder_name": "0000-ccl-note",
+    "default_format": "tex"
+}

doc/ccl_paper/.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/{{ cookiecutter.folder_name }}
+    - cp doc/{{ cookiecutter.folder_name }}/{{ cookiecutter.folder_name }}.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 {{ cookiecutter.folder_name }}.pdf
+        git -c user.name='travis' -c user.email='travis' commit -m init
+        git push -q -f https://YourGitHubUserName:[email protected]/DarkEnergyScienceCollaboration/{{ cookiecutter.repo_name }} pdf
+    fi

doc/ccl_paper/Makefile

@@ -0,0 +1,189 @@
+# 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), {{ cookiecutter.default_format }})
+ 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
+# {% raw %}
+main : authlist
+	latexmk -g -pdf  \
+	-pdflatex='openout_any=a pdflatex %O -interaction=nonstopmode "${flag}\input{%S}"'  \
+	${main}
+# {% endraw %}
+
+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 : mkauthlist-exists
+	#pip install --upgrade mkauthlist
+ifdef MKAUTHLIST
+	$(MKAUTHLIST) -j ${style} -f -c "LSST Dark Energy Science Collaboration" \
+		--cntrb contributions.tex authors.csv authors.tex
+else
+	mkauthlist -j ${style} -f -c "LSST Dark Energy Science Collaboration" \
+		--cntrb contributions.tex authors.csv authors.tex
+endif
+
+# 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).
+
+# Check if mkauthlist exists. Can be overridden with environment variable.
+mkauthlist-exists : 
+ifndef MKAUTHLIST
+	$(if $(shell which mkauthlist),,$(error "mkauthlist not found. Install using 'pip install mkauthlist'"))
+endif
+
+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 \
+.logos/desc-logo-small.png \
+.logos/desc-logo.png \
+.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/ccl_paper/README.md

@@ -0,0 +1,75 @@
+
+## 0000-ccl_note
+# Core Cosmology Library: Precision Cosmological Predictions for LSST
+
+*David Alonso, Nora Elisa Chisari, Elizabeth Krause, C. Danielle Leonard, Sukhdeep Singh, Antonio Villarreal, Michal Vrastil, Joe Zuntz,  and others from the TJP Working Group*
+
+An overview of the core cosmology library, providing routines for cosmological predictions with validated numerical accuracy.
+
+
+## Editing this Paper
+
+Fork and/or clone the project repo, and then
+edit the primary file, `main.tex`.
+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 latex in LSST DESC Note style, and uses Alex Drlica-Wagner's `mkauthlist` program to compile the author list from the information stored in `authors.csv`. The Makefile includes the `pip install` command needed to obtain `mkauthlist`, but this does mean that you'll need to have `pip` installed and able to install python packages on your system.
+
+## Known building issues
+
+If you are not admin of your system, you might need to edit the following line of the Makefile, replacing:
+```
+pip install --upgrade mkauthlist
+```
+by
+```
+pip install --user --upgrade mkauthlist
+```
+
+In this case, make sure that the directory where `mkauthlist` is installed is placed at the beginning of the `$PYTHONPATH`.
+
+Also, `pip` might be installed in your system under a different alias. If so, you will need to replace `pip` above by the correct alias.
+
+## 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
+
+Once this project is in a public GitHub repo, we'll be able to use the `.travis.yml` file in this folder to cause [travis-ci](http://travis-ci.org) to compile the CCL Note into a PDF in the base repo at GitHub every time we push a commit to the master branch. The paper should then appear as:
+
+**https://github.com/LSSTDESC/CCL/tree/pdf/0000-ccl_note.pdf**
+
+To enable this service, we 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 we don't see your repo listed, we may not have permission to do this: in this case, [we'll need to contact an admin via the issues](https://github.com/LSSTDESC/CCL/issues/new?body=@LSSTDESC/admin).
+2. Get a [GitHub "personal access token"](https://github.com/settings/tokens), choosing the "repo" option.
+3. Set the `GITHUB_API_KEY` environment variable with the value of this token at the CCL repo's [travis settings page](https://travis-ci.org/LSSTDESC/CCL/settings).
+4. Merge the contents of the `.travis.yml` file in this folder with the existing CCL `.travis.yml` file).
+5. Edit the final `git push` command with a repo admin GitHub username.  
+6. Commit and push to trigger the travis build. Note that the PDF will only be deployed if the master branch is updated.