This project (cr-geomag-prop) demonstrates a tool to visualize charge particle propagation through the Earth's magnetic field using PyOpenCL and PyOpenGL. The following link shows a demonstration of this project's visualization of GeV proton particles interacting with the geomagnetic field, while below is a screenshot from this simulation.

To check-out the repo:

git clone https://github.com/zhampel/cr-geomag-prop.git

The Earth texture was obtained freely at the Planetary Pixel Emporium.

There are two available models for estimating the geomagnetic field. The first is the dipole approximation, where the axis of the field is tilted by 11.5 deg from the Earth's axis of rotation. The second is the International Geomagnetic Reference Field (IGRF), a best fit model to satellite borne and ground based sensor measurements using a 13-order expansion of Legendre functions.

The two figures below show isoclinic diagrams of these two models, the dipole being on the left, the IGRF on the right, where deviation of IGRF from the symmetric dipole approximation is clearly visible. These diagrams were generated using the following MATLAB package.

Links showing short video demos of propagating protons in these fields are provided for the IGRF model as well as the dipole approximation.

Upon installation of required dependencies, one simply needs to run

python crprop/run.py -p proton -n 1000 -e 1e7 1e8 --lat_lon_alt 18.99 -97.308 3 -s boris

to start the simulation, where -p defines the species to run, the number of particles to simulate is given by -n, and the minimum and maximum particle energy in electronvolts (eV) are provided as a list via -e. The --lat_lon_alt flag allows the user to specify the particles's starting latitude and longitude in degrees, and the height above the Earth's surface in Earth radii. Finally, the -s option allows the user to choose the equation of motion integrator. The values shown in the line above are the defaults, thus users can do a first run simply via python crprop/run.py. Users can also use a YAML config file to input all options and run via

python crprop/run.py -c config.yml

with a default configuration file provided in the crprops directory.

Once the window opens, one can also use various mouse operations to change the scene. Holding the left mouse button allows the user to move the viewing position, while holding down the right mouse button and moving up and down on the screen provides a zooming operation. The center mouse button provides translation of the origin about the screen.

The colors of the particles are representative of their energy, and are correlated per the respective wavelengths. Red corresponds to the lowest energies, while violet represents the highest values. The color-to-energy scaling is log-linear, thus color wavelength is proportional to the logarithm of the particle energy.

There are several available user options when running the simulation:

• p key or spacebar: start/pause the propagation
• r key: start/stop the rotation of the perspective
• s key: save the frames to png files
• t key: toggle between a textured Earth and a simple sphere
• q or Esc keys: quit the simulation

A BASH script named crprop/make_mp4.sh is provided to generate an mp4 movie if saved frames are present in the frames directory. One must have ffmpeg installed on the system to make the movie.

I've successfully run using Python2.7 and on Python3.7.5. The installation of PyOpenCL and PyOpenGL potentially can be a bit tricky depending on the platform, but on my Linux machines, I've had success via make install or pip install -r requirements.txt.

On my MacBook Pro, I've instead been able to get things running via the following steps:

• Ensure Python3 accessible, e.g. in /usr/local/bin/python3
• brew install freeglut
• Start a new virtual-env: virtualenv -p /usr/local/bin/python3 venv
• pip install setuptools numpy pygame Pillow astropy pyyaml pybind11
• Download PyOpenGL and PyOpenGL-accelerate from here
• Untar each, then python setup.py install PyOpenGL, then PyOpenGL-accelerate
• You can test the PyOpenGL installation with the PyOpenGL-Demo package, also found at the PyOpenGL site
• Download PyOpenCL from here, for example
• Build with specific Python paths and gl-interoperability (though I have found =paths unnecessary to specify explicitly...):
  ./configure.py --python-exe=PATH_TO_PYTHON_EXE --prefix=PATH_TO_PREFIX --enable-shared --cl-enable-gl
• make && make install

To test the installation, one can the PyOpenCL particle example script

One can also go to Andreas Kloeckner's site for even more details regarding PyOpenCL installation and documentation.

The installation of PyOpenCL and PyOpenGL potentially can be a bit tricky depending on the platform, but may be done via make install or pip install -r requirements.txt. If this doesn't work, the best resource for preparing the PyOpenCL installation can be found at Andreas Klockner's website. I have had success with building PyOpenGL from source, but in principle can be done via pip as shown here. Otherwise, NumPy, Pillow, and PyGame are the remaining requirements for cr-geomag-prop.