Getting started

psipy is a package for loading and visualising the output of PSI’s MAS model runs. This page provides some narrative documentation that should get you up and running with obtaining, loading, and visualising some model results.

Getting data

The PSI MHDWeb pages give access to MAS model runs. The runs are indexed by Carrington rotation, and for each Carrington rotation there are generally a number of different runs, varying in the type model run and/or the boundary conditions.

To load data with psipy you need to manually download the files you are interested in to a directory on your computer.

MAS and PLUTO data

psipy supports data from both MAS model runs and PLUTO model runs. For simplicity the instructions in this guide are written with MAS model output in mind. Everything works the same way for PLUTO model output though - just load the files with the PLUTOOutput class instead of the MASOutput class. We are striving for feature parity so that the same capabilities are available for both the MAS and PLUTO output. As of version 0.4, field line tracing should now work for PLUTO as well as MAS files.

Loading data

psipy stores the output variables from a single MAS run in the MASOutput object. To create one of these, specify the directory which has all of the output .hdf files you want to load:

from psipy.model import MASOutput

directory = '/path/to/files'
mas_output = MASOutput(directory)

It is assumed that the files have the filename structure '{var}{timestep}.hdf', where var is a variable name, and timestep is a three-digit or six-digit zero-padded integer timestep.

If you encounter errors when following these examples, it may be that you have added (or there exists) a file to the MAS/PLUTO directory that is mimicking a variable file, but is, in fact something else, and PsiPy is confused about it.

To see which variables have been loaded, you can look at the .variables attribute:

print(mas_output.variables)

This will print a list of the variables that have been loaded. Each individual variable can then be accessed with square brackets, for example, to get the radial magnetic field component:

br = mas_output['br']

This will return a Variable object, which stores the underlying data as a xarray.DataArray under the Variable.data property.

Data coordinates

The data stored in Variable.data contains the values of the data as a normal array, and in addition, stores the coordinates of each data point.

MAS model outputs are defined on a 3D grid of points on a spherical grid. The coordinate names are 'r', 'theta', 'phi'. The coordinate values along each dimension can be accessed using the r_coords, theta_coords, phi_coords properties, e.g.:

rvals = br.r_coords

Sampling data

Variable objects have a Variable.sample_at_coords method to take a sample of the 3D data cube along a 1D trajectory. This is helpful for flying a ‘virtual spacecraft’ through the model and comparing the model results with in-situ measurements.

sample_at_coords requires arrays of longitude, latitude, and radial distance. Given these coordinates, it uses linear interpolation to extract the values of the variable at each of the coordinate points.

For an example of how all this works, see Comparing in-situ data to model output.