1. Downloading and Setting Up OSPREI

1.1 Initial Download

OSPREI is hosted on CK's personal Github. Go to the repository and click on the green button labeled "Code" and select "Download Zip" from the drop down menu. This will download “OSPREI-master.zip” that contains all of the files for OSPREI, several helper functions, and the files needed to run the example. Unzip the file.

Alternatively, via command line run:

git clone https://github.com/ckay314/OSPREI.git
					

which will clone the repo, creating a folder named OSPREI in whatever directory the command was executed.

There is no real installation process for OSPREI as long as you have python3 set up with most of the standard libraries. OSPREI requires numpy, math, matplotlib, scipy, sys, os, datetime, pickle, and astropy. OSPREI should function with the newest version of these packages, but occasional issues or a lag in updates may occur. Please email if there are any issues so we can fix them.

The OSPREI folder will contain 4 subfolders, and the README.md for the Github site. The four folders are:

• coreCode - the OSPREI code itself
• exampleFiles - input files used to run OSPREI, which we will use within this demo
• helperCode - programs not explicitly used by OSPREI during a run, but that may be needed to help set up the coronal background or determine initial positions
• processCode - programs that take the OSPREI output and process into figures. This includes the main processing script that should (mostly) work for any OSPREI run and several more-complicated examples for specific demo cases

1.2 Configuration

Before running OSPREI you need to configure it to the folder system on your computer as it is currently set up for CK's laptop. In addition to the folders from the repo, create a folder to save the background magnetic field files (that are needed for the ForeCAT component). These files are stored as .pkl (pickles) by Python so CK uses a folder called PickleJar to hold them.

mkdir PickleJar

Move OSPREI.py from coreCode into the main OSPREI directory:

mv coreCode/OSPREI.py .

and processOSPREI.py from the processCode directory:

mv processCode/processOSPREI.py .

If you are unfamiliar with command line operations, note that the “.” is part of the actual command, not a grammatical inclusion. Alternatively, you can just move things using a file browser instead of the command line if that is your preference. Moving these files just makes it easier to run them from the top directory, but there’s also no reason you cannot call them by providing the full line (e.g. coreCode/OSPREI.py) each time you run python.

Find the file mainPaths.txt, which should be in the top directory. If you open it you will see a list of file paths that are set to CK's laptop setup. Change these to match your own computer. mainpath should be the top directory for OSPREI. codepath points to the coreCode folder and processpath points to the processCode folder. magpath is wherever you want to store your magnetic field files. CK creates a new folder called PickleJar to hold these. Finally, heliopath points to a the helioweb files, which are included in the OSPREI repository. This is just a set of trajectories for planets and satellite that OSPREI can use to generate the satellite files it needs. More information on the satellite trajectory is in section 5.1

1.3 Running OSPREI

OSPREI is run with a single call to python:

python OSPREI.py input.txt

Note that you may need to call python as “python3” or something similar, depending on your installation. All of the simulation parameters are controlled by a single .txt file, such as input.txt in the example. If you try and run OSPREI without an input file you should get the following error message:

python OSPREI.py 
No input file given!

In the following sections, we will make sure everything is working correctly and run through some demo cases highlight the range of options available with OSPREI.