KratosStudyRun.kt

    private fun explore(session: KratosSession, options: Options) {
        val study = KratosStudyDemo.study(session, options.target)
        val arms = listOf(KratosStudyDemo.ARM.start, KratosStudyDemo.ARM.endInclusive)
        val ks = listOf(KratosStudyDemo.CONDUCTIVITY.start, KratosStudyDemo.CONDUCTIVITY.endInclusive)
        val probes = ArrayList<Double>()
        for (arm in arms) for (k in ks) {
            val sample = study.evaluate(doubleArrayOf(arm, k))
            val probe = sample.metrics["probe"] ?: Double.NaN
            probes += probe
            println("corner arm=%.3f k=%.3f  probe=%.4f K  peak=%.4f K  %.0f ms"
                .format(arm, k, probe, sample.metrics["peak"] ?: Double.NaN, sample.solveMs))
        }
        val finite = probes.filter { it.isFinite() }
        if (finite.isNotEmpty()) {
            println("achievable probe temperature %.3f .. %.3f K".format(finite.min(), finite.max()))
            println("a target in the interior would be about %.1f K"
                .format((finite.min() + finite.max()) / 2))
        }
        println("mean solve %.0f ms over ${study.solveCount} solves".format(study.meanSolveMs))
        println("Kratos study explore done")
    }

    private fun sweep(session: KratosSession, options: Options) {
        var index = 0
        val study = KratosStudyDemo.study(session, options.target) { sample ->
            index++
            if (index % 10 == 0 || !sample.feasible) println("  [$index] $sample")
        }
        // ------------------------------------------------------------------------------------
        // Stage 1: a coarse grid, then a refinement seeded from it.
        //
        // This is the comparison the whole exercise is for, and it is run FIRST so that neither the
        // coarse grid nor the refinement can see an answer the fine grid already found. The claim
        // being tested is that a study does not have to tile finely to answer finely.
        // ------------------------------------------------------------------------------------
        val coarse = if (options.coarse <= 0) null else {
            println("COARSE GRID ${options.coarse}x${options.coarse}")
            study.grid(options.coarse, options.coarse).also { println("  ${it.summary()}") }
        }
        val coarseSolves = study.solveCount

        // mu = 1 on purpose: a (1+lambda) climb spends every evaluation near the seed. A larger mu
        // would fill its initial population with uniform draws from the whole space, which is the
        // opposite of what "refine around this point" means.
        val refinement = if (options.refine <= 0 || coarse?.best == null) null else {
            println()
            println("REFINEMENT ${options.refine} evaluations seeded at the coarse grid's best")
            study.optimise(options.refine, seed = 11L, mu = 1, lambda = 4, sigma = 0.03,
                control = false, start = coarse.best!!.coordinates, immigrantRate = 0.0)
                .also { println("  ${it.run.summary()}"); println("  best: ${it.best}") }
        }
        val refineSolves = study.solveCount

        // ------------------------------------------------------------------------------------
        // Stage 2: a search with no prior information at all, and its random control.
        // ------------------------------------------------------------------------------------
        val optimisation = if (options.budget <= 0) null else {
            println()
            println("GLOBAL SEARCH ${options.budget} evaluations, against a random control")
            study.optimise(options.budget, seed = 7L).also {
                println("  ${it.run.summary()}")
                it.control?.let { c -> println("  ${c.summary()}") }
                println("  advantage over the control: %+.6g (positive means the search won)"
                    .format(it.advantage ?: Double.NaN))
            }
        }
        val searchSolves = study.solveCount

        // ------------------------------------------------------------------------------------
        // Stage 3: the fine grid — the reference answer, and the landscape the figure draws.
        // ------------------------------------------------------------------------------------
        println()
        val startedGrid = System.nanoTime()
        val landscape = study.grid(options.rows, options.cols)
        val gridSeconds = (System.nanoTime() - startedGrid) / 1e9
        println("FINE GRID ${landscape.summary()}")
        println("  wall %.1f s · %d solves so far · mean %.0f ms".format(
            gridSeconds, study.solveCount, study.meanSolveMs))
        check(session.domain.buildCount == 1) { "the background grid was rebuilt during the sweep" }
        println("NO_REMESH background=${session.domain.id} buildCount=${session.domain.buildCount} " +
            "over ${study.solveCount} solves")

        println()
        println("CLOSED FORM CHECK — the valley against k* = q phi / (T - Tb)")
        val checks = KratosStudyDemo.verifyValley(landscape, options.target)
        checks.forEach { println("  $it") }

        val solvesBeforeReplay = study.solveCount
        val hitsBeforeReplay = study.cacheHits
        val replay = study.grid(options.rows, options.cols)
        check(study.solveCount == solvesBeforeReplay) { "a repeated grid re-solved something" }
        println("CACHE re-running the same grid cost ${study.solveCount - solvesBeforeReplay} " +
            "new solves and ${study.cacheHits - hitsBeforeReplay} hits; " +
            "best unchanged at ${replay.best?.objective}")

        // The table the whole run exists to print: what each method reached, and what it cost.
        //
        // Budgeted in **evaluations**, because that is what the methods were given and what makes
        // them comparable; distinct solves are reported once at the bottom, and differ only by the
        // cache hits (the refinement's seed, for one, was already solved by the coarse grid).
        println()
        println("METHOD COMPARISON — objective (lower is better) against evaluations spent")
        fun row(label: String, value: Double?, evaluations: Int) =
            println("  %-30s %12s  %4d evaluations".format(
                label, value?.let { "%.6g".format(it) } ?: "-", evaluations))
        val coarseCells = options.coarse * options.coarse
        coarse?.let { row("coarse ${options.coarse}x${options.coarse} grid", it.best?.objective, coarseCells) }
        refinement?.let { row("  + refinement", it.best?.objective, coarseCells + options.refine) }
        optimisation?.let {
            row("global search, no prior", it.best?.objective, options.budget)
            it.control?.let { c ->
                row("random control, same budget", it.trace(c).lastOrNull(), options.budget)
            }
        }
        row("fine ${options.rows}x${options.cols} grid", landscape.best?.objective, options.rows * options.cols)
        println("  coarse+refine spent $refineSolves distinct solves of the " +
            "${coarseCells + options.refine} evaluations it was given; the two search arms together " +
            "spent ${searchSolves - refineSolves}")
        println("  ${study.solveCount} distinct designs solved in all, ${study.cacheHits} served from cache")

        // Stretched, and captioned as such: the miss spans 5 K over the whole space but under 1 K
        // along the short-arm edge, and a linear ramp renders that edge as one flat shade with the
        // valley invisible inside it.
        val scale = ColourScale.STRETCHED
        val extra = listOfNotNull(refinement?.let {
            StudyTrace("refine", it.trace(it.run), REFINE_COLOUR)
        })
        val sheet = KratosStudyFigure.sheet(landscape, optimisation, scale = scale, extra = extra)
        val landscapeOnly = KratosStudyFigure.landscape(
            landscape, refinement ?: optimisation, scale = scale)
        write(options.out.resolve("kratos-study-sheet.png"), sheet)
        write(options.out.resolve("kratos-study-landscape.png"), landscapeOnly)
        optimisation?.let {
            write(options.out.resolve("kratos-study-convergence.png"),
                KratosStudyFigure.convergence(it, landscape.best?.objective, extra = extra))
        }

        // The winner, as geometry and as a field, which is the other half of what a study owes:
        // not only "this design is best" but "here is the design, and here is what it does".
        landscape.best?.let { winner ->
            val design = study.designAt(winner.coordinates)
            println()
            println("BEST $design  ${landscape.objectiveName}=%.6g  probe=%.4f K  peak=%.4f K".format(
                winner.objective, winner.metrics["probe"], winner.metrics["peak"]))
            val result = study.resultAt(winner.coordinates)
            val slice = result.sliceMesh(samples = 96)
            println("best slice: ${slice.vertexCount} vertices, ${slice.indices.size / 3} triangles; " +
                "temperature ${"%.3f".format(result.range("temperature").first)}-" +
                "${"%.3f".format(result.range("temperature").second)} K")
            val skin = KratosDemo.body(design.armEnd).surface()
            println("best geometry: ${skin.vertexCount} vertices, ${skin.indices.size / 3} triangles")
        }
        println()
        println("total solver time %.1f s over ${study.solveCount} solves (${study.cacheHits} cache hits)"
            .format(study.solveMs / 1000.0))
        println("Kratos study sweep done")
    }

    private fun write(path: Path, bytes: ByteArray) {
        Files.write(path, bytes)
        println("wrote $path (${bytes.size} bytes)")
    }

    private class Options(args: Array<String>) {
        var out: Path = Path.of("build/kratos-studies").toAbsolutePath()
        var rows = 11
        var cols = 11
        var budget = 40
        var coarse = 5
        var refine = 30
        var target = KratosStudyDemo.TARGET
        var explore = false

        init {
            var i = 0
            while (i < args.size) {
                when (args[i]) {
                    "--out" -> { out = Path.of(args[++i]).toAbsolutePath() }
                    "--grid" -> { rows = args[++i].toInt(); cols = args[++i].toInt() }
                    "--budget" -> { budget = args[++i].toInt() }
                    "--refine" -> { refine = args[++i].toInt() }
                    "--coarse" -> { coarse = args[++i].toInt() }
                    "--target" -> { target = args[++i].toDouble() }
                    "--explore" -> explore = true
                    else -> error("unknown argument ${args[i]}")
                }
                i++
            }
        }
    }
}

    @JvmStatic fun main(args: Array<String>) {
        val found = Kratos.probeAny().get(600, TimeUnit.SECONDS)
        println("launch=${found.config.resolvedLaunch()}")
        if (!found.available) {
            println("Kratos study smoke passed (SKIPPED: optional environment absent)")
            return
        }
        val budget = if (found.config.resolvedLaunch() is KratosLaunch.Container) 600L else 60L
        // Never a committed path: a FIELD_TEST that writes into the tree is a dirty working copy.
        val out = Files.createTempDirectory("field-kratos-study-")
        KratosSession.openAsync(KratosStudyDemo.BOUNDS, KratosStudyDemo.RESOLUTION, found.config)
            .get(budget, TimeUnit.SECONDS).use { session ->
                val study = KratosStudyDemo.study(session)
                val landscape = study.grid(3, 3)
                println("GRID ${landscape.summary()}")
                check(landscape.feasible.size == 9) { "every corner of this space should be feasible" }
                check(session.domain.buildCount == 1) { "the sweep rebuilt the background grid" }

                val solved = study.solveCount
                study.grid(3, 3)
                check(study.solveCount == solved) { "a repeated grid re-solved ${study.solveCount - solved}" }
                check(study.cacheHits == 9) { "expected 9 cache hits, got ${study.cacheHits}" }

                // Physics, not plumbing: at a fixed geometry, a higher conductivity is a colder probe.
                val cold = landscape.at(1, 2).metrics.getValue("probe")
                val hot = landscape.at(1, 0).metrics.getValue("probe")
                check(hot > cold + 1e-6) { "raising conductivity must lower the probe: $hot vs $cold" }

                val optimisation = study.optimise(6, seed = 3L, mu = 2, lambda = 3, control = false)
                println(optimisation.summary())
                check(optimisation.best != null) { "the search found nothing" }

                val raster = KratosStudyFigure.sheetRaster(landscape, optimisation)
                val distinct = raster.pixels.toHashSet().size
                check(distinct > 12) { "the figure has only $distinct distinct colours; it is blank" }
                val png = out.resolve("smoke.png")
                Files.write(png, raster.png())
                check(Files.size(png) > 4096) { "the figure is suspiciously small" }
                println("figure $distinct distinct colours, ${Files.size(png)} bytes at $png")
                println("solves ${study.solveCount} · hits ${study.cacheHits} · " +
                    "mean %.0f ms".format(study.meanSolveMs))
                println("Kratos study smoke passed")
            }
    }
}