Merge pull request #120 from aburrell/rc_v2.0.1

Release Candidate v2.0.1

.github/workflows/main.yml

@@ -5,7 +5,11 @@
 
 name: pytest with flake8
 
-on: [push, pull_request]
+on:
+  pull_request:
+  push:
+  schedule:
+    - cron: "0 3 * * 1"  # Runs 03:00 UT on Mondays 
 
 jobs:
   build:
@@ -48,8 +52,8 @@ jobs:
       if: ${{ matrix.os == 'macos-latest' }}
       run: |
           brew reinstall gcc
-          python -m build .
-          pip install .
+          CC=/usr/local/bin/gcc-12 python -m build .
+          CC=/usr/local/bin/gcc-12 pip install .
 
     - name: Install on Windows
       if: ${{ matrix.os == 'windows-latest' }}

.zenodo.json

@@ -34,6 +34,10 @@
       "affiliation": "Naval Research Laboratory", 
       "name": "Burrell, Angeline G."
     },
+    {
+      "orcid": "0000-0001-7098-0524",
+      "name": "Lamarche, Leslie L."
+    },
     {
       "orcid": "0000-0002-3487-3630",
       "name": "Starr, Gregory"
@@ -46,10 +50,6 @@
       "orcid": "0000-0001-7955-4441",
       "affiliation": "GFZ German Research Centre for Geosciences",
       "name": "Morschhauser, Achim"
-    },
-    {
-      "orcid": "0000-0001-7098-0524",
-      "name": "Lamarche, Leslie L."
     }
   ]
 }

AUTHORS.rst

@@ -7,10 +7,10 @@ This python wrapper is made by:
 * Karl M. Laundal
 * Christer van der Meeren
 * Angeline G. Burrell (maintainer)
+* Leslie Lamarche
 * Gregory Starr
 * Ashton Reimer
 * Achim Morschhauser
-* Leslie Lamarche
 
 Fortran code by Emmert et al. [2010] [1]_. Quasi-dipole and modified
 apex coordinates are defined by Richmond [1995] [2]_. The code uses
@@ -19,7 +19,7 @@ IGRF-12 with coefficients valid through 2020 [Thébault et al., 2015] [3]_.
 .. [1] Emmert, J. T., A. D. Richmond, and D. P. Drob (2010),
        A computationally compact representation of Magnetic-Apex
        and Quasi-Dipole coordinates with smooth base vectors,
-       J. Geophys. Res., 115(A8), A08322, :doi:`10.1029/2010JA015326`.
+       J. Geophys. Res., 115(A8), A08322, doi:10.1029/2010JA015326.
 
 .. [2] Richmond, A. D. (1995), Ionospheric Electrodynamics Using
        Magnetic Apex Coordinates, Journal of geomagnetism and

CHANGELOG.rst

@@ -2,6 +2,15 @@
 Changelog
 =========
 
+2.0.1 (2023-04-11)
+------------------
+* Expanded installation instructions in the documenation
+* Added unit tests for todays date, ensuring that `apex.dat` is current
+* Added cron unit test to GitHub Actions CI
+* Added a logo
+* Correct indexing bug in Fortran source that was causing array overflow and
+  memory errors for extrapolated years beyond the latest formal IGRF fit
+
 2.0.0 (2022-12-09)
 ------------------
 * Update Fortran source code to Fortran 90 standards

README.rst

@@ -1,3 +1,5 @@
+|logo|
+
 ========
 Overview
 ========
@@ -71,8 +73,7 @@ References
 .. [1] Emmert, J. T., A. D. Richmond, and D. P. Drob (2010),
        A computationally compact representation of Magnetic-Apex
        and Quasi-Dipole coordinates with smooth base vectors,
-       J. Geophys. Res., 115(A8), A08322,
-       `doi:10.1029/2010JA015326 <http://dx.doi.org/10.1029/2010JA015326>`_.
+       J. Geophys. Res., 115(A8), A08322, doi:10.1029/2010JA015326.
 
 .. [2] Richmond, A. D. (1995), Ionospheric Electrodynamics Using
        Magnetic Apex Coordinates, Journal of geomagnetism and
@@ -121,23 +122,26 @@ Badges
 
 .. |downloads| image:: https://img.shields.io/pypi/dm/apexpy.svg?style=flat
     :alt: PyPI Package monthly downloads
-    :target: https://pypi.python.org/pypi/apexpy
+    :target: https://pypi.org/project/apexpy
 
 .. |wheel| image:: https://img.shields.io/pypi/wheel/apexpy.svg?style=flat
     :alt: PyPI Wheel
-    :target: https://pypi.python.org/pypi/apexpy
+    :target: https://pypi.org/project/apexpy
 
 .. |supported-versions| image:: https://img.shields.io/pypi/pyversions/apexpy.svg?style=flat
     :alt: Supported versions
-    :target: https://pypi.python.org/pypi/apexpy
+    :target: https://pypi.org/project/apexpy
 
 .. |supported-implementations| image:: https://img.shields.io/pypi/implementation/apexpy.svg?style=flat
     :alt: Supported implementations
-    :target: https://pypi.python.org/pypi/apexpy
+    :target: https://pypi.org/project/apexpy
 
 .. |scrutinizer| image:: https://img.shields.io/scrutinizer/quality/g/aburrell/apexpy/main.svg?style=flat
     :alt: Scrutinizer Status
     :target: https://scrutinizer-ci.com/g/aburrell/apexpy/
 
 .. |doi| image:: https://www.zenodo.org/badge/doi/10.5281/zenodo.4585641.svg
    :target: https://doi.org/10.5281/zenodo.1214206
+
+.. |logo| image:: docs/apexpy.png
+   :alt: ApexPy logo: yellow magnetic field lines surrounding the Earth's surface, which is blue

apexpy/__init__.py

@@ -12,5 +12,5 @@
 from apexpy import helpers  # noqa F401
 
 # Define the global variables
-__version__ = "2.0.0"
+__version__ = "2.0.1"
 __all__ = ['Apex', 'fortranapex', 'helpers', 'ApexHeightError']

apexpy/apex.py

@@ -980,7 +980,7 @@ def basevectors_qd(self, lat, lon, height, coords='geo', precision=1e-10):
         .. [3] Emmert, J. T., A. D. Richmond, and D. P. Drob (2010),
                A computationally compact representation of Magnetic-Apex
                and Quasi-Dipole coordinates with smooth base vectors,
-               J. Geophys. Res., 115(A8), A08322, :doi:`10.1029/2010JA015326`.
+               J. Geophys. Res., 115(A8), A08322, doi:10.1029/2010JA015326.
 
         """
         # Convert from current coordinates to geodetic coordinates
@@ -1079,7 +1079,7 @@ def basevectors_apex(self, lat, lon, height, coords='geo', precision=1e-10):
         .. [5] Emmert, J. T., A. D. Richmond, and D. P. Drob (2010),
                A computationally compact representation of Magnetic-Apex
                and Quasi-Dipole coordinates with smooth base vectors,
-               J. Geophys. Res., 115(A8), A08322, :doi:`10.1029/2010JA015326`.
+               J. Geophys. Res., 115(A8), A08322, doi:10.1029/2010JA015326.
 
         """
         # Convert to geodetic coordinates from current coordinate system

apexpy/tests/test_Apex.py

@@ -108,6 +108,13 @@ def test_init_defaults(self):
         self.eval_refh()
         return
 
+    def test_init_today(self):
+        """Test Apex class initialization with today's date."""
+        self.apex_out = apexpy.Apex(date=self.test_date)
+        self.eval_date()
+        self.eval_refh()
+        return
+
     @pytest.mark.parametrize("in_date",
                              [2015, 2015.5, dt.date(2015, 1, 1),
                               dt.datetime(2015, 6, 1, 18, 23, 45)])
@@ -313,6 +320,13 @@ def get_input_args(self, method_name, precision=0.0):
 
         return in_args
 
+    def test_apex_conversion_today(self):
+        """Test Apex class conversion with today's date."""
+        self.apex_out = apexpy.Apex(date=dt.datetime.utcnow(), refh=300)
+        assert not np.isnan(self.apex_out.geo2apex(self.in_lat, self.in_lon,
+                                                   self.in_alt)).any()
+        return
+
     @pytest.mark.parametrize("apex_method,fortran_method,fslice",
                              [("_geo2qd", "apxg2q", slice(0, 2, 1)),
                               ("_geo2apex", "apxg2all", slice(2, 4, 1)),
@@ -1758,3 +1772,75 @@ def test_get_height_along_fieldline(self, lat, height):
         assert abs(height - fheight) < 1.0e-7, \
             "bad height calculation: {:.7f} != {:.7f}".format(height, fheight)
         return
+
+
+class TestApexMethodExtrapolateIGRF(object):
+    """Test the Apex methods on a year when IGRF must be extrapolated.
+
+    Notes
+    -----
+    Extrapolation should be done using a year within 5 years of the latest IGRF
+    model epoch.
+
+    """
+
+    def setup_method(self):
+        """Initialize all tests."""
+        self.apex_out = apexpy.Apex(date=2025, refh=300)
+        self.in_lat = 60
+        self.in_lon = 15
+        self.in_alt = 100
+        self.in_time = dt.datetime(2024, 2, 3, 4, 5, 6)
+        return
+
+    def teardown_method(self):
+        """Clean up after each test."""
+        del self.apex_out, self.in_lat, self.in_lon, self.in_alt
+        return
+
+    @pytest.mark.parametrize("method_name, out_comp",
+                             [("geo2apex",
+                               (56.25343704223633, 92.04932403564453)),
+                              ("apex2geo",
+                               (53.84184265136719, -66.93045806884766,
+                                3.6222547805664362e-06)),
+                              ("geo2qd",
+                               (56.82968521118164, 92.04932403564453)),
+                              ("apex2qd", (60.498401178276744, 15.0)),
+                              ("qd2apex", (59.49138097045895, 15.0))])
+    def test_method_scalar_input(self, method_name, out_comp):
+        """Test the user method against set values with scalars.
+
+        Parameters
+        ----------
+        method_name : str
+            Apex class method to be tested
+        out_comp : tuple of floats
+            Expected output values
+
+        """
+        # Get the desired methods
+        user_method = getattr(self.apex_out, method_name)
+
+        # Get the user output
+        user_out = user_method(self.in_lat, self.in_lon, self.in_alt)
+
+        # Evaluate the user output
+        np.testing.assert_allclose(user_out, out_comp, rtol=1e-5, atol=1e-5)
+
+        for out_val in user_out:
+            assert np.asarray(out_val).shape == (), "output is not a scalar"
+        return
+
+    def test_convert_to_mlt(self):
+        """Test conversion from mlon to mlt with scalars."""
+
+        # Get user output
+        user_out = self.apex_out.mlon2mlt(self.in_lon, self.in_time)
+
+        # Set comparison values
+        out_comp = 23.955474853515625
+
+        # Evaluate user output
+        np.testing.assert_allclose(user_out, out_comp, rtol=1e-5, atol=1e-5)
+        return

apexpy/tests/test_cmd.py

@@ -61,19 +61,19 @@ def execute_command_line(self, command, command_kwargs=None,
             or the requested output from the pipe command.
 
         """
-        if command_kwargs is None:
-            command_kwargs = {}
-
-        pipe = subprocess.Popen(command, **command_kwargs)
-        out = pipe.communicate()
-        pipe.wait()
+        data = None
 
         if pipe_out:
-            data = out
-        elif os.path.isfile(self.outfile):
-            data = np.loadtxt(self.outfile)
+            if command_kwargs is None:
+                command_kwargs = {}
+
+            pipe = subprocess.Popen(command, **command_kwargs)
+            data = pipe.communicate()
+            pipe.wait()
         else:
-            data = None
+            os.system(" ".join(command))
+            if os.path.isfile(self.outfile):
+                data = np.loadtxt(self.outfile)
 
         return data
 

docs/api.rst

@@ -63,4 +63,4 @@ You can get help on the command by running ``apexpy -h``.
 .. [1] Emmert, J. T., A. D. Richmond, and D. P. Drob (2010),
        A computationally compact representation of Magnetic-Apex
        and Quasi-Dipole coordinates with smooth base vectors,
-       J. Geophys. Res., 115(A8), A08322, :doi:`10.1029/2010JA015326`.
+       J. Geophys. Res., 115(A8), A08322, doi:10.1029/2010JA015326.

docs/conf.py

@@ -1,6 +1,7 @@
 # -*- coding: utf-8 -*-
 
 import json
+import os
 import re
 
 extensions = ['sphinx.ext.autodoc',
@@ -35,6 +36,9 @@
 autoapi_keep_files = True
 autoapi_root = 'autoapi/generated'
 
+# The name of an image file (relative to this directory) to place at the top
+# of the sidebar.
+html_logo = os.path.join(os.path.abspath('.'), 'apexpy.png')
 
 # The theme to use for HTML and HTML Help pages.  See the documentation for
 # a list of builtin themes.
@@ -54,4 +58,4 @@
 napoleon_use_rtype = False
 napoleon_use_param = False
 
-extlinks = {'doi': ('http://dx.doi.org/%s', 'doi:')}
+extlinks = {'doi': ('http://dx.doi.org/%s', 'doi:%s')}

docs/examples/index.rst → docs/ex_index.rst

@@ -6,7 +6,7 @@ and support functions.
 
 .. toctree::
 
-   ex_init.rst
-   ex_cli.rst
-   ex_apexh.rst
-   ex_gc.rst
+   examples/ex_init.rst
+   examples/ex_cli.rst
+   examples/ex_apexh.rst
+   examples/ex_gc.rst

docs/index.rst

@@ -7,7 +7,7 @@ Contents
 
    readme
    installation
-   examples/index
+   ex_index
    api
    contributing
    maintenance

docs/installation.rst

@@ -42,7 +42,9 @@ The code behind this package is written in Fortran.  Because of this, you
 the following steps.  `Gfortran <https://gcc.gnu.org/wiki/GFortran>`_ is a free
 compiler that can be installed, if one is not already available on your system.
 If you are installing this or MinGW in Windows, make sure you install it
-**after** installing the Windows Microsoft C++ Build tools. The :py:mod:`apexpy`
+**after** installing the Windows Microsoft C++ Build tools. You must also make
+sure that the compilers and Python that are installed both use the same
+processing standard (either 32-bit or 64-bit). The :py:mod:`apexpy`
 installation has been tested successfully with gfortran 7 and some more recent
 versions.  Earlier versions of gfortran may not work and are not recommended.
 
@@ -125,10 +127,12 @@ To download an artifact:
    download location. Alternatively (or if this doesn't work) you can use
    `wget` to retrieve the archive.
 4. Copy the zip archive into the ``apexpy/dist`` directory and unzip.
-5. Check the archive for the expected matrix of *.whl objects
+5. Check the archive for the expected matrix of ``*.whl`` objects
 
 To install, use ``pip install .``
 
+.. _installation-build:
+
 Build from Source
 ^^^^^^^^^^^^^^^^^
 
@@ -215,6 +219,20 @@ encountered when using clang for ``CC`` alongside gfortran.  This resulted in a
 seemly successful installation with :py:mod:`apexpy` reporting that fortranapex
 cannot be imported.
 
+Some users have reported unusual behavior when using Anaconda on Apple Silicon
+systems.  Anaconda will attempt to build and install the Intel versions of
+wheels instead of the M1 versions and run everything through Rosetta.  This
+configuration has not been fully evaluated, but it results in a seemly
+successful installation with :py:mod:`apexpy` reporting that fortranapex
+cannot be imported.  Users should confirm that wheels created by conda (both for
+apexpy and other packages) end in ``arm64.whl`` not ``osx-64.whl``.  If the
+later is true, users should consider uninstalling anaconda completely, and
+instead installing miniconda following
+`these instructions <https://conda.io/projects/conda/en/stable/user-guide/install/macos.html>`_,
+which has been confirmed to work. **WARNING:** This will remove any environments
+you have set up and likely undo all IDE settings, so be cautious and consider
+backing up your work first!
+
 
 Windows systems are known to have issues with Fortran-based codes.  The Windows
 testing we do uses miniconda, so we recommend using the Anaconda environment.