Abstract
Yingqi is Quizzman I-Ching's Liuyao timing engine. It derives time-branch candidates from the hexagram, the selected use-god and calendar context, then ranks them with their rule evidence. This paper describes algorithm version 1.1.0, ruleset zengshan_core_v1, 18 rule identifiers, hidden-spirit handling, evidence aggregation and the twelve-branch cycle. Six worked vectors, 144 branch-distance pairs and 5,760 ranking cases make the numerical model reproducible. Output scores express rule priority rather than event probabilities.
1 Scope
The implementation is libiching/yingqi/ [1]. Yingqi computes Liuyao timing after the six lines have been established. QP-SYS-002 describes the enclosing I-Ching architecture; QP-SYS-003 covers casting. The timing engine consumes the cast and its derived states.
2 Background references
The ruleset refers to the General Notes on Timing Categories and Flying and Hidden Spirits chapters of Zeng Shan Bu Yi, 《增刪卜易》 [2]. Numerical weights, tie resolution and the data interface are Quizzman software conventions. The classical text supplies traditional rule context; it does not supply these numerical scoring constants.
3 Terms
Timing is a time point or window inferred from hexagram conditions. The use-god is the selected line or six-relative category. A hidden spirit is sought in the palace-head hexagram when the requested relative is absent from the primary hexagram; its covering line is the flying spirit. A trigger is one rule-evidence record targeting a branch. A candidate groups records for a branch and receives a rank.
4 Notation
Branches 1 through 12 are Zi, Chou, Yin, Mao, Chen, Si, Wu, Wei, Shen, You, Xu and Hai. Lines run bottom to top, 1 through 6. Let a be the base branch, b the target, G_b its evidence group, s_i an individual weight, d(a,b) the cyclic offset and S_b the aggregated score.
5 Time conventions
yingqi_predict_from_solar_datetime obtains the day stem, day branch and month branch from the calendar SDK. Invalid solar dates return no candidates; the document exporter marks invalid input unavailable. Direct stem-branch entry checks stems 1..10 and branches 1..12. Calendar, timezone and day-boundary policy belong to the calendar layer that supplies this context.
The horizons are hour, day, month and year; unknown values normalize to day. A nonpositive top-k defaults to 3. An invalid base branch falls back to the day branch. A target matching the base branch means the next occurrence after twelve steps, rather than offset zero.
6 Computational structure
The pipeline selects the use-god, derives line facts, generates triggers, groups them by target branch, ranks branches and exports result_document.timing. Rule evaluation computes conditions and numbers; presentation expresses the resulting structured candidates. A displayed milestone can therefore be traced to its line and contributing rules.
7 Sources and materials
The source manifest records SHA-256 checksums for 15 Yingqi files, algorithm version 1.1.0 and ruleset zengshan_core_v1 [1]. rules.json enumerates the 18 rule identifiers and their priorities. The vectors contain synthetic triggers only. The Python verifier uses the standard library and a fixed seed [3].
8 Use-god and hidden-spirit derivation
For target relative 1..5, selection first prefers a matching moving line. The ascending 1..6 scan overwrites previous moving matches, so the highest matching moving position wins. Without a moving match, the first matching line from the bottom wins. If the relative is absent, the palace-head hexagram supplies a hidden spirit and the corresponding covering branch is retained.
If no line has been selected, a sole moving line uses the supplied primary moving position; other cases use the subject line. Derived facts include branch, element, movement, transformed branch, same-element count, sole moving or static line, and generating or controlling relations affecting hidden and flying spirits. Domain and keyword helpers support relative selection; the core also accepts an explicit target relative.
Hidden-spirit assessment considers seasonal support, day and month conditions, the covering line and moving lines. R_HIDDEN_SPIRIT_VALUE and R_HIDDEN_SPIRIT_CLASH_FLY are emitted only when that assessment finds the hidden spirit usable. This treatment participates in computation and candidate generation.
9 Formal model
The clash branch is:
The strictly future cyclic offset is:
For nonempty G_b and the ruleset's nonnegative weights:
Each additional trigger record for the branch adds three points. The count concerns records, not distinct rule identifiers; duplicate input records can increase the score. Source rule evaluation has a fixed emission order, and candidate evidence preserves the contributing records.
10 Trigger generation and ranking
Rule families cover void filling and clash; month-break filling and combination; tomb opening; release from combination; advance and retreat; assistance to weakness; direct branch value; moving combination and static clash; excessive strength; attack conditioned on overall polarity; sole moving or static lines; and hidden spirits. One rule may emit multiple target branches. Void handling gives the original branch weight 55 and its clash weight 48. Direct value has weight 52, moving combination 47 and static clash 45. The full registry is rules.json.
Within a branch, the primary rule has the largest individual score; equal scores select the lower rule priority. Equal score and priority retain the earlier record. Across branches the ascending key is:
A larger score wins before rule priority, nearer occurrence and lower branch index. Every branch is selected at most once. Twelve branches therefore bound the output at twelve candidates, even when top-k is large.
11 Implementation interface
A candidate carries rank, target_branch, relativeFrom, relativeTo, unit, score, primary_rule and evidence. Evidence records expose ruleId, line and weight. The timing document retains algorithm_version and ruleset. Exported evidence.weight is currently 1; equation (3) uses trigger.score.
Candidate strength uses thresholds 40 and 50; document confidence uses 48 and 54 on the leading score. Thus score 52 has high strength and medium confidence. Both are labels on RULE_SCORE.
Offsets in (2) are positions in the horizon's branch cycle. An hour branch is a phase of the earthly-branch hour cycle; month and year branches likewise need calendar resolution. The ranking module's relative fields alone do not produce a civil timestamp with timezone information.
12 Model validation
Run python3 verify.py in artifacts to regenerate vectors and the verification record [3]. Checks cover all 144 base-target pairs; twelve inputs for clash and harmony involutions; six hand-checked vectors; 5,760 ranking cases against an independent batch grouping and key-sort oracle; and eight label-boundary cases. These are finite-domain mathematical-model checks, rather than native Vir execution results.
13 Results and worked examples
YINGQI-V001 starts at Zi. Direct Zi scores 52 with offset 12, while Wu scores 45 with offset 6. Zi ranks first because score precedes proximity.
YINGQI-V002 starts at Chen. Yin receives weights 55 and 52, producing 58; Shen receives 48 and 45, producing 51. Their order is Yin then Shen, with offsets 10 and 4. YINGQI-V003 holds two scores at 50 and demonstrates rule priority preceding proximity. All checks listed in 12 pass; the JSON vectors retain inputs and expected outputs.
14 Discussion
The structure separates hexagram facts, rule conditions, scores and display language. It exposes why a branch was selected, which evidence converged there and which rule broke a tie. For n triggers and k selected branches, the current repeated-selection implementation costs O(k n²). The bound k≤12 keeps this finite for a single hexagram's rule set.
15 Interpretation limits
The evidence bonus is a ranking policy without event-rate calibration. Validation in 12 covers offsets and ranking; it does not certify every six-relative derivation, hidden-spirit path or calendar conversion. Resolving target branches into civil times requires the caller's calendar context and horizon convention.
16 Conclusion
Yingqi is a distinct timing engine within Quizzman I-Ching, with use-god derivation, hidden spirits, 18 rule identifiers, evidence aggregation, deterministic tie resolution and traceable output. The equations, source checksums and reproducibility materials make the presented calculations directly inspectable.
Bibliography
- [1] Yingqi source manifest and algorithm version.
- [2] Zeng Shan Bu Yi timing and hidden-spirit chapters.
- [3] Synthetic vectors and timing-model verification.
Bibliography (ISO 690 Profile)
- [1] Quizzman Research & Engineering Team. Yingqi 1.1.0 source manifest and SHA-256 checksums. 2026. [URL]
- [2] 野鶴老人. 增刪卜易 — 各門類應期總注章、飛伏神章. [URL] (Public text transcription; chapter reference without a claim to a particular printed edition or page numbering.)
- [3] Quizzman Research & Engineering Team. Yingqi finite-domain mathematical-model verification. 2026. [URL] (Reproduce with verify.py and test-vectors.json in the same artifacts directory.)