tutorial and unit test for mode sources using DiffractedPlanewave object

[oskooi]

Adds a tutorial and unit test based on the discussion in #2069, particularly this comment.

[codecov-commenter]

Codecov Report

Merging #2072 (f700429) into master (5275f43) will increase coverage by 0.08%.
The diff coverage is n/a.

@@            Coverage Diff             @@
##           master    #2072      +/-   ##
==========================================
+ Coverage   73.25%   73.33%   +0.08%     
==========================================
  Files          17       17              
  Lines        4902     4902              
==========================================
+ Hits         3591     3595       +4     
+ Misses       1311     1307       -4     

Impacted Files	Coverage Δ
python/simulation.py	77.05% <0.00%> (+0.12%)	⬆️
python/source.py	96.21% <0.00%> (+0.75%)	⬆️

[stevengj]

This line seems unnecessary — since the source spans the whole width of the cell, it should automatically set the corresponding k component of the eigenmode source, whereas the orthogonal k component will be found by the mode solver.

[oskooi]

Actually, it turns out that eig_kpoint=k is necessary because of the line before it: direction=mp.NO_DIRECTION. Removing eig_kpoint but keeping direction=mp.NO_DIRECTION produces this error:

meep: invalid direction in add_eigenmode_source

This is because setting direction=mp.NO_DIRECTION also requires specifying an eig_kpoint.

Removing both eig_kpoint and direction=mp.NO_DIRECTION causes the test to fail because the default direction=mp.AUTOMATIC assumes that the k_point is always perpendicular to the line monitor which it is not. This leads to a wrong mode to be used for the mode decomposition which causes the test to fail:

======================================================================
FAIL: test_mode_source (__main__.TestDiffractedPlanewave)
----------------------------------------------------------------------
Traceback (most recent call last):
  File "/meep/python/tests/test_diffracted_planewave.py", line 231, in test_mode_source
    self.assertAlmostEqual(tran_bandnum,
AssertionError: 380.9518159531796 != 325.7552498084876 within 4 places (55.19656614469204 difference)

The existing setup is therefore correct.

[stevengj]

because the default direction=mp.AUTOMATIC assumes that the k_point is always perpendicular to the line monitor which it is not.

I don't follow — if the monitor region spans the whole width of the cell, for Bloch-periodic boundaries it sets the parallel components of k to those of the boundary conditions, and then solves for the perpendicular component, no?

[oskooi]

I think the issue is related to these lines in add_source:

meep/python/simulation.py

Lines 2464 to 2468 in 91d36ba

	if isinstance(src, EigenModeSource):
	if src.direction < 0:
	direction = self.fields.normal_direction(where)
	else:
	direction = src.direction

That is, when creating an EigenModeSource with the default direction of mp.AUTOMATIC (which has a value of -1), the direction is assigned to the normal direction of the monitor and thus eig_kpoint is ignored.

[oskooi]

The observed behavior is a feature and not a bug. See #2107 (comment).