NRLMSIS-2.1 Python Wrapper

msis21py is a wrapper around the NRLMSIS-2.1 empirical model.

This repository uses the NRLMSIS-2.1 model as is with Python. The integration is achieved by means of a FORTRAN shim (msis21shim.f90) that is compiled into a module using F2PY. The parameter file msis21.parm is automatically provided at runtime.

Prerequisites

A Fortran compiler is REQUIRED.

Linux

Ensure that you have the following development packages installed:

• build-essential (for gcc, g++, make, etc.)
• gfortran (Fortran compiler)

macOS

Ensure that you have the Xcode Command Line Tools installed. You can install them by running:

xcode-select --install

Install homebrew if you haven't already, and then install gfortran:

brew install gfortran

Note: For macOS Big Sur and above, you may need to add the following line to your environment script (~/.zshrc if using ZSH, or the relevant shell init script):

export LIBRARY_PATH="$LIBRARY_PATH:/Library/Developer/CommandLineTools/SDKs/MacOSX.sdk/usr/lib"

Then reopen the terminal. This fixes the issue where -lSystem fails for gfortran.

Windows (amd64 or x86_64 targets)

On Windows, MSYS2 is the preferred distribution for installing the Fortran compiler toolchain (for GNU Compiler Collection).

• Install MSYS2. Note the directory where MSYS2 was installed (defaults to C:\msys64) [referred to as MSYS_INSTALL_DIR]. It is not recommended to change this directory.
• Launch the MSYS2 terminal (MSYS2 MSYS application on the start menu)
• Update MSYS2 environment (assuming fresh install):

  pacman -Syu # Restart the terminal
  pacman -Su  # Update packages
  

• Install the GNU Compiler Collection:

  pacman -S --needed base-devel mingw-w64-ucrt-x86_64-toolchain mingw-w64-ucrt-x86_64-gcc-fortran
  

• Add MSYS_INSTALL_DIR\ucrt64\bin (defaults to C:\msys64\ucrt64\bin) to PATH:
  • Search for env in the Start menu,
  • Select "Edit the system environment variables",
  • Click "Environment Variables",
  • Double click 'Path' under 'User variables for USER'
  • Click "New"
  • Type in, or paste the full path to ucrt64\bin (defaults to C:\msys64\ucrt64\bin)
  • Click "Ok" on the environment variable windows to save the changes.
• Continue with installation instructions for the Python packages below, in a new, regular terminal (e.g. Command Prompt or PowerShell with Python installed).

[!NOTE] Change the toolchain names accordingly for Windows arm64. This platform has not been tested and is not officially supported.

Installation

From PyPI

pip install msis21py

From GitHub

pip install msis21py@git+https://github.com/sunipkm/msis21py

Usage

Quick Test

On the command line, execute Msis21Test. This should produce a plot of noon and midnight neutral temperature profiles.

Python

from msis21py import NrlMsis21, alt_grid
from datetime import datetime, UTC
import matplotlib.pyplot as plt

# Instantiate the model
msis = NrlMsis21()
# Note: msis is a singleton (thread safety with FORTRAN)
# Evaluate the model
ds = msis.evaluate(
    datetime(2022, 3, 12, 0, 0, 0, tzinfo=UTC),
    40, -70,
    alt_grid()
)

# ds is an xarray Dataset
# Plot neutral temperature profile
ds.Tn.plot(y='alt_km')
plt.show()

Output Dataset Format

• Coordinates
  • Altitude (alt_km): Altitude in km
• Data Variables (as a function of altitude)
  • Densities of O, O₂, N₂, H, He, Ar, N, Anomalous O, and NO in cm^-3
  • Neutral temperature (Tn) in K
  • Mass density (mden) in g cm^-3
• Attributes
  • settings: JSON string of settings (msis21py.Settings) used to evaluate the model.
  • date: ISO formatted date and time for which the model was evaluated.
  • lat and lon: Latitude and longitude for where the model was evaluated.
  • Additional attributes are provided as JSON dictionaries containing a value, its unit, a longer name (long_name) and an associated description, if available.

The dataset is NetCDF4 compatible.

Examples

An example script to generate the following plot is available in the in tests/test_msis21.py.

License

This project is licensed under the MIT License. See the LICENSE file for details. The NRLMSIS-2.1 model is in the public domain as per the original license, and is a product of the U.S. Government that is restricted to academic and research use only. Please refer to the original license for more details. Please follow the citation guidelines provided by NRL when using the model in your work.

Citation

If you use this code in your work, please cite the repository:

@software{sunipkm_msis21py_2025,
  author       = {Sunip K. Mukherjee},
  title        = {{msis21py}: A Python Wrapper for the NRLMSIS-2.1 Empirical Model},
  month        = nov,
  year         = 2025,
  publisher    = {GitHub},
  version      = {v0.0.2},
  doi          = {https://zenodo.org/badge/latestdoi/1090668363},
  url          = {https://github.com/sunipkm/msis21py},
}