add stop_when_energy_decayed termination condition

[oskooi]

For simulations involving a large computational cell in which the sources and the monitors are separated by a large distance (i.e., tens to hundreds of wavelengths), the available termination conditions stop_when_fields_decayed and stop_when_dft_decayed are inadequate because they often stop the simulation prematurely as the fields have not had sufficient time to propagate throughout the entire cell.

This PR introduces a new termination condition stop_when_energy_decayed which tracks the electric energy over the entire cell. However, the cost of calling the function electric_energy_in_box at every timestep to obtain the energy can be significant: in tests, ~20X slow down in the time-stepping rate compared to using a fixed runtime termination condition.

The performance penalty notwithstanding, some preliminary tests have demonstrated that this feature provides an improvement compared to using a large, fixed, and overly conservative run time chosen arbitrarily.

[stevengj]

The cost of calling the function electric_energy_in_box at every timestep to obtain the energy is trivial and thus there is no performance penalty for using this new feature.

Is there any particular reason to call it on every timestep?

Also, note that you might want to look at field_energy_in_box instead of just the electric energy. (For example, if you have a monopole-like resonant mode, the cavity energy oscillates back and forth between the electric and magnetic fields.)

[oskooi]

Is there any particular reason to call it on every timestep?

Given the performance penalty of calling field_energy_in_box which requires looping over all grid points, it is now called at dt time units (which is a required parameter) rather than at each time step.

Also, note that you might want to look at field_energy_in_box instead of just the electric energy.

Done.

[stevengj]

What's going on with all of these Union -> Optional changes? Seems like they belong in a separate PR.

[oskooi]

#1919 added the Optional type hint to various parameters of the Simulation constructor such as geometry, sources, etc. The type hint Optional[Type] is equivalent to Union[Type, None] according to PEP 484. The default values of each parameter are parsed by the ast.parse() function in doc/generate_py_api.py. Because I have been using different versions of Python (3.5, 3.8) to call generate_py_api.py in various PRs which involve updating the docs (i.e., #1958, #1926, etc.), the different Python grammars seem to have been interchanging Optional and Union. The same thing seems to be happening again in this PR. ast.parse() is also inserting an extra space before and after the = sign. We therefore probably need to edit generate_py_api.py in a separate PR to ensure consistent parsing of the type hints and thus avoid these unnecessary changes.

[oskooi]

Those changes were caused by running make python_api_doc which was necessary to update the markdown page in the documentation.