food_chain/ECOLOGY-MODEL.md

# ECOSPHERE v45 — 生態モデル仕様

## 1. 単位と timestep

- time: day
- `dt = 1/24 day`
- distance: m
- animal wet mass: kg
- animal reserve energy: kJ
- producer / zooplankton: kg biomass m^-2

## 2. 表現

- terrestrial/aquatic producer: grid biomass field
- zooplankton: cohort biomass grid
- macro consumers: individual agents
- food web: fixed sparse consumer-resource graph

水深/鉛直層、人為的攪乱、自動移入、自動種分化は実装しない。

## 3. 生産者

水域の最大増殖率:

`muMax(T) = 0.81 * exp(0.0631*T) day^-1`

実増殖率:

`mu = muMax(T) * min(fN,fP) * fLight`

freshwater / marine で Bissinger 式を温度上限として使い、光・N・P で制限する。dissolved oxygen はこの式へ直接掛けない。

陸上 producer は fallback として `rMax=0.03 day^-1`, `K=0.5 kg m^-2` と moisture / light / temperature limitation を使う。

## 4. 摂食

### 個体資源

動物個体どうしの捕食では interaction edge の attack / handling / preference を使い、Rall et al. 2012 の mass-temperature scaling を接続する。

`Fij = aij * Pij * Nj^q / (1 + sum(aik * Pik * hik * Nk^q))`

捕食イベントは `p = 1-exp(-rate*dt)` でサンプリングする。

### 連続 biomass 資源

producer と zooplankton は「1個体の獲物体重」を持たない。したがって field density を Rall の predator:prey body-mass ratio へ代入しない。

v45 は biomass density に対する Holling 型飽和を使い、consumer mass に応じた最大摂取量を上限とする。既定 half-saturation / max-intake 係数は simulator calibration であり `PARAMETER-PROVENANCE.json` に記録する。

植物由来 assimilation = 0.45、動物由来 = 0.85。

## 5. 代謝・死亡・繁殖

basal metabolism は `B0 * M^0.75`。ectotherm は Arrhenius 型温度補正、endotherm は別 normalization。

死亡要因:
- predation
- starvation
- lifespan
- background hazard
- thermal stress

個体は `structuralMassKg` と reserve energy を分離し、juvenile structural growth は余剰 reserve energy から支払う。

繁殖は maturity / seasonal window / interval / energy threshold を満たすと発生し、親は生存する。generic 初期種は同一 role 内で繁殖季節が完全同期しないよう、species ごとに annual phase offset を持つ。

## 6. 移動

Hirt et al. 2017 Supplementary Table 4 の

`v_kmh = a*M^b*(1-exp(-h*M^i))`

を maximum speed に使う。

| mode | a | b | h | i |
|---|---:|---:|---:|---:|
| flying | 142.8 | 0.24 | 2.4 | -0.72 |
| running | 25.5 | 0.26 | 22.0 | -0.60 |
| swimming | 11.2 | 0.36 | 19.5 | -0.56 |

maximum / routine / foraging / escape speed、daily movement budget、free roaming waypoint を分離する。

スポーン地点への復帰制約は持たない。徘徊時は現在位置から自由移動 waypoint を生成し、到達後に次の waypoint へ更新する。岸線では signed-distance 勾配から生息可能側の法線を求め、禁止側への速度成分を除いて接線方向へ連続投影する。producer / zooplankton の仮想目標は到達時に破棄し、local feeding と navigation を分離する。

固定目標への接近では `distance - arrivalRadius` を1 timestepの上限距離とし overshoot を防ぐ。producer / zooplankton 到達後は最大90 m/dayの局所 grazing movement とする。

### social steering

v45 は **位置ベースのみ**。

- separation: 近接しすぎた個体から離れる
- cohesion: 同種近隣の重心へ弱く寄る

neighbor velocity alignment、回転指数、角運動量検出、逆トルクは使わない。これにより旋回速度を別個体へ伝播させる feedback loop を構造的に除去する。

## 7. playback / 描画

生態 timestep とUI再生速度を分離する。

- ×1 target = 1 simulated day / real second
- 実効 day/s はUIへ表示
- 高倍率では描画 snapshot cadence を下げ、計算を優先
- 高速統計では個体/field描画転送を停止

## 8. climate / profile

`terrestrial / freshwater / marine` profile を分離する。通常UIでは aquatic profile を freshwater / marine で切り替える。

## 9. 水域

初期 procedural water の radius に `sqrt(2)` を一度掛ける。union 面積の厳密測定・最適化はしない。

ユーザー編集水域は `setWater()` に渡された形状をそのまま採用する。追加ツール既定半径は170 m。

## 10. provenance / validation

文献由来値と simulator calibration は `PARAMETER-PROVENANCE.json` で区別する。実行検査は `VALIDATION.md` を参照。