Merge pull request #118 from pysat/nrl_pub_release

NRL pub release
pysat · Apr 25, 2024 · 647def0 · 647def0
2 parents d9dfc65 + 7e31ff2
commit 647def0
Show file tree

Hide file tree

Showing 29 changed files with 243 additions and 51 deletions.
diff --git a/.readthedocs.yml b/.readthedocs.yml
@@ -0,0 +1,25 @@
+# .readthedocs.yml
+# Read the Docs configuration file
+# See https://docs.readthedocs.io/en/stable/config-file/v2.html for details
+
+# Required version of readthedocs
+version: 2
+
+# Set the version of Python and other tools you might need
+build:
+  os: ubuntu-22.04
+  tools:
+    python: "3.11"
+
+# Build documentation in the docs/ directory with Sphinx
+sphinx:
+   configuration: docs/conf.py
+
+
+# Declare the Python requirements required to build your docs
+python:
+   install:
+    - method: pip
+      path: .
+      extra_requirements:
+        - doc
diff --git a/ACKNOWLEDGEMENTS.md b/ACKNOWLEDGEMENTS.md
@@ -0,0 +1,29 @@
+Funding
+=======
+The following institutions, missions, and programs have provided funding
+for pysatMissions development.
+
+Institutions
+------------
+ - The Catholic University of America (CUA)
+ - Cosmic Studio
+ - National Aeronautics and Space Administration (NASA)
+ - National Science Foundation (NSF)
+ - Office of Naval Research (ONR)
+ - Universities Space Research Association
+ - The University of Texas at Dallas
+
+Programs
+--------
+ - NSF 125908, AGS-1651393
+ - Naval Research Laboratory N00173191G016 and N0017322P0744
+ - The Space Precipitation Impacts (SPI) project at Goddard Space Flight Center
+   through the Heliophysics Internal Science Funding Model
+
+Disclaimers
+===========
+Any opinions or actions taken by the listed funding institutions are those of
+the institutions and do not necessarily reflect the views of the pysatMissions
+development team or individual authors. Any opinions, findings, and conclusions
+or recommendations expressed in this material are those of the author(s) and do
+not necessarily reflect the views of the funding agencies.
diff --git a/CHANGELOG.md b/CHANGELOG.md
@@ -6,6 +6,7 @@ This project adheres to [Semantic Versioning](https://semver.org/).
 * Maintenance
   * Update workflows coveralls usage
   * Update NEP29
+  * Update headers and add acknowledgements
 
 ## [0.3.4] - 2023-06-22
 * Add support for skyfield propagation

diff --git a/README.md b/README.md
@@ -11,16 +11,19 @@
 [![Coverage Status](https://coveralls.io/repos/github/pysat/pysatMissions/badge.svg?branch=main)](https://coveralls.io/github/pysat/pysatMissions?branch=main)
 [![Maintainability](https://api.codeclimate.com/v1/badges/83011911691b9d2076e9/maintainability)](https://codeclimate.com/github/pysat/pysatMissions/maintainability)
 
-pysatMissions allows users to run build simulated satellites for Two-Line Elements (TLE) and add empirical data.  It includes the missions_ephem and mission_sgp4 instrument modules which can be imported into pysat.
+pysatMissions allows users to run build simulated satellites for Two-Line
+Elements (TLE) and add empirical data.  It includes the missions_ephem and
+mission_sgp4 instrument modules which can be imported into pysat.
 
 Main Features
 -------------
 - Simulate satellite orbits from TLEs and add data from empirical models
-- Import magnetic coordinates through apexpy and aacgmv2 (optional install)
+- Import magnetic coordinates through apexpy and aacgmv2 (optional dependencies)
 
 Documentation
 ---------------------
-[Full Documentation for main package](https://pysat.readthedocs.io/en/latest/)
+[Full Documentation](https://pysatmissions.readthedocs.io/en/latest/)
+[pysat Documentation](https://pysat.readthedocs.io/en/latest/)
 
 
 # Installation
@@ -76,7 +79,9 @@ from pysatMissions.instruments import missions_sgp4
 
 sim_inst = pysat.Instrument(inst_module=missions_sgp4)
 ```
-Another way to use the instruments in an external repository is to register the instruments.  This only needs to be done the first time you load an instrument.  Afterward, pysat will identify them using the `platform` and `name` keywords.
+Another way to use the instruments in an external repository is to register the
+instruments.  This only needs to be done the first time you load an instrument.
+Afterward, pysat will identify them using the `platform` and `name` keywords.
 
 ```
 import pysat
@@ -96,7 +101,7 @@ additional configuration.  Both can be installed from pip, but may require the
 The instrument `missions_ephem` has been deprecated since pyEphem is no longer
 maintained. This will be removed in v0.4.0.  Note that OMMBV is required for
 this instrument to function correctly, but is not required for the core
-pysatMissions package.  This has also been made optional to improve installation.  
-Please use the `missions_sgp4` instrument for future needs.
+pysatMissions package.  This has also been made optional to improve
+installation.   Please use the `missions_sgp4` instrument for future needs.
 
 The orbital trajectories can be calculated without any of the optional modules.
diff --git a/docs/acknowledgements.rst b/docs/acknowledgements.rst
@@ -0,0 +1 @@
+.. mdinclude:: ../ACKNOWLEDGEMENTS.md
diff --git a/docs/index.rst b/docs/index.rst
@@ -8,7 +8,7 @@ routines to generate simualted instruments using Two-Line Elements (TLEs),
 as well as apply geomagnetic field models to existing pysat instruments.
 
 .. toctree::
-   :maxdepth: -1
+   :maxdepth: 2
 
    introduction.rst
    installation.rst
@@ -19,3 +19,17 @@ as well as apply geomagnetic field models to existing pysat instruments.
    references.rst
    develop_guide.rst
    history.rst
+   acknowledgements.rst
+
+
+.. admonition:: DISTRIBUTION STATEMENT A: Approved for public release.
+		Distribution is unlimited.
+
+
+
+Indices and tables
+==================
+
+* :ref:`genindex`
+* :ref:`modindex`
+* :ref:`search`
diff --git a/docs/installation.rst b/docs/installation.rst
@@ -18,7 +18,7 @@ and for the Space Physics community.  This module officially supports
 Python 3.8+ and pysat 3.0.4+.
 
  ================ =================== ==================
- Common  modules   Community modules   Optional Modules
+ Common modules   Community modules   Optional Modules
  ================ =================== ==================
   numpy            pysat>=3.0.4        aacgmv2
   pandas           pyEphem             apexpy

diff --git a/docs/references.rst b/docs/references.rst
@@ -36,10 +36,10 @@ calculating magnetic apex coordinates.
   Science Reviews, 206, 27–59
 
 OMMBV
-------------
+-----
 
 .. image:: https://zenodo.org/badge/DOI/10.5281/zenodo.1299374.svg
    :target: https://doi.org/10.5281/zenodo.1299374
 
 `OMMBV <https://github.com/rstoneback/OMMBV>`_ calculates
-Orthogonal Multipole Magnetic Basis Vectors for the earth's magnetic field.
+Orthogonal Multipole Magnetic Basis Vectors for the Earth's magnetic field.
diff --git a/poweredbypysat.png b/poweredbypysat.png
diff --git a/pysatMissions/__init__.py b/pysatMissions/__init__.py
@@ -1,3 +1,9 @@
+# Full author list can be found in .zenodo.json file
+# DOI:10.5281/zenodo.3475498
+#
+# DISTRIBUTION STATEMENT A: Approved for public release. Distribution is
+# unlimited.
+# ----------------------------------------------------------------------------
 """Core library for pysatMissions.
 
 pysatMissions allows users to run build simulated satellites for Two-Line

diff --git a/pysatMissions/instruments/__init__.py b/pysatMissions/instruments/__init__.py
@@ -1,3 +1,9 @@
+# Full author list can be found in .zenodo.json file
+# DOI:10.5281/zenodo.3475498
+#
+# DISTRIBUTION STATEMENT A: Approved for public release. Distribution is
+# unlimited.
+# ----------------------------------------------------------------------------
 """Provides the instrument modules to be used with pysat."""
 
 from pysatMissions.instruments import methods  # noqa: F401

diff --git a/pysatMissions/instruments/_core.py b/pysatMissions/instruments/_core.py
@@ -1,3 +1,9 @@
+# Full author list can be found in .zenodo.json file
+# DOI:10.5281/zenodo.3475498
+#
+# DISTRIBUTION STATEMENT A: Approved for public release. Distribution is
+# unlimited.
+# ----------------------------------------------------------------------------
 """Handles the default pysat functions for simulated instruments."""
 
 

diff --git a/pysatMissions/instruments/methods/__init__.py b/pysatMissions/instruments/methods/__init__.py
@@ -1,3 +1,9 @@
+# Full author list can be found in .zenodo.json file
+# DOI:10.5281/zenodo.3475498
+#
+# DISTRIBUTION STATEMENT A: Approved for public release. Distribution is
+# unlimited.
+# ----------------------------------------------------------------------------
 """Methods to support multiple instrument files."""
 
 from pysatMissions.instruments.methods import orbits

diff --git a/pysatMissions/instruments/methods/orbits.py b/pysatMissions/instruments/methods/orbits.py
@@ -1,3 +1,9 @@
+# Full author list can be found in .zenodo.json file
+# DOI:10.5281/zenodo.3475498
+#
+# DISTRIBUTION STATEMENT A: Approved for public release. Distribution is
+# unlimited.
+# ----------------------------------------------------------------------------
 """Methods to convert orbital information for propagators."""
 
 import numpy as np

diff --git a/pysatMissions/instruments/missions_ephem.py b/pysatMissions/instruments/missions_ephem.py
@@ -1,4 +1,10 @@
 # -*- coding: utf-8 -*-
+# Full author list can be found in .zenodo.json file
+# DOI:10.5281/zenodo.3475498
+#
+# DISTRIBUTION STATEMENT A: Approved for public release. Distribution is
+# unlimited.
+# ----------------------------------------------------------------------------
 """Produce satellite orbit data.
 
 .. deprecated:: 0.3.0

diff --git a/pysatMissions/instruments/missions_sgp4.py b/pysatMissions/instruments/missions_sgp4.py
@@ -1,4 +1,10 @@
 # -*- coding: utf-8 -*-
+# Full author list can be found in .zenodo.json file
+# DOI:10.5281/zenodo.3475498
+#
+# DISTRIBUTION STATEMENT A: Approved for public release. Distribution is
+# unlimited.
+# ----------------------------------------------------------------------------
 """Simulate satellite orbit data using Two Line Elements (TLEs) and SGP4.
 
 Properties

diff --git a/pysatMissions/instruments/missions_skyfield.py b/pysatMissions/instruments/missions_skyfield.py
@@ -1,4 +1,10 @@
 # -*- coding: utf-8 -*-
+# Full author list can be found in .zenodo.json file
+# DOI:10.5281/zenodo.3475498
+#
+# DISTRIBUTION STATEMENT A: Approved for public release. Distribution is
+# unlimited.
+# ----------------------------------------------------------------------------
 """Simulate satellite orbit data using Two Line Elements (TLEs) and SGP4.
 
 Properties

diff --git a/pysatMissions/methods/__init__.py b/pysatMissions/methods/__init__.py
@@ -1,3 +1,9 @@
+# Full author list can be found in .zenodo.json file
+# DOI:10.5281/zenodo.3475498
+#
+# DISTRIBUTION STATEMENT A: Approved for public release. Distribution is
+# unlimited.
+# ----------------------------------------------------------------------------
 """Provides the methods to interface with numerous empirical model packages."""
 
 from pysatMissions.methods import magcoord

diff --git a/pysatMissions/methods/magcoord.py b/pysatMissions/methods/magcoord.py
@@ -1,5 +1,10 @@
-"""Routines for projecting aacgmv2 and apexpy model values onto pysat instruments.
-"""
+# Full author list can be found in .zenodo.json file
+# DOI:10.5281/zenodo.3475498
+#
+# DISTRIBUTION STATEMENT A: Approved for public release. Distribution is
+# unlimited.
+# ----------------------------------------------------------------------------
+"""Routines for projecting aacgmv2 and apexpy coords onto pysat instruments."""
 
 import pysat
 from pysatMissions.utils import package_check

diff --git a/pysatMissions/methods/spacecraft.py b/pysatMissions/methods/spacecraft.py
@@ -1,3 +1,9 @@
+# Full author list can be found in .zenodo.json file
+# DOI:10.5281/zenodo.3475498
+#
+# DISTRIBUTION STATEMENT A: Approved for public release. Distribution is
+# unlimited.
+# ----------------------------------------------------------------------------
 """Default routines for projecting values onto vectors for pysat instruments."""
 
 import numpy as np
@@ -16,23 +22,20 @@ def add_ram_pointing_sc_attitude_vectors(inst):
     inst : pysat.Instrument
         Instrument object
 
-    Returns
-    -------
-    None
-        Modifies pysat.Instrument object in place to include S/C attitude
-        unit vectors, expressed in ECEF basis. Vectors are named
-        sc_(x,y,z)hat_ecef_(x,y,z).
-        sc_xhat_ecef_x is the spacecraft unit vector along x (positive along
-        velocity vector) reported in ECEF, ECEF x-component.
-
     Notes
     -----
-        Expects velocity and position of spacecraft in Earth Centered
-        Earth Fixed (ECEF) coordinates to be in the instrument object
-        and named velocity_ecef_* (*=x,y,z) and position_ecef_* (*=x,y,z)
+    Modifies pysat.Instrument object in place to include S/C attitude
+    unit vectors, expressed in ECEF basis. Vectors are named
+    sc_(x,y,z)hat_ecef_(x,y,z).
+    sc_xhat_ecef_x is the spacecraft unit vector along x (positive along
+    velocity vector) reported in ECEF, ECEF x-component.
 
-        Adds attitude vectors for spacecraft in the ECEF basis by calculating
-        the scalar product of each attitude vector with each component of ECEF.
+    Expects velocity and position of spacecraft in Earth Centered
+    Earth Fixed (ECEF) coordinates to be in the instrument object
+    and named velocity_ecef_(x,y,z) and position_ecef_(x,y,z)
+
+    Adds attitude vectors for spacecraft in the ECEF basis by calculating
+    the scalar product of each attitude vector with each component of ECEF.
 
     """
 
@@ -71,11 +74,11 @@ def add_ram_pointing_sc_attitude_vectors(inst):
         for u in ['x', 'y', 'z']:
             inst.meta['sc_{:}hat_ecef_{:}'.format(v, u)] = {
                 inst.meta.labels.units: '',
-                inst.meta.labels.name: 'SC {:}-unit vector, ECEF-{:}'.format(v, u),
-                inst.meta.labels.desc: ' '.join(('S/C attitude ({:}'.format(v),
-                                                 '-direction, ram) unit vector,',
-                                                 'expressed in ECEF basis,',
-                                                 '{:}-component'.format(u)))}
+                inst.meta.labels.name: 'SC {:}-unit vector, ECEF-{:}'.format(
+                    v, u),
+                inst.meta.labels.desc: ' '.join((
+                    'S/C attitude ({:}-direction, ram) unit vector,'.format(v),
+                    'expressed in ECEF basis, {:}-component'.format(u)))}
 
     # Check what magnitudes we get
     mag = np.linalg.norm(
@@ -94,26 +97,24 @@ def calculate_ecef_velocity(inst):
     """Calculate spacecraft velocity in ECEF frame.
 
     .. deprecated:: 0.4.0
-      This function is no longer needed with the deprecation of `missions_ephem`.
-      Better calculations are available through geospacepy and skyfield.
-      `calculate_ecef_velocity` will be removed in versions 0.5.0+
-
-    Presumes that the spacecraft velocity in ECEF is in
-    the input instrument object as position_ecef_*. Uses a symmetric
-    difference to calculate the velocity thus endpoints will be
-    set to NaN. Routine should be run using pysat data padding feature
-    to create valid end points.
+      This function is no longer needed with the deprecation of
+      `missions_ephem`. Better calculations are available through geospacepy
+      and skyfield. `calculate_ecef_velocity` will be removed in versions 0.5.0+
 
     Parameters
     ----------
     inst : pysat.Instrument
         Instrument object
 
-    Returns
-    -------
-    None
-        Modifies pysat.Instrument object in place to include ECEF velocity
-        using naming scheme velocity_ecef_* (*=x,y,z)
+    Notes
+    -----
+    Presumes that the spacecraft velocity in ECEF is in the input instrument
+    object as position_ecef_(x,y,z). Uses a symmetric difference to calculate
+    the velocity thus endpoints will be set to NaN. Routine should be run using
+    pysat data padding feature to create valid end points.
+
+    Modifies pysat.Instrument object in place to include ECEF velocity
+    using naming scheme velocity_ecef_(x,y,z)
 
     """
 
@@ -168,6 +169,7 @@ def project_ecef_vector_onto_sc(inst, x_label, y_label, z_label,
         Label used to set Z component of projected vector
     meta : array_like of dicts (None)
         Dicts contain metadata to be assigned.
+
     """
 
     # TODO(#65): add checks for existence of ECEF variables in the Instrument
@@ -184,9 +186,12 @@ def project_ecef_vector_onto_sc(inst, x_label, y_label, z_label,
     zy = inst['sc_zhat_ecef_y']
     zz = inst['sc_zhat_ecef_z']
 
-    inst[new_x_label] = inst[x_label] * xx + inst[y_label] * xy + inst[z_label] * xz
-    inst[new_y_label] = inst[x_label] * yx + inst[y_label] * yy + inst[z_label] * yz
-    inst[new_z_label] = inst[x_label] * zx + inst[y_label] * zy + inst[z_label] * zz
+    inst[new_x_label] = inst[x_label] * xx + inst[y_label] * xy + inst[
+        z_label] * xz
+    inst[new_y_label] = inst[x_label] * yx + inst[y_label] * yy + inst[
+        z_label] * yz
+    inst[new_z_label] = inst[x_label] * zx + inst[y_label] * zy + inst[
+        z_label] * zz
 
     if meta is not None:
         inst.meta[new_x_label] = meta[0]

diff --git a/pysatMissions/tests/__init__.py b/pysatMissions/tests/__init__.py
@@ -1,3 +1,9 @@
+# Full author list can be found in .zenodo.json file
+# DOI:10.5281/zenodo.3475498
+#
+# DISTRIBUTION STATEMENT A: Approved for public release. Distribution is
+# unlimited.
+# ----------------------------------------------------------------------------
 """Unit and Integration tests for pysatMissions.
 
 Note