Excitation objects

See also bfdtd.excitation module.

Excitation

class bfdtd.excitation.Excitation(name=None, current_source=None, P1=None, P2=None, E=None, H=None, Type=None, time_constant=None, amplitude=None, time_offset=None, frequency=None, param1=None, param2=None, template_filename=None, template_source_plane=None, template_target_plane=None, template_direction=None, template_rotation=None, layer=None, group=None)

Bases: object

The base class for BFDTD excitations.

When using a gaussian sinewave, undesired effects (part of the signal cut off) might happen, if the time offset is too small compared to the time constant.

To prevent this, the writing procedure automatically checks if:

MIN_TIME_OFFSET_TIME_CONSTANT_RATIO*self.time_constant > self.time_offset.

If this is the case, there are 3 possible outcomes, depending on the value of self.TimeOffsetSafetyBehaviour:

• self.TimeOffsetSafetyBehaviour=0 (the default): adapt the time offset by setting self.time_offset = MIN_TIME_OFFSET_TIME_CONSTANT_RATIO*self.time_constant
• self.TimeOffsetSafetyBehaviour=1: raise an Exception
• self.TimeOffsetSafetyBehaviour=2: ignore and continue writing

Note

You can change MIN_TIME_OFFSET_TIME_CONSTANT_RATIO in interactive mode as follows: bfdtd.excitation.MIN_TIME_OFFSET_TIME_CONSTANT_RATIO=42

From MEEP documentation. Not fully implemented yet, but the plan is to clearly and accurately document the sources and make it easier to get exactly what we want. It is possible that BFDTD gaussian sources behave differently than MEEP sources. BFDTD sources do not seem to have a proper cutoff for instance, or at least not properly return to zero and stay there.

Note

Units: Usually DISTANCE=1μm, so that frequencies are in MHz and times in μs.

Gaussian source:

A Gaussian-pulse source roughly proportional to exp( − iωt − (t − t0)^2 / (2*w^2)). cf MEEP documentation.

Attributes:

• frequency [number]:

  The center frequency f in units of (m/s)/DISTANCE (or ω in units of 2π*(m/s)/DISTANCE).

  No default value.

  You can instead specify:

  • wavelength = c0/f in units of DISTANCE
  • period = 1/f in units of DISTANCE/(m/s)

• width [number]:

  The width w used in the Gaussian. No default value. You can instead specify:

  • fwidth x, which is a synonym for (width (/ 1 x)) (i.e. the frequency width is proportional to the inverse of the temporal width)
  • FWHM_time
  • FWHM_frequency
  • FWHM_angular_frequency

• start-time [number]:

  The starting time for the source; default is 0 (turn on at t = 0). (Not the time of the peak! See below.) You can instead specify:

  • end-time
  • peak-time

• cutoff [number]:

  How many widths the current decays for before we cut it off and set it to zero—this applies for both turn-on and turn-off of the pulse. The default is 5.0. A larger value of cutoff will reduce the amount of high-frequency components that are introduced by the start/stop of the source, but will of course lead to longer simulation times. The peak of the gaussian is reached at the time t0= start-time + cutoff*width.

check()

Checks the excitation for common mistakes.

checkPeriodvsTimeConstant(raise_exception=False)

disableAutoFix()

disableSafetyChecks()

enableAutoFix()

enableSafetyChecks()

fix()

Automatically fix common mistakes.

getAdaptedTimeOffset()

Returns MIN_TIME_OFFSET_TIME_CONSTANT_RATIO*self.time_constant

cf setTimeOffset()

getAmplitude()

getCentro()

getEndTime()

cf setTimeOffset()

getExcitedComponentNames()

getExtension()

getFrequency()

getFrequencyMax()

getFrequencyMin()

getFrequencyRange()

getLambda()

getLocation()

getMeshingParameters(xvec, yvec, zvec, epsx, epsy, epsz)

getName()

getPeakTime()

cf setTimeOffset()

getPeriod()

getSize()

getStartTime()

cf setTimeOffset()

getTimeConstant()

getTimeOffset()

cf setTimeOffset()

getWavelength()

getWavelengthMax()

getWavelengthMin()

getWavelengthRange()

printInfo()

read_entry(entry)

setAmplitude(amplitude)

setCentro(nova_centro)

setEndTime(end_time)

cf setTimeOffset()

setEx()

setExtension(P1, P2)

setEy()

setEz()

setFrequency(freq_MHz)

setFrequencyRange(fmin, fmax, autofix=False)

Sets central frequency and frequency width so that the FFT of the pulse covers from fmin to fmax.

Formulas used:

• frequency = 0.5*(fmin+fmax)
• time_constant = 1/(4*(fmax-fmin))

setLambda(lambda_mum)

setLocation(loc)

setName(name)

setPeakTime(peak_time)

cf setTimeOffset()

setPeriod(period)

setSize(size_vec3)

setStartTime(start_time)

cf setTimeOffset()

setTimeConstant(time_constant)

setTimeOffset(time_offset=None)

Set the time offset. If time_offset is None, it adapts the time offset by setting self.time_offset = MIN_TIME_OFFSET_TIME_CONSTANT_RATIO*self.time_constant

The time offset can be get/set using the following three alternatives:

• StartTime = self.time_offset - MIN_TIME_OFFSET_TIME_CONSTANT_RATIO*self.time_constant :
  • setStartTime()
  • getStartTime()
• PeakTime = self.time_offset :
  • getPeakTime()
  • setPeakTime()
• EndTime = self.time_offset + MIN_TIME_OFFSET_TIME_CONSTANT_RATIO*self.time_constant :
  • getEndTime()
  • setEndTime()

setWavelength(lambda_mum)

setWavelengthRange(lambda_min, lambda_max)

translate(vec3)

write_entry(FILE=<_io.TextIOWrapper name='<stdout>' mode='w' encoding='UTF-8'>, AutoFix=True, SafetyChecks=True)

write entry into FILE .. todo:: reduce code duplication here .. todo:: Should fix+check functions be called from BFDTDobject? Or should fix+check args be passed to write_entry? or should object’s AutoFix/SafetyChecks be modified from BFDTDobject?

Every function should do one thing and do it well -> no fix+check in here Having fix+check in here reduces risk of accidental bad output writing -> fix+check should be in here

Writing bad output should be made difficult, but not too difficult for testing purposes.