fitting.simulation

fitting.simulation

Functions¶

Name	Description
simulate_fid	Simulate a complex Free Induction Decay (FID) signal.

simulate_fid¶

fitting.simulation.simulate_fid(
    amplitudes,
    *,
    frequencies=None,
    chemical_shifts=None,
    reference_frequency=None,
    carrier_ppm=0.0,
    spectral_width=10000.0,
    n_points=1024,
    dampings=50.0,
    phases=0.0,
    lineshape_g=0.0,
    dead_time=0.0,
    target_snr=None,
    seed=None,
)

Simulate a complex Free Induction Decay (FID) signal.

Returns a formatted array.DataArray compliant with xmris.core vocabularies.

This function relies on the AMARES algorithm formulation. The generated data is a time-domain signal, meaning its primary dimension and coordinate will always be time. Simulation parameters (like the input ppm/Hz peaks and noise targets) are preserved in the DataArray’s attributes for downstream tracking.

If target_snr is provided, complex Gaussian white noise is added to the ideal signal. The total noise variance is split equally between the real and imaginary receiver channels to physically mimic quadrature detection.

Parameters¶

Name	Type	Description	Default
amplitudes	ArrayLike	The amplitudes (a_k) of the peaks.	required
frequencies	ArrayLike \| None	The frequencies (f_k) of the peaks in Hz.	`None`
chemical_shifts	ArrayLike \| None	The chemical shifts of the peaks in ppm. Must be accompanied by `reference_frequency`.	`None`
reference_frequency	float \| None	The spectrometer operating frequency in MHz. Maps to ATTRS.reference_frequency.	`None`
carrier_ppm	float	The transmitter carrier frequency in ppm. The observable frequency window is centered around this value to prevent spectral aliasing. Default is 0.0.	`0.0`
spectral_width	float	The spectral width in Hz. Determines the dwell time. Default is 10000.0.	`10000.0`
n_points	int	The number of data points (N). Default is 1024.	`1024`
dampings	float \| ArrayLike	The damping factor(s) (d_k). Default is 50.0.	`50.0`
phases	float \| ArrayLike	The phase(s) (phi_k) in radians. Default is 0.0. Mind the unit asymmetry with fitting: this simulation takes phase in radians, whereas `fit_amares` reports fitted phase in degrees (and `build_prior_knowledge` takes it in degrees too).	`0.0`
lineshape_g	float \| ArrayLike	The lineshape parameter(s) (g_k) between 0 (Lorentzian) and 1 (Gaussian).	`0.0`
dead_time	float	The time origin offset in seconds. Default is 0.0.	`0.0`
target_snr	float \| None	The target Signal-to-Noise Ratio. If provided, complex Gaussian white noise is added to the FID. Signal power is calculated from the first 10 points of the FID. Default is None (returns ideal, noiseless FID).	`None`
seed	int \| None	Seed for the noise generator. Pass an integer for reproducible noise — required whenever downstream assertions depend on the noisy data (e.g. the notebook test suite). Default is None (fresh entropy every call).	`None`

Returns¶

Name	Type	Description
	xarray.DataArray	A 1D DataArray containing the complex FID signal, dimensioned by `DIMS.time`, with coordinates `COORDS.time`, and rich simulation metadata.