If 'Sorry, you have to detect the errors' is the final answer, I can't have confidence in my simulations. I just don't have the ability to learn OS inside and out to predict all of the potential issues.



I couldn't imagine a Zemax engineer sitting over a customer's shoulder, noticing problems with their simulation, and not telling them. That's what the API is doing - unless for whatever reason it can't detect errors itself. If that's the case, I guess some big architectural overhaul is in order.

This is more of a general problem and design of the entire API. Here are some examples:

• other_row.CoatScatterData.GetFaceData(2**31 - 1)
  
  
  
  • Should throw an error because that face doesn't exist. Instead, it returns a face data object.
  
  
  
  


• non_sequential_component_editor.GetObjectAt(1200210)
  
  
  
  • Returns None instead of throwing an error. This is better than complete silence though.
  
  
  • Other functions return False or -1 or 1 (like non_sequential_ray_trace_tool.ClearDetectors(1328913298)), or like GetFaceData it could return an object. All these types of values somehow indicate something went wrong.
  
  
  
  


• ZAR loading ignores errors loading Solidworks files, doesn't print anything/log anything


• Opening multiple zos_system.Tools at once fails silently, no warnings


• non_sequential_ray_trace_tool.set_SplitNSCRays('adsfads')
  
  
  
  • No error despite a bad input, return value is the same as setting it to a valid input
  
  
  
  

Another response could be, 'Don't make mistakes and give things bad arguments' - this is like selling cars without seatbelts and airbags. Roads without guardrails, etc. It's especially important for newbies (me) and people on a team of 1 without experienced reviewers (also me).

Those examples are just a very few - I anticipate it being ubiquitous since I'd guess the Python API was automatically generated, not hand-written.



Fair on the return values - I'd hope for at least consistency so I could check for the same thing every time. I don't have a UI - I just have a server people submit ZAR files to and it runs simulations, so I need it to crash and burn rather than plug along. I'd rather have a disrupted flow than inaccurate results.



'one should consider the development resources at Zemax as well' agreed, and they can prioritize this however they want. I just disagree with  'it's the user's burden' as an API philosophy.

This sounds odd to me. First of all, SolidWorks only needs to be installed if you are loading SolidWorks files, not general CAD formats like STEP etc. Chris, can you clarify what type of CAD files you are using? If they are STEP etc files there should ne bo issue.

One thing to try is to load the ZAR archive by hand via the UI and see what errors you get. Any error generated in the UI should have an equivalent via ZOS-API. It would be a bug if no equivalent error message was returned.

That said, error handling is one of the things you do need to handle if writing at the ZOS-API level and even in ZPL. If you try to do something that cannot be done from the UI, like running multiple tools at once, I think it may be very difficult for the Zemax coders to trap those things without making the coded run slower for all users. So there is a balance of effort between the API programmer and the Zemax programmer. I'd start with whatever error messages you get from the UI: these should be replicated in ZOS-API.

We were using 'CAD Part: SolidWorks®'.



'error handling is one of the things you do need to handle if writing at the ZOS-API level and even in ZPL'. If you try to do something that cannot be done from the UI, like running multiple tools at once, '

This is my point - it shouldn't fall on the shoulders of API users to check for all possible errors. For a decent UX, the API should provide guardrails that say 'Oh! Looks like you don't have Solidworks installed. Please install before running a ray trace with these objects.' Instead, it says 'No Solidworks? That's okay, they probably weren't important anyway. Simulate away!' Please don't focus on just this issue though, it's a problem throughout the API - see the examples I posted above.

'I think it may be very difficult for the Zemax coders to trap those things without making the coded run slower for all users.'

It's good to consider performance, but the code certainly won't run noticeably slower for any of the use cases I mentioned. Unless something is very wrong that I don't know about.

'start with whatever error messages you get from the UI'

The API should be independent from the UI, but alright. The UI tells me I need Solidworks installed to view the files, and converts all the rows in the NCE to null objects. In the API, it converts them to null objects, but doesn't log any warnings or throw any errors. Fortunately, I can check for null objects and stop the simulation myself as a band-aid fix. Before now, though, all we knew was that something was weird about our simulations - numbers didn't match up like we expected. That leaves the entire space of all called functions, all model setup, everything to search to find the issue. Instead of the API pointing out exactly what is wrong.



I've attached the contrived ZAR we made for debugging.

Perfect, thank you for your response (and calmness despite my lack of calmness ). Checking the status didn't help with the Solidworks problem, but logging will help. I see the messages I need there.



In the short term, I'd recommend turning on message logging by default. That could prevent a lot of headaches while you're working on other features, and it's a quick fix. As soon as someone creates an application object, call BeginMessageLogging(), format the output somehow, and print it to the console.



Better to have too many log messages than not enough.

Jumping in here to say that I agree with Chris, Ray, and Brian.  The API documentation is lacking, and error checking isn’t very good and can cause big problems that are frustrating and time consuming to figure out.  Given the price increases over the past few years, the burden on the user is much too high, 

My recent experience with this issue was inserting a lens from the Lens Catalog.  Before that moment, I’d never used the API in a manner that forced me to check GetCurrentStatus().

The challenge I faced was:

When inserting a lens from the lens catalog, there is no way to know if the material catalogs being used in the model are consistent with the lens in the catalog.  One needs to

1. Trap the message from GetCurrrentStatus
2. Search through all material catalogs to find the catalog that has the glass that is required
3. Add that material

I have only encountered one message with: GetCurrentStatus, that of an undefined glass.  It is revealed as a message in text.  I have no idea what other messages may exists and how to parse them.

What other messages have other people encountered?