Output files format

Tonatiuh's output files format

Before run a Tonatiuh simulation users can select how the information want to be saved:

• Not export. Selecting this option instructs Tonatiuh not to save any ray tracing results. This option could be of interest to verify that an optical system has been properly modelled before using the program to trace a large number of rays.
• Binary data files. Selecting this option instructs Tonatiuh to save the ray tracing results into one or several binary files. The format of the binary files varies depending on the information the user wants to store from every photon. The specific format of the binary files produce by Tonatiuh is detailed in an associated ASCII file.
• SQL Database. Selecting this option instructs Tonatiuh to save the ray tracing results in a SQL Database. Different database's tables are use to store different pieces of information:
  • Surfaces: stores the basic identification information of the surfaces the photons are intersecting.
  • Photons: stores the intersection-related information of each photon intersecting the concentrating geometry.
  • WPhoton: stores the power associated to each photon. The following sections shows how read exported data with Mathematica or R.

Binary data files

First, we will start reading the ASCII file to know which information have been saved during the simulation. The size of this file is not fixed, it depends export option used by the user. The parameters exported for each photon are between the lines with the string “START PARAMETER” and the line with the string “END PARAMETERS”. One line is used to define each parameter exported. Next the information related with surfaces is defined. Only surfaces related with the photons saved are defined in this file. This information the user must extract the lines between “START SURFACES” and “END SURFACES”. Each line between two strings defines the information about one surface that is the identifier used for the surface in the binary files and the URL of that surface. Finally, the last line of the file is power per photon of the simulation.

[[]]
Figure 1. View of a ASCII file created after a simulation.

As mentioned, the file starts with the line "START PARAMETERS". The following lines are the parameters per each photon stored. In the image there are six lines before the string “END PARAMETERS”, so in the binary file 6 parameters per each photon have stored. The ASCII file also shows that only photons related with one surface have been stored, because there is only one line between “START SURFACES” and “END SURFACES”. Finally, the line for the power per photon is defined. The values of the parameters for each photon are in the binary file or binary files stored using double precision real number in big-endian format. If the user defines a maximum size for the binary files, the information could be stored in more than one file. All the files are created with the same name and a suffix, the suffix is a number that represents the file index. The file or files only have a sequence of real numbers, the values of the parameters. The values of a photon are not grouped, so taking into account the number of parameters stored per photon (defined in the ASCII file) and after reading and tuples of values of a photon can be created. After that, the user can execute desired post-processing.

Tonatiuh does not provide means for post-processing and representing the results of the ray tracing it carries out. At CENER either Mathematica or R applications are used for it. Here some of the functions that can be used to read parameter files can be seen:

(* Function to Read Tonatiuh's binary output file *)
ReadTonatiuhResults[filename_] := BinaryReadList[ filename, "Real64",  ByteOrdering -> +1];

(* Read parameters from Tonatiuh's ASCII ouput  file. *)
ReadParameters[filename_] := 
 Module[{parametersFileData, parametersStartIndex, parametersEndIndex,`parameters},
  parametersFileData = ReadList[filename, String]; 
  parametersStartIndex = Flatten[Position[parametersFileData, "START PARAMETERS"]][[1]]; 
  parametersEndIndex = Flatten[Position[parametersFileData, "END PARAMETERS"]][[1]];
  If[(parametersEndIndex - parametersStartIndex) > 1, 
   parameters = Take[parametersFileData, {parametersStartIndex + 1, parametersEndIndex - 1}],
   parameters = {};
   ];
  parameters]

(* Read surfaces from Tonatiuh's ASCII ouput file. *)
ReadSurfaces[filename_] := 
 Module[{parametersFileData, surfacesStartIndex, surfacesEndIndex, surfaces},  
  parametersFileData = ReadList[filename, String];
  surfacesStartIndex = Flatten[Position[parametersFileData, "START SURFACES"]][[1]];
  surfacesEndIndex = Flatten[Position[parametersFileData, "END SURFACES"]][[1]];
  If[(surfacesStartIndex - surfacesEndIndex) > 1, 
   surfaces = Take[parametersFileData, {surfacesStartIndex + 1, 
      surfacesEndIndex - 1}],
   surfaces = {};
   ];
    surfaces]

(* Read ASCII output file information. *)
ReadTonatiuhParametersFile[filename_] := 
  Module[{parametersFileData, parameters, nParameters, surfaces, data, powerPerPhoton, photonsList},
  parametersFileData = ReadList[filename, String];
    parameters = ReadParameters[filename];
    nParameters = Length[parameters];
    surfaces = Sort[ReadSurfaces[filename], #1[[1]] < #2[[1]] &];
    powerPerPhoton = ToExpression[ Last[parametersFileData]];
    {parameters, surfaces, powerPerPhoton}
    ]

....

After executing the last function with the ASCII file filename the output will be the following:

{parameters, surfaces, powerPerPhoton} =  ReadTonatiuhParametersFile[filename].

In order to create a list of tuples (one tuple per photon data) with the values of the binary files, some of the functions that can be used are listed bellow:

nElementsPerPhoton = Length[parameters];
photonMapAll = Partition[ReadTonatiuhResults[filename ], nElementsPerPhoton];
numberOfPhotons = Length[photonMapAll];

Some useful functions for R to help us read Tonatiuh output files could be:

#Read parameter file
ReadParameters<- function(filename ){
	parameterFileStrings<-scan(filename, sep="\n", what='string', quiet=TRUE);

	parametersStartIndex<-match("START PARAMETERS", parameterFileStrings );
	parametersEndIndex<-match("END PARAMETERS", parameterFileStrings); 

	if( ( parametersEndIndex - parametersStartIndex ) > 1 ){
		parameters <-parameterFileStrings[(parametersStartIndex+1):(parametersEndIndex-1)];
	}else{
		parameters<-c();	 
	}
	return( parameters );
}

#Read surfaces from ASCII file
ReadSurfaces<- function(filename ){
	parameterFileStrings<-scan(filename, sep="\n", what='string', quiet=TRUE);

	surfacesStartIndex <- match("START SURFACES", parameterFileStrings );
	surfacesEndIndex <- match("END SURFACES", parameterFileStrings); 


	if( ( surfacesEndIndex - surfacesStartIndex ) > 1 ){
		surfacesData <- parameterFileStrings[( surfacesStartIndex + 1 ):( surfacesEndIndex- 1 )];
		surfaces<-matrix( nrow=length(surfacesData),ncol=2 );
		for( i in 1:length(surfacesData) ){
			s<-strsplit( surfacesData[i], " ")[[1]];
			surfaces[i,1]<-as.numeric( s[1] );
			surfaces[i,2]<-s[2];
		}
		
	}else{
		surfaces<-c();
	}

	return( surfaces [order( as.numeric( surfaces [,1] )),]);
}

#Read power per photon value from ASCII file
ReadPowerPerPhoton<- function( filename ){
	parameterFileStrings<-scan(filename, sep="\n", what='string', quiet=TRUE);
	powerPerPhoton <- as.numeric( tail( parameterFileStrings, n=1 ) );
	return( powerPerPhoton )
}

#Read a binary file an creates a matrix of (nPhotons x nElementsPerPhoton)
ReadTonatiuhData <- function(tonatiuhDataFile,nParameters){

  #file: creates or opens a file. "rb":open to read in binary mode
  fileName <- file(tonatiuhDataFile, "rb")  
  #file.info: extracts information about the file. $size: file size in bytes
  fileSize <- file.info(tonatiuhDataFile)$size
  photonData <- readBin(fileName,what="numeric",n=(fileSize)/8,endian="big")

  #close: close the file
  close(fileName)

nPhotons <- length(photonData)/nParameters

photonMap<-photonData
dim(photonMap)<-c(nParameters,nPhotons)
photonMap<-t(photonMap)

return(photonMap)
}

---

User's Guide | Wiki Home