# Fit templates

A template is a YAML file with one or more regions. It is validated before any fitting happens,
so a typo fails with a precise message instead of a strange fit.

```yaml
name: Te3d                 # used in reports and file names
version: "1"
description: Tellurium 3d: telluride / Te0 and Te(IV) oxide doublets.
source: Moulder et al. 1992; NIST SRD 20      # where the numbers come from, in words
references: [moulder1992, nist_srd20]        # bibliography keys (elements/data/bibliography.yaml)
regions:
  - label: Te 3d           # matched against spectrum labels ("Te 3d", "Te3d")
    element: Te
    orbital: 3d
    window: [568.0, 592.0] # binding-energy range that is fitted (eV)
    background: shirley    # shirley | tougaard | linear | active_shirley | none
    background_params: {}  # e.g. {fit_B: true} for tougaard, {n_avg: 7} for shirley
    lineshape: pseudo_voigt  # default for components: pseudo_voigt | gl_product | voigt |
                             # gaussian | lorentzian | doniach_sunjic | exp_tail
    default_shape:
      eta: {value: 0.3, min: 0.1, max: 0.7}   # shape parameters shared by default
    fwhm_tolerance: 0.15   # optional: every width within ±15 % of the first component's
    rsf_line: Te 3d5/2     # line whose (whole-doublet) sensitivity factor is used
    components:
      - name: Te-M
        chemical_state: telluride / metallic Te
        provenance: {source: bahl1978, method: literature}   # see docs/constraints.md
        center: {value: 572.8, min: 571.8, max: 573.6}
        fwhm:   {value: 1.0,   min: 0.6,   max: 1.6}
        area:   {min: 0}                 # initial area is guessed from the data
        doublet:
          splitting: 10.39               # minor line at center + splitting
          ratio: 0.6667                  # minor / major area
          splitting_vary: false          # optionally free within ±splitting_tolerance
          share_fwhm: true
      - name: Te(IV)
        enabled: true                    # disabled components are kept but not fitted
        center: {expr: "{Te-M.center} + 3.3"}   # tie to another component
        fwhm:   {expr: "{Te-M.fwhm} * 1.25"}
        doublet: {splitting: 10.39, ratio: 0.6667}
```

## Parameters

Each of `center`, `fwhm`, `area` and the shape parameters takes `value`, `min`, `max`,
`vary` and `expr`. An `expr` uses lmfit syntax, where `{Component.param}` refers to another
component's parameter. Expressions are resolved after all components are created, so forward
references work.

## Lineshapes and their shape parameters

| lineshape | parameters | notes |
|---|---|---|
| `pseudo_voigt` | `eta` | sum form, `eta` = Lorentzian fraction |
| `gl_product` | `m` | product GL(m); true FWHM equals `fwhm` for every `m` |
| `voigt` | — | true Voigt via the Faddeeva function |
| `doniach_sunjic` | `asymmetry`, `fwhm_g` | metals; Gaussian-broadened; area over ±25 FWHM |
| `exp_tail` | `eta`, `tail_scale`, `tail_mix` | pseudo-Voigt with an exponential high-BE tail |

## Getting a starting template

```bash
xpsflow propose data/sample.vms "sample/Se 3d" --out templates/Se3d_mine.yaml
```

This proposes components from the detected peaks and assigns them to literature chemical states
that are plausible for the elements found on the sample. Edit it, then run with
`xpsflow run data/ --template templates/Se3d_mine.yaml`.

## Provenance

Every component may carry `provenance: {source, method, note}`. `source` is a bibliography key;
`method` is one of `literature`, `instrument`, `user`, `data` or `default`. Components without a
block inherit the region's provenance, then the template's first reference. Components xpsflow
proposes itself are marked `data`. The report prints the full table; see `docs/constraints.md`.

## Reproducibility

Every run writes the exact regions it used, after model selection, to `templates/` next to the
report, so the analysis can be repeated or reviewed without the original session.