add antenna gain and efficiency figures of merit

[dmarek-flex]

added more fields to DirectivityData to allow for retrieving the partial radiation intensities, directivities, and helpers to compute gain given a supplied power. Radiated power is based on flux but now includes the direction of the projection monitor, when it is 2D.

Antenna parameters can be extracted by using the TerminalComponentModeler, where the concept of a port is needed to calculate the incident and reflected powers.

For more advanced antennas, we will need the ability to calculate results with a linear combination of ports excited.

Checklist:

• Make gain and efficiency calculations available
• Fix backend tests with new API
• Simplify notebooks by using new API
• Add post processing support for generating far field response using multiple ports with different complex amplitudes
• Add tests and example to notebook demonstrating post processing step for multiple port excitations

Relevant PRs:

• Notebook PR for how the changes can be used.
• Backend Test PR for changed tests.
• New backend test PR

[dmarek-flex]

Let's start of the review with RF. Not too complicated of changes, but maybe there is room for improvement on how we package the data. See this notebook PR for how the changes can be used.

[weiliangjin2021]

1st round of review. All look nice!

[dmarek-flex]

@weiliangjin2021 @dbochkov-flexcompute Assuming all tests pass I am done the main changes I wanted to make to enable these features. Anything else I do will be typos and docstring improvements if I see any.

[weiliangjin2021]

Very remarkable work! A few minor comments below

[weiliangjin2021]

One architecture question: AntennaParametersData seems more suitable to be placed in monitor_data.py?

[dmarek-flex]

One architecture question: AntennaParametersData seems more suitable to be placed in monitor_data.py?

I think that is not a bad idea, but it seems like monitor data is usually associated with a monitor that directly creates it, which is the main reason I did not put it there. In some sense, AntennaParametersData is created by a monitor plus a TerminalComponentModeler. I am leaning towards leaving it in the microwave plugin. Alternatively, maybe I could add it to the components/microwave folder to keep it separate from the other monitor data.

@daquinteroflex @yaugenst-flex Any suggestions from outside the RF world?

[daquinteroflex]

So there's a few reasons I'll text privately, but basically everything RF specific like this, imo should go under

tidy3d/components/microwave/
    data/
       ...
       # however we want to structure it in here.

Basically imagine that directory is a small world of its own that represents the current "tidy3d/components" and should be extended in a kind of self contained domain if possible

[dmarek-flex]

@daquinteroflex @weiliangjin2021 Added a new commit improving docs and moving/renaming AntennaMetricsData. Does that seem consistent with other solver stuff? Later I will move the path integral code as a tool into that folder as well I think.

The one unique thing about AntennaMetricsData is that it is not directly created by a Monitor, but I ended up using the same kind of file naming scheme as other types of MonitorData. A little unsure about that.

[daquinteroflex]

Nice, the reorganization makes sense! So for now, unless there's going to be a set of mixed monitor + other things data types - this still fits in logically within microwave/data/monitor_data.py.

In terms of naming, it's still a "data" container as such. If we believe this concept of "metrics data" might be extended, this could be a good name as you have it? It also kind of makes sense because it's like a "DeviceMetricsData" type. Can always refactor file location in the future depending how this changes too to device_data.py or metrics_data.py too.

[dmarek-flex]

@daquinteroflex Yea I like metrics since it is shorter than what I had before and could be used in the future for other specific types of devices.

[dbochkov-flexcompute]

A little bit of nitpicking, technically functions

• scale_fields_by_freq_array
• get_phi_slice
• from_spherical_field_dataset
• calc_radiation_efficiency
• from_directivity_data
• compute_power_wave_amplitudes_at_each_port
• compute_port_VI
• compute_power_wave_amplitudes
• compute_power_delivered_by_port

are exposed to the user, so ideally they should have Parameters and Returns sections in docstrings. Or you could just add underscore to those ones that don't really need to be accessible by the user. Otherwise everything looks great to me