diff --git a/.readthedocs.yml b/.readthedocs.yml new file mode 100644 index 00000000..b198cf86 --- /dev/null +++ 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 new file mode 100644 index 00000000..6c93bd0d --- /dev/null +++ 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 index bba4c924..559f5d86 100644 --- 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 index 02a5e446..b0bb4021 100644 --- 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 new file mode 100644 index 00000000..dd1f917a --- /dev/null +++ b/docs/acknowledgements.rst @@ -0,0 +1 @@ +.. mdinclude:: ../ACKNOWLEDGEMENTS.md diff --git a/docs/index.rst b/docs/index.rst index e70257dc..716c9a9c 100644 --- 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 index f592d6fb..57c9750c 100644 --- 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 index c5c1a0c6..f9d9e1bd 100644 --- 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 `_ 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 deleted file mode 100644 index ff169c67..00000000 Binary files a/poweredbypysat.png and /dev/null differ diff --git a/pysatMissions/__init__.py b/pysatMissions/__init__.py index d9ec8ef9..ad8c5673 100644 --- 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 index 2cc1b10f..d20bb40f 100644 --- 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 index 913eca26..72950802 100644 --- 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 index 2fa11425..c87cebf3 100644 --- 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 index 20d05754..c9cf6469 100644 --- 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 index 6ac06072..9ec2bfc8 100644 --- 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 index 8c6b6e36..5c31d20f 100644 --- 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 index 921a8c4e..49f4bf3d 100644 --- 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 index 97dbd4c2..09197d1a 100644 --- 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 index 8ab10ec0..0633a5b8 100644 --- 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 index c7098035..d0d9d6c9 100644 --- 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 index 96d5f6ef..3fdd8187 100644 --- 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 diff --git a/pysatMissions/tests/test_deprecation.py b/pysatMissions/tests/test_deprecation.py index 7b2fac8f..10802d8e 100644 --- a/pysatMissions/tests/test_deprecation.py +++ b/pysatMissions/tests/test_deprecation.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 tests for deprecated methods and objects in pysatMissions.""" import warnings @@ -20,7 +26,7 @@ def teardown_method(self): return def test_ephem_deprecation(self): - """Test that instatiating missions_ephem will give DeprecationWarning.""" + """Test that instatiating missions_ephem gives DeprecationWarning.""" with warnings.catch_warnings(record=True) as war: pysat.Instrument(inst_module=missions_ephem) diff --git a/pysatMissions/tests/test_inst_methods_orbits.py b/pysatMissions/tests/test_inst_methods_orbits.py index d8ffe46c..135fd3ef 100644 --- a/pysatMissions/tests/test_inst_methods_orbits.py +++ b/pysatMissions/tests/test_inst_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. +# ---------------------------------------------------------------------------- """Unit tests for `pysatMissions.instruments.methods.orbits`.""" import pysatMissions.instruments.methods.orbits as mm_orbits diff --git a/pysatMissions/tests/test_instruments.py b/pysatMissions/tests/test_instruments.py index b8f25fbc..06268411 100644 --- a/pysatMissions/tests/test_instruments.py +++ b/pysatMissions/tests/test_instruments.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 each instrument module. Note @@ -12,8 +18,7 @@ import pytest -# Make sure to import your instrument package here -# e.g., +# Make sure to import your instrument package here: import pysatMissions # Import the test classes from pysat diff --git a/pysatMissions/tests/test_methods_magcoord.py b/pysatMissions/tests/test_methods_magcoord.py index 183cb351..e01f7af5 100644 --- a/pysatMissions/tests/test_methods_magcoord.py +++ b/pysatMissions/tests/test_methods_magcoord.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. +# ---------------------------------------------------------------------------- """Test some of the aacgmv2 method functions.""" import datetime as dt diff --git a/pysatMissions/tests/test_methods_spacecraft.py b/pysatMissions/tests/test_methods_spacecraft.py index dbffd059..22e6b08d 100644 --- a/pysatMissions/tests/test_methods_spacecraft.py +++ b/pysatMissions/tests/test_methods_spacecraft.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. +# ---------------------------------------------------------------------------- """Test some of the spacecraft method functions.""" import datetime as dt diff --git a/pysatMissions/tests/test_utils.py b/pysatMissions/tests/test_utils.py index c3b45fdd..08bdfdab 100644 --- a/pysatMissions/tests/test_utils.py +++ b/pysatMissions/tests/test_utils.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 tests for pysatMissions utilitis.""" from importlib import import_module diff --git a/pysatMissions/utils/__init__.py b/pysatMissions/utils/__init__.py index 1827258c..ec0a6980 100644 --- a/pysatMissions/utils/__init__.py +++ b/pysatMissions/utils/__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 for pysatCDAAC instruments.""" from pysatMissions.utils._core import package_check # noqa F401 diff --git a/pysatMissions/utils/_core.py b/pysatMissions/utils/_core.py index 00682f48..94ff07bc 100644 --- a/pysatMissions/utils/_core.py +++ b/pysatMissions/utils/_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. +# ---------------------------------------------------------------------------- """Utilities for pysatMissions.""" from functools import wraps