add readme v3

Author: ppraneth

src/torchjd/scalarization/README.md

@@ -6,32 +6,44 @@ vector of losses) into a single scalar optimizable with a standard `loss.backwar
 This file is for contributors working on scalarizers. For the list of available scalarizers and their
 full API, see [torchjd.org](https://torchjd.org/latest/docs/scalarization/).
 
-## The contract
+## The abstraction
 
-A scalarizer subclasses `Scalarizer` (in [`_scalarizer_base.py`](_scalarizer_base.py)) and implements
-one method:
+A scalarizer captures a single decision: **how to collapse a vector of objective values into one
+scalar to minimize**, using only those values. It is the value-level counterpart of an aggregator,
+which makes the same kind of decision at the gradient level. Everything after it (backpropagation,
+the optimizer step) is standard PyTorch.
+
+Concretely, it subclasses `Scalarizer` (in [`_scalarizer_base.py`](_scalarizer_base.py)) and
+implements one method:
 
 ```python
 def forward(self, values: Tensor, /) -> Tensor:
     ...
 ```
 
-- **Any shape in, scalar out:** it reduces over *all* elements of `values` (0-dim, vector, matrix,
-  higher-dim) into a 0-dim scalar.
-- **`values`, not `losses`:** a scalarizer is generic and not tied to losses.
-- **Pure and differentiable:** the output depends only on `values` and the configured parameters, so
-  that `scalarizer(values).backward()` produces the gradient.
+- It reduces over *all* elements of `values`, of any shape, into a 0-dim scalar.
+- The result is a **differentiable** function of `values` and the configured parameters, so that
+  `scalarizer(values).backward()` produces the gradient.
+
+## What is not a scalarizer
+
+A scalarizer sees only the values. Its gradient-level counterpart lives in the
+[aggregation](../aggregation) package: an `Aggregator` (which, like a scalarizer, can be stateful)
+combines the per-objective *gradients* (the Jacobian or its Gramian) into a single gradient.
+
+So if your method needs the model, its parameters, or the per-objective gradients (gradient norms,
+for instance), it is an aggregator, not a scalarizer.
 
 ## Adding one
 
 A new scalarizer is a class plus the files that register it. Mirror an existing scalarizer of the
 same kind:
 
-- `_<name>.py` — the class.
-- `__init__.py` — the import and an `__all__` entry.
-- `docs/source/docs/scalarization/<name>.rst` — the docs page, added to the `index.rst` toctree.
-- `tests/unit/scalarization/test_<name>.py` — the tests.
-- `CHANGELOG.md` — an entry under `[Unreleased]`.
+- `_<name>.py`: the class.
+- `__init__.py`: the import and an `__all__` entry.
+- `docs/source/docs/scalarization/<name>.rst`: the docs page, added to the `index.rst` toctree.
+- `tests/unit/scalarization/test_<name>.py`: the tests.
+- `CHANGELOG.md`: an entry under `[Unreleased]`.
 
 ## State
 
@@ -46,19 +58,15 @@ weights, a loss history). When it does:
 - **`nn.Parameter` vs buffer:** trainable state is an `nn.Parameter`; non-trained tensors that must
   move with `.to()` are registered with `register_buffer`.
 
-## What is not a scalarizer
-
-A scalarizer only ever sees the loss values.
-
-Anything that needs the model, its parameters, or the per-task gradients belongs in the
-[aggregation](../aggregation) package as a `Weighting` / `Aggregator`, which operates on the Jacobian
-or its Gramian. If you reach for gradient norms or the network inside `forward`, you are writing an
-aggregator, not a scalarizer.
+Randomness is not state: a scalarizer may draw fresh randomness on each call (like the random
+baseline) without being `Stateful`. There is no stochastic mixin; it just uses the global torch RNG,
+so document the behavior and let users seed it with `torch.manual_seed`.
 
 ## Things to be careful about
 
-- **Determinism and side effects:** the output should depend only on `values` and the configured
-  parameters. Any state change must be deliberate, explicit, and undone by `reset()`.
+- **Determinism and side effects:** the output should depend only on `values`, the configured
+  parameters, and (if the method is intentionally random) the global RNG. Any state change must be
+  deliberate, explicit, and undone by `reset()`.
 - **Numerical stability:** keep the reduction finite on the edges of its domain (log-sum-exp
   centering, an eps under a norm or in a denominator, etc.), and explain any value shift in a comment
   and a `.. note::`.