Merge pull request #651 from philippeller/pisa4

Pisa4

CONTRIBUTORS.md

@@ -1,20 +1,34 @@
 # Contributors
 
-Anyone who has contributed to the PISA project can file an issue, open a PR, or email to [email protected] to request to be listed here.
-See also [EXTERNAL_ATTRIBUTION.md](EXTERNAL_ATTRIBUTION.md).
-
 PISA was originally developed by members of The IceCube Collaboration, http://icecube.wisc.edu.
 Development by The IceCube Collaboration on PISA continues, PISA is being shared with the public in hopes that others can use and contribute back as well.
 
 Individual contributors, whether or not from The IceCube Collaboration, are listed below, in alphabetical order.
 
+* Thimothy Arlen
+* Summer Blott
+* Sebastian Böser
+* Étienne Bourbeau
+* Melanie Day
+* Thomas Ehrhardt
+* Philipp Eller
+* Aaron Fienberg
+* Leander Fischer
+* Maicon Hieronymus
+* Feifei Huang
+* Justin L. Lanfranchi
+* Elisa Lohfink
+* Wing Yan Ma
+* Shivesh Mandalia
+* Joakim Sandroos
+* Austin Schneider
+* Lukas Schulte
+* Tom Stuttart
+* Ahnaf Tahmid
+* Alexander Trettin
+* Mathhew J. Weiss
+* Jan Weldert
+* Steven Wren
 
-| Contributor                     | Email                                   | Contribution (optional; see git history for more detail)
-| ------------------------------- | --------------------------------------- | --------------------------------------------------------
-| Thimothy Arlen                  | [email protected]                  | PISA foundations, project management 
-| Sebastian Böser                 | [email protected]                    | PISA foundations, project management 
-| Melanie Day                     |                                         |
-| Justin L. Lanfranchi            | [email protected]               | PISA Cake (3.0) lead dev; architecture, core objects, vbwkde reco stage
-| Lukas Schulte                   | [email protected]                    |
-| Steven Wren                     |                                         |
-
+Anyone who has contributed to the PISA project can file an issue, open a PR to request to be listed here.
+See also [EXTERNAL_ATTRIBUTION.md](EXTERNAL_ATTRIBUTION.md).

INSTALL.md

@@ -57,7 +57,7 @@ The other advantage to these distributions is that they easily install without s
 To install PISA, you'll need to have the following non-python requirements.
 Note that these are not installed automatically, and you must install them yourself prior to installing PISA.
 Also note that Python, HDF5, and pip support come pre-packaged or as `conda`-installable packages in the Anaconda Python distribution.
-* [python](http://www.python.org) — version 3.7.x required: numba 0.45, which is required for SmartArray, does not allow python 3.8 or higher
+* [python](http://www.python.org) — version 3.x
   * Anaconda: built in
 * [pip](https://pip.pypa.io) version >= 1.8 required
   * Anaconda:<br>

README.md

@@ -1,4 +1,5 @@
-# PISA
+<img src="images/pisa4.png" width="250">
+
 [Introduction](pisa/README.md) |
 [Installation](INSTALL.md) |
 [Documentation](http://icecube.wisc.edu/%7Epeller/pisa_docs/index.html) |
@@ -7,34 +8,80 @@
 [Contributors](CONTRIBUTORS.md) |
 [Others' work](EXTERNAL_ATTRIBUTION.md)
 
-:warning: **PISA master branch now uses python 3!** :warning:
-
-PISA (PINGU Simulation and Analysis) is software written to analyze the results (or expected results) of an experiment based on Monte Carlo simulation.
+PISA is a software written to analyze the results (or expected results) of an experiment based on Monte Carlo simulation.
 
 In particular, PISA was written by and for the IceCube Collaboration for analyses employing the [IceCube Neutrino Observatory](https://icecube.wisc.edu/), including the [DeepCore](https://arxiv.org/abs/1109.6096) and the proposed [PINGU](https://arxiv.org/abs/1401.2046) low-energy in-fill arrays.
 However, any such experiment—or any experiment at all—can make use of PISA for analyzing expected and actual results.
 
 PISA was originally developed to cope with low-statistics Monte Carlo (MC) for PINGU when iterating on multiple proposed geometries by using parameterizations of the MC and operate on histograms of the data rather than directly reweighting the MC (as is traditionally done in high-energy Physics experiments).
 However, PISA's methods apply equally well to high-MC situations, and PISA also performs traditional reweighted-MC analysis as well.
 
-## Directory listing
-
-| File/directory            | Description
-| ------------------------- | -----------
-| `docs/`                   | Sphinx auto-generated documentation
-| `images/`                 | Images to include in documentation
-| `pisa/`                   | Source code
-| `pisa_examples/`          | Example resources for PISA from data to settings, notebooks with examples of how to use PISA, etc.
-| `pisa_tests/`             | Scripts for running physics and unit tests
-| `.gitattributes`          | Used with `versioneer`
-| `.gitignore`              | GIT ignores files matching these specifications
-| `CONTRIBUTORS.md`         | Listing of individuals who contributed code to PISA
-| `EXTERNAL_ATTRIBUTION.md` | Authors, references, and/or copyrights on external code used within PISA
-| `INSTALL.md`              | How to install PISA
-| `LICENSE`                 | Apache 2.0 license; applicable unless noted otherwise
-| `MANIFEST.in`             | Extra files to distribute with PISA package
-| `README.md`               | Brief overview of PISA
-| `pylintrc`                | PISA coding conventions for use with pylint
-| `setup.cfg`               | Setup file for `versioneer`
-| `setup.py`                | Python setup file, allowing e.g. `pip` installation
-| `versioneer.py`           | Automatic versioning
+If you use PISA, please cite our publication (e-Print available here: https://arxiv.org/abs/1803.05390):
+```
+"Computational Techniques for the Analysis of Small Signals
+in High-Statistics Neutrino Oscillation Experiments"
+IceCube Collaboration - M.G. Aartsen et al. (Mar 14, 2018)
+Published in: Nucl.Instrum.Meth.A 977 (2020) 164332
+```
+
+
+
+# Quick start
+
+## Installation
+
+```shell
+git clone [email protected]:IceCubeOpenSource/pisa.git
+cd pisa
+pip install -e .
+```
+
+For detailed installation instructions and common issues see [Installation](INSTALL.md)
+
+## Minimal Example
+
+Producing some oscillograms
+
+
+```python
+from pisa.core import Pipeline
+import matplotlib.pyplot as plt
+```
+
+    << PISA is running in single precision (FP32) mode; numba is running on CPU (single core) >>
+
+
+Instantiate a `Pipeline` or multiple pipelines in a `DistributionMaker` using PISA config files
+
+
+```python
+template_maker = Pipeline("settings/pipeline/osc_example.cfg")
+```
+
+Run the pipleine with nominal settings
+
+
+```python
+template_maker.run()
+```
+
+Get the oscillation probabilities <img src="https://render.githubusercontent.com/render/math?math=P_{\nu_\mu\to\nu_\mu}">
+
+
+```python
+outputs = template_maker.data.get_mapset('prob_mu')
+```
+
+Plot some results
+
+
+```python
+fig, axes = plt.subplots(figsize=(18, 5), ncols=3)
+outputs['nue_cc'].plot(ax=axes[0], cmap='RdYlBu_r', vmin=0, vmax=1);
+outputs['numu_cc'].plot(ax=axes[1], cmap='RdYlBu_r', vmin=0, vmax=1);
+outputs['nutau_cc'].plot(ax=axes[2], cmap='RdYlBu_r', vmin=0, vmax=1);
+```
+
+
+![png](README_files/README_10_0.png)
+

generate_readme.sh

@@ -0,0 +1,4 @@
+git rm README_files/*
+jupyter nbconvert --to markdown --output-dir . pisa_examples/README.ipynb
+git add -f README_files/*.png
+git add README.md

pisa/README.md

@@ -35,20 +35,3 @@ The original drawing is [here](https://docs.google.com/drawings/edit?id=1RxQj8rP
 
 An excellent (and far more detailed) description of the analysis process is maintained by Elim Cheung with particular application to IceCube/DeepCore atmospheric neutrino measurements [here](http://umdgrb.umd.edu/~elims/Fitter/Basics).
 She wrote her own fitter to perform these tasks. You can evaluate her ezFit analysis software as an alternative to (or as a complementary tool for comparing results with) PISA [here](http://code.icecube.wisc.edu/projects/icecube/browser/IceCube/sandbox/elims/ezfit).
-
-## Directory listing
-
-| File/directory               | Description
-| ---------------------------- | -----------
-| `analysis/`                  | Primary code for running an analysis
-| `core/`                      | Objects at the heart of PISA's functionality
-| `images/`                    | Images included in documentation
-| `scripts/`                   | Executable scripts with various purposes
-| `stages/`                    | Stages and the services that implement them
-| `utils/`                     | Miscellaneous functions and classes useful to PISA and for use by analyzers
-| `__init__.py`                | Global PISA constants and necessarily-centralized objects
-| `_version.py`                | Generated by Versioneer for versioning PISA
-| `general_conventions.md`     | PISA coding conventions
-| `glossary.md`                | Terminology used in PISA
-| `README.md`                  | Overview of PISA
-| `units_and_uncertainties.md` | How to specify & use units and uncertainties

pisa/__init__.py

@@ -11,7 +11,6 @@
 import warnings
 
 from numba import jit as numba_jit
-from numba import NumbaDeprecationWarning
 from numpy import (
     array, inf, nan,
     float32, float64,
@@ -123,9 +122,6 @@
     assert OMP_NUM_THREADS >= 1
 
 
-# Get SmartArray DeprecationWarning out of the way silently
-warnings.filterwarnings("ignore", category=NumbaDeprecationWarning)
-
 NUMBA_CUDA_AVAIL = False
 def dummy_func(x):
     """Decorate to to see if Numba actually works"""
@@ -141,8 +137,8 @@ def dummy_func(x):
     NUMBA_CUDA_AVAIL = True
 finally:
     if 'cuda' in globals() or 'cuda' in locals():
-        if NUMBA_CUDA_AVAIL:
-            cuda.close()
+        #if NUMBA_CUDA_AVAIL:
+        #    cuda.close()
         del cuda
 del dummy_func
 
@@ -160,7 +156,7 @@ def dummy_func(x):
 FLOAT64_STRINGS = ['double', 'float64', 'fp64', '64', 'f8']
 if 'PISA_FTYPE' in os.environ:
     PISA_FTYPE = os.environ['PISA_FTYPE']
-    ini_msgs.append('PISA_FTYPE env var is defined as: "%s"' % PISA_FTYPE)
+    #ini_msgs.append('PISA_FTYPE env var is defined as: "%s"' % PISA_FTYPE)
     if PISA_FTYPE.strip().lower() in FLOAT32_STRINGS:
         FTYPE = np.float32
         CTYPE = np.complex64
@@ -178,10 +174,7 @@ def dummy_func(x):
 del FLOAT32_STRINGS, FLOAT64_STRINGS
 
 # set default target
-if NUMBA_CUDA_AVAIL:
-    TARGET = 'cuda'
-else:
-    TARGET = 'cpu'
+TARGET = 'cpu'
 
 cpu_targets = ['cpu', 'numba'] # pylint: disable=invalid-name
 parallel_targets = ['parallel', 'multicore'] # pylint: disable=invalid-name

pisa/analysis/README.md

@@ -2,11 +2,4 @@
 
 Primary tools for performing analyses in PISA.
 
-
-## Directory Listing
-
-| File/directory    | Description
-| ----------------- | -----------
-| `__init__.py`     | Makes `analysis` directory behave as a Python module
-| `analysis.py`     | Defines `Analysis` class giving generic tools for performing analyses; sub-class this for specialized analyses
-| `hypo_testing.py` | Script and class `HypoTesting` for performing hypothesis tests; the class inherits from `Analysis`
+recent changes in `analysis.py` see https://nbviewer.jupyter.org/urls/seafile.rlp.net/f/c156d1fc084f4bd8af63//%3Fdl%3D1