From ac78ade918efb8f93d23861e63c986dbcab43c83 Mon Sep 17 00:00:00 2001 From: Greg Lucas Date: Mon, 18 Nov 2024 15:31:50 -0700 Subject: [PATCH] DOC: Add CHANGELOG file to track changes in the project Additionally, update some other documentation surrounding it and include this in the main documentation page with myst markdown. --- .github/workflows/docs.yml | 2 +- .github/workflows/tests.yml | 2 +- CHANGELOG.md | 76 +++++++++++++++++++++++++++++++++ README.md | 18 ++++---- docs/requirements.txt | 5 --- docs/source/changelog/index.rst | 3 ++ docs/source/conf.py | 3 +- docs/source/index.rst | 21 ++------- pyproject.toml | 7 +-- 9 files changed, 101 insertions(+), 36 deletions(-) create mode 100644 CHANGELOG.md delete mode 100644 docs/requirements.txt create mode 100644 docs/source/changelog/index.rst diff --git a/.github/workflows/docs.yml b/.github/workflows/docs.yml index a32f4e9..4462f8e 100644 --- a/.github/workflows/docs.yml +++ b/.github/workflows/docs.yml @@ -31,7 +31,7 @@ jobs: - name: Install dependencies run: | python -m pip install --upgrade pip - pip install .[docs] + pip install .[doc] - name: Build documentation run: | diff --git a/.github/workflows/tests.yml b/.github/workflows/tests.yml index c9b10a2..6832494 100644 --- a/.github/workflows/tests.yml +++ b/.github/workflows/tests.yml @@ -76,7 +76,7 @@ jobs: # that includes https://github.com/mesonbuild/meson/pull/13851 is available python -m pip install git+https://github.com/mesonbuild/meson python -m pip install ninja meson-python setuptools_scm numpy - python -m pip install --no-build-isolation -v .[tests] + python -m pip install --no-build-isolation -v .[test] - name: Test with pytest run: | diff --git a/CHANGELOG.md b/CHANGELOG.md new file mode 100644 index 0000000..e4b76a7 --- /dev/null +++ b/CHANGELOG.md @@ -0,0 +1,76 @@ +# Changelog + +All notable changes to this project will be documented in this file. + +## [Unreleased] + +- **ADDED** Python 3.13 and 3.13t support +- **ADDED** Multithreaded support. + - The underlying MSIS libraries are not threadsafe due + to the use of many global/save variables. There is a lock around the + extension modules so that only one thread will be calling the routines + at a time, so the Python library is safe to use in a multi-threaded context. +- **MAINTENANCE** Default `-O1` optimization level for all builds. + - Previously, this + was only done on Windows machines. Users can change this by updating + environment variables before building with `FFLAGS=-Ofast`, but note that + some machines produce invalid results when higher optimizations are used. +- **PERFORMANCE** Cache options state between subsequent runs. + - Avoid calling initialization switches unless they have changed between runs +- **PERFORMANCE** Speed up numpy function calls. + - Change some numpy broadcasting and comparisons to speed up the creation of + input and output values. +- **MAINTENANCE** Add dynamic versioning to the project based on git tags and commits. + - This removes the need to manually bump the version numbers and metadata before + releasing the project which led to some errors previously. +- **DEPRECATED** Calling `msis00f.pytselec()` and `msis00f.pygtd7d` functions. + - Use `msis00f.pyinitswitch` and `msis00f.pymsiscalc` instead. + - This helps with standardization across the extension modules. These extension + should rarely be used by external people and `msis.run()` is a better entry + to using the package. + +## [v0.9.0] - 2024-04-03 + +- **MAINTENANCE** Add MacOS arm64 wheels (Apple Silicon). +- **FIX** Obvious solar radio burst F10.7 data is automatically removed. + - This applies to the default data and a warning is issued when running over + these time periods. + +## [v0.8.0] - 2023-10-03 + +- **MAINTENANCE** Python 3.10+ required. + +## [v0.7.0] - 2023-01-29 + +### Maintenance + +- **MAINTENANCE** CelesTrak is now used as the data provider for the Ap and F10.7 values. + - This avoids data gaps and interpolation issues that were present in the source data. +- **MAINTENANCE** Cleanup type hints throughout the codebase. +- **MAINTENANCE** Updated the wrappers argument order to be the same throughout. + - This helps when called with positional vs keyword arguments. + +## [v0.6.0] - 2022-11-14 + +- **ADDED** Automatic download of F10.7 and ap data for users. + - This means that F10.7 and ap are optional inputs to the `msis.run()` + function during historical periods and the routines will automatically + fetch the proper input data. + +- **MAINTENANCE** We now use meson as the build system to compile the extension modules. + +## [v0.5.0] - 2022-08-18 + +- **ADDED** MSIS2.1, a new version of MSIS. + - This is the first version that contains NO. + - This is the new default used in `msis.run()`. +- **MAINTENANCE** Added more wheels to the release and CI systems for testing. + +## [v0.4.0] - 2022-02-26 + +- **ADDED** Created a DOI for the project: . +- **ADDED** Handle flattened input arrays directly (satellite flythroughs). + +## [v0.3.0] - 2021-08-31 + +- **ADDED** First release with wheels for all platforms. diff --git a/README.md b/README.md index c585090..35023d0 100644 --- a/README.md +++ b/README.md @@ -8,8 +8,10 @@ [![GitHubActions](https://github.com/SWxTREC/pymsis/actions/workflows/tests.yml/badge.svg)](https://github.com/SWxTREC/pymsis/actions?query=workflow%3Atests) [![codecov](https://codecov.io/gh/SWxTREC/pymsis/branch/main/graph/badge.svg?token=NSUGKPJ3F7)](https://codecov.io/gh/SWxTREC/pymsis) -Pymsis is a minimal and fast Python wrapper of the NRLMSIS -models (MSISE-00, MSIS2.0, MSIS2.1). +Pymsis is a minimal and fast Python wrapper of the NRLMSIS models (MSISE-00, MSIS2.0, MSIS2.1). +The [MSIS model](https://www.nrl.navy.mil/Our-Work/Areas-of-Research/Space-Science/) is +developed by the Naval Research Laboratory. For quick access to the model data without any code, +there is a web viewer that uses pymsis: ## Quickstart @@ -41,9 +43,9 @@ plt.show() > **note** > -> * The model will automatically download and access the F10.7 and ap data for you if you have an internet connection. -> * The returned data structure has shape [ndates, nlons, nlats, nalts, 11], but for this example we only have one point with many dates [ndates, 1, 1, 1, 11]. -> * The 11 is for each of the species MSIS calculates for each input point. The first element is the Total Mass Density (kg/m3). +> - The model will automatically download and access the F10.7 and ap data for you if you have an internet connection. +> - The returned data structure has shape [ndates, nlons, nlats, nalts, 11], but for this example we only have one point with many dates [ndates, 1, 1, 1, 11]. +> -s The 11 is for each of the species MSIS calculates for each input point. The first element is the Total Mass Density (kg/m3). ## NRL Mass Spectrometer, Incoherent Scatter Radar Extended Model (MSIS) @@ -52,7 +54,7 @@ model](https://www.nrl.navy.mil/Our-Work/Areas-of-Research/Space-Science/) is developed by the Naval Research Laboratory. Note that the MSIS2 code is not available for commercial use without -contacting NRL. See the [MSIS2 license file](MSIS2_LICENSE) for explicit +contacting NRL. See the [MSIS2 license file](https://github.com/SWxTREC/pymsis/blob/main/MSIS2_LICENSE)) for explicit details. We do not repackage the MSIS source code in this repository for that reason. However, we do provide utilities to easily download and extract the original source code. By using that code you @@ -127,7 +129,7 @@ test dependencies. ```bash git clone https://github.com/SWxTREC/pymsis.git cd pymsis -pip install .[tests] +pip install .[test] ``` ### Remote installation @@ -136,7 +138,7 @@ The installation is dependent on access to the NRL source code. If the download fails, or you have no internet access you can manually install the Fortran source code as follows. A script to help with this or give ideas on how to achieve this remote installation are provided in the -[tools directory](tools/download_source.py). +[tools directory](https://github.com/SWxTREC/pymsis/blob/main/tools/download_source.py)). 1. **Download the source code** The source code is hosted on NRL\'s website: diff --git a/docs/requirements.txt b/docs/requirements.txt deleted file mode 100644 index 0106a79..0000000 --- a/docs/requirements.txt +++ /dev/null @@ -1,5 +0,0 @@ -numpy -matplotlib -sphinx -sphinx_gallery -pydata-sphinx-theme \ No newline at end of file diff --git a/docs/source/changelog/index.rst b/docs/source/changelog/index.rst new file mode 100644 index 0000000..10bc301 --- /dev/null +++ b/docs/source/changelog/index.rst @@ -0,0 +1,3 @@ + +.. include:: ../../../CHANGELOG.md + :parser: myst_parser.sphinx_ \ No newline at end of file diff --git a/docs/source/conf.py b/docs/source/conf.py index a23014e..c472408 100644 --- a/docs/source/conf.py +++ b/docs/source/conf.py @@ -37,11 +37,12 @@ # extensions coming with Sphinx (named 'sphinx.ext.*') or your custom # ones. extensions = [ + "matplotlib.sphinxext.plot_directive", + "myst_parser", "sphinx.ext.autodoc", "sphinx.ext.autosummary", "sphinx.ext.githubpages", # Helpful for publishing to gh-pages "sphinx.ext.napoleon", - "matplotlib.sphinxext.plot_directive", "sphinx_gallery.gen_gallery", ] diff --git a/docs/source/index.rst b/docs/source/index.rst index 07502dd..7103a9d 100644 --- a/docs/source/index.rst +++ b/docs/source/index.rst @@ -1,24 +1,11 @@ - -Pymsis (|version|) -================== - -This is a lightweight Python wrapper around the MSIS00 and MSIS2 Fortran source code. -The `MSIS model `_ is -developed by the Naval Research Laboratory. For quick access to the model data without any code, -there is a web viewer that uses pymsis: ``_. - -The :ref:`examples` are a good reference for quickly getting started with the Python code and demonstrate -how to call the models and plot the results. The explicit interfaces are described in the :ref:`api`. +.. include:: ../../README.md + :parser: myst_parser.sphinx_ .. toctree:: :maxdepth: 1 + :hidden: examples/index reference/index development/index - -If you make use of pymsis, please consider citing it in your research. -|Zenodo|_ - -.. |Zenodo| image:: https://zenodo.org/badge/298114805.svg -.. _Zenodo: https://zenodo.org/badge/latestdoi/298114805 + changelog/index diff --git a/pyproject.toml b/pyproject.toml index 1b931fc..251af1e 100644 --- a/pyproject.toml +++ b/pyproject.toml @@ -35,18 +35,19 @@ requires-python = ">=3.10" dependencies = ["numpy>=1.23"] [project.optional-dependencies] -tests = [ +test = [ "pytest", "pytest-cov", ] -docs = [ +doc = [ "matplotlib", + "myst-parser", "sphinx", "sphinx_gallery", "pydata-sphinx-theme", ] dev = [ - "pymsis[tests,docs]", + "pymsis[doc,test]", "mypy", "pre-commit", "ruff",