Geliosphere is application that utilize GPU as a computing unit for cosmic ray modulation in Heliosphere. Contains 1D models of cosmic ray modulation in heliosphere 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
<details> 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|1D Bp|2D SolarProp-like|2D Geliosphere) |
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
<details>
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
</details>
Module structure
<details>
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. </details>
Source file description
<details>
Geliosphere module
<details>
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.
</details>
Algorithm module
<details>
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.
</details>
Factory module
<details>
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.
</details>
Input module
<details>
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.
</details>
CPU Implementations module
<details>
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.
</details>
CUDA Kernel module
<details>
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.
</details>
Utils module
<details>
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.
</details>
Visualization
<details>
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.
</details>
</details>