Synthetic Data Generation
=========================

The `QSynthetic` class provides generators for 20+ dynamical regimes.

Basic Usage
-----------

.. code-block:: python

   import QSignature
   syn = QSignature.QSynthetic()

   # Exponential decay
   t, R = syn.exponential_decay(tau=2.0)

   # Underdamped oscillator
   t, R = syn.underdamped_oscillator(alpha=0.2, omega_d=6.0)

   # Overdamped system
   t, R = syn.overdamped_system(tau1=0.5, tau2=3.0)

   # Conservative oscillator
   t, R = syn.conservative_oscillator(omega0=2*np.pi)

Available Systems
-----------------

.. list-table::
   :widths: 25 75
   :header-rows: 1

   * - Method
     - Description
   * - `exponential_decay()`
     - First-order exponential relaxation
   * - `underdamped_oscillator()`
     - Underdamped harmonic oscillator
   * - `overdamped_system()`
     - Overdamped or critically damped system
   * - `conservative_oscillator()`
     - Undamped (conservative) oscillations
   * - `duffing_oscillator()`
     - Nonlinear Duffing oscillator
   * - `powerlaw_decay()`
     - Power-law/heavy-tailed decay
   * - `chaotic_system()`
     - Lorenz or Rössler chaotic systems
   * - `fractional_order_system()`
     - Fractional order differential equations
   * - `chirp_system()`
     - Time-varying frequency (chirp)
   * - `multiscale_system()`
     - Multiple interacting temporal scales
   * - `intermittent_system()`
     - Bursty/intermittent dynamics

Adding Noise
------------

.. code-block:: python

   # Add Gaussian noise during generation
   t, R = syn.underdamped_oscillator(alpha=0.2, omega_d=6.0, noise_std=0.05)

   # Add noise after generation
   R_noisy = syn.add_measurement_noise(R, noise_type='gaussian', std=0.1)

Sampling Irregularities
-----------------------

.. code-block:: python

   t_irr, R_irr = syn.add_sampling_irregularities(t, R, missing_prob=0.05)

Batch Dataset Generation
------------------------

.. code-block:: python

   dataset = syn.generate_dataset(n_samples=100, add_noise=True, noise_std=0.05)