Geliosphere

Geliosphere is application that utilize GPU as a computing unit for cosmic ray modulation in Heliosphere. Beside GPU-based models, it also contains parallel CPU implementations for all models. Geliosphere contains 2D, and 1D models of cosmic ray modulation in heliosphere. Information about 2D Geliosphere model, with its description can be found in this paper.. 1D models are based on this paper..

Class documentation can be found here.

Parameter	Value	Description
-F	-	Run forward-in-time simulation
-B	-	Run backward-in-time simulation
-E	-	Run SOLARPROPLike 2D backward-in-time simulation
-T	-	Run Geliosphere 2D backward-in-time simulation
-c	-	Set .csv output
--cpu-only	-	Simulation will be executed on CPU.
--evaluation	string	Run only evaluation
-h	-	Print help for Geliosphere
-d	float	Set time step (default value 5.0s)
-K	float	Set K0 (default value 5∗10^22cm2/s)
-V	float	Set solar wind speed (default value 400 km/s)
-p	string	Set custom path for output in output directory
-N	int	Set number of test particles in millions
-m	int	Load K0 and V for given month from table based on Usoskin’s tables for 1D, and K0 and tilt angle for 2D
-y	int	Load K0 and V for given year from table based on Usoskin’s tables for 1D, and K0 and tilt angle for 2D
-s	string	Set path to settings toml file (default Settings.tml in root folder)
-b	string	Run simulations in batch according to defined input values in input csv file
--custom-model	string	Run custom user-implemented model

All GPUs from Nvidia Pascal, Amphere, Volta and Turing architectures are supported.

Additional information about used models can be found in following articles:

Accuracy and comparasion results from GPU implementation to Crank-Nicolson model

Batch mode

Since version 1.2.0 we support batch processing of simulations. Batch mode requires CSV file as input with following structure: ``` year,month,K0,V,dt,N,r,theta,pathToCustomSettingsFile,name,model ```

Name	Description
year	Load K0 and V for given year from table based on Usoskin’s tables for 1D, and K0 and tilt angle for 2D
month	Load K0 and V for given month from table based on Usoskin’s tables for 1D, and K0 and tilt angle for 2D
K0	Set K0
V	Set solar wind speed
dt	Set time step
N	Set number of test particles in millions
r	Set default value of r injection used in Geliosphere in AU
theta	Set default value of theta injection used in Geliosphere in degrees
pathToCustomSettingsFile	Path to settings file, which content will be used in simulation.
name	Name of the simulation, which is used as folder name for directory containing output files. Name is optional, but have to be unique in input file.
model	Name of the model (Valid values are: 1D Fp

Injection of r and theta are not regular input parameters via CLI. Their values can be modified in settings file. To keep possible conflicts within input file, r and theta injections, we decided to generate new settings file based on default settings with updating r and theta injection values.

Input validation conditions are same as for input from CLI, validation will fail on following conditions:

• Input file does not contain unique names - there are duplicates of names in input file,
• Both month and year are not set at once - only one of them is set,
• Input file contains unsupported model,
• Both K0, V and year with month cannot be selected at once.

Following snipet contains example of input CSV file:

year,month,K0,V,dt,N,r,theta,pathToCustomSettingsFile,name,model
1990,11,,,100,2,1.1861,88.34,,1,2D Geliosphere
1990,12,,,100,2,1.446,88.05,,2,2D Geliosphere
1991,1,,,100,2,1.7398,88.01,,,2D Geliosphere
,,5E+022,400,500,100,,,,Test,1D Fp

Installation

Geliosphere with GPU support

Standard installation of the GPU version of Geliosphere requires installation of the Nvidia toolkit, g++ and cmake 3.14+. These packages can be installed via any packaging tool. The following example is provided for the apt-get packaging tool:

sudo apt-get install cuda g++ cmake

Different Linux distributions may have different approach for CUDA installation.

After installation is complete, an optimized version of the tool can be built via the following command:

cmake -B build -DCMAKE_BUILD_TYPE=Release
cmake --build build

After build is complete successfully, executable is placed in build directory with Geliosphere. For further instruction regarding the program usage, following command will display help for the user:

./build/Geliosphere --help

Geliosphere with CPU-only support

The packages are similar, with the exception that the CPU version naturally does not require installation of the Nvidia toolkit. CPU-only version of Geliosphere can be built via the following command:

cmake -B build -DCMAKE_BUILD_TYPE=Release -DCPU_VERSION_ONLY=1
cmake --build build

Dockerized versions

We also included runner scripts(runner.sh and runner_cpu_only.sh), that can build and run Geliosphere in Docker. They automatically build Docker image, however it can re-built via:

./runner.sh -f
./runner_cpu_only.sh -f

Help for Geliosphere can be displayed via following command:

./runner.sh --help
./runner_cpu_only.sh --help

Module structure

Following image describes relations between modules in Geliosphere:

Modules are used to organize the logic needed for simulations in the heliosphere and to support logic for them. These modules are described as follows:

• Geliosphere - contains the main function and links basic logic for selecting the model, parsing input data and running the selected model,
• Algorithm - contains logic used for selecting implementation of model for selected computing unit, and logic for analyzing output spectra,
• Factory - contains classes based on factory and abstract factory patterns used for creating objects,
• Input - contains classes used for parsing input data,
• CPU Implementations - contains classes used for running parallel CPU implementations of models of cosmic rays modulation in the heliosphere,
• CUDA Kernel - contains classes used for running parallel GPU implementations of models of cosmic rays modulation in the heliosphere,
• Utils - contains classes holding various functions used in Geliosphere.

Additionally we added python scripts to replicate figure comparing results from Geliosphere 2D model and Ulysses.

• Visualization - contains scripts needed for visualization.

Source file description

Geliosphere module

Geliosphere
|
│    Dockerfile
|    Dockerfile.CPU  
|    main.cpp
└───Algorithm
└───Constants
└───CpuImplementations
└───CUDAKernel
└───Factory
└───Utils
└───Visualization

Geliosphere module contains following source files:

• Dockerfile - file containing defitinion for building GPU Docker image with GPU support.
• Dockerfile.CPU - file containing defitinion for building GPU Docker image with CPU-only support.
• main.cpp - file containing main functions with needed iteractions between modules.

Algorithm module

Algorithm
│    
└───include
|   |   AbstractAlgorithm.hpp
|   |   BatchRun.hpp
|   |   OneDimensionBpAlgorithm.hpp
|   |   OneDimensionBpResults.hpp
|   |   OneDimensionFpAlgorithm.hpp
|   |   OneDimensionFpResults.hpp
|   |   ResultConstants.hpp
|   |   GeliosphereAlgorithm.hpp
|   |   SolarPropLikeAlgorithm.hpp
|   |   TwoDimensionBpResults.hpp
└───src
    |   AbstractAlgorithm.cpp
    |   BatchRun.cpp
    |   OneDimensionBpAlgorithm.cpp
    |   OneDimensionBpResults.cpp
    |   OneDimensionFpAlgorithm.cpp
    |   OneDimensionFpResults.cpp
    |   GeliosphereAlgorithm.cpp
    |   SolarPropLikeAlgorithm.cpp
    |   TwoDimensionBpResults.cpp

Algorithm module contains following source files:

• AbstractAlgorithm.hpp - Header file of abstract definition for algorithm.

• BatchRun.hpp - Header file of implementation of batch run mode.

• OneDimensionBpAlgorithm.hpp - Header file of implementation of 1D B-p model

• OneDimensionBpResults.hpp - Header file of implementation of 1D B-p model analyzer for output data.

• OneDimensionFpAlgorithm.hpp - Header file of implementation of 1D F-p model

• OneDimensionFpResults.hpp - Header file of implementation of 1D F-p model analyzer for output data.

• ResultConstants.hpp - Header file containing constants needed for analysis of log files for all models.

• GeliosphereAlgorithm.hpp - Header file of implementation of Geliosphere 2D B-p model.

• SolarPropLikeAlgorithm.hpp - Header file of implementation of SolarProp-like 2D B-p model.

• TwoDimensionBpResults.hpp - Header file of implementation of 2D B-p model analyzer for output data.

• AbstractAlgorithm.cpp - Source file of abstract definition for algorithm.

• BatchRun.cpp - Source file of implementation of batch run mode.

• OneDimensionBpAlgorithm.cpp - Source file of implementation of 1D B-p model.

• OneDimensionBpResults.cpp - Source file of implementation of 1D B-p model analyzer for output data.

• OneDimensionFpAlgorithm.cpp - Source file of implementation of 1D F-p model.

• OneDimensionFpResults.cpp - Source file of implementation of 1D F-p model analyzer for output data.

• GeliosphereAlgorithm.cpp - Source file of implementation of Geliosphere 2D B-p model.

• SolarPropLikeAlgorithm.cpp - Source file of implementation of SolarProp-like 2D B-p model.

• TwoDimensionBpResults.cpp - Source file of implementation of 2D B-p model analyzer for output data.

Factory module

Factory
│    
└───include
|   |   AbstractAlgorithmFactory.hpp
|   |   CosmicFactory.hpp
└───src
    |   AbstractAlgorithmFactory.cpp
    |   CosmicFactory.cpp

Factory module contains following source files:

• AbstractAlgorithmFactory.hpp - Interface of Abstract Factory Pattern.

• CosmicFactory.hpp - Class represents implementation of Factory Pattern for cosmic algorithms.

• AbstractAlgorithmFactory.cpp - Source file for interface of Abstract Factory Pattern.

• CosmicFactory.cpp - Source file of class represents implementation of Factory Pattern for cosmic algorithms.

Input module

Input
│    
└───include
|   |   InputValidation.hpp
|   |   MeasureValuesTransformation.hpp
|   |   ParamsCarrier.hpp
|   |   ParseParams.hpp
|   |   TomlSettings.hpp
└───src
    |   InputValidation.cpp
    |   MeasureValuesTransformation.cpp
    |   ParamsCarrier.cpp
    |   ParseParams.cpp
    |   TomlSettings.cpp

Input module contains following source files:

• InputValidation.hpp - Header file for class representing validation of input into Geliosphere.

• MeasureValuesTransformation.hpp - Header file for class representing extraction of measured parameters for simulation from table.

• ParamsCarrier.hpp - Header file for universal map-like structure.

• ParseParams.hpp - Header file of parser of arguments from CLI

• TomlSettings.hpp - Header file for class representing parser of values from settings.

• InputValidation.cpp - Source file for class representing validation of input into Geliosphere.

• MeasureValuesTransformation.cpp - Source file for class representing extraction of measured parameters for simulation from table.

• ParamsCarrier.cpp - Source file for universal map-like structure.

• ParseParams.cpp - Source file of parser of arguments from CLI

• TomlSettings.cpp - Source file for class representing parser of values from settings.

CPU Implementations module

CpuImplementations
│    
└───include
|   |   AbstractCpuModel.hpp
|   |   Constants.hpp
|   |   OneDimensionBpCpuModel.hpp
|   |   OneDimensionFpCpuModel.hpp
|   |   GeliosphereCpuModel.hpp
|   |   SolarPropLikeCpuModel.hpp
└───src
    |   OneDimensionBpCpuModel.cpp
    |   OneDimensionFpCpuModel.cpp
    |   GeliosphereCpuModel.cpp
    |   SolarPropLikeCpuModel.cpp

CPU Implementations module contains following source files:

• AbstractCpuModel.hpp - Abstract definition for implementation of model on CPU.

• Constants.hpp - Header file for constants for CPU implementations.

• OneDimensionBpCpuModel.hpp - Header file for CPU implementation for 1D B-p model.

• OneDimensionFpCpuModel.hpp - Header file for CPU implementation for 1D F-p model.

• GeliosphereCpuModel.hpp - Header file for CPU implementation for Geliosphere 2D B-p model.

• SolarPropLikeCpuModel.hpp - Header file for CPU implementation for SolarProp-like 2D B-p model.

• OneDimensionBpCpuModel.cpp - Source file for CPU implementation for 1D B-p model.

• OneDimensionFpCpuModel.cpp - Source file for CPU implementation for 1D F-p model.

• GeliosphereCpuModel.cpp - Source file for CPU implementation for Geliosphere 2D B-p model.

• SolarPropLikeCpuModel.cpp - Source file for CPU implementation for SolarProp-like 2D B-p model.

CUDA Kernel module

CUDAKernel
│    
└───include
|   |   AbstractGpuSimulation.hpp
|   |   CosmicConstants.cuh
|   |   CosmicUtils.cuh
|   |   CudaErrorCheck.cuh
|   |   OneDimensionBpGpuModel.hpp
|   |   OneDimensionBpModel.cuh
|   |   OneDimensionFpGpuModel.hpp
|   |   OneDimensionFpModel.cuh
|   |   GeliosphereGpuModel.hpp
|   |   GeliosphereModel.cuh
|   |   SolarPropLikeGpuModel.hpp
|   |   SolarPropLikeModel.cuh
└───src
    |   CosmicConstants.cu
    |   CosmicUtils.cu
    |   OneDimensionBpGpuModel.cpp
    |   OneDimensionBpModel.cu
    |   OneDimensionFpGpuModel.cpp
    |   OneDimensionFpModel.cu
    |   GeliosphereGpuModel.cpp
    |   GeliosphereModel.cu
    |   SolarPropLikeGpuModel.cpp
    |   SolarPropLikeModel.cu

CUDA Kernel module contains following source files:

• AbstractGpuSimulation.hpp - Abstract definition for implementation of model on GPU.

• CosmicConstants.cuh - Header file for constants needed for simulations.

• CosmicUtils.cuh - Header file for common functions for simulations.

• CudaErrorCheck.cuh - Header file for utilities for checking errors.

• OneDimensionBpGpuModel.hpp - Header file for class utilizing GPU implementation of 1D B-p model.

• OneDimensionBpModel.cuh - Header file for GPU implementation of 1D B-p model.

• OneDimensionFpGpuModel.hpp - Header file for class utilizing GPU implementation of 1D F-p model.

• OneDimensionFpModel.cuh - Header file for GPU implementation of 1D F-p model.

• GeliosphereGpuModel.hpp - Header file for class utilizing GPU implementation of Geliosphere 2D B-p model.

• GeliosphereGpuModel.cuh - Header file for GPU implementation of Geliosphere 2D B-p model.

• SolarPropLikeGpuModel.hpp - Header file for class utilizing GPU implementation of SolarProp-like 2D B-p model.

• SolarPropLikeModel.cuh - Header file for GPU implementation of SolarProp-like 2D B-p model.

• CosmicConstants.cu - Source file for constants needed for simulations.

• CosmicUtils.cu - Source file for common functions for simulations.

• OneDimensionBpGpuModel.cpp - Source file for class utilizing GPU implementation of 1D B-p model.

• OneDimensionBpModel.cu - Source file for GPU implementation of 1D B-p model.

• OneDimensionFpGpuModel.cpp - Source file for class utilizing GPU implementation of 1D F-p model.

• OneDimensionFpModel.cu - Source file for GPU implementation of 1D F-p model.

• GeliosphereGpuModel.cpp - Source file for class utilizing GPU implementation of Geliosphere 2D B-p model.

• GeliosphereGpuModel.cu - Source file for GPU implementation of Geliosphere 2D B-p model.

• SolarPropLikeGpuModel.cpp - Source file for class utilizing GPU implementation of SolarProp-like 2D B-p model.

• SolarPropLikeModel.cu - Source file for GPU implementation of SolarProp-like 2D B-p model.

Utils module

Utils
│    
└───include
|   |   FileUtils.hpp
|   |   ResultsUtils.hpp
└───src
    |   FileUtils.cpp
    |   ResultsUtils.cpp

Utils module contains following source files:

• FileUtils.hpp - Header file for utilities for manipulating with directories.
• ResultsUtils.hpp - Header file for utilities for analyting log files.
• FileUtils.cpp - Source file for utilities for manipulating with directories.
• ResultsUtils.cpp - Source file for utilities for analyting log files.

Visualization

Visualization
│    
└───batch_run_geliosphere.py
└───create_plot.py
└───create_ulysses_Geliosphere_flux.py
└───prepare_input_based_on_ulysses.py
└───prepare_spectra.py

Visualization directory contains following scripts:

• batch_run_geliosphere.py - script used to batch run of Geliosphere.
• create_plot.py - script responsible for visualizing Ulysses and Geliosphere energetic spectra.
• create_ulysses_Geliosphere_flux.py - script used to replicate figure comparing Ulysses trajectory and Geliosphere 2D model results between 1994 and 1998.
• prepare_input_based_on_ulysses.py - script used to prepare input for visualization script from Ulysses trajectory data.
• prepare_spectra.py - process spectra from Geliosphere for further visualization.