tidy3d.plugins.dipole_emission.DipoleEmissionStudy

class DipoleEmissionStudy

Bases: Tidy3dBaseModel

Dipole-emission sweep definition.

Parameters:

• base_sim (Simulation) – Source-free simulation describing the passive optical structure. Monitors in this simulation are available only through optional diagnostic batch data.

• analysis_region (EmissionAnalysisRegion) – Region containing the sampled dipoles and defining the far-field collection side.

• positions (PointDataArray) – Sampled dipole locations as a PointDataArray with dims ('index', 'axis').

• position_weights (Optional[Union[ArrayLike[dtype=float, ndim=1], ArrayLike[dtype=float, ndim=2]]] = None) – Weights used when summing radiation intensity over positions. Provide one weight per position, or one weight per position and Cartesian dipole axis. If omitted, all sampled positions have unit weight.

• store_position_indexes (tuple[int, ...] = ()) – Zero-based indexes into positions for individual position-resolved radiation intensity samples to retain. The default stores only the summed result.

• source_time (Union[GaussianPulse, ContinuousWave, CustomSourceTime, BroadbandPulse, BasebandStep, BasebandGaussianPulse, BasebandRectangularPulse, BasebandCustomSourceTime]) – Spectral envelope for the emission calculation. The envelope is included in radiation_intensity and divided out by the radiation_intensity_transfer(...) method.

• freqs (ArrayLike[dtype=float, ndim=1]) – Frequencies at which the emission response is evaluated.

• angles (SphericalAngleDataArray) – Far-field observation directions as (theta, phi) pairs in radians, with theta measured away from the selected collection normal and restricted to abs(theta) < pi/2.

• polarizations (tuple[Literal['p', 's'], ...] = ('p', 's')) – Far-field polarization components to evaluate at each observation angle. The p component lies in the plane formed by the observation direction and collection normal; s is orthogonal to that plane.

• a (A study evaluates radiative emission from classical electric dipoles in)

• per (passive optical environment. It reports angular radiation intensity)

• x- (squared dipole moment for)

• y-

• over (and z-oriented dipoles after summing)

• Optional (the sampled dipole positions using position_weights.)

• The (position-resolved samples may be retained for selected position indexes.)

• half-space; (result describes radiation into the selected collection)

• loss (non-radiative)

• modes (trapped guided)

• Purcell-factor (and total)

• included. (accounting are not)

Attributes

position_weights_array	Weights used to sum radiation intensity over sampled positions and axes.
pulse_spectrum_abs2	Squared source spectrum magnitude sampled at freqs.
base_sim
analysis_region
positions
position_weights
store_position_indexes
source_time
freqs
angles
polarizations

Methods

compose(batch_data)	Reduce user-managed batch data into DipoleEmissionStudyData.
run([folder_name, return_batch_data])	Run this emission study and return angular radiation intensity.
to_simulations()	Build the simulations for this emission study without submitting them.

base_sim

analysis_region

positions

position_weights

store_position_indexes

source_time

freqs

angles

polarizations

property pulse_spectrum_abs2

Squared source spectrum magnitude sampled at freqs.

property position_weights_array

Weights used to sum radiation intensity over sampled positions and axes.

to_simulations()

Build the simulations for this emission study without submitting them.

Use this method when you want to inspect the study simulations or submit the batch yourself. The returned simulations preserve any diagnostic monitors from base_sim; those diagnostic results are not part of DipoleEmissionStudyData and remain available only from the raw batch data.

Returns:

One ordinary Tidy3D simulation per stored observation angle and far-field polarization. The simulations are not submitted by this method.

Return type:

dict[str, Simulation]

compose(batch_data)

Reduce user-managed batch data into DipoleEmissionStudyData.

This method is intended for users who submit simulations from to_simulations(...) manually and want to produce the same reduced emission result returned by run(...).

Parameters:

batch_data (td.web.BatchData) – Batch results from simulations produced by to_simulations(...). Data from any user monitors copied from base_sim remains in this raw batch object and is not embedded in the returned DipoleEmissionStudyData.

Returns:

Serializable reduced emission data containing stored radiation_intensity with dimensions ("dipole_axis", "polarization", "angle", "f"). radiation_intensity_transfer(...) normalizes radiation_intensity by the bulk emitted power at a provided reference refractive index. Position-resolved arrays are included only when store_position_indexes is nonempty.

Return type:

DipoleEmissionStudyData

run(folder_name='dipole_emission', return_batch_data=False, **batch_kwargs)

Run this emission study and return angular radiation intensity.

The study returns radiation per squared electric dipole moment, with dipole moment expressed in C*um, summed over the sampled dipole positions using position_weights. The compact result is indexed by Cartesian dipole orientation, far-field polarization, observation angle, and frequency. To recover an absolute angular power density for a physical dipole moment d, multiply radiation_intensity by |d|**2.

Parameters:

• folder_name (str = "dipole_emission") – Cloud folder name used for the study batch.

• return_batch_data (bool = False) – If False, return only the reduced DipoleEmissionStudyData. If True, return (dipole_data, batch_data) so copied diagnostic monitors and raw simulation data remain available to the caller.

• **batch_kwargs – Additional keyword arguments forwarded to td.web.Batch(...) for batch construction options such as verbose and to td.web.Batch.run(...) for run options such as path_dir.

Returns:

Reduced emission data, optionally paired with the raw batch data.

Return type:

DipoleEmissionStudyData or tuple[DipoleEmissionStudyData, td.web.BatchData]