(EUV imagery of the solar disk, taken by NASA SDO)

Overview

EUVpy is a Python module that contains the NEUVAC empirical model of solar EUV irradiance for use primarily in thermosphere-ionosphere models. Conceptual development was carried out by Dr. Aaron J. Ridley and analysis and contributions were made by Dr. Daniel A. Brandt and Dr. Joseph Paki.

EUVpy also contains code for running, comparing, and analyzing the performance of NEUVAC in comparison to other empirical models such as EUVAC, HEUVAC, HFG, and FISM2. As such, the package includes access to EUVAC, HEUVAC, and HFG, and allows the user to download the F10.7 index at will.

Installation

You can obtain EUVpy with a simple git clone command. In the terminal, execute the following command:

git clone https://github.com/DanBrandt/EUVpy.git

The EUVpy package provides access to the HEUVAC model, which is written in Fortran and requires gfortran to be installed. To install gfortran (if you don't already have it), open a terminal and execute the following command:

sudo apt-get install gfortran

Now, enter into the package folder and run the following command in order to compile the Fortran code that HEUVAC alone depends upon:

cd EUVpy
. install_heuvac.sh

If this step gives you trouble, try executing the following code first, and then retry the above commands.

git submodule update --init --recursive --remote

After HEUVAC is compiled once, you should never have to compile it again.

Now you are in a position to install the rest of the EUVpy package. Before doing this, you will first want to initialize a Python virtual environment.

cd ~/.virtualenvs
python3.x -m venv myVenv
pip install --upgrade pip
pip install wheel
source myVenv/bin/activate

Above, 'python3.x' refers to whatever version of Python 3 you have installed. EUVpy works with any version of Python 3. You may now use one of two ways to install EUVpy. You can install from the cloned repo directly, or you can install from PyPI.

Installing from the Cloned Repository

Navigate back to the package folder:

cd
cd myDirectory/EUVpy

After this is done, simply execute the following command:

pip install .

Installing from PyPI

A simpler way to install also involves just entering the following in the terminal:

pip install EUVpy

Note: If you choose this route, you'll have to install HEUVAC differently than described above. You will have to navigate the directory containing the HEUVAC files, and execute the following command, as follows:

cd src/EUVpy/empiricalModels/models/HEUVAC/srcHEUVAC . compile.sh

You can then return to the top package directory. This should only have to be done once. This approach will be replaced with a user-friendly console script in the next release of this package.

Unit Testing

Note: this section only applies if you installed from the cloned repo.

Just to make sure everything installed correctly, while in the package folder, run the following command in the terminal.

pytest

If all of the tests pass, you should be good to go! If you find an issue at this step (or any other) please don't hesitate to reach out!

Usage

EUVpy contains modules for 4 different EUV irradiance models. These models include:

• NEUVAC
• EUVAC
• HEUVAC
• HFG (SOLOMON)

We note that SOLOMON in the literature can either refer to the empirical model between F10.7 and 81 day-averaged F10.7 centered on the current day (hereafter F10.7A) and EUV irradiance in 22 overlapping bands as described by Solomon and Qian 2005, or it can refer to any EUV irradiance data summed into those 22 overlapping bins (referred to as the STAN BANDS). In this package, SOLOMON only refers to the former, though functionality does exist to run all other models in the STAN BANDS.

Finding your way around

There are few folders in this package:

• empiricalModels: Contains code and data for EUVAC, HEUVAC, and SOLOMON, as well as FISM:
• experiments: Contains code and figures related to the publication associated with NEUVAC. In this folder, the file fitNeuvac.py s used for actually performing the NEUVAC fits between F10.7, F10.7A, and FISM2, while uncNeuvac.py contains code for computing the correlation matrix used to enable running NEUVAC ensembles, as well as generating plots of the squared difference between NEUVAC and FISM2 in different bands.
• NEUVAC: Contains the code for running NEUVAC.
• solarIndices: Contains F10.7 solar index data, from both OMNIWeb and Penticton.
• tools: Contains code for miscellaneous helper functions. In this folder appears the following:
  • EUV: Contains numerous functions within fism2_process.py for reading in and rebinning FISM2 data.
  • processIndices.py: Contains functions for reading in, downloading, and cleaning OMNIWeb data.
  • processIrradiances.py: Contains functions for reading in data from TIMED/SEE, SDO/EVE, and FISM.
  • spectralAnalysis.py: Contains functions for converting between solar spectral irradiance and solar spectral flux.
  • toolbox.py: Contains miscellaneous helper functions that mainly focus on directory management, loading and saving data, statistics, and fitting.

Each of the models in EUVpy requires F10.7 as an input. To grab F10.7 between any two dates, simply do the following:

from EUVpy.tools import processIndices

f107times, f107, f107a, f107b = processIndices.getCLSF107('YYYY-MM-DD', 'YYYY-MM-DD', truncate=False)

To import any of the models, simply do as follows:

NEUVAC

from EUVpy.NEUVAC import neuvac

neuvacIrr, _, _, _ = neuvac.neuvacEUV(f107, f107b, bands='EUVAC')

EUVAC

from EUVpy.empiricalModels.models.EUVAC import euvac

euvacFlux, euvacIrr, _, _, _ = euvac.euvac(f107, f107a)

HEUVAC

from EUVpy.empiricalModels.models.HEUVAC import heuvac

heuvac_wav, heuvacFlux, heuvacIrr, _, _, _ = heuvac.heuvac(f107, f107a, torr=True)

SOLOMON

from EUVpy.empiricalModels.models.SOLOMON import solomon

solomonFluxHFG, solomonIrrHFG = SOLOMON.solomon.solomon(f107, f107a, model='HFG')

solomonFluxEUVAC, solomonIrrEUVAC = SOLOMON.solomon.solomon(f107, f107a, model='EUVAC')

Examples

There is a Python notebook you can walk through in order to get familiar with the basic functionality of EUVpy.

We encourage you to peruse more examples in the documentation for guidelines on how to run each of the models.

Due to the unique construction of NEUVAC, at present, we only recommend running ensembles for NEUVAC, and not any of the other models.

Code of Conduct

In using this code, depending on the module used, proper citations should be given to the original authors responsible for developing each model or dataset:

NEUVAC: Brandt and Ridley, 2024

EUVAC: Richards, et al. 1994

HEUVAC Richards, et al. 2006

SOLOMON Solomon and Qian, 2005

FISM2: Chamberlin, et al. 2020