(sec_list_of_switches)=
# List of switches

The flexibility of AM$^3$ is implemented by *switches* which allow to turn on/off processes and optimizations: Interaction channels can be switched on and off individually by means of binary switches. For example, running 

```
am3.set_process_electron_compton_cooling(1)
```

switches on electron and positron energy losses due to inverse Compton scattering. On the contrary, setting a process to `0` makes the solver skip the calculation of that process. This can be used for testing purposes, or to improve the code performance in cases where it is known that a given process is not relevant.
The switches mainly use the naming patterns for particles and interactions introduced in the [Code Overview](code_overview).

The readout is symmetric to the `set` functions. E.g., to retrieve the setting for the electron compton cooling, use 

```
am3.get_process_electron_compton_cooling()
```

## Main switches for energy loss and secondary emission

|Process | Switch                              | Value | Default |
|----------------------------------|------------|---------------|----|
| Synchrotron| `am3.set_process_<particle>_syn()`                     |`0` (off) / `1` (on) | `1` for `electron` and `proton`,<br />`0` for `pion` and `muon` |
| Inverse Compton| `am3.set_process_<particle>_compton()`             |`0` (off) / `1` (on) | `1` for `electron` and `proton`,<br /> `0` for `pion` and `muon` |
| Photon-photon pair production | `am3.set_process_annihilation()`    |`0` (off) / `1` (on) | `1` | 
| Bethe-Heitler pair production | `am3.set_process_bethe_heitler()`   |`0` (off) / `1` (on) | `1` |   
| Photopion production | `am3.set_process_photopion()`   | `0` (off)/`1` (on)   |`1` |                         
| Proton-proton interactions | `am3.set_process_pp()`  |`0` (off) / `1` (on) | `1` |

For every master switch listed above, there is an additional `_cooling` switch for energy losses and a `_emission` switch for photon emission.

For example, by running

```
am3.set_process_muon_syn_cooling(1)
am3.set_process_muon_syn_cooling_cooling(1)
am3.set_process_muon_syn_cooling_emission(0)
```

we tell the solver to account for muon energy losses due to synchrotron, but to ignore the resulting photon emission. All  `_cooling` and  `_emission`  switches have a default value of `1`.\
Note: The photo-pion induced loss term for photons deviates from the above pattern and can be switched to `0` (off)/`1` (on) using `am3.set_process_photopion_photon_loss`

## Switches for other physics processes

A range of additional processes may be included using the following:

| Process | Switch                         | Values | Default |
|----------------------------|------------------|-------------------|-------|
| Phsyical escape | `am3.set_process_escape()`                     |`0` (off) / `1` (on) | `1` |
| Volume expansion | `am3.set_process_expansion()`             |`0` (off) / `1` (on) | `1`  |
| Adiabatic cooling of charged particles | `am3.set_process_adiabatic_cooling()`    |`0` (off) / `1` (on) | `1` | 
| Pion decay | `am3.set_process_pion_decay()`   |`0` (off) / `1` (on) | `1` |   
| Muon decay | `am3.set_process_muon_decay()`   |`0` (off) / `1` (on) | `1`  |     
| Synchrotron self-absorption | `am3.set_process_ssa()` |`0` (off) / `1` (on) | `1` |
| Include quantum synchrotron regime | `am3.set_process_quantum_syn()` |`0` (off) / `1` (on) | `0` |

Notes: *(1)* The escape rate depends on escape timescale and escape fractions, while both expansion and adiabatic cooling rate depend on the expansion timescale. *(2)* Pion and muon decay are necessary to estimate neutrino emission. *(3)* Quantum synchrotron (relevant in case of strong magnetic fields) is only included for electrons. 

For proton-proton interactions, additional switches to select the interaction description and the transition to the $\delta$-function description are available:
- `am3.set_pp_transition_energy_to_delta_approx()` sets the proton energy below which the delta approximation is used in eV. Default value is 100 GeV. 
- `am3.set_pp_model_charged_pions()`  sets the model underlying charged pions from pp interactions. Pass `0` (SIBYLL)/ `1` (QGSJET). Default value is `0`.
- `am3.set_pp_model_neutral_pions()`  sets the model underlying neutral  pions from pp interactions. Pass `0` (SIBYLL)/ `1` (QGSJET)/ `2` (Geant4)/ `3` (Pythia8). Default value is `0`.
- `set_process_pp_emission_pi0_into_cascade()` is used to specify the treatment of neutral pion decay. Pass `0` to use the Kelner+ (2006) treatment combined with the decay as photo-pion produced neutral pions, or `1` to use the treatment of Kafexhiu et al 2014. Default is `0`.



## Switches for performance optimization

| Switch                      | Value | Default | Description  |
|----------------------------|-------------------|-------|----------|
| Inverse Compton emission | | | | 
|`am3.set_optimize_compton_emission_emin()` | Energy | $10^{-3}$ eV | Min. energy point photon emission |
|`am3.set_optimize_compton_target_emax()`   | Energy | $10^{6}$ eV | Max. Grid energy target photon field |
|`am3.set_optimize_compton_target_grid()`	  | `0` (off)/<br />`1` (on)          | 1 | Use every second bin of target photon field |
|`am3.set_optimize_compton_emission_grid()` | `0` (off)/<br />`1` (on)          | 1 | Calculate every second bin of emitted photon field (interpolate inbetween) |
| Photon-photon pair production    |  | | | 
|`am3.set_optimize_annihilation_pair_emission()` | `0` (off)/<br />`1` (on) | `0` | Use 7-bin approximation for emitted pairs |
| Bethe-Heitler pair production            |  | | | 
| `am3.set_optimize_bethe_heitler_outgoing_pairs_grid()` |`0` (off)/<br />`1` (on)| 1 | Skip every second energy bin of emitted pairs|
| `am3.set_optimize_bethe_heitler_incoming_protons_min()` | Energy | 1 TeV | Min. energy target protons | 
| `am3.set_optimize_bethe_heitler_target_photon_max()` | Energy | $\sim$ 511 keV | Max. energy target photon field | 
| Photopion production   |  | | | 
| `am3.set_optimize_photopion_target_photon_grid()` |`0` (off)/<br />`1` (on) | 1 | Skip every 2nd energy bin of target photons|
| `am3.set_optimize_photopion_target_photon_max()` | Energy | $\sim$ 511 keV | Max. energy target photon field | 

If optimizers are switched on it is advised to test the results for accuracy.

## Other switches

| Process | Switch                            | Value | Default |
| ------- | -------------------------------------------|---------------| ------------- |
| Trace photon components | `am3.set_process_parse_sed()` |`0` (off) / `1` (on) | `0` |
| Turn off all hadronic processes | `am3.set_process_hadronic()` |`0` (off) / `1` (on) | `1` | 
| Electrons and positrons separately (`0`) or together (`1`) | `am3.set_process_merge_positrons_into_electrons` |`0` (off) / `1` (on) | `0` |
| Calculate maximal energies for template injection | `am3.set_estimate_max_energies()` |`0` (off) / `1` (on) | `0` |