main ion density calculation using a combination of VB and CER diagnostics in IDA-lite

[StuartBenjamin]

Major changes:

i. "ni_source" allows user to choose whether to use CER, VB (Zeff) or both when calculating ni and its error from ida-lite files
- see bottom text for the mathematical error formulation
ii. ni_sigma overrides the zeff_active method in perturb_equilibrium when it has a real value from ida-lite
- controlled by ni_from_zeff, which is automatically set False when sigma_ni is not a flat ni_scalar_sigma
- Zeff is still drawn as an aux channel, and used in the bootstrap either

Minor changes:

a. zeff comes from ida-lite unless zeff_from_fuse=True. Error envelope comes from ida-lite either way
b. re-adding the option to use median instead of mean for ida-lite sample centers (default is false, no change to normal running)
c. Minor test updates to include Zeff_err / n_12C6 / n_12C6_err channels

Mathematics behind error propagation:

Symbols

Symbol	Code	Meaning
$Z$	impurity_Z	Impurity charge (6 for C)
$n_e, \sigma_{n_e}$	ne, sigma_ne	Electron density and its 1-sigma
$Z_\mathrm{eff}, \sigma_{Z_\mathrm{eff}}$	Zeff, sigma_Zeff	Effective charge (visible bremsstrahlung) and 1-sigma
$n_C, \sigma_{n_C}$	n_carbon, sigma_n_carbon	Carbon density (CER) and 1-sigma
$w$	w	Route weight: 1/2 if both routes active, else 1

Clipping

$$\tilde{Z}_\mathrm{eff} \equiv \mathrm{clip}\left(Z_\mathrm{eff},\, 1,\, Z\right)$$

guarantees $0 \le n_{i,Z_\mathrm{eff}} \le n_e$.

Route 1 - ion density from Zeff assuming single impurity species, visible Bremsstrahlung diagnostic

$$n_{i,Z_\mathrm{eff}} = n_e \frac{Z-\tilde{Z}_\mathrm{eff}}{Z-1}$$ $$\frac{\partial n_{i,Z_\mathrm{eff}}}{\partial n_e} = \frac{Z-\tilde{Z}_\mathrm{eff}}{Z-1} \qquad \left|\frac{\partial n_{i,Z_\mathrm{eff}}}{\partial Z_\mathrm{eff}}\right| \sigma_{Z_\mathrm{eff}} = \frac{n_e\, \sigma_{Z_\mathrm{eff}}}{Z-1}$$

Route 2 - ion density calculated via dilution due to carbon, CER diagnostic

$$n_{i,\mathrm{CER}} = \max\left(n_e - Z n_C,\; 0\right)$$ $$\frac{\partial n_{i,\mathrm{CER}}}{\partial n_e} = 1 \qquad \left|\frac{\partial n_{i,\mathrm{CER}}}{\partial n_C}\right| \sigma_{n_C} = Z \sigma_{n_C}$$

Combined estimate

$$n_i = w\, n_{i,Z_\mathrm{eff}} + w\, n_{i,\mathrm{CER}}$$

with equal weights $w = 1/2$ when both routes are active.

Propagated variance

$$\boxed{\;\sigma_{n_i}^2 = \sigma_\mathrm{prop}^2 + \frac{\max\left(0,\; \Delta^2 - \sigma_\Delta^2\right)}{4}\;}$$

where

$$D_{n_e} \equiv \frac{\partial n_i}{\partial n_e} = w \frac{Z-\tilde{Z}_\mathrm{eff}}{Z-1} + w = w \frac{2Z - \tilde{Z}_\mathrm{eff} - 1}{Z-1}$$ $$\sigma_\mathrm{prop}^2 = \underbrace{\left(\frac{w\, n_e\, \sigma_{Z_\mathrm{eff}}}{Z-1}\right)^2}_{Z_\mathrm{eff}} + \underbrace{\left(w Z \sigma_{n_C}\right)^2}_{n_C} + \underbrace{\left(D_{n_e} \sigma_{n_e}\right)^2}_{n_e \text{: summed, then squared}}$$

with the assumption $\mathrm{cov}(Z_\mathrm{eff}, n_C) = 0$ (separate diagnostics).

$$\Delta \equiv n_{i,Z_\mathrm{eff}} - n_{i,\mathrm{CER}} = Z n_C - n_e \frac{\tilde{Z}_\mathrm{eff}-1}{Z-1}$$ $$\frac{\partial \Delta}{\partial n_e} = \frac{Z-\tilde{Z}_\mathrm{eff}}{Z-1} - 1 = -\frac{\tilde{Z}_\mathrm{eff}-1}{Z-1}$$ $$\sigma_\Delta^2 = \left(\frac{\tilde{Z}_\mathrm{eff}-1}{Z-1} \sigma_{n_e}\right)^2 + \left(\frac{n_e \sigma_{Z_\mathrm{eff}}}{Z-1}\right)^2 + \left(Z \sigma_{n_C}\right)^2$$

Note: $\sigma_\Delta^2 \ne \sigma_1^2 + \sigma_2^2$$.

The ion density expression comes from the DerSimonian-Laird
method-of-moments with k=2 and us prescribing a weight factor w = 1/2:

$$\hat{\tau}^2 = \frac{\max\left(0,\; \Delta^2 - \sigma_\Delta^2\right)}{2} \qquad \left[w^2 + (1-w)^2\right]\hat{\tau}^2 = \frac{\hat{\tau}^2}{2}$$

It reduces to the propagated variance when the two ion
density calculations agree routes agree, and to (Delta/2)^2 when a
discrepancy dominates.

Reported tension

Returned as ni_route_chi, defined as

$$\chi_\mathrm{route} = \frac{|\Delta|}{\sigma_\Delta}$$

It is NaN where the variance of Delta is zero, and None when only one route
is active.