Merge pull request #152 from sami2py/main

Update develop with release changes

.github/workflows/main.yml

@@ -18,9 +18,6 @@ jobs:
           - python-version: 3.7
             numpy_ver: 1.17
             os: ubuntu-latest
-          - python-version: 3.7
-            numpy_ver: 1.17
-            os: windows-latest
 
     name: Python ${{ matrix.python-version }} on ${{ matrix.os }} with numpy ${{ matrix.numpy_ver }}
     runs-on: ${{ matrix.os }}

.zenodo.json

@@ -23,6 +23,9 @@
     "affiliation": "U.S. Naval Research Laboratory",
     "name": "Burrell, Angeline G.",
     "orcid": "0000-0001-8875-9326"
+    },
+    {
+      "name": "zzyztyy"
     }
   ],
   "access_right": "open",

CHANGELOG.md

@@ -2,16 +2,18 @@
 All notable changes to this project will be documented in this file.
 This project adheres to [Semantic Versioning](http://semver.org/).
 
-## [next version] - 2021-04-05
-- Updated Variable and datasest attributes for netcdf export
-- Added default drift fourier coefficient array accessable from run model
+## [0.2.3] - 2021-06-16
+- Updated Variable and dataset attributes for netcdf export
+  - Updated netcdf file in test_data
+- Added default drift fourier coefficient array accessible from run model
 - Using minimum test version of numpy in accordance with NEP 29
 - Removed the sami2py-1.00.namelist and version.txt files from run_name
 - Bug Fix
   - Pull version info from a single location
   - fixed a bug in compiling readthedocs
   - added default exb file: setup.py generates a exb.inp file
   - Use integer for longitude in directory structure
+  - Improved windows compatibility
 - Added ability to input custom ExB Drifts as a Fourier Series
   - return_fourier function in utils.py
   - plot_exb function in _core_class.py
@@ -21,8 +23,9 @@ This project adheres to [Semantic Versioning](http://semver.org/).
   - private __make_fourier function in utils.py
   - Testing fourier_fit function in test_utils.py
   - scipy dependency added
-- added default exb file: setup.py generates a exb.inp file
+- Added default exb file: setup.py generates a exb.inp file
 - Added deprecation warnings to plotting functions
+- Adjusted output step size in model to more closely match desired cadence
 - Migrated CI testing to Github Actions
 - Documentation
   - Added zenodo integration

License.md

@@ -1,4 +1,4 @@
-Copyright (c) 2019, Jeff Klenzing (JK) and Joe Huba (JH)
+Copyright (c) 2021, sami2py development team
 All rights reserved.
 
 Redistribution and use in source and binary forms, with or without

README.rst

@@ -5,7 +5,7 @@ sami2py: sami2py is another model of the ionosphere python style
     :stub-columns: 1
 
     * - docs
-      - | |docs| |doi|
+      - | |rtd| |doi|
     * - tests
       - | |pytest|
         | |coveralls| |codecov|

docs/conf.py

@@ -17,7 +17,6 @@
 import sys
 # Need to set path before this can be imported
 sys.path.insert(0, os.path.abspath('..'))
-from sami2py import __version__  # noqa: E402
 
 # -- Project information -----------------------------------------------------
 
@@ -28,9 +27,13 @@
 copyright = ', '.join(['2021', author])
 
 # The short X.Y version
-version = __version__[::-1].partition('.')[2][::-1]
-# The full version, including alpha/beta/rc tags
-release = __version__
+module_dir = os.path.split(os.path.abspath(os.path.dirname(__file__)))[0]
+version_file = os.path.join(module_dir, project, 'version.txt')
+with open(version_file, 'r') as fin:
+    version = fin.read().strip()
+
+# The full version, including alpha/beta/rc tags.
+release = '{:s}-alpha'.format(version)
 
 
 # -- General configuration ---------------------------------------------------
@@ -50,7 +53,8 @@
     'sphinx.ext.autosummary',
     'sphinx.ext.napoleon',
     'numpydoc',
-    'IPython.sphinxext.ipython_console_highlighting']
+    'IPython.sphinxext.ipython_console_highlighting',
+    'm2r2']
 
 numpydoc_show_class_members = False
 

docs/contributing.rst

@@ -1 +1 @@
-.. include:: ../CONTRIBUTING.md
+.. mdinclude:: ../CONTRIBUTING.md

docs/introduction.rst

@@ -6,28 +6,50 @@
 Introduction
 ============
 
-Sami2py is a python module that runs the SAMI2 model, as well as archives, loads and plots the resulting modeled values. SAMI2 is a model developed by the Naval Research Laboratory to simulate the motions of plasma in a 2D ionospheric environment along a dipole magnetic field [Huba et al, 2000].  SAMI2 solves for the chemical and dynamical evolution of seven ion species in this environment (H\ :sup:`+`\, He\ :sup:`+`\, N\ :sup:`+`\, O\ :sup:`+`\, N\ :sub:`2` :sup:`+`\, NO\ :sup:`+`\, and O\ :sub:`2` :sup:`+`\).
-
-The implementation used here includes several added options to the original release of SAMI2.  A full list is included in :ref:`modifications`, but several of these include:
- - The ability to scale the neutral atmosphere in which the ions form through direct modification of the exospheric neutral temperature for extreme solar minimum conditions, as discussed by Emmert et al [2010].
+sami2py is a python module that runs the SAMI2 model, as well as archives, loads
+and plots the resulting modeled values. SAMI2 is a model developed by the Naval
+Research Laboratory to simulate the motions of plasma in a 2D ionospheric
+environment along a dipole magnetic field [Huba et al, 2000].  SAMI2 solves for
+the chemical and dynamical evolution of seven ion species in this environment
+(H\ :sup:`+`\, He\ :sup:`+`\, N\ :sup:`+`\, O\ :sup:`+`\, N\ :sub:`2` :sup:`+`\,
+NO\ :sup:`+`\, and O\ :sub:`2` :sup:`+`\).
+
+The implementation used here includes several added options to the original
+release of SAMI2.  A full list is included in :ref:`modifications`, but several
+of these include:
+ - The ability to scale the neutral atmosphere in which the ions form through
+   direct modification of the exospheric neutral temperature for extreme solar
+   minimum conditions, as discussed by Emmert et al [2010].
  - The ability to switch between HWM93, HWM07, and HWM14 as a user option.
 
 This implementation is based on the MatLab version used in Klenzing et al [2013].
 
-The open-source fortran version of SAMI2 is found at https://www.nrl.navy.mil/ppd/branches/6790/sami2
+The open-source fortran version of SAMI2 is found at
+https://www.nrl.navy.mil/ppd/branches/6790/sami2
 
 
 How to Cite
 -----------
 
-When referring to this software package, please cite the original paper by Huba et al [2000] https://doi.org/10.1029/2000JA000035 as well as the package by Klenzing and Smith [2019] https://doi.org/10.5281/zenodo.2875800.
+When referring to this software package, please cite the original paper by Huba
+et al [2000] https://doi.org/10.1029/2000JA000035 as well as the package by
+Klenzing et al. [2019] https://doi.org/10.5281/zenodo.2875800.
 
-Additionally, please include the following text in the acknowledgements: "This work uses the SAMI2 ionosphere model written and developed by the Naval Research Laboratory."
+Additionally, please include the following text in the acknowledgements: "This
+work uses the SAMI2 ionosphere model written and developed by the Naval Research
+Laboratory."
 
 
 References
 ----------
 
- - Huba, J.D., G. Joyce, and J.A. Fedder, Sami2 is Another Model of the Ionosphere (SAMI2): A new low‐latitude ionosphere model, *J. Geophys. Res.*, 105, Pages 23035-23053, https://doi.org/10.1029/2000JA000035, 2000.
- - Emmert, J.T., J.L. Lean, and J.M. Picone, Record‐low thermospheric density during the 2008 solar minimum, *Geophys. Res. Lett.*, 37, https://doi.org/10.1029/2010GL043671, 2010.
- - Klenzing, J., A. G. Burrell, R. A. Heelis, J. D. Huba, R. Pfaff, and F. Simões, Exploring the role of ionospheric drivers during the extreme solar minimum of 2008, *Ann. Geophys.*, 31, 2147-2156, https://doi.org/10.5194/angeo-31-2147-2013, 2013.
+ - Huba, J.D., G. Joyce, and J.A. Fedder, Sami2 is Another Model of the
+   Ionosphere (SAMI2): A new low‐latitude ionosphere model, *J. Geophys. Res.*,
+   105, Pages 23035-23053, https://doi.org/10.1029/2000JA000035, 2000.
+ - Emmert, J.T., J.L. Lean, and J.M. Picone, Record‐low thermospheric density
+   during the 2008 solar minimum, *Geophys. Res. Lett.*, 37,
+   https://doi.org/10.1029/2010GL043671, 2010.
+ - Klenzing, J., A. G. Burrell, R. A. Heelis, J. D. Huba, R. Pfaff, and F.
+   Simões, Exploring the role of ionospheric drivers during the extreme solar
+   minimum of 2008, *Ann. Geophys.*, 31, 2147-2156,
+   https://doi.org/10.5194/angeo-31-2147-2013, 2013.

docs/modifications.rst

@@ -1,22 +1,43 @@
 .. _modifications:
 
 Modifications from SAMI2-1.00
-========================================
+=============================
+
+General Updates
+---------------
+The calculation for the output step size was adjusted to be closer to the
+desired data cadence.
 
 NRLMSISe-00
 -----------
-This version uses the official release of NRLMSISe-00 (with one modification, discussed below). The unmodified version can be found at https://map.nrl.navy.mil/map/pub/nrl/NRLMSIS/NRLMSISE-00/
+This version uses the official release of NRLMSISe-00 (with one modification,
+discussed below). The unmodified version can be found at
+https://map.nrl.navy.mil/map/pub/nrl/NRLMSIS/NRLMSISE-00/
 
-The exospheric neutral temperature can be directly scaled by the user for extreme solar minimum conditions, as discussed by Emmert et al [2010].  This is modified by the ``Tinf_scale`` keyword, and is passed through the namelist as Tinf_scl.
+The exospheric neutral temperature can be directly scaled by the user for
+extreme solar minimum conditions, as discussed by Emmert et al [2010].  This
+is modified by the ``Tinf_scale`` keyword, and is passed through the namelist
+as Tinf_scl.
 
 Photoionization
 ---------------
-The photoionization rates can be modified by scaling the resultant EUV spectra.  Note that this occurs independently of any modifications to the neutral atmosphere through MSIS.  See Klenzing et al [2013] for examples. This is modified by the ``euv_scale`` keyword, and is passed through the namelist as euv_scl.
+The photoionization rates can be modified by scaling the resultant EUV spectra.
+Note that this occurs independently of any modifications to the neutral
+atmosphere through MSIS.  See Klenzing et al [2013] for examples. This is
+modified by the ``euv_scale`` keyword, and is passed through the namelist as
+euv_scl.
 
 ExB Drifts
 ----------
-Fejer-Scherliess remains the default model for drifts, but the user may now input a series of Fourier coefficients to describe the ExB drifts as a function of local time rather than use the Fejer-Scherliess model.  The coefficients are specified by the ``ExB_drifts`` keyword, which are passed into sami2 through the new exb.inp file.  The fourier coefficient routine replaces the sine wave triggered when .fejer. = false.
+Fejer-Scherliess remains the default model for drifts, but the user may now
+input a series of Fourier coefficients to describe the ExB drifts as a function
+of local time rather than use the Fejer-Scherliess model.  The coefficients are
+specified by the ``ExB_drifts`` keyword, which are passed into sami2 through
+the new exb.inp file.  The fourier coefficient routine replaces the sine wave
+triggered when .fejer. = false.
 
 Horizontal Wind Model
 ---------------------
-Sami2py uses the HWM-14 model by default.  Users may specify HWM93 or HWM07 for comparison through the ``hwm_model`` keyword, which is passed through the namelist as hwm_mod.
+Sami2py uses the HWM-14 model by default.  Users may specify HWM93 or HWM07 for
+comparison through the ``hwm_model`` keyword, which is passed through the
+namelist as hwm_mod.

docs/requirements.txt

@@ -1,2 +1,3 @@
-numpydoc
 ipython
+m2r2
+numpydoc

docs/sample_workflow.rst

@@ -7,7 +7,13 @@ In iPython, run:
 
   import sami2py
 
-If this is your first import of sami2py, it will remind you to set the top level directory that will hold the model output.  This should be a string containing the path to the directory you want to store the data in, such as ``path='/Users/me/data/sami2py'`` or ``path='C:\home\data'``.  This should be outside the main code directory, so model output files are not confused with model inputs or source code.  If you are using Git, it will also ensure that Git does not try to store your local code runs within the repository.
+If this is your first import of sami2py, it will remind you to set the top level
+directory that will hold the model output.  This should be a string containing
+the path to the directory you want to store the data in, such as
+``path='/Users/me/data/sami2py'`` or ``path='C:\home\data'``.  This should be
+outside the main code directory, so model output files are not confused with
+model inputs or source code.  If you are using Git, it will also ensure that
+Git does not try to store your local code runs within the repository.
 
 .. code:: python
 
@@ -19,17 +25,23 @@ sami2py will raise an error if this is not done before trying to run the model.
 
   sami2py.run_model(tag='run_name', lon=0, year=2012, day=210)
 
-Note that the sami2 model runs for 24 hours to clear transients, then begins to output data.
+Note that the sami2 model runs for 24 hours of simulated time to clear
+transients, then begins to output data. For the default options (24 hours of
+prep, 24 hours of output, output every 15 minutes), this may take 10-20 minutes
+to run, depending on the user setup.
 
 Now load the resultant data:
 
 .. code:: python
 
   ModelRun = sami2py.Model(tag='run_name', lon=0, year=2012, day=210)
 
-The data is stored as `ModelRun.data`, which is an `xarray.Dataset`.  Information about the run is stored as 'ModelRun.MetaData', which is a human-readable dictionary of the namelist.
+The data is stored as `ModelRun.data`, which is an `xarray.Dataset`.
+Information about the run is stored as 'ModelRun.MetaData', which is a
+human-readable dictionary of the namelist.
 
-The MetaData can be accessed directly via the dictionary, or through the __repr__.  Typing
+The MetaData can be accessed directly via the dictionary, or through the
+``__repr__``.  Typing
 
 .. code:: python
 
@@ -60,4 +72,32 @@ yields
 
   No modifications to empirical models
 
+
+Options
+-------
+
+For applications that require neutral density data (such as the `growin
+<https://github.com/JonathonMSmith/growin>`_` package), you can tell sami2 to
+output neutral parameters alongside the ions.  Note that the coupling between
+ions and neutrals is one way (neutrals drive ions), the neutral values are not
+expected to change from the version initialized by MSIS and scaled within the
+initialization routines in sami2.
+
+.. code:: python
+
+  sami2py.run_model(tag='run_name', lon=0, year=2012, day=210, outn=True)
+
+
+Saving as a netCDF4
+-------------------
+
+Once loaded, you have the option of saving your output as a netCDF4.  The
+resulting file can then be loaded via xarray or pysatModels.  All metadata
+about the model run (including the options used to generate the file) are saved
+as attributes within the netCDF4 object.
+
+.. code:: python
+
+  ModelRun.to_netcdf('your_filename.nc')
+
 Full description coming soon

requirements.txt

@@ -1,6 +1,6 @@
+matplotlib
 netCDF4
 numpy
 pandas
-xarray
-matplotlib
 scipy
+xarray

sami2py/__init__.py

@@ -15,15 +15,15 @@
 in this environment (H+, He+, N+, O+, N2+, NO+, and O2+).
 
 """
-from __future__ import print_function
 import logging
-import sys
 import os
+import sys
 
 # set the version
 here = os.path.abspath(os.path.dirname(__file__))
 with open(os.path.join(here, 'version.txt')) as version_file:
     __version__ = version_file.read().strip()
+del here, version_file
 
 # get home directory
 home_dir = os.path.expanduser('~')
@@ -37,16 +37,17 @@
     os.makedirs(sami2py_dir)
     print('Created {} directory to store settings.'.format(sami2py_dir))
 
-
-archive_path = os.path.join(sami2py_dir, 'archive_path.txt')
-if os.path.isfile(archive_path):
+_archive_path = os.path.join(sami2py_dir, 'archive_path.txt')
+if os.path.isfile(_archive_path):
     # load up stored data path
-    with open(archive_path, 'r') as f:
-        archive_dir = f.readline()
+    with open(_archive_path, 'r') as fin:
+        archive_dir = fin.readline()
+        del fin
 else:
     # create file
-    with open(archive_path, 'w+') as f:
-        f.write('')
+    with open(_archive_path, 'w+') as fout:
+        fout.write('')
+        del fout
     archive_dir = ''
     print('Run sami2py.utils.set_archive_dir to set the path to'
           ' top-level directory for model outputs.')
@@ -56,12 +57,15 @@
 
 if not on_rtd:
     # load fortran directory
-    with open(os.path.join(sami2py_dir, 'fortran_path.txt'), 'r') as f:
-        fortran_dir = f.readline()
+    with open(os.path.join(sami2py_dir, 'fortran_path.txt'), 'r') as fin:
+        fortran_dir = fin.readline()
+        del fin
     # load test_data directory
-    with open(os.path.join(sami2py_dir, 'test_data_path.txt'), 'r') as f:
-        test_data_dir = f.readline()
+    with open(os.path.join(sami2py_dir, 'test_data_path.txt'), 'r') as fin:
+        test_data_dir = fin.readline()
+        del fin
 
+del home_dir, env_name, on_rtd
 
 # import main functions
 try: