Standardize build output filenames with explicit bit widths

Add auto-generated filenames based on configuration:
- Format: neural_{alu|computer}{BITS}[_{MEMORY}].safetensors
- All bit widths (8/16/32) now explicit in filename
- Memory profiles: _reduced, _small, _scratchpad, _registers
- Custom addr-bits: _addrN suffix
- Enhanced CLI help with detailed argument descriptions
- Updated README with new naming scheme and examples

README.md

@@ -178,7 +178,7 @@ The weights in this repository implement a complete 8-bit computer: registers, A
 import torch
 from safetensors.torch import load_file
 
-tensors = load_file("neural_computer.safetensors")
+tensors = load_file("neural_computer8.safetensors")
 
 def heaviside(x):
     return (x >= 0).float()
@@ -705,18 +705,37 @@ This approach treats the problem as what it is: a structured parsing task where
 
 ## Build Tool
 
+Output filenames are auto-generated from configuration:
+
+```
+Format: neural_{alu|computer}{BITS}[_{MEMORY}].safetensors
+
+Examples:
+  neural_alu8.safetensors               # 8-bit, no memory
+  neural_alu32.safetensors              # 32-bit, no memory
+  neural_computer8.safetensors          # 8-bit, full memory (default)
+  neural_computer32.safetensors         # 32-bit, full memory
+  neural_computer8_small.safetensors    # 8-bit, 1KB memory
+  neural_computer32_small.safetensors   # 32-bit, 1KB memory
+  neural_computer8_addr12.safetensors   # 8-bit, custom 4KB (2^12 bytes)
+```
+
 ```bash
 # 8-bit CPU (default)
-python build.py --apply all                                # Full 64KB memory
-python build.py -m none --apply all                        # Pure ALU (32K params)
-python build.py -m scratchpad --apply all                  # 256-byte scratch
+python build.py --apply all                                # -> neural_computer8.safetensors
+python build.py -m none --apply all                        # -> neural_alu8.safetensors
+python build.py -m scratchpad --apply all                  # -> neural_computer8_scratchpad.safetensors
+
+# 16-bit ALU
+python build.py --bits 16 --apply all                      # -> neural_computer16.safetensors
+python build.py --bits 16 -m none --apply all              # -> neural_alu16.safetensors
 
 # 32-bit ALU
-python build.py --bits 32 -m small --apply all             # 1KB scratch (~203K params)
-python build.py --bits 32 -m none --apply all              # Pure 32-bit ALU
+python build.py --bits 32 -m small --apply all             # -> neural_computer32_small.safetensors
+python build.py --bits 32 -m none --apply all              # -> neural_alu32.safetensors
 
-# Custom configurations
-python build.py --bits 16 --addr-bits 6 --apply all        # 16-bit ALU, 64 bytes memory
+# Custom address width
+python build.py --bits 16 -a 6 --apply all                 # -> neural_computer16_addr6.safetensors
 ```
 
 **Bit widths** (`--bits`):
@@ -729,14 +748,16 @@ python build.py --bits 16 --addr-bits 6 --apply all        # 16-bit ALU, 64 byte
 
 **Memory profiles** (`-m`):
 
-| Profile | Size | Params | Use Case |
-|---------|------|--------|----------|
-| `none` | 0B | ~32K | Pure ALU |
-| `registers` | 16B | ~34K | Minimal state |
-| `scratchpad` | 256B | ~63K | 8-bit scratch |
-| `small` | 1KB | ~123K | 32-bit scratch |
-| `reduced` | 4KB | ~549K | Small programs |
-| `full` | 64KB | ~8.29M | Full CPU |
+| Profile | Size | Addr Bits | Filename Suffix | Params | Use Case |
+|---------|------|-----------|-----------------|--------|----------|
+| `none` | 0B | — | (uses `alu`) | ~32K | Pure ALU |
+| `registers` | 16B | 4 | `_registers` | ~34K | Minimal state |
+| `scratchpad` | 256B | 8 | `_scratchpad` | ~63K | 8-bit scratch |
+| `small` | 1KB | 10 | `_small` | ~123K | 32-bit scratch |
+| `reduced` | 4KB | 12 | `_reduced` | ~549K | Small programs |
+| `full` | 64KB | 16 | (none) | ~8.29M | Full CPU |
+
+**Custom address width** (`-a N`): Memory size = 2^N bytes, suffix = `_addrN`
 
 ---
 

build.py

@@ -112,7 +112,34 @@ from safetensors import safe_open
 from safetensors.torch import save_file
 
 
-MODEL_PATH = Path(__file__).resolve().parent / "neural_computer.safetensors"
+MODEL_DIR = Path(__file__).resolve().parent
+
+
+def get_model_path(bits: int = 8, memory_profile: str = None, addr_bits: int = None) -> Path:
+    """Generate model filename based on configuration."""
+    if addr_bits is not None:
+        if addr_bits == 0:
+            has_memory = False
+            mem_suffix = ""
+        else:
+            has_memory = True
+            mem_suffix = f"_addr{addr_bits}"
+    elif memory_profile == "none":
+        has_memory = False
+        mem_suffix = ""
+    elif memory_profile == "full" or memory_profile is None:
+        has_memory = True
+        mem_suffix = ""
+    else:
+        has_memory = True
+        mem_suffix = f"_{memory_profile}"
+
+    base = "neural_alu" if not has_memory else "neural_computer"
+
+    return MODEL_DIR / f"{base}{bits}{mem_suffix}.safetensors"
+
+
+MODEL_PATH = MODEL_DIR / "neural_computer8.safetensors"
 MANIFEST_PATH = Path(__file__).resolve().parent / "tensors.txt"
 
 DEFAULT_ADDR_BITS = 16
@@ -2288,46 +2315,99 @@ ALU Bit Widths:
   16          16-bit ALU (0-65535)
   32          32-bit ALU (0-4294967295)
 
-Examples:
-  python build.py memory --memory-profile none --apply    # LLM-only (no RAM)
-  python build.py memory --memory-profile small --apply   # 1KB for 32-bit scratch
-  python build.py alu --bits 32 --apply                   # 32-bit ALU circuits
-  python build.py all --bits 32 -m small --apply          # Full 32-bit build
+Output Filenames (auto-generated from config):
+  Format: neural_{alu|computer}{BITS}[_{MEMORY}].safetensors
+
+  Memory suffix:
+    -m full       -> (none)
+    -m reduced    -> _reduced
+    -m small      -> _small
+    -m scratchpad -> _scratchpad
+    -m registers  -> _registers
+    -m none       -> (uses "alu" instead of "computer")
+    -a N          -> _addrN
+
+  Examples:
+    neural_alu8.safetensors              # 8-bit, no memory
+    neural_alu16.safetensors             # 16-bit, no memory
+    neural_alu32.safetensors             # 32-bit, no memory
+    neural_computer8.safetensors         # 8-bit, full memory
+    neural_computer16.safetensors        # 16-bit, full memory
+    neural_computer32.safetensors        # 32-bit, full memory
+    neural_computer8_reduced.safetensors # 8-bit, reduced memory
+    neural_computer32_reduced.safetensors# 32-bit, reduced memory
+    neural_computer8_small.safetensors   # 8-bit, small memory
+    neural_computer32_small.safetensors  # 32-bit, small memory
+    neural_computer8_addr12.safetensors  # 8-bit, custom 12-bit address
+    neural_computer32_addr10.safetensors # 32-bit, custom 10-bit address
+
+Usage (note: options must come BEFORE subcommand):
+  python build.py --apply all                     # -> neural_computer8.safetensors
+  python build.py -m none --apply all             # -> neural_alu8.safetensors
+  python build.py -m reduced --apply all          # -> neural_computer8_reduced.safetensors
+  python build.py --bits 16 --apply all           # -> neural_computer16.safetensors
+  python build.py --bits 32 --apply all           # -> neural_computer32.safetensors
+  python build.py --bits 32 -m none --apply all   # -> neural_alu32.safetensors
+  python build.py --bits 32 -m small --apply all  # -> neural_computer32_small.safetensors
+  python build.py --bits 32 -a 10 --apply all     # -> neural_computer32_addr10.safetensors
 """
     )
-    parser.add_argument("--model", type=Path, default=MODEL_PATH, help="Model path")
-    parser.add_argument("--apply", action="store_true", help="Apply changes (default: dry-run)")
-    parser.add_argument("--manifest", action="store_true", help="Write tensors.txt manifest (memory only)")
+    parser.add_argument(
+        "--model", type=Path, default=None,
+        help="Output path. Auto-generated as neural_{alu|computer}{BITS}[_{MEMORY}].safetensors if not specified"
+    )
+    parser.add_argument(
+        "--apply", action="store_true",
+        help="Apply changes to model file. Without this flag, runs in dry-run mode (no writes)"
+    )
+    parser.add_argument(
+        "--manifest", action="store_true",
+        help="Write tensors.txt manifest listing all tensors (memory command only)"
+    )
     parser.add_argument(
         "--bits", "-b",
         type=int,
         choices=SUPPORTED_BITS,
         default=8,
-        help="ALU bit width: 8 (default), 16, or 32"
+        help="ALU bit width. 8=0-255 (default), 16=0-65535, 32=0-4294967295"
     )
 
     mem_group = parser.add_mutually_exclusive_group()
     mem_group.add_argument(
         "--memory-profile", "-m",
         choices=list(MEMORY_PROFILES.keys()),
-        help="Memory size profile (full/reduced/small/scratchpad/registers/none)"
+        help="""Memory profile:
+  full=64KB/16-bit addr (suffix: none),
+  reduced=4KB/12-bit (suffix: _reduced),
+  small=1KB/10-bit (suffix: _small),
+  scratchpad=256B/8-bit (suffix: _scratchpad),
+  registers=16B/4-bit (suffix: _registers),
+  none=0B/pure ALU (uses 'alu' in filename)"""
     )
     mem_group.add_argument(
         "--addr-bits", "-a",
         type=int,
         choices=range(0, 17),
         metavar="N",
-        help="Address bus width in bits (0-16). 0=no memory, 16=64KB"
+        help="Custom address bus width 0-16. Memory size=2^N bytes. 0=pure ALU. Suffix: _addrN"
     )
 
     subparsers = parser.add_subparsers(dest="command", help="Subcommands")
-    subparsers.add_parser("memory", help="Generate memory circuits (size controlled by --memory-profile or --addr-bits)")
-    subparsers.add_parser("alu", help="Generate ALU extension circuits (use --bits for 16/32-bit)")
-    subparsers.add_parser("inputs", help="Add .inputs metadata tensors")
-    subparsers.add_parser("all", help="Run memory, alu, then inputs")
+    subparsers.add_parser("memory", help="Generate memory circuits (decoder, read mux, write cells)")
+    subparsers.add_parser("alu", help="Generate N-bit ALU circuits (adder, sub, mul, div, cmp, bitwise, shift)")
+    subparsers.add_parser("inputs", help="Add .inputs metadata tensors for gate routing")
+    subparsers.add_parser("all", help="Run all: memory -> alu -> inputs")
 
     args = parser.parse_args()
 
+    if args.model is None:
+        args.model = get_model_path(
+            bits=args.bits,
+            memory_profile=getattr(args, 'memory_profile', None),
+            addr_bits=getattr(args, 'addr_bits', None)
+        )
+        print(f"Auto-generated model path: {args.model}")
+
     if args.command == "memory":
         cmd_memory(args)
     elif args.command == "alu":