Sources

This page lists the source classes and source-time waveforms in witwin.maxwell (import as import witwin.maxwell as mw). You need it when you add an excitation to a scene with Scene.add_source (see Scene). For guidance on choosing a source, see Choose sources and waveforms and Sources and monitors.

A source has two parts. The spatial part (this page's source classes) says where and how the field is injected. The temporal part (source_time) is one of CW, GaussianPulse, RickerWavelet or CustomSourceTime, and carries the amplitude and phase. When source_time is None, the source runs as CW at the simulation frequency with amplitude 1.0.

All lengths are in metres, frequencies in Hz and times in seconds. All source classes are frozen dataclasses; their constructor arguments become read-only attributes. Each also has a read-only kind string tag.

import witwin.maxwell as mw
 
scene = mw.Scene(
    domain=mw.Domain(bounds=((-0.5, 0.5), (-0.5, 0.5), (-0.5, 0.5))),
    grid=mw.GridSpec.uniform(0.02),
)
scene.add_source(
    mw.PointDipole(position=(0.0, 0.0, 0.0), polarization="Ez", source_time=mw.CW(frequency=1.0e9))
)

Polarization values#

Every polarization argument except the one on ModeSource accepts:

• a field name, "Ex", "Ey" or "Ez" (case-insensitive), or
• any non-zero 3-vector, which is normalized to unit length.

PointDipole#

class PointDipole(position, polarization='Ez', width=0.02, profile='gaussian', source_time=None, name=None)

Electric point-dipole current source.

Raises ValueError if width is not greater than 0 or profile is not one of the two values.

dipole = mw.PointDipole(
    position=(0.0, 0.0, 0.0),
    polarization="Ez",
    width=0.05,
    source_time=mw.GaussianPulse(frequency=1.0e9, fwidth=0.4e9),
)

PlaneWave#

class PlaneWave(
    direction=(0.0, 0.0, 1.0), polarization=(1.0, 0.0, 0.0),
    source_time=None, injection='soft', injection_axis=None, name=None,
)

Plane-wave source. With injection='soft' it injects on an automatically placed source plane; with a TFSF descriptor it uses a total-field/scattered-field surface.

Raises ValueError if polarization is not orthogonal to direction, or for an invalid injection or injection_axis.

The soft source plane sits just inside the absorbing boundary on the side the wave comes from. A soft plane wave supports zero-phase periodic boundaries on the transverse axes. Oblique incidence on Bloch boundaries, periodicity along the propagation axis, and a nonzero tangential phase need TFSF.

wave = mw.PlaneWave(
    direction=(0.0, 0.0, 1.0),
    polarization=(1.0, 0.0, 0.0),
    source_time=mw.CW(frequency=1.0e9),
)

GaussianBeam#

class GaussianBeam(
    direction=(0.0, 0.0, 1.0), polarization=(1.0, 0.0, 0.0),
    beam_waist=0.5, focus=(0.0, 0.0, 0.0),
    source_time=None, injection='soft', injection_axis=None, name=None,
)

Gaussian-beam source with a circular waist. direction, polarization, source_time, injection, injection_axis and name behave as on PlaneWave.

beam = mw.GaussianBeam(
    direction=(1.0, 0.0, 0.0),
    polarization=(0.0, 0.0, 1.0),
    beam_waist=0.2,
    focus=(0.0, 0.0, 0.0),
    source_time=mw.CW(frequency=1.0e9),
)

AstigmaticGaussianBeam#

class AstigmaticGaussianBeam(
    direction=(0.0, 0.0, 1.0), polarization=(1.0, 0.0, 0.0),
    beam_waist=(0.5, 0.5), focus=(0.0, 0.0, 0.0), focus_u=0.0, focus_v=0.0,
    source_time=None, injection='soft', injection_axis=None, name=None,
)

Elliptical Gaussian beam with separate waists and waist positions on two transverse axes. The u axis is polarization; the v axis is direction x polarization. With equal waists and zero offsets it matches GaussianBeam. Other arguments behave as on PlaneWave.

Raises ValueError if beam_waist does not have two positive values.

beam = mw.AstigmaticGaussianBeam(
    direction=(1.0, 0.0, 0.0),
    polarization=(0.0, 0.0, 1.0),
    beam_waist=(0.3, 0.18),
    focus=(0.1, 0.0, 0.0),
    focus_u=0.05,
    focus_v=-0.05,
    source_time=mw.CW(frequency=1.0e9),
)

TFSF#

class TFSF(bounds)

Total-field/scattered-field injection descriptor. Pass it as injection= to PlaneWave, GaussianBeam or AstigmaticGaussianBeam. Inside the box the field is total; outside it is scattered only.

Raises ValueError if bounds does not hold three valid ranges.

scene.add_source(
    mw.PlaneWave(
        direction=(1.0, 0.0, 0.0),
        polarization=(0.0, 0.0, 1.0),
        source_time=mw.CW(frequency=1.0e9),
        injection=mw.TFSF(bounds=((-0.2, 0.2), (-0.2, 0.2), (-0.2, 0.2))),
    )
)

TFSF.slab#

TFSF.slab(*, axis, bounds) -> TFSF

Classmethod. Returns a slab descriptor: two faces normal to axis, spanning the whole transverse cross section. Use it with PlaneWave for gratings and layered stacks.

Raises ValueError for an invalid axis or bounds.

With Bloch boundaries on the two transverse axes, the slab supports oblique incidence and CW, GaussianPulse or RickerWavelet. With absorbing transverse boundaries, it supports normal incidence only. Other spatial sources reject a slab descriptor.

scene.add_source(
    mw.PlaneWave(
        direction=(0.25, 0.0, 0.9682458366),
        polarization=(1.0, 0.0, -0.2581988897),
        source_time=mw.CW(frequency=200e12),
        injection=mw.TFSF.slab(axis="z", bounds=(-0.4, 0.4)),
    )
)

ModeSource#

class ModeSource(
    position=(0.0, 0.0, 0.0), size=(1.0, 1.0, 0.0), mode_index=0, direction='+',
    polarization='auto', source_time=None, injection='soft', name=None,
    bend_radius=None, bend_axis=None,
)

Launches a guided waveguide mode, solved on an axis-aligned plane.

Raises ValueError for a size without exactly one zero component, a non-tangential polarization, a negative mode_index, an invalid direction, injection other than 'soft', or an inconsistent bend pair.

After construction, normal_axis and polarization_axis hold the resolved axis names, and polarization holds the unit vector of polarization_axis.

scene.add_source(
    mw.ModeSource(
        position=(-0.32, 0.0, 0.0),
        size=(0.0, 0.56, 0.56),
        polarization="Ez",
        source_time=mw.CW(frequency=1.0e9),
        name="mode0",
    )
)

For S-parameter work, prefer ModePort in Ports and lumped elements. See also Mode ports and S-parameters.

UniformCurrentSource#

class UniformCurrentSource(size, polarization='Ez', source_time=None, center=(0.0, 0.0, 0.0), name=None)

Uniform additive electric current filling an axis-aligned box. The current is deposited by the overlap of the box with each Yee component's control volume. Note that size comes first and center is the fourth argument.

scene.add_source(
    mw.UniformCurrentSource(
        size=(0.06, 0.06, 0.06),
        polarization="Ez",
        source_time=mw.GaussianPulse(frequency=1e9, fwidth=5e8),
        center=(0.0, 0.0, 0.0),
    )
)

CurrentDataset#

class CurrentDataset(coords, components)

Electric and magnetic current samples on a rectilinear grid, used by CustomCurrentSource.

Raises ValueError for a wrong number of axes, non-increasing coordinates, an unknown component name, or a shape mismatch.

CustomCurrentSource#

class CustomCurrentSource(current_dataset, source_time=None, name=None)

Injects an arbitrary volume distribution of electric (J) and magnetic (M) current, sampled from the dataset onto the Yee grid with trilinear interpolation.

import numpy as np
 
x = y = z = np.linspace(-0.05, 0.05, 2)
dataset = mw.CurrentDataset((x, y, z), {"Jz": np.ones((2, 2, 2)), "Mx": np.full((2, 2, 2), 0.3)})
scene.add_source(mw.CustomCurrentSource(dataset, source_time=mw.GaussianPulse(frequency=3e14, fwidth=1e13)))

FieldDataset#

class FieldDataset(coords, components)

Tangential electric and magnetic field samples on a rectilinear grid, used by CustomFieldSource. The rules for coords and components match CurrentDataset, with component names 'Ex', 'Ey', 'Ez', 'Hx', 'Hy', 'Hz'.

CustomFieldSource#

class CustomFieldSource(field_dataset, source_time=None, name=None)

Replays a tangential field distribution on a plane as equivalent surface currents, J = n x H and M = -n x E. The normal n points along the single-sample axis of the dataset, toward its positive direction, and the source injects toward +normal only.

Raises TypeError if field_dataset is not a FieldDataset. ValueError if the dataset does not have exactly one single-sample axis.

The normal_axis property returns that axis as 'x', 'y' or 'z'.

import numpy as np
 
x, y, z = np.linspace(-0.1, 0.1, 3), np.linspace(-0.1, 0.1, 2), np.array([0.0])
dataset = mw.FieldDataset((x, y, z), {"Ex": np.ones((3, 2, 1)), "Hy": np.full((3, 2, 1), 0.3)})
scene.add_source(mw.CustomFieldSource(dataset, source_time=mw.GaussianPulse(frequency=3e14, fwidth=1e13)))

CW#

class CW(frequency, amplitude=1.0, phase=0.0)

Continuous wave, A * cos(2*pi*f*t + phi).

GaussianPulse#

class GaussianPulse(frequency, fwidth, amplitude=1.0, phase=0.0, delay=None)

Gaussian-envelope pulse, A * exp(-tau^2 / (2*sigma_t^2)) * cos(2*pi*f*tau + phi) with tau = t - delay and sigma_t = 1 / (2*pi*fwidth).

pulse = mw.GaussianPulse(frequency=1.0e9, fwidth=0.4e9, amplitude=2.0)
pulse.evaluate(pulse.delay)  # 2.0

RickerWavelet#

class RickerWavelet(frequency, amplitude=1.0, delay=None)

Ricker (Mexican-hat) wavelet, A * (1 - 2*a^2) * exp(-a^2) with a = pi*f*(t - delay).

CustomSourceTime#

class CustomSourceTime(times=None, amplitudes=None, *, amplitude=1.0, characteristic_frequency=None)

Arbitrary waveform from a sampled table or a Python callable. It is evaluated on the solver time grid n*dt through the Python injection path.

There are two forms:

• CustomSourceTime(times, amplitudes): a table. Values are linearly interpolated and zero outside the sampled range. Unsorted samples are sorted by time.
• CustomSourceTime(fn, characteristic_frequency=...): a callable fn(t) -> float. Pass it as the first positional argument.

Raises ValueError if neither form is complete, a callable comes without characteristic_frequency or with a second positional argument, or the table is not 1D, has mismatched lengths, or has fewer than two samples.

import numpy as np
 
pulse = mw.GaussianPulse(frequency=1.0e9, fwidth=0.4e9)
times = np.arange(0.0, 3.0e-9, 2.0e-12)
table = mw.CustomSourceTime(times, [pulse.evaluate(float(t)) for t in times])
dipole = mw.PointDipole(position=(0.0, 0.0, 0.0), polarization="Ez", source_time=table)

See also#