ZOSAPI extention mode - importnotfound error

  • 26 February 2024
  • 9 replies


I am very new to ZOSAPI - python programming. I am simply following the article -

I am using pycharm IDE and running from it (as suggested, in running this in python console). Upto this point, everything seems to be working fine. I see the prompt in optics studio (given below) with the status : connected. 

OpticsStudio Connection made 


All the variable are also loaded : 

Variables Defined



However, I don’t see this feature “It means that there is an “Intellisense” when working with the Interactive Extension” .

Missing Intellisense


That is, none of the methods of ZOSAPI are loaded. And if I try running the example code (as suggested in the article), I am getting an error, “ModuleNotFoundError: No module named 'ZOSAPI'” . 

ModuleNotFound Error

I have already installed Pythonnet package, which helped to make the first connection with optics studio. But I don’t understand why a script other than the boilerplate won’t work.

I hope this is an easy mistake to fix. 




Best answer by David.Nguyen 28 February 2024, 14:22

View original

9 replies

Userlevel 3

Hi @nc9289,

Can you share the code you are trying to run? Otherwise we need to make assumptions about your code, and chances are those assumptions will be incorrect.

If you're getting started with Python and the ZOS-API, I recommend trying ZOSPy, an open source Python library that simplifies the interaction with the ZOS-API. This library also takes care of loading the ZOS-API DLLs, so you don't have to. The documentation also contains examples that explain how to model certain optical systems, for example a simple thick lens.

Hi @chaasjes 

Thanks for the reply. 

I have attached two text file here, with the codes. ‘PythonZOSconnection6.txt’ is auto generated biolerplate code, which helps to make a connection with OpticsStudio in extention mode. 

ZOSAPI_example is one of the example file that comes with the software, and I was trying this as a first test. 

However, I get the modulenotfounderror. 


Userlevel 7
Badge +2



You need to combine the boilerplate code with the example to be able to use it in Interactive Extension mode. I can’t explain why, but you can’t just import ZOSAPI like you tried. I’ve uploaded a version of Example 1 that works for me on R1.00. I took the boilerplate template, and after the comment (possibly line 102): "Insert Code Here” I inserted Example 1 from the lines (included):

# creates a new API directory
if not os.path.exists(TheApplication.SamplesDir + "\\API\\Python"):
os.makedirs(TheApplication.SamplesDir + "\\API\\Python")

Ignoring all the other lines above. And lastly, I also removed the last two lines:

# This will clean up the connection to OpticStudio.
# Note that it closes down the server instance of OpticStudio, so you for maximum performance do not do
# this until you need to.
del zos
zos = None

Let me know if you can manage this way.

Take care,



@David.Nguyen This is great ! It worked.

I want to primarily use ZOSAPI for automating optics studio POP simulations (beam propogation). 

Before getting into zemax programming, I had already made a ray trace model. I wonder (a novice question), if it is possible to work with it using ZOSAPI without having to write the code to define the model again from scratch ? In other words, if I just want to programmatically work on a specific lens file ?

Thanks for your help. 

Userlevel 7
Badge +2



I want to say yes in general, but it will be more or less complex depending on the kind of data you have for your model. Some time ago I wrote a script to parse specific data from a lens patent in a sort of tabular format directly into OpticStudio with the ZOS-API. You find the code at the end of my original question:

What kind of lens data do you have and in which format?

Take care,



Sorry, I should provide more details on what I am trying to achieve. For example, I have this example zemax lens file called “Grating”. This is already ray traced, and I don’t have a ZOS-API python code for this. So, if I want to manipulate the file, I will do this manually in the zemax software. But my question is if there is a way to work on an already existing lens file via ZOS-API, without having to develop the code from scartch?

I will attach a screen shot here. You can see that the model is already developed manually. Programmatically, I just want to manipulate certain aspects of it. It seems I will have to write the code from scratch first. 



Userlevel 7
Badge +2



The ZOS-API gives you a programmatic access to OpticStudio. As such, the ZOS-API does almost anything that can be done manually through the user interface. I think the reason you are asking is because the lenses are often built inside the example files, but you can totally work with an existing file to perform any other sort of manipulation.

Say you have a per-existing file called my_lens.zos, for example. Then, in the user interface, you can click File..Open, browse to your lens file and select it. Your file opens. You can then click Analyze..Rays & Spots..Standard Spot Diagram and you see an analysis window of your spot diagram.

You can do exactly the same with the ZOS-API. If you use the boilerplate templates, they usually give you access to TheSystem, which represents the current optical system in your application. You can then use the command:

TheSystem.LoadFile(“your_path/my_lens.zos”, True)

The first string parameter is the full path to your file, and the second boolean parameter is to indicate whether you want the current file to be saved or not. Finally, you can also open any analysis window that will be calculated on the pre-existing file that you just opened. For the spot diagram for example:

MySpotDiagram = TheSystem.Analyses.New_StandardSpot()

Note that I’m using the default settings of the spot diagram here, but it is also possible to modify them with the ZOS-API. You can also modify your pre-existing file, save it to a different name, ...etc. The actual lens data is inside the ZOS/ZMX file itself, if that makes sense.

Let me know if I understood the question properly this time, and if what I wrote is clear.

Take care,



Thanks for explaination. Quick check, I want to edit a lens file, so it doesn’t matter if the extension is .zmx or .zos ?

TheSystem.LoadFile(“your_path/my_lens.zmx”, True)


TheSystem.LoadFile(“your_path/my_lens.zos”, True)

I would appreciate some help regarding doing POP simulations via python, especially if there is a way to custom define my pilot beam. 

Happy to create a new request :)



Userlevel 7
Badge +2



Whenever your questions diverges from the original topic, I suggest you create a new post. It will be easier for other user to search the forum and find relevant information.

The two lines of code should work indeed, let us know otherwise.

You can open a POP analysis with

my_pop = TheSystem.Analyses.New_Analysis(ZOSAPI.Analysis.AnalysisIDM.PhysicalOpticsPropagation)

Then, as with any analysis, you can check whether POP has its settings fully implemented in the ZOS-API with


The result should be True (at least for R1.00), and this means POP settings are accessible through the ZOS-API directly. You can find the exhaustive list of settings in the Programming..ZOS-API Help..ZOS-API Syntax Help under ZOSAPI>Analysis>PhysicalOptics>IAS_PhysicalOpticsPropagation. I don’t think you can modify the pilot beam directly, the pilot beam is generated by OpticStudio to help with determining what algorithm is most suited to perform the propagation. You can modify your Beam Definition though

# Open a POP analysis
my_pop = TheSystem.Analyses.New_Analysis(ZOSAPI.Analysis.AnalysisIDM.PhysicalOpticsPropagation)

# Retrieve POP settings
my_pop_settings = my_pop.GetSettings()

# Modify Beam Definition
my_pop_settings.BeamType = ZOSAPI.Analysis.PhysicalOptics.POPBeamTypes.GaussianWaist
my_pop_settings.SetParameterValue(0, 1.23) # Waist X
my_pop_settings.SetParameterValue(1, 4.56) # Waist Y
my_pop_settings.SetParameterValue(2, 0.1) # Decenter X
my_pop_settings.SetParameterValue(3, 0.2) # Decenter Y
my_pop_settings.SetParameterValue(4, 0.8) # Aperture X
my_pop_settings.SetParameterValue(5, 0.9) # Aperture Y
my_pop_settings.SetParameterValue(6, 1.1) # Order X
my_pop_settings.SetParameterValue(7, 1.2) # Order Y

# Apply settings and run POP

Note that SetParameterValue indices definition change based on the selected BeamType. For Gaussian Angle, you only have 4 paramters, the indices are from 0 to 3 (Angle X, Angle Y, Decenter X, Decenter Y).

I hope this helps.

Take care,