transforms
ptwm_core::transforms::delta
XorDelta and FloatDelta ops — cross-tensor residual encoding.
ptwm_core::transforms::delta
XorDelta and FloatDelta ops — cross-tensor residual encoding.
ptwm_core::transforms::delta
crates/ptwm-core/src/transforms/delta.rs:1mod delta`XorDelta` and `FloatDelta` ops — cross-tensor residual encoding.
## Cross-tensor op asymmetry
Both ops consume two inputs (current plane + reference plane) on `forward`
and two inputs (residual + reference plane) on `inverse`. The `Op` trait
was designed for single-tensor chains; cross-tensor ops bend this by
accepting the reference as the second element in the slice on both sides:
- `forward(&[current, reference])` → `[residual]`
- `inverse(&[residual, reference])` → `[original]`
The runtime is responsible for supplying the reference as `inputs[1]` /
`outputs[1]` respectively. This is documented here so chain authors know
the convention.
## XorDelta
Byte-level XOR residual. Because XOR is involutive, `forward` and `inverse`
are the same operation: `residual[i] = a[i] ^ b[i]`. Round-trip is
guaranteed byte-exact for all inputs.
## FloatDelta (DONE_WITH_CONCERNS)
Element-wise float subtract (`output = current - reference`). Currently
only `f32` is supported. The round-trip `inverse(forward(a, b), b)` computes
`(a - b) + b`, which IEEE 754 does NOT guarantee to equal `a` bit-exactly
when `a - b` introduces a rounding error.
**This op is marked DONE_WITH_CONCERNS**: it violates the PPG byte-exact
round-trip invariant for arbitrary f32 inputs where `|a - b|` causes
sub-normal rounding. It exists for opportunistic delta encoding where near-
identical tensors make the residual very small and coding gain outweighs the
approximation. A future version may use integer delta on the raw bit patterns
(which is lossless) instead.
ptwm_core::transforms::delta::DTYPE_CODE_F32
crates/ptwm-core/src/transforms/delta.rs:215pub const DTYPE_CODE_F32dtype_code for f32 (matches `Dtype::Float32.code()` = 1 in the crate's dtype registry).
ptwm_core::transforms::delta::FloatDelta
crates/ptwm-core/src/transforms/delta.rs:207pub struct FloatDeltaElement-wise float subtract residual against a reference tensor plane.
**DONE_WITH_CONCERNS**: IEEE 754 does not guarantee that `(a - b) + b == a`
bit-exactly for all inputs. This op may violate the PPG byte-exact round-
trip invariant. Use `XorDelta` instead when lossless is required.
Currently only `dtype_code` corresponding to `f32` is supported.
**Input convention** (both forward and inverse):
- `inputs[0]` / `outputs[0]`: the plane being encoded or the residual.
- `inputs[1]` / `outputs[1]`: the reference plane.
ptwm_core::transforms::delta::XorDelta
crates/ptwm-core/src/transforms/delta.rs:57pub struct XorDeltaByte-level XOR residual against a reference tensor plane.
`dep_idx` identifies which dependency tensor supplies the reference.
**Input convention** (both forward and inverse):
- `inputs[0]` / `outputs[0]`: the plane being encoded or the residual.
- `inputs[1]` / `outputs[1]`: the reference plane (same shape).
Both are consumed; one residual plane is produced.