(md_extended_kernels)=

# Extended multidimensional kernels

```{warning}
This page is a stub generated by Codex. The content has been verified, but important information (references, links to external packages) may be missing  
```

The standard multidimensional quasi-periodic model uses one latent quasi-periodic GP and, optionally, its first derivative. `PyORBIT` also includes `tinygp` multidimensional kernels that add a second latent component: either a cosine term or a squared-exponential term.

These models are useful when the data show an activity signal that is not fully described by a single quasi-periodic latent process.

## Model definition and requirements

**model name**: `tinygp_multidimensional_quasiperiodiccosine`
- required common object: `activity`
- aliases: `tinygp_multidimensional_quasiperiodic_cosine`
- adds a cosine latent component to the quasi-periodic latent GP

**model name**: `tinygp_multidimensional_quasiperiodicsquaredexponential`
- required common object: `activity`
- aliases: `tinygp_multidimensional_quasiperiodic_squaredexponential`
- adds a squared-exponential latent component with timescale `Pcyc`

**model name**: `tinygp_multiquasiperiodic_trainedsquaredexponential`
- required common object: `activity`
- aliases: `tinygp_multiquasiperiodictrainedsquaredexponential`
- adds a squared-exponential component trained independently within each dataset, while the quasi-periodic component remains multidimensional

All three models require `tinygp`; read [Caveats on the use of `tinyGP`](../running_pyorbit/tinygp_caveats) carefully.

## Keywords

Model-wide keywords, with the default value in boldface.

**hyperparameters_condition**
* accepted values: `True` | **`False`**
* activates the quasi-periodic hyperparameter condition described in the [quasi-periodic kernel](../gaussian_process/quasiperiodic_kernel).

**rotation_decay_condition**
* accepted values: `True` | **`False`**
* if activated, requires `Pdec > 2 Prot`.

**use_stellar_rotation_period**
* accepted values: `True` | **`False`**
* replaces `Prot` with `rotation_period` from `star_parameters`.

**use_stellar_activity_decay**
* accepted values: `True` | **`False`**
* replaces `Pdec` with `activity_decay` from `star_parameters`.

**derivative**
* accepted values: mapping of dataset names to booleans
* sets the default derivative use for each dataset. If not provided, derivatives are enabled for most datasets and disabled for `H-alpha`, `S_index`, `Ca_HK`, and `FWHM`.

**derivative_quasiperiodic**
* accepted values: mapping of dataset names to booleans
* overrides the derivative switch for the quasi-periodic component. If `False`, `rot_amp` is fixed to zero for that dataset.

**derivative_cosine**
* accepted values: mapping of dataset names to booleans
* used by `tinygp_multidimensional_quasiperiodiccosine`. If `False`, `cos_der` is fixed to zero for that dataset.

**derivative_squaredexponential**
* accepted values: mapping of dataset names to booleans
* used by `tinygp_multidimensional_quasiperiodicsquaredexponential`. If `False`, `cyc_der` is fixed to zero for that dataset.

## Examples

Quasi-periodic plus cosine:

```yaml
models:
  gp_multidimensional:
    model: tinygp_multidimensional_quasiperiodiccosine
    common: activity
    hyperparameters_condition: True
    rotation_decay_condition: True
    RVdata:
      boundaries:
        rot_amp: [0.0, 20.0]
        con_amp: [-20.0, 20.0]
        cos_amp: [-20.0, 20.0]
        cos_der: [-20.0, 20.0]
      derivative_quasiperiodic: True
      derivative_cosine: True
    Sdata:
      boundaries:
        con_amp: [-1.0, 1.0]
        cos_amp: [-1.0, 1.0]
      derivative_quasiperiodic: False
      derivative_cosine: False
```

Quasi-periodic plus squared-exponential:

```yaml
common:
  activity:
    boundaries:
      Prot: [10.0, 20.0]
      Pdec: [20.0, 1000.0]
      Pcyc: [100.0, 5000.0]
      Oamp: [0.001, 1.0]
models:
  gp_multidimensional:
    model: tinygp_multidimensional_quasiperiodicsquaredexponential
    common: activity
    RVdata:
      boundaries:
        rot_amp: [0.0, 20.0]
        con_amp: [-20.0, 20.0]
        cyc_amp: [-20.0, 20.0]
        cyc_der: [-20.0, 20.0]
      derivative_quasiperiodic: True
      derivative_squaredexponential: True
```

Trained squared-exponential component:

```yaml
models:
  gp_multidimensional:
    model: tinygp_multiquasiperiodic_trainedsquaredexponential
    common: activity
    RVdata:
      boundaries:
        rot_amp: [0.0, 20.0]
        con_amp: [-20.0, 20.0]
        cyc_amp: [0.0, 20.0]
      derivative_quasiperiodic: True
```

## Model parameters

### Quasi-periodic plus cosine

| Name | Parameter | Common? | Definition | Notes |
| :--- | :-------- | :------ | :--------- | :---- |
| `Prot` | Rotational period of the star | common | `activity` | |
| `Pdec` | Decay timescale of active regions | common | `activity` | |
| `Oamp` | Coherence scale | common | `activity` | |
| `con_amp` | Coefficient of the quasi-periodic latent GP | dataset | `activity` | |
| `rot_amp` | Coefficient of the quasi-periodic derivative | dataset | `activity` | Fixed to zero when `derivative_quasiperiodic: False` |
| `cos_amp` | Coefficient of the cosine latent component | dataset | `activity` | |
| `cos_der` | Coefficient of the derivative of the cosine component | dataset | `activity` | Fixed to zero when `derivative_cosine: False` |

### Quasi-periodic plus squared-exponential

| Name | Parameter | Common? | Definition | Notes |
| :--- | :-------- | :------ | :--------- | :---- |
| `Prot` | Rotational period of the star | common | `activity` | |
| `Pdec` | Decay timescale of active regions | common | `activity` | |
| `Pcyc` | Timescale of the squared-exponential component | common | `activity` | |
| `Oamp` | Coherence scale | common | `activity` | |
| `con_amp` | Coefficient of the quasi-periodic latent GP | dataset | `activity` | |
| `rot_amp` | Coefficient of the quasi-periodic derivative | dataset | `activity` | Fixed to zero when `derivative_quasiperiodic: False` |
| `cyc_amp` | Coefficient of the squared-exponential component | dataset | `activity` | |
| `cyc_der` | Coefficient of the derivative of the squared-exponential component | dataset | `activity` | Fixed to zero when `derivative_squaredexponential: False` |

### Multidimensional quasi-periodic plus trained squared-exponential

| Name | Parameter | Common? | Definition | Notes |
| :--- | :-------- | :------ | :--------- | :---- |
| `Prot` | Rotational period of the star | common | `activity` | |
| `Pdec` | Decay timescale of active regions | common | `activity` | |
| `Pcyc` | Timescale of the trained squared-exponential component | common | `activity` | |
| `Oamp` | Coherence scale | common | `activity` | |
| `con_amp` | Coefficient of the quasi-periodic latent GP | dataset | `activity` | |
| `rot_amp` | Coefficient of the quasi-periodic derivative | dataset | `activity` | Fixed to zero when `derivative_quasiperiodic: False` |
| `cyc_amp` | Amplitude coefficient of the dataset-local squared-exponential component | dataset | `activity` | |