diff --git a/.github/workflows/dotnet-quality.yml b/.github/workflows/dotnet-quality.yml
index db1a880..06076f0 100644
--- a/.github/workflows/dotnet-quality.yml
+++ b/.github/workflows/dotnet-quality.yml
@@ -19,17 +19,28 @@ jobs:
with:
global-json-file: global.json
- - name: Restore
- run: dotnet restore src/Sapling.sln
+ - name: Restore test projects
+ run: |
+ dotnet restore src/Sapling.Engine.Tests/Sapling.Engine.Tests.csproj
+ dotnet restore src/Sapling.WebHost.Tests/Sapling.WebHost.Tests.csproj
- - name: Test with coverage
+ - name: Test engine and UCI with coverage
run: >-
- dotnet test src/Sapling.sln
+ dotnet test src/Sapling.Engine.Tests/Sapling.Engine.Tests.csproj
--no-restore
--configuration Release
--collect:"XPlat Code Coverage"
--settings .github/coverlet.runsettings
- --results-directory artifacts/TestResults
+ --results-directory artifacts/TestResults/engine
+
+ - name: Test web host with coverage
+ run: >-
+ dotnet test src/Sapling.WebHost.Tests/Sapling.WebHost.Tests.csproj
+ --no-restore
+ --configuration Release
+ --collect:"XPlat Code Coverage"
+ --settings .github/coverlet.runsettings
+ --results-directory artifacts/TestResults/webhost
- name: Upload Cobertura coverage reports
if: always()
diff --git a/.github/workflows/release-pipeline.yaml b/.github/workflows/release-pipeline.yaml
index 258c6c5..39999b6 100644
--- a/.github/workflows/release-pipeline.yaml
+++ b/.github/workflows/release-pipeline.yaml
@@ -15,18 +15,27 @@ jobs:
- name: Checkout code
uses: actions/checkout@v4
+ - name: Require the default branch for releases
+ env:
+ DEFAULT_BRANCH: ${{ github.event.repository.default_branch }}
+ run: |
+ if [[ "$GITHUB_REF" != "refs/heads/$DEFAULT_BRANCH" ]]; then
+ echo "Release workflow must be dispatched from the default branch ($DEFAULT_BRANCH)." >&2
+ exit 1
+ fi
+
- name: Setup .NET Core
uses: actions/setup-dotnet@v4
with:
global-json-file: global.json
- # Get the version from the .csproj file
+ # Read the release version from shared Directory.Build.props via MSBuild.
- name: Get .NET application version
working-directory: src/Sapling
id: get_version
run: |
VERSION=$(dotnet msbuild Sapling.csproj -getProperty:Version)
- # Assembly-style 2.0.0.0 maps to the release tag Sapling-2.0.0.
+ # The three-part application version maps directly to the release tag.
if [[ "$VERSION" =~ ^([0-9]+\.[0-9]+\.[0-9]+)\.0$ ]]; then
VERSION="${BASH_REMATCH[1]}"
fi
diff --git a/README.md b/README.md
index a354eb6..9ac4e76 100644
--- a/README.md
+++ b/README.md
@@ -4,7 +4,7 @@
-### Sapling v2.0.0 — a .NET UCI chess engine
+### Sapling v2.1.0 — a .NET UCI chess engine
Play it here -> https://timmoth.com/sapling/play/
diff --git a/Scripts/test_web_worker.mjs b/Scripts/test_web_worker.mjs
index e9869e3..b22183f 100644
--- a/Scripts/test_web_worker.mjs
+++ b/Scripts/test_web_worker.mjs
@@ -84,6 +84,24 @@ assert.equal(hintsDone.hintId, 12);
const hintUpdates = backlog.filter((message) => message.type === 'hint-progress' && message.hintId === 12);
assert.ok(hintUpdates.some((message) => message.scores.some((score) => score.move === 'e2e4')));
assert.ok(hintUpdates.some((message) => message.scores.some((score) => score.move === 'd2d4')));
+for (const update of hintUpdates) {
+ for (const score of update.scores) {
+ assert.ok(Number.isFinite(score.lossCp) && score.lossCp >= 0, 'hint supplies global move-quality loss');
+ }
+}
+
+
+const mateHintTask = self.onmessage({ data: {
+ type: 'hints', hintId: 13, fen: '7k/5Q2/6K1/8/8/8/8/8 w - - 0 1',
+ moves: ['f7g7'], history: [],
+} });
+await waitFor('hints-done', (message) => message.hintId === 13);
+await mateHintTask;
+const mateHint = backlog.filter((message) => message.type === 'hint-progress' && message.hintId === 13)
+ .flatMap((message) => message.scores).find((score) => score.move === 'f7g7');
+assert.equal(mateHint.scoreType, 'mate');
+assert.equal(mateHint.score, 0, 'a move delivering checkmate retains the resulting-position M0 distance');
+assert.equal(mateHint.lossCp, 0);
const interruptedSearch = self.onmessage({ data: {
type: 'search', requestId: 20, maxDepth: 120, sliceNodes: 12_000,
diff --git a/src/Directory.Build.props b/src/Directory.Build.props
index 35f19a1..49eaed3 100644
--- a/src/Directory.Build.props
+++ b/src/Directory.Build.props
@@ -1,10 +1,10 @@
- 2.0.0
+ 2.1.0
$(Version)
- 2.0.0.0
- 2.0.0.0
+ 2.1.0
+ 2.1.0
diff --git a/src/README.md b/src/README.md
index 94c4d63..fa66120 100644
--- a/src/README.md
+++ b/src/README.md
@@ -1,4 +1,4 @@
-### Sapling v2.0.0 — a .NET UCI chess engine
+### Sapling v2.1.0 — a .NET UCI chess engine
Play it here -> https://iblunder.com/
@@ -7,9 +7,9 @@ Or challenge it on Lichess -> https://lichess.org/@/sapling-bot
## Releases
You can browse all windows, linux or mac releases [here](https://github.com/Timmoth/Sapling/releases)
-## v2.0.0
+## v2.1.0
-The planned release tag is `Sapling-2.0.0`. Version metadata is shared in [`Directory.Build.props`](Directory.Build.props); see the [release workflow](../.github/workflows/release-pipeline.yaml).
+The planned release tag is `Sapling-2.1.0`. Version metadata is shared in [`Directory.Build.props`](Directory.Build.props); see the [release workflow](../.github/workflows/release-pipeline.yaml).
## Requirements
- Use an executable matching your OS and architecture. The normal build selects AVX2, Vector128 or scalar NNUE at runtime and uses magic bitboards when BMI2/PEXT is unavailable. Dedicated AVX512 builds select that backend when supported; explicitly forcing `SAPLING_BACKEND=Avx512` requires AVX512F and AVX512BW.
diff --git a/src/Sapling.Engine.Tests/AllocationHelperTests.cs b/src/Sapling.Engine.Tests/AllocationHelperTests.cs
index 920bf38..5877912 100644
--- a/src/Sapling.Engine.Tests/AllocationHelperTests.cs
+++ b/src/Sapling.Engine.Tests/AllocationHelperTests.cs
@@ -94,11 +94,12 @@ public void CalculateTranspositionTableSize_AbsurdSizes_Throw()
[Fact]
public void CalculateSizeInMb_RoundTripsKnownSizes()
{
- foreach (var mb in new[] { 64L, 256, 1024 })
+ foreach (var mb in new[] { 16L, 32, 64, 256, 1024 })
{
var count = TranspositionTableExtensions.CalculateTranspositionTableSize(mb);
var inverted = TranspositionTableExtensions.CalculateSizeInMb((uint)count);
Assert.Equal(count, TranspositionTableExtensions.CalculateTranspositionTableSize(inverted));
+ Assert.Equal(mb, inverted);
}
}
diff --git a/src/Sapling.Engine.Tests/HumanPlayTests.cs b/src/Sapling.Engine.Tests/HumanPlayTests.cs
index 1f729fd..a12d3b4 100644
--- a/src/Sapling.Engine.Tests/HumanPlayTests.cs
+++ b/src/Sapling.Engine.Tests/HumanPlayTests.cs
@@ -14,6 +14,7 @@ public void EmbeddedPolicy_MatchesPyTorchGoldenMoveDistributions()
using var fixture = JsonDocument.Parse(File.ReadAllText(
Path.Combine(AppContext.BaseDirectory, "human_policy_inference_golden.json")));
Assert.Equal(1, fixture.RootElement.GetProperty("schema_version").GetInt32());
+ Assert.Equal(fixture.RootElement.GetProperty("model_sha256").GetString(), HumanMovePolicy.ModelSha256);
foreach (var testCase in fixture.RootElement.GetProperty("cases").EnumerateArray())
{
@@ -47,6 +48,59 @@ public void EmbeddedPolicy_MatchesPyTorchGoldenMoveDistributions()
}
}
+ [Fact]
+ public void EmbeddedPolicy_MultiRatingScoringMatchesSingleRatingScoring()
+ {
+ using var state = GameState.InitialState();
+ var board = state.Board;
+ var boardFeatures = HumanPolicyEncoding.EncodeBoard(ref board);
+ var legalMoves = new List();
+ board.GenerateLegalMoves(legalMoves, captureOnly: false);
+ var moveFeatures = new float[legalMoves.Count * HumanPolicyEncoding.MoveFeatures];
+ var ratings = new[] { 500, 800, 1500, 2200 };
+ var multiRatingLogits = HumanMovePolicy.ScoreCandidatesForRatings(
+ boardFeatures, moveFeatures, legalMoves.Count, ratings);
+
+ Assert.Equal(ratings.Length, multiRatingLogits.Length);
+ for (var i = 0; i < ratings.Length; i++)
+ Assert.Equal(HumanMovePolicy.ScoreCandidates(boardFeatures, moveFeatures,
+ legalMoves.Count, ratings[i]), multiRatingLogits[i]);
+ Assert.Throws(() => HumanMovePolicy.ScoreCandidatesForRatings(
+ boardFeatures, moveFeatures, legalMoves.Count, Array.Empty()));
+ Assert.Throws(() => HumanMovePolicy.ScoreCandidatesForRatings(
+ boardFeatures, moveFeatures, legalMoves.Count, new[] { 499 }));
+ }
+
+ [Fact]
+ public void HumanPlayCalibration_AppliesStaticDepthEightHumanDataCalibration()
+ {
+ Assert.True(HumanPlayCalibration.AppliesToCurrentModel);
+ Assert.Equal(new HumanPlaySettings(500, 1f, .5f), HumanPlayCalibration.ForDisplayElo(500));
+ Assert.Equal(new HumanPlaySettings(875, 1f, .6875f), HumanPlayCalibration.ForDisplayElo(800));
+ Assert.Equal(new HumanPlaySettings(1000, 1f, .75f), HumanPlayCalibration.ForDisplayElo(900));
+ Assert.Equal(new HumanPlaySettings(1088, 1f, .75f), HumanPlayCalibration.ForDisplayElo(1000));
+ Assert.Equal(new HumanPlaySettings(1500, 1f, .625f), HumanPlayCalibration.ForDisplayElo(1500));
+ Assert.Equal(new HumanPlaySettings(1700, 1f, .375f), HumanPlayCalibration.ForDisplayElo(1700));
+ Assert.Equal(new HumanPlaySettings(1750, 1.0125f, .5625f), HumanPlayCalibration.ForDisplayElo(1800));
+ Assert.Equal(new HumanPlaySettings(2050, 1.05f, .75f), HumanPlayCalibration.ForDisplayElo(2200));
+ Assert.Equal(new HumanPlaySettings(0, 1f, 0f), HumanPlayCalibration.ForDisplayElo(0));
+ }
+
+ [Theory]
+ [InlineData("6rk/8/8/8/8/8/4R3/K7 w - - 0 1", "e2g2", true)]
+ [InlineData("6rk/8/8/8/8/8/4R3/5K2 w - - 0 1", "e2g2", false)]
+ public void DirectCaptureRisk_RequiresLegalCaptureWithoutImmediateRecapture(string fen, string uci, bool expected)
+ {
+ var board = BoardStateExtensions.CreateBoardFromFen(fen);
+ var originalHash = board.Hash;
+ var legalMoves = new List();
+ board.GenerateLegalMoves(legalMoves, captureOnly: false);
+ var move = Assert.Single(legalMoves, candidate => candidate.ToUciMoveName() == uci);
+
+ Assert.Equal(expected, DirectCaptureRisk.IsRiskAfterMove(ref board, move));
+ Assert.Equal(originalHash, board.Hash);
+ }
+
[Fact]
public void DisabledHumanPlay_LeavesEngineBestMoveSelected()
{
@@ -60,6 +114,24 @@ public void DisabledHumanPlay_LeavesEngineBestMoveSelected()
Assert.Equal(1f, probability);
}
+ [Fact]
+ public void SelectMove_PreservesThePolicyChoiceWhenItIsRankZero()
+ {
+ HumanPlay.Reset();
+ HumanPlay.SetElo(1500);
+ using var state = GameState.InitialState();
+ using var searcher = new ParallelSearcher(1024);
+ var ranked = searcher.RankRootMoves(state, 2);
+ var board = state.Board;
+
+ var selection = HumanPlay.SelectMove(new ZeroRandom(), ref board, ranked);
+
+ Assert.Equal(0, selection.Rank);
+ Assert.Equal(ranked[0].Move, selection.Move);
+ Assert.True(selection.Probability > 0f);
+ HumanPlay.Reset();
+ }
+
[Fact]
public void EmbeddedPolicySampler_AlwaysSelectsARankedLegalMove()
{
@@ -124,6 +196,63 @@ public void EmbeddedPolicy_UsesRatingConditioning()
.Sum(pair => Math.Abs(pair.First - pair.Second)) > 1e-6f);
}
+ [Fact]
+ public void PolicyProbabilities_TemperatureChangesEntropyAndStayNormalized()
+ {
+ var logits = new float[] { 2f, 1f, -1f };
+ var cool = HumanMovePolicy.Probabilities(logits, 0.5f);
+ var baseLine = HumanMovePolicy.Probabilities(logits);
+ var warm = HumanMovePolicy.Probabilities(logits, 2f);
+
+ Assert.InRange(cool.Sum(), 0.99999f, 1.00001f);
+ Assert.InRange(baseLine.Sum(), 0.99999f, 1.00001f);
+ Assert.InRange(warm.Sum(), 0.99999f, 1.00001f);
+ Assert.True(cool[0] > baseLine[0]);
+ Assert.True(baseLine[0] > warm[0]);
+ }
+
+ [Fact]
+ public void PolicySampler_SoftPenaltyReducesMarkedCandidateProbability()
+ {
+ var board = BoardStateExtensions.CreateBoardFromFen(Constants.InitialState);
+ var boardFeatures = HumanPolicyEncoding.EncodeBoard(ref board);
+ var moves = new List();
+ board.GenerateLegalMoves(moves, captureOnly: false);
+ var moveFeatures = new float[moves.Count * HumanPolicyEncoding.MoveFeatures];
+ var penaltyMask = new bool[moves.Count];
+ penaltyMask[0] = true;
+
+ var baselineIndex = HumanMovePolicy.Sample(new ZeroRandom(), boardFeatures, moveFeatures,
+ moves.Count, 1500, 1f, out var baselineProbability);
+ var penalizedIndex = HumanMovePolicy.Sample(new ZeroRandom(), boardFeatures, moveFeatures,
+ moves.Count, 1500, 1f, out var penalizedProbability, penaltyMask, 1f);
+
+ Assert.Equal(0, baselineIndex);
+ Assert.Equal(0, penalizedIndex);
+ Assert.True(penalizedProbability < baselineProbability);
+ }
+
+ [Theory]
+ [InlineData(0f)]
+ [InlineData(-1f)]
+ [InlineData(float.NaN)]
+ [InlineData(float.PositiveInfinity)]
+ public void PolicyProbabilities_RejectInvalidTemperature(float temperature)
+ {
+ Assert.Throws(() => HumanMovePolicy.Probabilities(new float[] { 1f, 0f }, temperature));
+ }
+
+ [Fact]
+ public void HumanPlay_ResetRestoresDefaultTemperature()
+ {
+ HumanPlay.SetTemperature(1.75f);
+ Assert.Equal(1.75f, HumanPlay.Temperature);
+
+ HumanPlay.Reset();
+
+ Assert.Equal(1f, HumanPlay.Temperature);
+ }
+
[Fact]
public void EmbeddedPolicySampler_IsSeededAndReturnsSelectedSoftmaxProbability()
{
@@ -146,6 +275,13 @@ public void EmbeddedPolicySampler_IsSeededAndReturnsSelectedSoftmaxProbability()
Assert.Equal(repeated, selected);
Assert.Equal(repeatedProbability, probability, 1e-7f);
Assert.Equal(expectedProbabilities[selected], probability, 1e-6f);
+
+ const float temperature = 1.6f;
+ var temperatureProbabilities = HumanMovePolicy.Probabilities(
+ HumanMovePolicy.ScoreCandidates(boardFeatures, moveFeatures, legalMoves.Count, 1500), temperature);
+ var temperatureSelected = HumanMovePolicy.Sample(new Random(8128), boardFeatures, moveFeatures,
+ legalMoves.Count, 1500, temperature, out var temperatureProbability);
+ Assert.Equal(temperatureProbabilities[temperatureSelected], temperatureProbability, 1e-6f);
}
[Fact]
@@ -156,7 +292,7 @@ public void EmbeddedPolicy_RejectsMalformedTensorShapesAndOutOfRangeRatings()
var shortBoard = () => HumanMovePolicy.ScoreCandidates(board.AsSpan(1), moves, 1, 1500);
var wrongMoveCount = () => HumanMovePolicy.ScoreCandidates(board, moves, 2, 1500);
- var invalidRating = () => HumanMovePolicy.ScoreCandidates(board, moves, 1, 799);
+ var invalidRating = () => HumanMovePolicy.ScoreCandidates(board, moves, 1, 499);
Assert.Throws(shortBoard);
Assert.Throws(wrongMoveCount);
@@ -166,8 +302,8 @@ public void EmbeddedPolicy_RejectsMalformedTensorShapesAndOutOfRangeRatings()
[Theory]
[InlineData(-100, 0)]
[InlineData(0, 0)]
- [InlineData(1, 800)]
- [InlineData(300, 800)]
+ [InlineData(1, 500)]
+ [InlineData(300, 500)]
[InlineData(1500, 1500)]
[InlineData(3000, 2200)]
public void HumanElo_MapsToTheTrainedPolicyRange(int requested, int expected)
@@ -203,4 +339,9 @@ private static float[] Softmax(float[] logits)
var sum = values.Sum();
return values.Select(value => (float)(value / sum)).ToArray();
}
+
+ private sealed class ZeroRandom : Random
+ {
+ public override double NextDouble() => 0d;
+ }
}
diff --git a/src/Sapling.Engine.Tests/HumanPolicyEncodingTests.cs b/src/Sapling.Engine.Tests/HumanPolicyEncodingTests.cs
index 023d746..b7e4947 100644
--- a/src/Sapling.Engine.Tests/HumanPolicyEncodingTests.cs
+++ b/src/Sapling.Engine.Tests/HumanPolicyEncodingTests.cs
@@ -66,6 +66,7 @@ public void Encoders_MatchSharedGoldenFixtures()
}
[Theory]
+ [InlineData(500, -1.4285715f)]
[InlineData(800, -1f)]
[InlineData(1500, 0f)]
[InlineData(2200, 1f)]
@@ -75,7 +76,7 @@ public void RatingEncoder_UsesSpecifiedScale(int rating, float expected)
}
[Theory]
- [InlineData(799)]
+ [InlineData(499)]
[InlineData(2201)]
public void RatingEncoder_RejectsOutOfRangeValues(int rating)
{
diff --git a/src/Sapling.Engine.Tests/TimeManagementTests.cs b/src/Sapling.Engine.Tests/TimeManagementTests.cs
index 2a798e3..b1b1c29 100644
--- a/src/Sapling.Engine.Tests/TimeManagementTests.cs
+++ b/src/Sapling.Engine.Tests/TimeManagementTests.cs
@@ -31,6 +31,18 @@ public void FlaggedClock_GetsSmallFiniteBudget()
Assert.True(budget.HardLimitMs >= budget.SoftLimitMs);
}
+ [Theory]
+ [InlineData(100, 1, 4)]
+ [InlineData(200, 10, 40)]
+ [InlineData(1_000, 23, 92)]
+ public void LowBulletClock_LeavesLargerResponseReserve(int timeMs, int softMs, int hardMs)
+ {
+ var budget = TimeManagement.Calculate(timeMs, 0, 0, 20, true);
+
+ Assert.Equal(softMs, budget.SoftLimitMs);
+ Assert.Equal(hardMs, budget.HardLimitMs);
+ }
+
[Theory]
[InlineData(10_000, 0, 0)]
[InlineData(10_000, 100, 10)]
@@ -55,6 +67,15 @@ public void ExplicitMovesToGo_AllocatesMoreThanEmergencyClock()
Assert.True(fiveMoves.SoftLimitMs > thirtyMoves.SoftLimitMs);
}
+ [Fact]
+ public void HardLimit_IsBoundedByFourSoftBudgetsOnLongClock()
+ {
+ var budget = TimeManagement.Calculate(287_710, 2_000, 0, 98, true);
+
+ Assert.Equal(10_706, budget.SoftLimitMs);
+ Assert.Equal(42_824, budget.HardLimitMs);
+ }
+
[Fact]
public void SoftLimitAdjustment_SpendsLessOnStableMoves()
{
diff --git a/src/Sapling.Engine.Tests/UciProcessStabilityTests.cs b/src/Sapling.Engine.Tests/UciProcessStabilityTests.cs
index db56631..42d1d3d 100644
--- a/src/Sapling.Engine.Tests/UciProcessStabilityTests.cs
+++ b/src/Sapling.Engine.Tests/UciProcessStabilityTests.cs
@@ -85,14 +85,20 @@ public void Smp_ThreadCounts_ProduceLegalBestmoves(int threads)
}
[Theory]
+ [InlineData(16)]
[InlineData(32)]
[InlineData(256)]
[InlineData(1024)]
public void Hash_Sizes_Work(int mb)
{
using var e = StartEngine();
+ var options = e.ParseOptions();
+ Assert.Equal("16", options["Hash"].lo);
+ Assert.Equal("16", options["Hash"].dflt);
e.Send($"setoption name Hash value {mb}");
- e.Ready();
+ e.Send("isready");
+ var response = e.ReadUntil("readyok");
+ Assert.DoesNotContain(response, line => line.StartsWith(ErrorPrefix));
e.Send("position startpos");
Assert.True(e.Bestmove("go depth 6").Length > 0, $"Hash={mb} must produce a bestmove");
}
@@ -167,7 +173,7 @@ public void FullSelfPlayGame_ClocksAndLegality()
var mv = e.Bestmove($"go wtime {wtime} btime {btime} winc 4 binc 4");
var dt = (int)sw.ElapsedMilliseconds;
if (mv.Length == 0 || mv == "(none)") break;
- Assert.True(dt < clock + 500, $"ply {ply} overran its clock");
+ Assert.True(dt < clock, $"ply {ply} flagged: spent {dt} ms with {clock} ms on the clock");
if (white) wtime = Math.Max(1, wtime - dt + 4); else btime = Math.Max(1, btime - dt + 4);
moves.Add(mv);
e.Send("position startpos moves " + string.Join(' ', moves));
@@ -177,6 +183,45 @@ public void FullSelfPlayGame_ClocksAndLegality()
ReplayLegal(string.Join(' ', moves));
}
+ [Fact]
+ public void LongZeroIncrementBulletGame_DoesNotFlagWithoutHumanElo()
+ {
+ using var e = StartEngine();
+ e.Send("setoption name Threads value 1");
+ e.Send("setoption name Hash value 16");
+ e.Ready();
+
+ var moves = new List();
+ double whiteTimeMs = 1_000;
+ double blackTimeMs = 1_000;
+ for (var ply = 0; ply < 140; ply++)
+ {
+ var whiteToMove = ply % 2 == 0;
+ var clockMs = whiteToMove ? whiteTimeMs : blackTimeMs;
+ Assert.True(clockMs > 0, $"flagged before ply {ply + 1}");
+
+ e.Send(moves.Count == 0
+ ? "position startpos"
+ : "position startpos moves " + string.Join(' ', moves));
+ var wtime = Math.Max(0, (int)Math.Floor(whiteTimeMs));
+ var btime = Math.Max(0, (int)Math.Floor(blackTimeMs));
+ var timer = Stopwatch.StartNew();
+ var move = e.Bestmove($"go wtime {wtime} btime {btime} winc 0 binc 0");
+ Assert.True(timer.Elapsed.TotalMilliseconds < clockMs,
+ $"flagged on ply {ply + 1}: spent {timer.Elapsed.TotalMilliseconds:F2} ms with {clockMs:F2} ms left");
+ Assert.NotEmpty(move);
+ Assert.NotEqual("(none)", move);
+
+ moves.Add(move);
+ if (whiteToMove)
+ whiteTimeMs -= timer.Elapsed.TotalMilliseconds;
+ else
+ blackTimeMs -= timer.Elapsed.TotalMilliseconds;
+ }
+
+ Assert.Equal(140, moves.Count);
+ }
+
[Fact]
public void GameOver_MatedSideReturnsNone()
{
@@ -290,6 +335,41 @@ public void HumanEloAndPonder_OptionsProduceLegalPlay()
Assert.NotEmpty(e.Bestmove("go wtime 2000 btime 2000"));
}
+ [Fact]
+ public void HumanElo_RootRankingStaysInsideMoveTimeBudget()
+ {
+ using var e = StartEngine();
+ e.Send("setoption name HumanElo value 1500");
+ e.Ready();
+ e.Send("position startpos");
+
+ var timer = Stopwatch.StartNew();
+ Assert.NotEmpty(e.Bestmove("go movetime 100"));
+
+ Assert.True(timer.Elapsed < TimeSpan.FromMilliseconds(600),
+ $"HumanElo ranking must respect the 100 ms move budget; took {timer.Elapsed.TotalMilliseconds:F0} ms");
+ }
+
+ [Fact]
+ public void HumanTemperatureOption_AcceptsPositiveFloatAndRejectsZero()
+ {
+ using var e = StartEngine();
+ var options = e.ParseOptions();
+ Assert.Equal("string", options["HumanTemperature"].kind);
+
+ e.Send("setoption name HumanElo value 1500");
+ e.Send("setoption name HumanTemperature value 0.8");
+ e.Ready();
+ Assert.False(e.SawPrefixWithin(ErrorPrefix, TimeSpan.FromMilliseconds(200)));
+
+ e.Send("setoption name HumanTemperature value 0");
+ Assert.True(e.SawPrefixWithin(ErrorPrefix, TimeSpan.FromSeconds(2)));
+
+ e.Send("setoption name HumanTemperature value 1");
+ e.Send("setoption name HumanElo value 0");
+ e.Ready();
+ }
+
[Fact]
public void PonderCommands_DoNotWedgeTheEngine()
{
diff --git a/src/Sapling.Engine/HumanPolicyEncoding.cs b/src/Sapling.Engine/HumanPolicyEncoding.cs
index f097b11..c0f4aac 100644
--- a/src/Sapling.Engine/HumanPolicyEncoding.cs
+++ b/src/Sapling.Engine/HumanPolicyEncoding.cs
@@ -9,7 +9,7 @@ public static unsafe class HumanPolicyEncoding
public const int BoardChannels = 18;
public const int SquaresPerBoard = 64;
public const int MoveFeatures = 134;
- public const int MinRating = 800;
+ public const int MinRating = 500;
public const int MaxRating = 2200;
private static readonly byte[] PieceChannels =
diff --git a/src/Sapling.Engine/MathHelpers.cs b/src/Sapling.Engine/MathHelpers.cs
index c3b3501..1145b9f 100644
--- a/src/Sapling.Engine/MathHelpers.cs
+++ b/src/Sapling.Engine/MathHelpers.cs
@@ -101,7 +101,11 @@ public static void FreeAligned(void* block)
// Parallel zero-init. Runtimes without blocking waits (browser-wasm) must
// zero the block inline; Task.WaitAll throws "Cannot wait on monitors" there.
- int threadCount = Environment.ProcessorCount;
+ // TT allocation is independent of UCI search Threads. Using the full logical CPU
+ // count here can make even a single-threaded search create hundreds of runtime
+ // worker threads on large tournament hosts. A small fixed fan-out is sufficient
+ // to clear the table quickly without scaling the process thread count with the host.
+ int threadCount = Math.Min(Environment.ProcessorCount, 8);
if (threadCount <= 1 || OperatingSystem.IsBrowser())
{
ZeroBytes((byte*)block, totalSize);
diff --git a/src/Sapling.Engine/Resources/human_policy_v1.weights b/src/Sapling.Engine/Resources/human_policy_v1.weights
index d869e2f..9be8777 100644
Binary files a/src/Sapling.Engine/Resources/human_policy_v1.weights and b/src/Sapling.Engine/Resources/human_policy_v1.weights differ
diff --git a/src/Sapling.Engine/Search/ParallelSearcher.cs b/src/Sapling.Engine/Search/ParallelSearcher.cs
index 219bbe7..c4c2ac0 100644
--- a/src/Sapling.Engine/Search/ParallelSearcher.cs
+++ b/src/Sapling.Engine/Search/ParallelSearcher.cs
@@ -265,7 +265,7 @@ public Searcher.ResumableResult ResumableSlice(int maxDepth, long sliceNodeBudge
/// Root ranking for human-like difficulty. Single worker, direct table access. Only reached
/// when HumanPlay is enabled; the normal search paths are unaffected.
///
- public List<(uint Move, int Score, int Feat)> RankRootMoves(GameState state, int depth)
+ public List<(uint Move, int Score, int Feat)> RankRootMoves(GameState state, int depth, int timeLimitMs = 0)
{
lock (_operationGate)
{
@@ -283,7 +283,7 @@ public Searcher.ResumableResult ResumableSlice(int maxDepth, long sliceNodeBudge
}
try
{
- return worker.RankRootMoves(state, depth);
+ return worker.RankRootMoves(state, depth, timeLimitMs);
}
finally
{
diff --git a/src/Sapling.Engine/Search/Searcher.HumanRank.cs b/src/Sapling.Engine/Search/Searcher.HumanRank.cs
index 61184c9..6323e2e 100644
--- a/src/Sapling.Engine/Search/Searcher.HumanRank.cs
+++ b/src/Sapling.Engine/Search/Searcher.HumanRank.cs
@@ -16,7 +16,7 @@ namespace Sapling.Engine.Search;
///
public unsafe partial class Searcher
{
- public List<(uint Move, int Score, int Feat)> RankRootMoves(GameState inputBoard, int depth)
+ public List<(uint Move, int Score, int Feat)> RankRootMoves(GameState inputBoard, int depth, int timeLimitMs = 0)
{
lock (_lifecycleGate)
{
@@ -25,7 +25,7 @@ public unsafe partial class Searcher
ResetCore(inputBoard);
_nodeLimit = 0;
- _deadlineTimestamp = 0;
+ SetTimeLimits(timeLimitMs, timeLimitMs);
_sliceActive = false;
_sliceExhausted = false;
@@ -61,6 +61,8 @@ public unsafe partial class Searcher
var score = -NegaMaxSearch(newBoardState, newAccumulatorState, 1, depth - 1,
Constants.MinScore, Constants.MaxScore);
+ if (Interrupted())
+ break;
var feat = (m.IsCapture() ? 1 : 0)
| (m.IsCastle() ? 2 : 0)
diff --git a/src/Sapling.Engine/Search/TimeManagement.cs b/src/Sapling.Engine/Search/TimeManagement.cs
index df768a1..d708bb2 100644
--- a/src/Sapling.Engine/Search/TimeManagement.cs
+++ b/src/Sapling.Engine/Search/TimeManagement.cs
@@ -7,9 +7,15 @@ public readonly record struct SearchTimeBudget(int SoftLimitMs, int HardLimitMs,
public static class TimeManagement
{
- private const long OverheadMs = 50;
+ // Keep the established 50 ms reserve while there is time to think, then ramp it to 100 ms
+ // as the clock approaches zero. A fixed 100 ms reserve reduced bullet strength; a fixed
+ // 50 ms reserve produced 1 ms flag overruns in loaded gauntlets.
+ private const long MinOverheadMs = 50;
+ private const long MaxOverheadMs = 100;
+ private const long OverheadRampMs = 1_000;
private const long MinSearchMs = 10;
private const long ShortClockThresholdMs = 120_000;
+ private const long MaxHardToSoftMultiple = 4;
private static ReadOnlySpan StabilityFactors => [1.8, 1.4, 1.2, 1.0, 0.9, 0.8, 0.75];
public static SearchTimeBudget Calculate(
@@ -33,11 +39,11 @@ public static SearchTimeBudget Calculate(
if (!hasClock)
return SearchTimeBudget.InfiniteSearch;
- var remaining = Math.Max(1, (long)timeMs - OverheadMs);
+ var remaining = Math.Max(1, (long)timeMs - CalculateOverhead(timeMs));
var increment = Math.Max(0, incrementMs);
var moves = movesToGo > 0
? Math.Clamp(movesToGo, 1, 500)
- : plyCount < 40 ? 30 : plyCount < 80 ? 20 : 10;
+ : plyCount < 40 ? 40 : plyCount < 80 ? 30 : 20;
long soft;
if (remaining < ShortClockThresholdMs)
@@ -46,7 +52,7 @@ public static SearchTimeBudget Calculate(
if (remaining > increment * 2)
allocation += increment * 8 / 10;
- var minimum = Math.Min(50, remaining / 4);
+ var minimum = Math.Min(MinSearchMs, remaining / 4);
soft = Math.Max(minimum, allocation);
}
else
@@ -56,10 +62,20 @@ public static SearchTimeBudget Calculate(
}
soft = Math.Clamp(soft, 1, remaining);
- var hard = Math.Clamp(remaining * 9 / 10, soft, remaining);
+ // A single deep iteration can run past the soft limit before iterative deepening
+ // checks it again. Keep the hard deadline tied to this move's allocation so that
+ // one such iteration cannot consume most of the player's remaining clock.
+ var hard = Math.Clamp(Math.Min(remaining * 9 / 10, soft * MaxHardToSoftMultiple), soft, remaining);
return new SearchTimeBudget((int)soft, (int)hard, false);
}
+ private static long CalculateOverhead(int timeMs)
+ {
+ var clock = Math.Clamp((long)timeMs, 0, OverheadRampMs);
+ var ramp = (OverheadRampMs - clock) * (MaxOverheadMs - MinOverheadMs) / OverheadRampMs;
+ return MinOverheadMs + ramp;
+ }
+
public static int AdjustSoftLimit(
int baseSoftLimitMs,
int hardLimitMs,
diff --git a/src/Sapling.Engine/Transpositions/TranspositionTableExtensions.cs b/src/Sapling.Engine/Transpositions/TranspositionTableExtensions.cs
index 7d71b28..20aa1e0 100644
--- a/src/Sapling.Engine/Transpositions/TranspositionTableExtensions.cs
+++ b/src/Sapling.Engine/Transpositions/TranspositionTableExtensions.cs
@@ -177,23 +177,11 @@ public static unsafe int CalculateSizeInMb(uint transpositionCount)
throw new ArgumentException("Invalid transposition count, must be a power of 2.");
}
- // Reverse the potential shift caused by rounding up in the original function
- ulong adjustedTranspositionCount = (ulong)transpositionCount << 1;
-
- // Calculate the size in MB
- var sizeInMb = (int)(adjustedTranspositionCount * (ulong)sizeof(Transposition) / (1024 * 1024));
-
- // Check if the original function would have produced the same transposition count
- // for this sizeInMb, if not, decrement the size until it matches.
- while (CalculateTranspositionTableSize(sizeInMb) != transpositionCount)
- {
- sizeInMb--;
- if (sizeInMb < 0)
- {
- throw new ArgumentException("Could not invert the function, invalid input.");
- }
- }
-
- return sizeInMb;
+ // Report the bytes this table actually occupies. The size-to-count conversion retains
+ // a historical 20-byte divisor for search-tree compatibility, but entries now have a
+ // 16-byte stride. Reversing that conversion reports a larger Hash setting than the
+ // allocated table and can cause UCI clients to write back an inflated default.
+ var allocatedBytes = (ulong)transpositionCount * (ulong)sizeof(Transposition);
+ return checked((int)(allocatedBytes / (1024 * 1024)));
}
}
diff --git a/src/Sapling.Engine/Tuning/DirectCaptureRisk.cs b/src/Sapling.Engine/Tuning/DirectCaptureRisk.cs
new file mode 100644
index 0000000..ce6ab26
--- /dev/null
+++ b/src/Sapling.Engine/Tuning/DirectCaptureRisk.cs
@@ -0,0 +1,61 @@
+using Sapling.Engine.MoveGen;
+
+namespace Sapling.Engine.Tuning;
+
+/// Detects immediate legal captures of a minor-or-better piece without a legal recapture.
+public static unsafe class DirectCaptureRisk
+{
+ public static bool IsRiskAfterMove(ref BoardStateData source, uint move)
+ {
+ return IsRiskAfterMove(ref source, move, new List(32), new List(32));
+ }
+
+ public static bool IsRiskAfterMove(ref BoardStateData source, uint move,
+ List replies, List recaptures)
+ {
+ ArgumentNullException.ThrowIfNull(replies);
+ ArgumentNullException.ThrowIfNull(recaptures);
+ var after = source;
+ ApplyMove(ref after, move);
+ // We only need captures here; avoiding quiet replies substantially reduces the
+ // per-candidate cost of the runtime safety signal.
+ after.GenerateLegalMoves(replies, captureOnly: true);
+ foreach (var capture in replies)
+ {
+ var victim = capture.GetCapturedPiece();
+ if (victim == Constants.None || PieceValues.PieceValue[victim] < Constants.KnightValue)
+ continue;
+
+ var captureSquare = capture.GetToSquare();
+ var afterCapture = after;
+ ApplyMove(ref afterCapture, capture);
+ var capturingPieceAfterMove = afterCapture.GetPiece(captureSquare);
+ afterCapture.GenerateLegalMoves(recaptures, captureOnly: true);
+ var recaptured = recaptures.Any(reply => reply.GetToSquare() == captureSquare
+ && reply.GetCapturedPiece() == capturingPieceAfterMove);
+ if (!recaptured)
+ return true;
+ }
+ return false;
+ }
+
+ private static void ApplyMove(ref BoardStateData board, uint move)
+ {
+ var oldEnpassant = board.EnPassantFile;
+ var oldEnpassantHashFile = Zobrist.GetEnPassantHashFile(ref board);
+ var oldCastle = board.CastleRights;
+ var whiteToMove = board.WhiteToMove;
+ if (whiteToMove) board.PartialApplyWhite(move);
+ else board.PartialApplyBlack(move);
+ board.UpdateCheckStatus();
+
+ AccumulatorState accumulator = default;
+ fixed (BoardStateData* boardPtr = &board)
+ {
+ if (whiteToMove)
+ boardPtr->FinishApplyWhite(ref accumulator, move, oldEnpassant, oldEnpassantHashFile, oldCastle);
+ else
+ boardPtr->FinishApplyBlack(ref accumulator, move, oldEnpassant, oldEnpassantHashFile, oldCastle);
+ }
+ }
+}
diff --git a/src/Sapling.Engine/Tuning/HumanMovePolicy.cs b/src/Sapling.Engine/Tuning/HumanMovePolicy.cs
index 886225d..ccdd3f5 100644
--- a/src/Sapling.Engine/Tuning/HumanMovePolicy.cs
+++ b/src/Sapling.Engine/Tuning/HumanMovePolicy.cs
@@ -1,4 +1,5 @@
using System.Reflection;
+using System.Security.Cryptography;
using System.Text;
using Sapling.Engine.MoveGen;
@@ -17,26 +18,63 @@ public static class HumanMovePolicy
private const int BoardEmbedding = 128;
private const int MoveHidden = 64;
private const string ResourceName = "Sapling.Engine.HumanPolicy.weights";
+ public static string ModelSha256 { get; private set; } = string.Empty;
private static readonly Weights Model = LoadWeights();
/// Returns one raw policy logit per candidate; the input feature layout is schema v1.
public static float[] ScoreCandidates(ReadOnlySpan board, ReadOnlySpan moves,
int candidateCount, int rating)
+ {
+ ValidateFeatures(board, moves, candidateCount);
+ if (rating is < HumanPolicyEncoding.MinRating or > HumanPolicyEncoding.MaxRating)
+ throw new ArgumentOutOfRangeException(nameof(rating));
+
+ var embedding = EncodeBoardEmbedding(board);
+ return ScoreCandidatesFromEmbedding(moves, candidateCount, rating, embedding);
+ }
+
+ /// Scores multiple rating conditions while encoding the position once.
+ public static float[][] ScoreCandidatesForRatings(ReadOnlySpan board,
+ ReadOnlySpan moves, int candidateCount, ReadOnlySpan ratings)
+ {
+ ValidateFeatures(board, moves, candidateCount);
+ if (ratings.IsEmpty)
+ throw new ArgumentException("At least one target rating is required.", nameof(ratings));
+ foreach (var rating in ratings)
+ if (rating is < HumanPolicyEncoding.MinRating or > HumanPolicyEncoding.MaxRating)
+ throw new ArgumentOutOfRangeException(nameof(ratings), rating,
+ $"Ratings must be in [{HumanPolicyEncoding.MinRating}, {HumanPolicyEncoding.MaxRating}].");
+
+ var embedding = EncodeBoardEmbedding(board);
+ var logitsByRating = new float[ratings.Length][];
+ for (var i = 0; i < ratings.Length; i++)
+ logitsByRating[i] = ScoreCandidatesFromEmbedding(moves, candidateCount, ratings[i], embedding);
+ return logitsByRating;
+ }
+
+ private static void ValidateFeatures(ReadOnlySpan board, ReadOnlySpan moves,
+ int candidateCount)
{
if (board.Length != BoardLength)
throw new ArgumentException($"Board tensor must have length {BoardLength}.", nameof(board));
if (candidateCount < 1 || moves.Length != checked(candidateCount * CandidateFeatures))
throw new ArgumentException("Move tensor size does not match the candidate count.", nameof(moves));
- if (rating is < HumanPolicyEncoding.MinRating or > HumanPolicyEncoding.MaxRating)
- throw new ArgumentOutOfRangeException(nameof(rating));
+ }
+ private static float[] EncodeBoardEmbedding(ReadOnlySpan board)
+ {
var first = new float[ConvChannels * 64];
var second = new float[ConvChannels * 64];
var embedding = new float[BoardEmbedding];
Convolve(board, Model.Conv1Weight, Model.Conv1Bias, 18, first);
Convolve(first, Model.Conv2Weight, Model.Conv2Bias, ConvChannels, second);
DenseRelu(second, Model.BoardWeight, Model.BoardBias, embedding);
+ return embedding;
+ }
+ private static float[] ScoreCandidatesFromEmbedding(ReadOnlySpan moves, int candidateCount,
+ int rating, float[] embedding)
+ {
var ratingFeature = HumanPolicyEncoding.EncodeRating(rating);
var logits = new float[candidateCount];
Span hidden = stackalloc float[MoveHidden];
@@ -66,38 +104,78 @@ public static float[] ScoreCandidates(ReadOnlySpan board, ReadOnlySpanSamples one candidate from the policy softmax and reports its probability.
public static int Sample(Random random, ReadOnlySpan board, ReadOnlySpan moves,
int candidateCount, int rating, out float probability)
+ => Sample(random, board, moves, candidateCount, rating, 1f, out probability);
+
+ /// Samples at the supplied temperature and reports probability under that distribution.
+ public static int Sample(Random random, ReadOnlySpan board, ReadOnlySpan moves,
+ int candidateCount, int rating, float temperature, out float probability)
+ => Sample(random, board, moves, candidateCount, rating, temperature, out probability,
+ ReadOnlySpan.Empty, 0f);
+
+ /// Samples with an optional soft logit penalty for candidates marked by a safety signal.
+ public static int Sample(Random random, ReadOnlySpan board, ReadOnlySpan moves,
+ int candidateCount, int rating, float temperature, out float probability,
+ ReadOnlySpan penalizedCandidates, float logitPenalty)
{
ArgumentNullException.ThrowIfNull(random);
+ if (!float.IsFinite(logitPenalty) || logitPenalty < 0f)
+ throw new ArgumentOutOfRangeException(nameof(logitPenalty), "Logit penalty must be finite and non-negative.");
+ if (!penalizedCandidates.IsEmpty && penalizedCandidates.Length != candidateCount)
+ throw new ArgumentException("Penalty mask length must match candidate count.", nameof(penalizedCandidates));
+ if (logitPenalty > 0f && penalizedCandidates.IsEmpty)
+ throw new ArgumentException("A non-empty penalty mask is required when the logit penalty is positive.", nameof(penalizedCandidates));
var logits = ScoreCandidates(board, moves, candidateCount, rating);
+ if (logitPenalty > 0f)
+ for (var i = 0; i < logits.Length; i++)
+ if (!penalizedCandidates.IsEmpty && penalizedCandidates[i]) logits[i] -= logitPenalty;
+ var probabilities = Probabilities(logits, temperature);
if (candidateCount == 1)
{
probability = 1f;
return 0;
}
- var max = logits.Max();
- var total = 0.0;
- for (var i = 0; i < logits.Length; i++)
- total += Math.Exp((double)logits[i] - max);
- if (!double.IsFinite(total) || total <= 0)
- throw new InvalidOperationException("Human policy scores cannot be normalized.");
-
- var target = random.NextDouble() * total;
+ var target = random.NextDouble();
var selected = logits.Length - 1;
for (var i = 0; i < logits.Length; i++)
{
- var weight = Math.Exp((double)logits[i] - max);
- target -= weight;
+ target -= probabilities[i];
if (target < 0)
{
selected = i;
break;
}
}
- probability = (float)(Math.Exp((double)logits[selected] - max) / total);
+ probability = probabilities[selected];
return selected;
}
+ /// Returns a numerically stable softmax distribution over logits.
+ public static float[] Probabilities(ReadOnlySpan logits, float temperature = 1f)
+ {
+ if (logits.IsEmpty)
+ throw new ArgumentException("At least one candidate logit is required.", nameof(logits));
+ if (!float.IsFinite(temperature) || temperature <= 0f)
+ throw new ArgumentOutOfRangeException(nameof(temperature), "Temperature must be finite and positive.");
+
+ var max = logits[0];
+ for (var i = 1; i < logits.Length; i++)
+ if (logits[i] > max) max = logits[i];
+ var probabilities = new float[logits.Length];
+ var total = 0.0;
+ for (var i = 0; i < logits.Length; i++)
+ {
+ var weight = Math.Exp(((double)logits[i] - max) / temperature);
+ probabilities[i] = (float)weight;
+ total += weight;
+ }
+ if (!double.IsFinite(total) || total <= 0)
+ throw new InvalidOperationException("Human policy scores cannot be normalized.");
+ for (var i = 0; i < probabilities.Length; i++)
+ probabilities[i] = (float)(probabilities[i] / total);
+ return probabilities;
+ }
+
private static void Convolve(ReadOnlySpan input, float[] weights, float[] bias,
int inputChannels, Span output)
{
@@ -142,6 +220,8 @@ private static Weights LoadWeights()
{
using var stream = typeof(HumanMovePolicy).Assembly.GetManifestResourceStream(ResourceName)
?? throw new InvalidDataException($"Embedded human policy resource '{ResourceName}' was not found.");
+ ModelSha256 = Convert.ToHexString(SHA256.HashData(stream)).ToLowerInvariant();
+ stream.Position = 0;
using var reader = new BinaryReader(stream, Encoding.ASCII, leaveOpen: false);
if (!reader.ReadBytes(8).AsSpan().SequenceEqual("SAPHPW01"u8))
throw new InvalidDataException("Embedded human policy has an invalid header.");
diff --git a/src/Sapling.Engine/Tuning/HumanPlay.cs b/src/Sapling.Engine/Tuning/HumanPlay.cs
index fe6f0f3..874ef35 100644
--- a/src/Sapling.Engine/Tuning/HumanPlay.cs
+++ b/src/Sapling.Engine/Tuning/HumanPlay.cs
@@ -2,6 +2,8 @@
namespace Sapling.Engine.Tuning;
+public readonly record struct HumanMoveSelection(uint Move, int Rank, float Probability);
+
/// Rating-conditioned move selection backed by the embedded trained human policy.
public static class HumanPlay
{
@@ -11,6 +13,7 @@ public static class HumanPlay
public static bool Enabled { get; private set; }
public static int Elo { get; private set; }
+ public static float Temperature { get; private set; } = 1f;
public static int RankDepth { get; set; } = DefaultRankDepth;
/// Zero disables human play. Active ratings are clamped to the trained range.
@@ -20,6 +23,14 @@ public static void SetElo(int elo)
Enabled = Elo != 0;
}
+ /// Sets the calibrated sampling temperature; 1 preserves the trained distribution.
+ public static void SetTemperature(float temperature)
+ {
+ if (!float.IsFinite(temperature) || temperature <= 0f)
+ throw new ArgumentOutOfRangeException(nameof(temperature), "Temperature must be finite and positive.");
+ Temperature = temperature;
+ }
+
/// Samples among exact, best-first root candidates using schema-v1 policy features.
public static int PickMove(Random rng, ref BoardStateData board,
IReadOnlyList<(uint Move, int Score, int Feat)> ranked, out float selectedProbability)
@@ -38,14 +49,42 @@ public static int PickMove(Random rng, ref BoardStateData board,
HumanPolicyEncoding.EncodeMove(ranked[i].Move, ranked[i].Score, bestScore,
moveFeatures.AsSpan(i * HumanPolicyEncoding.MoveFeatures, HumanPolicyEncoding.MoveFeatures));
}
- return HumanMovePolicy.Sample(rng, boardFeatures, moveFeatures, ranked.Count, Elo,
+ var settings = HumanPlayCalibration.ForDisplayElo(Elo);
+ if (settings.DirectCaptureRiskPenalty > 0f)
+ {
+ var directCaptureRisk = new bool[ranked.Count];
+ var replyMoves = new List(32);
+ var recaptureMoves = new List(32);
+ for (var i = 0; i < ranked.Count; i++)
+ directCaptureRisk[i] = DirectCaptureRisk.IsRiskAfterMove(ref board, ranked[i].Move,
+ replyMoves, recaptureMoves);
+ return HumanMovePolicy.Sample(rng, boardFeatures, moveFeatures, ranked.Count,
+ settings.ModelElo, Temperature * settings.Temperature,
+ out selectedProbability, directCaptureRisk, settings.DirectCaptureRiskPenalty);
+ }
+ return HumanMovePolicy.Sample(rng, boardFeatures, moveFeatures, ranked.Count,
+ settings.ModelElo, Temperature * settings.Temperature,
out selectedProbability);
}
+ /// Returns the selected move identity, including when it is ranked first.
+ public static HumanMoveSelection SelectMove(Random rng, ref BoardStateData board,
+ IReadOnlyList<(uint Move, int Score, int Feat)> ranked)
+ {
+ ArgumentNullException.ThrowIfNull(rng);
+ ArgumentNullException.ThrowIfNull(ranked);
+ if (ranked.Count == 0)
+ throw new ArgumentException("At least one legal move is required.", nameof(ranked));
+
+ var rank = PickMove(rng, ref board, ranked, out var probability);
+ return new HumanMoveSelection(ranked[rank].Move, rank, probability);
+ }
+
public static void Reset()
{
Enabled = false;
Elo = 0;
+ Temperature = 1f;
RankDepth = DefaultRankDepth;
}
}
diff --git a/src/Sapling.Engine/Tuning/HumanPlayCalibration.cs b/src/Sapling.Engine/Tuning/HumanPlayCalibration.cs
new file mode 100644
index 0000000..2adda5c
--- /dev/null
+++ b/src/Sapling.Engine/Tuning/HumanPlayCalibration.cs
@@ -0,0 +1,78 @@
+namespace Sapling.Engine.Tuning;
+
+public readonly record struct HumanPlaySettings(int ModelElo, float Temperature, float DirectCaptureRiskPenalty = 0f);
+
+///
+/// Human-play calibration checked against Lichess rapid moves and Maia-relative outcomes.
+/// The map is valid only for the
+/// embedded policy weights it was fitted against.
+///
+public static class HumanPlayCalibration
+{
+ public const string CalibrationId = "lichess-rapid-balanced-human-errors-upper-v1";
+ public const string StrengthExperimentId = "maia-cutechess-2026-10-balanced-upper-v1";
+ public const int ExperimentalModelEloAdjustment = 0;
+ public const string SourceModelSha256 = "b075580ede7c87f7bb1375189d0d894d969e02579ed346efd3f0b116bc9aee87";
+
+ private static readonly (int DisplayElo, int ModelElo, float Temperature, float DirectCaptureRiskPenalty)[] Anchors =
+ [
+ (500, 500, 1f, 0.5f),
+ (700, 750, 1f, 0.625f),
+ (900, 1000, 1f, 0.75f),
+ (1100, 1175, 1f, 0.75f),
+ (1300, 1300, 1f, 0.625f),
+ (1500, 1500, 1f, 0.625f),
+ (1700, 1700, 1f, 0.375f),
+ (1900, 1800, 1.025f, 0.75f),
+ (2100, 1950, 1.05f, 0.75f),
+ (2200, 2050, 1.05f, 0.75f)
+ ];
+
+ public static bool AppliesToCurrentModel
+ => string.Equals(HumanMovePolicy.ModelSha256, SourceModelSha256, StringComparison.Ordinal);
+
+ public static HumanPlaySettings ForDisplayElo(int displayElo)
+ {
+ if (displayElo <= 0)
+ return new HumanPlaySettings(0, 1f, 0f);
+
+ var clamped = Math.Clamp(displayElo, HumanPlay.MinElo, HumanPlay.MaxElo);
+ if (!AppliesToCurrentModel)
+ return new HumanPlaySettings(clamped, 1f, 0f);
+
+ if (clamped <= Anchors[0].DisplayElo)
+ {
+ var first = Anchors[0];
+ var next = Anchors[1];
+ var slope = (next.ModelElo - first.ModelElo)
+ / (float)(next.DisplayElo - first.DisplayElo);
+ return new HumanPlaySettings(
+ (int)MathF.Round(first.ModelElo + (clamped - first.DisplayElo) * slope)
+ + ExperimentalModelEloAdjustment,
+ first.Temperature, first.DirectCaptureRiskPenalty);
+ }
+
+ for (var i = 1; i < Anchors.Length; i++)
+ {
+ var right = Anchors[i];
+ if (clamped > right.DisplayElo) continue;
+ var left = Anchors[i - 1];
+ var fraction = (clamped - left.DisplayElo) / (float)(right.DisplayElo - left.DisplayElo);
+ var modelElo = left.ModelElo + fraction * (right.ModelElo - left.ModelElo);
+ var temperature = left.Temperature + fraction * (right.Temperature - left.Temperature);
+ var riskPenalty = left.DirectCaptureRiskPenalty
+ + fraction * (right.DirectCaptureRiskPenalty - left.DirectCaptureRiskPenalty);
+ return new HumanPlaySettings(
+ (int)MathF.Round(modelElo) + ExperimentalModelEloAdjustment,
+ temperature, riskPenalty);
+ }
+
+ var last = Anchors[^1];
+ return WithStrengthAdjustment(last);
+ }
+
+ private static HumanPlaySettings WithStrengthAdjustment(
+ (int DisplayElo, int ModelElo, float Temperature, float DirectCaptureRiskPenalty) anchor)
+ => new(anchor.ModelElo + ExperimentalModelEloAdjustment,
+ anchor.Temperature, anchor.DirectCaptureRiskPenalty);
+}
diff --git a/src/Sapling.Mobile/App.xaml b/src/Sapling.Mobile/App.xaml
new file mode 100644
index 0000000..58d47e2
--- /dev/null
+++ b/src/Sapling.Mobile/App.xaml
@@ -0,0 +1,14 @@
+
+
+
+
+
+
+
+
+
+
+
diff --git a/src/Sapling.Mobile/App.xaml.cs b/src/Sapling.Mobile/App.xaml.cs
new file mode 100644
index 0000000..f670827
--- /dev/null
+++ b/src/Sapling.Mobile/App.xaml.cs
@@ -0,0 +1,12 @@
+namespace Sapling.Mobile;
+
+public partial class App : Application
+{
+ public App()
+ {
+ UserAppTheme = AppTheme.Dark;
+ InitializeComponent();
+ }
+
+ protected override Window CreateWindow(IActivationState? activationState) => new(new MainPage());
+}
diff --git a/src/Sapling.Mobile/MainPage.cs b/src/Sapling.Mobile/MainPage.cs
new file mode 100644
index 0000000..16a0a7d
--- /dev/null
+++ b/src/Sapling.Mobile/MainPage.cs
@@ -0,0 +1,994 @@
+using System.Diagnostics;
+using System.Globalization;
+using Sapling.Engine;
+using Sapling.Engine.MoveGen;
+using Sapling.Engine.Search;
+using Sapling.Engine.Transpositions;
+using Sapling.Engine.Tuning;
+
+namespace Sapling.Mobile;
+
+/// Native MAUI game screen. The C# engine runs in-process; no web view or server is used.
+public sealed class MainPage : ContentPage
+{
+ private static readonly Color Canvas = Color.FromArgb("#0B0B0F");
+ private static readonly Color Surface = Color.FromArgb("#1C1C1E");
+ private static readonly Color Surface2 = Color.FromArgb("#2C2C2E");
+ private static readonly Color PrimaryText = Color.FromArgb("#F2F2F7");
+ private static readonly Color SecondaryText = Color.FromArgb("#98989F");
+ private static readonly Color Separator = Color.FromArgb("#38383A");
+ private static readonly Color Accent = Color.FromArgb("#0A84FF");
+ private static readonly Color LightSquare = Color.FromArgb("#F0D9B5");
+ private static readonly Color DarkSquare = Color.FromArgb("#B58863");
+ private static readonly string InitialFen = Constants.InitialState;
+
+ private readonly Grid _board = new() { RowSpacing = 0, ColumnSpacing = 0 };
+ private readonly AbsoluteLayout _animationOverlay = new() { InputTransparent = true };
+ private readonly Button[] _squares = new Button[64];
+ private readonly Image[] _pieces = new Image[64];
+ private readonly Label _status = new() { FontSize = 15, FontAttributes = FontAttributes.Bold };
+ private readonly Label _moveCount = new() { FontSize = 13, TextColor = SecondaryText };
+ private readonly Label _depth = new() { Text = "–" };
+ private readonly Label _evaluation = new() { Text = "–" };
+ private readonly Label _elapsed = new() { Text = "–" };
+ private readonly Label _nodes = new() { Text = "–" };
+ private readonly Label _nps = new() { Text = "–" };
+ private readonly Label _pv = new() { Text = "–", LineBreakMode = LineBreakMode.WordWrap, FontSize = 12 };
+ private readonly VerticalStackLayout _moveRows = new() { Spacing = 4 };
+ private readonly Label _material = new() { FontSize = 13, TextColor = SecondaryText };
+ private readonly Label _eloValue = new() { FontSize = 13, TextColor = SecondaryText };
+ private readonly Slider _eloSlider = new() { Minimum = 0, Maximum = 171, Value = 171 };
+ private readonly Button _undoButton;
+ private readonly Button _redoButton;
+ private readonly Button _hintButton;
+ private readonly Button _searchButton;
+ private readonly Button _whiteButton;
+ private readonly Button _blackButton;
+ private readonly Border _root;
+
+ private ParallelSearcher? _engine;
+ private GameState? _game;
+ private Task? _searchTask;
+ private int? _selectedSquare;
+ private HashSet _targets = [];
+ private readonly List _history = [];
+ private readonly Stack _redo = new();
+ private readonly List<(int Value, bool WhiteCaptured)> _captured = [];
+ private readonly List _moveLabels = [];
+ private Dictionary _hintScores = new(StringComparer.Ordinal);
+ private bool _humanWhite = true;
+ private bool _flipped;
+ private bool _thinking;
+ private bool _hinting;
+ private bool _hintMode;
+ private bool _restoring;
+ private bool _disposed;
+ private volatile bool _cancelSearch;
+ private int _positionVersion;
+ private int _boardRenderVersion;
+ private readonly Stopwatch _searchClock = new();
+ private readonly Random _humanRng = new();
+
+ public MainPage()
+ {
+ Title = "Sapling";
+ BackgroundColor = Canvas;
+ Padding = new Thickness(12, 4);
+ _undoButton = ActionButton("Undo", "arrow.uturn.backward", UndoAsync);
+ _redoButton = ActionButton("Redo", "arrow.uturn.forward", RedoAsync);
+ _hintButton = ActionButton("Hints Off", "sparkles", ToggleHintsAsync);
+ _searchButton = new Button
+ {
+ Text = "New game", FontSize = 12, Padding = new Thickness(6, 10), CornerRadius = 14,
+ BackgroundColor = Accent, TextColor = Colors.White, HorizontalOptions = LayoutOptions.Fill,
+ VerticalOptions = LayoutOptions.Center, MinimumHeightRequest = 46
+ };
+ _searchButton.Clicked += SearchButtonNewGameClicked;
+ _whiteButton = ActionButton("White", "", () => ChangeSideAsync(true));
+ _blackButton = ActionButton("Black", "", () => ChangeSideAsync(false));
+ _whiteButton.BackgroundColor = Accent;
+ _whiteButton.TextColor = Colors.White;
+ _root = new Border
+ {
+ StrokeThickness = 0,
+ StrokeShape = new Microsoft.Maui.Controls.Shapes.RoundRectangle { CornerRadius = 28 },
+ BackgroundColor = Canvas,
+ Content = BuildPageContent()
+ };
+ Content = _root;
+ BuildBoard();
+ ApplyTheme();
+ Application.Current!.RequestedThemeChanged += (_, _) => ApplyTheme();
+ UpdateBoard();
+ SetStatus("Preparing local engine…");
+ Loaded += OnLoaded;
+ Unloaded += OnUnloaded;
+ }
+
+ private View BuildPageContent()
+ {
+ var scroll = new ScrollView { VerticalScrollBarVisibility = ScrollBarVisibility.Never };
+ var content = new VerticalStackLayout { Spacing = 12, Padding = new Thickness(0, 4, 0, 20) };
+ content.Children.Add(BuildHeader());
+ content.Children.Add(BuildBoardCard());
+ content.Children.Add(BuildActionRow());
+ content.Children.Add(BuildSettingsCard());
+ content.Children.Add(BuildAnalysisCard());
+ content.Children.Add(BuildMovesCard());
+ content.Children.Add(BuildExportRow());
+ scroll.Content = content;
+ return scroll;
+ }
+
+ private View BuildHeader()
+ {
+ var title = new Label
+ {
+ Text = "Sapling", FontSize = 28, FontAttributes = FontAttributes.Bold,
+ VerticalTextAlignment = TextAlignment.Center
+ };
+ var subtitle = new Label { Text = "CHESS ENGINE", FontSize = 10, CharacterSpacing = 1.5, TextColor = SecondaryText };
+ var brandText = new VerticalStackLayout { Spacing = 1, Children = { title, subtitle } };
+ var brand = new HorizontalStackLayout
+ {
+ Spacing = 9,
+ VerticalOptions = LayoutOptions.Center,
+ Children = { new Image { Source = "sapling_logo.png", WidthRequest = 28, HeightRequest = 28, Aspect = Aspect.AspectFit }, brandText }
+ };
+ var github = new Button
+ {
+ Text = "GitHub", FontSize = 13, Padding = new Thickness(13, 8),
+ CornerRadius = 18, BackgroundColor = Surface2, TextColor = PrimaryText,
+ HorizontalOptions = LayoutOptions.End, VerticalOptions = LayoutOptions.Center
+ };
+ github.Clicked += async (_, _) => await Launcher.Default.OpenAsync("https://github.com/Timmoth/Sapling");
+ var row = new Grid { ColumnDefinitions = { new ColumnDefinition(GridLength.Star), new ColumnDefinition(GridLength.Auto) } };
+ row.Add(brand, 0, 0);
+ row.Add(github, 1, 0);
+ return row;
+ }
+
+ private View BuildBoardCard()
+ {
+ var statusRow = new Grid
+ {
+ ColumnDefinitions = { new ColumnDefinition(GridLength.Star), new ColumnDefinition(GridLength.Auto) },
+ Children = { _status, _moveCount }
+ };
+ Grid.SetColumn(_moveCount, 1);
+ var boardFrame = new Border
+ {
+ Stroke = Color.FromArgb("#333333"),
+ StrokeThickness = 2,
+ StrokeShape = new Microsoft.Maui.Controls.Shapes.RoundRectangle { CornerRadius = 13 },
+ Padding = 0,
+ Content = BuildBoardSurface(),
+ HorizontalOptions = LayoutOptions.Fill,
+ MaximumWidthRequest = 640
+ };
+ boardFrame.SizeChanged += (_, _) =>
+ {
+ var width = boardFrame.Width - boardFrame.Padding.HorizontalThickness;
+ if (width > 0) boardFrame.HeightRequest = width;
+ };
+ var boardStack = new VerticalStackLayout { Spacing = 9, Children = { statusRow, boardFrame, _material } };
+ var card = Card(boardStack);
+ return card;
+ }
+
+ private View BuildBoardSurface()
+ {
+ var surface = new Grid();
+ surface.Add(_board);
+ surface.Add(_animationOverlay);
+ return surface;
+ }
+
+ private View BuildActionRow()
+ {
+ var grid = new Grid
+ {
+ ColumnDefinitions =
+ {
+ new ColumnDefinition(GridLength.Star), new ColumnDefinition(GridLength.Star),
+ new ColumnDefinition(GridLength.Star), new ColumnDefinition(GridLength.Star)
+ },
+ ColumnSpacing = 8
+ };
+ grid.Add(_searchButton, 0, 0);
+ grid.Add(_undoButton, 1, 0);
+ grid.Add(_redoButton, 2, 0);
+ grid.Add(_hintButton, 3, 0);
+ return grid;
+ }
+
+ private View BuildSettingsCard()
+ {
+ var heading = SectionHeading("Game settings", "person.fill");
+ var sideCaption = new Label { Text = "Play as", FontSize = 14, VerticalTextAlignment = TextAlignment.Center };
+ var sideButtons = new HorizontalStackLayout { Spacing = 8, Children = { _whiteButton, _blackButton } };
+ var sideRow = new Grid
+ {
+ ColumnDefinitions = { new ColumnDefinition(GridLength.Star), new ColumnDefinition(GridLength.Auto) },
+ Children = { sideCaption, sideButtons }
+ };
+ Grid.SetColumn(sideButtons, 1);
+ var flip = ActionButton("Flip board", "arrow.2.squarepath", () => { _flipped = !_flipped; UpdateBoard(); return Task.CompletedTask; });
+ flip.HorizontalOptions = LayoutOptions.Fill;
+ var eloRow = new Grid
+ {
+ ColumnDefinitions = { new ColumnDefinition(GridLength.Star), new ColumnDefinition(GridLength.Auto) },
+ Children = { new Label { Text = "Human-style level", FontSize = 14 }, _eloValue }
+ };
+ Grid.SetColumn(_eloValue, 1);
+ _eloSlider.MinimumTrackColor = Accent;
+ _eloSlider.ValueChanged += (_, e) =>
+ {
+ var step = (int)Math.Round(e.NewValue);
+ var elo = step == 171 ? 0 : 500 + step * 10;
+ _eloValue.Text = elo == 0 ? "Full strength" : $"≈{elo} Elo";
+ HumanPlay.SetElo(elo);
+ };
+ var stack = new VerticalStackLayout
+ {
+ Spacing = 13,
+ Children = { heading, sideRow, flip, new BoxView { HeightRequest = 1, Color = Separator }, eloRow, _eloSlider }
+ };
+ var card = Card(stack);
+ return card;
+ }
+
+ private View BuildAnalysisCard()
+ {
+ var grid = new Grid
+ {
+ ColumnDefinitions =
+ {
+ new ColumnDefinition(GridLength.Star), new ColumnDefinition(GridLength.Star),
+ new ColumnDefinition(GridLength.Star)
+ },
+ RowDefinitions = { new RowDefinition(GridLength.Auto), new RowDefinition(GridLength.Auto) },
+ ColumnSpacing = 8, RowSpacing = 12
+ };
+ AddStat(grid, "DEPTH", _depth, 0, 0);
+ AddStat(grid, "EVALUATION", _evaluation, 1, 0);
+ AddStat(grid, "TIME", _elapsed, 2, 0);
+ AddStat(grid, "NODES", _nodes, 0, 1);
+ AddStat(grid, "NODES / SEC", _nps, 1, 1);
+ var stack = new VerticalStackLayout
+ {
+ Spacing = 14,
+ Children =
+ {
+ SectionHeading("Analysis", "waveform.path"), grid,
+ new BoxView { HeightRequest = 1, Color = Separator },
+ new Label { Text = "PRINCIPAL VARIATION", FontSize = 10, CharacterSpacing = 1.2, TextColor = SecondaryText },
+ _pv
+ }
+ };
+ return Card(stack);
+ }
+
+ private View BuildMovesCard()
+ {
+ var header = SectionHeading("Moves", "list.number");
+ var moveScroll = new ScrollView { HeightRequest = 156, Content = _moveRows };
+ return Card(new VerticalStackLayout { Spacing = 12, Children = { header, moveScroll } });
+ }
+
+ private View BuildExportRow()
+ {
+ var grid = new Grid
+ {
+ ColumnDefinitions = { new ColumnDefinition(GridLength.Star), new ColumnDefinition(GridLength.Star), new ColumnDefinition(GridLength.Star) },
+ ColumnSpacing = 8
+ };
+ var fen = ActionButton("Copy FEN", "doc.on.doc", CopyFenAsync);
+ var pgn = ActionButton("Copy PGN", "doc.on.doc", CopyPgnAsync);
+ var share = ActionButton("Share PGN", "square.and.arrow.up", SharePgnAsync);
+ grid.Add(fen, 0, 0); grid.Add(pgn, 1, 0); grid.Add(share, 2, 0);
+ return grid;
+ }
+
+ private void BuildBoard()
+ {
+ for (var row = 0; row < 8; row++) _board.RowDefinitions.Add(new RowDefinition(GridLength.Star));
+ for (var col = 0; col < 8; col++) _board.ColumnDefinitions.Add(new ColumnDefinition(GridLength.Star));
+ for (var viewRow = 0; viewRow < 8; viewRow++)
+ for (var viewCol = 0; viewCol < 8; viewCol++)
+ {
+ var row = viewRow;
+ var col = viewCol;
+ var button = new Button
+ {
+ Padding = 0, Margin = 0, CornerRadius = 0, BorderWidth = 0,
+ FontSize = 34,
+ MinimumHeightRequest = 0, MinimumWidthRequest = 0,
+ HorizontalOptions = LayoutOptions.Fill, VerticalOptions = LayoutOptions.Fill
+ };
+ SemanticProperties.SetHint(button, "Double tap to select or move a piece");
+ button.Clicked += async (_, _) => await OnSquareTappedAsync(SquareAt(row, col));
+ _squares[SquareAt(row, col)] = button;
+ _board.Add(button, col, row);
+ var piece = new Image
+ {
+ Aspect = Aspect.AspectFit,
+ Margin = 4,
+ HorizontalOptions = LayoutOptions.Fill,
+ VerticalOptions = LayoutOptions.Fill,
+ InputTransparent = true
+ };
+ _pieces[SquareAt(row, col)] = piece;
+ _board.Add(piece, col, row);
+ }
+ }
+
+ private async void OnLoaded(object? sender, EventArgs e)
+ {
+ if (_engine is not null || _disposed) return;
+ try
+ {
+ await Task.Run(() =>
+ {
+ var entries = TranspositionTableExtensions.CalculateTranspositionTableSize(16);
+ var engine = new ParallelSearcher(entries);
+ engine.SetThreads(1);
+ var game = GameState.InitialState();
+ MainThread.BeginInvokeOnMainThread(() =>
+ {
+ if (_disposed) { engine.Dispose(); game.Dispose(); return; }
+ _engine = engine;
+ _game = game;
+ UpdateBoard();
+ SetStatus(_humanWhite ? "Your move" : "Sapling to move");
+ UpdateControls();
+ if (!_humanWhite) _ = StartAiMoveAsync();
+ });
+ });
+ }
+ catch (Exception ex)
+ {
+ SetStatus($"Engine unavailable: {ex.Message}");
+ }
+ }
+
+ private void OnUnloaded(object? sender, EventArgs e)
+ {
+ if (_disposed) return;
+ _disposed = true;
+ _engine?.Stop();
+ _engine?.Dispose();
+ _game?.Dispose();
+ _engine = null;
+ _game = null;
+ }
+
+ private async Task OnSquareTappedAsync(int square)
+ {
+ if (_game is null || _thinking || _hinting || _restoring || IsGameOver() || IsEngineTurn()) return;
+ var legal = _game.LegalMoves;
+ if (_selectedSquare is null)
+ {
+ SelectIfMovable(square, legal);
+ return;
+ }
+ if (_selectedSquare == square) { ClearSelection(); return; }
+ var candidates = legal.Where(m => m.GetFromSquare() == _selectedSquare && m.GetToSquare() == square).ToArray();
+ if (candidates.Length == 0)
+ {
+ SelectIfMovable(square, legal);
+ return;
+ }
+ uint move = candidates[0];
+ if (candidates.Length > 1)
+ {
+ var choice = await DisplayActionSheetAsync("Promote pawn to", "Cancel", null, "Queen", "Rook", "Bishop", "Knight");
+ if (choice == "Cancel" || choice is null) return;
+ var suffix = choice switch { "Rook" => "r", "Bishop" => "b", "Knight" => "n", _ => "q" };
+ move = candidates.First(m => m.ToUciMoveName().EndsWith(suffix, StringComparison.Ordinal));
+ }
+ await PlayMoveAsync(move, isHuman: true);
+ }
+
+ private void SelectIfMovable(int square, List legal)
+ {
+ if (_game is null) return;
+ var ownColor = _game.Board.WhiteToMove == _humanWhite;
+ if (!ownColor) return;
+ if (legal.Any(m => m.GetFromSquare() == square))
+ {
+ _selectedSquare = square;
+ _targets = legal.Where(m => m.GetFromSquare() == square).Select(m => (int)m.GetToSquare()).ToHashSet();
+ UpdateBoard();
+ if (_hintMode) _ = ScoreHintsAsync();
+ }
+ }
+
+ private async Task PlayMoveAsync(uint move, bool isHuman)
+ {
+ if (_game is null) return;
+ var from = (int)move.GetFromSquare();
+ var to = (int)move.GetToSquare();
+ var isCastle = move.GetMoveType() == (byte)MoveType.Castle;
+ var captured = move.GetCapturedPiece();
+ _history.Add(move.ToUciMoveName());
+ _moveLabels.Add(move.ToPgnMoveName());
+ if (captured != Constants.None)
+ _captured.Add((PieceValueType(captured), _game.Board.WhiteToMove));
+ _redo.Clear();
+ _game.Apply(move);
+ ClearSelection(false);
+ UpdateBoard();
+ await AnimateBoardMoveAsync(from, to, isCastle);
+ UpdateMoveList();
+ UpdateControls();
+ UpdateTerminalStatus();
+ if (!_game.GameOver() && isHuman) await StartAiMoveAsync();
+ }
+
+ private async Task AnimateBoardMoveAsync(int from, int to, bool isCastle)
+ {
+#if IOS
+ if (UIKit.UIAccessibility.IsReduceMotionEnabled) return;
+#endif
+ var distance = _board.Width / 8;
+ if (distance <= 0) return;
+ var renderVersion = _boardRenderVersion;
+ var moves = new List { AnimatePieceAsync(from, to, distance, renderVersion) };
+ if (isCastle)
+ {
+ var rank = from / 8;
+ var kingSide = to > from;
+ var rookFrom = rank * 8 + (kingSide ? 7 : 0);
+ var rookTo = rank * 8 + (kingSide ? 5 : 3);
+ moves.Add(AnimatePieceAsync(rookFrom, rookTo, distance, renderVersion));
+ }
+ await Task.WhenAll(moves);
+ }
+
+ private async Task AnimatePieceAsync(int from, int destination, double cellSize, int renderVersion)
+ {
+ var destinationPiece = _pieces[destination];
+ if (!destinationPiece.IsVisible || destinationPiece.Source is null) return;
+ var (fromRow, fromCol) = ViewPosition(from);
+ var (toRow, toCol) = ViewPosition(destination);
+ var deltaX = (toCol - fromCol) * cellSize;
+ var deltaY = (toRow - fromRow) * cellSize;
+ var imageSize = cellSize * 0.8;
+ var movingPiece = new Image
+ {
+ Source = destinationPiece.Source,
+ Aspect = Aspect.AspectFit,
+ InputTransparent = true
+ };
+ AbsoluteLayout.SetLayoutBounds(movingPiece, new Rect(
+ fromCol * cellSize + cellSize * 0.1,
+ fromRow * cellSize + cellSize * 0.1,
+ imageSize,
+ imageSize));
+ _animationOverlay.Add(movingPiece);
+ destinationPiece.IsVisible = false;
+ var fileChange = Math.Abs(from % 8 - destination % 8);
+ var rankChange = Math.Abs(from / 8 - destination / 8);
+ var isKnightMove = (fileChange == 1 && rankChange == 2) || (fileChange == 2 && rankChange == 1);
+ try
+ {
+ if (isKnightMove)
+ {
+ await movingPiece.TranslateToAsync(0, deltaY, 240, Easing.CubicInOut);
+ await movingPiece.TranslateToAsync(deltaX, deltaY, 120, Easing.CubicInOut);
+ }
+ else
+ {
+ await movingPiece.TranslateToAsync(deltaX, deltaY, 360, Easing.CubicInOut);
+ }
+ }
+ finally
+ {
+ movingPiece.CancelAnimations();
+ _animationOverlay.Remove(movingPiece);
+ if (renderVersion == _boardRenderVersion) destinationPiece.IsVisible = true;
+ }
+ }
+
+ private (int Row, int Col) ViewPosition(int square)
+ {
+ for (var row = 0; row < 8; row++)
+ for (var col = 0; col < 8; col++)
+ if (SquareAt(row, col) == square) return (row, col);
+ return (0, 0);
+ }
+
+ private async Task StartAiMoveAsync()
+ {
+ var session = _engine;
+ var game = _game;
+ if (game is null || session is null || _thinking || IsGameOver()) return;
+ _thinking = true;
+ _searchButton.Text = "Stop";
+ _searchButton.Clicked -= SearchButtonNewGameClicked;
+ _searchButton.Clicked += SearchButtonStopClicked;
+ SetStatus("Sapling is thinking…");
+ UpdateControls();
+ _searchClock.Restart();
+ _depth.Text = "0"; _evaluation.Text = "–"; _elapsed.Text = "0.0s"; _nodes.Text = "0"; _nps.Text = "0"; _pv.Text = "–";
+ var positionVersion = _positionVersion;
+ _cancelSearch = false;
+ var searchWork = Task.Run(() =>
+ {
+ Searcher.ResumableResult result = default;
+ try
+ {
+ session.BeginResumableSearch(game);
+ var total = Stopwatch.StartNew();
+ while (!result.Done && !_cancelSearch && total.ElapsedMilliseconds < 1500 && result.TotalNodes < 4_000_000)
+ {
+ result = session.ResumableSlice(40, 12_000, 45);
+ var progress = result;
+ MainThread.BeginInvokeOnMainThread(() => UpdateSearchStats(progress, game.Board.WhiteToMove));
+ if (!result.Done) Thread.Yield();
+ }
+ if (!result.Done) { session.Stop(); result = session.ResumableSlice(40, 1, 10); }
+ }
+ finally
+ {
+ session.EndResumableSearch();
+ }
+
+ uint selectedMove = 0;
+ if (!_cancelSearch && result.BestMove != 0)
+ {
+ if (HumanPlay.Enabled)
+ {
+ var ranked = session.RankRootMoves(game, HumanPlay.RankDepth);
+ if (ranked.Count > 0)
+ {
+ var board = game.Board;
+ var selection = HumanPlay.SelectMove(_humanRng, ref board, ranked);
+ selectedMove = selection.Move;
+ result = result with
+ {
+ Depth = HumanPlay.RankDepth,
+ Score = ranked[selection.Rank].Score,
+ BestMove = selection.Move,
+ Pv = [selection.Move]
+ };
+ }
+ }
+ else
+ {
+ selectedMove = result.BestMove;
+ }
+ }
+ return (Result: result, SelectedMove: selectedMove);
+ });
+ _searchTask = searchWork;
+ Searcher.ResumableResult final;
+ uint selectedMove;
+ try
+ {
+ var completed = await searchWork;
+ final = completed.Result;
+ selectedMove = completed.SelectedMove;
+ }
+ catch (Exception ex)
+ {
+ SetStatus($"Search failed: {ex.Message}");
+ final = default;
+ selectedMove = 0;
+ }
+ _searchTask = null;
+ _searchClock.Stop();
+ if (_disposed || positionVersion != _positionVersion)
+ {
+ _thinking = false;
+ ResetSearchButton();
+ return;
+ }
+ UpdateSearchStats(final, game.Board.WhiteToMove);
+ _thinking = false;
+ ResetSearchButton();
+ if (!_cancelSearch && selectedMove != 0)
+ await PlayMoveAsync(selectedMove, isHuman: false);
+ else
+ {
+ SetStatus(IsGameOver() ? TerminalStatus() : "Search stopped");
+ UpdateControls();
+ }
+ }
+
+ private void UpdateSearchStats(Searcher.ResumableResult result, bool whiteToMove)
+ {
+ if (_disposed || !_thinking) return;
+ _depth.Text = result.Depth.ToString(CultureInfo.InvariantCulture);
+ _evaluation.Text = FormatEvaluation(result.Score, whiteToMove);
+ _elapsed.Text = _searchClock.Elapsed.TotalSeconds.ToString("F1", CultureInfo.InvariantCulture) + "s";
+ _nodes.Text = result.TotalNodes.ToString("N0", CultureInfo.CurrentCulture);
+ _nps.Text = (_searchClock.Elapsed.TotalSeconds > 0 ? result.TotalNodes / _searchClock.Elapsed.TotalSeconds : 0).ToString("N0", CultureInfo.CurrentCulture);
+ _pv.Text = result.Pv.Count == 0 ? "–" : string.Join(" ", result.Pv.Select(m => m.ToUciMoveName()));
+ }
+
+ private async Task NewGameAsync()
+ {
+ _positionVersion++;
+ await StopSearchAsync();
+ if (_game is null) return;
+ _game.ResetToFen(InitialFen);
+ _history.Clear(); _moveLabels.Clear(); _captured.Clear(); _redo.Clear();
+ ClearSelection(false);
+ ResetStats();
+ UpdateBoard(); UpdateMoveList(); UpdateControls();
+ SetStatus(_humanWhite ? "Your move" : "Sapling to move");
+ if (!_humanWhite) await StartAiMoveAsync();
+ }
+
+ private async Task UndoAsync()
+ {
+ if (_game is null || _history.Count == 0 || _restoring) return;
+ if (_thinking) await StopSearchAsync();
+ var count = _history.Count > 1 && !IsEngineTurn() ? 2 : 1;
+ count = Math.Min(count, _history.Count);
+ var removed = _history.TakeLast(count).ToArray();
+ _redo.Push(removed);
+ _history.RemoveRange(_history.Count - count, count);
+ _moveLabels.RemoveRange(_moveLabels.Count - count, count);
+ await RestoreHistoryAsync();
+ }
+
+ private async Task RedoAsync()
+ {
+ if (_game is null || _redo.Count == 0 || _restoring) return;
+ _history.AddRange(_redo.Pop());
+ await RestoreHistoryAsync();
+ }
+
+ private async Task RestoreHistoryAsync()
+ {
+ var game = _game;
+ if (game is null) return;
+ _restoring = true;
+ SetStatus("Restoring position…");
+ game.ResetToFen(InitialFen);
+ _captured.Clear();
+ _moveLabels.Clear();
+ foreach (var uci in _history)
+ {
+ var move = game.LegalMoves.FirstOrDefault(m => m.ToUciMoveName() == uci);
+ if (move == 0) break;
+ _moveLabels.Add(move.ToPgnMoveName());
+ var captured = move.GetCapturedPiece();
+ if (captured != Constants.None) _captured.Add((PieceValueType(captured), game.Board.WhiteToMove));
+ game.Apply(move);
+ }
+ _restoring = false;
+ ClearSelection(false);
+ UpdateBoard(); UpdateMoveList(); UpdateControls(); UpdateTerminalStatus();
+ if (!game.GameOver() && IsEngineTurn()) await StartAiMoveAsync();
+ }
+
+ private async Task StopSearchAsync()
+ {
+ if (!_thinking || _engine is null) return;
+ _cancelSearch = true;
+ _engine.Stop();
+ var pending = _searchTask;
+ if (pending is not null)
+ {
+ try { await pending; }
+ catch { }
+ await Task.Delay(30);
+ }
+ }
+
+ private async Task ChangeSideAsync(bool white)
+ {
+ _humanWhite = white;
+ _whiteButton.BackgroundColor = white ? Accent : Surface2;
+ _whiteButton.TextColor = PrimaryText;
+ _blackButton.BackgroundColor = white ? Surface2 : Accent;
+ _blackButton.TextColor = PrimaryText;
+ await NewGameAsync();
+ }
+
+ private async Task ToggleHintsAsync()
+ {
+ _hintMode = !_hintMode;
+ _hintButton.Text = _hintMode ? "Hints On" : "Hints Off";
+ _hintButton.BackgroundColor = _hintMode ? Accent : Surface2;
+ _hintButton.TextColor = PrimaryText;
+ _hintScores.Clear();
+ UpdateBoard();
+ if (_hintMode && _selectedSquare.HasValue) await ScoreHintsAsync();
+ }
+
+ private async Task ScoreHintsAsync()
+ {
+ var game = _game;
+ var engine = _engine;
+ if (game is null || engine is null || !_selectedSquare.HasValue || _thinking || _hinting || _restoring) return;
+ var legal = game.LegalMoves.Where(m => m.GetFromSquare() == _selectedSquare.Value).ToArray();
+ if (legal.Length == 0) return;
+ _hinting = true;
+ UpdateControls();
+ SetStatus("Scoring candidate moves…");
+ try
+ {
+ var scores = await Task.Run(() => engine.RankRootMoves(game, 4));
+ _hintScores = scores.ToDictionary(s => s.Move.ToUciMoveName(), s => s.Score, StringComparer.Ordinal);
+ UpdateBoard();
+ }
+ catch (Exception ex) { SetStatus($"Hint search failed: {ex.Message}"); }
+ finally
+ {
+ _hinting = false;
+ UpdateControls();
+ if (!_thinking) SetStatus(game.Board.InCheck ? "Your move · check" : "Your move");
+ }
+ }
+
+ private async Task CopyFenAsync()
+ {
+ if (_game is null) return;
+ await Clipboard.Default.SetTextAsync(_game.Board.ToFen());
+ SetStatus("FEN copied");
+ }
+
+ private async Task CopyPgnAsync()
+ {
+ if (_game is null) return;
+ await Clipboard.Default.SetTextAsync(_game.ToPgn());
+ SetStatus("PGN copied");
+ }
+
+ private async Task SharePgnAsync()
+ {
+ if (_game is null) return;
+ await Share.Default.RequestAsync(new ShareTextRequest { Title = "Sapling game", Text = _game.ToPgn() });
+ }
+
+ private void UpdateBoard()
+ {
+ _boardRenderVersion++;
+ foreach (var movingPiece in _animationOverlay.Children.OfType()) movingPiece.CancelAnimations();
+ _animationOverlay.Children.Clear();
+ var fen = _game is null ? InitialFen : _game.Board.ToFen();
+ var placement = fen.Split(' ')[0].Split('/');
+ var pieces = new char[64];
+ for (var fenRow = 0; fenRow < 8; fenRow++)
+ {
+ var file = 0;
+ foreach (var c in placement[fenRow])
+ {
+ if (char.IsDigit(c)) file += c - '0';
+ else pieces[(7 - fenRow) * 8 + file++] = c;
+ }
+ }
+ var legal = _game?.LegalMoves ?? [];
+ var lastMove = _history.Count == 0 ? null : _history[^1];
+ var checkedSquare = _game is { } game && game.Board.InCheck
+ ? (game.Board.WhiteToMove ? game.Board.WhiteKingSquare : game.Board.BlackKingSquare)
+ : -1;
+ for (var row = 0; row < 8; row++)
+ for (var col = 0; col < 8; col++)
+ {
+ var square = SquareAt(row, col);
+ var button = _squares[square];
+ var piece = pieces[square];
+ button.Text = "";
+ button.TextColor = Color.FromArgb("#1C1C1E");
+ button.FontSize = Math.Max(10, Math.Min(18, Width / 24));
+ var pieceImage = _pieces[square];
+ pieceImage.Source = PieceImage(piece);
+ pieceImage.IsVisible = piece != '\0';
+ var light = ((square % 8) + (square / 8)) % 2 == 1;
+ var color = light ? LightSquare : DarkSquare;
+ if (_targets.Contains(square)) color = Color.FromArgb("#397548");
+ if (_selectedSquare == square) color = Color.FromArgb("#8C811A");
+ if (lastMove is { Length: >= 4 } && (SquareFrom(lastMove[..2]) == square || SquareFrom(lastMove.Substring(2, 2)) == square))
+ color = light ? Color.FromArgb("#B6C8A5") : Color.FromArgb("#789273");
+ if (checkedSquare == square) color = Color.FromArgb("#A93D3A");
+ button.BackgroundColor = color;
+ var label = SquareName(square);
+ var candidate = legal.FirstOrDefault(m => m.GetToSquare() == square && _selectedSquare.HasValue && m.GetFromSquare() == _selectedSquare.Value);
+ button.Text = piece == '\0' && _targets.Contains(square) ? "·" : "";
+ if (_hintMode && candidate != 0 && _hintScores.TryGetValue(candidate.ToUciMoveName(), out var hintScore))
+ button.Text = piece == '\0' ? FormatHintScore(hintScore) : "";
+ SemanticProperties.SetDescription(button, $"{label}, {(piece == '\0' ? "empty" : PieceName(piece))}");
+ SemanticProperties.SetHint(button, row == 7 ? $"File {label[0]}. Double tap to select or move." : "Double tap to select or move.");
+ }
+ _moveCount.Text = $"{_history.Count} {(_history.Count == 1 ? "move" : "moves")}";
+ _material.Text = MaterialSummary();
+ UpdateControls();
+ }
+
+ private void UpdateMoveList()
+ {
+ _moveRows.Children.Clear();
+ for (var index = 0; index < _history.Count; index += 2)
+ {
+ var white = _moveLabels[index];
+ var black = index + 1 < _moveLabels.Count ? _moveLabels[index + 1] : "";
+ var row = new Grid { ColumnDefinitions = { new ColumnDefinition(new GridLength(40)), new ColumnDefinition(GridLength.Star), new ColumnDefinition(GridLength.Star) }, Padding = new Thickness(2, 3) };
+ row.Add(new Label { Text = $"{index / 2 + 1}.", TextColor = SecondaryText, FontSize = 13 }, 0, 0);
+ row.Add(new Label { Text = white, FontSize = 14 }, 1, 0);
+ row.Add(new Label { Text = black, FontSize = 14 }, 2, 0);
+ _moveRows.Children.Add(row);
+ }
+ }
+
+ private string MaterialSummary()
+ {
+ var balance = _captured.Sum(c => c.WhiteCaptured ? c.Value : -c.Value);
+ return balance == 0 ? "Material even" : balance > 0 ? $"White +{balance}" : $"Black +{Math.Abs(balance)}";
+ }
+
+ private void UpdateControls()
+ {
+ var canEdit = _game is not null && !_thinking && !_hinting && !_restoring;
+ _undoButton.IsEnabled = canEdit && _history.Count > 0;
+ _redoButton.IsEnabled = canEdit && _redo.Count > 0;
+ _hintButton.IsEnabled = canEdit && !IsGameOver();
+ _whiteButton.IsEnabled = canEdit;
+ _blackButton.IsEnabled = canEdit;
+ _eloSlider.IsEnabled = canEdit;
+ _searchButton.IsEnabled = _game is not null && !_restoring && !_hinting;
+ }
+
+ private void UpdateTerminalStatus()
+ {
+ if (_game?.GameOver() == true) SetStatus(TerminalStatus());
+ else SetStatus(_game?.Board.InCheck == true ? (IsEngineTurn() ? "Sapling to move · check" : "Your move · check") : IsEngineTurn() ? "Sapling to move" : "Your move");
+ }
+
+ private string TerminalStatus()
+ {
+ if (_game is null) return "Game over";
+ if (_game.LegalMoves.Count == 0) return _game.Board.WhiteToMove ? "Checkmate · Black wins" : "Checkmate · White wins";
+ return "Draw";
+ }
+
+ private bool IsGameOver() => _game?.GameOver() ?? false;
+ private bool IsEngineTurn() => _game is not null && _game.Board.WhiteToMove != _humanWhite;
+
+ private void ResetSearchButton()
+ {
+ _searchButton.Clicked -= SearchButtonStopClicked;
+ _searchButton.Clicked -= SearchButtonNewGameClicked;
+ _searchButton.Text = "New game";
+ _searchButton.Clicked += SearchButtonNewGameClicked;
+ UpdateControls();
+ }
+
+ private async void SearchButtonStopClicked(object? sender, EventArgs e)
+ {
+ if (_engine is null) return;
+ _engine.Stop();
+ if (_searchTask is not null) { try { await _searchTask; } catch { } }
+ }
+ private async void SearchButtonNewGameClicked(object? sender, EventArgs e) => await NewGameAsync();
+
+ private void ResetStats()
+ {
+ _depth.Text = _evaluation.Text = _elapsed.Text = _nodes.Text = _nps.Text = "–";
+ _pv.Text = "–";
+ }
+
+ private void ClearSelection(bool refresh = true)
+ {
+ _selectedSquare = null;
+ _targets.Clear();
+ _hintScores.Clear();
+ if (refresh) UpdateBoard();
+ }
+
+ private void SetStatus(string text)
+ {
+ _status.Text = text;
+ SemanticScreenReader.Announce(text);
+ }
+
+ private void ApplyTheme()
+ {
+ BackgroundColor = Canvas;
+ _root.BackgroundColor = BackgroundColor;
+ _status.TextColor = PrimaryText;
+ if (_game is not null) UpdateBoard();
+ }
+
+ private View Card(View content)
+ {
+ var card = new Border
+ {
+ Padding = 12,
+ StrokeThickness = 0,
+ StrokeShape = new Microsoft.Maui.Controls.Shapes.RoundRectangle { CornerRadius = 20 },
+ Content = content
+ };
+ card.BackgroundColor = Surface;
+ return card;
+ }
+
+ private Label SectionHeading(string text, string symbol)
+ {
+ var label = new Label { Text = text, FontSize = 17, FontAttributes = FontAttributes.Bold };
+ SemanticProperties.SetHeadingLevel(label, SemanticHeadingLevel.Level2);
+ return label;
+ }
+
+ private Button ActionButton(string text, string symbol, Func action, bool primary = false)
+ {
+ _ = symbol;
+ var button = new Button
+ {
+ Text = text, FontSize = 12, Padding = new Thickness(5, 8), CornerRadius = 12,
+ BackgroundColor = primary ? Accent : Surface2,
+ TextColor = primary ? Colors.White : PrimaryText,
+ HorizontalOptions = LayoutOptions.Fill, VerticalOptions = LayoutOptions.Center,
+ LineBreakMode = LineBreakMode.TailTruncation, MinimumHeightRequest = 46
+ };
+ button.Clicked += async (_, _) => await action();
+ return button;
+ }
+
+ private static string? PieceImage(char piece) => piece switch
+ {
+ 'K' => "white_king.svg", 'Q' => "white_queen.svg", 'R' => "white_rook.svg",
+ 'B' => "white_bishop.svg", 'N' => "white_knight.svg", 'P' => "white_pawn.svg",
+ 'k' => "black_king.svg", 'q' => "black_queen.svg", 'r' => "black_rook.svg",
+ 'b' => "black_bishop.svg", 'n' => "black_knight.svg", 'p' => "black_pawn.svg",
+ _ => null
+ };
+
+ private static void AddStat(Grid grid, string caption, Label value, int column, int row)
+ {
+ var stack = new VerticalStackLayout { Spacing = 3 };
+ stack.Children.Add(new Label { Text = caption, FontSize = 9, CharacterSpacing = 1, TextColor = SecondaryText });
+ value.FontSize = 16;
+ value.FontAttributes = FontAttributes.Bold;
+ stack.Children.Add(value);
+ grid.Add(stack, column, row);
+ }
+
+ private int SquareAt(int viewRow, int viewCol) => _flipped
+ ? viewRow * 8 + (7 - viewCol)
+ : (7 - viewRow) * 8 + viewCol;
+
+ private static string SquareName(int square) => $"{(char)('a' + square % 8)}{square / 8 + 1}";
+ private static int SquareFrom(string square) => (square[1] - '1') * 8 + square[0] - 'a';
+
+ private static string PieceName(char piece) => char.ToLowerInvariant(piece) switch
+ {
+ 'k' => "king", 'q' => "queen", 'r' => "rook", 'b' => "bishop", 'n' => "knight", 'p' => "pawn", _ => "piece"
+ };
+
+ private static int PieceValueType(byte piece) => (piece & 0x0F) switch
+ {
+ Constants.WhitePawn or Constants.BlackPawn => 1,
+ Constants.WhiteKnight or Constants.BlackKnight => 3,
+ Constants.WhiteBishop or Constants.BlackBishop => 3,
+ Constants.WhiteRook or Constants.BlackRook => 5,
+ Constants.WhiteQueen or Constants.BlackQueen => 9,
+ _ => 0
+ };
+
+ private static string FormatEvaluation(int score, bool whiteToMove)
+ {
+ var signed = whiteToMove ? score : -score;
+ if (MoveScoring.IsMateScore(signed))
+ {
+ var mate = MoveScoring.GetMateDistance(signed);
+ return signed > 0 ? $"M{mate}" : $"−M{mate}";
+ }
+ return (signed / 100.0).ToString("+0.00;-0.00;0.00", CultureInfo.InvariantCulture);
+ }
+
+ private static string FormatHintScore(int score)
+ {
+ if (MoveScoring.IsMateScore(score))
+ {
+ var mate = MoveScoring.GetMateDistance(score);
+ return score > 0 ? $"M{mate}" : $"−M{mate}";
+ }
+ return (score / 100.0).ToString("+0.0;-0.0;0.0", CultureInfo.InvariantCulture);
+ }
+}
diff --git a/src/Sapling.Mobile/MauiProgram.cs b/src/Sapling.Mobile/MauiProgram.cs
new file mode 100644
index 0000000..9cbdbf6
--- /dev/null
+++ b/src/Sapling.Mobile/MauiProgram.cs
@@ -0,0 +1,18 @@
+using Microsoft.Extensions.Logging;
+
+namespace Sapling.Mobile;
+
+public static class MauiProgram
+{
+ public static MauiApp CreateMauiApp()
+ {
+ var builder = MauiApp.CreateBuilder();
+ builder.UseMauiApp();
+
+#if DEBUG
+ builder.Logging.AddDebug();
+#endif
+
+ return builder.Build();
+ }
+}
diff --git a/src/Sapling.Mobile/Platforms/Android/AndroidManifest.xml b/src/Sapling.Mobile/Platforms/Android/AndroidManifest.xml
new file mode 100644
index 0000000..e0ea348
--- /dev/null
+++ b/src/Sapling.Mobile/Platforms/Android/AndroidManifest.xml
@@ -0,0 +1,4 @@
+
+
+
+
diff --git a/src/Sapling.Mobile/Platforms/Android/MainActivity.cs b/src/Sapling.Mobile/Platforms/Android/MainActivity.cs
new file mode 100644
index 0000000..b559ebe
--- /dev/null
+++ b/src/Sapling.Mobile/Platforms/Android/MainActivity.cs
@@ -0,0 +1,10 @@
+using Android.App;
+using Android.Content.PM;
+using Android.OS;
+
+namespace Sapling.Mobile;
+
+[Activity(Theme = "@style/Maui.SplashTheme", MainLauncher = true, LaunchMode = LaunchMode.SingleTop, ConfigurationChanges = ConfigChanges.ScreenSize | ConfigChanges.Orientation | ConfigChanges.UiMode | ConfigChanges.ScreenLayout | ConfigChanges.SmallestScreenSize | ConfigChanges.Density)]
+public class MainActivity : MauiAppCompatActivity
+{
+}
diff --git a/src/Sapling.Mobile/Platforms/Android/MainApplication.cs b/src/Sapling.Mobile/Platforms/Android/MainApplication.cs
new file mode 100644
index 0000000..b81295b
--- /dev/null
+++ b/src/Sapling.Mobile/Platforms/Android/MainApplication.cs
@@ -0,0 +1,15 @@
+using Android.App;
+using Android.Runtime;
+
+namespace Sapling.Mobile;
+
+[Application]
+public class MainApplication : MauiApplication
+{
+ public MainApplication(IntPtr handle, JniHandleOwnership ownership)
+ : base(handle, ownership)
+ {
+ }
+
+ protected override MauiApp CreateMauiApp() => MauiProgram.CreateMauiApp();
+}
diff --git a/src/Sapling.Mobile/Platforms/Android/Resources/values/colors.xml b/src/Sapling.Mobile/Platforms/Android/Resources/values/colors.xml
new file mode 100644
index 0000000..f26fc3e
--- /dev/null
+++ b/src/Sapling.Mobile/Platforms/Android/Resources/values/colors.xml
@@ -0,0 +1,6 @@
+
+
+ #4B8067
+ #2E5A45
+ #2E5A45
+
diff --git a/src/Sapling.Mobile/Platforms/iOS/AppDelegate.cs b/src/Sapling.Mobile/Platforms/iOS/AppDelegate.cs
new file mode 100644
index 0000000..6c6ac91
--- /dev/null
+++ b/src/Sapling.Mobile/Platforms/iOS/AppDelegate.cs
@@ -0,0 +1,9 @@
+using Foundation;
+
+namespace Sapling.Mobile;
+
+[Register("AppDelegate")]
+public class AppDelegate : MauiUIApplicationDelegate
+{
+ protected override MauiApp CreateMauiApp() => MauiProgram.CreateMauiApp();
+}
diff --git a/src/Sapling.Mobile/Platforms/iOS/Info.plist b/src/Sapling.Mobile/Platforms/iOS/Info.plist
new file mode 100644
index 0000000..0004a4f
--- /dev/null
+++ b/src/Sapling.Mobile/Platforms/iOS/Info.plist
@@ -0,0 +1,32 @@
+
+
+
+
+ LSRequiresIPhoneOS
+
+ UIDeviceFamily
+
+ 1
+ 2
+
+ UIRequiredDeviceCapabilities
+
+ arm64
+
+ UISupportedInterfaceOrientations
+
+ UIInterfaceOrientationPortrait
+ UIInterfaceOrientationLandscapeLeft
+ UIInterfaceOrientationLandscapeRight
+
+ UISupportedInterfaceOrientations~ipad
+
+ UIInterfaceOrientationPortrait
+ UIInterfaceOrientationPortraitUpsideDown
+ UIInterfaceOrientationLandscapeLeft
+ UIInterfaceOrientationLandscapeRight
+
+ XSAppIconAssets
+ Assets.xcassets/appicon.appiconset
+
+
diff --git a/src/Sapling.Mobile/Platforms/iOS/Program.cs b/src/Sapling.Mobile/Platforms/iOS/Program.cs
new file mode 100644
index 0000000..6aee5a6
--- /dev/null
+++ b/src/Sapling.Mobile/Platforms/iOS/Program.cs
@@ -0,0 +1,15 @@
+using ObjCRuntime;
+using UIKit;
+
+namespace Sapling.Mobile;
+
+public class Program
+{
+ // This is the main entry point of the application.
+ static void Main(string[] args)
+ {
+ // if you want to use a different Application Delegate class from "AppDelegate"
+ // you can specify it here.
+ UIApplication.Main(args, null, typeof(AppDelegate));
+ }
+}
diff --git a/src/Sapling.Mobile/Platforms/iOS/Resources/PrivacyInfo.xcprivacy b/src/Sapling.Mobile/Platforms/iOS/Resources/PrivacyInfo.xcprivacy
new file mode 100644
index 0000000..24ab3b4
--- /dev/null
+++ b/src/Sapling.Mobile/Platforms/iOS/Resources/PrivacyInfo.xcprivacy
@@ -0,0 +1,51 @@
+
+
+
+
+
+ NSPrivacyAccessedAPITypes
+
+
+ NSPrivacyAccessedAPIType
+ NSPrivacyAccessedAPICategoryFileTimestamp
+ NSPrivacyAccessedAPITypeReasons
+
+ C617.1
+
+
+
+ NSPrivacyAccessedAPIType
+ NSPrivacyAccessedAPICategorySystemBootTime
+ NSPrivacyAccessedAPITypeReasons
+
+ 35F9.1
+
+
+
+ NSPrivacyAccessedAPIType
+ NSPrivacyAccessedAPICategoryDiskSpace
+ NSPrivacyAccessedAPITypeReasons
+
+ E174.1
+
+
+
+
+
+
diff --git a/src/Sapling.Mobile/README.md b/src/Sapling.Mobile/README.md
new file mode 100644
index 0000000..8b74468
--- /dev/null
+++ b/src/Sapling.Mobile/README.md
@@ -0,0 +1,22 @@
+# Sapling Mobile
+
+Native .NET MAUI app for Android and iOS. The app references `Sapling.Engine` directly and
+runs searches locally on the device. It has no WebView, backend dependency, or network
+permission.
+
+## Build
+
+Install the .NET MAUI workload for the SDK pinned by the repository, then build a platform:
+
+```sh
+dotnet workload install maui
+dotnet build src/Sapling.Mobile/Sapling.Mobile.csproj -c Release -f net10.0-android
+dotnet build src/Sapling.Mobile/Sapling.Mobile.csproj -c Release -f net10.0-ios
+```
+
+The iOS build requires Xcode. Device signing is configured by the local Xcode environment.
+
+The app starts a single engine worker with a 16 MiB transposition table. Search is driven in
+bounded slices so the UI stays responsive and can show depth, score, time, nodes, speed, and
+the current principal variation. The board, game controls, analysis, and export actions are
+native MAUI views.
diff --git a/src/Sapling.Mobile/Resources/AppIcon/appicon.svg b/src/Sapling.Mobile/Resources/AppIcon/appicon.svg
new file mode 100644
index 0000000..6ee4094
--- /dev/null
+++ b/src/Sapling.Mobile/Resources/AppIcon/appicon.svg
@@ -0,0 +1,4 @@
+
+
diff --git a/src/Sapling.Mobile/Resources/AppIcon/appiconfg.png b/src/Sapling.Mobile/Resources/AppIcon/appiconfg.png
new file mode 100644
index 0000000..0786dd5
Binary files /dev/null and b/src/Sapling.Mobile/Resources/AppIcon/appiconfg.png differ
diff --git a/src/Sapling.Mobile/Resources/Images/black_bishop.svg b/src/Sapling.Mobile/Resources/Images/black_bishop.svg
new file mode 100644
index 0000000..b2aeb13
--- /dev/null
+++ b/src/Sapling.Mobile/Resources/Images/black_bishop.svg
@@ -0,0 +1 @@
+
\ No newline at end of file
diff --git a/src/Sapling.Mobile/Resources/Images/black_king.svg b/src/Sapling.Mobile/Resources/Images/black_king.svg
new file mode 100644
index 0000000..a726621
--- /dev/null
+++ b/src/Sapling.Mobile/Resources/Images/black_king.svg
@@ -0,0 +1 @@
+
\ No newline at end of file
diff --git a/src/Sapling.Mobile/Resources/Images/black_knight.svg b/src/Sapling.Mobile/Resources/Images/black_knight.svg
new file mode 100644
index 0000000..0bf9be8
--- /dev/null
+++ b/src/Sapling.Mobile/Resources/Images/black_knight.svg
@@ -0,0 +1 @@
+
\ No newline at end of file
diff --git a/src/Sapling.Mobile/Resources/Images/black_pawn.svg b/src/Sapling.Mobile/Resources/Images/black_pawn.svg
new file mode 100644
index 0000000..e97fce6
--- /dev/null
+++ b/src/Sapling.Mobile/Resources/Images/black_pawn.svg
@@ -0,0 +1 @@
+
\ No newline at end of file
diff --git a/src/Sapling.Mobile/Resources/Images/black_queen.svg b/src/Sapling.Mobile/Resources/Images/black_queen.svg
new file mode 100644
index 0000000..cb352ff
--- /dev/null
+++ b/src/Sapling.Mobile/Resources/Images/black_queen.svg
@@ -0,0 +1 @@
+
\ No newline at end of file
diff --git a/src/Sapling.Mobile/Resources/Images/black_rook.svg b/src/Sapling.Mobile/Resources/Images/black_rook.svg
new file mode 100644
index 0000000..5ce91a9
--- /dev/null
+++ b/src/Sapling.Mobile/Resources/Images/black_rook.svg
@@ -0,0 +1 @@
+
\ No newline at end of file
diff --git a/src/Sapling.Mobile/Resources/Images/sapling_logo.png b/src/Sapling.Mobile/Resources/Images/sapling_logo.png
new file mode 100644
index 0000000..52e6420
Binary files /dev/null and b/src/Sapling.Mobile/Resources/Images/sapling_logo.png differ
diff --git a/src/Sapling.Mobile/Resources/Images/white_bishop.svg b/src/Sapling.Mobile/Resources/Images/white_bishop.svg
new file mode 100644
index 0000000..16fc2ea
--- /dev/null
+++ b/src/Sapling.Mobile/Resources/Images/white_bishop.svg
@@ -0,0 +1 @@
+
\ No newline at end of file
diff --git a/src/Sapling.Mobile/Resources/Images/white_king.svg b/src/Sapling.Mobile/Resources/Images/white_king.svg
new file mode 100644
index 0000000..a21a5eb
--- /dev/null
+++ b/src/Sapling.Mobile/Resources/Images/white_king.svg
@@ -0,0 +1 @@
+
\ No newline at end of file
diff --git a/src/Sapling.Mobile/Resources/Images/white_knight.svg b/src/Sapling.Mobile/Resources/Images/white_knight.svg
new file mode 100644
index 0000000..9650e74
--- /dev/null
+++ b/src/Sapling.Mobile/Resources/Images/white_knight.svg
@@ -0,0 +1 @@
+
\ No newline at end of file
diff --git a/src/Sapling.Mobile/Resources/Images/white_pawn.svg b/src/Sapling.Mobile/Resources/Images/white_pawn.svg
new file mode 100644
index 0000000..ceb32e2
--- /dev/null
+++ b/src/Sapling.Mobile/Resources/Images/white_pawn.svg
@@ -0,0 +1 @@
+
\ No newline at end of file
diff --git a/src/Sapling.Mobile/Resources/Images/white_queen.svg b/src/Sapling.Mobile/Resources/Images/white_queen.svg
new file mode 100644
index 0000000..c0af0ab
--- /dev/null
+++ b/src/Sapling.Mobile/Resources/Images/white_queen.svg
@@ -0,0 +1 @@
+
\ No newline at end of file
diff --git a/src/Sapling.Mobile/Resources/Images/white_rook.svg b/src/Sapling.Mobile/Resources/Images/white_rook.svg
new file mode 100644
index 0000000..ba3d4e3
--- /dev/null
+++ b/src/Sapling.Mobile/Resources/Images/white_rook.svg
@@ -0,0 +1 @@
+
\ No newline at end of file
diff --git a/src/Sapling.Mobile/Resources/Splash/sapling_pixel.png b/src/Sapling.Mobile/Resources/Splash/sapling_pixel.png
new file mode 100644
index 0000000..3afb6cb
Binary files /dev/null and b/src/Sapling.Mobile/Resources/Splash/sapling_pixel.png differ
diff --git a/src/Sapling.Mobile/Resources/Styles/Colors.xaml b/src/Sapling.Mobile/Resources/Styles/Colors.xaml
new file mode 100644
index 0000000..13714db
--- /dev/null
+++ b/src/Sapling.Mobile/Resources/Styles/Colors.xaml
@@ -0,0 +1,44 @@
+
+
+
+
+
+ #4B8067
+ #2E5A45
+ #242424
+ #D7E5DC
+ #9880e5
+ #233D2F
+
+ White
+ Black
+ #D600AA
+ #190649
+ #1f1f1f
+
+ #E1E1E1
+ #C8C8C8
+ #ACACAC
+ #919191
+ #6E6E6E
+ #404040
+ #212121
+ #141414
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
diff --git a/src/Sapling.Mobile/Resources/Styles/Styles.xaml b/src/Sapling.Mobile/Resources/Styles/Styles.xaml
new file mode 100644
index 0000000..4a0d3af
--- /dev/null
+++ b/src/Sapling.Mobile/Resources/Styles/Styles.xaml
@@ -0,0 +1,424 @@
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
diff --git a/src/Sapling.Mobile/Sapling.Mobile.csproj b/src/Sapling.Mobile/Sapling.Mobile.csproj
new file mode 100644
index 0000000..797f6eb
--- /dev/null
+++ b/src/Sapling.Mobile/Sapling.Mobile.csproj
@@ -0,0 +1,58 @@
+
+
+
+ net10.0-android;net10.0-ios
+
+ Exe
+ Sapling.Mobile
+ true
+ true
+ enable
+ enable
+
+
+ SourceGen
+
+
+ Sapling
+
+
+ com.aptacode.sapling
+
+
+ 1.0
+ 1
+
+
+
+ 15.0
+ 21.0
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
diff --git a/src/Sapling.WebHost.Tests/EngineHostContractTests.cs b/src/Sapling.WebHost.Tests/EngineHostContractTests.cs
index 56b35b0..2827eaa 100644
--- a/src/Sapling.WebHost.Tests/EngineHostContractTests.cs
+++ b/src/Sapling.WebHost.Tests/EngineHostContractTests.cs
@@ -18,6 +18,27 @@ private static long Num(string json, string key)
return long.Parse(m.Groups[1].Value);
}
+ [Fact]
+ public void ScoreHints_ScoresEveryLegalMoveAgainstTheGlobalBest()
+ {
+ EngineHost.Initialize(1);
+ EngineHost.SetPosition(Constants.InitialState);
+ EngineHost.SetHumanElo(500);
+ using var result = JsonDocument.Parse(EngineHost.ScoreHints());
+ var root = result.RootElement;
+ Assert.True(root.GetProperty("ok").GetBoolean());
+ var moves = root.GetProperty("moves").EnumerateArray().Select(x => x.GetString()).ToArray();
+ var scores = root.GetProperty("scores").EnumerateArray().Select(x => x.GetInt32()).ToArray();
+ var loss = root.GetProperty("lossCp").EnumerateArray().Select(x => x.GetInt32()).ToArray();
+ Assert.Equal(20, moves.Length);
+ Assert.Equal(moves.Length, loss.Length);
+ Assert.Contains("e2e4", moves);
+ Assert.Contains("g1f3", moves);
+ for (var i = 0; i < scores.Length; i++) Assert.Equal(scores.Max() - scores[i], loss[i]);
+ Assert.Contains(0, loss);
+ Assert.Contains("\"ok\":true", EngineHost.ApplyMove("e2e4"));
+ }
+
[Fact]
public void SearchSlice_CapsToTotalNodeBudget()
{
@@ -83,7 +104,7 @@ public void SetPosition_RejectsMissingKingFen()
[Theory]
[InlineData(0, 0)]
- [InlineData(300, 800)]
+ [InlineData(300, 500)]
[InlineData(1500, 1500)]
[InlineData(3000, 2200)]
public void SetHumanElo_UsesEmbeddedPolicyRange(int requested, int expected)
diff --git a/src/Sapling.WebHost/EngineHost.cs b/src/Sapling.WebHost/EngineHost.cs
index 04575f0..e30a281 100644
--- a/src/Sapling.WebHost/EngineHost.cs
+++ b/src/Sapling.WebHost/EngineHost.cs
@@ -138,6 +138,43 @@ public static string ApplyMove(string uci)
}
}
+ [JSExport]
+ public static string ScoreHints()
+ {
+ if (_state != HostState.Idle) return Busy();
+ if (_game is null || _ps is null) return NotReady();
+ try
+ {
+ var ranked = _ps.RankRootMoves(_game, HumanPlay.RankDepth);
+ // Mate labels retain their distance; only quality comparisons use a fixed pawn value.
+ static int QualityScore(int score) => MoveScoring.IsMateScore(score)
+ ? Math.Sign(score) * 2000 : score;
+ var best = ranked.Count == 0 ? 0 : ranked.Max(item => QualityScore(item.Score));
+ var j = new Json();
+ j.Start();
+ j.Bool("ok", true);
+ j.ArrStart("moves");
+ foreach (var item in ranked) j.StrItem(item.Move.ToUciMoveName());
+ j.ArrEnd();
+ j.ArrStart("scores");
+ foreach (var item in ranked) j.NumItem(MoveScoring.IsMateScore(item.Score)
+ ? Math.Sign(item.Score) * MoveScoring.GetMateDistance(item.Score) : item.Score);
+ j.ArrEnd();
+ j.ArrStart("scoreTypes");
+ foreach (var item in ranked) j.StrItem(MoveScoring.IsMateScore(item.Score) ? "mate" : "cp");
+ j.ArrEnd();
+ j.ArrStart("rankScores");
+ foreach (var item in ranked) j.NumItem(item.Score);
+ j.ArrEnd();
+ j.ArrStart("lossCp");
+ foreach (var item in ranked) j.NumItem(best - QualityScore(item.Score));
+ j.ArrEnd();
+ j.End();
+ return j.Done();
+ }
+ catch (Exception ex) { return Error(ex); }
+ }
+
[JSExport]
public static string ScoreMove(string uci)
{
@@ -533,16 +570,13 @@ private static void ApplyHumanOverride()
return;
var board = _game.Board;
- var rank = HumanPlay.PickMove(_humanRng, ref board, ranked, out _);
- if (rank <= 0 || rank >= ranked.Count)
- return;
-
- var chosen = ranked[rank].Move;
+ var selection = HumanPlay.SelectMove(_humanRng, ref board, ranked);
+ var chosen = selection.Move;
if (chosen == _bestMove)
return;
_bestMove = chosen;
- _bestScore = ranked[rank].Score;
+ _bestScore = ranked[selection.Rank].Score;
_bestPv = new List { chosen };
}
diff --git a/src/Sapling.sln b/src/Sapling.sln
index 8cbae38..9d5e858 100644
--- a/src/Sapling.sln
+++ b/src/Sapling.sln
@@ -13,6 +13,8 @@ Project("{FAE04EC0-301F-11D3-BF4B-00C04F79EFBC}") = "Sapling.Bench", "Sapling.Be
EndProject
Project("{FAE04EC0-301F-11D3-BF4B-00C04F79EFBC}") = "Sapling.WebHost.Tests", "Sapling.WebHost.Tests\Sapling.WebHost.Tests.csproj", "{4D9300EC-CDA9-4537-A1C1-C97085F488F2}"
EndProject
+Project("{FAE04EC0-301F-11D3-BF4B-00C04F79EFBC}") = "Sapling.Mobile", "Sapling.Mobile\Sapling.Mobile.csproj", "{C4C82A5D-A68A-44C6-BE7A-C5CC60FBA611}"
+EndProject
Global
GlobalSection(SolutionConfigurationPlatforms) = preSolution
Debug|Any CPU = Debug|Any CPU
@@ -83,6 +85,18 @@ Global
{4D9300EC-CDA9-4537-A1C1-C97085F488F2}.Release|x64.Build.0 = Release|x64
{4D9300EC-CDA9-4537-A1C1-C97085F488F2}.Release|x86.ActiveCfg = Release|Any CPU
{4D9300EC-CDA9-4537-A1C1-C97085F488F2}.Release|x86.Build.0 = Release|Any CPU
+ {C4C82A5D-A68A-44C6-BE7A-C5CC60FBA611}.Debug|Any CPU.ActiveCfg = Debug|Any CPU
+ {C4C82A5D-A68A-44C6-BE7A-C5CC60FBA611}.Debug|Any CPU.Build.0 = Debug|Any CPU
+ {C4C82A5D-A68A-44C6-BE7A-C5CC60FBA611}.Debug|x64.ActiveCfg = Debug|Any CPU
+ {C4C82A5D-A68A-44C6-BE7A-C5CC60FBA611}.Debug|x64.Build.0 = Debug|Any CPU
+ {C4C82A5D-A68A-44C6-BE7A-C5CC60FBA611}.Debug|x86.ActiveCfg = Debug|Any CPU
+ {C4C82A5D-A68A-44C6-BE7A-C5CC60FBA611}.Debug|x86.Build.0 = Debug|Any CPU
+ {C4C82A5D-A68A-44C6-BE7A-C5CC60FBA611}.Release|Any CPU.ActiveCfg = Release|Any CPU
+ {C4C82A5D-A68A-44C6-BE7A-C5CC60FBA611}.Release|Any CPU.Build.0 = Release|Any CPU
+ {C4C82A5D-A68A-44C6-BE7A-C5CC60FBA611}.Release|x64.ActiveCfg = Release|Any CPU
+ {C4C82A5D-A68A-44C6-BE7A-C5CC60FBA611}.Release|x64.Build.0 = Release|Any CPU
+ {C4C82A5D-A68A-44C6-BE7A-C5CC60FBA611}.Release|x86.ActiveCfg = Release|Any CPU
+ {C4C82A5D-A68A-44C6-BE7A-C5CC60FBA611}.Release|x86.Build.0 = Release|Any CPU
EndGlobalSection
GlobalSection(SolutionProperties) = preSolution
HideSolutionNode = FALSE
diff --git a/src/Sapling/UciEngine.cs b/src/Sapling/UciEngine.cs
index 84212dd..c819551 100644
--- a/src/Sapling/UciEngine.cs
+++ b/src/Sapling/UciEngine.cs
@@ -1,4 +1,5 @@
using System.Diagnostics;
+using System.Globalization;
using Sapling.Engine;
using Sapling.Engine.DataGen;
using Sapling.Engine.Evaluation;
@@ -14,7 +15,7 @@ public class UciEngine : IDisposable
private readonly object _commandGate = new();
private bool _disposed;
- public long TranspositionSize = (long)TranspositionTableExtensions.CalculateTranspositionTableSize(256);
+ public long TranspositionSize = TranspositionTableExtensions.CalculateTranspositionTableSize(16);
public static int MaxHashMb()
{
@@ -100,9 +101,9 @@ private void SetOption(string[] tokens)
break;
}
- if (transpositionSize < 32)
+ if (transpositionSize < 16)
{
- ReportProtocolError($"Hash must be at least 32 MB, got {transpositionSize}");
+ ReportProtocolError($"Hash must be at least 16 MB, got {transpositionSize}");
break;
}
@@ -114,6 +115,8 @@ private void SetOption(string[] tokens)
}
var size = TranspositionTableExtensions.CalculateTranspositionTableSize(transpositionSize);
+ if (size == TranspositionSize)
+ break;
var replacement = new ParallelSearcher(size);
try { replacement.SetThreads(_threadCount); }
catch { replacement.Dispose(); throw; }
@@ -131,6 +134,20 @@ private void SetOption(string[] tokens)
LogToFile($"[Debug] Set HumanElo '{HumanPlay.Elo}'");
}
+ break;
+
+ case "humantemperature":
+ if (tokens[3] == "value"
+ && float.TryParse(tokens[4], NumberStyles.Float, CultureInfo.InvariantCulture, out var humanTemperature))
+ {
+ HumanPlay.SetTemperature(humanTemperature);
+ LogToFile($"[Debug] Set HumanTemperature '{HumanPlay.Temperature.ToString(CultureInfo.InvariantCulture)}'");
+ }
+ else
+ {
+ ReportProtocolError("HumanTemperature expects a positive finite number");
+ }
+
break;
}
}
@@ -211,8 +228,9 @@ private void ReceiveCommandCore(string message)
Respond($"option name Threads type spin default {_threadCount} min 1 max 1024");
Respond($"option name Ponder type check default {_ponderEnabled.ToString().ToLower()}");
Respond($"option name UCI_Chess960 type check default {_chess960Enabled.ToString().ToLower()}");
- Respond($"option name Hash type spin default {TranspositionTableExtensions.CalculateSizeInMb((uint)TranspositionSize)} min 32 max {MaxHashMb()}");
+ Respond($"option name Hash type spin default {TranspositionTableExtensions.CalculateSizeInMb((uint)TranspositionSize)} min 16 max {MaxHashMb()}");
Respond($"option name HumanElo type spin default 0 min 0 max {HumanPlay.MaxElo}");
+ Respond("option name HumanTemperature type string default 1");
#if OpenBench
foreach (var spsaParameters in SpsaTuner.TuningParameters.Values)
{
@@ -546,14 +564,15 @@ private unsafe void ProcessGoCommand(string message)
tokens.Contains("infinite", StringComparer.OrdinalIgnoreCase) ||
(_ponderEnabled && tokens.Contains("ponder", StringComparer.OrdinalIgnoreCase)));
- OnMoveChosen(ApplyHumanLevel(_parallelSearcher.TimeBoundSearch(
- _gameState, timeBudget.SoftLimitMs, timeBudget.HardLimitMs)));
+ var timedResult = _parallelSearcher.TimeBoundSearch(
+ _gameState, timeBudget.SoftLimitMs, timeBudget.HardLimitMs);
+ OnMoveChosen(ApplyHumanLevel(timedResult, timeBudget.HardLimitMs));
}
private static string[] Tokenize(string message) =>
message.Split((char[]?)null, StringSplitOptions.RemoveEmptyEntries);
private const float MinSearchTimeMs = 10f;
- private const float OverheadBufferMs = 50f;
+ private const float OverheadBufferMs = 100f;
private const float IncrementUsageFactorLong = 0.6f;
private const float SoftLimitFactorLong = 0.75f;
private const float HardLimitFactorLong = 0.90f;
@@ -616,28 +635,31 @@ public static int CalculateThinkTime(
/// unchanged. When active, the embedded policy samples from fixed-depth root candidates.
///
private (List move, int depthSearched, int score, long nodes, TimeSpan duration) ApplyHumanLevel(
- (List move, int depthSearched, int score, long nodes, TimeSpan duration) result)
+ (List move, int depthSearched, int score, long nodes, TimeSpan duration) result,
+ int hardLimitMs = 0)
{
if (!HumanPlay.Enabled || result.move.Count == 0)
return result;
- var ranked = _parallelSearcher.RankRootMoves(_gameState, HumanPlay.RankDepth);
+ var rankTimeLimitMs = 0;
+ if (hardLimitMs > 0)
+ {
+ rankTimeLimitMs = (int)Math.Floor(hardLimitMs - result.duration.TotalMilliseconds);
+ if (rankTimeLimitMs < 1)
+ return result;
+ }
+
+ var ranked = _parallelSearcher.RankRootMoves(_gameState, HumanPlay.RankDepth, rankTimeLimitMs);
if (ranked.Count == 0)
return result;
var board = _gameState.Board;
- var rank = HumanPlay.PickMove(_humanRng, ref board, ranked, out _);
- if (rank <= 0)
- return result; // play the engine's own best move (keeps PV + ponder)
-
- if (rank >= ranked.Count)
- rank = ranked.Count - 1;
-
- var chosen = ranked[rank].Move;
+ var selection = HumanPlay.SelectMove(_humanRng, ref board, ranked);
+ var chosen = selection.Move;
if (chosen == result.move[0])
return result;
- return (new List { chosen }, result.depthSearched, ranked[rank].Score, result.nodes, result.duration);
+ return (new List { chosen }, result.depthSearched, ranked[selection.Rank].Score, result.nodes, result.duration);
}
private void OnMoveChosen(
diff --git a/tools/human-policy/README.md b/tools/human-policy/README.md
index a08bf6d..7fcb360 100644
--- a/tools/human-policy/README.md
+++ b/tools/human-policy/README.md
@@ -1,10 +1,58 @@
# Sapling human move policy
-This directory contains the versioned data, training and export pipeline for Sapling's rating-conditioned move policy. Keep large source archives, prepared datasets, checkpoints and intermediate exports outside Git. The checked-in `src/Sapling.Engine/Resources/human_policy_v1.weights` is the compact model used at runtime.
-
-## Current embedded model
-
-The embedded resource is the candidate trained on the 10 GiB Lichess sample. It was evaluated on 36,549 held-out positions and exported from the selected checkpoint with SHA-256 `af76696a6ee68a4cd87919283df143a6c3b513aa3c6a56b614489e6810b0c80f` (1,175,142 bytes). Held-out metrics are NLL 1.8880, top-1 43.75%, and top-3 70.22%; the 1 GiB baseline on the same test split scored NLL 2.1599, top-1 38.81%, and top-3 65.30%. `tests/inference_golden.json` contains reference logits regenerated from that checkpoint and is checked against the embedded runtime by xUnit.
+The shared engine embeds `src/Sapling.Engine/Resources/human_policy_v1.weights`; native and browser
+builds require no external model file or inference service. Human Elo supports 500–2200; zero disables it.
+
+## Current model
+
+The model uses 1,025,387 July 2026 Lichess rated rapid positions. Its latest two-epoch fine-tune
+added 15,623 game-disjoint positions below 800 and used rating-balanced sampling.
+Resource SHA-256: `b075580ede7c87f7bb1375189d0d894d969e02579ed346efd3f0b116bc9aee87`.
+
+On 9,000 separate September games, compared with the preceding runtime:
+
+| Metric | Previous | Current |
+|---|---:|---:|
+| NLL | 2.00581 | 1.97440 |
+| Brier score | 0.74130 | 0.73299 |
+| Top-choice agreement | 41.33% | 41.32% |
+| Sampled exact-match | 29.73% | 28.47% |
+| Direct-capture risk mass | 5.98% | 8.36% |
+| >=300 cp regret mass | 12.12% | 15.26% |
+
+NLL and Brier improve with game-cluster 95% confidence intervals excluding zero. Recorded human
+risk and large-regret rates were 8.80% and 17.22%, respectively. The broader policy fits these human
+frequencies better, with lower sampled exact-match as an explicit tradeoff. These signals do not
+establish that every individual mistake looks human.
+
+Maia calibration matches gave score-equivalent gaps of approximately −74 to +92 Elo across nine
+settings, versus +63 to +288 previously. Each point used 100 games and 50 color-swapped opening pairs
+on a reused book; these are calibration estimates, not independently verified playing ratings.
+Archives, checkpoints, and detailed experiment records remain on the evaluation host outside this repository.
+
+## Runtime calibration
+
+[`HumanPlayCalibration.cs`](../../src/Sapling.Engine/Tuning/HumanPlayCalibration.cs) contains the
+model-bound rating, temperature and risk-penalty anchors. Settings interpolate at each exact rating.
+A checksum mismatch bypasses calibration. [`DirectCaptureRisk.cs`](../../src/Sapling.Engine/Tuning/DirectCaptureRisk.cs)
+flags an immediate legal capture of a minor-or-better piece without an immediate recapture; it does
+not assess full material compensation or justified sacrifices.
+
+## Evaluating changes
+
+[`compare_checkpoints.py`](compare_checkpoints.py) compares two checkpoints on scored validation or
+test positions using exact-rating interpolation from [`runtime_calibration.py`](runtime_calibration.py).
+It reports likelihood, Brier score, top-k and sampled agreement, engine-regret tails, observed human
+risk rates, and game-cluster bootstrap intervals by rating band. Run `--help` for checkpoint, dataset,
+calibration and risk-map options. A calibration JSON contains `calibration_anchors` with
+`human_rating_band`, `display_rating`, `model_rating`, and `temperature`; a risk-map JSON contains
+`penalties` with `human_rating_band` and `risk_penalty`.
+
+Select changes on validation data and retain a separate game-disjoint evaluation window. Compare
+actual human error frequencies instead of minimizing every mistake. September was excluded from
+training; previously consulted test windows should not be treated as untouched for future selection.
+Current training data used the earlier both-player rating restriction; the extractor now retains
+in-range movers against out-of-range opponents.
## Repeatable training workflow
@@ -17,10 +65,10 @@ python -m pip install --upgrade pip
python -m pip install -r tools/human-policy/requirements.txt
```
-Before training, verify CUDA with `python -c 'import torch; print(torch.__version__, torch.cuda.is_available())'`. The trainer requires CUDA. The extractor and dataset tests can run on CPU.
+Before training, verify the available device with `python -c 'import torch; print(torch.__version__, torch.cuda.is_available())'`. The trainer supports CPU and CUDA; the extractor and dataset tests can run on CPU.
1. Download a Lichess monthly standard PGN archive from and record its checksum. Store it outside the repository, for example as `data/raw/month.pgn.zst`.
-2. Extract rated rapid games to deterministic game-level splits. `pzstd` parallelizes decompression; `--workers` and `--batch-size` control parsing. Omit `--max-games` or set it to `0` to scan the full archive. Use a nonzero value for a bounded pilot.
+2. Extract rated rapid games to deterministic game-level splits. `pzstd` parallelizes decompression; `--workers` and `--batch-size` control parsing. Omit `--max-games` or set it to `0` to scan the full archive. Use a nonzero value for a bounded pilot. To evaluate a later archive-order window, set `--skip-games N` with a nonzero `--max-games`; the manifest records both bounds and the sampled positions' game-date range.
```sh
mkdir -p data/positions
@@ -68,7 +116,7 @@ Keep the archive checksum, preprocessing commit, extraction options, engine buil
- Squares use `a1=0`, `b1=1`, through `h8=63`; board tensor flattening is `channel * 64 + square`, with row `square // 8` and column `square % 8`.
- Board planes are white P/N/B/R/Q/K, black P/N/B/R/Q/K, side-to-move, white K/Q rights, black K/Q rights, then en-passant target: 18 planes total. En-passant uses the FEN target square even when no legal capture exists.
- The first 132 move features are `from[64] + to[64] + promotion[Q,R,B,N]`. Features 132 and 133 are `tanh(root_score / 1000)` and `tanh(max(0, best_score - root_score) / 1000)`. Scores are fixed-depth root-ranking integers from the side-to-move perspective. Preserve legal candidate order through scoring and selection.
-- Ratings are mover-side Lichess rapid ratings in `[800,2200]`, mapped by `(rating - 1500) / 700`. Out-of-range values are rejected by the encoder.
+- Ratings are mover-side Lichess rapid ratings in `[500,2200]`, mapped by `(rating - 1500) / 700`. Out-of-range values are rejected by the encoder. The checked-in candidate is calibrated across 500–2200, with an additional 15,623 game-disjoint low-rating positions and rating-balanced sampling in its latest fine-tune.
- Schema version is `1`; Chess960 is excluded. `tests/golden_cases.json` covers castling, en-passant, promotions and score normalization for both Python and C# encoders.
`extract_pgn.py` filters standard, rated rapid games, samples positions by 200-point mover-rating band and splits by game. `analyze_positions.py` scores every legal move through Sapling's `rank` command. `dataset.py` validates score coverage and encodes inputs; `HumanPolicyEncoding` is the matching C# implementation. `train.py` writes the best validation checkpoint and metrics; `export_engine_weights.py` produces the compact resource embedded by the engine.
diff --git a/tools/human-policy/compare_checkpoints.py b/tools/human-policy/compare_checkpoints.py
new file mode 100644
index 0000000..7f41722
--- /dev/null
+++ b/tools/human-policy/compare_checkpoints.py
@@ -0,0 +1,293 @@
+#!/usr/bin/env python3
+"""Compare two human-policy checkpoints on game-disjoint scored positions."""
+
+from __future__ import annotations
+
+import argparse
+import hashlib
+import json
+from collections import defaultdict
+from functools import partial
+from pathlib import Path
+
+import chess
+import numpy as np
+import torch
+from torch.utils.data import DataLoader, Dataset
+
+from runtime_calibration import settings_for_rating
+from model import HumanMovePolicy
+from train import PositionDataset, collate_positions
+
+
+METRICS = (
+ "nll",
+ "brier",
+ "expected_match",
+ "top1",
+ "top3",
+ "expected_regret_cp",
+ "probability_on_300cp_regrets",
+ "probability_on_direct_capture_risk",
+ "observed_human_regret_cp",
+ "observed_human_300cp_regret_rate",
+ "observed_human_direct_capture_risk_rate",
+)
+
+
+class RowsWithMetadata(Dataset):
+ def __init__(self, dataset: PositionDataset):
+ self.dataset = dataset
+
+ def __len__(self):
+ return len(self.dataset)
+
+ def __getitem__(self, index):
+ return self.dataset[index], self.dataset.rows[index]
+
+
+def direct_capture_risk_after_move(board: chess.Board, move: chess.Move) -> bool:
+ """Mirror the runtime proxy: an immediate capture of a minor+ piece with no recapture."""
+ after = board.copy(stack=False)
+ after.push(move)
+ for capture in list(after.legal_moves):
+ if not after.is_capture(capture) or after.is_en_passant(capture):
+ continue
+ victim = after.piece_at(capture.to_square)
+ if victim is None or victim.piece_type < chess.KNIGHT:
+ continue
+ capture_square = capture.to_square
+ after_capture = after.copy(stack=False)
+ after_capture.push(capture)
+ piece_on_capture_square = after_capture.piece_at(capture_square)
+ recaptured = any(
+ after_capture.is_capture(reply) and reply.to_square == capture_square
+ and after_capture.piece_at(reply.to_square) == piece_on_capture_square
+ for reply in after_capture.legal_moves
+ )
+ if not recaptured:
+ return True
+ return False
+
+
+def collate_with_metadata(items, compute_direct_risk: bool):
+ encoded = collate_positions([item for item, _ in items])
+ rows = [row for _, row in items]
+ regrets = np.zeros_like(encoded["mask"].numpy(), dtype=np.float32)
+ direct_risk = np.zeros_like(regrets, dtype=np.float32)
+ for index, row in enumerate(rows):
+ board = chess.Board(row["fen"])
+ legal = list(board.legal_moves)
+ scores = {move: int(score) for move, score in row["engine_scores"].items()}
+ best = max(scores.values())
+ regrets[index, :len(legal)] = [best - scores[move.uci()] for move in legal]
+ if compute_direct_risk:
+ direct_risk[index, :len(legal)] = [
+ float(direct_capture_risk_after_move(board, move)) for move in legal
+ ]
+ encoded["regrets"] = torch.from_numpy(regrets)
+ encoded["direct_risk"] = torch.from_numpy(direct_risk)
+ encoded["game_ids"] = [str(row["game_id"]) for row in rows]
+ encoded["rating_bands"] = [
+ f"{(min(int(row['rating']), 2199) // 200) * 200}-"
+ f"{(min(int(row['rating']), 2199) // 200) * 200 + 199}"
+ for row in rows
+ ]
+ return encoded
+
+
+def sha256_file(path: Path) -> str:
+ digest = hashlib.sha256()
+ with path.open("rb") as stream:
+ for block in iter(lambda: stream.read(8 * 1024 * 1024), b""):
+ digest.update(block)
+ return digest.hexdigest()
+
+
+def load_model(path: Path, device: torch.device) -> HumanMovePolicy:
+ checkpoint = torch.load(path, map_location=device, weights_only=False)
+ if checkpoint.get("schema_version") != 1:
+ raise ValueError(f"unsupported checkpoint schema: {path}")
+ model = HumanMovePolicy().to(device)
+ model.load_state_dict(checkpoint["model_state_dict"], strict=True)
+ model.eval()
+ return model
+
+
+def load_calibration(path: Path | None) -> dict[str, dict] | None:
+ if path is None:
+ return None
+ doc = json.loads(path.read_text(encoding="utf-8"))
+ anchors = doc.get("calibration_anchors") or doc.get("constrained_expected_match_anchors")
+ if not anchors:
+ raise ValueError(f"calibration map has no supported anchors: {path}")
+ return {row["human_rating_band"]: row for row in anchors}
+
+
+def load_risk_penalties(path: Path | None) -> dict[str, float]:
+ if path is None:
+ return {}
+ doc = json.loads(path.read_text(encoding="utf-8"))
+ return {row["human_rating_band"]: float(row["risk_penalty"])
+ for row in doc.get("penalties", [])}
+
+
+def summarize_groups(groups: dict[str, dict[str, list[float]]], replicates: int,
+ rng: np.random.Generator) -> dict:
+ result = {}
+ for scope, games in groups.items():
+ game_ids = sorted(games)
+ counts = np.asarray([games[game][0] for game in game_ids], dtype=np.float64)
+ cells = np.asarray([games[game][1:] for game in game_ids], dtype=np.float64)
+ positions = int(counts.sum())
+ cells = cells.reshape(len(game_ids), 2, len(METRICS)).transpose(0, 2, 1)
+ metric_result = {}
+ for metric_index, metric in enumerate(METRICS):
+ sums = cells[:, metric_index, :]
+ means = sums.sum(axis=0) / positions
+ deltas = []
+ for start in range(0, replicates, 100):
+ batch_count = min(100, replicates - start)
+ sample = rng.integers(0, len(game_ids), size=(batch_count, len(game_ids)))
+ sampled_sums = sums[sample].sum(axis=1)
+ sampled_counts = counts[sample].sum(axis=1)
+ deltas.extend((sampled_sums[:, 1] - sampled_sums[:, 0]) / sampled_counts)
+ ci = np.quantile(np.asarray(deltas), [0.025, 0.975]).tolist()
+ metric_result[metric] = {
+ "baseline": float(means[0]),
+ "candidate": float(means[1]),
+ "delta": float(means[1] - means[0]),
+ "delta_ci95": [float(ci[0]), float(ci[1])],
+ }
+ result[scope] = {"positions": positions, "games": len(game_ids), "metrics": metric_result}
+ return result
+
+
+def main() -> int:
+ parser = argparse.ArgumentParser(description=__doc__)
+ parser.add_argument("--baseline", required=True, type=Path)
+ parser.add_argument("--candidate", required=True, type=Path)
+ parser.add_argument("--dataset-dir", required=True, type=Path)
+ parser.add_argument("--baseline-calibration", type=Path)
+ parser.add_argument("--candidate-calibration", type=Path)
+ parser.add_argument("--baseline-risk-map", type=Path)
+ parser.add_argument("--candidate-risk-map", type=Path)
+ parser.add_argument("--split", choices=("validation", "test"), default="test")
+ parser.add_argument("--batch-size", type=int, default=128)
+ parser.add_argument("--workers", type=int, default=8)
+ parser.add_argument("--threads", type=int, default=16)
+ parser.add_argument("--replicates", type=int, default=2000)
+ parser.add_argument("--seed", type=int, default=20261028)
+ parser.add_argument("--output", required=True, type=Path)
+ args = parser.parse_args()
+
+ torch.set_num_threads(args.threads)
+ device = torch.device("cpu")
+ baseline = load_model(args.baseline, device)
+ candidate = load_model(args.candidate, device)
+ baseline_calibration = load_calibration(args.baseline_calibration)
+ candidate_calibration = load_calibration(args.candidate_calibration)
+ baseline_risk_map = load_risk_penalties(args.baseline_risk_map)
+ candidate_risk_map = load_risk_penalties(args.candidate_risk_map)
+ needs_direct_risk = True # Observed human risk is reported even without policy penalties.
+ source = args.dataset_dir / f"{args.split}.jsonl"
+ data = PositionDataset(source, "none")
+ loader = DataLoader(RowsWithMetadata(data), batch_size=args.batch_size, shuffle=False,
+ num_workers=args.workers,
+ collate_fn=partial(collate_with_metadata,
+ compute_direct_risk=needs_direct_risk))
+
+ # scope -> game -> [position count, baseline metric sums..., candidate sums...]
+ groups: dict[str, dict[str, list[float]]] = defaultdict(dict)
+ with torch.inference_mode():
+ for batch in loader:
+ board = batch["board"].to(device)
+ moves = batch["moves"].to(device)
+ rating = batch["rating"].to(device)
+ mask = batch["mask"].to(device)
+ targets = batch["target"].to(device)
+ regrets = batch["regrets"].to(device)
+ direct_risk = batch["direct_risk"].to(device)
+ bands = batch["rating_bands"]
+ settings = []
+ for calibration, risk_map in (
+ (baseline_calibration, baseline_risk_map),
+ (candidate_calibration, candidate_risk_map),
+ ):
+ exact_ratings = torch.round(rating[:, 0] * 700 + 1500).tolist()
+ runtime_settings = [settings_for_rating(value, calibration, risk_map)
+ for value in exact_ratings]
+ rating_tensor = torch.tensor(
+ [[(value[0] - 1500) / 700.0] for value in runtime_settings], dtype=torch.float32)
+ temperatures = torch.tensor([value[1] for value in runtime_settings], dtype=torch.float32)
+ penalties = torch.tensor([value[2] for value in runtime_settings], dtype=torch.float32)
+ settings.append((rating_tensor, temperatures, penalties))
+ logits_by_model = []
+ for model, (model_rating, temperatures, penalties) in zip(
+ (baseline, candidate), settings):
+ logits = model(board, moves, model_rating).masked_fill(~mask, -1e9)
+ logits = logits - direct_risk * penalties[:, None]
+ logits_by_model.append(logits / temperatures[:, None])
+ row_metrics = []
+ for logits in logits_by_model:
+ log_probabilities = torch.log_softmax(logits, dim=-1)
+ probabilities = log_probabilities.exp()
+ target_log_probability = log_probabilities.gather(1, targets[:, None]).squeeze(1)
+ target_probability = probabilities.gather(1, targets[:, None]).squeeze(1)
+ top_indices = logits.topk(min(3, logits.shape[1]), dim=1).indices
+ top1 = top_indices[:, 0].eq(targets).float()
+ top3 = top_indices.eq(targets[:, None]).any(dim=1).float()
+ regret_mass = (probabilities * (regrets >= 300).float()).sum(dim=1)
+ direct_risk_mass = (probabilities * direct_risk).sum(dim=1)
+ expected_regret = (probabilities * regrets).sum(dim=1)
+ # The recorded move supplies an empirical error-rate reference. Reducing
+ # every mistake can otherwise make a low-rating policy unrealistically strong.
+ observed_regret = regrets.gather(1, targets[:, None]).squeeze(1)
+ observed_risk = direct_risk.gather(1, targets[:, None]).squeeze(1)
+ row_metrics.append(torch.stack((
+ -target_log_probability,
+ probabilities.square().sum(dim=1) - 2 * target_probability + 1, target_probability,
+ top1, top3, expected_regret, regret_mass, direct_risk_mass,
+ observed_regret, (observed_regret >= 300).float(), observed_risk,
+ ), dim=1).cpu().numpy())
+
+ for index, game_id in enumerate(batch["game_ids"]):
+ values = np.concatenate((row_metrics[0][index], row_metrics[1][index])).tolist()
+ band = batch["rating_bands"][index]
+ for scope in ("overall", band):
+ cell = groups[scope].setdefault(game_id, [0.0] * (1 + 2 * len(METRICS)))
+ cell[0] += 1
+ for metric_index, value in enumerate(values):
+ cell[1 + metric_index] += value
+
+ rng = np.random.default_rng(args.seed)
+ report = {
+ "baseline_checkpoint": str(args.baseline),
+ "baseline_sha256": sha256_file(args.baseline),
+ "candidate_checkpoint": str(args.candidate),
+ "candidate_sha256": sha256_file(args.candidate),
+ "baseline_calibration": str(args.baseline_calibration) if args.baseline_calibration else None,
+ "baseline_calibration_sha256": sha256_file(args.baseline_calibration) if args.baseline_calibration else None,
+ "candidate_calibration": str(args.candidate_calibration) if args.candidate_calibration else None,
+ "candidate_calibration_sha256": sha256_file(args.candidate_calibration) if args.candidate_calibration else None,
+ "baseline_risk_map": str(args.baseline_risk_map) if args.baseline_risk_map else None,
+ "baseline_risk_map_sha256": sha256_file(args.baseline_risk_map) if args.baseline_risk_map else None,
+ "candidate_risk_map": str(args.candidate_risk_map) if args.candidate_risk_map else None,
+ "candidate_risk_map_sha256": sha256_file(args.candidate_risk_map) if args.candidate_risk_map else None,
+ "input": str(source),
+ "input_sha256": sha256_file(source),
+ "split": args.split,
+ "calibration_application": "exact position rating with runtime anchor interpolation",
+ "bootstrap_unit": "game, preserving all sampled positions from a game",
+ "bootstrap_seed": args.seed,
+ "bootstrap_replicates": args.replicates,
+ "results": summarize_groups(groups, args.replicates, rng),
+ }
+ args.output.parent.mkdir(parents=True, exist_ok=True)
+ args.output.write_text(json.dumps(report, indent=2) + "\n", encoding="utf-8")
+ print(json.dumps(report, indent=2))
+ return 0
+
+
+if __name__ == "__main__":
+ raise SystemExit(main())
diff --git a/tools/human-policy/config.yaml b/tools/human-policy/config.yaml
index f3e1c43..6c0ceab 100644
--- a/tools/human-policy/config.yaml
+++ b/tools/human-policy/config.yaml
@@ -8,4 +8,5 @@ weight_decay: 0.0001
num_workers: 4
early_stopping_patience: 3
deterministic: false
+rating_balanced_sampling: false # true gives each represented rating band equal sampling weight
ablation: none # none, rating, or engine
diff --git a/tools/human-policy/dataset.py b/tools/human-policy/dataset.py
index 2c3a369..9d2fc5b 100644
--- a/tools/human-policy/dataset.py
+++ b/tools/human-policy/dataset.py
@@ -9,7 +9,7 @@
SCHEMA_VERSION = 1
BOARD_CHANNELS = 18
MOVE_FEATURES = 134
-MIN_RATING = 800
+MIN_RATING = 500
MAX_RATING = 2200
_PIECE_ORDER = (chess.PAWN, chess.KNIGHT, chess.BISHOP,
chess.ROOK, chess.QUEEN, chess.KING)
diff --git a/tools/human-policy/export_onnx.py b/tools/human-policy/export_onnx.py
index 9a6196a..cac5d7a 100644
--- a/tools/human-policy/export_onnx.py
+++ b/tools/human-policy/export_onnx.py
@@ -9,7 +9,6 @@
import chess
import numpy as np
-import onnxruntime as ort
import torch
from dataset import (
@@ -87,6 +86,8 @@ def softmax(logits: np.ndarray) -> np.ndarray:
def main() -> int:
+ import onnxruntime as ort
+
parser = argparse.ArgumentParser(description=__doc__)
parser.add_argument("--checkpoint", required=True, type=Path)
parser.add_argument("--output", required=True, type=Path)
diff --git a/tools/human-policy/extract_pgn.py b/tools/human-policy/extract_pgn.py
index 19a10cb..e795fd5 100644
--- a/tools/human-policy/extract_pgn.py
+++ b/tools/human-policy/extract_pgn.py
@@ -86,6 +86,15 @@ def iter_pgn_text_games(stream, chunk_size: int = 1024 * 1024):
yield "".join(current)
+def game_window(games, skip_games: int, max_games: int):
+ """Return a bounded archive-order window without parsing skipped games."""
+ if skip_games:
+ games = itertools.islice(games, skip_games, None)
+ if max_games:
+ games = itertools.islice(games, max_games)
+ return games
+
+
def headers_from_pgn_text(pgn_text: str):
separator = re.search(r"\r?\n\s*\r?\n", pgn_text)
if separator is None:
@@ -149,8 +158,11 @@ def is_standard_rated_rapid(headers) -> tuple[bool, str]:
return True, ""
-def rating_band(rating: int) -> str:
- lower = (rating // RATING_BAND_WIDTH) * RATING_BAND_WIDTH
+def rating_band(rating: int, maximum: int = 2200) -> str:
+ # The configured maximum is inclusive, not the start of another band. Keep it
+ # with the preceding rating range to align extraction and calibration buckets.
+ bounded_rating = min(rating, maximum - 1)
+ lower = (bounded_rating // RATING_BAND_WIDTH) * RATING_BAND_WIDTH
return f"{lower}-{lower + RATING_BAND_WIDTH - 1}"
@@ -158,11 +170,14 @@ def collect_game_positions(game: chess.pgn.Game, minimum: int, maximum: int):
headers = game.headers
white_rating = parse_rating(headers.get("WhiteElo"), minimum, maximum)
black_rating = parse_rating(headers.get("BlackElo"), minimum, maximum)
- if white_rating is None or black_rating is None:
+ if white_rating is None and black_rating is None:
return None, "missing_or_out_of_range_rating"
key = game_id(game)
split = split_for(key)
+ date = headers.get("UTCDate") or headers.get("Date", "")
+ if not re.fullmatch(r"\d{4}\.\d{2}\.\d{2}", date):
+ date = ""
board = game.board()
if board.chess960 or not board.is_valid():
return None, "invalid_start_position"
@@ -175,15 +190,17 @@ def collect_game_positions(game: chess.pgn.Game, minimum: int, maximum: int):
mover_rating = white_rating if board.turn == chess.WHITE else black_rating
# Keep the FEN target square even if no legal en-passant capture exists.
fen = board.fen(en_passant="fen")
- rows.append({
- "game_id": key,
- "ply": ply,
- "fen": fen,
- "move": move.uci(),
- "rating": mover_rating,
- "pool": "rapid",
- "split": split,
- })
+ if mover_rating is not None:
+ rows.append({
+ "game_id": key,
+ "game_date": date,
+ "ply": ply,
+ "fen": fen,
+ "move": move.uci(),
+ "rating": mover_rating,
+ "pool": "rapid",
+ "split": split,
+ })
board.push(move)
except (ValueError, AssertionError):
return None, "corrupt_game"
@@ -202,7 +219,7 @@ def process_pgn_text(pgn_text: str, minimum: int, maximum: int):
if not keep:
return None, f"skip_{reason}"
if (parse_rating(headers.get("WhiteElo"), minimum, maximum) is None
- or parse_rating(headers.get("BlackElo"), minimum, maximum) is None):
+ and parse_rating(headers.get("BlackElo"), minimum, maximum) is None):
return None, "skip_missing_or_out_of_range_rating"
try:
game = chess.pgn.read_game(io.StringIO(pgn_text))
@@ -259,8 +276,10 @@ def main() -> int:
parser.add_argument("--input", required=True, type=Path,
help="Monthly .pgn.zst or plain .pgn archive; '-' reads PGN text from stdin")
parser.add_argument("--pool", choices=("rapid",), default="rapid")
- parser.add_argument("--min-rating", type=int, default=800)
+ parser.add_argument("--min-rating", type=int, default=500)
parser.add_argument("--max-rating", type=int, default=2200)
+ parser.add_argument("--skip-games", type=int, default=0,
+ help="Skip this many archive-order games before the sample window")
parser.add_argument("--max-games", type=int, default=10000, help="Maximum games scanned; 0 means no limit")
parser.add_argument("--max-positions-per-band", type=int, default=30000,
help="Reservoir limit for each 200-point mover-rating band")
@@ -278,8 +297,8 @@ def main() -> int:
if args.min_rating < 0 or args.max_rating <= args.min_rating:
parser.error("require 0 <= --min-rating < --max-rating")
- if args.max_games < 0 or args.max_positions_per_band < 1 or args.workers < 1 or args.batch_size < 1:
- parser.error("--max-games must be >= 0, --max-positions-per-band, --workers, and --batch-size must be >= 1")
+ if args.skip_games < 0 or args.max_games < 0 or args.max_positions_per_band < 1 or args.workers < 1 or args.batch_size < 1:
+ parser.error("--skip-games and --max-games must be >= 0; --max-positions-per-band, --workers, and --batch-size must be >= 1")
if str(args.input) != "-" and not args.input.is_file():
parser.error(f"input archive does not exist: {args.input}")
@@ -287,6 +306,7 @@ def main() -> int:
"input": str(args.input), "pool": args.pool,
"rating_range": [args.min_rating, args.max_rating],
"max_games": args.max_games,
+ "skip_games": args.skip_games,
"max_positions_per_band": args.max_positions_per_band,
"workers": args.workers,
"batch_size": args.batch_size,
@@ -301,9 +321,9 @@ def main() -> int:
started = time.monotonic()
try:
with open_pgn(args.input) as stream:
- pgn_texts = iter_pgn_text_games(stream)
- if args.max_games:
- pgn_texts = itertools.islice(pgn_texts, args.max_games)
+ pgn_texts = game_window(
+ iter_pgn_text_games(stream), args.skip_games, args.max_games
+ )
for rows, reason in iter_processed_games(
pgn_texts, args.workers, args.min_rating, args.max_rating, args.batch_size):
scanned += 1
@@ -319,7 +339,7 @@ def main() -> int:
accepted_games += 1
counters["accepted_games"] += 1
for row in rows:
- band = rating_band(row["rating"])
+ band = rating_band(row["rating"], args.max_rating)
seen_by_band[band] += 1
row["rating_band"] = band
bucket = samples[band]
@@ -366,11 +386,14 @@ def main() -> int:
"rating_tags": ["WhiteElo", "BlackElo"],
"rating_range": [args.min_rating, args.max_rating],
"mover_rating": True,
+ "rating_range_applies_to": "side_to_move_only",
+ "opponent_may_be_out_of_range": True,
"exclude_bot_title": True,
"starting_position": "standard chess start only",
"plies": "all nonterminal pre-move positions",
},
"sampling": {
+ "skip_games_before_window": args.skip_games,
"max_games_scanned": args.max_games,
"compressed_input_bytes": args.input.stat().st_size if args.input.name.endswith(".zst") else None,
"allow_truncated_zstd": args.allow_truncated_zstd,
@@ -386,6 +409,12 @@ def main() -> int:
"sampled_games_by_split": {split: len(ids) for split, ids in final_games.items()},
},
"files": {split: path.name for split, path in paths.items()},
+ "sampled_position_game_date_range": {
+ "min": min((row["game_date"] for bucket in samples.values() for row in bucket
+ if row.get("game_date")), default=None),
+ "max": max((row["game_date"] for bucket in samples.values() for row in bucket
+ if row.get("game_date")), default=None),
+ },
"preprocessing_commit": args.preprocessing_commit,
"encoder_schema_version": 1,
}
diff --git a/tools/human-policy/runtime_calibration.py b/tools/human-policy/runtime_calibration.py
new file mode 100644
index 0000000..a36085e
--- /dev/null
+++ b/tools/human-policy/runtime_calibration.py
@@ -0,0 +1,23 @@
+"""Mirror the runtime's interpolation at each position's exact display rating."""
+from bisect import bisect_left
+
+
+def settings_for_rating(rating, calibration, risk_map):
+ if not calibration:
+ band = f"{min(int(rating), 2199) // 200 * 200}-{min(int(rating), 2199) // 200 * 200 + 199}"
+ return int(rating), 1.0, risk_map.get(band, 0.0)
+ anchors = sorted(calibration.values(), key=lambda row: row['display_rating'])
+ value = max(500, min(2200, int(rating)))
+ right = bisect_left([row['display_rating'] for row in anchors], value)
+ if right == 0:
+ left = end = anchors[0]
+ elif right == len(anchors):
+ left = end = anchors[-1]
+ else:
+ left, end = anchors[right - 1], anchors[right]
+ fraction = 0.0 if left is end else (value - left['display_rating']) / (end['display_rating'] - left['display_rating'])
+ def interpolate(key, default):
+ return float(left.get(key, default)) + fraction * (float(end.get(key, default)) - float(left.get(key, default)))
+ penalty = risk_map.get(left['human_rating_band'], 0.0)
+ penalty += fraction * (risk_map.get(end['human_rating_band'], 0.0) - penalty)
+ return round(interpolate('model_rating', value)), interpolate('temperature', 1.0), penalty
diff --git a/tools/human-policy/tests/inference_golden.json b/tools/human-policy/tests/inference_golden.json
index 685f3e9..98dc31c 100644
--- a/tools/human-policy/tests/inference_golden.json
+++ b/tools/human-policy/tests/inference_golden.json
@@ -28,26 +28,26 @@
"a2a4": 892
},
"expected_logits": {
- "g1h3": -4.129846572875977,
- "g1f3": -2.9405746459960938,
- "b1c3": -5.787903308868408,
- "b1a3": -9.376141548156738,
- "h2h3": -8.84622859954834,
- "g2g3": -7.673403263092041,
- "f2f3": -8.7103271484375,
- "e2e3": -8.449319839477539,
- "d2d3": -9.055224418640137,
- "c2c3": -2.4014813899993896,
- "b2b3": -3.335494041442871,
- "a2a3": -6.000059604644775,
- "h2h4": -8.013949394226074,
- "g2g4": -6.379883289337158,
- "f2f4": -6.499444007873535,
- "e2e4": -3.933741807937622,
- "d2d4": -4.55936861038208,
- "c2c4": -7.970196723937988,
- "b2b4": -10.502673149108887,
- "a2a4": -3.3137197494506836
+ "g1h3": -5.7042412757873535,
+ "g1f3": -4.015295028686523,
+ "b1c3": -6.501139163970947,
+ "b1a3": -9.743982315063477,
+ "h2h3": -9.366164207458496,
+ "g2g3": -8.060844421386719,
+ "f2f3": -8.997420310974121,
+ "e2e3": -7.496097564697266,
+ "d2d3": -8.181498527526855,
+ "c2c3": -4.248743534088135,
+ "b2b3": -5.2266926765441895,
+ "a2a3": -7.807715892791748,
+ "h2h4": -8.29611587524414,
+ "g2g4": -7.245790481567383,
+ "f2f4": -6.910080432891846,
+ "e2e4": -3.8604981899261475,
+ "d2d4": -3.9907209873199463,
+ "c2c4": -7.647462844848633,
+ "b2b4": -9.784415245056152,
+ "a2a4": -5.703970909118652
}
},
{
@@ -64,13 +64,13 @@
"d4e3": -711
},
"expected_logits": {
- "e8f8": -2.5770068168640137,
- "e8d8": 1.623659610748291,
- "e8f7": -0.37501800060272217,
- "e8e7": -0.26707541942596436,
- "e8d7": -0.6275354027748108,
- "d4d3": -1.7596043348312378,
- "d4e3": -1.6283692121505737
+ "e8f8": -2.405924081802368,
+ "e8d8": 1.0515103340148926,
+ "e8f7": -0.23106451332569122,
+ "e8e7": -0.2320978194475174,
+ "e8d7": -0.7684127688407898,
+ "d4d3": -1.1986483335494995,
+ "d4e3": -1.140328049659729
}
},
{
@@ -106,32 +106,32 @@
"e1c1": -374
},
"expected_logits": {
- "h1h8": -1.535881757736206,
- "h1h7": -1.9286389350891113,
- "h1h6": -2.412630319595337,
- "h1h5": -3.434300422668457,
- "h1h4": -4.319737434387207,
- "h1h3": -0.46203333139419556,
- "h1h2": -2.5040900707244873,
- "h1g1": -2.7144529819488525,
- "h1f1": -2.8445310592651367,
- "e1f2": -2.8797991275787354,
- "e1e2": -3.1125595569610596,
- "e1d2": -3.599623441696167,
- "e1f1": -3.9727771282196045,
- "e1d1": -3.831151247024536,
- "a1a8": -3.572868585586548,
- "a1a7": 2.2592124938964844,
- "a1a6": -0.9174104332923889,
- "a1a5": -2.2116079330444336,
- "a1a4": -3.0133936405181885,
- "a1a3": -3.9863979816436768,
- "a1a2": -4.288959503173828,
- "a1d1": -3.819956064224243,
- "a1c1": -4.67031192779541,
- "a1b1": -4.671708583831787,
- "e1g1": -2.415222644805908,
- "e1c1": -3.11667799949646
+ "h1h8": -1.3694086074829102,
+ "h1h7": -1.7002028226852417,
+ "h1h6": -2.521631956100464,
+ "h1h5": -2.8059098720550537,
+ "h1h4": -3.665440082550049,
+ "h1h3": -1.0190373659133911,
+ "h1h2": -2.051719903945923,
+ "h1g1": -2.0537755489349365,
+ "h1f1": -2.6322858333587646,
+ "e1f2": -2.468033790588379,
+ "e1e2": -2.9511985778808594,
+ "e1d2": -3.3517870903015137,
+ "e1f1": -3.569554090499878,
+ "e1d1": -3.3178837299346924,
+ "a1a8": -3.7825443744659424,
+ "a1a7": 1.193898320198059,
+ "a1a6": -1.3537575006484985,
+ "a1a5": -2.2938969135284424,
+ "a1a4": -3.113237142562866,
+ "a1a3": -4.172932147979736,
+ "a1a2": -4.560199737548828,
+ "a1d1": -3.38081693649292,
+ "a1c1": -4.555295467376709,
+ "a1b1": -5.129169940948486,
+ "e1g1": -1.7395941019058228,
+ "e1c1": -2.582695484161377
}
},
{
@@ -150,15 +150,15 @@
"a7a8n": -570
},
"expected_logits": {
- "e1f2": -1.6157597303390503,
- "e1e2": -2.5167014598846436,
- "e1d2": -3.0110926628112793,
- "e1f1": -5.081879615783691,
- "e1d1": -5.008589744567871,
- "a7a8q": -3.838310956954956,
- "a7a8r": -6.783886432647705,
- "a7a8b": -8.765006065368652,
- "a7a8n": -6.81964111328125
+ "e1f2": -2.0149426460266113,
+ "e1e2": -2.6541249752044678,
+ "e1d2": -3.3922789096832275,
+ "e1f1": -4.74859094619751,
+ "e1d1": -4.5840020179748535,
+ "a7a8q": -3.559063196182251,
+ "a7a8r": -7.680973529815674,
+ "a7a8b": -8.693378448486328,
+ "a7a8n": -6.955727577209473
}
},
{
@@ -173,12 +173,13 @@
"e8d7": 563
},
"expected_logits": {
- "e8f8": -5.282007217407227,
- "e8d8": 1.7908046245574951,
- "e8f7": -0.6711249947547913,
- "e8e7": -0.8237032294273376,
- "e8d7": -1.454167127609253
+ "e8f8": -5.969244480133057,
+ "e8d8": 0.5181062817573547,
+ "e8f7": -0.8433820605278015,
+ "e8e7": -1.0989807844161987,
+ "e8d7": -1.8043649196624756
}
}
- ]
+ ],
+ "model_sha256": "b075580ede7c87f7bb1375189d0d894d969e02579ed346efd3f0b116bc9aee87"
}
diff --git a/tools/human-policy/tests/test_dataset.py b/tools/human-policy/tests/test_dataset.py
index 430e7b7..f4df3aa 100644
--- a/tools/human-policy/tests/test_dataset.py
+++ b/tools/human-policy/tests/test_dataset.py
@@ -10,8 +10,9 @@
sys.path.insert(0, str(Path(__file__).parents[1]))
from dataset import encode_board, encode_move, encode_position, encode_rating
from extract_pgn import (
- headers_from_pgn_text, is_standard_rated_rapid, iter_pgn_text_games, iter_processed_games, open_pgn,
- rapid_time_control, split_for,
+ game_window, headers_from_pgn_text, is_standard_rated_rapid, iter_pgn_text_games,
+ iter_processed_games, open_pgn,
+ rapid_time_control, rating_band, split_for,
)
@@ -73,12 +74,17 @@ def test_training_row_requires_legal_label_and_encodes_rating(self):
encode_position(board, moves, selected, 1500, {"e2e4": 0})
def test_rating_range_is_explicit(self):
+ self.assertAlmostEqual(encode_rating(500), -1.4285714285714286)
self.assertEqual(encode_rating(800), -1.0)
self.assertEqual(encode_rating(2200), 1.0)
- for rating in (799, 2201):
+ for rating in (499, 2201):
with self.subTest(rating=rating), self.assertRaises(ValueError):
encode_rating(rating)
+ def test_inclusive_maximum_rating_stays_in_final_calibration_band(self):
+ self.assertEqual(rating_band(2199), "2000-2199")
+ self.assertEqual(rating_band(2200), "2000-2199")
+
def test_chess960_is_rejected(self):
with self.assertRaisesRegex(ValueError, "Chess960 is excluded"):
encode_board(chess.Board.from_chess960_pos(0))
@@ -121,6 +127,12 @@ def test_fast_pgn_header_scan_preserves_complete_accepted_game_text(self):
self.assertEqual(is_standard_rated_rapid(headers_from_pgn_text(games[1]))[1],
"not_rapid_or_unknown_time_control")
+ def test_game_window_skips_and_limits_archive_order_without_reordering(self):
+ games = iter(("game-0", "game-1", "game-2", "game-3", "game-4"))
+ self.assertEqual(list(game_window(games, skip_games=2, max_games=2)),
+ ["game-2", "game-3"])
+ self.assertEqual(list(game_window(iter(range(4)), skip_games=4, max_games=0)), [])
+
def test_parallel_game_parsing_matches_serial_and_preserves_archive_order(self):
text = (
'[Event "Rated Rapid game"]\n[Site "https://lichess.org/rapid-a"]\n'
@@ -142,6 +154,21 @@ def test_parallel_game_parsing_matches_serial_and_preserves_archive_order(self):
self.assertEqual(parallel, serial)
self.assertEqual([rows[0]["game_id"] if rows else reason for rows, reason in parallel],
["rapid-a", "skip_not_rated", "rapid-c"])
+ self.assertEqual(parallel[0][0][0]["game_date"], "")
+
+ def test_rating_filter_retains_in_range_mover_against_out_of_range_opponent(self):
+ text = ('[Event "Rated Rapid game"]\n[Site "https://lichess.org/boundary"]\n'
+ '[WhiteElo "2100"]\n[BlackElo "2300"]\n[TimeControl "600+0"]\n\n'
+ '1. e4 e5 2. Nf3 Nc6 1/2-1/2\n')
+ rows, reason = list(iter_processed_games([text], workers=1, minimum=500, maximum=2200))[0]
+ self.assertEqual(reason, "")
+ self.assertEqual([row["move"] for row in rows], ["e2e4", "g1f3"])
+ self.assertEqual([row["ply"] for row in rows], [0, 2])
+ self.assertTrue(all(row["rating"] == 2100 for row in rows))
+ rejected, reason = list(iter_processed_games(
+ [text.replace('"2100"', '"2400"')], workers=1, minimum=500, maximum=2200))[0]
+ self.assertIsNone(rejected)
+ self.assertEqual(reason, "skip_missing_or_out_of_range_rating")
def test_standard_rated_rapid_header_filter(self):
game = chess.pgn.Game()
diff --git a/tools/human-policy/tests/test_runtime_calibration.py b/tools/human-policy/tests/test_runtime_calibration.py
new file mode 100644
index 0000000..908c28d
--- /dev/null
+++ b/tools/human-policy/tests/test_runtime_calibration.py
@@ -0,0 +1,18 @@
+import sys
+import unittest
+from pathlib import Path
+sys.path.insert(0, str(Path(__file__).parents[1]))
+from runtime_calibration import settings_for_rating
+
+class RuntimeCalibrationTests(unittest.TestCase):
+ def test_interpolates_model_temperature_and_risk_at_exact_rating(self):
+ anchors = {
+ '600-799': dict(human_rating_band='600-799', display_rating=700, model_rating=1000, temperature=1),
+ '800-999': dict(human_rating_band='800-999', display_rating=900, model_rating=1200, temperature=1.2),
+ }
+ self.assertEqual(settings_for_rating(800, anchors, {'600-799': 1, '800-999': 1.5}), (1100, 1.1, 1.25))
+ self.assertEqual(settings_for_rating(2200, anchors, {}), (1200, 1.2, 0))
+ self.assertEqual(settings_for_rating(500, anchors, {}), (1000, 1, 0))
+
+ def test_identity_without_map(self):
+ self.assertEqual(settings_for_rating(2200, None, {'2000-2199': .5}), (2200, 1, .5))
diff --git a/tools/human-policy/tests/test_train.py b/tools/human-policy/tests/test_train.py
new file mode 100644
index 0000000..f3725e7
--- /dev/null
+++ b/tools/human-policy/tests/test_train.py
@@ -0,0 +1,22 @@
+import unittest
+import sys
+from pathlib import Path
+
+sys.path.insert(0, str(Path(__file__).parents[1]))
+from train import rating_band, rating_balanced_weights
+
+
+class TrainingRatingBandTests(unittest.TestCase):
+ def test_balancing_gives_rare_and_common_bands_equal_total_weight(self):
+ weights = rating_balanced_weights([{"rating": 500}] + [{"rating": 1500}] * 9)
+ self.assertAlmostEqual(weights[0], sum(weights[1:]))
+ self.assertEqual(rating_balanced_weights([]), [])
+
+ def test_inclusive_2200_endpoint_stays_in_last_band(self):
+ self.assertEqual(rating_band(500), "400-599")
+ self.assertEqual(rating_band(2199), "2000-2199")
+ self.assertEqual(rating_band(2200), "2000-2199")
+
+
+if __name__ == "__main__":
+ unittest.main()
diff --git a/tools/human-policy/train.py b/tools/human-policy/train.py
index c3d1b8f..0c59ad8 100644
--- a/tools/human-policy/train.py
+++ b/tools/human-policy/train.py
@@ -1,9 +1,10 @@
#!/usr/bin/env python3
-"""Train the Sapling human move policy on CUDA using pre-analyzed JSONL splits."""
+"""Train the Sapling human move policy on a GPU or CPU using scored JSONL splits."""
from __future__ import annotations
import argparse
+from collections import Counter
import json
import math
import random
@@ -15,9 +16,9 @@
import torch
import torch.nn.functional as F
import yaml
-from torch.utils.data import DataLoader, Dataset
+from torch.utils.data import DataLoader, Dataset, WeightedRandomSampler
-from dataset import SCHEMA_VERSION, encode_position
+from dataset import MAX_RATING, SCHEMA_VERSION, encode_position
from model import HumanMovePolicy
@@ -55,10 +56,24 @@ def __getitem__(self, index):
"rating": np.asarray([rating], dtype=np.float32),
"target": target,
"ply": int(row["ply"]),
- "rating_band": f"{(int(row['rating']) // 200) * 200}-{(int(row['rating']) // 200) * 200 + 199}",
+ "rating_band": rating_band(int(row["rating"])),
}
+def rating_band(rating: int) -> str:
+ # The configured maximum is inclusive and belongs to the final calibration band.
+ bounded = min(rating, MAX_RATING - 1)
+ lower = (bounded // 200) * 200
+ return f"{lower}-{lower + 199}"
+
+
+def rating_balanced_weights(rows):
+ """Give each represented rating band equal total sampling weight."""
+ bands = [rating_band(int(row["rating"])) for row in rows]
+ counts = Counter(bands)
+ return [1.0 / counts[band] for band in bands]
+
+
def collate_positions(rows):
batch_size = len(rows)
max_moves = max(len(row["moves"]) for row in rows)
@@ -90,6 +105,7 @@ def evaluate(model, loader, device):
total_top1 = 0
total_top3 = 0
total_uniform_nll = 0.0
+ total_expected_match = 0.0
by_rating = {}
by_stage = {"opening": {}, "middlegame": {}, "endgame": {}}
with torch.no_grad():
@@ -108,13 +124,15 @@ def evaluate(model, loader, device):
valid_counts = mask.sum(dim=1).float()
uniform = valid_counts.log()
+ total_expected_match += (-losses).exp().sum().item()
total_nll += losses.sum().item()
total_positions += len(target)
total_top1 += top1.sum().item()
total_top3 += top3.sum().item()
total_uniform_nll += uniform.sum().item()
for i, band in enumerate(batch["rating_band"]):
- row = by_rating.setdefault(band, {"nll": 0.0, "top1": 0, "top3": 0, "count": 0})
+ row = by_rating.setdefault(band, {"nll": 0.0, "top1": 0, "top3": 0, "expected_match": 0.0, "count": 0})
+ row["expected_match"] += float((-losses[i]).exp().item())
row["nll"] += losses[i].item()
row["top1"] += int(top1[i].item())
row["top3"] += int(top3[i].item())
@@ -129,7 +147,7 @@ def finalize(rows):
band: {
"positions": row["count"],
"nll": row["nll"] / row["count"],
- **({"top1": row["top1"] / row["count"], "top3": row["top3"] / row["count"]}
+ **({"top1": row["top1"] / row["count"], "top3": row["top3"] / row["count"], "expected_match": row["expected_match"] / row["count"]}
if "top1" in row else {}),
}
for band, row in sorted(rows.items())
@@ -138,6 +156,7 @@ def finalize(rows):
return {
"positions": total_positions,
"nll": total_nll / total_positions,
+ "expected_match": total_expected_match / total_positions,
"top1": total_top1 / total_positions,
"top3": total_top3 / total_positions,
"uniform_legal_move_nll": total_uniform_nll / total_positions,
@@ -153,9 +172,13 @@ def main() -> int:
config = yaml.safe_load(args.config.read_text(encoding="utf-8"))
if config.get("ablation", "none") not in ("none", "rating", "engine"):
parser.error("ablation must be none, rating, or engine")
- if not torch.cuda.is_available():
- raise RuntimeError("CUDA is required for this training run; torch.cuda.is_available() is false")
- device = torch.device("cuda")
+ device_name = str(config.get("device", "cuda"))
+ if device_name == "cuda" and not torch.cuda.is_available():
+ raise RuntimeError("CUDA was requested but torch.cuda.is_available() is false")
+ if device_name not in {"cuda", "cpu"}:
+ raise ValueError("device must be 'cuda' or 'cpu'")
+ device = torch.device(device_name)
+ torch.set_num_threads(int(config.get("torch_num_threads", torch.get_num_threads())))
dataset_dir = Path(config["dataset_dir"])
manifest = json.loads((dataset_dir / "manifest.json").read_text(encoding="utf-8"))
if manifest.get("encoder_schema_version") != SCHEMA_VERSION or "engine_analysis" not in manifest:
@@ -165,7 +188,8 @@ def main() -> int:
random.seed(seed)
np.random.seed(seed)
torch.manual_seed(seed)
- torch.cuda.manual_seed_all(seed)
+ if device.type == "cuda":
+ torch.cuda.manual_seed_all(seed)
if config.get("deterministic", False):
torch.use_deterministic_algorithms(True)
@@ -175,12 +199,23 @@ def main() -> int:
loader_options = {
"batch_size": int(config.get("batch_size", 128)),
"num_workers": workers,
- "pin_memory": True,
+ "pin_memory": device.type == "cuda",
"collate_fn": collate_positions,
}
- train_loader = DataLoader(train_data, shuffle=True, **loader_options)
+ sampler = None
+ if config.get("rating_balanced_sampling", False):
+ sampler = WeightedRandomSampler(rating_balanced_weights(train_data.rows),
+ len(train_data), replacement=True)
+ train_loader = DataLoader(train_data, shuffle=sampler is None, sampler=sampler, **loader_options)
validation_loader = DataLoader(validation_data, shuffle=False, **loader_options)
- model = HumanMovePolicy().to(device)
+ model = HumanMovePolicy()
+ initial_checkpoint = config.get("initial_checkpoint")
+ if initial_checkpoint:
+ initial = torch.load(Path(initial_checkpoint), map_location="cpu", weights_only=False)
+ if initial.get("schema_version") != SCHEMA_VERSION:
+ raise ValueError("initial checkpoint schema version does not match")
+ model.load_state_dict(initial["model_state_dict"], strict=True)
+ model = model.to(device)
optimizer = torch.optim.AdamW(
model.parameters(),
lr=float(config.get("learning_rate", 1e-3)),
@@ -193,7 +228,8 @@ def main() -> int:
history = []
patience = int(config.get("early_stopping_patience", 3))
- print(json.dumps({"config": config, "device": torch.cuda.get_device_name(0),
+ resolved_device = torch.cuda.get_device_name(0) if device.type == "cuda" else "CPU"
+ print(json.dumps({"config": config, "device": resolved_device,
"train_positions": len(train_data), "validation_positions": len(validation_data)}, sort_keys=True),
file=sys.stderr)
for epoch in range(1, int(config.get("epochs", 10)) + 1):
@@ -221,6 +257,7 @@ def main() -> int:
"model_state_dict": model.state_dict(),
"schema_version": SCHEMA_VERSION,
"config": config,
+ "initial_checkpoint": str(initial_checkpoint) if initial_checkpoint else None,
"epoch": epoch,
"validation_metrics": metrics,
"engine_analysis": manifest["engine_analysis"],
diff --git a/web/README.md b/web/README.md
index fcff283..737fc91 100644
--- a/web/README.md
+++ b/web/README.md
@@ -41,10 +41,15 @@ restore, hint scoring and Elo restoration. Run the built static app in a browser
interaction checks before release.
The trained policy's weights are embedded in `Sapling.Engine` and its inference runs in the
-same C# engine code for native UCI and browser WASM builds. Human Elo values from 800 to 2200
+same C# engine code for native UCI and browser WASM builds. Human Elo values from 500 to 2200
select the policy; zero disables it. The web build ships no separate policy model or inference
runtime.
+Move hints use full-strength analysis of all legal moves. Ordinary badges show `Best` or the
+pawn-equivalent evaluation lost against the best move, regardless of whether the position is winning
+or losing. Mate labels keep their existing format and resulting-position distance; only move-quality
+comparisons substitute ±20 pawns for mate scores.
+
## Wasm profiles (4.6)
Measured nodes/second for the **published** artifacts (Node-hosted `browser-wasm`, identical
diff --git a/web/app.js b/web/app.js
index a263264..83f8b84 100644
--- a/web/app.js
+++ b/web/app.js
@@ -1,6 +1,6 @@
// Web UI controller; chess rules and game history come from the engine.
-import { eloFromSliderValue, eloLabelForSliderValue, formatEngineEval, formatMoveScore,
+import { eloFromSliderValue, eloLabelForSliderValue, formatEngineEval, formatMoveScore, formatHintScore,
FULL_ENGINE_SLIDER_VALUE } from './ui-model.js';
const INITIAL_FEN = 'rnbqkbnr/pppppppp/8/8/8/8/PPPPPPPP/RNBQKBNR w KQkq - 0 1';
@@ -178,6 +178,7 @@ function render() {
const badge = document.createElement('span');
badge.className = 'hint-score';
badge.textContent = hint.label;
+ badge.title = hint.scoreType === 'mate' ? hint.label : `${(hint.lossCp / 100).toFixed(2)} pawns lost versus the best legal move`;
cell.appendChild(badge);
}
@@ -432,10 +433,6 @@ function updateHintScores(msg) {
render();
}
-function formatHintScore(score) {
- if (score.scoreType === 'mate') return score.score > 0 ? `M${Math.abs(score.score)}` : `-M${Math.abs(score.score)}`;
- return (score.score >= 0 ? '+' : '') + (score.score / 100).toFixed(1);
-}
function toggleHintMode() {
if (hinting || restoring) return;
diff --git a/web/index.html b/web/index.html
index a6d20c3..41ffb13 100644
--- a/web/index.html
+++ b/web/index.html
@@ -128,7 +128,7 @@ Sapling
Level 3000+ · Full engine
-
diff --git a/web/tests/ui-contract.test.js b/web/tests/ui-contract.test.js
index 6600aa3..5946b47 100644
--- a/web/tests/ui-contract.test.js
+++ b/web/tests/ui-contract.test.js
@@ -8,6 +8,7 @@ import {
eloLabelForSliderValue,
formatEngineEval,
formatMoveScore,
+ formatHintScore,
FULL_ENGINE_SLIDER_VALUE,
} from '../ui-model.js';
@@ -15,19 +16,19 @@ const webRoot = path.resolve(path.dirname(fileURLToPath(import.meta.url)), '..')
const read = (name) => readFile(path.join(webRoot, name), 'utf8');
test('Human Elo slider maps endpoints and all configured ratings', () => {
- assert.equal(eloFromSliderValue(0), 800);
- assert.equal(eloFromSliderValue(140), 2200);
+ assert.equal(eloFromSliderValue(0), 500);
+ assert.equal(eloFromSliderValue(170), 2200);
assert.equal(eloFromSliderValue(FULL_ENGINE_SLIDER_VALUE), 0);
- assert.deepEqual(Array.from({ length: 141 }, (_, step) => eloFromSliderValue(step)),
- Array.from({ length: 141 }, (_, step) => 800 + step * 10));
+ assert.deepEqual(Array.from({ length: 171 }, (_, step) => eloFromSliderValue(step)),
+ Array.from({ length: 171 }, (_, step) => 500 + step * 10));
assert.throws(() => eloFromSliderValue(-1), RangeError);
- assert.throws(() => eloFromSliderValue(142), RangeError);
+ assert.throws(() => eloFromSliderValue(172), RangeError);
assert.throws(() => eloFromSliderValue(1.5), RangeError);
});
test('Human Elo labels distinguish trained ratings from full engine', () => {
- assert.equal(eloLabelForSliderValue(0), '≈800 Elo');
- assert.equal(eloLabelForSliderValue(140), '≈2200 Elo');
+ assert.equal(eloLabelForSliderValue(0), '≈500 Elo');
+ assert.equal(eloLabelForSliderValue(170), '≈2200 Elo');
assert.equal(eloLabelForSliderValue(FULL_ENGINE_SLIDER_VALUE), '3000+ · Full engine');
});
@@ -69,3 +70,12 @@ test('all piece image paths used by the board are present', async () => {
}
}
});
+
+test('hints show move quality independently of position advantage and preserve mates', () => {
+ assert.equal(formatHintScore({ scoreType: 'cp', score: -900, lossCp: 0 }), 'Best');
+ assert.equal(formatHintScore({ scoreType: 'cp', score: 900, lossCp: 150 }), '−1.5');
+ assert.equal(formatHintScore({ scoreType: 'cp', score: 30, lossCp: 1 }), '−0.01');
+ assert.equal(formatHintScore({ scoreType: 'mate', score: 2, lossCp: 0 }), 'M2');
+ assert.equal(formatHintScore({ scoreType: 'mate', score: -1, lossCp: 0 }), '-M1');
+ assert.equal(formatHintScore({ scoreType: 'mate', score: 0, lossCp: 0 }), '-M0');
+});
diff --git a/web/ui-model.js b/web/ui-model.js
index 095e8ee..1b31649 100644
--- a/web/ui-model.js
+++ b/web/ui-model.js
@@ -1,11 +1,11 @@
-export const FULL_ENGINE_SLIDER_VALUE = 141;
+export const FULL_ENGINE_SLIDER_VALUE = 171;
export function eloFromSliderValue(value) {
const step = Number(value);
if (!Number.isInteger(step) || step < 0 || step > FULL_ENGINE_SLIDER_VALUE) {
- throw new RangeError('Human-style slider value must be an integer from 0 to 141.');
+ throw new RangeError('Human-style slider value must be an integer from 0 to 171.');
}
- return step === FULL_ENGINE_SLIDER_VALUE ? 0 : 800 + step * 10;
+ return step === FULL_ENGINE_SLIDER_VALUE ? 0 : 500 + step * 10;
}
export function eloLabelForSliderValue(value) {
@@ -24,3 +24,10 @@ export function formatEngineEval(type, score, side) {
if (type === 'mate') return (whiteScore > 0 ? 'M' : 'M-') + Math.abs(whiteScore);
return (whiteScore / 100).toFixed(2);
}
+
+export function formatHintScore(score) {
+ if (score.scoreType === 'mate') return score.score > 0 ? `M${Math.abs(score.score)}` : `-M${Math.abs(score.score)}`;
+ if (score.lossCp === 0) return 'Best';
+ const loss = Math.max(0, score.lossCp) / 100;
+ return `−${loss.toFixed(loss < 0.1 ? 2 : 1)}`;
+}
diff --git a/web/worker.js b/web/worker.js
index 1decf1b..71e5232 100644
--- a/web/worker.js
+++ b/web/worker.js
@@ -176,32 +176,21 @@ async function runHints(req) {
const scores = [];
let error = '';
- for (const move of req.moves || []) {
- if (activeHintId !== id) return;
- let result = parse(host.SetPosition(String(req.fen || '')));
- if (result.ok) result = parse(host.ApplyMove(String(move)));
- if (!result.ok) { error = result.message || result.error || 'Could not apply move.'; break; }
-
- const searchId = ++currentRequest;
- stopFlags.delete(searchId);
- result = parse(host.StartSearch(searchId, 5, 1800, 5000, 45));
- if (!result.ok) { error = result.message || result.error || 'Could not start analysis.'; break; }
-
- while (true) {
- if (activeHintId !== id) return;
- result = parse(host.SearchSlice(searchId));
- if (!result.ok || result.done) break;
- await new Promise((resolve) => setTimeout(resolve, 0));
+ let result = parse(host.SetPosition(String(req.fen || '')));
+ if (result.ok) result = parse(host.ScoreHints());
+ if (!result.ok) {
+ error = result.message || result.error || 'Move analysis failed.';
+ } else {
+ const requested = new Set(req.moves || []);
+ for (let i = 0; i < result.moves.length; i++) {
+ const move = result.moves[i];
+ if (!requested.has(move)) continue;
+ // Root mate distance includes this move; badges describe the resulting position.
+ const score = result.scoreTypes[i] === 'mate' && result.scores[i] > 0
+ ? result.scores[i] - 1 : result.scores[i];
+ scores.push({ move, score, scoreType: result.scoreTypes[i],
+ rankScore: result.rankScores[i], lossCp: result.lossCp[i] });
}
- if (!result.ok) { error = result.message || result.error || 'Move analysis failed.'; break; }
-
- const score = -(result.score || 0);
- const scoreType = result.scoreType || 'cp';
- const rankScore = scoreType === 'mate'
- ? score > 0 ? 100000 - Math.abs(score) : -100000 + Math.abs(score)
- : score;
- scores.push({ move, score, scoreType, rankScore });
- scores.sort((a, b) => b.rankScore - a.rankScore);
post({ type: 'hint-progress', hintId: id, scores });
}