C++ interface for the [HelMod](http://helmod.org) offline calculator.

See upper stream pages [History and Citation](http://www.helmod.org/index.php/history-and-citation) and [Bibliography](http://www.helmod.org/index.php/publications).

## Instruction

### 1. Prepare modulation data archive

In order to use this C++ library to calculate solar modulation of cosmic rays (CR), modulation archive must be provided. The archive stores time dependent matrices that are used to transform a local interstellar CR spectrum (LIS) into modulated spectrum at the top of atmosphere (TOA).

This library reads a reorganized version of such archive which is more disk-friendly than the official one. You can [download the latest archive here](https://cloud.itp.ac.cn/d/2927e56f3364406c87b5/).
Note that the archives with suffix `-lite` only provide modulation
data for lighter isotopes (Z < 9) during a shorter time range (2000-2030).

Let's say the tarball `helmod_data-4.2.0.tar.xz` has been download and is stored in the current working directory. As an example, to extract the archive file into `/usr/local/share/`, execute

```sh
$ sudo mkdir -pv /usr/local/share
$ sudo tar -xJvf ./helmod_data-4.2.0.tar.xz -C /usr/local/share

```

A directory containing all the modulation matrices will be created as `/usr/local/share/helmod_data-4.2.0/`.  It's recommended to create a symbolic link as an entry point that later provided to the library.

```sh
$ sudo ln -sv helmod_data-4.2.0 /usr/local/share/helmod_data
$ # check the link
$ ls -ld /usr/local/share/helmod_data*

```

### 2. Compile the library

This library is built using `cmake`. Make sure it's presented on your computer.

Clone this project using git, or download and decompress the source package. After changing your working directory into the project root directory (containing the README you currently reading), create a new directory to build inside.

```sh
$ mkdir build
$ cd build
$ cmake .. -DHELMOD_DATA_PATH=/usr/local/share/helmod_data

```

Note that without specifying `CMAKE_INSTALL_PREFIX`, the library will later be installed to `/usr/local`.

If the cmake command terminated successfully, you can now build and test the library.

```sh
$ make
$ make test

```

Note that the test won't pass if `HELMOD_DATA_PATH` was not provided during `cmake`. In that case you can still use the library by specifically pass the archive path as function argument at runtime.

Now it's time to install the library into the system.

```sh
$ sudo make install

```

### 3. Modulate cosmic ray fluxes

#### Using the command line tool

The installation provides an command line tool for inspecting and utilizing the modulation matrices.
The executable binary is installed to `bin/helmod` under the prefix directory.
Make sure its path is in your `PATH` variable, and run
``` sh
helmod --help
```
for a detailed description of its usage.

#### Use in C++ program

See `test/test_mod.cc` for a demonstration of modulating proton flux during the AMS02 mission window.

To compile this code, run
``` sh
$ c++ test_mod.cc -o test_mod.exe -lhelmod
```
You can also specify the fallback archive path at compile time.
``` sh
$ c++ test_mod.cc -o test_mod.exe -lhelmod -DHELMOD_DATA_PATH=/path/to/helmod_data
```