Merge pull request #6 from amisr/develop

[MNT]: Release v2020.2.0

.readthedocs.yml

@@ -9,11 +9,11 @@ build:
 
 python:
   version: 3.7
-  # install:
-  #    - method: pip
-  #      path: .
-  #    - requirements: requirements.txt
-  # system_packages: true
+  install:
+     - method: pip
+       path: .
+     - requirements: requirements.txt
+  system_packages: true
 
 sphinx:
   builder: html

README.rst

@@ -1,11 +1,14 @@
 flipchem
 ========
-.. image:: https://travis-ci.org/amisr/flipchem.svg?branch=master
-    :target: https://travis-ci.org/amisr/flipchem
+.. image:: https://travis-ci.com/amisr/flipchem.svg?branch=master
+    :target: https://travis-ci.com/amisr/flipchem
+.. image:: https://readthedocs.org/projects/flipchem/badge/?version=latest
+    :target: https://flipchem.readthedocs.io/en/latest/?badge=latest
+    :alt: Documentation Status
 
 Overview
 --------
-`flipchem` provides a python wrapper of the flipchem ionospheric photochemistry model developed by Phil Richards [Richards2011]_. The model requires NRLMSIS-00 neutral density and the f107 f107a and AP geophysical parameters as inputs, so both of these have been packaged with `flipchem`. NRLMSIS-00 is provided by wrapping the C version of the code written by Dominik Brodowski, which is based on the original Fortran version of the model [Picone2002]_.
+`flipchem` provides a python wrapper of the flipchem ionospheric photochemistry model developed by Phil Richards [Richards2011]_. Specifically, this code wraps the version of flipchem that was used for [Richards2010]_. The model requires NRLMSIS-00 neutral density and the f107, f107a, and AP geophysical parameters, so both of these have been packaged with `flipchem`. NRLMSIS-00 is provided by wrapping the C version of the code written by Dominik Brodowski, which is based on the original Fortran version of the model [Picone2002]_.
 
 Use Case
 --------
@@ -19,106 +22,76 @@ The package is intended to be used for fitting Incoherent Scatter Radar (ISR) da
 
 This facilitates usage of the multiprocessing library when processing ISR data, if each time interval is treated as a pool of asynchronous jobs.
 
-Installation
-------------
+Quick Start
+-----------
 
-Since this package is a wrapper around both C and Fortran source code, one must install `numpy <https://numpy.readthedocs.io/en/latest/>`_ before attempting installation. `Numpy` is used during installation of `flipchem` to compile the Fortran [Oliphant2006]_. 
+Since this package is a wrapper around both C and Fortran source code, one must have a C and Fortran compiler installed and one must also install `numpy <https://numpy.readthedocs.io/en/latest/>`_ before attempting installation. `Numpy` is used during installation of `flipchem` to compile the Fortran via f2py [Oliphant2006]_.
 
-Installation of `flipchem` can be accomplished using `pip`::
+Then, installation of `flipchem` can be accomplished using `pip`::
 
-    pip install git+https://github.com/amisr/flipchem.git@v2020.1.1
+    pip install git+https://github.com/amisr/flipchem.git@v2020.2.0
 
+And to make a profile of ion densities, one can try this::
 
-Example Usage
--------------
-
-First, it is very important to update the geophysical parameters files. There is an archive of these files available at `<https://amisr.com/geophys_params/>`_. They are organized by year, so once updated, you only need to update the current year. To update all years::
-
-    import flipchem
-    flipchem.update_geophys(year='all')
-
-
-and to update a specific year, say 1991::
-
-    import flipchem
-    flipchem.update_geophys(year=1991)
-
-
-Get the O+, O2+, NO+, N2+, and N+ ion densities at 130km above the RISR-N ISR::
-
-    from datetime import datetime
-    from flipchem import Flipchem
-
-    date = datetime(2017,1,4,2)
-    fc = Flipchem(date)
-
-    glat = 74.72955
-    glon = -94.90576
-    alt = 130.0
-    ne = 5.0e11
-    te = ti = 600.
-    outputs = fc.get_point(glat,glon,alt,ne,te,ti)
-    lthrs,sza,dec,Op,O2p,NOp,N2p,Np,NNO,N2D,success = outputs
-
-
-Or, we can get the ion fractions instead by replacing the last 2 lines with::
-
-    outputs = fc.get_point_fractions(glat,glon,alt,ne,te,ti)
-    lthrs,sza,dec,Op,O2p,NOp,N2p,Np,NNO,N2D,success = outputs
-
-
-One can also access MSIS directly::
-
-    from flipchem import MSIS
-    from datetime import datetime
-
-    date = datetime(2017,1,4,2)
-    glat = 74.72955
-    glon = -94.90576
-    alt = 130.0
-
-    msis = MSIS(date)
-    outputs = msis.get_point(glat,glon,alt)
-    He,O,N2,O2,Ar,Mass,H,N,AnomO,Texo,Tn = outputs
-
-And one can also access the f107, f107a, and AP::
 
     from datetime import datetime
+    import numpy as np
     import flipchem
-
-    f107, f107a, ap = flipchem.read_geophys(datetime(2017,1,4,2))
-
-
-And there is code available with the MSIS wrapper that provides ion-neutral and electron-neutral collision frequencies::
-
-    from flipchem import MSIS
-    from flipchem import compute_ion_neutral_collfreq
-    from flipchem import compute_electron_neutral_collfreq
-    from datetime import datetime
-
-    date = datetime(2017,1,4,2)
+    date = datetime(2017,1,4,18)
+    fc = flipchem.Flipchem(date)
+    
     glat = 74.72955
     glon = -94.90576
-    alt = 130.0
-
-    msis = MSIS(date)
-    outputs = msis.get_point(glat,glon,alt)
-    He,O,N2,O2,Ar,Mass,H,N,AnomO,Texo,Tn = outputs
+    alts = np.linspace(90,350,num=100)
+    nes = 5.0e11*np.exp(1-(alts-250)/70-np.exp(-(alts-250)/70))
+    tes = 2500*(1-np.exp(-(alts-90)/70))+300
+    tis = 1750*(1-np.exp(-(alts-90)/70))+300
     
-    # N+, O+, N2+, NO+, O2+
-    ion_masses = [14.0,16.0,28.0,30.0,32.0]
-    Te = Ti = 1000.0
-    nu_in = list()
-    neutral_densities = (H,He,N,O,N2,O2)
-    for mass in ion_masses:
-        nu_in.append(compute_ion_neutral_collfreq(neutral_densities, Tn, mass, Ti))
-    nu_en = compute_electron_neutral_collfreq(neutral_densities, Te)
+    Op = np.zeros((alts.shape))
+    O2p = np.zeros((alts.shape))
+    NOp = np.zeros((alts.shape))
+    N2p = np.zeros((alts.shape))
+    Np = np.zeros((alts.shape))
+    iters = np.zeros((alts.shape))
+    
+    for i,(alt,ne,te,ti) in enumerate(zip(alts,nes,tes,tis)):
+        outputs = fc.get_point(glat,glon,alt,ne,te,ti)
+        Op[i] = outputs[3]
+        O2p[i] = outputs[4]
+        NOp[i] = outputs[5]
+        N2p[i] = outputs[6]
+        Np[i] = outputs[7]
+        iters[i] = outputs[-1]
+    
+    fig = pyplot.figure(figsize=(15,10))
+    ax1 = fig.add_subplot(121)
+    ax2 = fig.add_subplot(122)
+    ax1.plot(nes,alts,'--',label='$N_e$',lw=4)
+    ax1.plot(Op,alts,label='$O^+$')
+    ax1.plot(O2p,alts,label='$O_2^+$')
+    ax1.plot(NOp,alts,label='$NO^+$')
+    ax1.plot(N2p,alts,label='$N_2^+$')
+    ax1.plot(Np,alts,label='$N^+$')
+    ax1.set_xscale('log')
+    ax1.set_xlim([1e9,1e12])
+    ax1.set_ylabel('Altitude (km)')
+    ax1.set_xlabel('Number Density (m$^{-3}$)')
+    l = ax1.legend()
+    
+    ax2.plot(tes,alts,label='$T_e$')
+    ax2.plot(tis,alts,label='$T_i$')
+    ax2.set_xlabel('Temperature (K)')
+    l = ax2.legend()
+
+Documentation
+-------------
 
-Example Notebook
-----------------
+You can finde more detailed documentation, including installation guides for Windows 10, macOS, and Linux here: https://flipchem.readthedocs.io
 
-`Here you can find an example notebook that shows how to get altitude profiles of ion densities <https://nbviewer.jupyter.org/github/amisr/flipchem/blob/v2020.1.1/notebooks/usage_examples.ipynb>`_. Is there an example missing that you would like to see? Feel free to suggest one!
+References
+----------
 
 .. [Oliphant2006] Oliphant, T. E. (2006). A guide to NumPy (Vol. 1). Trelgol Publishing USA.
 .. [Picone2002] Picone, J. M., Hedin, A. E., Drob, D. P., and Aikin, A. C. (2002). NRLMSISE‐00 empirical model of the atmosphere: Statistical comparisons and scientific issues, J. Geophys. Res., 107(A12), 1468, doi:10.1029/2002JA009430. 
+.. [Richards2010] Richards, P. G., Bilitza, D., and Voglozin, D. (2010), Ion density calculator (IDC): A new efficient model of ionospheric ion densities, Radio Sci., 45, RS5007, doi:10.1029/2009RS004332.
 .. [Richards2011] Richards, P. G. (2011). Reexamination of ionospheric photochemistry, J. Geophys. Res., 116, A08307, doi:10.1029/2011JA016613.

docs/conf.py

@@ -53,29 +53,33 @@
 # ones.
 extensions = [
     'sphinx.ext.autodoc',
+    'sphinx.ext.autosummary',
     'sphinx.ext.todo',
     'sphinx.ext.viewcode',
+    'sphinx.ext.napoleon',
 ]
 
+#napolean config options
+napoleon_use_ivar = True
+napoleon_use_rtype = False
+napoleon_use_param = False
+
 # Add any paths that contain templates here, relative to this directory.
 templates_path = ['_templates']
 
 # The suffix(es) of source filenames.
 # You can specify multiple suffix as a list of string:
-#
-# source_suffix = ['.rst', '.md']
 source_suffix = '.rst'
 
 # The encoding of source files.
-#
-# source_encoding = 'utf-8-sig'
+source_encoding = 'utf-8'
 
 # The master toctree document.
 master_doc = 'index'
 
 # General information about the project.
 project = u'AMISR'
-copyright = u'2019, asreimer'
+copyright = u'2020, asreimer'
 author = u'asreimer'
 
 # The version info for the project you're documenting, acts as replacement for

docs/index.rst

@@ -1 +1,11 @@
-.. include:: ../README.rst
+========
+Contents
+========
+
+.. toctree::
+   :maxdepth: 3
+
+   readme
+   installation/index
+   usage
+   reference/index

docs/installation/index.rst

@@ -0,0 +1,11 @@
+============
+Installation
+============
+
+.. toctree::
+   :maxdepth: 3
+
+   installation.linux
+   installation.macos
+   installation.windows
+

docs/installation/installation.linux.rst

@@ -0,0 +1,32 @@
+Installation Guide for Linux
+****************************
+
+Installing the flipchem python package requires python (python 3.x is recommended), a C compiler, and a Fortran compiler. Installation also requires the numpy python package to first be installed. Below is a guide for installation.
+
+Install system packages
+=======================
+
+Use you linux system package manager, for example `dnf` on Fedora or `aptitude` in Ubuntu, to install::
+
+    gcc python3 python3-devel
+
+You can usually find the OS specific package name with some light googling. If not, feel free to post an issue to github: https://github.com/amisr/flipchem
+
+Install numpy
+=============
+
+It is generally a good idea to work within a python virtual environment. This isolates the python environment that you work within from the system python enviroment. That means you are free to install packages without worrying about breaking your system. If you don't already have an environment set up, `here's a nice guide <https://realpython.com/python-virtual-environments-a-primer/>`_.
+
+After activating the python environment, you can install numpy using `pip`::
+
+    pip install numpy
+
+Installing flipchem
+===================
+
+Now you can install flipchem to the same python environment using `pip`::
+
+    pip install git+https://github.com/amisr/flipchem.git@v2020.2.0
+
+
+That's it! Easy peasy.

docs/installation/installation.macos.rst

@@ -0,0 +1,32 @@
+Installation Guide for macOS
+****************************
+
+Installing the flipchem python package requires python (python 3.x is recommended), a C compiler, and a Fortran compiler. Installation also requires the numpy python package to first be installed. Below is a guide for installation.
+
+Install system packages
+=======================
+
+In macOS it is recommended that you obtain `gcc` and `python3` using a package manager such as `homebrew` or `macports`. If you choose `homebrew`, then you can install `gcc` and `python` with::
+
+    $ brew install gcc python
+
+This will install the python headers (traditionally supplied by a `python-devel` package in linux) needed to compile the C and Fortran source code in `flipchem`. If you encounter trouble, feel free to post an issue to github: https://github.com/amisr/flipchem
+
+Install numpy
+=============
+
+It is generally a good idea to work within a python virtual environment. This isolates the python environment that you work within from the system python enviroment. That means you are free to install packages without worrying about breaking your system. If you don't already have an environment set up, `here's a nice guide <https://realpython.com/python-virtual-environments-a-primer/>`_.
+
+After activating the python environment, you can install numpy using `pip`::
+
+    pip install numpy
+
+Installing flipchem
+===================
+
+Now you can install flipchem to the same python environment using `pip`::
+
+    pip install git+https://github.com/amisr/flipchem.git@v2020.2.0
+
+
+That's it! Easy peasy.

docs/installation/installation.windows.rst

@@ -0,0 +1,55 @@
+Installation Guide for Windows
+******************************
+
+Installing the flipchem python package requires python (python 3.x is recommended), a C compiler, and a Fortran compiler. Installation also requires the numpy python package to first be installed. Below is a guide for installation.
+
+Install system packages
+=======================
+
+On Windows 10, it is recommended that you use the `chocolatey` package manager to install compilers and python. Package managers simplify the management of installed software. One could also install the C and Fortran compilers and python without a package manager, but this will likely be harder than using `chocolatey`. First, `install chocolatey <https://chocolatey.org/>`_.
+
+Next, install the compilers and python. Here we will use miniconda to provide python::
+
+    > choco install mingw32
+
+and::
+
+    > choco install miniconda3 --params="'/AddToPath:1'" --params="'/RegisterPython:1'"
+
+Optional
+--------
+
+If you would like to work within a bash shell, then you should also install `git bash`::
+
+    > choco install git.install
+
+and then, open a git-bash shell and run the following command to initialize the conda python environment for bash::
+
+    $ /c/tools/miniconda3/Scripts/conda init bash
+
+After this, you will have to restart the bash console.
+
+Install numpy
+=============
+
+Brief aside: It is generally a good idea to work within a python virtual environment. This isolates the python environment that you work within from the system python enviroment. That means you are free to install packages without worrying about breaking your system. If you don't already have an environment set up, `here's a nice guide <https://realpython.com/python-virtual-environments-a-primer/>`_. Since we are using miniconda, which is isolated from the Windows system anyway, this isn't as important, but it is a good habit. You can use `conda` to install the `virtualenv` package::
+
+    conda install virtualenv
+
+To install `numpy`, we'll use `conda`::
+
+    conda install numpy
+
+Installing flipchem
+===================
+
+Now you can install flipchem to the same python environment using `pip`::
+
+    pip install git+https://github.com/amisr/flipchem.git@v2020.2.0
+
+If `pip` isn't installed, you can install it using `conda`::
+
+    conda install pip
+
+
+That's it! Easy peasy.

docs/readme.rst

@@ -0,0 +1 @@
+.. include:: ../README.rst