This library is based on the following public classes under the raytracing namespace:

Here's a schematic of the I/O logic.

NB: image with hyperlinks, you can click on the boxes to jump directly to the class definition.

Writing

Declare an openPMD_io object with a filename used for writing (raytracing::openPMD_io())
initialize the file (raytracing::openPMD_io::init_write)
a Ray object should be constructed and filled with all the relevant information for the ray being traced
the ray is then queued for writing with the raytracing::openPMD_io::trace_write
the queued rays are written to file in bunches of CHUNKSIZE and finally when raytracing::openPMD_io::save_write() is called

In the following a very simple example can be found.

#include <openPMD_io.hh>
int
main(int argc, char* argv[]) {
    std::string filename = "test_file.json";
    raytracing::openPMD_io iol(filename, "test code");
    iol.init_write(  "2112", 8,raytracing::AUTO, 2);
    std::cout << "filename = " << filename << std::endl;
    raytracing::Ray myray;
    myray.set_position(1, 2, 3);
    //...
    myray.set_direction(1, 1, 1, 1. / sqrt(3));
    // append
    for(size_t i =0; i < 10; ++i){
        iol.trace_write(myray);
    }
    std::cout << "trace write done" << std::endl;
    iol.save_write();
    std::cout << "save write done" << std::endl;
    return 0;
}

The Ray class is providing all the conversion/utility operations on the quantities stored in the openPMD file according to the RAYTRACE extension

Reading

Reading from an openPMD file follows the same logic as the reading, with symmetricly defined methods of the openPMD_io class.

#include <openPMD_io.hh>
int main(void){
    std::string filename = "test_file.json";
    raytracing::openPMD_io io(filename, "test code");
    io.init_read(raytracing::HDF5);
    auto ray = io.trace_read();
    
    return 0;
}

Unit conversion

The units of the quantities stored in the openPMD file are pre-defined by the extension and not customizable by the user.

For a more user-friendly user interface, the user should create it's own version of the Ray object (either in C++ or in Python), inheriting from the original Ray object. The conversion should be done in the overloaded methods. This should highly simplify the user code.

Otherwise, the user can also use the bare Ray class with the "scale" optional argument for the different methods to scale the units into the pre-defined ones.

Todo

[NO] Units conversion!!!!
[X] Setter and getter for gravity direction
[X] Setter and getter for horizontalCoordinate
[X] Setter and getter for numParticles
[X] Interal usage of numParticles
[X] Binding of wavelength, time, weight, id, status getters
[ ] Test the python binding
[ ] Cmake install for the python binding
[ ] PyPi package
[X] ostream friend for the ray class to make easier to debug
[X] Repeating ray multiple times if requested when reading the openPMD file
[X] Writing in chunks
[X] Throwing runtime_error when over the maximum foreseen number of rays
[X] Add doctest package for C++ unit tests

Examples

Examples can be found