(sho_matern32_kernels)=

# SHO and Matern-3/2 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 SHO and Matern-3/2 kernels are generic GP kernels that can be used for stellar variability or correlated residuals. By default their parameters are dataset-specific. They can also share timescales across datasets or borrow the stellar rotation and activity-decay parameters from common objects.

## Model definition and requirements

**model name**: `tinygp_sho`
- required common object: `activity`
- implemented with `tinygp`

**model name**: `celerite2_sho`
- required common object: `activity`
- implemented with `celerite2`

**model name**: `spleaf_sho`
- required common object: `activity`
- implemented with `S+LEAF`

**model name**: `tinygp_matern32`
- required common object: `activity`
- implemented with `tinygp`

**model name**: `celerite2_matern32`
- required common object: `activity`
- implemented with `celerite2`

## Keywords

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

**use_shared_hyperparameters**
* accepted values: `True` | **`False`**
* moves all kernel parameters from dataset-specific to common parameters. For SHO models this includes `sho_scale`, `sho_decay`, and `sho_sigma`; for Matern-3/2 models this includes `matern32_scale` and `matern32_sigma`.

**use_shared_scale**
* accepted values: `True` | **`False`**
* makes only the kernel timescale common. For SHO models this is `sho_scale`; for Matern-3/2 models this is `matern32_scale`.

**use_shared_decay**
* accepted values: `True` | **`False`**
* makes only the SHO damping timescale `sho_decay` common.

**use_activity_Prot**
* accepted values: `True` | **`False`**
* replaces the kernel scale with `Prot` from the `activity` common object.

**use_activity_Pdec**
* accepted values: `True` | **`False`**
* replaces the kernel decay or scale with `Pdec` from the `activity` common object.

**use_stellar_rotation_period**
* accepted values: `True` | **`False`**
* replaces the kernel scale with `rotation_period` from `star_parameters`.

**use_stellar_activity_decay**
* accepted values: `True` | **`False`**
* replaces the kernel decay or scale with `activity_decay` from `star_parameters`.

For Matern-3/2 models the replacement flags are mutually exclusive because there is only one timescale.

The SHO models also support the hyperparameter-condition keywords described in the [quasi-periodic plus derivative kernel](quasiperiodic_derivative_kernel.md). In that case the SHO scale is interpreted as `Prot` and the SHO decay is interpreted as `Pdec` for the purpose of the condition.

## Examples

Dataset-specific SHO kernel:

```yaml
models:
  celerite2_sho:
    model: celerite2_sho
    boundaries:
      sho_scale: [0.1, 100.0]
      sho_decay: [0.1, 1000.0]
      sho_sigma: [0.0, 1.0]
```

Matern-3/2 kernel with a shared timescale:

```yaml
common:
  activity:
    boundaries:
      matern32_scale: [0.1, 100.0]
models:
  tinygp_matern32:
    model: tinygp_matern32
    common: activity
    use_shared_scale: True
    boundaries:
      matern32_sigma: [0.0, 1.0]
```

SHO kernel using stellar rotation and activity decay from `star_parameters`:

```yaml
common:
  activity:
    model: activity
  star:
    star_parameters:
      boundaries:
        rotation_period: [10.0, 20.0]
        activity_decay: [20.0, 1000.0]
models:
  spleaf_sho:
    model: spleaf_sho
    common:
      - activity
      - star_parameters
    use_stellar_rotation_period: True
    use_stellar_activity_decay: True
    boundaries:
      sho_sigma: [0.0, 1.0]
```

## Model parameters

### SHO models

| Name | Parameter | Common? | Definition | Notes |
| :--- | :-------- | :------ | :--------- | :---- |
| `sho_scale` | SHO undamped period, or `rho` | dataset | `activity` | Common when `use_shared_scale: True` or `use_shared_hyperparameters: True` |
| `sho_decay` | SHO damping timescale, or `tau` | dataset | `activity` | Common when `use_shared_decay: True` or `use_shared_hyperparameters: True` |
| `sho_sigma` | Standard deviation of the process | dataset | `activity` | Common when `use_shared_hyperparameters: True` |

### Matern-3/2 models

| Name | Parameter | Common? | Definition | Notes |
| :--- | :-------- | :------ | :--------- | :---- |
| `matern32_scale` | Matern-3/2 scale, or `rho` | dataset | `activity` | Common when `use_shared_scale: True` or `use_shared_hyperparameters: True` |
| `matern32_sigma` | Standard deviation of the process | dataset | `activity` | Common when `use_shared_hyperparameters: True` |

```{tip}
Some older result files may contain `matern32_rho`. The current models map it internally to `matern32_scale`.
```