Skip to content

armgit / kokon

Public Imported from GitHub
0

Edit photos by describing the change, on your own GPU. A free, open-source alternative to Nano Banana and ChatGPT image editing: photos stay on your computer, no daily limit. One installer for Windows, Mac and Linux sets up the best open model (Qwen-Image 2.1). MCP server for AI agents.

11.0 KB
Raw Blame
import CoreVideo
import Metal
import QuartzCore
import XCTest
@testable import KokonEngine

/// The per-chip paths, checked for correctness on whatever Mac runs the tests: their speed needs the chip they are
/// for (`kokon-engine-mac bench`), their results do not.
final class PerChipTests: XCTestCase {
    /// `na_matmul` (the M5's neural accelerators; shader cores on older Metal 4 GPUs) against a product in double of
    /// the same fp16 operands, on shapes with several tiles along m and n and a K that is not a power of two: both
    /// tile variants (4 SIMD groups, and the M5 Pro's 2), forced on whatever chip runs the test.
    func testNeuralAcceleratorProduct() throws {
        let device = try XCTUnwrap(MTLCreateSystemDefaultDevice())
        guard NeuralAccelerators.make(device: device) != nil else {
            throw XCTSkip("Metal 4 tensor operations unavailable: \(NeuralAccelerators.unavailable ?? "?")")
        }
        let context = try MetalContext()
        let (m, k, n) = (192, 320, 128)
        var seed: UInt64 = 11
        func random() -> Float16 {
            seed = seed &* 6364136223846793005 &+ 1442695040888963407
            return Float16(Float(seed >> 40) / Float(1 << 24) - 0.5)
        }
        let a = (0..<(m * k)).map { _ in random() }, b = (0..<(k * n)).map { _ in random() }
        let ab = try context.scratch(a.count * 2, label: "A"), bb = try context.scratch(b.count * 2, label: "B")
        ab.contents().copyMemory(from: a, byteCount: a.count * 2)
        bb.contents().copyMemory(from: b, byteCount: b.count * 2)
        var exact = [Double](repeating: 0, count: m * n), scale = 0.0
        for i in 0..<m {
            for j in 0..<n {
                var s = 0.0
                for l in 0..<k { s += Double(a[i * k + l]) * Double(b[l * n + j]) }
                exact[i * n + j] = s
                scale = max(scale, abs(s))
            }
        }
        var results: [[Float]] = []
        for groups in [4, 2] {
            let na = try XCTUnwrap(NeuralAccelerators.make(device: device, simdgroups: groups))
            XCTAssertEqual(na.simdgroups, groups)
            let cb = try context.scratch(m * n * 4, label: "C")
            let commands = context.queue.makeCommandBuffer()!
            try na.encode(a: (ab, 0), b: (bb, 0), c: (cb, 0), m: m, n: n, k: k, commands: commands)
            try MetalContext.finish(commands, "na_matmul")
            let c = Array(UnsafeBufferPointer(start: cb.contents().assumingMemoryBound(to: Float.self), count: m * n))
            let worst = zip(c, exact).map { abs(Double($0) - $1) }.max() ?? 0
            XCTAssertLessThan(worst / scale, 1e-5, "\(groups) SIMD groups: fp16 products accumulated in fp32")
            results.append(c)
        }
        // On the M5 Pro and the M2 Pro the two were the same to the bit; elsewhere only the error above is required.
        if device.supportsFamily(.apple10) { XCTAssertEqual(results[0], results[1]) }
    }

    /// Which GPUs get 2 SIMD groups per tile: Apple10 (the M5's), unless the setting says otherwise.
    func testNeuralAcceleratorTileSelection() {
        XCTAssertEqual(NeuralAccelerators.simdgroups(gpuFamily: 10, setting: nil), 2)
        XCTAssertEqual(NeuralAccelerators.simdgroups(gpuFamily: 10, setting: "0"), 4)
        for family in [7, 8, 9] {   // M1–M4
            XCTAssertEqual(NeuralAccelerators.simdgroups(gpuFamily: family, setting: nil), 4, "Apple\(family)")
            XCTAssertEqual(NeuralAccelerators.simdgroups(gpuFamily: family, setting: "1"), 2, "Apple\(family)")
        }
    }

    /// Which GPUs take the attention on the neural accelerators: Apple10 with Metal 4 (the M5's), unless the setting
    /// says otherwise; never without Metal 4.
    func testNeuralAttentionSelection() {
        XCTAssertTrue(NeuralAttention.selected(gpuFamily: 10, metal4: true, setting: nil))
        XCTAssertFalse(NeuralAttention.selected(gpuFamily: 10, metal4: true, setting: "0"))
        for family in [7, 8, 9] {   // M1–M4
            XCTAssertFalse(NeuralAttention.selected(gpuFamily: family, metal4: true, setting: nil), "Apple\(family)")
            XCTAssertTrue(NeuralAttention.selected(gpuFamily: family, metal4: true, setting: "1"), "Apple\(family)")
        }
        XCTAssertFalse(NeuralAttention.selected(gpuFamily: 10, metal4: false, setting: "1"))
    }

    func testChipNames() {
        XCTAssertEqual(Chip.generation(of: "Apple M2 Pro"), 2)
        XCTAssertEqual(Chip.generation(of: "Apple M4 Max"), 4)
        XCTAssertEqual(Chip.generation(of: "Apple M10"), 10)
        XCTAssertNil(Chip.generation(of: "Intel(R) Core(TM) i9"))
        let here = Chip.current
        XCTAssertGreaterThan(here.performanceCores, 0)
        // A virtual Mac (GitHub's runners) has a paravirtual GPU that reports no Apple family.
        if MTLCreateSystemDefaultDevice()?.name.contains("Paravirtual") != true {
            XCTAssertGreaterThan(here.gpuFamily, 6)
        }
    }

    /// The first evaluation's shares from the cost model: on any chip they add up and keep each unit in its range.
    func testStartingShares() throws {
        let balancer = Balancer(aneAttention: false, chip: Chip.current)
        let rows = 4096
        let ane = try XCTUnwrap(balancer.bestAneRows(rows: rows, amx: true))
        XCTAssertTrue((1024...(rows - 512)).contains(ane) && ane % 256 == 0, "\(ane)")
        for kind in Balancer.evaluationCounts.keys {
            let amx = try XCTUnwrap(balancer.amxRows(kind: kind, rest: rows - ane))
            XCTAssertTrue(amx % 64 == 0 && amx >= 0 && amx < rows - ane, "\(kind): \(amx)")
        }
        let heads = balancer.bestHeads(ane: true, cpu: true)
        XCTAssertEqual(heads.gpu + heads.ane + heads.cpu, QwenDiT.heads)
        XCTAssertGreaterThan(heads.gpu, 0)
    }
}

extension PerChipTests {
    /// The int8 Neural Engine program (the M3/M4 path) against the exact product of its int8 operands, with K in one
    /// piece and cut in two (over 2 688).
    func testNeuralEngineInt8Product() throws {
        guard #available(macOS 26, *) else { throw XCTSkip("the int8 program needs macOS 26") }
        for (rows, k, n) in [(256, 512, 128), (256, 3072, 128)] {
            let p = try NeuralEngineProduct(rows: rows, k: k, n: n, int8: true)
            var seed = UInt64(k)
            func random() -> Int8 {
                seed = seed &* 6364136223846793005 &+ 1442695040888963407
                return Int8(Int(seed >> 56) - 128 == -128 ? 0 : Int(seed >> 56) - 128)
            }
            let x = (0..<(rows * k)).map { _ in random() }, w = (0..<(k * n)).map { _ in random() }
            for (surface, values) in [(p.x, x), (p.w, w)] {
                CVPixelBufferLockBaseAddress(surface, [])
                CVPixelBufferGetBaseAddress(surface)!.copyMemory(from: values, byteCount: values.count)
                CVPixelBufferUnlockBaseAddress(surface, [])
            }
            try p.run()
            var worst = 0.0
            p.read { y in
                for i in stride(from: 0, to: rows, by: 17) {
                    for j in 0..<n {
                        var s = 0
                        for l in 0..<k { s += Int(x[i * k + l]) * Int(w[l * n + j]) }
                        let want = Double(s) / Double(k)   // the program's 1/√K on each operand
                        worst = max(worst, abs(Double(y[i * n + j]) - want) / 16129)
                    }
                }
            }
            XCTAssertLessThan(worst, 2e-3, "\(rows)×\(k)×\(n): fp16 output of a sum bounded by 127²")
        }
    }
}

extension PerChipTests {
    /// The release made visible at once (`KOKON_FLUSH_READY`): chosen by measuring this Mac, once per process.
    func testFlushReleaseSelection() throws {
        guard ProcessInfo.processInfo.environment["KOKON_FLUSH_READY"] == nil else { throw XCTSkip("KOKON_FLUSH_READY is set") }
        let device = try XCTUnwrap(MTLCreateSystemDefaultDevice())
        if device.name.contains("Paravirtual") { throw XCTSkip("a virtual GPU's timing says nothing") }
        let context = try MetalContext()
        let start = CACurrentMediaTime()
        let late = Coexecutor.signalArrivesLate(context)
        let seconds = CACurrentMediaTime() - start
        print("\(Chip.current): signals arrive \(late ? "late (flush on)" : "on time (flush off)"), measured in \(Int(seconds * 1000)) ms")
        XCTAssertEqual(Coexecutor.flushReleaseSelected(context), late)
        XCTAssertLessThan(seconds, 0.5)
    }

    /// With the flush, the CPU sees the release while the GPU's work after it is still running, not at the command
    /// buffer's end (on the M5 Pro without it: at the end). Any Mac: the flush is a wait on a value already reached.
    func testFlushedReleaseReachesTheCPUBeforeTheEnd() throws {
        let device = try XCTUnwrap(MTLCreateSystemDefaultDevice())
        if device.name.contains("Paravirtual") { throw XCTSkip("a virtual GPU's timing says nothing") }
        let context = try MetalContext()
        let source = """
        #include <metal_stdlib>
        using namespace metal;
        kernel void spin(device float *o [[buffer(0)]], constant uint &n [[buffer(1)]], uint i [[thread_position_in_grid]]) {
            float x = float(i);
            for (uint k = 0; k < n; k++) { x = fma(x, 1.0000001f, 0.5f); }
            o[i] = x;
        }
        """
        let pipeline = try device.makeComputePipelineState(function: try XCTUnwrap(
            device.makeLibrary(source: source, options: nil).makeFunction(name: "spin")))
        let out = try context.scratch(4 << 20, label: "spin")
        func spin(_ commands: MTLCommandBuffer, _ n: UInt32) {
            var n = n
            let e = commands.makeComputeCommandEncoder()!
            e.setComputePipelineState(pipeline); e.setBuffer(out, offset: 0, index: 0); e.setBytes(&n, length: 4, index: 1)
            e.dispatchThreads(MTLSize(width: 1 << 20, height: 1, depth: 1), threadsPerThreadgroup: MTLSize(width: 256, height: 1, depth: 1))
            e.endEncoding()
        }
        // About 60 ms of GPU work on each side of the release.
        var n: UInt32 = 1000
        for _ in 0..<3 {
            let c = context.queue.makeCommandBuffer()!
            spin(c, n)
            try MetalContext.finish(c, "spin")
            n = UInt32(min(Double(1 << 24), Double(n) * 0.06 / max(c.gpuEndTime - c.gpuStartTime, 1e-4)))
        }
        let event = try XCTUnwrap(device.makeSharedEvent())
        let commands = context.queue.makeCommandBuffer()!
        // GPU work before the release too, as in the engine (a signal first in its command buffer is seen at once).
        spin(commands, n)
        Coexecutor.release(event, 1, flush: true, commands)
        spin(commands, n)
        nonisolated(unsafe) var seen = 0.0
        let watcher = Thread {
            _ = event.wait(untilSignaledValue: 1, timeoutMS: 10_000)
            seen = CACurrentMediaTime()
        }
        watcher.start()
        try MetalContext.finish(commands, "release")
        while seen == 0 { usleep(100) }
        XCTAssertLessThan(seen, commands.gpuEndTime - 0.02, "the release reached the CPU only at the command buffer's end")
    }
}