Methodology & Position

What this engine computes, how we verify it, what we claim — and what we explicitly do not.

Engine version 0.1.0 · last updated 2026-10-10

1. What we build, in one paragraph

fengshui.engine is a computation engine for the traditional Chinese cosmological system called feng shui （風水，"wind and water"）: a diagnostic framework in which dwellings and sites are described by direction, timing, and symbolic numerology derived from classical Chinese astronomy and calendrics. Our engine implements the computational core of that framework — calendars, solar terms, sexagenary cycles, flying-star charts, mansion assignments — with modern astronomical methods, runs it entirely in your browser, and makes every result reproducible byte-for-byte. We compute the tradition faithfully. We make no claims about the tradition's efficacy.

2. The scientific debate — both sides, stated fairly

Feng shui's factual status is contested, and any serious treatment must show the debate rather than pick a side quietly.

The mainstream scientific position

The scientific consensus is that feng shui's core explanatory concepts — qi （氣） flows, auspicious/inauspicious directions, period-based energy maps — have no verified causal mechanism and no reproducible predictive power under controlled conditions. Studies asserting feng shui effects have generally lacked controls or replication. From this view, feng shui is best understood as a cultural practice whose effects on people are psychological and social (placebo, ritual, order, and aesthetics — real effects, but of practice and belief, not of compass orientations), and claims of predictive or therapeutic power are unsupported.

The practitioner and scholarly position

Practitioners and scholars of Chinese science note that feng shui is a coherent, internally consistent technical tradition with roughly two millennia of textual history — the same astronomical-calendrical machinery that produced China's official calendars. Its orientation rules encode accumulated environmental observation (shelter from wind, solar gain, drainage, "mountain-back/water-front" siting) that has parallels in environmental psychology and vernacular-architecture research. Its value, on this view, is as a living technical heritage and a symbolic language for spatial decisions — and its claims should be understood within its own interpretive framework, not judged solely as lab science.

Where we stand

We take the engineer's position, deliberately narrow:

• We verify the computation, not the cosmology. Given an input, the traditional algorithms produce a determinate output; we make that output correct, reproducible, and inspectable. Whether the framework's claims about dwellings are true is not a question our software answers, and we do not suggest otherwise.
• We do not sell outcomes. The product contains no "your future" claims, no luck-changing services, no health or wealth predictions. Our compliance layer (see §5) structurally blocks that class of statement in every user-facing output the engine produces.
• We label interpretation as interpretation. Where the engine's output feeds human reading, our UI marks the boundary between computed structure (a chart, a cycle, an angle) and interpretive commentary.

3. How the computation works

Astronomy

• Solar position: VSOP87 truncated series with nutation, aberration, and ΔT (observed table with historical extrapolation). Solar terms are solved to a convergence residual of ≈ 0.0001 arcseconds, and the achieved longitude is published in the output rather than assumed.
• New moons: Meeus chapter 49 periodic corrections, anchored to the true (not mean) new moon; anchors themselves are cross-validated — an anchor error we made and fixed is in the errata.
• Calendar assembly: GB/T 33661-2017 leap-month rules over the new-moon chain, verified against the Hong Kong Observatory's published tables for 1901–2100 (2,474 lunar month starts, 73 leap months, 4,800 solar-term dates).

Geomagnetism

Compass declination (the correction between true and magnetic north for the luopan 羅盤) uses the World Magnetic Model WMM2025 with coefficients generated from NOAA's source, validated against NOAA's official test vectors.

Rules with genuine ambiguity

Where the tradition itself disagrees (year-pillar boundary, month-stem escape base, Tigua variants, Eight Mansions derivations, day-boundary conventions), the alternatives are implemented explicitly and the choice is recorded in every output's ruleset_id. The open entries are on the dispute register.

4. Reproducibility: the part competitors do not offer

Every computation embeds a provenance record: an RFC 8785 (JCS) canonical form of the request and a SHA-256 input_digest. Because the engine runs in your browser via WebAssembly, you can recompute any chart locally and check its digest against an independent implementation (our verification page does exactly this — try it). The same engine compiled to Python produces byte-identical output across 400 randomized cases, and a third-party recompute of digests matches 400/400. The full acceptance harness (21 layers) is part of the repository.

5. Compliance architecture

Every user-facing string produced by the engine passes a compliance filter implemented inside the kernel — not as a policy document, but as code on the output path: threatening/fear language, guarantee words ("destined", "100% certain"), paid luck-changing services, medical claims, and investment advice are blocked or downgraded by rule sets per region; disclaimers are injected; an append-only, hash-chained audit log records dispositions; ambiguous cases enter a human review queue. This exists because a calculation tool that quietly morphs into a fortune-telling service is how this product category harms users — and because several jurisdictions regulate exactly these claims.

6. Privacy

Birth data and chart computation run locally in your browser (WebAssembly, zero network requests for computation). Accounts, billing, and saved cases use the server, with the minimum data described at signup. We do not sell data; there is no advertising tracker on this site.

7. Open problems

• Minute-level instant divergences vs. references near midnight thresholds (enumerated, unresolved — see report §7).
• Differential against the sxtwl/Shouxing baseline — planned.
• Low-end device performance measurements — currently extrapolated.
• External anchoring of the audit hash chain — designed, not deployed.

Questions, corrections, or source contributions for the dispute register are welcome — corrections with citations are how entries close.