Characterizing the orientation of angled sources is the wrong kind of difficult

[so-rose]

First of all, thank you for building and open-sourcing an amazing tool! It is a pleasure to work with, and the documentation is also excellent.

Describe the bug
I'm writing a Blender-integrated tool for simulation design using tidy3d (BSc thesis), within which it is important to understand which directions angled sources are going (without a round-trip by the web-interface).

To produce a visualization (and myself understand where wave are being nudged), it becomes quite important to be able to generate the $\mathbf{k}$ and $\mathbf{p}$ vectors that characterize the wavevector and polarization direction, for any choice of:

• Injection Half-Axis: $\pm x,z,y$
• $\theta$: Physicist-convention inclination from the inj. half-axis in radians.
• $\varphi$: Physicist-convention rotation from the plane orthogonal to the injection half-axis (winding swapped for $\pm y$)
• $p_a \in \text{radians}$ s.t. $\mathbf{p}$ is the result of this polarization angle applied onto a piecewise split between optics-convention (at normal incidence) and principled

Whether due to unclear documentation, the vastness of spherical coordinate system conventions, or particular mistakes I made when trying to choose (discontinuous) zenith/azimuth reference axes and their influencing factors, I was spending hours running into a brick wall trying to describe it mathematically.

In the end I felt the need to fully reverse engineer the winding direction and initial axes per-injection-half-axis in order to become satisfied with the consistency of my characterization. This was constructed fully from performing click-and-see experiments on a single plane wave in a dummy sim within the web interface:

	$+x$	$-x$	$+y$	$-y$	$+z$	$-z$
$\theta>0$: ax. $p_a=0$	$-y$	$-y$	$-x$	$-x$	$-x$	$-x$
$\theta>0$: ax. $p_a=0$	$-z$	$+z$	$+z$	$-z$	$-y$	$+y$
$\theta+$ wind	$z$ CCW	$z$ CCW	$z$ CW	$z$ CW	$y$ CCW	$y$ CCW
$\varphi+$ wind	$x$ CCW	$x$ CCW	$y$ CW	$y$ CW	$z$ CCW	$z$ CCW
$\theta=0$: ax. $p_a=0$	$+y$	$+y$	$+x$	$+x$	$+x$	$+x$
$\theta=0$: $p_a$ wind	$x$ CCW	$x$ CW	$y$ CCW	$y$ CW	$z$ CCW	$z$ CW

Is that a bug?
Well, to me, it's a property of the software that causes it to behave erratically. I know, one person's bug is another person's feature; the distinction is not for me to judge, really.

All I can say is that I simply cannot see myself arriving at an intuitive way of defining non-inj-axis-angled sources in tidy3d, in Python or otherwise, without a "click/plot" loop that eventually "magically" (as a function of personal mental model clarity) makes the orientation look reasonable.

Especially: What I'm almost certain is an optics-oriented convenience - placing $s$ and $p$ polarizations at $0,\ \frac{pi}{2}$ when $\theta = 0$ - ends up feeling very jumpy, as a slight adjustment to $\theta$ easily leads a person to believe that something is broken, and does very little to support any emerging mental model of how angled sources are oriented.

Piecewise discontinuities are also not great for ex. gradient-based optimization of $\theta$ in particular.

To Reproduce
Steps to reproduce the behavior (it's a UX bug, fundamentally, so this is a theoretical experiment involving a human QA tester):

1. Set a new QA tester to characterize an angled source's wavevector and polarization vector from the spherical inputs (also inj half-axis and so on).
2. Ask them to reconstruct a procedure, just using mathematical operations, for how to find the two vectors given only the information provided via official docs.
3. Track their knowledge graph, and profile the time it takes to discover the various nuances.

Expected behavior
In a word, clarity.

Firstly: Is my table correct? I may have misread some things! I'm sure there's a set of transforms that quite neatly encapsulates all of this using a piecewise defined spherical-to-cartesian transform w/inj-half-axis dependent zenith/azimuth (believe me, I tried!), and maybe some phase corrections on well-chosen axis-angle rotations. But fundamentally, it's first of all important to me that the brute-force approach isn't wrong.

It would be an immense help to have whatever's going on documented in full mathematical and physical clarity. In my opinion, the descriptions in pages like the plane wave docs were a vastly insufficient support for my mental model regarding the plane wave orientation.

I could imagine a very helpful UX thing could be allowing the specification of a direction as a global ISO 80000 spherical coordinate system, which could then internally be matched to an injection half-axis + special spherical coordinates. Perhaps an optional Orientation-type object could be a way of generalizing this, and it could be an optional input that overrides the existing inputs - keeping backwards-compatibility and all that (an Orientation object could also encapsulate other nice things when dealing with / composing orientations, like accepting / producing quaternions and/or a proper rotation matrix. A lot of physics deals with a lot of orientations, it likely wouldn't be off-base).

Desktop (please complete the following information):

• OS: Debian Linux 10
• Version: 2.6.1 (PyPI)

Additional context
I hope this kind of thing is constructive and helpful. I'm happy to provide more context if needed.

[tylerflex]

@so-rose thanks for raising the issue. Does #1694 seem like it will fix at least your discontinuity issue?

[tylerflex]

Will close as #1694 is merged, so should be fixed in 2.7.0 feel free to reopen if it is an issue in the future.

[so-rose]

Hi @tylerflex, thank you for the prompt response and fix! At first glance this seems to fix the issue; since the client orientation seems to actually have been misbehaving (and now fixed), and not merely "correct but hard to understand", it's safe to presume all is well.

I'll try to characterize everything again just in case, and if anything's amiss then I'll open a new issue. I'm just happy it's not some obvious oversight on my part!

In any case, I'm glad the report could be of use.