Sources API

Complete API reference for all electromagnetic sources in Prismo.

Base Classes

Source

class prismo.sources.base.Source(center, size, name=None, enabled=True)

Bases: ABC

Abstract base class for all electromagnetic sources.

Parameters:

• center (Tuple[float, float, float]) – Physical coordinates of the source center (x, y, z) in meters.

• size (Tuple[float, float, float]) – Physical dimensions of the source region (Lx, Ly, Lz) in meters. For point sources, use (0, 0, 0).

• name (str, optional) – Name of the source for identification.

• enabled (bool, optional) – Flag to enable/disable the source, default=True.

__init__(center, size, name=None, enabled=True)

initialize(grid)

Initialize the source on a specific grid.

Parameters:

grid (YeeGrid) – The grid on which to initialize the source.

Return type:

None

abstractmethod update_fields(fields, time, dt)

Update electromagnetic fields with source contribution.

Parameters:

• fields (ElectromagneticFields) – Electromagnetic fields to update.

• time (float) – Current simulation time in seconds.

• dt (float) – Time step in seconds.

Return type:

None

disable()

Disable the source.

Return type:

None

enable()

Enable the source.

Return type:

None

Waveforms

Waveform

class prismo.sources.waveform.Waveform(amplitude=1.0, phase=0.0)

Bases: object

Base class for time-dependent waveforms.

Parameters:

• amplitude (float, optional) – Peak amplitude of the waveform, default=1.0.

• phase (float, optional) – Phase offset in radians, default=0.0.

__init__(amplitude=1.0, phase=0.0)

__call__(t)

Evaluate the waveform at given time(s).

Parameters:

t (float or numpy.ndarray) – Time(s) in seconds.

Returns:

Waveform value(s) at specified time(s).

Return type:

float or numpy.ndarray

evaluate(t)

Evaluate the waveform at given time(s).

Parameters:

t (float or numpy.ndarray) – Time(s) in seconds.

Returns:

Waveform value(s) at specified time(s).

Return type:

float or numpy.ndarray

GaussianPulse

class prismo.sources.waveform.GaussianPulse(frequency, pulse_width, amplitude=1.0, phase=0.0, delay=None)

Bases: Waveform

Gaussian pulse waveform.

Parameters:

• frequency (float) – Center frequency in Hz.

• pulse_width (float) – Width of the Gaussian pulse in seconds.

• amplitude (float, optional) – Peak amplitude of the waveform, default=1.0.

• phase (float, optional) – Phase offset in radians, default=0.0.

• delay (float, optional) – Time delay for the pulse peak in seconds, default=3*pulse_width.

__init__(frequency, pulse_width, amplitude=1.0, phase=0.0, delay=None)

evaluate(t)

Evaluate the Gaussian pulse at given time(s).

Parameters:

t (float or numpy.ndarray) – Time(s) in seconds.

Returns:

Waveform value(s) at specified time(s).

Return type:

float or numpy.ndarray

ContinuousWave

class prismo.sources.waveform.ContinuousWave(frequency, amplitude=1.0, phase=0.0)

Bases: Waveform

Continuous sine wave at a fixed frequency.

Parameters:

• frequency (float) – Frequency in Hz.

• amplitude (float, optional) – Peak amplitude of the waveform, default=1.0.

• phase (float, optional) – Phase offset in radians, default=0.0.

__init__(frequency, amplitude=1.0, phase=0.0)

evaluate(t)

Evaluate the continuous wave at given time(s).

Parameters:

t (float or numpy.ndarray) – Time(s) in seconds.

Returns:

Waveform value(s) at specified time(s).

Return type:

float or numpy.ndarray

Point Sources

ElectricDipole

class prismo.sources.point.ElectricDipole(position, polarization, frequency, pulse=True, pulse_width=None, amplitude=1.0, phase=0.0, name=None, enabled=True)

Bases: PointSource

Electric dipole source for exciting electromagnetic fields.

Parameters:

• position (Tuple[float, float, float]) – Physical coordinates of the source (x, y, z) in meters.

• polarization (Literal["x", "y", "z"]) – Polarization direction of the dipole.

• frequency (float) – Source frequency in Hz.

• pulse (bool, optional) – Whether to use a Gaussian pulse (True) or continuous wave (False), default=True.

• pulse_width (float, optional) – Width of the Gaussian pulse in seconds, required if pulse=True.

• amplitude (float, optional) – Peak amplitude of the source, default=1.0.

• phase (float, optional) – Phase offset in radians, default=0.0.

• name (str, optional) – Name of the source for identification.

• enabled (bool, optional) – Flag to enable/disable the source, default=True.

__init__(position, polarization, frequency, pulse=True, pulse_width=None, amplitude=1.0, phase=0.0, name=None, enabled=True)

MagneticDipole

class prismo.sources.point.MagneticDipole(position, polarization, frequency, pulse=True, pulse_width=None, amplitude=1.0, phase=0.0, name=None, enabled=True)

Bases: PointSource

Magnetic dipole source for exciting electromagnetic fields.

Parameters:

• position (Tuple[float, float, float]) – Physical coordinates of the source (x, y, z) in meters.

• polarization (Literal["x", "y", "z"]) – Polarization direction of the dipole.

• frequency (float) – Source frequency in Hz.

• pulse (bool, optional) – Whether to use a Gaussian pulse (True) or continuous wave (False), default=True.

• pulse_width (float, optional) – Width of the Gaussian pulse in seconds, required if pulse=True.

• amplitude (float, optional) – Peak amplitude of the source, default=1.0.

• phase (float, optional) – Phase offset in radians, default=0.0.

• name (str, optional) – Name of the source for identification.

• enabled (bool, optional) – Flag to enable/disable the source, default=True.

__init__(position, polarization, frequency, pulse=True, pulse_width=None, amplitude=1.0, phase=0.0, name=None, enabled=True)

Plane Wave Sources

PlaneWaveSource

class prismo.sources.plane_wave.PlaneWaveSource(center, size, direction, polarization, frequency, pulse=True, pulse_width=None, amplitude=1.0, phase=0.0, name=None, enabled=True)

Bases: Source

Plane wave source for exciting uniform electromagnetic fields.

Parameters:

• center (Tuple[float, float, float]) – Physical coordinates of the wave center (x, y, z) in meters.

• size (Tuple[float, float, float]) – Physical dimensions of the source region (Lx, Ly, Lz) in meters.

• direction (Literal["x", "y", "z", "+x", "-x", "+y", "-y", "+z", "-z"]) – Propagation direction of the wave, with optional sign.

• polarization (Literal["x", "y", "z"]) – Polarization direction of the electric field (must be perpendicular to direction).

• frequency (float) – Center frequency in Hz.

• pulse (bool, optional) – Whether to use a Gaussian pulse (True) or continuous wave (False), default=True.

• pulse_width (float, optional) – Width of the Gaussian pulse in seconds, required if pulse=True.

• amplitude (float, optional) – Peak amplitude of the source, default=1.0.

• phase (float, optional) – Phase offset in radians, default=0.0.

• name (str, optional) – Name of the source for identification.

• enabled (bool, optional) – Flag to enable/disable the source, default=True.

__init__(center, size, direction, polarization, frequency, pulse=True, pulse_width=None, amplitude=1.0, phase=0.0, name=None, enabled=True)

initialize(grid)

Initialize the plane wave source on a specific grid.

Parameters:

grid (YeeGrid) – The grid on which to initialize the source.

Return type:

None

update_fields(fields, time, dt)

Update electromagnetic fields with plane wave source contribution.

Parameters:

• fields (ElectromagneticFields) – Electromagnetic fields to update.

• time (float) – Current simulation time in seconds.

• dt (float) – Time step in seconds.

Return type:

None

TFSFSource

class prismo.sources.tfsf.TFSFSource(center, size, direction, polarization, frequency, pulse=True, pulse_width=None, amplitude=1.0, phase=0.0, angle=0.0, name=None, enabled=True)

Bases: Source

Total-Field/Scattered-Field (TFSF) plane wave source.

This source implements the TFSF formulation for injecting plane waves into the FDTD grid. The TFSF boundary separates the computational domain into two regions: - Total-field region (interior): Contains incident + scattered fields - Scattered-field region (exterior): Contains only scattered fields

Parameters:

• center (Tuple[float, float, float]) – Physical coordinates of the TFSF region center (x, y, z) in meters.

• size (Tuple[float, float, float]) – Physical dimensions of the TFSF region (Lx, Ly, Lz) in meters. The TFSF surface will be placed on the boundaries of this region.

• direction (Literal["x", "y", "z", "+x", "-x", "+y", "-y", "+z", "-z"]) – Propagation direction of the plane wave.

• polarization (Literal["x", "y", "z"]) – Polarization direction of the electric field (must be perpendicular to direction).

• frequency (float) – Center frequency in Hz.

• pulse (bool, optional) – Whether to use a Gaussian pulse (True) or continuous wave (False), default=True.

• pulse_width (float, optional) – Width of the Gaussian pulse in seconds, required if pulse=True.

• amplitude (float, optional) – Peak amplitude of the source, default=1.0.

• phase (float, optional) – Phase offset in radians, default=0.0.

• angle (float, optional) – Incidence angle in radians (for oblique incidence), default=0.0.

• name (str, optional) – Name of the source for identification.

• enabled (bool, optional) – Flag to enable/disable the source, default=True.

__init__(center, size, direction, polarization, frequency, pulse=True, pulse_width=None, amplitude=1.0, phase=0.0, angle=0.0, name=None, enabled=True)

initialize(grid)

Initialize the TFSF source on a specific grid.

Parameters:

grid (YeeGrid) – The grid on which to initialize the source.

Return type:

None

update_fields(fields, time, dt)

Update electromagnetic fields with TFSF source contribution.

This applies corrections to the fields on the TFSF boundary to inject the incident plane wave.

Parameters:

• fields (ElectromagneticFields) – Electromagnetic fields to update.

• time (float) – Current simulation time in seconds.

• dt (float) – Time step in seconds.

Return type:

None

__repr__()

Return string representation of the TFSF source.

Return type:

str

Gaussian Sources

GaussianSource

Mode Sources

ModeSource

class prismo.sources.mode.ModeSource(center, size, mode, direction, waveform, amplitude=1.0, phase=0.0, name=None)

Bases: Source

Source that injects a waveguide mode.

Uses mode profiles from eigenmode solver to inject guided modes into the simulation domain with specified waveform modulation.

Parameters:

• center (Tuple[float, float, float]) – Physical coordinates of source plane center.

• size (Tuple[float, float, float]) – Size of source plane.

• mode (WaveguideMode) – Waveguide mode to inject (from ModeSolver).

• direction (str) – Propagation direction (‘+x’, ‘-x’, ‘+y’, ‘-y’, ‘+z’, ‘-z’).

• waveform (Waveform) – Temporal waveform for mode excitation.

• amplitude (float, optional) – Source amplitude, default=1.0.

• phase (float, optional) – Initial phase (radians), default=0.0.

• name (str, optional) – Source name.

__init__(center, size, mode, direction, waveform, amplitude=1.0, phase=0.0, name=None)

initialize(grid)

Initialize mode source on grid.

Return type:

None

update_fields(fields, time, dt)

Update fields with mode source.

Adds mode profile weighted by temporal waveform.

Parameters:

• fields (ElectromagneticFields) – Field arrays to update.

• time (float) – Current simulation time.

• dt (float) – Time step.

Return type:

None

ModeLauncher

class prismo.sources.mode.ModeLauncher(mode, direction, power=1.0)

Bases: object

Helper class for launching modes with proper excitation.

Handles mode injection, normalization, and phase matching.

Parameters:

• mode (WaveguideMode) – Mode to launch.

• direction (str) – Propagation direction.

• power (float, optional) – Mode power (W), default=1.0.

__init__(mode, direction, power=1.0)

get_normalized_mode()

Get mode with normalized power.

Returns:

Mode with fields scaled to achieve target power.

Return type:

WaveguideMode

See Also

• Sources and Monitors - Source usage guide

• Tutorial 1: Your First FDTD Simulation - Tutorial using sources

• Mode Ports - Mode source guide