Full-repo audit and cleanup: correctness, efficiency, redundancy, docstrings, static typing

[almilder]

Summary

Full-repo audit and cleanup covering correctness, efficiency, redundancy, docstrings, user-facing docs, and static-typing issues surfaced by pyright/Pylance.

Correctness fixes

• calc_series.py: fixed a real NameError (undefined fe_val/velocity) and a wrong-argument-count call to plot_dist in the non-angular 2D-distribution plotting branch.
• loss_function.py: loss() called self.unravel_pytree, an attribute that was never assigned (only unravel_weights was ever set); loss_functionals() raised an opaque UnboundLocalError for an unrecognized loss_method instead of a clear ValueError.
• warpcorr.py: added a clear NotImplementedError for non-EPW instruments instead of a silent crash.
• distribution_functions/base.py: calc_moment now raises a clear error for unsupported distribution-function shapes instead of returning an unbound variable.
• load_ts_data.py: fixed two invalid \m escape sequences in axis-label strings.

Efficiency improvements

• loss_function.py: removed a duplicate forward-model call in calc_loss, vectorized calculate_covariance_matrix with vmap instead of an unrolled Python loop.
• form_factor.py: cached the Z-prime table disk reads instead of reloading them on every FormFactor construction.
• postprocess.py / calc_series.py: hoisted ThomsonScatteringDiagnostic construction out of per-batch/per-iteration loops.
• warpcorr.py: vectorized the pixel-by-pixel dewarping loop (up to ~1M iterations per shot) using np.add.at-based scatter-accumulation; verified byte-exact against the original loop-based implementation on real shot data.
• correct_throughput.py: replaced a tile+transpose allocation with plain broadcasting, and a cell-by-cell xlrd read loop with vectorized col_values calls; also drops the deprecated numpy.matlib.repmat import. Both verified exact-match against the originals.

Redundancy / simplification

• generate_spectra.py: consolidated ion_spectrum/electron_spectrum and their _detailed counterparts around shared core methods; verified bit-exact against the pristine pre-refactor implementation on both the fast and detailed paths.
• plotters.py: factored detailed_lineouts's duplicated worst/best plotting blocks into a shared helper, fixing a real bug uncovered in the process (the "worst" block never set the ion subplot's y-limit due to a copy-paste slip); factored the duplicated white-transition colormap construction.
• example_plot.py: deleted -- never functional as written, and nothing referenced it beyond a stale auto-generated docs stub.
• edf_movie.py: replaced a hardcoded personal file path with a documented, editable constant.

Docstrings

Added missing public function/method docstrings across the touched modules, and module-level docstrings to every file in the package that lacked one.

Documentation

docs/source/getting_started.rst now documents the standalone postprocessor runner and cluster job submission (queue_tsadar.py, the machine config field, and the required Slurm environment variables), neither of which were previously documented.

Test plan

• pytest tests/ — 125 passed, 5 skipped, run on this branch (stacked on Refactor postprocessing into a single batch-handling path; add standalone postprocessor runner #128, Fix calibration fallback warning and surface EPWtcc/IAWtcc for unknow… #129, Close matplotlib figures in the data visualizer to prevent an OOM error #131)

[almilder]

Review summary

Reviewed the full diff against main. The bulk of this PR is docstrings, comments, and faithful refactors — deduplicating near-identical code in plotters.py/generate_spectra.py, vectorizing warpcorr.py's dewarp loop, and caching zprimeMaxw's lookup tables. Every substantive behavioral change was traced against its pre-PR equivalent and found to be equivalent or a genuine fix, including two incidental correctness fixes bundled in:

• unravel_pytree → unravel_weights fixes a real AttributeError that exists on main today.
• log_mlflow's % → ceiling-division fix corrects real silent data-dropping for batches of >1000 entries.
• The plot_dist call-site fix removes a stale extra positional arg that would have raised TypeError.

Finding

• tsadar/data/data_visualizer.py — the lineouts-with-background plot was gated by a bare config["data"]["background"]["report_background"] lookup with no default, replacing the old type in ["fit", "pixel"] check that only ever relied on type (a key every config has always had). Every config shipped in this repo has report_background now (added in Close matplotlib figures in the data visualizer to prevent an OOM error #131), but any external or hand-maintained deck that predates that change has no way to know it needs the key, and would hit a bare KeyError: 'report_background' from inside prepare_data on a fresh fit with launch_data_visualizer: true — where the same deck previously ran fine.

Fix

Checks for the key explicitly and raises with a message that says what's missing and how to fix it, instead of a bare KeyError:

if "report_background" not in config["data"]["background"]:
    raise KeyError(
        "config['data']['background'] is missing 'report_background'; add it (True/False) to your deck"
    )