Text Objective API

The task, code-to-code and radial terms preserve live-radius gradients. The two cross-entropy terms have independent learned positive logit scales.

Req 11's three terms and their learned logit scales (spec 4.1).

The task term, the code-code term and the radial term; LogitScale holds each of the two listwise terms' scale. Nothing else remains of the six-term objective (spec 4.5).

LogitScale

Bases: Module

A learned logit scale (spec 4.1): s = exp(θ), starting at init and clamped to [low, high].

Its one parameter is θ, log_scale, so s is always positive. The clamp acts on θ in the forward pass: s never leaves the range, and θ takes no gradient while it lies outside it.

Parameters:

Name Type Description Default
init float

s at the start, inside the range.

 required
low float

The least scale, positive.

 required
high float

The greatest scale, above low.

 required

Raises:

Type Description
ValueError

If a value is not finite, the range does not satisfy 0 < low < high, or init lies outside it.

forward()

The scale: exp(θ), with θ clamped to [log low, log high].

Returns:

Type Description
Tensor

A 0-d tensor in the parameter's dtype.

code_code_loss(distances, scale, structural, keep, target_temperature)

The code–code listwise term (spec 4.1(ii)): the mean over the step's anchors of CE(p_a, softmax over J_a of −s_c · d(a, j)), with the target p_a = softmax over J_a of −D*_{aj} / τ_t.

J_a is every code but the anchor and, for a unary pair, its partner, so a unary pair is neither a positive nor a negative (Req 9). A code outside J_a carries no probability on either side: its D* never reaches the target, its d never reaches the model's softmax, and it takes no gradient. The term reads no exclusion data, so no exclusion pair can act as a code–code negative (Req 8(c)).

Parameters:

Name Type Description Default
distances Tensor

d(a, j) from every anchor to every code, (A, N), finite everywhere, off J_a too.

 required
scale Tensor

s_c, the code–code term's logit scale, a 0-d tensor.

 required
structural Tensor

D*_{aj}, the tree metric from every anchor to every code, (A, N).

 required
keep Tensor

J_a, bool (A, N).

 required
target_temperature float

τ_t, the temperature of the target's softmax.

 required

Returns:

Type Description
Tensor

The term, a 0-d tensor in the distances' dtype.

Raises:

Type Description
ValueError

If the step has no anchor, the shapes or the mask are malformed, an anchor keeps no code, or target_temperature is not a positive finite number.

radial_loss(radius, levels, radial_step)

The radial term (spec 4.1(iii)): the mean over the step's anchors of (r_a − ρ · (λ(a) − 1))².

The virtual root sits at the origin, the sectors (level 2) at r = ρ and the six-digit codes at r = 5ρ. r is the geodesic distance from the origin, the text stage's one radial coordinate (spec 4.2).

Parameters:

Name Type Description Default
radius Tensor

r_a, the anchors' radii, (A,).

 required
levels Tensor

λ(a), the anchors' code levels, (A,).

 required
radial_step float

ρ, the radius from one level to the next.

 required

Returns:

Type Description
Tensor

The term, a 0-d tensor in the radii's dtype.

Raises:

Type Description
ValueError

If the radii and levels are not non-empty and aligned (A,), or radial_step is not a positive finite number.

task_loss(distances, scale, candidates, targets)

The task term (spec 4.1(i)): the mean over the step's queries of −log Σ_{t ∈ T} softmax_C(−s_q · d(q, c))_t.

The probability is summed over the query's targets T, so a query with two targets pays nothing for how it splits the probability between them. The softmax runs over exactly the candidates C: a code outside them carries no probability and takes no gradient. Spec 4.1 builds C from the codes at the query's level and the query's forced negatives N, so a cross-reference query always scores its referencing code (Req 8(b)).

Parameters:

Name Type Description Default
distances Tensor

d(q, c) from every query to every code, (Q, N), finite everywhere, outside C too.

 required
scale Tensor

s_q, the task term's logit scale, a 0-d tensor.

 required
candidates Tensor

C, bool (Q, N).

 required
targets Tensor

T, bool (Q, N): for each query, a non-empty subset of its candidates.

 required

Returns:

Type Description
Tensor

The term, a 0-d tensor in the distances' dtype.

Raises:

Type Description
ValueError

If the step has no query, the shapes or masks are malformed, a query has no target, or a target is not one of its query's candidates.