tidy3d.DirectivityData

class DirectivityData

Bases: FieldProjectionAngleData

Data associated with a DirectivityMonitor.

Parameters:

• attrs (dict = {}) – Dictionary storing arbitrary metadata for a Tidy3D object. This dictionary can be freely used by the user for storing data without affecting the operation of Tidy3D as it is not used internally. Note that, unlike regular Tidy3D fields, attrs are mutable. For example, the following is allowed for setting an attr obj.attrs['foo'] = bar. Also note that Tidy3D` will raise a TypeError if attrs contain objects that can not be serialized. One can check if attrs are serializable by calling obj.json().

• monitor (DirectivityMonitor) – Monitor describing the angle-based projection grid on which to measure directivity data.

• Er (FieldProjectionAngleDataArray) – Spatial distribution of r-component of the electric field.

• Etheta (FieldProjectionAngleDataArray) – Spatial distribution of the theta-component of the electric field.

• Ephi (FieldProjectionAngleDataArray) – Spatial distribution of phi-component of the electric field.

• Hr (FieldProjectionAngleDataArray) – Spatial distribution of r-component of the magnetic field.

• Htheta (FieldProjectionAngleDataArray) – Spatial distribution of theta-component of the magnetic field.

• Hphi (FieldProjectionAngleDataArray) – Spatial distribution of phi-component of the magnetic field.

• medium (Union[Medium, AnisotropicMedium, PECMedium, PoleResidue, Sellmeier, Lorentz, Debye, Drude, FullyAnisotropicMedium, CustomMedium, CustomPoleResidue, CustomSellmeier, CustomLorentz, CustomDebye, CustomDrude, CustomAnisotropicMedium, PerturbationMedium, PerturbationPoleResidue, LossyMetalMedium, Medium2D, AnisotropicMediumFromMedium2D] = Medium(attrs={}, name=None, frequency_range=None, allow_gain=False, nonlinear_spec=None, modulation_spec=None, viz_spec=None, heat_spec=None, type='Medium', permittivity=1.0, conductivity=0.0)) – Background medium through which to project fields.

• is_2d_simulation (bool = False) – Indicates whether the monitor data is for a 2D simulation.

• projection_surfaces (Tuple[FieldProjectionSurface, ...]) – Surfaces of the monitor where near fields were recorded for projection

• flux (FluxDataArray) – Flux values that are either computed from fields recorded on the projection surfaces or by integrating the projected fields over a spherical surface.

Example

>>> from tidy3d import FluxDataArray, FieldProjectionAngleDataArray
>>> f = np.linspace(1e14, 2e14, 10)
>>> r = np.atleast_1d(1e6)
>>> theta = np.linspace(0, np.pi, 10)
>>> phi = np.linspace(0, 2*np.pi, 20)
>>> coords = dict(r=r, theta=theta, phi=phi, f=f)
>>> coords_flux = dict(f=f)
>>> values = (1+1j) * np.random.random((len(r), len(theta), len(phi), len(f)))
>>> flux_data = FluxDataArray(np.random.random(len(f)), coords=coords_flux)
>>> scalar_field = FieldProjectionAngleDataArray(values, coords=coords)
>>> monitor = DirectivityMonitor(center=(1,2,3), size=(2,2,2), freqs=f, name='n2f_monitor', phi=phi, theta=theta)
>>> data = DirectivityData(monitor=monitor, flux=flux_data, Er=scalar_field, Etheta=scalar_field, Ephi=scalar_field,
...     Hr=scalar_field, Htheta=scalar_field, Hphi=scalar_field, projection_surfaces=monitor.projection_surfaces)

Attributes

axial_ratio	Axial Ratio (AR) in the frequency domain as a function of angles theta and phi.
directivity	Directivity in the frequency domain as a function of angles theta and phi.
fields_circular_polarization	Electric and magnetic fields in the circular polarization basis.
left_polarization	Electric far field for left-hand circular polarization (counterclockwise component) with an angle-based projection grid.
radiated_power	Total radiated power in the frequency domain with units of Watts.
radiation_intensity	Radiation intensity in the frequency domain as a function of angles theta and phi.
right_polarization	Electric far field for right-hand circular polarization (clockwise component) with an angle-based projection grid.
attrs

Methods

calc_gain(power_in)	The gain figure of merit for antennas.
calc_partial_gain(power_in[, pol_basis, ...])	The partial gain figures of merit for antennas.
calc_radiation_efficiency(power_in)	Calculate radiation efficiency as the ratio of radiated power to input power.
fields_linear_polarization_tilted(tilt_angle)	Electric and magnetic fields in the linear polarization basis that is rotated at the pole of the radiation sphere by tilt_angle.
from_spherical_field_dataset(monitor, ...)	Creates a DirectivityData instance from a spherical field dataset.
normalize(source_spectrum_fn)	Return a copy of self after normalization is applied using the source spectrum function, for both field components and flux data.
partial_directivity([pol_basis, tilt_angle])	Directivity in the frequency domain as a function of angles theta and phi.
partial_radiation_intensity([pol_basis, ...])	Partial radiation intensity in the frequency domain as a function of angles theta and phi.

Inherited Common Usage

monitor

flux

static from_spherical_field_dataset(monitor, field_dataset)

Creates a DirectivityData instance from a spherical field dataset.

Parameters:

• monitor (DirectivityMonitor) – Monitor defining measurement parameters.

• field_dataset (xr.Dataset) – Dataset containing spherical field components (Er, Etheta, etc.). Must sample the entire spherical surface to compute flux correctly.

Returns:

New DirectivityData instance with computed flux from spherical field integration.

Return type:

DirectivityData

__add__(other)

Form the superposition of two DirectivityData. Flux is recomputed by integrating the projected fields over a sphere.

Note

Intended use is for combining fields from different simulations that were recorded using the same monitor. The returned DirectivityData takes the monitor from self.

normalize(source_spectrum_fn)

Return a copy of self after normalization is applied using the source spectrum function, for both field components and flux data.

partial_radiation_intensity(pol_basis='linear', tilt_angle=None)

Partial radiation intensity in the frequency domain as a function of angles theta and phi. The partial radiation intensities are computed in the linear or circular polarization bases. If tilt_angle is not None, the radiation intensity is computed in the linear polarization basis rotated by tilt_angle from the theta-axis. Radiation intensity is measured in units of Watts per unit solid angle.

Parameters:

• pol_basis (PolarizationBasis) – The desired polarization basis used to express partial radiation intensity, either linear or circular.

• tilt_angle (float) – The angle by which the co-polar vector is rotated from the theta-axis. At tilt_angle = 0, the co-polar vector coincides with the theta-axis and the cross-polar vector coincides with the phi-axis; while at tilt_angle = pi/2, the co-polar vector coincides with the phi-axis.

Returns:

Dataset containing the partial radiation intensities split into the two polarization states.

Return type:

xarray.Dataset

property radiation_intensity

Radiation intensity in the frequency domain as a function of angles theta and phi. Radiation intensity is measured in units of Watts per unit solid angle.

property radiated_power

Total radiated power in the frequency domain with units of Watts.

partial_directivity(pol_basis='linear', tilt_angle=None)

Directivity in the frequency domain as a function of angles theta and phi. The partial directivities are computed in the linear or circular polarization bases. If tilt_angle is not None, the radiation intensity is computed in the linear polarization basis rotated by tilt_angle from the theta-axis. Directivity is a dimensionless quantity defined as the ratio of the radiation intensity in a given direction to the average radiation intensity over all directions.

Parameters:

• pol_basis (PolarizationBasis) – The desired polarization basis used to express partial directivity, either linear or circular.

• tilt_angle (float) – The angle by which the co-polar vector is rotated from the theta-axis. At tilt_angle = 0, the co-polar vector coincides with the theta-axis and the cross-polar vector coincides with the phi-axis; while at tilt_angle = pi/2, the co-polar vector coincides with the phi-axis.

Returns:

Dataset containing the partial directivities split into the two polarization states.

Return type:

xarray.Dataset

property directivity

Directivity in the frequency domain as a function of angles theta and phi. Directivity is a dimensionless quantity defined as the ratio of the radiation intensity in a given direction to the average radiation intensity over all directions.

calc_radiation_efficiency(power_in)

Calculate radiation efficiency as the ratio of radiated power to input power.

Parameters:

power_in (FreqDataArray) – Power supplied to the radiating element in the frequency domain, in units of Watts.

Returns:

Radiation efficiency (dimensionless) in the frequency domain, computed as radiated_power / power_in.

Return type:

FreqDataArray

calc_partial_gain(power_in, pol_basis='linear', tilt_angle=None)

The partial gain figures of merit for antennas. The partial gains are computed in the linear or circular polarization bases. If tilt_angle is not None, the partial directivity is computed in the linear polarization basis rotated by tilt_angle from the theta-axis. Gain is dimensionless.

Parameters:

• power_in (FreqDataArray) – Power, in units of Watts, supplied to the radiating element in the frequency domain.

• pol_basis (PolarizationBasis) – The desired polarization basis used to express partial gain, either linear or circular.

• tilt_angle (float) – The angle by which the co-polar vector is rotated from the theta-axis. At tilt_angle = 0, the co-polar vector coincides with the theta-axis and the cross-polar vector coincides with the phi-axis; while at tilt_angle = pi/2, the co-polar vector coincides with the phi-axis.

Returns:

Dataset containing the partial gains split into the two polarization states.

Return type:

xarray.Dataset

calc_gain(power_in)

The gain figure of merit for antennas. Gain is dimensionless.

Parameters:

power_in (FreqDataArray) – Power, in units of Watts, supplied to the radiating element in the frequency domain.

property axial_ratio

Axial Ratio (AR) in the frequency domain as a function of angles theta and phi. AR is a dimensionless quantity defined as the ratio of the major axis to the minor axis of the polarization ellipse.

Note

The axial ratio computation is based on:

Balanis, Constantine A., “Antenna Theory: Analysis and Design,” John Wiley & Sons, Chapter 2.12 (2016).

property left_polarization

Electric far field for left-hand circular polarization (counterclockwise component) with an angle-based projection grid.

property right_polarization

Electric far field for right-hand circular polarization (clockwise component) with an angle-based projection grid.

fields_linear_polarization_tilted(tilt_angle)

Electric and magnetic fields in the linear polarization basis that is rotated at the pole of the radiation sphere by tilt_angle.

Parameters:

tilt_angle (float) – The angle by which the co-polar vector is rotated from the theta-axis. At tilt_angle = 0, the co-polar vector coincides with the theta-axis and the cross-polar vector coincides with the phi-axis; while at tilt_angle = pi/2, the co-polar vector coincides with the phi-axis.

Returns:

Dataset containing (Eco, Ecross, Hco, Hcross)

Return type:

xarray.Dataset

property fields_circular_polarization

Electric and magnetic fields in the circular polarization basis.

Note

Uses IEEE handedness convention for polarization state, which means right-handed circularly polarization is associated with a clockwise rotation of the electric field vector from the point of the view of the source. However, we use the physics convention for time evolution of time-harmonic fields, which modifies the computation when compared to engineering references.

Returns:

xarray dataset containing (Eleft, Eright, Hleft, Hright) in Spherical coordinates.

Return type:

xarray.Dataset

__hash__()

Hash method.