Add reverse Ref2VA-to-FL2VA experimental LoRAs

Add rank 256, 512, and 1024 exact sign-inverted reverse-direction LoRAs, per-layer reports, inversion utility, updated checksums, NOTICE, and bidirectional usage documentation.

NOTICE

@@ -1,5 +1,4 @@
 MiniMax H3 is licensed under the MiniMax H3 Community License Agreement, Copyright © 2026 MiniMax. All Rights Reserved.
 
 Modification notice:
-These experimental files were produced by mechanically extracting randomized-SVD approximations of the difference between the pruned BF16 FL2VA and Ref2VA MiniMax-H3 checkpoints. They are modified model-derivative files, not official MiniMax or Comfy Org releases.
-
+These experimental files were produced by mechanically extracting randomized-SVD approximations of the difference between the pruned BF16 FL2VA and Ref2VA MiniMax-H3 checkpoints, plus exact sign-inverted opposite-direction forms. They are modified model-derivative files, not official MiniMax or Comfy Org releases.

README.md

@@ -14,22 +14,28 @@ tags:
   - experimental
 ---
 
-# MiniMax-H3 pruned FL2VA → Ref2VA delta LoRAs
+# MiniMax-H3 pruned FL2VA ↔ Ref2VA delta LoRAs
 
 > [!WARNING]
 > **Highly experimental, mechanically extracted adapters.** These are randomized-SVD approximations of the weight difference between the official pruned BF16 Ref2VA and FL2VA checkpoints. They were not trained as LoRAs and have not been generation-tested. Only safetensors integrity and structural loading with ComfyUI's current LoRA parser were validated. Expect artifacts, capability loss, or unpredictable behavior.
 
-These model-only ComfyUI LoRAs explore whether some Ref2VA behavior can be transferred to the pruned FL2VA model by approximating:
+These model-only ComfyUI LoRAs explore transferring behavior in either direction between the pruned FL2VA and Ref2VA models. The forward files approximate:
 
 ```text
 delta = pruned Ref2VA BF16 - pruned FL2VA BF16
 ```
 
-At strength `1.0`, applying an adapter to the matching pruned FL2VA BF16 checkpoint moves the model toward a rank-limited approximation of pruned Ref2VA. Lower strengths interpolate only in the extracted weight direction; they do not isolate a clean semantic capability.
+The reverse files are exact sign-inverted forms of those approximations:
 
-## Required base
+```text
+reverse delta = pruned FL2VA BF16 - pruned Ref2VA BF16
+```
+
+At strength `1.0`, applying an adapter to its matching base moves the model toward a rank-limited approximation of the other variant. Lower strengths interpolate only in the extracted weight direction; they do not isolate a clean semantic capability.
 
-Use only:
+## Required checkpoints and directions
+
+For files named `ref2va_from_fl2va`, use this base:
 
 ```text
 Comfy-Org/MiniMax-H3
@@ -42,7 +48,7 @@ Base SHA-256:
 a32572fb90b5508b201ec7c2eddcc184b13ddfd3c6f6d2cf06a0b46535d541b4
 ```
 
-The adapters were extracted against this target:
+For files named `fl2va_from_ref2va`, use this base:
 
 ```text
 diffusion_models/minimax_h3_ref2va_pruned_bf16.safetensors
@@ -53,11 +59,14 @@ Do not expect correct results with the full-size BF16, FP8, or INT8 checkpoints.
 
 ## Files
 
-| File | Size | Weighted matrix-delta energy capture |
-|---|---:|---:|
-| `minimax_h3_ref2va_from_fl2va_pruned_rank256_bf16_lora.safetensors` | 2.589 GB | 99.1260% |
-| `minimax_h3_ref2va_from_fl2va_pruned_rank512_bf16_lora.safetensors` | 5.075 GB | 99.2417% |
-| `minimax_h3_ref2va_from_fl2va_pruned_rank1024_bf16_lora.safetensors` | 10.048 GB | 99.4311% |
+| Direction | File | Size | Weighted matrix-delta energy capture |
+|---|---|---:|---:|
+| FL2VA → Ref2VA | `minimax_h3_ref2va_from_fl2va_pruned_rank256_bf16_lora.safetensors` | 2.589 GB | 99.1260% |
+| FL2VA → Ref2VA | `minimax_h3_ref2va_from_fl2va_pruned_rank512_bf16_lora.safetensors` | 5.075 GB | 99.2417% |
+| FL2VA → Ref2VA | `minimax_h3_ref2va_from_fl2va_pruned_rank1024_bf16_lora.safetensors` | 10.048 GB | 99.4311% |
+| Ref2VA → FL2VA | `minimax_h3_fl2va_from_ref2va_pruned_rank256_bf16_lora.safetensors` | 2.589 GB | 99.1260% |
+| Ref2VA → FL2VA | `minimax_h3_fl2va_from_ref2va_pruned_rank512_bf16_lora.safetensors` | 5.075 GB | 99.2417% |
+| Ref2VA → FL2VA | `minimax_h3_fl2va_from_ref2va_pruned_rank1024_bf16_lora.safetensors` | 10.048 GB | 99.4311% |
 
 The weighted percentage is dominated by high-energy tensors whose effective rank is naturally small. Many large attention and MLP deltas retain substantially less energy, so this statistic is **not** a quality score. Compare generations with identical prompts, inputs, seeds, and sampler settings.
 
@@ -66,12 +75,12 @@ Each `.safetensors.json` file contains the complete per-layer extraction report.
 ## ComfyUI use
 
 1. Put one `.safetensors` file in `ComfyUI/models/loras/`.
-2. Load `minimax_h3_fl2va_pruned_bf16.safetensors` as the diffusion model.
+2. Load pruned FL2VA for a `ref2va_from_fl2va` file, or pruned Ref2VA for a `fl2va_from_ref2va` file.
 3. Apply the adapter with a model-only LoRA loader.
 4. Start at model strength `1.0`; compare `0.25`, `0.5`, `0.75`, and `1.0` using identical inputs.
-5. Do not stack the three ranks together. They are alternative approximations of the same delta.
+5. Do not stack ranks or opposing directions together. They are alternative forms of the same underlying delta.
 
-All three files loaded as 531 expected ComfyUI patches: 264 matrix adapters and 267 exact vector/bias diff patches. `rope.inv_freq` was identical between the source checkpoints and was omitted.
+All six files loaded as 531 expected ComfyUI patches each: 264 matrix adapters and 267 exact vector/bias diff patches. `rope.inv_freq` was identical between the source checkpoints and was omitted.
 
 ## Extraction details
 
@@ -83,8 +92,9 @@ All three files loaded as 531 expected ComfyUI patches: 264 matrix adapters and
 - Vector and bias patches: FP32 ComfyUI `.diff` / `.diff_b`
 - Source tensors: 532 matching tensors
 - Peak extractor CUDA allocation: approximately 1.24 GB
+- Reverse-direction construction: exact sign inversion of one LoRA factor and every `.diff` / `.diff_b` tensor
 
-The included `extract_minimax_h3_ref2va_lora.py` performs checkpointed, one-tensor-at-a-time extraction. It avoids loading both 40 GB checkpoints into memory simultaneously.
+The included `extract_minimax_h3_ref2va_lora.py` performs checkpointed, one-tensor-at-a-time extraction. It avoids loading both 40 GB checkpoints into memory simultaneously. `invert_comfy_lora_direction.py` creates the opposite direction without repeating or degrading the SVD.
 
 ## License and territorial restrictions
 
@@ -99,4 +109,3 @@ This repository does not grant additional rights or remove any upstream restrict
 - Generation-tested: **no**
 - Structurally parsed by ComfyUI: **yes**
 - Affiliated with or endorsed by MiniMax or Comfy Org: **no**
-

SHA256SUMS

@@ -1,3 +1,6 @@
 f8f15be3728fe52159b2dd840f6c8d7057f99b93690ba5bb129d827757cf13f4  minimax_h3_ref2va_from_fl2va_pruned_rank256_bf16_lora.safetensors
 f7e7fac7e5d29622705f92e1a1cd359db0c54c3364344fdecfc82d8d32b7d512  minimax_h3_ref2va_from_fl2va_pruned_rank512_bf16_lora.safetensors
 b97515fd5e654a3b37c4f499404f73340cb46e93bb626a575cd8626fd889fad0  minimax_h3_ref2va_from_fl2va_pruned_rank1024_bf16_lora.safetensors
+cd4001221599e88f1fa06b2e0cddbc69d61e14765f9b0a994369663f9fc86167  minimax_h3_fl2va_from_ref2va_pruned_rank256_bf16_lora.safetensors
+b7cad943cea4fee3d4614c092f78b370fd3d9cc876f7a5c6f6d254c1aed8b122  minimax_h3_fl2va_from_ref2va_pruned_rank512_bf16_lora.safetensors
+8c90b63df76e1819870c8b6809b08eb2bf8cf80348e59e3117d69e322a481d68  minimax_h3_fl2va_from_ref2va_pruned_rank1024_bf16_lora.safetensors

invert_comfy_lora_direction.py

@@ -0,0 +1,176 @@
+#!/usr/bin/env python3
+"""Create the exact opposite direction of an extracted ComfyUI LoRA.
+
+For a normal LoRA patch, negating either the up or down factor negates the
+represented matrix delta. ComfyUI ``.diff`` and ``.diff_b`` tensors are
+negated directly. Alpha and the other LoRA factor remain unchanged.
+
+The conversion streams one tensor at a time and writes resumable safetensors
+parts, so even very large LoRAs require little memory.
+"""
+
+from __future__ import annotations
+
+import argparse
+import hashlib
+import json
+import os
+import shutil
+from pathlib import Path
+from typing import Any
+
+import torch
+from safetensors import safe_open
+from safetensors.torch import save_file
+
+from extract_minimax_h3_ref2va_lora import merge_parts, write_json_atomic
+
+
+def parse_args() -> argparse.Namespace:
+    parser = argparse.ArgumentParser(
+        description="Invert an extracted ComfyUI LoRA without recomputing its SVD."
+    )
+    parser.add_argument("--input", type=Path, required=True)
+    parser.add_argument("--output", type=Path, required=True)
+    parser.add_argument("--keep-parts", action="store_true")
+    parser.add_argument("--quiet", action="store_true")
+    return parser.parse_args()
+
+
+def should_negate(key: str) -> bool:
+    return (
+        key.endswith(".lora_up.weight")
+        or key.endswith(".diff")
+        or key.endswith(".diff_b")
+    )
+
+
+def part_path(parts_dir: Path, index: int, key: str) -> Path:
+    digest = hashlib.sha1(key.encode("utf-8")).hexdigest()[:12]
+    return parts_dir / f"{index:04d}-{digest}.safetensors"
+
+
+def reverse_metadata(metadata: dict[str, str], input_path: Path) -> dict[str, str]:
+    output = dict(metadata)
+    source_base = output.get("source_base")
+    source_target = output.get("source_target")
+    if source_base is not None and source_target is not None:
+        output["source_base"] = source_target
+        output["source_target"] = source_base
+    output["modelspec.title"] = "MiniMax-H3 REF2VA to FL2VA extracted LoRA"
+    output["modelspec.description"] = (
+        "Opposite-direction form of an extracted FL2VA-to-REF2VA LoRA; "
+        "one factor and all exact ComfyUI diff patches are sign-inverted."
+    )
+    output["direction"] = "ref2va_to_fl2va"
+    output["inverted_from"] = input_path.name
+    return output
+
+
+def reverse_report(input_path: Path, output_path: Path, summary: dict[str, Any]) -> None:
+    input_report = input_path.with_suffix(input_path.suffix + ".json")
+    output_report = output_path.with_suffix(output_path.suffix + ".json")
+    if input_report.is_file():
+        report = json.loads(input_report.read_text())
+        report_summary = report.setdefault("summary", {})
+        report_summary.update(summary)
+        write_json_atomic(output_report, report)
+    else:
+        write_json_atomic(output_report, {"summary": summary})
+
+
+def run(args: argparse.Namespace) -> None:
+    if not args.input.is_file():
+        raise FileNotFoundError(args.input)
+    if args.output.exists():
+        raise FileExistsError(f"Refusing to overwrite {args.output}")
+
+    parts_dir = Path(f"{args.output}.parts")
+    parts_dir.mkdir(parents=True, exist_ok=True)
+    progress_path = parts_dir / "progress.json"
+    progress: dict[str, Any] = {
+        "input": str(args.input.resolve()),
+        "completed": {},
+    }
+    if progress_path.exists():
+        progress = json.loads(progress_path.read_text())
+        if progress.get("input") != str(args.input.resolve()):
+            raise ValueError("Existing parts belong to a different input file")
+    completed: dict[str, Any] = progress.setdefault("completed", {})
+
+    with safe_open(args.input, framework="pt", device="cpu") as source:
+        keys = list(source.keys())
+        metadata = source.metadata() or {}
+        negated_count = 0
+        copied_count = 0
+
+        for index, key in enumerate(keys):
+            output_part = part_path(parts_dir, index, key)
+            negate = should_negate(key)
+            previous = completed.get(key)
+            if previous is not None and output_part.is_file():
+                if previous["negated"]:
+                    negated_count += 1
+                else:
+                    copied_count += 1
+                if not args.quiet:
+                    print(f"[{index + 1:04d}/{len(keys)}] resume {key}", flush=True)
+                continue
+
+            tensor = source.get_tensor(key)
+            output_tensor = (-tensor).contiguous() if negate else tensor.contiguous()
+            temporary = output_part.with_name(f".{output_part.name}.tmp")
+            temporary.unlink(missing_ok=True)
+            save_file({key: output_tensor}, str(temporary))
+            os.replace(temporary, output_part)
+            completed[key] = {
+                "negated": negate,
+                "shape": list(tensor.shape),
+                "dtype": str(tensor.dtype),
+                "part": output_part.name,
+            }
+            write_json_atomic(progress_path, progress)
+            if negate:
+                negated_count += 1
+                action = "negate"
+            else:
+                copied_count += 1
+                action = "copy"
+            if not args.quiet:
+                print(f"[{index + 1:04d}/{len(keys)}] {action} {key}", flush=True)
+
+    parts = sorted(parts_dir.glob("[0-9][0-9][0-9][0-9]-*.safetensors"))
+    output_metadata = reverse_metadata(metadata, args.input)
+    tensor_count = merge_parts(parts, args.output, output_metadata)
+    if tensor_count != len(keys):
+        raise ValueError(f"Final tensor count mismatch: {tensor_count} != {len(keys)}")
+
+    with safe_open(args.output, framework="pt", device="cpu") as final:
+        if list(final.keys()) != keys:
+            raise ValueError("Final key order/content differs from the input")
+
+    summary = {
+        "direction": "ref2va_to_fl2va",
+        "inverted_from": args.input.name,
+        "output_file": args.output.name,
+        "output_tensors": tensor_count,
+        "negated_tensors": negated_count,
+        "copied_tensors": copied_count,
+        "output_bytes": args.output.stat().st_size,
+    }
+    reverse_report(args.input, args.output, summary)
+    print(json.dumps(summary, indent=2), flush=True)
+
+    if not args.keep_parts:
+        for part in parts:
+            part.unlink()
+        progress_path.unlink(missing_ok=True)
+        shutil.rmtree(parts_dir)
+
+
+def main() -> None:
+    run(parse_args())
+
+
+if __name__ == "__main__":
+    main()

minimax_h3_fl2va_from_ref2va_pruned_rank1024_bf16_lora.safetensors

@@ -0,0 +1,3 @@
+version https://git-lfs.github.com/spec/v1
+oid sha256:8c90b63df76e1819870c8b6809b08eb2bf8cf80348e59e3117d69e322a481d68
+size 10047563968

minimax_h3_fl2va_from_ref2va_pruned_rank1024_bf16_lora.safetensors.json

@@ -0,0 +1,3 @@
+version https://git-lfs.github.com/spec/v1
+oid sha256:97009c54e939ff7576cf1c65ede03421eb6035c079d471899543847dc0d127c1
+size 216945

minimax_h3_fl2va_from_ref2va_pruned_rank256_bf16_lora.safetensors

@@ -0,0 +1,3 @@
+version https://git-lfs.github.com/spec/v1
+oid sha256:cd4001221599e88f1fa06b2e0cddbc69d61e14765f9b0a994369663f9fc86167
+size 2588648560

minimax_h3_fl2va_from_ref2va_pruned_rank256_bf16_lora.safetensors.json

@@ -0,0 +1,3 @@
+version https://git-lfs.github.com/spec/v1
+oid sha256:f9cc0dccd043471612a5db6f333027e38666ae6b1d57ef07a9ca838c5f3ab6ed
+size 217055

minimax_h3_fl2va_from_ref2va_pruned_rank512_bf16_lora.safetensors

@@ -0,0 +1,3 @@
+version https://git-lfs.github.com/spec/v1
+oid sha256:b7cad943cea4fee3d4614c092f78b370fd3d9cc876f7a5c6f6d254c1aed8b122
+size 5074953760

minimax_h3_fl2va_from_ref2va_pruned_rank512_bf16_lora.safetensors.json

@@ -0,0 +1,3 @@
+version https://git-lfs.github.com/spec/v1
+oid sha256:05f96c313abfa9e301844dc3ead2b2b7b635c32775d775f366ba27dcf95630ea
+size 216928