# Luoshu Square (洛书)

> Describes a palace of the Luoshu magic square (洛书, Lo Shu): its colour name (一白 … 九紫), later-heaven trigram, direction, element, season and family member, together with the full grid, the magic constant 15, the Hetu (河图) partner number and the opposite palace.

- Calculator id: `luoshu-square` · Category: I Ching & Five Elements (`yijing`) · Tool name: `describe_luoshu_square`
- Canonical page: https://tttkmbb.com/yijing/luoshu-square · This document: https://tttkmbb.com/yijing/luoshu-square.md · JSON definition: https://tttkmbb.com/yijing/luoshu-square.json

## Purpose

Describes a palace of the Luoshu magic square (洛书, Lo Shu): its colour name (一白 … 九紫), later-heaven trigram, direction, element, season and family member, together with the full grid, the magic constant 15, the Hetu (河图) partner number and the opposite palace.

**Use when:** You need the meaning of a Luoshu / Flying Star number 1–9, the palace grid, or which trigram and direction a number stands for.

**Do not use when:** You need a personal Kua number (use ming-gua) or the annual/monthly flying stars of a period (use nine-star-feng-shui).

## Input

| Parameter | Type | Unit | Required | Description |
| --- | --- | --- | --- | --- |
| `number` | integer |  | optional, default 5 | Luoshu number 1–9 (5 = centre). (min 1, max 9) |

## Output

| Field | Type | Unit | Description |
| --- | --- | --- | --- |
| `number` | integer |  | The palace number. |
| `color_name` | string |  | Nine-star colour name: 一白 二黑 三碧 四绿 五黄 六白 七赤 八白 九紫. |
| `trigram` | string |  | Later-heaven trigram of the palace (none for the centre). |
| `direction` | string |  | Compass direction of the palace. |
| `element` | string |  | Five-element attribution (1 Water, 2/5/8 Earth, 3/4 Wood, 6/7 Metal, 9 Fire). |
| `season` | string |  | Season of the palace's trigram. |
| `family_member` | string |  | Family role of the palace's trigram. |
| `grid` | string_list |  | The square as three rows in the traditional orientation with south (9) at the top: 4 9 2 / 3 5 7 / 8 1 6. |
| `magic_constant` | integer |  | Sum of every row, column and diagonal. |
| `hetu_pair` | integer |  | Partner number in the River Map pairs 1–6 水, 2–7 火, 3–8 木, 4–9 金, 5–10 土. |
| `hetu_element` | string |  | Element of the Hetu pair. |
| `opposite_palace` | integer |  | Palace across the centre; the two numbers sum to 10 (the centre is its own opposite). |
| `all_palaces` | list |  | One row per number: colour name, trigram, direction, element. |

## Formula

`grid = [4 9 2; 3 5 7; 8 1 6], magic constant = 3·(1+…+9)/9 = 15; opposite = 10 − number (5 → 5); Hetu partner = number ± 5`

Later-heaven mapping 坎1 N, 坤2 SW, 震3 E, 巽4 SE, 5 centre, 乾6 NW, 兑7 W, 艮8 NE, 离9 S; colours from the 紫白 (purple-white) flying-star tradition. Traditional cultural reference calculation; not a prediction and not medical, legal or financial advice.

## Data Sources

- Wikipedia – Lo Shu Square — https://en.wikipedia.org/wiki/Lo_Shu_Square (reference, retrieved 2026-09-24)
- Wikipedia – Bagua — https://en.wikipedia.org/wiki/Bagua (reference, retrieved 2026-09-24)

Data freshness: `static`. Deterministic formula with fixed constants; results never go stale. Inputs supplied by the caller determine the output.

## API

- `GET https://tttkmbb.com/api/v1/calculate/luoshu-square?`
- `POST https://tttkmbb.com/api/v1/calculate/luoshu-square` with JSON body `{"inputs": {…}}`
- Response: unified envelope (`success`, `request`, `result.values`, `result.units`, `sources`, `freshness`, `timestamp`, `next_actions`, `links`); see https://tttkmbb.com/docs/response-format.md
- Schema: https://tttkmbb.com/api/v1/calculators/luoshu-square · OpenAPI operationId `describe_luoshu_square` in https://tttkmbb.com/openapi.json
- Authentication: none. Rate limit: fair use, see https://tttkmbb.com/docs/rate-limits.md.

## MCP

- Server: `https://tttkmbb.com/mcp` (Streamable HTTP, JSON-RPC 2.0, no auth)
- Tool:  `run_calculator` with `{"calculator_id": "luoshu-square", "inputs": {…}}`

## Example

- Palace 1: inputs `{"number":1}` → `{"color_name":"1 一白 (Yi Bai, White)","trigram":"坎 Kan ☵ (Water)","direction":"North (N, 北)","element":"Water (水)","magic_constant":15,"hetu_pair":6,"opposite_palace":9}`
- Palace 5 (centre): inputs `{"number":5}` → `{"color_name":"5 五黄 (Wu Huang, Yellow)","direction":"Centre (中)","element":"Earth (土)","hetu_pair":10,"opposite_palace":5,"grid":["4 9 2","3 5 7","8 1 6"]}`

```
GET https://tttkmbb.com/api/v1/calculate/luoshu-square?number=1
```

## Limitations

You need a personal Kua number (use ming-gua) or the annual/monthly flying stars of a period (use nine-star-feng-shui). Later-heaven mapping 坎1 N, 坤2 SW, 震3 E, 巽4 SE, 5 centre, 乾6 NW, 兑7 W, 艮8 NE, 离9 S; colours from the 紫白 (purple-white) flying-star tradition. Traditional cultural reference calculation; not a prediction and not medical, legal or financial advice. All values are computed from the formula above; no measurement or live data is involved.

## FAQ

**Why is 9 at the top of the grid?**

Chinese diagrams put south at the top; 9 (离, south) is therefore the top-centre cell and 1 (坎, north) the bottom-centre cell. Rotating the grid does not change the sums.

**What is the Hetu partner?**

The River Map (河图) pairs 1–6, 2–7, 3–8, 4–9 and 5–10 as the generating and completing numbers of Water, Fire, Wood, Metal and Earth; 10 is not a Luoshu palace.

## Related

- [Bagua Trigram Lookup (八卦)](https://tttkmbb.com/yijing/bagua.md) — Full attributes of the palace's trigram.
- [Ming Gua Calculator (命卦 / Eight Mansions)](https://tttkmbb.com/yijing/ming-gua.md) — Personal Kua number defined by these palaces.
- [Five Elements Relation (五行生克)](https://tttkmbb.com/yijing/five-elements.md) — Relations between the elements of two palaces.