implement-method

Implement new method

This skill implements a new method by recovering its research, comparing the paper against the existing implementations, settling the non-standard parts of its interface, and producing the full set of TorchJD files (class, docs, tests, changelog) that match the established conventions.

It is the companion of the research-method skill: that one investigates a method and records a row in a tracking issue; this one turns that row into a merged implementation.

For agents: invoke as /implement-method method-name (paper-name) (e.g. /implement-method stch (Smooth Tchebycheff Scalarization for Multi-objective Optimization)). If no method name is provided, ask the user for the name of the method and the title of the paper.

For humans: follow the numbered steps below to guide your development.

Instructions

Step 1: Recover the research context

Determine whether the method should be a scalarizer or an aggregator, then read everything the research-method skill already found about it:

• Scalarizers are tracked in https://github.com/SimplexLab/TorchJD/issues/667, aggregators in https://github.com/SimplexLab/TorchJD/issues/665. Fetch the relevant issue and find the row for this method. Read every column:
  • Ref — the paper (open it; you will need the exact equations / algorithm).
  • Stateful — whether and how the method holds state.
  • Existing implementations — links to the official repo (if any) and the best-known third-party ones (LibMTL, libmoon, pymoo, ...), ideally with the exact file(s) and line(s).
  • Special Remarks — may link to a full research write-up (e.g. a claude.ai share produced by research-method). Read it if present.
• The most valuable inputs are the non-standard interface aspects uncovered during research: statefulness, trainable parameters, randomness, warm-up / history buffers, statistics beyond the forward values (e.g. per-task losses for an aggregator), and preconditions. If these are not fully captured in the issue, ask the user to share the research-method findings before continuing. Do not guess them.

If the method is not in the tracking issue yet, run research-method first.

Step 2: Load the implementation reference for this method type

Read only the reference matching the method type, to keep context focused:

• Scalarizer → read references/scalarizers.md.
• Aggregator → read references/aggregators.md.

Each reference lists the exact files to create/edit and the TorchJD-specific conventions, with the closest existing methods to mirror.

Step 3: Compare the paper with the existing implementations

Always do this — it is the step we invariably end up needing. Read the relevant equations / the algorithm box in the paper, then read the official and best-known third-party implementations at the exact files/lines from the tracking row.

Reconcile any discrepancies between them. The ones that most often bite:

• Minimization vs maximization. TorchJD minimizes losses; much MOO/evolutionary work is written for maximization, with the minimization form buried in a footnote. Find it, and check the sign of every reference / ideal-point subtraction.
• Normalization. A direction or weight vector may be normalized (w / ‖w‖) in the code but not the paper, or vice versa.
• Dead arguments. An impl may accept a parameter (e.g. a reference point) yet silently ignore it.
• Droppable terms. An abs / clamp / max(0, ·) in the paper may be unnecessary under the method's preconditions (e.g. non-negative weights); drop it only with a justification.
• Other: an extra factor, an init value, a stabilization / epsilon trick.

Decide which to follow, note why, and surface the disagreement to the user — the implementation should be faithful to a clearly-stated source, not an unexplained blend.

Step 4: Settle the interface and design decisions

Using the research findings (Step 1) and the comparison (Step 3), map each non-standard aspect onto the closest existing pattern from the reference loaded in Step 2 (statefulness, trainable parameters, an internal optimizer, a preference/reference vector, ...). Then settle, for any method type:

• Preconditions (e.g. positivity): enforce them (raise ValueError) or only document them, and how nan/inf should propagate.
• Which constructor arguments are required vs optional, and their defaults.

List the non-standard parts and your proposed handling, and confirm the design with the user before writing code. This is where most of the maintainer review happens, so settle it up front.

Step 5: Implement the method

Follow the file-by-file checklist in the reference loaded at Step 2. Match the style, naming, and conventions of the closest existing method. If you adapt code from a third-party repository, add the license header to the source file and an entry to NOTICES (see the reference).

Step 6: Verify

Run the checks listed in the reference (unit tests with -W error, lint, and the docs build/doctest). GPU tests require a CUDA device; if you cannot run them, provide the exact commands for the user to run on their GPU and report back the results.

Step 7: Self-review the code you produced

Before opening anything, re-read your own diff against the requirements and improve what can be improved. Check that:

• The class follows the closest existing method's conventions (the reference's checklist): correct base class(es), forward(self, values, /) returning a 0-dim scalar, shape validation, reset() for stateful methods, a correct __repr__, and the docstring conventions (r""" only with LaTeX, :class: cross-ref, .. math:: + bullet list, a usage doctest, :param: for each argument).
• The design decisions settled in Step 4 are actually reflected in the code, and any discrepancy between the paper and the existing implementations (Step 3) is resolved deliberately, with a comment or docstring note where it is non-obvious.
• The tests cover the documented edge cases and contracts, not just the happy path.
• All six files are present and consistent (class, __init__.py, .rst, toctree, test, CHANGELOG.md), plus NOTICES + a license header if you adapted code.

Apply the fixes you find, then re-run the relevant checks from Step 6.

Step 8: Open a draft PR

Create a new branch, commit, and open a draft pull request targeting main, following the repository's PR conventions (a CHANGELOG.md entry under [Unreleased] > ### Added; when asked for a PR description, output raw GitHub-flavored markdown in a fenced code block, with GitHub math syntax $...$ / $$...$$ and no em dashes). Keep it a draft so the contributor can read the code themselves before requesting maintainer review. Return the PR URL when done.