Metadata-Version: 2.5
Name: feudal
Version: 0.0.1
Summary: Medieval manor economy, famine, trade and war simulation for research
Author: icecx
License-Expression: Apache-2.0
License-File: LICENSE
Keywords: agent-based model,economics,famine,history,medieval,simulation,war
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Education
Classifier: Intended Audience :: Science/Research
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3 :: Only
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Scientific/Engineering
Classifier: Topic :: Sociology :: History
Classifier: Typing :: Typed
Requires-Python: >=3.11
Requires-Dist: numpy>=1.24
Requires-Dist: pandas>=2.0
Requires-Dist: pyyaml>=6.0
Provides-Extra: dev
Requires-Dist: pytest>=7; extra == 'dev'
Description-Content-Type: text/markdown

# feudal

**English summary.** `feudal` is a deterministic, vectorized simulation of medieval manors: harvests, granaries, famine, grain trade, realms with famine relief, wars with plunder and conquest, and rule-based realm policies ("AI rulers"). Same seed, same result. It ships with an ensemble runner that measures a policy's effect counterfactually: same world, same seed, same realm, only that realm's policy changed. No rendering; outputs are pandas DataFrames.

```bash
pip install feudal
```

```python
from feudal import World, Simulation, Famine
from feudal.metrics import collapse_order

world = World.generate(seed=1, n_manors=12)
df = Simulation(world, seed=1, events=[Famine(year=5, severity=0.6)]).run(years=20)
print(collapse_order(df))   # which manors collapse first, and when
```

Parameter values are rough orders of magnitude tuned for stable dynamics, **not historical calibration**. Treat results as properties of the model, not claims about the Middle Ages. The rest of this document is in Korean. Status: alpha (0.0.x); the API may change.

---

중세 영지(Manor) 단위의 인구·식량·교역 동역학을 돌리는 순수 로직 시뮬레이션 라이브러리. 렌더링은 없고, 재현성과 분석 편의성을 우선한다.

핵심 질문: **"기근이 나면 어느 영지부터 무너지는가?"**

> 파라미터 기본값은 동역학이 안정적으로 재현되도록 맞춘 대략적인 규모이고, 역사 고증이 아니다. 결과는 "이 모델의 성질"로 읽어야 하며 중세에 대한 주장이 아니다.

## 설치

```bash
pip install feudal
```

Python 3.11 이상(3.11·3.12·3.13에서 테스트), 의존성은 `numpy>=1.24`, `pandas>=2.0`, `pyyaml>=6.0`.

개발용 설치 (소스에서):

```bash
python -m venv .venv
# Windows: .venv\Scripts\activate   /   macOS·Linux: source .venv/bin/activate
pip install -e ".[dev]"
pytest
```

## 빠른 시작

```python
from feudal import World, Simulation, Famine
from feudal.metrics import collapse_order

world = World.generate(seed=1, n_manors=12)
sim = Simulation(world, seed=1, events=[Famine(year=5, severity=0.6)])
df = sim.run(years=20)
print(collapse_order(df))
```

### 반사실 실험: 교역이 기근을 완화하는가

```python
from feudal.metrics import total_losses

events = [Famine(year=5, severity=0.7, affected=[0, 1, 2, 3, 4, 5])]  # 절반의 영지만 흉작
isolated = Simulation(world, seed=1, events=events, trade=False).run(years=12)
traded   = Simulation(world, seed=1, events=events, trade=True).run(years=12)

print(total_losses(isolated).loc["total"], total_losses(traded).loc["total"])
print(collapse_order(isolated), collapse_order(traded), sep="\n")
```

같은 `seed`라면 이벤트나 교역 플래그만 바꿔도 날씨 난수열은 그대로다. 따라서 두 실행은 개입한 지점 외에는 동일한 세계를 공유한다.

### 국가와 전쟁

`World.generate`는 영지를 국가(`Realm`) 몇 개로 나눈다. 기본값은 `realm.n_realms: 3`이고, `n_realms=` 인자로 바꿀 수 있다. 무작위로 뽑은 수도에서 교역 그래프 최단거리로 영토를 넓히므로, 각 국가는 그래프상 연결된 덩어리가 된다.

```python
from feudal import War
from feudal.metrics import realm_losses

events = [
    Famine(year=5, severity=0.6),
    War(year=5, attacker=0, defender=2, duration=None),  # 5년차(0부터 셈)에 선전포고, 승패가 날 때까지
]
sim = Simulation(world, seed=1, events=events)
df = sim.run(years=20)
print(realm_losses(df))          # 국가별 기아 사망·이주·전쟁 사망
rd = sim.realm_dataframe()       # 국가 단위 틱별 지표 (창고, 교전 강도, 세곡, 구휼, 군량, 약탈, 배상)
print(sim.wars_dataframe())      # 전쟁별 기록: 시작·종전 연도, 결과, 배상, 양측 약탈량

Simulation(world, seed=1, events=events, relief=False)   # 국가 구휼 끄기
```

### 국가 정책 (AI 인터페이스)

국가마다 정책을 붙이면, 정책이 매년 초(지난해 전쟁 판정 직후, 이벤트 직전) 관측을 보고 행동을 고른다.

```python
from dataclasses import dataclass
from feudal import DeclareWar, MakePeace, SetTaxRate, SetRelief, Passive, Scripted

@dataclass
class Hungry:
    """예시: 창고가 12주치를 넘으면 가장 약해 보이는 이웃을 친다."""
    name: str = "hungry"

    def decide(self, obs, rng):
        if obs.at_war_with or obs.granary_weeks < 12:
            return []
        targets = [n for n in obs.neighbors if not n.truce]
        if not targets:
            return []
        weakest = min(targets, key=lambda n: n.population)
        return [DeclareWar(weakest.realm_id, reason=f"granary {obs.granary_weeks:.0f}w")]

sim = Simulation(world, seed=1, policies={0: Hungry(), 1: Passive(), 2: Scripted({3: [SetTaxRate(0.3)]})})
sim.run(years=20)
sim.decisions_dataframe()   # 연도, 국가, 정책, 행동, 대상, 값, 수락 여부, 거부 사유, 정책이 밝힌 이유
```

- **관측 (`RealmObservation`):** 자기 나라의 인구, 창고, 영지 재고 합, 주간 필요량, 세율, 구휼 여부를 본다. 지난해 기록(식량 충족률, 기아 사망, 전쟁 사망, 군량 충족률), 교전 상대, 끝난 전쟁 이력(`past_wars`: 상대, 공격 여부, 기간, 승·패·무)도 포함된다. 이웃(교역 간선으로 맞닿은 나라)에 대해서는 인구·창고 추정치, 교전 여부, 휴전 여부, 접경 영지 수를 본다. 이웃 추정치에는 `policy.observation_noise`만큼의 상대 오차가 섞인다.
- **행동:**
  - `DeclareWar(target, intensity)`: 승패가 날 때까지 계속되는 전쟁을 선포한다.
  - `MakePeace(target)`: 강화를 청한다. 전쟁이 즉시 끝나고, 청한 쪽이 창고의 `war.peace_tribute_share`를 상대에게 공물로 넘긴다. 결정 없이 빠져나오는 길을 막기 위한 대가다.
  - `SetTaxRate(rate)`: 소속 영지 전체의 세율을 바꾼다. `min_tax_rate`~`max_tax_rate`로 제한된다.
  - `SetRelief(enabled)`: 이 나라의 구휼을 켜거나 끈다.
  - 행동마다 `reason=`으로 이유를 남길 수 있다.
- **거부되는 행동:** 자기 자신·없는 나라에 대한 선전포고, 이미 교전 중인 상대에 대한 선전포고, 휴전 중(`war.truce_years`) 선전포고, 교전하지 않는 상대와의 강화. 거부된 행동도 결정 로그에 사유와 함께 남는다. 휴전은 정책에만 적용되고, 스크립트 `War` 이벤트에는 적용되지 않는다.
- **동시 결정:** 모든 나라의 관측을 먼저 만든 뒤 국가 순서대로 행동을 적용한다. 같은 해에는 누구도 다른 나라의 그해 결정을 보지 못한다.
- **재현성:** 각 나라의 정책은 날씨와 분리된 자기 전용 난수 스트림(`rng`)을 받는다. 따라서 정책을 바꾸거나 추가해도 날씨와 다른 나라의 난수는 그대로다. `Passive`만 붙인 실행은 정책이 없는 실행과 결과가 완전히 같다.
- **정책은 내부 상태를 두지 않는다.** 스냅샷에 담기지 않기 때문이다. 필요한 정보는 관측에서 얻는다.

#### 내장 규칙 기반 정책 (`feudal.policies`)

| 정책 | 전쟁 | 강화 | 세금·구휼 |
|---|---|---|---|
| `Cautious` | 창고가 12주치 이상이고 굶주린 해가 아니며 마지막 전쟁 후 10년이 지났을 때만 싸운다. 대상은 인구 비(내 인구 ÷ 상대 추정 인구)가 1.8배 이상인 이웃 중 가장 약한 쪽이며, 20년 안에 진 상대는 피한다. | 군량 충족률 80% 미만, 창고 2주치 미만, 기아 사망이 인구 1% 초과 중 하나라도 해당하면 강화를 청한다. | 건드리지 않는다. |
| `Aggressive` | 창고가 6주치 이상이면 인구 비 0.9 이상인 이웃 중 창고가 가장 많아 보이는 쪽을 친다. 한 번에 한 전쟁만 한다. | 군량 충족률이 50% 아래로 떨어질 때만 청한다. | 교전 중이면 세율 35%, 평시 22%. 선포가 거부될 수 있으므로 전시 세율은 전쟁 이듬해부터 적용한다. |
| `Steward` | 먼저 싸우지 않는다. | 공격받으면 이듬해 바로 공물을 내고 강화를 산다. | 굶주린 해 다음에는 세율 10%, 평년에는 22%. 구휼은 항상 켠다. |

모든 기준값은 생성자 인자다(예: `Cautious(attack_odds=1.5, rest_years=5)`).

시드 8개 × 30년 평균, 세 나라 모두 같은 정책 (월드 전체 합계):

| 정책 | 전쟁 수 | 기아 사망 | 전쟁 사망 | 최종 인구 |
|---|---|---|---|---|
| `Passive` | 0 | 248 | 0 | 5,003 |
| `Steward` | 0 | 238 | 0 | 5,019 |
| `Cautious` | 3.2 | 149 | 607 | 4,493 |
| `Aggressive` | 11.4 | 148 | 1,728 | 3,238 |

전쟁이 많을수록 기아 사망이 오히려 적은 것은 전쟁으로 인구가 먼저 줄어 남은 사람이 먹을 곡물이 넉넉해지기 때문이다. 정책 하나의 효과를 국가 크기와 분리해서 보려면 아래 앙상블 실험을 쓴다.

### 앙상블 실험

정책 배치(`Lineup`) 여러 개를 시드 여러 개로 돌리고, 국가별 요약을 표 하나로 모은다. 같은 시드에서는 모든 배치가 같은 세계와 같은 날씨를 공유한다.

```python
from feudal import Passive
from feudal.ensemble import run_ensemble, uniform, focal_lineups, focal_effect, summarize, win_rate
from feudal.policies import Aggressive, Cautious, Steward

if __name__ == "__main__":          # n_jobs > 1 을 Windows에서 쓸 때 필요
    lineups = [uniform("all_passive", Passive)]
    lineups += focal_lineups("aggressive", Aggressive, Passive, realm_ids=[0, 1, 2])
    df = run_ensemble(lineups, seeds=range(20), years=30, n_jobs=8)

    own = focal_effect(df, baseline="all_passive")                 # 초점 국가 자신
    others = focal_effect(df, baseline="all_passive", on="others")  # 나머지 국가 합계 (파급 효과)
    print(summarize(own, "lineup", ["population_change", "final_granary"]))
    print(win_rate(own, "population_change"))
```

- `focal_lineups(name, focal, rest, realm_ids)`: 초점 정책을 국가마다 하나씩 돌려 가며 배치하고, 나머지는 `rest`로 채운다.
- `focal_effect`: 같은 시드, 같은 국가에서 "그 나라 정책만 바꾼 실행"과 기준 배치의 차이다. 국가의 크기·위치·운이 상쇄되므로 정책 자체의 효과만 남는다.
- `run_ensemble` 결과의 국가별 요약 컬럼: `initial_population`, `final_population`, `population_change`, `final_granary`, `manors_start`, `manors_end`, `famine_deaths`, `war_deaths`, `emigrants`, `wars_started`, `wars_defended`, `wars_won`, `wars_lost`, `wars_drawn`, `plunder`, `reparations_net`. 단일 실행의 요약은 `realm_summary(sim)`으로 얻는다.
- `n_jobs > 1`이면 프로세스 병렬로 돌리고, 결과는 직렬 실행과 완전히 같다. 이때 정책 팩토리는 클래스나 모듈 수준 함수여야 하고 람다는 쓸 수 없다.

#### 실험 결과

재현 스크립트는 소스 배포본(sdist)의 `experiments/` 폴더에 있고, 실행하면 결과 CSV가 `experiments/results/`에 저장된다. 아래 수치는 모두 시드 20개 × 국가 3곳 × 30년이고, "같은 나라가 배경 정책을 썼을 때"와의 차이(평균 ± 표준오차)다. 인구 변화에는 정복으로 얻거나 잃은 영지의 인구가 포함된다.

**어떤 정책이 유리한가는 이웃에 달려 있다** (`experiments/policy_backgrounds.py`)

| 배경 | 초점 정책 | 자기 인구 | 자기 창고 | 영지 수 | 이웃 인구 합 | 인구가 늘어난 비율 |
|---|---|---|---|---|---|---|
| 모두 `Passive` | `Aggressive` | −256 ± 77 | +41,069 ± 7,999 | +0.6 | −558 | 20% |
| 모두 `Passive` | `Cautious` | −12 ± 29 | +15,176 ± 4,452 | +0.4 | −169 | 20% |
| 모두 `Passive` | `Steward` | +5 ± 5 | −3,467 ± 1,508 | 0 | −3 | 28% |
| 모두 `Aggressive` | `Steward` | +104 ± 58 | −35,447 ± 7,730 | −0.6 | +361 | 60% |
| 모두 `Aggressive` | `Cautious` | +23 ± 30 | −20,078 ± 5,928 | −0.4 | +201 | 40% |
| 모두 `Aggressive` | `Passive` | −1 ± 36 | −27,050 ± 7,298 | −0.6 | +262 | 40% |

- **평화로운 이웃 사이에서** 공격형은 창고와 영지를 얻는 대신 자기 인구를 잃고, 이웃에게는 그 두 배 넘는 인명 피해를 준다. 신중형은 자기 인구를 거의 잃지 않으면서(−12 ± 29) 창고와 영지를 얻는다. 정복 규칙을 넣기 전에는 신중형도 인구를 잃었다(−115).
- **공격적인 이웃 사이에서** 공물로 평화를 사는 `Steward`가 사람을 가장 많이 지킨다(+104, 60%의 실행에서 인구 증가). 대신 창고와 영지를 내준다. 맞서 싸우는 `Cautious`나 아무것도 하지 않는 `Passive`는 인구 면에서 공격형과 차이가 없다.
- 어느 배경에서든 전쟁을 줄이는 쪽으로 정책을 바꾸면 이웃의 인구가 늘어난다.

**공격성의 최적점** (`experiments/aggression_sweep.py`): 배경은 `Passive`. `Aggressive`가 공격에 필요로 하는 인구 비(`attack_odds`)를 바꿨다.

| `attack_odds` | 자기 인구 | 자기 창고 | 영지 수 | 선전포고 수 | 패전 수 | 이웃 인구 합 |
|---|---|---|---|---|---|---|
| 0.8 | −307 ± 80 | +38,080 | +0.43 | 4.8 | 0.45 | −494 |
| 1.0 | −212 ± 74 | +41,091 | +0.68 | 4.5 | 0.18 | −554 |
| 1.2 | −129 ± 68 | **+43,739** | +0.78 | 4.1 | 0.08 | −526 |
| 1.5 | −53 ± 60 | +41,359 | **+0.85** | 3.6 | 0 | −504 |
| 1.8 | +7 ± 52 | +34,662 | +0.80 | 3.2 | 0 | −410 |
| 2.2 | +40 ± 50 | +25,729 | +0.70 | 2.8 | 0 | −334 |
| 2.5 | +28 ± 49 | +24,093 | +0.65 | 2.5 | 0 | −299 |

- 창고는 1.2, 영지는 1.5에서 가장 많이 얻는다. 1.0 아래로 무모해지면 패전이 늘어 셋 다 손해다.
- 자기 인구는 1.8 이상에서야 손해가 사라지지만(표준오차 안), 그만큼 얻는 창고·영지도 줄어든다. "창고·영지 대 자기 인구"의 트레이드오프가 분명하고, 둘 다 최대인 지점은 없다.
- 이웃의 인명 피해는 공격성이 낮아질수록 꾸준히 줄지만 2.5에서도 −299로 크다.

### 저장과 복원

```python
world.to_json("world.json"); world = World.from_json("world.json")

snap = sim.snapshot()        # JSON 직렬화 가능한 dict (틱, 영지 상태, 난수 상태, 지금까지의 지표)
sim.restore(snap)            # 같은 world·events로 만든 Simulation에 복원
sim.current_world()          # 현재 상태가 반영된 World
```

### 파라미터

모든 수치는 패키지에 포함된 `feudal/data/params.yaml`에 있고(`load_params()`가 이 파일을 읽는다), 각 값의 단위와 근거는 파일 안 주석으로 적혀 있다. 기본값 대신 다른 파일을 쓰거나 일부만 바꿀 수 있다. `Simulation`은 시작할 때 파라미터를 검사하고, 시뮬레이션을 조용히 망가뜨릴 값(비율이 0~1 밖, `max_loss ≥ 1`, `decisive_ratio < 1` 등)이 있으면 `ValueError`를 낸다. 이벤트(`Famine`의 `severity`가 0~1 밖, `War`의 강도가 0 이하)와 정책 행동(NaN 세율, 0 이하 강도의 선전포고)도 같은 식으로 거부된다.

```python
from feudal import load_params, merge_params
params = load_params("my_params.yaml")
params = merge_params(load_params(), {"trade": {"reserve_weeks": 26}})
sim = Simulation(world, params, seed=1)
```

## 모델 요약

| 항목 | 내용 |
|---|---|
| 시간 | 1틱 = 1주, 1년 = 52틱. 0주차 = 봄 시작. 파종 4–8주, 수확 26–33주(가을 초중반). |
| 생산 | 수확 8주 동안 `경작지 × 비옥도 × base_yield × 날씨`를 나눠 들이고, 영주 몫(`lord_tax_rate`)은 제외. |
| 소비 | 매주 `인구 × grain_per_person_week`. 재고는 매주 `spoilage_per_week`만큼 손실. |
| 인구 | 식량 충족률 `s = 먹은 양 / 필요량`. `s = 1`이면 연 0.5% 증가, `s < 1`이면 부족분 `(1−s)`에 비례해 사망과 이주가 발생한다. 이주자는 시뮬레이션 밖으로 나간다. |
| 교역 | 교역 그래프의 간선을 따라 매주 1홉씩 이동한다. **수출**은 재고가 `다음 수확까지 필요량 + reserve_weeks`를 넘는 부분만, **수입**은 `다음 수확까지 필요량 + buffer_weeks`에 모자란 만큼만 이뤄진다. 가격차가 운송비(`cost_per_km × 거리`)를 넘을 때만 교역하고, 간선 용량과 거리 비례 운송 손실을 적용한다. |
| 가격 | `base × (재고/안전재고)^(−elasticity)`, `[min, max]`로 제한. 재고가 많을수록 싸다. |
| 날씨 | 해마다 지역 공통 계수(평균 1.0)에 영지별 편차를 더한다. `Famine`은 지정한 해의 계수를 `1 − severity`로 강제한다(연도는 0부터 센다). |
| 국가 | 영주 세곡의 `granary_share`만큼이 국가 창고로 들어간다. 재고가 `trigger_weeks`치 필요량 아래로 떨어진 소속 영지에는 `target_weeks`치까지 구휼한다. 한 주에 풀 수 있는 양은 창고의 `max_release_per_week` 비율까지이고, 수도에서의 거리에 비례해 운송 손실이 난다. |
| 국경 | 서로 다른 국가 영지를 잇는 교역 간선에는 `border_tariff`가 운송비에 더해진다. |
| 전쟁 | `War(year, attacker, defender, duration, intensity)`는 `year`년 초에 선전포고한다. 전쟁 중에는 다음이 적용된다. (1) 두 나라 사이 교역 간선이 끊긴다. (2) 두 나라가 인구 비례 군량을 낸다. 국가 창고에서 먼저 내고, 모자라면 영지 재고를 비율대로 징발한다. (3) 접경 영지(적국과 교역 간선으로 이어진 영지)는 수확기마다 새 수확의 `raid_harvest_loss`를 약탈당하고, 그중 `plunder_share`가 적국 창고로 간다. (4) 접경 영지에 매주 `frontline_mortality`의 전쟁 사망이 난다. |
| 종전 | 매년 초 지난해 전력(`인구 × 군량 충족률`)을 비교한다. 한쪽이 `decisive_ratio`배 이상이면 승리로 끝나고, 패전국은 창고의 `reparation_share`를 배상한다. 양쪽 전력이 모두 0이면 승부가 나지 않는다. 판정이 나지 않은 채 `duration`이 지나거나 `stalemate_years`가 지나면 배상 없는 백지 강화로 끝난다. 선포한 해에는 판정하지 않는다. 동시에 여러 전쟁을 하는 나라는 전쟁마다 군량을 따로 낸다. |
| 정복 | 판정승한 나라는 패전국의 접경 영지 중 자기 영토와 교역 간선이 가장 많이 닿은 곳부터 `annex_manors`개를 병합한다. 수도는 병합할 수 없고 패전국은 영지를 최소 하나 남기므로, 나라가 소멸하지는 않는다. 병합된 영지는 인구와 재고를 그대로 갖고 승전국 세율을 따른다. 국경 관세, 수도까지 거리, 지표의 `realm_id`가 그 시점부터 바뀐다. 강화(공물)나 백지 강화로 끝난 전쟁에서는 병합하지 않는다. |

틱 안의 순서: (연초: 지난해 전쟁 판정·정복 → 정책 → 이벤트) → 생산(수확기, 세곡 → 국가 창고, 접경 약탈) → 군량 → 구휼 → 교역 → 소비·인구 → 전쟁 사망 → 창고 부패 → 지표 기록.

이벤트는 연초마다 `YearContext`를 받는다. 그해의 날씨(`weather`)를 바꾸고, `ctx.declare_war(...)`로 전쟁을 선포할 수 있다. 진행 중인 전쟁은 해를 넘겨 이어지고, 판정이나 기한으로만 끝난다. 우선순위는 `WeatherShock` → `Famine` → `War` 순이다. 새로운 이벤트도 `priority`와 `on_year_start(ctx)`만 구현하면 넣을 수 있다.

## 지표 해석

`sim.run()`은 틱 × 영지 단위의 long-format DataFrame을 반환한다.

| 컬럼 | 의미 |
|---|---|
| `tick`, `year`, `week` | 시간 (year·week는 0부터) |
| `manor_id` | 영지 id |
| `population` | 틱 종료 시 인구 |
| `grain_stock` | 틱 종료 시 곡물 재고 (kg) |
| `price` | 현지 곡물 가격. 1.0이면 재고가 안전재고와 같은 수준. 높을수록 부족 |
| `food_ratio` | 이번 주 식량 충족률 (1 = 충분, 0 = 완전 기아) |
| `deaths`, `emigrants` | 이번 주 기아로 인한 사망과 이주 |
| `imports`, `exports` | 이번 주 교역 수입(운송 손실 차감 후)과 수출 |
| `realm_id` | 소속 국가 |
| `relief` | 이번 주 국가 창고에서 받은 구휼 곡물 |
| `requisitioned` | 이번 주 군량으로 징발된 곡물 |
| `raided` | 이번 주 약탈당한 수확 (접경 영지, 수확기만) |
| `war_deaths` | 이번 주 전쟁 사망 (접경 영지만) |

`sim.realm_dataframe()`은 틱 × 국가 단위 지표다. 컬럼: `population`, `granary`(창고 재고), `war_intensity`(0이면 평화), `tax_collected`, `relief_released`, `upkeep_from_granary`, `plunder`(약탈로 받은 곡물), `reparations`(받으면 +, 내면 −).

보조 함수 (`feudal.metrics`):

- `collapse_order(df, threshold=0.5)`: 인구가 첫 틱 대비 `threshold` 아래로 처음 떨어진 시점을 영지별로 구한다. 이른 순으로 정렬하며, 붕괴하지 않은 영지는 결과에 없다. "어느 영지부터 무너지는가"에 대한 직접적인 답이다.
- `gini(df, col="population")`: 틱별로 영지 간 `col`의 지니 계수를 구한다. 기근 뒤 이 값이 오르면 피해가 특정 영지에 몰렸다는 뜻이다.
- `total_losses(df)`: 영지별 누적 사망·이주·전쟁 사망과 합계 행.
- `realm_losses(df)`: 같은 값을 국가별로 합산한다.

해석할 때 참고할 점:

- **기근의 시차.** 흉작이 든 해에는 비축분으로 버티기 때문에 사망은 대개 **이듬해 봄~여름**(다음 수확 직전)에 몰린다. 기근 연도 바로 다음 해 붕괴가 많은 것은 이 때문이다.
- **교역의 효과는 기근 범위에 따라 다르다.** 일부 영지만 흉작이면 교역이 사망과 붕괴를 확실히 줄인다(테스트에서 10개 시드 모두 확인). 모든 영지가 동시에 흉작이면 나눌 잉여가 없어 효과가 거의 없다. 교역은 곡물을 재분배할 뿐 새로 만들지는 않는다.
- **`reserve_weeks`는 중요한 파라미터다.** 이 값을 4주처럼 작게 두면 잉여 영지가 해마다 이월 비축분을 내보낸다. 그러면 비옥도가 낮은 영지가 땅이 감당할 수 있는 수준을 넘는 인구를 떠안고, 전체 기근 때는 교역이 오히려 사망을 늘린다.

- **구휼의 효과는 전체 기간으로 판단해야 한다.** 구휼은 평년에도 비옥도 낮은 영지를 먹여 살린다. 그래서 기근 직전 인구가 더 많고, 기근 구간만 보면 사망이 오히려 많을 수 있다. 전체 기간 사망과 최종 인구로 보면 구휼이 있는 쪽이 낫다(테스트에서 10개 시드 모두 확인). 교역도 같은 이유로 구휼과 함께 켜면 기근 구간 사망을 늘릴 수 있다.
- **전쟁과 기근은 서로를 키운다.** 군량이 국가 창고를 먼저 비우기 때문에 기근 때 풀 구휼분이 사라지고, 붕괴 수가 각각일 때의 합을 넘기도 한다. 국경이 맞닿지 않은 두 나라의 전쟁은 접경 피해 없이 군량 부담과 교역 단절만 남긴다.
- **전쟁은 창고를 불릴 수 있지만 인구는 늘 줄어든다.** 시드 8개를 평시와 비교하면 공격국 창고는 6개에서 늘었지만, 인구는 모든 경우 줄었다. 진 쪽 창고가 오히려 늘기도 한다. 인구가 줄면 구휼로 나갈 곡물도 줄기 때문이다. 창고만 보고 전쟁의 득실을 판단하면 안 된다.

## 범위 밖

학습형·LLM 기반 정책, 봉신 위계, 나라의 소멸·분열, 이주민의 다른 영지 정착, 화폐 경제, 이름 생성기, 지도 렌더링, 흑사병 모델.
