How to locate geometry errors part II - design examples

This article presents examples of the most common reasons why a user would receive a "geometry error" warning from OpticStudio. This is part two in a series regarding this error, and should be read after the first article (linked in the introduction).

This article is accompanied by a zip archive containing sample files which demonstrate some of the more common geometry errors.

Authored By Dan Hill


Article Attachments


This is article two of a two-part series on geometry errors. It is recommended that you read “How to locate geometry errors part I” prior to working through the examples provided in this article.

As is outlined in part I, there are 3 common reasons for geometry errors: 

  • Invalid placement of entry and exit ports
  • Invalid placement of sources
  • Invalid construction of solid objects

This article will show a few example systems that feature these errors. 

The hybrid system

If geometry errors arise when working in hybrid mode in OpticStudio, it is most likely due to some improper placement of the entry and/or exit ports. Determining whether or not an entry and exit port is misplaced in OpticStudio is straightforward. To demonstrate this, we will use the provided sample file "Revised Core Clad Fiber_Geometry Error.ZMX"

Note:  This file is a revision of the “Core clad fiber.ZMX” file located in the {Zemax}\Samples\Non-Sequential\Fibers directory. A few alterations were made to demonstrate the errors associated with misplacing entry and exit ports.

Once you have downloaded the file, open the file from within OpticStudio. This file uses a hybrid mode to trace a sequential cone of rays through a K5/FK3 Core/Clad fiber.


Note that upon opening the file, a geometry error is issued because there is a deliberate invalid placement of the system’s exit port. Exit the error windows, and note that the sequential rays are not reaching the detector plane (the IMA surface):


Currently, the Ignore Errors option is turned ON. Since OpticStudio will continually issue an error until the problem is resolved, it is frustrating to continually have to close every error dialog each time the system is updated. Therefore, the Ignore Errors option is user-selectable. Let’s turn Ignore Errors OFF so that OpticStudio will issue the geometry error in the current lens file. As a reminder, Ignore Errors may be turned on/off by selecting “Ignore Trace Errors” on the NSC Editor menu bar. Note that when the button is highlighted, it is indicative of Ignore Errors being turned ON.


Once Ignore Errors has been turned OFF, update all windows by pressing Ctrl+Shift+U on the keyboard. Upon doing so, OpticStudio will issue the following error message:


The hybrid system II

Let’s review the information we have received from the geometry error in the current example file:


The error is occurring at the NSC group surface 2 (which happens to be the only NSC group in this file). The object at which the error is detected is Object 2, the Cylinder Volume object which represents the core of the fiber.

As we try to diagnose the error, temporarily turn ON the Ignore Errors in the NSC Editor.

Now, we already know that this error is due to the misplacement of ports, but let’s assume that we had no idea this was the case. From the error message, we know that the error is occurring within your NSC group, so we can concentrate on the objects listed in the NSC Editor: Component Group on Surface 2. In addition (as we noted earlier), in a hybrid mode design, geometry errors are most often due to misplacement of the entry and/or exit ports. Always first check the locations of these ports relative to the objects in your NSC group!

You may choose to draw the entry and exit ports by changing the “Draw Ports?” flag on the NSC surface in the LDE. A flag of 0 will draw neither the entry or exit port. A flag of 1 will draw just the entry port. A flag of 2 will draw just the exit port and a flag of 3 will draw both. Change the flag in the current example to 3.


Update the 3D Layout and highlight the entry port by moving your cursor to the NSC surface in the LDE. The entry port is currently co-located with the front surface of the fiber, which is an acceptable condition. In general, it is desirable to offset both ports slightly from any object within the NSC group.


Since the entry port is not affecting the ray trace, let’s check the exit port location for possible flaws.

The hybrid system III - The exit port

Move the cursor in the LDE to Surface 3 to highlight the exit port within the 3D Layout.  It is apparent from the 3D Layout that the rays are being terminated at the exit port, which is a good indication that the positioning of the exit port is invalid.


The position of the exit port is controlled by the Exit Loc X, Y, Z and Exit Tilt X, Y, Z parameters on the NSC surface in the LDE. Currently the Exit Loc Z is set to 50mm, while all other position and tilt parameters are set to zero. The locations and tilts are relative to the entry port. Since the Z length of both the core and clad are also 50mm, the exit port is currently co-located with the back face of the fiber.



The exit port must be separated by at least the Glue Distance from any portion of the Non-Sequential objects.

For the purposes of this design, it is not critical to place the exit port so close to the back face of the fiber. We may simply change the Exit Loc Z of the exit port to 50.5, and absorb this added thickness by changing the Thickness on Surface 3 by -0.5mm. Update the 3D Layout to verify that these changes did indeed affect the ray trace.


Lastly, turn the Ignore Error flag OFF from the NSC Editor menu to ensure that the geometry error has been fixed due to the changes that have been made. Once the Ignore Errors flag is turned off, press Ctrl+Shift+U to update all windows. OpticStudio should no longer issue a geometry error, and rays can now be evaluated at the image plane.


Misplaced sources

There are a few reasons as to why a geometry error might be issued when working in purely Non-Sequential OpticStudio. Sometimes an improper placement of a source, or the mis-use of the “Inside Of” flag will generate geometry errors. To demonstrate such possibilities, the following sample file will be used: "Revised LED_model_Geometry Error.ZMX"

Note: This file is a revision of the “led_model.zmx” file located in the {Zemax}/Samples/Non-Sequential/Sources/ directory. A few changes were made to demonstrate the errors associated with the misplacement of the NSC sources.

Once you have downloaded the file, open the file from within OpticStudio. This file uses some of the purely Non-Sequential capabilities in OpticStudio to model two LEDs illuminating onto a single detector. Note that upon opening the file, OpticStudio automatically performs a NSC ray trace.


Currently, the Ignore Errors option is turned ON to prevent the geometry error dialog from continually being issued. Even from the Shaded Model plot, it appears as if the flux on the detector plane is strikingly too circular, almost as if the rays from the topmost LED are not being accounted for. Also take note that the Total Power reported on the Detector Viewer is roughly 5mW, which is one quarter of the combined total power from the two sources.


To see how much power is actually lost due to errors, let’s re-run the Ray Trace/Detector Control (which performs a Monte Carlo Ray Trace). To open the Ray Trace Control dialog, click “Analyze...Ray Trace”. Check the following options in the dialog.


Click on “Clear & Trace” and let the ray trace complete.  Note that your results may be slightly different due to the random generation of rays!  Nevertheless, you should obtain similar results.


Once the ray trace is complete, OpticStudio will report the lost energy due to thresholds as well as energy lost due to errors. The lost energy due to errors is roughly 10mW, which is extremely significant since it serves as roughly half of the combined power from the two sources.  It is critical that these errors be addressed immediately so that accurate results may be obtained.

Misplaced sources II

To locate the cause of the errors, turn Ignore Errors OFF and rerun the ray trace.


Take note of the information in the dialog, close all error message windows by pressing “OK.”  Turn Ignore Errors back ON. This particular ray failure originated from Source Object 13, which is the Source Volume representing the source of the upper LED. In addition, the error occurred at object number 11. Object 11 represents the LED body the upper LED.

Zoom up on the region where Source Volume 13 is located, to see if anything looks suspicious.  It is very obvious that the Source Volume is straddling the boundary of a volume object, which is an unsatisfactory condition.  All rays emanating from a specific source must emanate from inside the same volume; no two rays from a single source can initially start inside of different volume objects.


The Source Volume object should be touching the contact wires (Objects 16 and 19). Change the Z Position of the Source Volume 13 to 1.6 so that it no longer straddles the boundaries of the die and instead sits in contact with the contact wires.

In addition to this, it is important to note that the geometry errors will not be solved at this point.  The upper LED emitter source object is inside the LED body, and needs to be indicated as such.  The upper LED body is described by Object 11. Change the “Inside Of” flag in the NSC Editor to 11 for the Source Volume 13.


Re-run the Monte Carlo Ray Trace. The chances of experiencing a geometry error have been greatly reduced.  And, as you can see, the lost energy has been reduced by many orders of magnitude.  Take note that the lost energy is so small, that it can be neglected altogether, and the results at the Detector Viewer can be evaluated with great certainty.



It is important to note that geometry errors may indicate a serious flaw in the system being traced. However, some perfectly good systems occasionally have a few rays fail. This is primarily due to the fact that these rays are incident exactly upon boundaries between facets or surface and accurate intercept points are not possible to compute. These rays are generally "trapped" internally by OpticStudio, and are absorbed or terminated. For the most part, the amount of “lost energy” associated with these rays is small relative to the total power of all the sources defined in the design. Therefore, these rays can be safely ignored, as they do not have much significance in the final system results.

Invalid user defined objects

User-defined objects, such as Polygon Objects or imported objects, are used quite frequently.  However, it is possible that these objects are improperly defined, and OpticStudio encounters a geometry related error when tracing rays through these invalid objects. To demonstrate such a geometry error, the sample file "Revised Interferometer.ZMX" is attached.

Note: This file is a revision of the “Interference Example 1 – A Simple Interferometer.zmx” file located in the {Zemax}/Samples/Non-Sequential/Coherence Interference and Diffraction/ directory. A few modifications were made to demonstrate the errors associated with tracing rays through user-defined objects.

Download the interferometer file as well as the “Splitter_2.pob” file. Make sure you save the .POB file into your {Zemax}/Objects/Polygon Objects/ directory.

Once you have downloaded the file, open the file from within OpticStudio. This file uses some of the purely Non-Sequential capabilities to display interference fringes at the detector planes. Note that upon opening the file, OpticStudio automatically issues a geometry error.  Upon accepting the geometry error, the Non-Sequential ray trace is initiated. It is immediately obvious that the results on the Detector Viewer aren’t quite as expected. So, let’s investigate the geometry error in more detail.


Turn Ignore Errors OFF for a moment and run a ray trace.


In this pure Non-Sequential system, it will be useful to diagnose the problem by observing the exact path the errored ray takes through the interferometer. To do this, we will use the Create Error Ray tool found in Setup tab:


Upon doing so, OpticStudio adds a Source Ray to the NSC Editor whose position and direction cosines exactly match those reported in the geometry error message:




In addition, OpticStudio has turned off the Source Rectangle by setting the # of Layout and Analysis Rays to zero.


As a result, we have a single, invariant ray which produces a geometry error. To confirm this, update the system once again and check that the geometry error message is issued once again with the exact same starting coordinates and direction cosines.

Invalid user defined objects II

Now that the Source Ray is defined, we can more easily analyze the reason for the error.

Turn Ignore Errors back ON, open the Ray Trace Control dialog (Analyze...Ray Trace) and run a Monte Carlo ray trace using the following settings. Make sure to “Save Rays” so that the Source Ray may be analyzed in more detail after the completion of the trace.


To evaluate the propagation of the ray, open the Ray Database Viewer (Analyze...Ray Database Viewer).  Make sure that the previously saved filename is listed as the “File:” in the settings of the Ray Database Viewer:


Even as we follow the propagation of the ray in the Ray Database Viewer, it is already known (from the geometry error), that the problem occurs at Object 5.  It is apparent from the Rdb that when the ray reaches Object 7 (the Detector Rectangle), OpticStudio assumes that the ray is inside of Object 5, as is denoted by the “In” and “Hit” columns.  After passing through the detector, the ray becomes terminated, indicated by the * in the “Z” column of the viewer.


The ray should have exited the Polygon Object (Splitter_2.POB) prior to hitting the detector.  Therefore, it is imperative that the definition of the .POB file be reviewed. From the Shaded Model, it appears that the splitter is missing its entire back face, which is most likely the cause of the problem.


Review the definition of the Polygon Object by viewing the .POB file in the text viewer. Through careful evaluation of the defined faces and syntax, it is apparent that the line representing the back face of the polygon object is “commented” out.


Remove the “!” from the line indicated above and re-save the .POB file. Once it is saved, click on “Reload All Objects” in the NSC Editor.

Remove the Ignore Errors flag and update the system. OpticStudio should no longer issue a geometry error. Thus, the Source ray can be removed, and the system analysis can once again be performed with the Source Rectangle.


This is a good example of how a user error in the definition of an object can cause problems within the ray trace. In this particular example, the ray never hit the back face of the Polygon Object.  Therefore, as far as OpticStudio was concerned, the ray never exited the Polygon Object.  The problem is, OpticStudio internally continued to trace this ray, but never found a point in which the ray finally exited the volume. Thus, a geometry error was identified.

Previous Article: How to locate geometry errors: part I


Was this article helpful?
2 out of 3 found this helpful



Please sign in to leave a comment.