Importing and exporting data

Importing and exporting data

TBTK provides a number of methods for reading and writing to external memory. We describe these methods here.

FileParser and ParameterSet

The FileParser can generate a ParameterSet by parsing a file formated as follows.

int     sizeX       = 50
int     sizeY       = 50
double  radius      = 10
complex phaseFactor = (1, 0)
bool    useGPU      = true
string  filename    = Model.json

Assume the file is called "ParameterFile". It is then possible to parse it and extract the values using

ParameterSet parameterSet
    = FileParser::parseParameterSet("ParameterFile");
 
int sizeX                   = parameterSet.getInt("sizeX");
int sizeY                   = parameterSet.getInt("sizeY");
double radius               = parameterSet.getDouble("radius");
complex<double> phaseFactor = parameterSet.getComplex("phaseFactor");
bool useGPU                 = parameterSet.getBool("useGPU");
string filename             = parameterSet.getString("filename");

Serializable and Resource

Many classes implement the Serializable interface. This means that they can be converted into text strings that can then be converted back into objects.

For example, the following code first serializes a Model and then recreates a copy of it from the resulting serialization string.

string serialization = model.serialize(Serializable::Mode::JSON);
Model copyOfModel(serialization, Serializable::Mode::JSON);

The parameter Serializable::Mode::JSON indicates that the serialization should be done to and from JSON. Currently, this is the only widely supported serialization format in TBTK.

The power of serialization is that a string can be stored or sent anywhere. The Resource class is meant to simplify this task. For example, the serialization created above can be saved to a file called Model.json using

Resource resource;
resource.setData(serialization);
resource.write("Model.json");

The Model can then be read in and reconstructed in a different program using

Resource resource;
resource.read("Model.json");
Model model(resource.getData(), Serializable::Mode::JSON);

The Resource can also download data from a URL. For example, the following code creates a Model from a file downloaded from www.second-quantization.com.

Resource resource;
resource.read(
    "http://www.second-quantization.com/v2/ExampleModel.json"
);
Model model(resource.getData(), Serializable::Mode::JSON);

To be able to use the Resource class, cURL must be installed when TBTK is compiled.

Exporter

The Exporter can be used to export Arrays and Properties to plain text files. The purpose is to make it easy to transfer data to, for example, Python or MATLAB for post-processing. An Array or Property on the None or Ranges format can be exported as follows.

Exporter exporter;
exporter.save(property, "Filename");

If the Property is on the Custom format, an additional pattern Index is needed to determine the set of Indices to export the Property for. For example, it is possible to export a Property with the index structure {x, y, z} for all Indices of the form {x, 5, z} as follows.

Exporter exporter;
exporter.save(property, {_a_, 5, _a_}, "Filename");

By default, the Exporter exports data using row major order. Some other languages, e.g. MATLAB and Fortran, uses column major order and it is, therefore, possible to change the output format. This is done through the following command.

exporter.setFormat(Exporter::Format::ColumnMajor);

The following code can be used to import the data into Python

import numpy as np
property = np.loadtxt("Filename").reshape(SIZE_X, SIZE_Y, SIZE_Z)

Here it is assumed that the data is three-dimensional with size SIZE_X, SIZE_Y, and SIZE_Z, and that the data has been exported on the row major order format (default).

Similarly, the following code can be used to import the data into MATLAB

data = dlmread('Filename')
property = reshape(data, [SIZE_X, SIZE_Y, SIZE_Z])

Here it is assumed that the data is three-dimensional with size SIZE_X, SIZE_Y, and SIZE_Z, and that the data has been exported on the column major order format.

Next: Streams