Skip to content

docs+test: document custom losses/config, add loss test coverage - #454

Merged
Demirrr merged 1 commit into
developfrom
docs/custom-losses-and-config
Sep 16, 2026
Merged

Demirrr merged 1 commit into
developfrom
docs/custom-losses-and-config

Conversation

@Demirrr

@Demirrr Demirrr commented Sep 16, 2026

Copy link
Copy Markdown
Member

Summary

Fixes #444, #445.

  • Adds Google-style docstrings to every class in dicee/losses/custom_losses.py (algorithm/paper reference where identifiable, hyperparameter meaning, known caveats — e.g. LabelSmoothingLoss's current no-op bug, LabelSmoothingLoss (loss_fn="LS") doesn't apply label smoothing — identical to plain BCE #453), plus a module docstring explaining the loss_fn dispatch and current_epoch convention.
  • Documents loss_fn, label_smoothing_rate, label_relaxation_alpha, adversarial_temperature, grouped_negative_sampling, strict_negative_sampling inline in config.py and in CLAUDE.md's config table.
  • Adds tests/test_unit_custom_losses.py (36 tests, Zero unit test coverage for dicee/losses/custom_losses.py #445): finite-output/gradient-flow checks for every loss class, edge cases (batch size 1, all-positive/all-negative targets, boundary hyperparameters), and correctness checks against independently-computed expected values where the math is verifiable.

Bug found and fixed while writing edge-case tests: CombinedAdaptiveLSandAdaptiveLR.forward called AdaptiveLabelRelaxationLoss(pred, target, current_epoch) — that class's forward only accepts (pred, target) — so loss_fn="CombinedAdaptiveLSandAdaptiveLR" crashed with TypeError as soon as current_epoch reached 100 (the smoothing→relaxation switch point). The manual smoke test in #442/#450 only trained for a few epochs and never reached the switch, so this went unnoticed at the time. Fixed and verified with a 105-epoch end-to-end run.

Also filed #453 for LabelSmoothingLoss not actually applying smoothing (found while writing its docstring) — TestLabelSmoothingLoss in the new test file documents this current behavior explicitly so a future fix is forced to update the tests rather than silently changing semantics.

Test plan

  • ruff check dicee/ --line-length=200 — clean
  • mypy dicee/ --config-file=pyproject.toml — stable (1349, no ratchet risk)
  • tests/test_unit_custom_losses.py (36 new tests) — all pass
  • Ran tests/test_unit_custom_losses.py, test_unit_base_model.py, test_neg_sample_margin.py, test_regression_distmult.py, test_custom_trainer.py — 112 passed
  • Manual end-to-end: loss_fn="CombinedAdaptiveLSandAdaptiveLR" trains DistMult on UMLS for 105 epochs (crossing the epoch-100 switch) successfully

#445)

Adds Google-style docstrings to every class in dicee/losses/custom_losses.py
(algorithm/paper reference where identifiable, hyperparameter meaning,
known caveats), a module docstring explaining the loss_fn dispatch and
current_epoch convention, and documents loss_fn/label_smoothing_rate/
label_relaxation_alpha/adversarial_temperature/grouped_negative_sampling/
strict_negative_sampling inline in config.py and in CLAUDE.md's config
table.

Fixes #444, #445.

Also fixes a bug found while writing edge-case tests:
CombinedAdaptiveLSandAdaptiveLR.forward called
AdaptiveLabelRelaxationLoss(pred, target, current_epoch) - that class's
forward only accepts (pred, target) - so loss_fn=
"CombinedAdaptiveLSandAdaptiveLR" crashed with TypeError as soon as
current_epoch reached 100 (the smoothing->relaxation switch point). Earlier
manual smoke testing (#442) only trained for a few epochs and never
reached the switch, so this went unnoticed. Verified fixed with a
105-epoch end-to-end run.

Adds tests/test_unit_custom_losses.py (36 tests): finite-output and
gradient-flow checks for every loss class, edge cases (batch size 1,
all-positive/all-negative targets, boundary hyperparameters), and
correctness checks against independently-computed expected values where
the math is verifiable (LabelRelaxationLoss's zero-loss-when-confident
property, the Adaptive* classes' bidirectional hyperparameter adjustment,
CombinedLSandLR/CombinedAdaptiveLSandAdaptiveLR's epoch-based switching,
AggregatedLSandLR's weighted-average formula, ACLS's margin penalty).
TestLabelSmoothingLoss explicitly documents the class's current no-op
behavior (tracked in #453) so a future fix is forced to update these
tests rather than silently changing semantics.

Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>
@Demirrr
Demirrr merged commit 2d09c80 into develop Sep 16, 2026
7 checks passed
@Demirrr
Demirrr deleted the docs/custom-losses-and-config branch September 16, 2026 07:53
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

dicee/losses/custom_losses.py has no docstrings and no documented config options

1 participant