docs/doc-source/ePS_ePSproc_tutorial/ePS_adv_tutorial_080520.ipynb

{
 "cells": [
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "# ePolyScat advanced usage tutorial\n",
    "08/05/20\n",
    "\n",
    "Paul Hockett\n",
    "\n",
    "Disclaimer: I am an enthusiastic ePolyScat user for photoionization calculations, but not an expert on the code. Nonetheless, this tutorial aims to go over some of the key features/uses of ePS for such problems - as far as my own usage goes - and provide an introduction and resource to new users."
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## Overview & resources"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "* [ePolyScat](https://epolyscat.droppages.com) (ePS) is an open-source tool for numerical computation of electron-molecule scattering & photoionization by Lucchese & coworkers. For more details try: \n",
    "    \n",
    "    * The [ePolyScat website and manual](https://epolyscat.droppages.com). Note that the manual uses a frames-based layout, use the menu on the page to navigate to sub-sections (direct links break the menu).\n",
    "    * *Calculation of low-energy elastic cross sections for electron-CF4 scattering*, F. A. Gianturco, R. R. Lucchese, and N. Sanna, J. Chem. Phys. 100, 6464 (1994), http://dx.doi.org/10.1063/1.467237\n",
    "    * *Cross section and asymmetry parameter calculation for sulfur 1s photoionization of SF6*, A. P. P. Natalense and R. R. Lucchese, J. Chem. Phys. 111, 5344 (1999), http://dx.doi.org/10.1063/1.479794\n",
    "        * *Applications of the Schwinger variational principle to electron-molecule collisions and molecular photoionization.* Lucchese, R. R., Takatsuka, K., & McKoy, V. (1986).  Physics Reports, 131(3), 147–221. https://doi.org/10.1016/0370-1573(86)90147-X (comprehensive discussion of the theory and methods underlying the code).\n",
    "    \n",
    " "
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "* [ePSproc](https://epsproc.readthedocs.io) is an open-source tool for post-processing & visualisation of ePS results, aimed primarily at photoionization studies.\n",
    "    \n",
    "    * Ongoing documentation is on [Read the Docs](https://epsproc.readthedocs.io).\n",
    "    * Source code is [available on Github](https://github.com/phockett/ePSproc).\n",
    "    * For more background, see the software metapaper for the original release of ePSproc (Aug. 2016): *ePSproc: Post-processing suite for ePolyScat electron-molecule scattering calculations*, on [Authorea](https://www.authorea.com/users/71114/articles/122402/_show_article) or [arXiv 1611.04043](https://arxiv.org/abs/1611.04043).\n",
    "    \n",
    "    "
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "* [ePSdata](https://phockett.github.io/ePSdata/index.html) is an open-data/open-science collection of ePS + ePSproc results.\n",
    "\n",
    "    * ePSdata collects ePS datasets, post-processed via ePSproc (Python) in [Jupyter notebooks](https://jupyter.org), for a full open-data/open-science transparent pipeline.\n",
    "    * ePSdata is currently (Jan 2020) collecting existing calculations from 2010 - 2019, from the [femtolabs at NRC](http://femtolab.ca), with one notebook per ePS job.\n",
    "    * In future, ePSdata pages will be automatically generated from ePS jobs (via the ePSman toolset, currently in development), for immediate dissemination to the research community.\n",
    "    * Source notebooks are available on the [Github project pages](https://github.com/phockett/ePSdata/), and notebooks + datasets via [Zenodo repositories](https://about.zenodo.org) (one per dataset). Each notebook + dataset is given a Zenodo DOI for full traceability, and notebooks are versioned on Github.\n",
    "    * Note: ePSdata may also be linked or mirrored on the existing [ePolyScat Collected Results OSF project](https://osf.io/psjxt/), but will effectively supercede those pages.\n",
    "    * All results are released under <a href=\"https://creativecommons.org/licenses/by-nc-sa/4.0/\">Creative Commons Attribution-NonCommercial-ShareAlike 4.0 (CC BY-NC-SA 4.0)</a> license, and are part of our ongoing [Open Science initiative](http://femtolab.ca/?p=877)."
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "### Workflow\n",
    "\n",
    "The general workflow for photoionization calculations plus post-processing is shown below. This pipeline involves a range of code suites, as shown in the main workflow; some additional details are also illustrated."
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "![ePS workflow](https://phockett.github.io/ePSdata/_images/ePSworkflow_170220.gv.png)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## ePS advanced usage\n",
    "\n",
    "As indicated in the [basic usage notebook](ePS_tutorial_080520.ipynb), there are a range of commands in ePS for additional computations and outputs. Explore the `Commands` [page of the manual for more details](https://epolyscat.droppages.com/SourceePolyScat_f90).\n",
    "\n",
    "In this tutorial these capabilities won't be explored further, aside from the to note two particularly interesting commands: \n",
    "\n",
    "* `DumpIdy`: [write photoionization matrix elements to output file](https://epolyscat.droppages.com/DumpIdy)\n",
    "* `ViewOrb`: [write (gridded) wavefunction to file](https://epolyscat.droppages.com/ViewOrb)\n",
    "\n",
    "In particular, the `DumpIdy` command provides a route to further post-processing/interfacing to other codes."
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "ePSproc has limited support for `ViewOrb`, with further support planned for the near future. Here's an example output, for the ABCO molecule (with legacy ePSproc Matlab code):\n",
    "\n",
    "![ABCO gif](https://osf.io/fv7q6/?action=download&mode=render&direct&public_file=False)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## ePSproc basic usage\n",
    "\n",
    "ePSproc implements some basic parsing of ePS files, plotting and further post-processing. Currently: \n",
    "\n",
    "* `CrossSection` segments can be read and plotted.\n",
    "* `DumpIdy` matrix element segments can be read and plotted.\n",
    "* Further properties (AF-PADs, MF-PADs etc) can be computed from the matrix elements.\n",
    "\n",
    "Example notebooks can be found in the ePSproc docs:\n",
    "\n",
    "* [Basic usage](https://epsproc.readthedocs.io/en/dev/demos/ePSproc_demo_Aug2019.html)\n",
    "* [Cross section parsing](https://epsproc.readthedocs.io/en/dev/demos/ePSproc_demo_CrossSections_Oct2019.html)\n",
    "\n",
    "\n",
    "(TODO - add some demo material directly here.)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## Working with dipole matrix elements"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "### Why work with matrix elements?\n",
    "\n",
    "Working directly from the dipole matrix elements has a few benefits, mainly relating to the flexibility these provide for post-processing and further use:\n",
    "\n",
    "- Fundamental molecular properties, these can be compared with experimentally obtained values (see [platfrom development for quantum metrology with photoelectrons notes](https://phockett.github.io/ePSdata/about.html#Scientific)).\n",
    "- Analysis of partial wave composition (also available directly from ePS using `GetCro` [with the CroByPartialWave option set](https://epolyscat.droppages.com/GetCro)).\n",
    "- Provides a minimal dataset which can be piped into further analysis/processing routines.\n",
    "- Computation of additional properties based on the matrix elements, e.g. molecular frame (MF) and aligned frame (AF) observables. (Some of these are already possible in ePS directly, e.g. `OrientCro` [for MF computations](https://epolyscat.droppages.com/OrientCro)).\n",
    "- Open-science: dissemination and sharing of results & processing (see [ePSdata](https://phockett.github.io/ePSdata/index.html)).\n",
    "\n",
    "\n",
    "Disadvantages...\n",
    "\n",
    "- Care required for consistency and correct treatment (e.g. phase conventions, normalisation, etc.).\n",
    "- Additional formalism and derivations required."
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "### ePSproc: workflow with matrix elements"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "The basic ePSproc workflow (from the [original software metapaper](https://www.authorea.com/users/71114/articles/122402/_show_article)) is shown below: essentially, the ePS output file is parsed for photoionization matrix elements, and ancillary data; the matrix elements are the used to calculate properties of interest, such as photoionziation cross-sections and MF-PADs.  For ePSdata, this workflow is applied to each ePS dataset, with a Jupyter notebook as a template. The completed analysis & dataset is then uploaded to Zenodo, and HTML version to ePSdata."
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "![ePSproc workflow](https://www.authorea.com/users/71114/articles/122402/master/file/figures/ePSproc_workflow_fig_040816/ePSproc_workflow_fig_040816.png)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "For further usage examples, see:\n",
    "\n",
    "* [Matrix element plotting routines demo](https://epsproc.readthedocs.io/en/dev/demos/ePSproc_demo_matE_plotting_Feb2020.html)\n",
    "* [Blm calculations](https://epsproc.readthedocs.io/en/dev/demos/ePSproc_BLM_calc_demo_Sept2019.html)\n",
    "* [Geometric method development](https://epsproc.readthedocs.io/en/dev/methods/geometric_method_dev_pt2_170320_v140420.html)\n",
    "\n",
    "... and the [results on ePSdata](https://phockett.github.io/ePSdata/index.html)."
   ]
  }
 ],
 "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.6"
  }
 },
 "nbformat": 4,
 "nbformat_minor": 4
}