ZRD2MAT Multi-Threading Failure Error

  • 24 January 2024
  • 6 replies

I am running a macro that sweeps through different source ray angles, traces the system, and then saves the .ZRD file to a matlab .MAT file. There are only 4 rays being traced and the system is somewhat simple, so the ray trace time is quick. However, I have started to see this error regarding multi-threading. Since I have many .ZRD files I would like to convert, is there a way to turn off multi-threading in a command so I don’t have to click through the error message for every .ZRD file? Thanks in advance.


Code section:
FOR io, ip_ang_start, ip_ang_end, 1
    #Change angle
    SETNSCPOSITION 1, ip_source, 5, io
    #Create file name
    traceName$ = $STR(io)
    fileName$ = "\inputRays" + traceName$ + ".ZRD"
    matFileName$ = "\inputRays" + traceName$ + ".MAT"
    PRINT "Input Angle: ", io
    PRINT fileName$
    #PRINT matFileName$
    #NSTR surf, source, split, scatter, usepolar, ignore_errors, random_seed, save, savefilename, filter, zrd_format
    NSTR 1, 0, 1, 1, 1, 1, 0, 1, fileName$, "", 1
    zrd2mat fileName2$, matFileName$, 0, 1, 4


Error message:



Best answer by Roger.Conley Smith 24 January 2024, 19:22

View original

6 replies

Userlevel 6
Badge +2

You can try SYSP 901, 1 to only have 1 core being used for multi-threaded calculations.  To use all the cores, you can reset it with SYSP 901, 0.

Hi Michael,

Thanks for the suggestion. It seems that the function  ZRD2MAT  is case sensitive and I had it in the macro in lower case. Changing to uppercase seemed to solve the issue.



Userlevel 6
Badge +2

Hi Roger,

None of the ZPL Keywords (or functions or variables) are case sensitive.  There is a ZPL pre-processor which converts all keywords, functions & variables to upper case and then the ZPL itself is run.  So, I would use caution with your above code if all you have changed is zrd2mat to ZRD2MAT.

What is most likely happening is based on the complexity of your ZRD file and how many other processes are opened, you’re getting lucky that the ZRD2MAT keyword is only using a single thread when calling the external MATFileGenerator.dll.  Since the MAT file format (binary -v7) has a complex data structure, the entire MAT file needs to be written at the same time OpticStudio by default chunks the ZRD file and reads/processes a ZRD using multiple threads.  So, the more complex (i.e., more rays) a ZRD file, the more threads OpticStudio will try to process the data and the more likely there will be issues writing the MAT file.

You can also turn off multi-threading by using the GUI if you don’t want to change your code (System Explorer > Advanced > Turn Off Threading):


Hi Michael,


I was a bit surprised that changing it to be case-sensitive solved the problem. I did try your method (and included update after the call to change the threads) but it returned the same error. I will try to turn off multi-threading through the editor and then try the previous code with the lower case call. For reference, the errors occurred when I was tracing 4 rays through 3 surfaces that are all planar. The raytrace database data is somewhat simple in the .zrd format, although noted that the .mat format is complicated.



Userlevel 7
Badge +3

Michael is correct that ZPL should NOT be case sensitive, but if that one keyword is, someone in Zemax development should have a look.

The ‘Turn off Threading’ and SYSP tricks were intended to test whether threading was the problem, and using them should only be for debugging.

The 2 in ZPL2MAT might be a problem as the vast majority of keywords do not have numbers in them.

Userlevel 6
Badge +2

Hey Mark, I already checked on a 1 ray ZRD file that both upper and lower case works.  Since the ‘2’ is in the middle of the keyword, there is no problem with the ZPL parser correctly handling.

If this persists as an issue, I suggest using the IZRDReader interface via the ZOS-API, which can be directly run in Matlab.  The following Webinar and KBA can help with this:

Accessing the Ray Database with the ZOS-API using MATLAB - webinar – Knowledgebase (

Batch Processing of Ray Trace Data using ZOS-API in MATLAB or Python – Knowledgebase (