C.1 Installation
This section treats how to prepare your system so that the simulation can be installed and executed. Note that all steps are necessary, even if you downloaded the binary. The simula-tion tool makes use of external libraries, which need to be available on your system in order for the simulation to work. At the time of writing, only Linux is supported.
The source code of the simulation is available as a GitHub repository, under the MIT license. The code can be found on:
http://github.com/rvangijlswijk/ionospheric-ray-tracer C.1.1 Prerequisites
This project makes use of the following packages:
• GTest: http://code.google.com/p/googletest/
• Boost libraries: http://www.boost.org/
• scons: http://www.scons.org/
• jsoncpp: https://github.com/open-source-parsers/jsoncpp
GTest is included in the source, but it is required to have both the boost and scons json li-braries installed locally.
C.1.2 Installation on Linux
The following section treats how to prepare your system for this package if you want to compile it from source. This procedure is tested on systems running Ubuntu 14.04 and Ubuntu 14.10.
Step 1 Install git:
sudo apt-get install git
Step 2 Ensure that the required build packages and libraries are installed. The minimum required gcc is gcc 4.9.
sudo add-apt-repository ppa:ubuntu-toolchain-r/test sudo apt-get update
sudo apt-get upgrade
sudo apt-get install build-essential g++ gcc python-dev autotools-dev libicu-dev build-essential libbz2-dev libstdc++
Step 3 Install the boost libraries. The minimum required version is libboost-1.55.
sudo aptitude install libboost-all-dev
Step 4 The next step is to download and compile the json library, jsoncpp. This library re-quires the software configuration tool scons, so that needs to be installed as well. Note that the version number of gcc might vary on your system. In the example below, gcc-4.9.2 is used:
sudo apt-get install scons
git clone https://github.com/open-source-parsers/jsoncpp.git cd jsoncpp
scons platform=linux-gcc
sudo cp libs/linux-gcc-4.9.2/libjson_linux-gcc-4.9.2_libmt.so /usr/lib
Step 5 The final step is to download the simulator itself. The release versions of the simu-lator are hosted on the following webpage:
http://github.com/rvangijlswijk/ionospheric-ray-tracer/releases One should download the file irt.zip in order to obtain the executable. This zipfile con-tains the executable, and a set of configuration files, which are required to configure the simulation. The zipfile must be unzipped to some folder on your system. Within this folder, the simulator can be executed.
C.2 Usage
The simulation can be configured in two ways. First, runtime options allow to set certain parameters at the command line. Second, configuration files store the configuration of both the scenario used and the application settings.
This section assumes that you are running a linux machine. The commands will not work on Windows.
C.2.1 Quickstart
The simulation can be executed with the following command:
./irt config/scenario_nominal.json
Note that this command should be executed in the folder where the binary is downloaded.
The command runs the simulation for the nominal scenario. The last parameter always in-dicates the configuration file for the planetary environment which should be used. In this example, the environment for the nominal scenario is used. Furthermore, the simulation assumes that a file exists at the relative path config/config.json. This file is automatically loaded.
A FEASIBILITY STUDY ON GROUND-BASED LOCALIZATION FOR MARS EXPLORATION 110
The results of the simulation are stored in a csv data file, which can be easily loaded by Matlab or some csv reader. The default location of the data file is Debug/data.dat. Ensure that the Debug folder exists before running the simulator.
C.2.2 Runtime options
Several options can be passed to the simulation to alter application settings. The options can be provided in the command line as follows:
./irt [-opts] scenarioConfig
The options are supplied as the first arguments. The scenario configuration file is always the last argument. This configuration file is also obligatory. Table C.1 lists the options that can be supplied.
Table C.1: List of command-line options
Option Explanation
-c | --config [path] Provide a custom application configuration file, located at path -i | --iterations [num] The number, num of consecutive times every ray should be simulated.
This is used for the Monte-Carlo approach. An increase in iterations will increase the number of measurements.
-h | --help Print a help text
-o | --output [path] Store the output at the location indicated by path. It is advised to have pathend with .dat, i.e. /path/to/data.dat
-p | --parallelism The number of threads to use for the simulation -v | --verbose Verbose, display log output
-vv Very verbose, display both log output and debug output
For example, to run the simulator on four threads, write the output to mydata.dat and use the configuration for the max scenario, one must use the following command:
./irt -o mydata.dat -p 4 config/scenario_max.json
C.2.3 Configuration files
The configuration of the simulation and the scenarios are stored in an application and sce-nario configuration file, respectively. The release download includes a folder, containing one application configuration file and scenario configuration files for several scenarios. These configurations are defined in json format. Some of the application configuration parameters can be overridden with the use of runtime options.
An example configuration file is given in codeblock C.1. The parameters that define the planet, its atmosphere and its ionosphere are dictated in this configuration. Parameters are defined in key-value pairs. The key dictates the name of the parameter, i.e. “radius”. The value can be given as number, scientific notation, array or text string. The simulation as-sumes a certain format for each value, and therefore the format as shown in the example
must be used. For example, the “radius” parameter uses an integer number value. The “sur-faceNCO2” parameter uses scientific notation. Note that the latter value is stated in brack-ets. It is assumed that all parameter names, given in the example, are self-explanatory.
A multilayer ionosphere is defined by adding an extra block with parameters to the “layer parameter”, which itself is an array. Example C.1 contains an ionosphere with two layers: the M2 and M1 layer. Further information about the json format is found at http://json.
org/. {
"name": "Mars",
"radius": 3390000,
"surfaceNCO2": "2.8e17",
"surfaceTemperature": 200,
"atmosphere": {
"start": 1000,
"end": 40000, },
"ionosphere": {
"start": 70000,
"step": 125,
"end": 250000,
"layers": [{
"name" : "M2 Layer",
"peakProductionAltitude": 130000,
"electronPeakDensity": "1.8e11",
"neutralScaleHeight": 11000,
"type": "chapman"
},{
"name" : "M1 Layer",
"peakProductionAltitude": 110000,
"electronPeakDensity": "9.0e10",
"neutralScaleHeight": 7600,
"type": "chapman"
}]
} }
Codeblock C.1: An example of a scenario configuration file
C.2.4 Executing from source
The simulation can be executed from source. The main application file is located under src/core/main.cpp, as seen from the root of the source code directory structure. The main.cppfile is a bootstrapper for the application file in Application.cpp. This boot-strapper is configured in both debug and release mode. In debug mode, all the unittests are run. The simulation itself is run in release mode.
A FEASIBILITY STUDY ON GROUND-BASED LOCALIZATION FOR MARS EXPLORATION 112