IMPORTANT UPDATE!

This version of OTSO is now deprecated. While it still works, we recommend using the new OTSOpy tool. OTSOpy is a Python package for OTSO that has many improvements and extra functionality in comparison to this initial release. It is available via pip or through the repository, making it significantly easier for users to set up and use.

OTSO

Oulu - Open-source geomagneToSphere prOpagation tool

OTSO is a geophysics tool used to compute the trajectories of cosmic rays within the Earth's magnetosphere. These computations are used to determine physical values, such as cut-off rigidities and asymptotic cones for locations on the Earth, that are needed by the cosmic ray research community. OTSO provides the user with free reign to select from a plethora of input parameters for tests, such as geomagetospheric conditions, as well as offering various magnetospheric models to choose from.

OTSO is developed using fortran and python. A knowledge of fortran is not needed to use the tool, however, it is required if the user wishes to edit the internal code of the tool (e.g. to add new magnetosphere models).

OTSO is open-source. Therefore, additions and suggestions from the community are welcome.

This is a base release for the tool and bugs are to be expected. I ask the community to please inform me of any bugs they may encounter or provide solutions that can be added to the base code of OTSO.

OTSO works on Windows, Linux, and Mac OS. Instructions for installing OTSO on each of these are located below.

Installation

In order for OTSO to be installed and operate correctly, one must have a fortran compiler and python installed. OTSO has been designed to work alongside the Anaconda python software as this makes OTSO much easier to use.

Installation instructions for OTSO outside of the Anaconda environment will be provided in the future. Currently Linux is the only OS where OTSO has been reliably installed without the use of Anaconda.

Current Issues

OTSO is designed around the Anaconda framework and utilises numpy distutils with f2py for compilation. Numpy has moved on from distutils in favor of meson as a compilation tool when using f2py, and this new version of numpy is provided as default in newer anaconda releases. Currently, attempts to compile OTSO with the new numpy and Anaconda have been unsuccessful. A temporary solution is to download an older release of Anaconda with the old numpy distribution included. To do this, go to the old Anaconda releases repository and download an older version of Anaconda. OTSO was developed on the 2022 release, so finding and installing anaconda via the installer labelled Anaconda3-2022.10 will fix this issue. Ensure that numpy version 1.21.5 is installed.

Once a successful install of OTSO has been conducted using the new meson f2py the instructions will be added to this repository so users may use whatever version of Anaconda they desire.

Windows OS

The easiest way to install OTSO on windows is outlined below.

1. Download and install Anaconda on your system.

2. Download and install MSYS2 on your system. To install the fortran compiler follow the steps below.

   • First enter pacman -Syu into the MSYS2 terminal to update the packages
   • After this is finished MSYS2 will close, open up the terminal again and repeat the first step until no more updates are needed.
   • To install the fortran compiler, enter pacman -S --needed base-devel mingw-w64-x86_64-toolchain into the MSYS2 terminal. Select the default option of all when prompted.
   • To insure gfortran is installed, enter pacman -S mingw-w64-x86_64-gcc-fortran into the MSYS2 terminal and run.
   • The last step for installing the fortran compiler is to add the directory where the .exe file for gfortran is to the environment path variables. The file is typically found at C:\msys64\mingw64\bin, but this can vary depending on where you decided to install MSYS2. To add this directory to the environment path variables you can follow these instructions.

3. In order to run on your computer, OTSO needs to be compiled. This can either be done automatically or manually. We suggest using the automatic compilation first and only attempting the manual way if the former method fails.

Automatic

• Run the Windows_OTSO_Compiler.cmd file located within the OTSO folder (the folder containing user manual) downloaded. If the previous steps have been completed correctly this should compile OTSO and it will be usable.
• Alternatively, you may instead run the makefile using the command make within the same terminal if you have make installed on your system.

Manual

• Open up an anaconda prompt to the Library folder directory.
• Compile the library using the command gfortran -c *Module.f95 *Functions.f95 *.for *.f95 *.f -fPIC within this anaconda prompt terminal.
• Within the same terminal enter ar cr OTSOlib.a *.o to create the static library.
• Copy all files that end with .mod and the OTSOlib.a file into the functions folder which can be found in the Parameters folder within the Tool directory.
• Find the location of the f2py-script.py file on your computer and copy the complete path to this file (it should be located in your anaconda3 directory similar to c:\User\anaconda3\Scripts\f2py-script.py). We recommend copying this path to a .txt file within the OTSO folder for future reference.
• Open a new anaconda prompt, or change the directory in the already open one, to the Tool folder within OTSO and run the command python [YOUR F2PY FILE PATH] -c --fcompiler=gnu95 --compiler=mingw32 -m MiddleMan MiddleMan.f95 OTSOlib.a, replacing [YOUR F2PY FILE PATH] with the path to the f2py-script.py file on your computer.
• It is also possible to run f2py -c --fcompiler=gnu95 --compiler=mingw32 -m MiddleMan MiddleMan.f95 OTSOlib.a instead and the compilations should complete.

Linux

Easiest way to install OTSO on Linux is outlined below. Links to online tutorials are provided as well as plain summaries for each step bellow. Note OTSO was tested on the Ubuntu OS and the following instructions will be for installing OTSO on this OS. It is possible the use of a different Linux OS could change the installation procedure.

1. Install Gfortran onto your Linux system. Follow these instructions. A Summary is given bellow.

   • Open a terminal, enter in the command sudo apt install gfortran and run.
   • Gfortran should now be installed on your OS.

2. Install Anaconda on your Linux system. If you are using Ubuntu follow these instructions. For other Linux OS use the following instructions.

   • Open a terminal and enter the command sudo apt-get update to syncronise all repositories.
   • Change the directory to /tmp using the command cd /tmp
   • Ensure that wget is installed on your computer. Running sudo apt-get install wget within the same terminal will install wget if you don't already have it.
   • To download the Anaconda installer run the command wget https://repo.anaconda.com/archive/Anaconda3-2022.05-Linux-x86_64.sh.
   • To check the integrity of the package enter sha256sum Anaconda3-2022.05-Linux-x86_64.sh into the terminal. If no errors are produced then proceed to the next step.
   • To install Anaconda run the command bash Anaconda3-2022.05-Linux-x86_64.sh in the same terminal.
   • You will now be prompted to read the licence agreement and accept the terms as well as choose the installation directory. Your home directory should already be selected and it is recommended you select this directory to install Anaconda too.
   • The installation is now complete. Close the terminal you are using. Future terminals that you open should have (base) at the start of the command line, this means that Anaconda is working and that you have access to all the packages within Anaconda.

3. OTSO must now be compiled in order to run. This can be done automatically via the provided bash file or manually.

Automatic

• Open a terminal to the main OTSO directory (the folder containing user manual) and run the bash Linux_and_Mac_OTSO_Compiler.sh file. Enter bash Linux_and_Mac_OTSO_Compiler.sh in the terminal and run.
• Alternatively, you may instead run the makefile using the command make within the same terminal if you have make installed on your system.

Manual

• Open a terminal in the Library folder within OTSO. Enter gfortran -c *Module.f95 *Functions.f95 *.for *.f95 *.f -fPIC into the terminal and run.
• Next run the command ar cr OTSOlib.a *.o in the same terminal.
• Copy all files that end with .mod and the OTSOlib.a file into the functions folder which can be found in the Parameters folder within the Tool directory.
• Lastly, open a terminal within the functions folder and run the command f2py -c -m MiddleMan MiddleMan.f95 OTSOlib.a

Without Anaconda

1. If Python is not already on your system follow these steps

• Enter sudo apt-get install python into your terminal to get the latest Python verison installed. (note this will install Python3)
• Download the Python3 development tools by entering sudo apt-get install python3-dev into the command terminal.
• Install the Numpy package needed to use f2py by entering sudo apt-get install python3-numpy into the same terminal

2. Download gfortran onto your linux system by entering sudo apt-get install gfortran into your command terminal.
3. You can then compile OTSO using the same methods outlined above in the