a newbie's experience

[asebian]

I have started playing around with this library recently and I'm still trying to get my head around how to use it and what I am not supposed to do. I got a first idea by going through the example code given in the documentation but without the chapter "Models and Representations" I would have to stick closely to the examples and I certainly would not be able to use it as a tool. But there are still a lot of assumptions I have to make. I try to back my guesses as good as I can by having a glimpse at the source but since Python does not provide private methods it's not always clear what's part of the API and what's for internal purposes. Are there any conventions that I can follow, like "names with leading underscores are private" for instance, or "stick to getters and setters"?

To my understanding the optical system aka OpticalModel can be configured and even altered using one of 5 interfaces (4 models and the specs) at a time. After changes were made to one of the models its method 'model_update' must bet called before another interface can be used. The fact that OpticalModel itself has an 'model_update' method seems counterintuitive to me. (Are updates never ambiguous anyway?)

Sometimes I might be using the library in a way it is not meant to be used. Here is a use case:

I read that single meniscus lenses were used in early photography and so I downloaded a Zemax file in order play with it. Contrary to the file the lens was used with the concave side facing the object. Instead of editing the file directly I decided to try to flip the lens in Python. Since the ElementModel does not yet provide that feature I tried using the SequentialModel.

from rayoptics.environment import *
opm, info = open_model("LE1234-A-Zemax(ZMX).zmx", info=True)
info
sm = opm['seq_model']
print('SequentialModel:')
sm.list_model()
print('\nSurfaces:')
sm.list_surfaces()
print('\nGaps:')
sm.list_gaps()

[snip]

The SequentialModel was as expected, the OpticalSpecs not so.

print('\nSpecSheet:\n', opm.specsheet, sep='')

SpecSheet:
infinite conjugates:
imager: IdealImager(m=-0.0, s=-inf, sp=99.6611978424791, tt=inf, f=99.6611978424791)
imager inputs: {'s': -inf}
frozen imager inputs: [True, True, True, True, False]
etendue inputs:
field: {'object': {'angle': 0.0}, 'image': {}}
aperture: {'object': {'pupil': 22.86}, 'image': {}}
etendue values:
field: {'object': {'angle': 0.0}, 'image': {'height': 0.0}}
aperture:
object: {'pupil': 22.86, 'NA': 0, 'f/#': 0}
image: {'f/#': -4.359632451552017, 'NA': 0.11394165154571817, 'pupil': -22.86}

What are the 'etendue inputs' and 'etendue values' and how are they related toOpticalSpecs's FieldSpec and PupilSpec properties? Why do the wavelengths and focus range specification not show up? If I want to make changes, shall I edit the specsheet or replace the spec objects with new instances?

Editing the surface values in place seems to work (in that case) but since there are no getters and setters I shied away from doing so and followed the code sample from chapter "Triplet example".

t= sm.gaps[0].thi
srfc1 = [-sm.ifcs[2].profile.cv, sm.gaps[1].thi, 'N-BK7', 'Schott']
srfc2 = [-sm.ifcs[1].profile.cv, sm.gaps[2].thi]
wsp = opm['optical_spec']['wvls']

opm = OpticalModel(specsheet=opm.specsheet)
opm['optical_spec']['wvls'] = wsp

sm = opm['seq_model']
sm.gaps[0].thi = t
sm.add_surface(srfc1)
sm.set_stop()
sm.add_surface(srfc2)
sm.update_model()

print('SequentialModel:')
sm.list_model()
print('\nSurfaces:')
sm.list_surfaces()
print('\nGaps:')
sm.list_gaps()
print('\nSpecSheet:\n', opm.specsheet, sep='')

SequentialModel:
c t medium mode zdr sd
Obj: 0.000000 1.00000e+10 air 1 0.0000
Stop: -0.012161 3.59000 N-BK7 1 11.430
2: -0.031114 92.6947 air 1 11.537
Img: 0.000000 0.00000 1 0.80125

[snip]

Was this really the official way to get and set the object distance?
Why are the semi diameter values different now?

Without detailed understanding of the inner processes I always have that feeling of uncertainty whether I've used the tool correctly or in a way that leads to unexpected results. The amount of thought and expertise contained in this library is definitely worth the effort of a cosmetic overhaul. If I had better understanding and weren't new to Python I would volunteer.

Cheers!

[mjhoptics]

Thanks for taking the time to write this up. I may this up into several responses, cause it's late here and there are a variety of questions :-)

First, as far as python is concerned, I've tried to follow the PEP8 guidelines and more generally items in the Effective Python book. One aspect of the latter (among many) is the advocacy of public instance variables instead of getters and setters. There are a few cases where I've transitioned to python properties, where additional flexibility was needed. Certainly one aspect of working in a python environment (vs using a compiled program) is that you can get at everything. You clearly appreciate this and are understandably uneasy. Almost all class instance variables in ray-optics are public; they really should be public attributes. There are a few cases where a leading underscore is used; this can be related to changing an attribute to a property. So don't feel bad about changing values directly; that's how its done.

To your specific example, flipping a single lens around is the most straightforward using the sequential model, sm. For your case you can do the following:
sm.ifcs[2].profile.cv, sm.ifcs[1].profile.cv = -sm.ifcs[1].profile.cv, -sm.ifcs[2].profile.cv
sm.ifcs[2].max_aperture, sm.ifcs[1].max_aperture = sm.ifcs[1].max_aperture, sm.ifcs[2].max_aperture
This swaps and flips the sign of the curvatures and swaps the semi-diameters.
After making changes to the model, such as above, you should update the optical model, opm.
opm.update_model()
There are various derived data, such as first order properties and ray traces for layout drawings, that are done as a result of update_model(). This is used heavily in the rayoptics app, built on top of the pyqt5 package.
As far as optical specifications are concerned, you can update the Pupil and Field Specs directly and (following a opm.update_model()) the system will reflect the new values. The Etendue stuff is sort of experimental and parallels the other OpticalSpec stuff.
Thanks again for your comments.
Mike

[asebian]

Thanks for your reply, Mike.

According to the source code opm.update_model() calls update_model() on all the models, the specifications, and updates the specsheet if necessary. This happens in a fixed, specific order. Let's say I've changed ele_model. Wouldn't opm.update_model() update elem_model to the settings in seq_model and effectively undo my changes? Maybe this wouldn't happen at the moment but in a future version of the library. When elements have flipping functionality implemented for instance. ;-)

[mjhoptics]

I would continue to use update_model() on the opm. I've recently added keyword args to the arg list of update_model and anticipate adding a keyword like source|originator|sender to identify which model changed, for cases where that's important.

[asebian]

Continuing with the use case I have successfully flipped surfaces of the lens.
Now I specify the sensor I am going to use.

osp = opm['optical_spec']
osp['fov'] = FieldSpec(
    osp, 
    key=['image', 'height'], 
    value=21.6, 
    flds=[0., 0.707, 1.], 
    is_relative=True
)
osp.update_model()

This seems to work just fine.
After plotting some diagrams I want to see the results when the lens has been stopped down.

osp['pupil'] = PupilSpec(
    osp, 
    key = ['object', 'f/#'], 
    value = 11
)
opm.update_model()

Obviously this is not the right approach, because most of my plotting attempts throw errors now.
Is there a way to add a diaphragm?

[mjhoptics]

You probably want to change the f/# in image space. So
key = ['image', 'f/#']
For infinite conjugate systems, object space NA or f/# doesn't make much sense, although I don't try to prevent or warn about it. For finite conjugate systems both NA and f/# should work.

[asebian]

I assumed that f/# would always equal focal length divided by entrance pupil diameter for infinite conjugate systems.
Does f/# in image space mean focal length divided by exit pupil diameter?
I guess I should start thinking in NA since f-numbers are a photography concept.

[mjhoptics]

The f/# can be expressed as:
f/# = -1/(2*slp_k)
where slp_k is the paraxial slope of the marginal ray in image space (i.e. exiting the optical system). The object space f/# is computed with the marginal ray slope in object space, which is zero for an object at infinity.