Quick Start
===========

This guide will get you started with QSignature in 5 minutes.

Script 1: Basic Classification (10 lines)
-----------------------------------------

.. code-block:: python

   import numpy as np
   import QSignature

   t = np.linspace(0, 10, 1000)
   R = 1 - np.exp(-0.3 * t) * np.cos(2 * np.pi * t)

   tau_s = QSignature.tau_s(t, R)
   tau_u = QSignature.tau_u(t, R)
   R_su = tau_s / tau_u

   print(f"R_su = {R_su:.3f}")
   print("→ DECAYING amplitude" if R_su < 1 else "→ GROWING amplitude")

**Output:**

.. code-block::

   R_su = -0.184
   → DECAYING amplitude

Script 2: Growth vs Decay Detection
-----------------------------------

.. code-block:: python

   import numpy as np
   import QSignature

   t = np.linspace(0, 10, 1000)

   # Decaying signal
   R_decay = 1 - np.exp(-0.3 * t) * np.cos(2 * np.pi * t)

   # Growing signal
   R_grow = 1 - np.exp(0.15 * t) * np.cos(2 * np.pi * t)
   R_grow = (R_grow - R_grow.min()) / (R_grow.max() - R_grow.min())

   R_su_decay = QSignature.tau_s(t, R_decay) / QSignature.tau_u(t, R_decay)
   R_su_grow = QSignature.tau_s(t, R_grow) / QSignature.tau_u(t, R_grow)

   print(f"Decaying: R_su = {R_su_decay:.3f} → {'DECAY' if R_su_decay < 1 else 'GROWTH'}")
   print(f"Growing:  R_su = {R_su_grow:.3f} → {'DECAY' if R_su_grow < 1 else 'GROWTH'}")

**Output:**

.. code-block::

   Decaying: R_su = -0.184 → DECAY
   Growing:  R_su = 2.073 → GROWTH

**Key insight:** QSignature clearly distinguishes between decaying and growing amplitude signals.

Script 3: QSpace Classification Demo
-------------------------------------

.. code-block:: python

   import numpy as np
   import QSignature

   t = np.linspace(0, 20, 2000)

   # Define different dynamical systems
   systems = {
       'Exponential Decay': lambda: 1 - np.exp(-0.5 * t),
       'Underdamped': lambda: 1 - np.exp(-0.2 * t) * np.cos(3 * t),
       'Weakly Damped': lambda: 1 - np.exp(-0.05 * t) * np.cos(5 * t),
       'Growth': lambda: 1 - np.exp(0.1 * t) * np.cos(2 * t),
   }

   print("="*60)
   print("QSPACE CLASSIFICATION DEMO")
   print("="*60)
   print(f"{'System':<18} {'R_su':>10} {'Δ_su':>10} {'Regime':>15}")
   print("-"*60)

   for name, func in systems.items():
       R = func()
       if name == 'Growth':
           R = (R - R.min()) / (R.max() - R.min())

       tau_s = QSignature.tau_s(t, R)
       tau_u = QSignature.tau_u(t, R)
       R_su = tau_s / tau_u
       Delta_su = R_su - 1

       if R_su > 1:
           regime = "GROWTH"
       elif R_su < 0:
           regime = "WEAKLY DAMPED"
       elif R_su < 1:
           regime = "UNDERDAMPED"
       else:
           regime = "EXPONENTIAL"

       print(f"{name:<18} {R_su:>+10.4f} {Delta_su:>+10.4f} {regime:>15}")

**Output:**

.. code-block::

   ============================================================
   QSPACE CLASSIFICATION DEMO
   ============================================================
   System                   R_su       Δ_su          Regime
   ------------------------------------------------------------
   Exponential Decay     +1.0000    -0.0000     UNDERDAMPED
   Underdamped           +0.0788    -0.9212     UNDERDAMPED
   Weakly Damped         -1.1150    -2.1150   WEAKLY DAMPED
   Growth                +1.2872    +0.2872          GROWTH

Understanding R_su
------------------

.. table::
   :widths: 30 70

   +----------------+------------------------------------------------+
   | R_su Value     | Meaning                                        |
   +================+================================================+
   | R_su > 1       | GROWING amplitude (late-time dominance)        |
   +----------------+------------------------------------------------+
   | 0 < R_su < 1   | DECAYING amplitude (underdamped)               |
   +----------------+------------------------------------------------+
   | R_su < 0       | DECAYING amplitude (weakly damped)             |
   +----------------+------------------------------------------------+
   | R_su ≈ 1       | STABLE amplitude (exponential)                 |
   +----------------+------------------------------------------------+

Important Notes
---------------

- **R_su < 0** indicates strong decay (weakly damped regime)
- **R_su > 1** indicates growth
- The Exponential Decay system appears as UNDERDAMPED because its R_su = 1.0000 (boundary case)
- For precise regime classification, refer to the QSpace boundaries in :doc:`qspace_classification`

Next Steps
----------

- See :doc:`qspace_classification` for detailed regime boundaries
- See :doc:`synthetic_data` for generating test signals
- See :doc:`api` for complete API reference