(xmris.fitting.simulation)=
# fitting.simulation
`fitting.simulation`



## Functions

| Name | Description |
| --- | --- |
| [simulate_fid](#xmris.fitting.simulation.simulate_fid) | Simulate a complex Free Induction Decay (FID) signal. |

(xmris.fitting.simulation.simulate_fid)=
### simulate_fid
```python
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,
)
```

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.                                                                                                                                                                 | `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`     |

#### Returns

| Name   | Type             | Description                                                                                                                                 |
|--------|------------------|---------------------------------------------------------------------------------------------------------------------------------------------|
|        | [xarray.DataArray](xref:xarray#xarray.DataArray) | A 1D DataArray containing the complex FID signal, dimensioned by `DIMS.time`, with coordinates `COORDS.time`, and rich simulation metadata. |