7.1. Input/Output

Handling input and output can be an important part of an application, as Tudat is built primarily for numerical orbit propagation/mission analysis, and not for visualization, which most users choose to do in e.g. Matlab. This page provides an overview of the most important Tudat methods for handling input and output, their set-up and how they can be used in an application.

7.1.1. Available methods

All functions and classes that handle input/output can be found in the InputOutput directory in the Tudat libraries. These functions and classes provide a variety of handlers and can, for example, skip lines, eliminate comments from a file, or store the propagation history to a particular file. In most cases, however, these specific file readers will not need to be called directly by the user, but are instead used when retrieving a default spherical harmonic gravity field or an aerodynamic database.

The input/output elements from Tudat that will be discussed here, can be subdivided into three categories:

  • Path-functions.
  • File-readers.
  • File-writers.

7.1.1.1. Path-functions

These are functions that return the root-path of the library (or a particular folder). They can be used to define a path relative to the root-path of Tudat when using a file-reader/writer. The following path functions are available:

getTudatRootPath() (Tudat)
This function returns the root-path corresponding with the root-directory of the Tudat library as a string with trailing slash included.
getSpiceKernelPath() (Tudat)

This function returns the path where the Spice Kernels are located as a string with trailing slash included. This is very useful when writing code that will work cross-platform. For instance, if you have a file inputData.txt that is located at:

C:/Software/tudatBundle/tudat/Tudat/Astrodynamics/

you will want to avoid writing this full path in your code, as it will not run on any other system where Tudat is installed in a different directory. Instead, what you can do:

std::string filePath = input_output::getTudatRootPath( ) + "Astrodynamics/";
std::string fileName = "inputData.txt"

Note

The full path/name of the input data file is now simply filePath+fileName, which will correctly identify the file location on any system.

7.1.1.2. File-readers

If needed, you can use this functionality as a starting point to create your own file-reader for your specific file type. If you run into issues when doing so, please contact the Tudat support team. However, there is a dedicated file-reader available in the Tudat library:

readMatrixFromFile (Tudat)
This function can be used to read a simple text file with separated numbers. The documentation includes the options for a separator and the character used to skip a line (e.g. a comment-line). Note that the new-line character (n) is reserved to split the lines of the matrix.

7.1.1.3. File-writers

The InputOutput directory in the Tudat library also contains functionality to write data (e.g. the propagation history of a satellite) to a file. The following function is available:

writeDataMapToTextFile (Tudat)

This function writes data stored in a map to a text file. A number of overloads exists for this function based on the input given to the function. Furthermore, the data-map can store different types of data (e.g. doubles and Eigen vectors, which are typical types for the propagation history). The following overload is most relevant:

writeDataMapToTextFile(dataMap,
  outputFileName,
  outputDirectory,
  fileHeader,
  precisionOfKeyType,
  precisionOfValueType,
  delimiter)

If only the dataMap and file-name are provided, the default KeyType-precision and ValueType-precision (digits10 from “limits” standard library), output directory (Tudat root-path), and delimiter (space) are used. If also the outputDirectory is provided an empty file header, a precision of 16 significant digits and a tab as delimiter are used, but these can be user-specified.

writeMatrixToTextFile (Tudat)
This function writes data stored in a Eigen::Matrix to a text file. The input required are the Matrix itself and the file-name. Note that any scalarType and number of rows and collumns can be used.

7.1.2. Examples

7.1.2.1. Text file to MatrixXd

An example of reading data from a text file to a Eigen::MatrixXd is shown in detail in Use of Thrust: User-defined Thrust Vector. A small overview is presented here:

For example a file named .txt contains data structured as follows:

0       0 0 5
6068    0 1 5
6097    1.0 0 5
6097.5  0.8 0 5
6098    0.6 0.1 5
6099    0.1 0.5 5
12192   0.2 1.0 4.5
18288   0.3 1.5 4.0
243575  0.4 2.0 3.0
3.999e6 1.0 1.0 2.0
4e6     1.1 5.0 1.0

thus 4 columns spaced with tabs. This file can be read with the following code:

Eigen::MatrixXd thrustForceMatrix =
       tudat::input_output::readMatrixFromFile( cppFolder + "nameOfFile.txt" , " \t", "#" );

where the first argument is the relative path to the .txt file, the second argument indicates the type(s) of separator(s) used (multiple seperators possible). The last argument indicates the character used for lines to be skipped.

7.1.2.2. Data-map (double,double) to text file

A data map is a template class that is defined by its key-type and value-type:

std::map< key-type, value-type >

Using this, a data map, where the type of the key is a double, and the type of the value is also a double, can be defined as:

std::map< double, double > keyDoubleValueDoubleMap;

Each entry in the data map consists of a key and a value and is entered using:

keyDoubleValueDoubleMap[ key ] = value;

As an example, three entries are stored in this data map:

keyDoubleValueDoubleMap[ std::sqrt( 3.0 ) ] = 1.0 / std::sqrt( 2.0 );
keyDoubleValueDoubleMap[ 4.5 ] = 56.89;
keyDoubleValueDoubleMap[ 12.65 ] = 1.0 / 3.0;

Now, this data-map can be stored to a file using:

tudat::input_output::writeDataMapToTextFile(
            keyDoubleValueDoubleMap, "keyDoubleValueDoubleMapDataFileWithDefaults" );

7.1.2.3. Data-map (double,Vector3d) to text file

An example of a data map, where the type of the key is a double, and the type of the value is an Eigen::Vector3d:

std::map< double, Eigen::Vector3d > keyDoubleValueVector3dMap;
keyDoubleValueVector3dMap[ 1.1 ] = Eigen::Vector3d( 0.0, 1.3, -6.54 );
keyDoubleValueVector3dMap[ 6.5 ] = Eigen::Vector3d( -4.56, 1.23, -9.98 );
keyDoubleValueVector3dMap[ 10.9 ] = Eigen::Vector3d( -46.13, 1.0 / 3.0, std::sqrt( 2.0 ) );

This data-map can be stored to a file using:

tudat::input_output::writeDataMapToTextFile(
            keyDoubleValueVector3dMap, "keyDoubleValueVector3dMapDataFile" );

7.1.2.4. Data-map (int, Matrix3d) to text file

An example of a data map, where the type of the key is a int, and the type of the value is an Eigen::Matrix3d:

Eigen::Matrix3d threeDimensionalMatrix;
threeDimensionalMatrix << 0, 1, 2, 3, 4, 5, 6, 7, 8;

std::map<int, Eigen::Matrix3d> matrixMap;
matrixMap[14] = threeDimensionalMatrix;

This data-map can be stored to a file using:

tudat::input_output::writeDataMapToTextFile(
            matrixMap, "matrixMap" );

This results in:

14          0                 1                 2                 3                 4                 5                 6                 7                 8

Note that all matrix entries are put on one line when writing a map to file. This makes the file easy to read by other programs.

7.1.2.5. Eigen::Matrix3d to text file

An example of a matrix to save:

Eigen::Matrix3d squareDoubleValueMatrix;
squareDoubleValueMatrix << 0, 1, 2, 3, 4, 5, 6, 7, 8;

This can be saved to a text file using:

tudat::input_output::writeMatrixToTextFile(
                             squareDoubleValueMatrix, "squareDoubleValueMatrixFile")

This results in:

0                     1                       2
3                     4                       5
6                     7                       8

Note the difference with saving matrices inside a map, which will put all matrix entries on one line.

7.1.2.6. Storing propagation history

A good example on how to store the propagation history in a data map can be found in the example applications in the Tudat Bundle. If you have downloaded the bundle, these examples can be found in:

tudatBundle/tudatApplications/satellitePropagatorExamples/SatellitePropagatorExamples

An example of saving the propagation history to a data file is described at the end of the Unperturbed Earth-orbiting Satellite walkthrough.

7.1.2.7. Storing dependent variable history

Dependent variables can be saved to a data file similar to the propagation history. Instead of the getEquationOfMotionNumericalSolution() function the getDependentVariableHistory() function of the DynamicsSimulator class is used to obtain the Data-map. Which can be saved as described above.