Document ces_source units and API contracts (closes #269)

[yuema137]

Summary

Resolves all five items raised in #269 — primarily by adding/expanding
docstrings on CESTemplateSource and its methods so the public API is
self-documenting (units, return types, lifecycle role).

Changes

• Class docstring on CESTemplateSource (cedc847) — reference
  table for required/optional config keys with explicit units, including
  rate_multiplier in events / (ton·year), fiducial_mass in ton,
  livetime_days in days, and energies in keV. [CES issues #269 item 1]
• pdf() docstring (a7b2f17) — clarifies the method evaluates
  the PDF at given CES coordinates and returns an array of values
  (not a callable); documents out-of-range behavior for piecewise vs
  linear interpolation. [CES issues #269 item 2]
• get_pmf_grid() docstring (a41fa82) — explains PMF vs PDF,
  why this method overrides the blueice default (per-source rebinning
  to minimal_energy_resolution differs from the shared
  analysis_space), and what each return value represents.
  [CES issues #269 item 3]
• Day-year conversion 365.26 → 365.25 (a97b0a5). [CES issues #269 item 4]
• compute_pdf() docstring (c5c60b7) — explains the method is a
  one-time lifecycle hook (not a per-point evaluator) and flags that
  the override is currently identical in body to
  HistogramPdfSource.compute_pdf. [CES issues #269 item 5]
• Broaden Transformation.parameters typing in ces_transformation.py
  (3c4ba41) — accept int, bool, and str in addition to float,
  so transformation parameters aren't forced through unnecessary float
  coercion. Same API-clarity theme as the docstring work, though not
  explicitly listed in CES issues #269.

Scope

The ces_source.py changes are doc-only; the only behavior changes
are the 365.25 day-year fix and the broadened Transformation
parameter typing.

Known follow-ups (intentionally out of scope)

• _calculate_expected_events multiplies by rate_multiplier twice
  while * fiducial_mass is commented out — looks like a units bug
  worth a separate fix.
• get_pmf_grid still has a stray print("from cache?", ...) debug
  line, and its second return value is zeros where blueice's contract
  documents float('inf') for non-density-estimating sources.
• CESTemplateSource.compute_pdf is currently redundant with the
  blueice parent and could be removed.

Test plan

• CI passes
• help(CESTemplateSource) shows the new config-key reference
• Sphinx/docs build (if any) picks up the new docstrings cleanly
• No behavior regressions in downstream fits using these sources

🤖 Generated with Claude Code

[coveralls]

Coverage Report for CI Build 25090677079

Coverage remained the same at 76.422%

Details

• Coverage remained the same as the base build.
• Patch coverage: 4 uncovered changes across 2 files (0 of 4 lines covered, 0.0%).
• 1 coverage regression across 1 file.

Uncovered Changes

File	Changed	Covered	%
alea/ces_source.py	2	0	0.0%
alea/ces_transformation.py	2	0	0.0%

Coverage Regressions

1 previously-covered line in 1 file lost coverage.

File	Lines Losing Coverage	Coverage
alea/ces_source.py	1	0.0%

---

Coverage Stats

Relevant Lines:	2303
Covered Lines:	1760
Line Coverage:	76.42%
Coverage Strength:	1.53 hits per line

---

💛 - Coveralls