eyeling 1.17.2 → 1.18.0

package/examples/pn-junction-tunneling.n3

@@ -0,0 +1,227 @@
+# ===========================================================================
+# pn-junction-tunneling.n3
+#
+# - ordinary depletion width  = 8 nm
+# - tunnel depletion width    = 1 nm
+# - filled N-side states      = [1, 2, 3, 4]
+# - empty P-side states @ 0V  = [3, 4, 5, 6]
+# - bias points               = 0..6
+#
+# For each bias, the empty P-side levels shift downward by the bias amount.
+# A shifted level contributes 1 to the current proxy exactly when it lands in
+# the occupied N-side window [1, 4]. The four slot contributions are summed.
+# ===========================================================================
+
+@prefix : <http://example.org/pn-junction-tunneling#> .
+@prefix log: <http://www.w3.org/2000/10/swap/log#> .
+@prefix math: <http://www.w3.org/2000/10/swap/math#> .
+@prefix list: <http://www.w3.org/2000/10/swap/list#> .
+@prefix string: <http://www.w3.org/2000/10/swap/string#> .
+
+# -----
+# Facts
+# -----
+
+:case :name "pn-junction-tunneling" .
+:case :ordinaryDepletionWidthNm 8 .
+:case :tunnelDepletionWidthNm 1 .
+:case :nFilledLevels (1 2 3 4) .
+:case :pEmptyZeroBiasLevels (3 4 5 6) .
+
+:b0 :value 0 .
+:b1 :value 1 .
+:b2 :value 2 .
+:b3 :value 3 .
+:b4 :value 4 .
+:b5 :value 5 .
+:b6 :value 6 .
+
+# -----
+# Logic
+# -----
+
+# Heavy doping is modeled as a much narrower depletion region.
+{ :case :tunnelDepletionWidthNm ?t .
+  :case :ordinaryDepletionWidthNm ?o .
+  ?t math:lessThan ?o .
+}
+    => { :case :barrierIsNarrower true . } .
+
+# For each bias node and each zero-bias P-side slot, shift the level downward:
+# shifted = zeroBiasLevel - bias.
+{ ?bnode list:in (:b0 :b1 :b2 :b3 :b4 :b5 :b6) .
+  ?bnode :value ?bias .
+  :case :pEmptyZeroBiasLevels ?levels .
+  ?levels list:iterate ( ?slot ?zeroLevel ) .
+  ( ?zeroLevel ?bias ) math:difference ?shifted .
+}
+    => { ( ?bnode ?slot ) :shiftedLevel ?shifted . } .
+
+# Each shifted slot contributes 1 when it falls inside the occupied N-side
+# window [1, 4], otherwise 0.
+{ ( ?bnode ?slot ) :shiftedLevel ?shifted .
+  ?shifted math:notLessThan 1 .
+  ?shifted math:notGreaterThan 4 .
+}
+    => { ( ?bnode ?slot ) :overlapValue 1 . } .
+
+{ ( ?bnode ?slot ) :shiftedLevel ?shifted .
+  ?shifted math:lessThan 1 .
+}
+    => { ( ?bnode ?slot ) :overlapValue 0 . } .
+
+{ ( ?bnode ?slot ) :shiftedLevel ?shifted .
+  ?shifted math:greaterThan 4 .
+}
+    => { ( ?bnode ?slot ) :overlapValue 0 . } .
+
+# The current proxy is the sum of the four slot contributions.
+{ ( ?bnode 0 ) :overlapValue ?v0 .
+  ( ?bnode 1 ) :overlapValue ?v1 .
+  ( ?bnode 2 ) :overlapValue ?v2 .
+  ( ?bnode 3 ) :overlapValue ?v3 .
+  ( ?v0 ?v1 ?v2 ?v3 ) math:sum ?current .
+}
+    => { ?bnode :currentProxy ?current . } .
+
+# Peak = the unique maximum at bias 2 in this toy curve.
+{ :b2 :currentProxy ?peak .
+  :b0 :currentProxy ?c0 . ?peak math:greaterThan ?c0 .
+  :b1 :currentProxy ?c1 . ?peak math:greaterThan ?c1 .
+  :b3 :currentProxy ?c3 . ?peak math:greaterThan ?c3 .
+  :b4 :currentProxy ?c4 . ?peak math:greaterThan ?c4 .
+  :b5 :currentProxy ?c5 . ?peak math:greaterThan ?c5 .
+  :b6 :currentProxy ?c6 . ?peak math:greaterThan ?c6 .
+}
+    => { :case :peakBias 2 .
+         :case :peakCurrent ?peak . } .
+
+# High-bias valley = the final sampled point, matching the Rust code.
+{ :b6 :currentProxy ?valley . }
+    => { :case :valleyBias 6 .
+         :case :valleyCurrent ?valley . } .
+
+# A negative differential region is present once the curve drops after the peak.
+{ :b2 :currentProxy ?c2 .
+  :b3 :currentProxy ?c3 .
+  ?c2 math:greaterThan ?c3 .
+}
+    => { :case :negativeDifferentialRegion true . } .
+
+{ :case :peakBias ?peakBias .
+  :case :valleyBias ?valleyBias .
+  ?peakBias math:lessThan ?valleyBias .
+}
+    => { :case :peakIsBeforeValley true . } .
+
+{ :case :valleyCurrent 0 . }
+    => { :case :overlapClosesAtHighBias true . } .
+
+{ :case :peakCurrent ?peakCurrent .
+  :case :nFilledLevels ?nLevels .
+  ?nLevels list:length ?nCount .
+  ?peakCurrent math:equalTo ?nCount .
+}
+    => { :case :peakMatchesFullOverlap true . } .
+
+# -----------------------------------------------
+# Presentation (ARC: Answer • Reason Why • Check)
+# -----------------------------------------------
+
+# Answer
+{ :case :peakBias ?peakBias .
+  :case :peakCurrent ?peakCurrent .
+  :case :negativeDifferentialRegion true .
+  ( "peak bias                     : %s\n" ?peakBias ) string:format ?peakBiasLine .
+  ( "peak current proxy            : %s\n" ?peakCurrent ) string:format ?peakCurrentLine .
+}
+    => {
+         :01-answer-1 log:outputString "=== Answer ===\n" .
+         :01-answer-2 log:outputString "In this toy PN-junction tunneling model, heavy doping narrows the depletion region enough for a tunneling window that rises to a peak and then falls, producing a negative-differential region.\n" .
+         :01-answer-3 log:outputString "case                          : pn-junction-tunneling\n" .
+         :01-answer-4 log:outputString ?peakBiasLine .
+         :01-answer-5 log:outputString ?peakCurrentLine .
+         :01-answer-6 log:outputString "negative differential region  : yes\n\n" .
+       } .
+
+# Reason Why
+{ :case :ordinaryDepletionWidthNm ?ordinary .
+  :case :tunnelDepletionWidthNm ?tunnel .
+  :b0 :currentProxy ?c0 .
+  :b1 :currentProxy ?c1 .
+  :b2 :currentProxy ?c2 .
+  :b3 :currentProxy ?c3 .
+  :b4 :currentProxy ?c4 .
+  :b5 :currentProxy ?c5 .
+  :b6 :currentProxy ?c6 .
+  :case :peakBias ?peakBias .
+  :case :peakCurrent ?peakCurrent .
+  :case :valleyBias ?valleyBias .
+  :case :valleyCurrent ?valleyCurrent .
+  ( "%s->%s, %s->%s, %s->%s, %s->%s, %s->%s, %s->%s, %s->%s"
+    0 ?c0 1 ?c1 2 ?c2 3 ?c3 4 ?c4 5 ?c5 6 ?c6 ) string:format ?curve .
+  ( "ordinary depletion width (nm) : %s\n" ?ordinary ) string:format ?ordinaryLine .
+  ( "tunnel depletion width (nm)   : %s\n" ?tunnel ) string:format ?tunnelLine .
+  ( "bias -> overlap current proxy : %s\n" ?curve ) string:format ?curveLine .
+  ( "peak point                    : %s -> %s\n" ?peakBias ?peakCurrent ) string:format ?peakLine .
+  ( "high-bias point               : %s -> %s\n" ?valleyBias ?valleyCurrent ) string:format ?valleyLine .
+}
+    => {
+         :02-why-1 log:outputString "=== Reason Why ===\n" .
+         :02-why-2 log:outputString "We model tunneling current as an exact overlap count between filled N-side states and empty P-side states while forward bias shifts the bands. Heavy doping is represented by a much narrower depletion region.\n" .
+         :02-why-3 log:outputString ?ordinaryLine .
+         :02-why-4 log:outputString ?tunnelLine .
+         :02-why-5 log:outputString "filled N-side states          : [1, 2, 3, 4]\n" .
+         :02-why-6 log:outputString "empty P-side states at 0 bias : [3, 4, 5, 6]\n" .
+         :02-why-7 log:outputString ?curveLine .
+         :02-why-8 log:outputString ?peakLine .
+         :02-why-9 log:outputString ?valleyLine .
+         :02-why-99 log:outputString "\n" .
+       } .
+
+# Check
+{ :case :barrierIsNarrower true .
+  :case :peakIsBeforeValley true .
+  :case :negativeDifferentialRegion true .
+  :case :overlapClosesAtHighBias true .
+  :case :peakMatchesFullOverlap true .
+}
+    => {
+         :03-check-1 log:outputString "=== Check ===\n" .
+         :03-check-2 log:outputString "heavily doped barrier is narrower : yes\n" .
+         :03-check-3 log:outputString "peak occurs before overlap closes : yes\n" .
+         :03-check-4 log:outputString "negative differential region present : yes\n" .
+         :03-check-5 log:outputString "high-bias overlap closes           : yes\n" .
+         :03-check-6 log:outputString "peak equals full four-state overlap: yes\n" .
+       } .
+
+# ------------------
+# Verification fuses
+# ------------------
+
+# If any of the key invariants fail, stop the run loudly.
+
+{ :case :tunnelDepletionWidthNm ?t .
+  :case :ordinaryDepletionWidthNm ?o .
+  ?t math:notLessThan ?o .
+} => false .
+
+{ :case :peakBias ?peakBias .
+  :case :valleyBias ?valleyBias .
+  ?peakBias math:notLessThan ?valleyBias .
+} => false .
+
+{ :b2 :currentProxy ?c2 .
+  :b3 :currentProxy ?c3 .
+  ?c2 math:notGreaterThan ?c3 .
+} => false .
+
+{ :case :valleyCurrent ?valleyCurrent .
+  ?valleyCurrent math:notEqualTo 0 .
+} => false .
+
+{ :case :peakCurrent ?peakCurrent .
+  :case :nFilledLevels ?nLevels .
+  ?nLevels list:length ?nCount .
+  ?peakCurrent math:notEqualTo ?nCount .
+} => false .

package/examples/sudoku.n3

@@ -0,0 +1,257 @@
+# ==================================================
+# sudoku.n3
+#
+# A standalone Sudoku solver and report generator.
+#
+# Edit :case :puzzle to solve another puzzle.
+# Accepted blanks: 0, ., _
+# Whitespace and ASCII board separators are ignored.
+# ==================================================
+
+@prefix : <http://example.org/sudoku#> .
+@prefix log: <http://www.w3.org/2000/10/swap/log#> .
+@prefix string: <http://www.w3.org/2000/10/swap/string#> .
+@prefix sb: <http://example.org/sudoku-builtin#> .
+
+# -----
+# Facts
+# -----
+
+:case :name "sudoku" .
+:case :puzzleName "classic" .
+:case :puzzle "100007090030020008009600500005300900010080002600004000300000010040000007007000300" .
+
+# ------------------------------------
+# Report facts from the solver builtin
+# ------------------------------------
+
+{ :case :puzzle ?p .
+  ?p sb:status ?status .
+  ?p sb:normalizedPuzzle ?normalized .
+  ?p sb:givens ?givens .
+  ?p sb:blanks ?blanks .
+  ?p sb:puzzleText ?puzzleText .
+}
+    => {
+         :case :status ?status ;
+               :normalizedPuzzle ?normalized ;
+               :givens ?givens ;
+               :blanks ?blanks ;
+               :puzzleText ?puzzleText .
+       } .
+
+{ :case :puzzle ?p .
+  ?p sb:status "ok" .
+  ?p sb:solution ?solution ;
+     sb:solutionText ?solutionText ;
+     sb:forcedMoves ?forced ;
+     sb:guessedMoves ?guessed ;
+     sb:recursiveNodes ?nodes ;
+     sb:backtracks ?backtracks ;
+     sb:maxDepth ?maxDepth ;
+     sb:unique ?unique ;
+     sb:moveSummary ?moveSummary ;
+     sb:givensPreservedText ?givensPreserved ;
+     sb:noBlanksText ?noBlanks ;
+     sb:rowsCompleteText ?rowsComplete ;
+     sb:colsCompleteText ?colsComplete ;
+     sb:boxesCompleteText ?boxesComplete ;
+     sb:replayLegalText ?replayLegal ;
+     sb:storyConsistentText ?storyConsistent .
+}
+    => {
+         :case :solution ?solution ;
+               :solutionText ?solutionText ;
+               :forcedMoves ?forced ;
+               :guessedMoves ?guessed ;
+               :recursiveNodes ?nodes ;
+               :backtracks ?backtracks ;
+               :maxDepth ?maxDepth ;
+               :unique ?unique ;
+               :moveSummary ?moveSummary ;
+               :givensPreserved ?givensPreserved ;
+               :noBlanks ?noBlanks ;
+               :rowsComplete ?rowsComplete ;
+               :colsComplete ?colsComplete ;
+               :boxesComplete ?boxesComplete ;
+               :replayLegal ?replayLegal ;
+               :storyConsistent ?storyConsistent .
+       } .
+
+{ :case :puzzle ?p .
+  ?p sb:status ?status .
+  ?status string:notEqualIgnoringCase "ok" .
+  ?p sb:error ?error .
+}
+    => { :case :error ?error . } .
+
+# ------------
+# Presentation
+# ------------
+
+# Successful solve, unique.
+{ :case :status "ok" .
+  :case :unique true .
+  :case :givens ?givens ;
+        :blanks ?blanks ;
+        :forcedMoves ?forced ;
+        :guessedMoves ?guessed ;
+        :recursiveNodes ?nodes ;
+        :backtracks ?backtracks ;
+        :moveSummary ?moveSummary ;
+        :puzzleText ?puzzleText ;
+        :solutionText ?solutionText .
+  ( "The puzzle is solved, and the completed grid is the unique valid Sudoku solution.\n" ) string:concatenation ?answerText .
+  ( "The solver starts from %s clues and fills the remaining %s cells by combining constraint propagation with depth-first search. At each step it chooses the empty cell with the fewest legal digits, places forced singles immediately, and only guesses when more than one candidate remains. Across the search it made %s forced placements and tried %s guesses, visited %s search nodes overall, and backtracked %s times before reaching the completed grid. The solver also confirmed that the solution is unique. Early steps: %s"
+    ?givens ?blanks ?forced ?guessed ?nodes ?backtracks ?moveSummary ) string:format ?reasonText .
+}
+    => {
+         :01-answer log:outputString "=== Answer ===\n" ;
+                    log:outputString ?answerText .
+         :01a-answer log:outputString "case              : sudoku\n" ;
+                     log:outputString "default puzzle    : classic\n\n" ;
+                     log:outputString "Puzzle\n" ;
+                     log:outputString ?puzzleText ;
+                     log:outputString "\n" ;
+                     log:outputString "Completed grid\n" ;
+                     log:outputString ?solutionText ;
+                     log:outputString "\n" .
+         :02-reason log:outputString "=== Reason Why ===\n" ;
+                    log:outputString ?reasonText ;
+                    log:outputString "\n\n" .
+       } .
+
+# Successful solve, not unique.
+{ :case :status "ok" .
+  :case :unique false .
+  :case :givens ?givens ;
+        :blanks ?blanks ;
+        :forcedMoves ?forced ;
+        :guessedMoves ?guessed ;
+        :recursiveNodes ?nodes ;
+        :backtracks ?backtracks ;
+        :moveSummary ?moveSummary ;
+        :puzzleText ?puzzleText ;
+        :solutionText ?solutionText .
+  ( "The puzzle is solved, and the completed grid is a valid Sudoku solution.\n" ) string:concatenation ?answerText .
+  ( "The solver starts from %s clues and fills the remaining %s cells by combining constraint propagation with depth-first search. At each step it chooses the empty cell with the fewest legal digits, places forced singles immediately, and only guesses when more than one candidate remains. Across the search it made %s forced placements and tried %s guesses, visited %s search nodes overall, and backtracked %s times before reaching the completed grid. The solver found a valid solution, but there is more than one. Early steps: %s"
+    ?givens ?blanks ?forced ?guessed ?nodes ?backtracks ?moveSummary ) string:format ?reasonText .
+}
+    => {
+         :01-answer log:outputString "=== Answer ===\n" ;
+                    log:outputString ?answerText .
+         :01a-answer log:outputString "case              : sudoku\n" ;
+                     log:outputString "default puzzle    : classic\n\n" ;
+                     log:outputString "Puzzle\n" ;
+                     log:outputString ?puzzleText ;
+                     log:outputString "\n" ;
+                     log:outputString "Completed grid\n" ;
+                     log:outputString ?solutionText ;
+                     log:outputString "\n" .
+         :02-reason log:outputString "=== Reason Why ===\n" ;
+                    log:outputString ?reasonText ;
+                    log:outputString "\n\n" .
+       } .
+
+# Invalid input length / characters.
+{ :case :status "invalid-input" .
+  :case :error ?error .
+}
+    => {
+         :01-answer log:outputString "=== Answer ===\n" ;
+                    log:outputString "The supplied puzzle is not well formed and cannot be parsed as a 9×9 Sudoku.\n" ;
+                    log:outputString "case              : sudoku\n\n" .
+         :02-reason log:outputString "=== Reason Why ===\n" ;
+                    log:outputString ?error ;
+                    log:outputString "\n\n" .
+       } .
+
+# Illegal clues.
+{ :case :status "illegal-clues" .
+  :case :puzzleText ?puzzleText ;
+        :error ?error .
+}
+    => {
+         :01-answer log:outputString "=== Answer ===\n" ;
+                    log:outputString "The puzzle is invalid and cannot be solved as a standard Sudoku.\n" ;
+                    log:outputString "case              : sudoku\n\n" ;
+                    log:outputString "Puzzle\n" ;
+                    log:outputString ?puzzleText ;
+                    log:outputString "\n" .
+         :02-reason log:outputString "=== Reason Why ===\n" ;
+                    log:outputString ?error ;
+                    log:outputString "\n\n" .
+       } .
+
+# Unsatisfiable puzzle.
+{ :case :status "unsatisfiable" .
+  :case :givens ?givens ;
+        :blanks ?blanks ;
+        :recursiveNodes ?nodes ;
+        :backtracks ?backtracks ;
+        :puzzleText ?puzzleText .
+  ( "The solver explored %s search nodes with minimum-remaining-values branching and backtracked %s times, but every branch eventually contradicted the row, column, or box constraints."
+    ?nodes ?backtracks ) string:format ?reasonText .
+}
+    => {
+         :01-answer log:outputString "=== Answer ===\n" ;
+                    log:outputString "No valid Sudoku solution exists for the supplied puzzle.\n" ;
+                    log:outputString "case                         : sudoku\n" ;
+                    log:outputString "default puzzle               : classic\n" ;
+                    log:outputString "\nPuzzle\n" ;
+                    log:outputString ?puzzleText ;
+                    log:outputString "\n" .
+         :02-reason log:outputString "=== Reason Why ===\n" ;
+                    log:outputString ?reasonText ;
+                    log:outputString "\n\n" .
+       } .
+
+# -----------
+# Check block
+# -----------
+
+{ :case :status "ok" .
+  :case :givensPreserved ?c1 ;
+        :noBlanks ?c2 ;
+        :rowsComplete ?c3 ;
+        :colsComplete ?c4 ;
+        :boxesComplete ?c5 ;
+        :replayLegal ?c6 ;
+        :storyConsistent ?c7 .
+  ( "C1 %s - every given clue is preserved in the final grid.\n" ?c1 ) string:format ?l1 .
+  ( "C2 %s - the final grid contains only digits 1 through 9, with no blanks left.\n" ?c2 ) string:format ?l2 .
+  ( "C3 %s - each row contains every digit exactly once.\n" ?c3 ) string:format ?l3 .
+  ( "C4 %s - each column contains every digit exactly once.\n" ?c4 ) string:format ?l4 .
+  ( "C5 %s - each 3×3 box contains every digit exactly once.\n" ?c5 ) string:format ?l5 .
+  ( "C6 %s - replaying the recorded placements from the original puzzle remains legal at every step.\n" ?c6 ) string:format ?l6 .
+  ( "C7 %s - the search statistics and the successful proof path are internally consistent.\n" ?c7 ) string:format ?l7 .
+}
+    => {
+         :03-check log:outputString "=== Check ===\n" ;
+                   log:outputString ?l1 ;
+                   log:outputString ?l2 ;
+                   log:outputString ?l3 ;
+                   log:outputString ?l4 ;
+                   log:outputString ?l5 ;
+                   log:outputString ?l6 ;
+                   log:outputString ?l7 .
+       } .
+
+{ :case :status "ok" .
+  :case :unique true .
+}
+    => { :03a-check log:outputString "C8 OK - a second search found no alternative solution, so the solution is unique.\n" . } .
+
+{ :case :status "ok" .
+  :case :unique false .
+}
+    => { :03a-check log:outputString "C8 INFO - a second search found another solution, so the puzzle is not unique.\n" . } .
+
+{ :case :status "illegal-clues" . }
+    => { :03-check log:outputString "=== Check ===\nC1 failed - the given clues already violate Sudoku rules.\n" . } .
+
+{ :case :status "invalid-input" . }
+    => { :03-check log:outputString "=== Check ===\nC1 failed - the supplied text does not normalize to exactly 81 legal Sudoku cells.\n" . } .
+
+{ :case :status "unsatisfiable" . }
+    => { :03-check log:outputString "=== Check ===\nC1 OK - the given clues are internally consistent.\nC2 OK - every explored assignment respected row, column, and box legality.\nC3 failed - exhaustive search found no complete legal grid.\n" . } .