Time Functions

Temporal dynamics functions for time-resolved spectroscopy.

Function Conventions

Use CamelCase naming (UpperCamelCase or lowerCamelCase) for function names.

Dynamics Functions: Signature: func(t, par1, par2, …, t0, y0) - t: Time axis (numpy array) - par1, par2, …: Function-specific parameters - t0: Time zero (function starts at this time) - y0: Offset value (baseline) - Returns: f(t) = 0 for t < t0, dynamics for t >= t0

Convolution Kernels: Signature: funcCONV(t, par1, par2, …) - t: Time axis centered at zero (from create_t_kernel) - par1, par2, …: Kernel parameters - Returns: Normalized kernel function - Must have a companion funcCONV_kernel_width(…) helper for support width

Time Zero Convention: All dynamics functions are zero before t0 and activate at t >= t0. This reflects physical causality: response begins after excitation.

Offset Convention: Parameter y0 sets the asymptotic value or baseline. - Decays: approach y0 as t → ∞ - Rises: start from 0, reach y0 + A - Oscillations: oscillate around y0

Time Resolution: Functions inherit time axis from Dynamics model. Consider: - Time step size relative to dynamics (dt << tau) - Time range coverage (include full decay/rise) - Kernel width appropriate for convolution

Parameter Naming

Common parameter names: - A: Amplitude (change in signal) - tau: Time constant (decay/rise time, 1/e point) - t0: Time zero (start of dynamics) - y0: Offset/baseline value - f: Frequency (for oscillations) - phi: Phase (for oscillations) - SD: Standard deviation (for Gaussian kernels) - W: FWHM (for Lorentzian kernels)

Adding New Functions

To add a new dynamics or convolution function:

  1. Implement following conventions above

  2. Ensure f(t<t0) = 0 for dynamics functions

  3. Add kernel_width function for convolution kernels

  4. Test with realistic time-resolved data

trspecfit.functions.time.boxCONV(x: ndarray, width: float) → ndarray[source]

Box (rectangular) convolution kernel.

Parameters:

  • x (ndarray) – Time axis (centered at 0)

  • width (float) – Width of rectangular window

Returns:

Rectangular function: 1 inside width, 0 outside (with smooth edges)

Return type:

ndarray

trspecfit.functions.time.boxCONV_kernel_width(width: float | None = None) → int[source]

Kernel width multiplier for box (1×width).

trspecfit.functions.time.erfFun(t: ndarray, A: float, SD: float, t0: float, y0: float) → ndarray[source]

Error function rise (step with Gaussian broadening). erfFun ≈ step ⊗ Gaussian(SD)

Parameters:

  • t (ndarray) – Time axis

  • A (float) – Amplitude (total change from initial to final value)

  • SD (float) – Standard deviation of Gaussian broadening (rise time ~2.355*SD) Smaller SD → sharper rise

  • t0 (float) – Center of rise (50% point)

  • y0 (float) – Final value (asymptote as t → ∞)

Returns:

Error function: A/2 * (1 + erf((t-t0)/(SD*√2))) + y0

Return type:

ndarray

trspecfit.functions.time.expDecayCONV(x: ndarray, tau: float) → ndarray[source]

Causal exponential kernel (one-sided decay).

Parameters:

  • x (ndarray) – Time axis (centered at 0)

  • tau (float) – Decay time constant

Returns:

One-sided exponential: 0 for x<0, exp(-x/tau) for x≥0

Return type:

ndarray

trspecfit.functions.time.expDecayCONV_kernel_width(tau: float | None = None) → int[source]

Kernel width multiplier for decay exponential (6×tau).

trspecfit.functions.time.expFun(t: ndarray, A: float, tau: float, t0: float, y0: float) → ndarray[source]

Exponential decay or rise dynamics.

Parameters:

  • t (ndarray) – Time axis

  • A (float) – Amplitude (initial change at t0). - A > 0: Decay from y0+A to y0 - A < 0: Rise from y0 to y0+|A|

  • tau (float) – Time constant (1/e time). Units: [time units] At t = t0 + tau, signal changes by factor of e (≈2.718)

  • t0 (float) – Time zero (start of exponential)

  • y0 (float) – Asymptotic value (baseline as t → ∞)

Returns:

Exponential: 0 for t<t0, A*exp(-(t-t0)/tau)+y0 for t>=t0

Return type:

ndarray

trspecfit.functions.time.expRiseCONV(x: ndarray, tau: float) → ndarray[source]

Causal exponential rise kernel.

Parameters:

  • x (ndarray) – Time axis (centered at 0)

  • tau (float) – Rise time constant

Returns:

One-sided exponential: exp(x/tau) for x≤0, 0 for x>0

Return type:

ndarray

trspecfit.functions.time.expRiseCONV_kernel_width(tau: float | None = None) → int[source]

Kernel width multiplier for rise exponential (6×tau).

trspecfit.functions.time.expSymCONV(x: ndarray, tau: float) → ndarray[source]

Symmetric exponential kernel (double exponential). Exponential decay in both directions from center: exp(-|x|/tau)

Parameters:

  • x (ndarray) – Time axis (centered at 0)

  • tau (float) – Decay time constant

Returns:

Symmetric exponential kernel

Return type:

ndarray

trspecfit.functions.time.expSymCONV_kernel_width(tau: float | None = None) → int[source]

Kernel width multiplier for symmetric exponential (6×tau).

trspecfit.functions.time.gaussCONV(x: ndarray, SD: float) → ndarray[source]

Gaussian convolution kernel (instrumental response function).

Parameters:

  • x (ndarray) – Time axis (typically from Component.create_t_kernel, centered at 0)

  • SD (float) – Standard deviation (Gaussian width). FWHM = 2.355 * SD = 2*√(2ln2) * SD

Returns:

Gaussian kernel (unnormalized, will be normalized in convolution)

Return type:

ndarray

trspecfit.functions.time.gaussCONV_kernel_width(SD: float | None = None) → int[source]

Kernel width multiplier for Gaussian convolution. Kernel extends to ±4*SD from center. At 4*SD, Gaussian has decayed to exp(-8) ≈ 3×10⁻⁴ of peak value.

trspecfit.functions.time.linFun(t: ndarray, m: float, t0: float, y0: float) → ndarray[source]

Linear dynamics (constant rate of change).

Parameters:

  • t (ndarray) – Time axis

  • m (float) – Slope (rate of change). Units: [signal units]/[time units] - m > 0: Linear increase - m < 0: Linear decrease

  • t0 (float) – Time zero (start of linear change)

  • y0 (float) – Offset value at t0 (initial value)

Returns:

Linear function: 0 for t<t0, m*(t-t0)+y0 for t>=t0

Return type:

ndarray

trspecfit.functions.time.lorentzCONV(x: ndarray, W: float) → ndarray[source]

Lorentzian convolution kernel.

Parameters:

  • x (ndarray) – Time axis (centered at 0)

  • W (float) – Full width at half maximum (FWHM) of Lorentzian

Returns:

Lorentzian kernel (unnormalized)

Return type:

ndarray

trspecfit.functions.time.lorentzCONV_kernel_width(W: float | None = None) → int[source]

Kernel width multiplier for Lorentzian (10×W).

trspecfit.functions.time.none(t: ndarray) → ndarray[source]

Placeholder function to define empty subcycles in a mcp.Dynamics model.

Used to define empty subcycles in multi-cycle Dynamics models without adding any time-dependent behavior. This allows subcycle numbering to work correctly when some subcycles should have no dynamics.

Usage (in model YAML file):

model_sub2:
  none: {}
Parameters:

t (ndarray) – Time axis (not used)

Returns:

Array of zeros with same shape as t

Return type:

ndarray

trspecfit.functions.time.sinDivX(t: ndarray, A: float, f: float, t0: float, y0: float) → ndarray[source]

Damped sinc function: sin(x)/x oscillation.

Parameters:

  • t (ndarray) – Time axis

  • A (float) – Amplitude scaling factor

  • f (float) – Frequency in [1/time units]

  • t0 (float) – Time zero (start of oscillation)

  • y0 (float) – Offset value

Returns:

Sinc oscillation: 0 for t<t0, A*sin(2πf(t-t0))/(2πf(t-t0))+y0 for t>=t0

Return type:

ndarray

trspecfit.functions.time.sinFun(t: ndarray, A: float, f: float, phi: float, t0: float, y0: float) → ndarray[source]

Sinusoidal oscillations (coherent dynamics).

Parameters:

  • t (ndarray) – Time axis

  • A (float) – Oscillation amplitude (peak-to-peak = 2A)

  • f (float) – Frequency in [1/time units] Period = 1/f

  • phi (float) – Phase offset in radians - phi = 0: Sine starts at zero - phi = π/2: Starts at maximum (cosine) - phi = π: Starts at zero (negative slope)

  • t0 (float) – Time zero (start of oscillation)

  • y0 (float) – Offset (center line of oscillation)

Returns:

Sinusoid: 0 for t<t0, A*sin(2πf(t-t0)+phi)+y0 for t>=t0

Return type:

ndarray

trspecfit.functions.time.sqrtFun(t: ndarray, A: float, t0: float, y0: float) → ndarray[source]

Square root rise (diffusion dynamics).

Parameters:

  • t (ndarray) – Time axis

  • A (float) – Amplitude scaling factor

  • t0 (float) – Time zero (start of diffusion)

  • y0 (float) – Offset value

Returns:

Square root rise: 0 for t<t0, A*√(t-t0)+y0 for t>=t0

Return type:

ndarray

trspecfit.functions.time.voigtCONV(x: ndarray, SD: float, W: float) → ndarray[source]

Voigt convolution kernel (Gaussian and Lorentzian combined).

Parameters:

  • x (ndarray) – Time axis (centered at 0)

  • SD (float) – Gaussian standard deviation

  • W (float) – Lorentzian FWHM

Returns:

Voigt kernel (normalized to peak = 1)

Return type:

ndarray

trspecfit.functions.time.voigtCONV_kernel_width(SD: float = 1.0, W: float = 0.0) → float[source]

Kernel width multiplier for Voigt support.

create_t_kernel multiplies the first kernel parameter by this value. For voigtCONV the first parameter is SD, but broad Lorentzian tails are controlled by W. Return a multiplier large enough that the support spans at least max(12*SD, 10*W).